@roomkit/gateway

WebSocket Gateway server for the RoomKit framework - handles client connections and routes messages to workers.

Installation

npm install @roomkit/gateway @roomkit/core

Features

• 🌐 WebSocket Server - High-performance WebSocket connections
• 🔄 Message Routing - Route messages between clients and workers
• 📊 Metrics & Monitoring - Built-in Prometheus metrics
• 🔒 Rate Limiting - Protect against abuse with configurable limits
• 💪 Session Management - Persistent sessions with Redis
• 🔌 Horizontal Scaling - Run multiple gateway instances
• ⚡ Production Ready - Battle-tested in production environments

Quick Start

import { createGateway } from '@roomkit/gateway';

const gateway = await createGateway({
  redis: 'redis://localhost:6379',
  ws: { 
    port: 27100,
    maxConnections: 10000 
  },
  admin: { 
    port: 27200 
  },
});

await gateway.listen();
console.log(\`Gateway listening on port \${gateway.wsPort}\`);

Configuration

Redis Configuration

// Option 1: URL string
redis: 'redis://:password@localhost:6379/0'

// Option 2: Object
redis: {
  host: 'localhost',
  port: 6379,
  password: 'your-password',
  db: 0
}

WebSocket Configuration

ws: {
  port: 27100,                    // WebSocket port (default: 27100)
  maxConnections: 10000,          // Max concurrent connections (default: 10000)
  heartbeatInterval: 30000,       // Heartbeat interval in ms (default: 30000)
  heartbeatTimeout: 90000,        // Heartbeat timeout in ms (default: 90000)
  idleConnectionTimeout: 60000,   // Idle timeout after auth in ms (default: 60000)
}

Rate Limiting

rateLimit: {
  connections: 100,  // New connections per second (default: 100)
  messages: 50,      // Messages per connection per second (default: 50)
  burst: 100,        // Message burst limit (default: 100)
  global: 50000,     // Global messages per second (default: 50000)
}

Admin API

admin: {
  port: 27200,       // Admin API port (default: 27200)
  enabled: true      // Enable admin API (default: true)
}

Complete Example

import { createGateway } from '@roomkit/gateway';

const gateway = await createGateway({
  // Optional: Custom gateway ID (auto-generated if not provided)
  id: 'gateway-1',
  
  // Redis configuration (required)
  redis: {
    host: process.env.REDIS_HOST || 'localhost',
    port: parseInt(process.env.REDIS_PORT || '6379'),
    password: process.env.REDIS_PASSWORD,
  },
  
  // WebSocket configuration
  ws: {
    port: 27100,
    maxConnections: 10000,
    heartbeatInterval: 30000,
    heartbeatTimeout: 90000,
  },
  
  // Rate limiting
  rateLimit: {
    connections: 100,
    messages: 50,
    burst: 100,
    global: 50000,
  },
  
  // Admin API
  admin: {
    port: 27200,
    enabled: true,
  },
});

// Start the gateway
await gateway.listen();

// Graceful shutdown
process.on('SIGTERM', async () => {
  await gateway.close();
  process.exit(0);
});

Environment Variables

The gateway supports basic environment variables for infrastructure configuration:

# Redis (infrastructure)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your-password

# Note: Application-level configs (ports, limits, etc.) should be 
# passed via code parameters for better type safety and clarity.

Admin API

The gateway provides an HTTP admin API for monitoring and management:

Health Check

```bash GET http://localhost:27200/health ```

Metrics

```bash GET http://localhost:27200/metrics ```

Connection Stats

```bash GET http://localhost:27200/admin/stats ```

List Connections

```bash GET http://localhost:27200/admin/connections ```

Docker

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 27100 27200
CMD ["node", "gateway.js"]

docker run -p 27100:27100 -p 27200:27200 \
  -e REDIS_HOST=redis \
  -e REDIS_PORT=6379 \
  my-gateway

Production Deployment

Multiple Instances

Run multiple gateway instances behind a load balancer:

# Gateway 1
node gateway.js --id gateway-1 --port 27100

# Gateway 2  
node gateway.js --id gateway-2 --port 27101

# Load balancer (nginx, haproxy, etc.)

Monitoring

• Use the `/metrics` endpoint for Prometheus
• Monitor connection count, message rate, error rate
• Set up alerts for rate limit triggers

Best Practices

1. Set appropriate rate limits based on your game's needs
2. Monitor memory usage - adjust maxConnections if needed
3. Use Redis cluster for high availability
4. Enable connection pooling in your load balancer
5. Set up health checks on `/health` endpoint

License

MIT