http

HTTP Gateway Component

The HTTP Gateway component enables external HTTP/REST clients to query SemStreams via bidirectional NATS request/reply patterns.

Overview

Type: Gateway Protocol: HTTP/REST Pattern: Request/Reply (External ↔ NATS) Read-Only: Yes (default)

The HTTP Gateway bridges external HTTP requests to internal NATS request/reply subjects, enabling REST API access to SemStreams components like GraphProcessor without requiring direct NATS connections.

Component Type: Gateway

SemStreams has 5 component types:

Key Difference from Output:

• Output: Unidirectional push (NATS → External)
• Gateway: Bidirectional request/reply (External ↔ NATS ↔ External)

Architecture

┌──────────────────┐
│  HTTP Client     │  POST /api-gateway/search/semantic
└────────┬─────────┘
         ↓ HTTP Request
┌────────────────────────────────────────┐
│  ServiceManager (Port 8080)            │
│  /api-gateway/* → HTTPGateway handlers │
└────────┬───────────────────────────────┘
         ↓ NATS Request/Reply
┌────────────────────────────────────────┐
│  graph-processor Component             │
│  Subscribed to graph.query.semantic    │
└────────┬───────────────────────────────┘
         ↓ NATS Reply
┌────────────────────────────────────────┐
│  ServiceManager                        │
│  Translate reply → HTTP Response       │
└────────┬───────────────────────────────┘
         ↓ HTTP Response
┌──────────────────┐
│  HTTP Client     │  Receives SearchResults JSON
└──────────────────┘

Configuration

Basic Configuration

{
  "components": {
    "api-gateway": {
      "type": "gateway",
      "name": "http",
      "enabled": true,
      "config": {
        "routes": [
          {
            "path": "/search/semantic",
            "method": "POST",
            "nats_subject": "graph.query.semantic",
            "timeout": "5s",
            "description": "Semantic similarity search"
          }
        ]
      }
    }
  }
}

Full Configuration

{
  "components": {
    "api-gateway": {
      "type": "gateway",
      "name": "http",
      "enabled": true,
      "config": {
        "enable_cors": true,
        "cors_origins": ["http://localhost:3000", "https://app.example.com"],
        "max_request_size": 1048576,
        "routes": [
          {
            "path": "/search/semantic",
            "method": "POST",
            "nats_subject": "graph.query.semantic",
            "timeout": "5s",
            "description": "Semantic similarity search across indexed entities"
          },
          {
            "path": "/entity/:id",
            "method": "GET",
            "nats_subject": "graph.query.entity",
            "timeout": "2s",
            "description": "Retrieve single entity by ID"
          }
        ]
      }
    }
  }
}

Configuration Schema

Gateway Config

Route Mapping

Route Registration

Routes are automatically registered at startup:

Component Instance Name: "api-gateway"
URL Prefix: "/api-gateway/"

Route: "/search/semantic"
Full Path: "/api-gateway/search/semantic"

ServiceManager discovers gateway components via interface:

type Gateway interface {
    component.Discoverable
    RegisterHTTPHandlers(prefix string, mux *http.ServeMux)
}

Mutation Control

HTTP methods (GET, POST, PUT, DELETE) don't directly map to mutation semantics. For example, POST is commonly used for complex queries like semantic search.

Design Principle: Mutation control should be enforced at the NATS subject/component level, not at the HTTP gateway layer. The gateway is protocol translation only.

CORS

CORS is disabled by default and requires explicit configuration for security:

Allow All Origins (Development)

{
  "enable_cors": true,
  "cors_origins": ["*"]
}

Restrict Origins (Production)

{
  "enable_cors": true,
  "cors_origins": [
    "https://app.example.com",
    "https://dashboard.example.com"
  ]
}

CORS Headers

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Max-Age: 3600

Error Handling

HTTP status codes are mapped from SemStreams error types:

Error Response Format:

{
  "error": "entity not found",
  "status": 404
}

Request Size Limits

Prevent DoS attacks with request size limits:

{
  "max_request_size": 1048576  // 1MB (default)
}

Range: 0 to 100MB (104857600 bytes)

Requests exceeding the limit are truncated to max_request_size.

Timeouts

Per-route timeout configuration:

{
  "routes": [
    {
      "path": "/search/semantic",
      "timeout": "5s"   // Quick queries
    },
    {
      "path": "/entity/:id/path",
      "timeout": "30s"  // Complex graph traversal
    }
  ]
}

Range: 100ms to 30s

If NATS doesn't reply within timeout, returns 504 Gateway Timeout.

Metrics

Prometheus metrics exported at :9090/metrics:

Gateway Metrics

# Request totals
gateway_requests_total{component="api-gateway", route="/search/semantic"}

# Failed requests
gateway_requests_failed_total{component="api-gateway", route="/search/semantic"}

# Request latency
gateway_request_duration_seconds{component="api-gateway", route="/search/semantic"}

Component Health

# Gateway health
component_healthy{component="api-gateway", type="gateway"}

# Error count
component_errors_total{component="api-gateway"}

Usage Examples

Semantic Search

curl -X POST http://localhost:8080/api-gateway/search/semantic \
  -H "Content-Type: application/json" \
  -d '{
    "query": "emergency alert system",
    "threshold": 0.3,
    "limit": 10
  }'

Response:

{
  "data": {
    "query": "emergency alert system",
    "threshold": 0.3,
    "hits": [
      {
        "entity_id": "alert-001",
        "score": 0.87,
        "entity_type": "alert",
        "properties": {
          "title": "Emergency Alert Test",
          "content": "Testing the emergency alert system"
        }
      }
    ]
  }
}

Entity Lookup

curl http://localhost:8080/api-gateway/entity/device-123

TypeScript Client

class SemStreamsClient {
  constructor(private baseURL = 'http://localhost:8080/api-gateway') {}

  async semanticSearch(query: string, limit = 10, threshold = 0.3) {
    const res = await fetch(`${this.baseURL}/search/semantic`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ query, limit, threshold })
    });

    if (!res.ok) {
      const error = await res.json();
      throw new Error(error.error);
    }

    return await res.json();
  }
}

const client = new SemStreamsClient();
const results = await client.semanticSearch('drone battery');

OpenAPI Integration

The HTTP gateway uses config-driven dynamic routes that are defined at runtime via YAML/JSON configuration. Because routes vary by deployment, they are not included in the static OpenAPI specification.

For gateways with well-defined endpoints (like graph-gateway), see their OpenAPI contributions in the generated spec.

Access OpenAPI:

• JSON Spec: http://localhost:8080/openapi.json
• Swagger UI: http://localhost:8080/docs

Note: The routes you configure for this gateway won't appear in the OpenAPI spec. Document your deployment-specific routes separately if needed.

Security Considerations

Production Deployment

1. TLS: Deploy behind reverse proxy with TLS

server {
    listen 443 ssl;
    server_name api.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

1. Authentication: Add auth middleware in reverse proxy

location /api-gateway/ {
    auth_request /auth;
    proxy_pass http://localhost:8080;
}

1. Rate Limiting: Prevent abuse

limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

location /api-gateway/ {
    limit_req zone=api burst=20;
    proxy_pass http://localhost:8080;
}

1. CORS: Restrict origins

{
  "cors_origins": ["https://app.example.com"]
}

Troubleshooting

"NATS connection not available" (503)

Cause: NATS server down or unreachable

Fix:

# Check NATS status
docker ps | grep nats

# Restart NATS
task integration:start

"timeout" errors (504)

Cause: Query exceeds route timeout

Fix: Increase timeout:

{
  "routes": [{
    "timeout": "30s"  // Increased from 5s
  }]
}

CORS errors in browser

Cause: Origin not in cors_origins list

Fix:

{
  "cors_origins": ["http://localhost:3000"]
}

Method not allowed (405)

Cause: Wrong HTTP method for route

Fix: Use correct method from route config (GET vs POST)

Related Documentation

• Gateway Package - Gateway interface and types
• EMBEDDING_ARCHITECTURE.md - Semantic search architecture
• configs/HTTP_GATEWAY_USAGE.md - Usage guide with curl examples
• configs/http-gateway-semantic-search.json - Example configuration