@iota-big3/sdk-gateway

Universal API Gateway with protocol translation, intelligent routing, and enterprise-grade production features.

Status

• TypeScript Health: ✅ HEALTHY (0 errors) - Phase 2.5 Complete
• Build Status: ✅ Passing
• Core Competency Grade: A- (90%)
• Next Phase: Ready for Phase 2f (lint) or Phase 3 (production audit)

Features

Core Gateway Features

• 🌐 Multi-Protocol Support: HTTP, gRPC, WebSocket, GraphQL
• 🔄 Protocol Translation: Automatic conversion between protocols
• 🧠 Intelligent Routing: Load balancing with multiple strategies
• 🛡️ Circuit Breakers: Prevent cascade failures with automatic recovery
• 📊 SLA Monitoring: Track and enforce service level agreements
• 💰 Cost Tracking: Real-time billing and usage limits
• 🔍 Service Discovery: Static, Kubernetes, Consul, etcd integration
• 🎯 Rate Limiting: Protect services from overload
• 💚 Health Checking: Active monitoring with custom checks
• 📦 Response Caching: Improve performance with intelligent caching
• 🚀 Zero Configuration: Smart defaults with decorator support

🆕 Phase 2k Production Readiness Features

• 🔥 Chaos Engineering: Controlled failure injection for resilience testing
• 📈 Performance Monitoring: Real-time metrics with anomaly detection
• 🧪 Production Smoke Tests: Automated deployment validation
• 🔍 Distributed Tracing Ready: OpenTelemetry integration points
• 🚨 Anomaly Detection: Automatic detection of performance degradation
• 📊 Advanced Metrics: P50/P95/P99 latency tracking, error rates, throughput

Installation

npm install @iota-big3/sdk-gateway

Quick Start

Basic Gateway Setup

import { createGateway } from "@iota-big3/sdk-gateway";

// Create gateway with default configuration
const gateway = createGateway({
  name: "My API Gateway",
  port: 8080,
  enableMetrics: true,
  enableSLA: true,
  enableCostTracking: true,

  // Rate limiting configuration
  rateLimit: {
    windowMs: 60000, // 1 minute
    max: 100, // 100 requests per window
  },

  // Health checking configuration
  healthCheck: {
    interval: 30000, // Check every 30 seconds
    timeout: 5000,
    retries: 3,
  },

  // Caching configuration
  caching: {
    enabled: true,
    ttl: 300, // 5 minutes
    maxSize: 1000,
    strategy: "lru",
  },
});

// Register a service
await gateway.registerService({
  id: "user-service-1",
  name: "user-service",
  host: "localhost",
  port: 3001,
  protocol: "http",
  healthCheck: "/health",
});

// Configure routing
gateway.registerRoute({
  id: "users",
  path: "/api/users/*",
  service: "user-service",
  circuitBreaker: {
    failureThreshold: 10,
    recoveryTimeout: 60000,
  },
});

// Start the gateway
await gateway.start();
console.log("Gateway is running on port 8080");

Production-Ready Setup with Chaos Engineering

import {
  createGateway,
  ChaosMiddleware,
  PerformanceMonitor,
  type ChaosOptions,
} from "@iota-big3/sdk-gateway";

// Configure chaos engineering for resilience testing
const chaosOptions: ChaosOptions = {
  enabled: process.env.NODE_ENV === "staging", // Only in staging
  failures: {
    networkLatency: {
      probability: 0.1, // 10% of requests
      minMs: 100,
      maxMs: 500,
    },
    serviceFailure: {
      probability: 0.05, // 5% of requests
      statusCodes: [500, 503, 429],
    },
    timeouts: {
      probability: 0.02, // 2% of requests
      duration: 5000,
    },
  },
};

// Create chaos middleware
const chaos = new ChaosMiddleware(chaosOptions);

// Create performance monitor
const monitor = new PerformanceMonitor({
  latency: { p50: 50, p95: 150, p99: 300 },
  errorRate: 0.01, // 1% threshold
  throughput: { min: 100, max: 10000 },
});

// Monitor anomalies
monitor.on("anomaly:critical", (anomaly) => {
  console.error("Performance anomaly detected:", anomaly);
  // Trigger alerts, auto-scaling, etc.
});

// Create production gateway
const gateway = createGateway({
  name: "Production Gateway",
  port: 8080,
  // ... other config
});

// Integrate chaos and monitoring
gateway.use(chaos);
gateway.use(monitor);

await gateway.start();

Production Features

Chaos Engineering

Test your system's resilience by injecting controlled failures:

const chaos = new ChaosMiddleware({
  enabled: true,
  failures: {
    // Network issues
    networkLatency: {
      probability: 0.1, // 10% of requests
      minMs: 100, // Minimum delay
      maxMs: 500, // Maximum delay
    },

    // Service failures
    serviceFailure: {
      probability: 0.05,
      statusCodes: [500, 503, 429],
    },

    // Resource exhaustion
    resourceExhaustion: {
      probability: 0.01,
      type: "cpu", // or 'memory', 'connections'
    },

    // Response corruption
    malformedResponse: {
      probability: 0.03,
      types: ["truncated", "invalid-json", "empty", "huge"],
    },
  },
});

