ConnectionType

Publisher Platform IP Geolocation Microservice

Service Type: Kubernetes Microservice
Technology: Node.js (JavaScript)
Runtime: Node.js Container
Last Updated: 2025-07-01

📋 Overview

The ConnectionType microservice provides IP geolocation services for the Publisher platform. It uses MaxMind GeoIP2 database to determine geographic information, connection type, and ISP details from IP addresses. The service maintains a cached local copy of the GeoIP2 database stored in Azure Blob Storage and provides real-time IP lookup capabilities.

Key Features

MaxMind GeoIP2 Integration: High-accuracy IP geolocation using MaxMind database
Azure Blob Storage: Automatic database updates from Azure Blob Storage
Intelligent Caching: Local database caching with ETag-based updates
Multiple IP Sources: Supports IP from query parameters, headers, and forwarded headers
Real-time Lookups: Fast IP geolocation with cached database
Automatic Updates: Periodic database refresh with configurable intervals

🛠 Technology Stack

Component	Technology
Language	JavaScript (Node.js)
Runtime	Node.js Container
Framework	HTTP Server
Geolocation	MaxMind GeoIP2
Storage	Azure Blob Storage
Caching	Local file system
Build Tool	Webpack
Container	Docker
Orchestration	Kubernetes

🏗 Architecture

Service Architecture

Deployment Pattern: Kubernetes Deployment with HTTP Service
Input: HTTP GET requests with IP addresses
Data Source: MaxMind GeoIP2 database from Azure Blob Storage
Caching Strategy: Local file system with ETag-based updates
Configuration: ConfigMap and environment variables

System Flow

graph TD
    A[IP Lookup Request] --> B[ConnectionType Service]
    B --> C[Extract IP Address]
    C --> D{Database Cache Valid?}
    D -->|No| E[Azure Blob Storage]
    E --> F[Download GeoIP2 Database]
    F --> G[Update Local Cache]
    G --> H[MaxMind Lookup]
    D -->|Yes| H
    H --> I[Geolocation Data]
    I --> J[JSON Response]

🔄 Processing Pipeline

IP Geolocation Flow

graph LR
    A[HTTP Request] --> B[IP Extraction]
    B --> C[Cache Validation]
    C --> D[Database Update]
    D --> E[MaxMind Lookup]
    E --> F[Response Generation]

Database Update Process

sequenceDiagram
    participant Client
    participant Service as ConnectionType
    participant Blob as Azure Blob
    participant MaxMind as GeoIP2 DB

    Client->>Service: IP Lookup Request
    Service->>Service: Check Cache Age
    Service->>Blob: Check ETag
    Blob-->>Service: ETag Response
    alt Database Updated
        Service->>Blob: Download New Database
        Blob-->>Service: GeoIP2 File
        Service->>MaxMind: Load Database
    end
    Service->>MaxMind: IP Lookup
    MaxMind-->>Service: Geolocation Data
    Service-->>Client: JSON Response

📡 API Specification

IP Geolocation Endpoint

Method: GET
Authentication: Internal service authentication
Content-Type: application/json

IP Address Sources (Priority Order)

Query Parameter: ?ip=192.168.1.1
Client IP Header: clientip header
X-Forwarded-For: x-forwarded-for header

Request Examples

# Query parameter
GET /?ip=8.8.8.8

# Header-based (automatic)
GET / 
Headers: clientip: 8.8.8.8

# X-Forwarded-For
GET /
Headers: x-forwarded-for: 8.8.8.8

Response Format

Success Response:

{
  "data": {
    "continent": {
      "code": "NA",
      "geoname_id": 6255149,
      "names": {
        "en": "North America"
      }
    },
    "country": {
      "geoname_id": 6252001,
      "iso_code": "US",
      "names": {
        "en": "United States"
      }
    },
    "location": {
      "accuracy_radius": 1000,
      "latitude": 37.751,
      "longitude": -97.822,
      "time_zone": "America/Chicago"
    },
    "postal": {
      "code": "67301"
    },
    "subdivisions": [
      {
        "geoname_id": 4273857,
        "iso_code": "KS",
        "names": {
          "en": "Kansas"
        }
      }
    ],
    "traits": {
      "autonomous_system_number": 15169,
      "autonomous_system_organization": "Google LLC",
      "connection_type": "Corporate",
      "isp": "Google LLC",
      "organization": "Google LLC"
    }
  }
}

