Skip to content

ControlHandler

Publisher Platform Traffic Control & Throttling Microservice

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

📋 Overview

The ControlHandler microservice is a critical traffic management and throttling system for the Publisher platform. It monitors campaign traffic, enforces threshold limits, manages overflow scenarios, and triggers alerts when traffic patterns exceed configured limits. The service maintains real-time control states and provides intelligent traffic routing based on campaign performance and capacity constraints.

Key Features

  • Real-time Traffic Monitoring: Tracks campaign traffic and session counts
  • Threshold Management: Enforces configurable traffic limits per campaign
  • Overflow Handling: Intelligent traffic routing when limits are exceeded
  • Alert Integration: Triggers alerts for threshold violations and anomalies
  • Live Control State: Maintains persistent control state with change tracking
  • Pipeline Processing: Multi-stage validation and processing pipeline
  • Event Hub Integration: Publishes control events and alerts

🛠 Technology Stack

Component Technology
Language JavaScript (Node.js)
Runtime Node.js Container
Framework HTTP Server
Database Azure Cosmos DB
Messaging Azure Event Hub
Processing Async Pipeline Architecture
Build Tool Webpack
Container Docker
Orchestration Kubernetes

🏗 Architecture

Service Architecture

  • Deployment Pattern: Kubernetes Deployment with HTTP Service
  • Input: HTTP POST requests with campaign events
  • Processing: Multi-stage pipeline with control validation
  • Output: Control state updates and alert events
  • State Management: Persistent live control storage in Cosmos DB
  • Configuration: Real-time document cache for control definitions

System Flow

graph TD
    A[Campaign Event] --> B[ControlHandler Service]
    B --> C[Initial Setup & Validation]
    C --> D[Document Cache Lookup]
    D --> E[Experience & Event Type Detection]
    E --> F[Control Matching]
    F --> G[Live Control Retrieval]
    G --> H[Counter Increment]
    H --> I{Threshold Exceeded?}
    I -->|No| J[Update Live Control]
    I -->|Yes| K[Generate Alerts]
    K --> L[Alert Event Hub]
    J --> M[Save Control State]
    M --> N[Success Response]

🔄 Processing Pipeline

The ControlHandler follows a sophisticated 3-stage pipeline architecture:

Stage 0: Initialize

graph LR
    A[S1InitialSetup] --> B[S2GetDocumentCache]
    B --> C[S3GetExperienceType]
    C --> D[S4GetEventType]
    D --> E[S5CheckForMatchingControls]
    E --> F[S6GetLiveControl]
    F --> G[S7GetPreviousDayControl]
    G --> H[S8IncrementCounter]

Stage 2: Alert Processing

graph LR
    A[S1GetAlerts] --> B[Alert Evaluation]
    B --> C[Threshold Checking]

Stage 3: Finalize

graph LR
    A[S1SaveLiveControl] --> B[S2SendAlertsToEventhub]

Control Processing Flow

sequenceDiagram
    participant Event as Campaign Event
    participant Handler as ControlHandler
    participant Cache as Document Cache
    participant DB as Cosmos DB
    participant EventHub as Alert EventHub

    Event->>Handler: Traffic Event
    Handler->>Handler: Extract Campaign Key & Session ID
    Handler->>Cache: Get Control Definitions
    Cache-->>Handler: Control Configurations
    Handler->>Handler: Match Controls by Type & Experience
    Handler->>DB: Get Live Control State
    DB-->>Handler: Current Counters
    Handler->>Handler: Increment Traffic Counter
    Handler->>Handler: Check Thresholds
    alt Threshold Exceeded
        Handler->>EventHub: Send Alert Event
    end
    Handler->>DB: Save Updated Control State
    Handler-->>Event: Processing Result

📡 API Specification

Control Processing Endpoint

  • Method: POST
  • Authentication: Internal service authentication
  • Content-Type: application/json
  • Headers: x-eventhub for event hub routing

Request Format

{
  "data": {
    "campaignkey": "campaign-123",
    "experienceType": "web",
    "eventType": "impression"
  },
  "wizsid": "session-456",
  "timestamp": "2025-01-01T12:00:00.000Z"
}

Response Format

Success Response: 

{
  "processedMsgs": [
    {
      "status": "SUCCESS",
      "response": {
        "controlsProcessed": 3,
        "alertsTriggered": 1
      },
      "errors": []
    }
  ],
  "failedEvents": []
}

Error Response: 