// Monitor chaos events
chaos.on("chaos:injected", (event) => {
  console.log(`Chaos injected: ${event.type} for request ${event.request}`);
});

Performance Monitoring

Real-time performance metrics with anomaly detection:

const monitor = new PerformanceMonitor({
  latency: {
    p50: 50, // 50ms median
    p95: 150, // 150ms for 95th percentile
    p99: 300, // 300ms for 99th percentile
  },
  errorRate: 0.01, // 1% error rate threshold
  throughput: {
    min: 100, // Minimum 100 req/sec
    max: 10000, // Maximum 10k req/sec
  },
  memory: {
    max: 512, // 512MB max memory
    growthRate: 10, // 10MB/hour growth allowed
  },
});

// Get real-time metrics
const metrics = monitor.getMetrics();
console.log({
  requestRate: metrics.requests.rate,
  p95Latency: metrics.latency.p95,
  errorRate: metrics.errors.rate,
  memoryUsage: metrics.resources.memory.heapUsed,
});

// Detect anomalies
const anomalies = monitor.detectAnomalies();
anomalies.forEach((anomaly) => {
  if (anomaly.severity === "critical") {
    // Trigger immediate action
  }
});

Production Smoke Tests

Validate deployments with automated smoke tests:

import { runSmokeTests, generateReport } from "@iota-big3/sdk-gateway";

async function validateDeployment() {
  const results = await runSmokeTests("https://api.production.com", {
    parallel: true,
    stopOnFailure: true,
  });

  const report = generateReport(results);

  console.log(`Pass Rate: ${report.summary.passRate}%`);
  console.log(`Duration: ${report.summary.duration}ms`);

  if (report.summary.passRate < 100) {
    console.error("Failed tests:", report.failures);
    // Trigger rollback
    throw new Error("Smoke tests failed");
  }
}

// Built-in smoke tests include:
// - Health check validation
// - Service discovery verification
// - Request routing tests
// - Rate limiting checks
// - Circuit breaker validation
// - Cache functionality
// - Authentication tests
// - Metrics endpoint validation

API Reference

Gateway Configuration

interface GatewayConfig {
  name?: string;
  version?: string;
  port?: number;
  host?: string;
  routes: RouteConfig[];

  // Features
  rateLimit?: RateLimiterConfig;
  healthCheck?: HealthCheckConfig;
  caching?: CacheConfig;

  // Integrations
  database?: DatabaseAdapter;
  logger?: Logger;
  authManager?: AuthManager;
  eventBus?: EventBus;
}

Core Methods

• gateway.start() - Start the gateway server
• gateway.stop() - Stop the gateway gracefully
• gateway.registerService(service) - Register a backend service
• gateway.registerRoute(route) - Configure a route
• gateway.getMetrics() - Get performance metrics
• gateway.getHealthStatus() - Get health status

Events

// Request lifecycle
gateway.on("request:start", (request) => {});
gateway.on("request:end", (request, response) => {});

// Circuit breaker
gateway.on("circuit:opened", ({ service, failures }) => {});
gateway.on("circuit:closed", ({ service }) => {});

// Rate limiting
gateway.on("rateLimit:exceeded", ({ key, limit }) => {});

// Health status
gateway.on("health:statusChanged", ({ service, status }) => {});

// Performance
gateway.on("anomaly:detected", (anomaly) => {});

Production Deployment Guide

1. Environment Configuration

# Production settings
NODE_ENV=production
GATEWAY_PORT=8080
CHAOS_ENABLED=false  # Enable only in staging
PERFORMANCE_MONITORING=true
SMOKE_TESTS_ON_DEPLOY=true

2. Health Checks

Ensure your services have health endpoints:

// Service health endpoint example
app.get("/health", (req, res) => {
  res.json({
    status: "healthy",
    version: "1.0.0",
    uptime: process.uptime(),
    memory: process.memoryUsage(),
  });
});

3. Monitoring Integration

// Integrate with your monitoring stack
monitor.on("anomaly:critical", async (anomaly) => {
  // Send to monitoring service
  await prometheus.recordMetric("gateway_anomaly", {
    type: anomaly.type,
    severity: anomaly.severity,
    value: anomaly.value,
  });

  // Alert ops team
  await pagerduty.trigger("gateway-anomaly", anomaly);
});

4. Graceful Shutdown

process.on("SIGTERM", async () => {
  console.log("SIGTERM received, shutting down gracefully");

  // Stop accepting new requests
  gateway.disable();

  // Wait for existing requests to complete
  await gateway.drain();

  // Close connections
  await gateway.stop();

  process.exit(0);
});

Testing

# Run all tests
npm test

# Run chaos engineering tests
npm run test:chaos

# Run performance benchmarks
npm run test:performance

# Run smoke tests
npm run test:smoke

Examples

See the examples directory for more detailed examples:

• Basic Gateway Setup
• Production Configuration
• Chaos Engineering Demo
• Performance Monitoring
• Multi-Protocol Gateway

Contributing

Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.