npm package: @roomkit/gateway
Description: High-performance WebSocket Gateway server for multiplayer games and real-time applications
Latest version: 1.3.1

# @roomkit/gateway

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

## Installation

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

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

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

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

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

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

## Complete Example

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

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

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

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

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