Error Response:

{
  "error": "IP address must be passed in as a path on the url, e.g., /192.168.0.201"
}

🔧 Business Logic

IP Address Validation

Minimum Length: IP must be at least 6 characters
Source Priority: Query parameter > clientip header > x-forwarded-for header
Format Support: IPv4 and IPv6 addresses

Database Management

Update Frequency: Configurable check interval (default: minutes)
ETag Optimization: Only downloads if database has changed
Local Storage: Temporary directory for database files
Fallback Handling: Graceful degradation if database unavailable

Caching Strategy

// Cache validation logic
if (geoIP2db && lastBlobCheck && 
    Date.now() - lastBlobCheck < config.blobCheckFrequencyMin * 60 * 1000) {
    // Use cached database
} else {
    // Update from blob storage
}

Geolocation Data Structure

The service returns comprehensive geolocation information including: - Geographic: Continent, country, subdivisions, city - Coordinates: Latitude, longitude, accuracy radius - Network: ISP, organization, ASN, connection type - Postal: Postal/ZIP codes - Time Zone: Local time zone information

⚙️ Configuration

Environment Variables

Azure Blob Storage: Connection string and container settings
Database Settings: File paths and update intervals
Logging: Log levels and Application Insights settings

Key Configuration Files

config/config.js: Main configuration
config/config.int.js: Integration environment
config/config.prod.js: Production environment

Configuration Structure

{
  "blob": {
    "containerName": "geoip-data",
    "fileName": "GeoLite2-City.mmdb"
  },
  "localGeoIP2Database": "/tmp/GeoLite2-City.mmdb",
  "localGeoIP2DatabaseFolder": "/tmp",
  "blobCheckFrequencyMin": 60
}

🚀 Deployment

Kubernetes Deployment

# Apply Kubernetes manifests
kubectl apply -f k8s/

# Check deployment status
kubectl get pods -l app=connectiontype

# View logs
kubectl logs -l app=connectiontype -f

Local Development

# Install dependencies
npm install

# Run tests
npm test

# Start service
npm start

📊 Monitoring & Health Checks

Health Endpoints

Liveness: /live - Basic health check
Readiness: /ready - Service readiness check

Key Metrics to Monitor

IP lookup request rate
Database update frequency
Cache hit/miss ratio
Azure Blob Storage connectivity
MaxMind database load time
Response time per lookup

Performance Metrics

Lookup Speed: Average response time for IP lookups
Cache Efficiency: Percentage of requests served from cache
Database Freshness: Time since last database update
Error Rates: Invalid IP addresses and lookup failures

🔧 Troubleshooting

Common Issues

Database Not Loading

Check Azure Blob Storage connectivity
Verify blob container and file name configuration
Ensure proper permissions for blob access
Check local file system permissions for /tmp directory

Invalid IP Lookups

# Check IP address format
# Verify IP is not private/internal range
# Test with known public IP addresses

Cache Update Failures

Verify Azure Blob Storage connection string
Check ETag handling and blob properties
Monitor blob download errors
Validate local file system space

Performance Issues

Slow Lookups: Check database file size and memory usage
High Memory: Monitor MaxMind database memory consumption
Cache Misses: Verify cache update frequency configuration

🧪 Testing

Unit Tests

npm test

Manual Testing

# Test with public IP
curl "http://localhost:8080?ip=8.8.8.8"

# Test with invalid IP
curl "http://localhost:8080?ip=invalid"

# Test header-based IP
curl -H "clientip: 1.1.1.1" "http://localhost:8080"

🤝 Dependencies

External Dependencies

MaxMind GeoIP2: Geolocation database and lookup library
Azure Blob Storage: Database file storage and distribution

Internal Dependencies

Shared Node Modules: Logger utilities
Configuration Service: Azure and application settings

NPM Dependencies

maxmind: GeoIP2 database reader
@azure/storage-blob: Azure Blob Storage client

This documentation was created through manual code analysis of the ConnectionType microservice codebase.