{
  "processedMsgs": [],
  "failedEvents": [
    {
      "status": "FAILED",
      "errors": ["Campaignkey unavailable"],
      "response": {}
    }
  ]
}

🔧 Business Logic

Control Matching Logic

Controls are matched based on multiple criteria: 1. Event Type: Must match the control's subType configuration 2. Experience Type: Must match the control's source configuration
3. Schedule: Control must be active and scheduled time must have passed 4. Active Status: Control must be marked as active

Traffic Counting & Thresholds

  • Real-time Counters: Each control maintains a currValue counter
  • Threshold Enforcement: Alerts triggered when currValue >= threshold
  • Daily Reset: Counters can be reset based on schedule configuration
  • Overflow Handling: Traffic redirected when thresholds exceeded

Live Control Management

// Control state structure
{
  "id": "control-123",
  "partitionKey": "campaign-456", 
  "currValue": 1250,
  "threshold": 1000,
  "active": true,
  "scheduleDateTime": "2025-01-01T00:00:00.000Z",
  "overflowType": "redirect",
  "overflowDestination": "backup-campaign",
  "notes": [
    "1640995200000 Live control threshold changed from 500 to 1000"
  ]
}

Change Tracking

The service tracks configuration changes in live controls: - Threshold Changes: Logs when thresholds are modified - Schedule Updates: Tracks schedule date/time changes - Overflow Configuration: Monitors overflow type and destination changes - Active Status: Records when controls are activated/deactivated

Alert Generation

Alerts are triggered for: - Threshold Violations: When traffic exceeds configured limits - Control Anomalies: Unusual traffic patterns or control behavior - Configuration Changes: When control settings are modified - System Events: Control activation, deactivation, or errors

⚙️ Configuration

Environment Variables

  • Cosmos DB: Connection strings and container settings
  • Event Hub: Alert and control event destinations
  • Pipeline Settings: Processing timeouts and retry configurations
  • Debug Settings: Logging levels and debug output

Key Configuration Files

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

Control Definition Structure

{
  "id": "control-123",
  "subType": ["impression", "click"],
  "source": ["web", "mobile"],
  "threshold": 1000,
  "scheduleDateTime": "2025-01-01T00:00:00.000Z",
  "overflowType": "redirect",
  "overflowDestination": "backup-campaign",
  "active": true
}

🚀 Deployment

Kubernetes Deployment

# Apply Kubernetes manifests
kubectl apply -f k8s/

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

# View logs
kubectl logs -l app=controlhandler -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

  • Control processing rate
  • Threshold violation frequency
  • Alert generation rate
  • Live control update performance
  • Pipeline stage execution times
  • Document cache hit rates

Business Metrics

  • Traffic Volume: Total events processed per campaign
  • Threshold Utilization: Percentage of threshold limits reached
  • Overflow Events: Frequency of traffic overflow scenarios
  • Control Effectiveness: Impact of controls on traffic management
  • Alert Response Time: Time from threshold violation to alert

🔧 Troubleshooting

Common Issues

Controls Not Matching

  1. Check event type and experience type mapping
  2. Verify control schedule and active status
  3. Validate document cache configuration
  4. Review control matching criteria

Threshold Not Enforcing

# Check live control state in Cosmos DB
# Verify threshold configuration in document cache
# Monitor counter increment logic

Alert Generation Failures

  1. Verify Event Hub connectivity for alerts
  2. Check alert generation logic and thresholds
  3. Monitor Event Hub publishing success rates
  4. Validate alert payload structure

Performance Issues

  • Slow Processing: Monitor pipeline stage execution times
  • High Memory: Check live control cache size and cleanup
  • Database Latency: Monitor Cosmos DB response times

🧪 Testing

Unit Tests

npm test

Pipeline Testing

# Test individual pipeline stages
node test/testPipeline.js

Manual Testing

# Test control processing
curl -X POST -H "Content-Type: application/json" \
  -H "x-eventhub: test" \
  -d '{"data":{"campaignkey":"test123"},"wizsid":"session456"}' \
  "http://localhost:8080"

🤝 Dependencies

Internal Dependencies

  • Document Cache Service: Control configuration management
  • Cosmos DB: Live control state persistence
  • Event Hub: Alert and control event publishing
  • Shared Pipeline: Processing pipeline framework

External Dependencies

  • Azure Cosmos DB: Control state storage
  • Azure Event Hub: Alert and event publishing

NPM Dependencies

  • @azure/cosmos: Cosmos DB integration
  • async: Asynchronous processing utilities
  • debug: Debug logging framework
  • moment: Date/time manipulation

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