@iota-big3/sdk-gateway/README.md

Universal API Gateway with protocol translation, intelligent routing, rate limiting, health checking, and caching

# @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

```bash
npm install @iota-big3/sdk-gateway
```

## Quick Start

### Basic Gateway Setup

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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

```typescript
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

```typescript
// 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

```bash
# 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:

```typescript
// 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

```typescript
// 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

```typescript
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

```bash
# 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](./examples) directory for more detailed examples:

- [Basic Gateway Setup](./examples/basic-gateway.ts)
- [Production Configuration](./examples/phase-2k-production-demo.ts)
- [Chaos Engineering Demo](./examples/chaos-demo.ts)
- [Performance Monitoring](./examples/performance-demo.ts)
- [Multi-Protocol Gateway](./examples/multi-protocol.ts)

## Contributing

Please read our [Contributing Guide](../../CONTRIBUTING.md) 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](../../LICENSE) file for details.