Server-Side WebSocket Operations

/**
 * WebSocket server that handles HTTP upgrade requests
 * @param config - Server configuration options
 */
class WebSocketServer extends EventEmitter {
    constructor(config?: ServerConfig);
    
    /** Mount server on HTTP server(s) with configuration */
    mount(config: ServerConfig): void;
    
    /** Unmount from HTTP server(s) */
    unmount(): void;
    
    /** Close all active connections */
    closeAllConnections(): void;
    
    /** Broadcast data to all connected clients */
    broadcast(data: Buffer | string): void;
    
    /** Broadcast UTF-8 text to all connected clients */
    broadcastUTF(utfData: string): void;
    
    /** Broadcast binary data to all connected clients */
    broadcastBytes(binaryData: Buffer): void;
    
    /** Gracefully shut down server */
    shutDown(): void;
    
    /** Array of active WebSocketConnection instances */
    readonly connections: WebSocketConnection[];
    
    /** Array of pending WebSocketRequest instances */
    readonly pendingRequests: WebSocketRequest[];
    
    /** Server configuration object */
    readonly config: ServerConfig;
}

interface ServerConfig {
    /** HTTP server instance(s) to attach to (required) */
    httpServer: http.Server | https.Server | http.Server[];
    
    /** Maximum frame size in bytes (default: 64KiB) */
    maxReceivedFrameSize?: number;
    
    /** Maximum message size in bytes (default: 1MiB) */
    maxReceivedMessageSize?: number;
    
    /** Whether to fragment outgoing messages (default: true) */
    fragmentOutgoingMessages?: boolean;
    
    /** Fragment messages larger than this size (default: 16KiB) */
    fragmentationThreshold?: number;
    
    /** Enable keepalive pings (default: true) */
    keepalive?: boolean;
    
    /** Keepalive ping interval in milliseconds (default: 20000) */
    keepaliveInterval?: number;
    
    /** Drop connection on keepalive timeout (default: true) */
    dropConnectionOnKeepaliveTimeout?: boolean;
    
    /** Grace period before dropping connection in milliseconds (default: 10000) */
    keepaliveGracePeriod?: number;
    
    /** Use TCP keepalive instead of WebSocket pings (default: false) */
    useNativeKeepalive?: boolean;
    
    /** Assemble fragmented messages (default: true) */
    assembleFragments?: boolean;
    
    /** Automatically accept all connections (default: false) */
    autoAcceptConnections?: boolean;
    
    /** Trust X-Forwarded-For header (default: false) */
    ignoreXForwardedFor?: boolean;
    
    /** Parse Cookie headers (default: true) */
    parseCookies?: boolean;
    
    /** Parse Sec-WebSocket-Extensions header (default: true) */
    parseExtensions?: boolean;
    
    /** Disable Nagle algorithm (default: true) */
    disableNagleAlgorithm?: boolean;
    
    /** Close frame timeout in milliseconds (default: 5000) */
    closeTimeout?: number;
}

const WebSocket = require('websocket');
const http = require('http');

// Create HTTP server
const httpServer = http.createServer();
httpServer.listen(8080);

// Create WebSocket server
const wsServer = new WebSocket.server({
    httpServer: httpServer,
    autoAcceptConnections: false,
    maxReceivedFrameSize: 64 * 1024,
    maxReceivedMessageSize: 1024 * 1024,
    keepalive: true,
    keepaliveInterval: 20000
});

// Handle connection requests
wsServer.on('request', function(request) {
    // Validate origin
    if (!originIsAllowed(request.origin)) {
        request.reject(403, 'Origin not allowed');
        return;
    }
    
    const connection = request.accept('echo-protocol', request.origin);
    console.log('Connection accepted from ' + connection.remoteAddress);
});

// Handle new connections
wsServer.on('connect', function(connection) {
    console.log('New connection established');
});

// Broadcast to all clients
wsServer.broadcastUTF('Server message to all clients');

/**
 * Incoming WebSocket handshake request
 * @param socket - TCP socket
 * @param httpRequest - HTTP request object
 * @param serverConfig - Server configuration
 */
class WebSocketRequest extends EventEmitter {
    /** Parse WebSocket handshake headers */
    readHandshake(): void;
    
    /** 
     * Accept the connection request
     * @param acceptedProtocol - Protocol to accept (must be in requestedProtocols)
     * @param allowedOrigin - Origin to include in response
     * @param cookies - Array of cookie objects to set
     * @returns WebSocketConnection instance
     */
    accept(acceptedProtocol?: string, allowedOrigin?: string, cookies?: Cookie[]): WebSocketConnection;
    
    /**
     * Reject the connection request
     * @param status - HTTP status code (default: 403)
     * @param reason - Rejection reason string
     * @param extraHeaders - Additional HTTP headers
     */
    reject(status?: number, reason?: string, extraHeaders?: object): void;
    
    /** Original HTTP request object */
    readonly httpRequest: http.IncomingMessage;
    
    /** TCP socket */
    readonly socket: net.Socket;
    
    /** Requested resource path */
    readonly resource: string;
    
    /** Parsed URL object */
    readonly resourceURL: URL;
    
    /** Sec-WebSocket-Key header value */
    readonly key: string;
    
    /** Requested WebSocket version */
    readonly webSocketVersion: number;
    
    /** Origin header value */
    readonly origin: string;
    
    /** Array of requested protocol strings (lowercase) */
    readonly requestedProtocols: string[];
    
    /** Map of lowercase to original case protocols */
    readonly protocolFullCaseMap: object;
    
    /** Array of requested extension objects */
    readonly requestedExtensions: object[];
    
    /** Array of parsed cookie objects */
    readonly cookies: Cookie[];
    
    /** Host header value */
    readonly host: string;
    
    /** Client IP address */
    readonly remoteAddress: string;
    
    /** Array including X-Forwarded-For addresses */
    readonly remoteAddresses: string[];
}

wsServer.on('request', function(request) {
    console.log('Connection from origin ' + request.origin);
    console.log('Requested protocols: ' + request.requestedProtocols.join(', '));
    console.log('Resource: ' + request.resource);
    
    // Validate the request
    if (!originIsAllowed(request.origin)) {
        request.reject(403, 'Origin not allowed');
        return;
    }
    
    if (request.requestedProtocols.indexOf('echo-protocol') === -1) {
        request.reject(400, 'Unsupported protocol');
        return;
    }
    
    // Accept with specific protocol and cookies
    const connection = request.accept('echo-protocol', request.origin, [
        { name: 'session', value: 'abc123', httponly: true }
    ]);
});

/**
 * Routes WebSocket requests based on path and protocol
 * @param config - Router configuration
 */
class WebSocketRouter extends EventEmitter {
    constructor(config?: RouterConfig);
    
    /** Attach router to WebSocketServer */
    attachServer(server: WebSocketServer): void;
    
    /** Detach from WebSocketServer */
    detachServer(): void;
    
    /**
     * Mount route handler
     * @param path - Path string or RegExp (use '*' for catch-all)
     * @param protocol - Protocol string (use '*' for any protocol)
     * @param callback - Function called with WebSocketRouterRequest
     */
    mount(path: string | RegExp, protocol: string, callback: (request: WebSocketRouterRequest) => void): void;
    
    /**
     * Remove route handler
     * @param path - Path string or RegExp
     * @param protocol - Protocol string
     */
    unmount(path: string | RegExp, protocol: string): void;
    
    /** Array of mounted route handlers */
    readonly handlers: RouteHandler[];
    
    /** Attached WebSocketServer instance */
    readonly server: WebSocketServer;
}

interface RouterConfig {
    /** WebSocketServer instance to attach to */
    server?: WebSocketServer;
}

const router = new WebSocket.router({
    server: wsServer
});

// Route specific paths and protocols
router.mount('/chat', 'chat-protocol', function(request) {
    console.log('Chat request from ' + request.origin);
    const connection = request.accept();
    // Handle chat connection
});

router.mount('/api/*', '*', function(request) {
    console.log('API request to ' + request.resource);
    const connection = request.accept();
    // Handle API connection
});

// Catch-all route
router.mount('*', '*', function(request) {
    console.log('Unhandled request to ' + request.resource);
    request.reject(404, 'Not found');
});

/**
 * WebSocket request within router context
 * @param webSocketRequest - Original WebSocketRequest
 * @param resolvedProtocol - Resolved protocol for this route
 */
class WebSocketRouterRequest extends EventEmitter {
    /**
     * Accept the connection
     * @param origin - Origin to include in response
     * @param cookies - Array of cookie objects to set
     */
    accept(origin?: string, cookies?: Cookie[]): WebSocketConnection;
    
    /**
     * Reject the connection
     * @param status - HTTP status code
     * @param reason - Rejection reason
     * @param extraHeaders - Additional headers
     */
    reject(status?: number, reason?: string, extraHeaders?: object): void;
    
    /** Original WebSocketRequest */
    readonly webSocketRequest: WebSocketRequest;
    
    /** Resolved protocol for this route */
    readonly protocol: string;
    
    // Inherited from WebSocketRequest
    readonly origin: string;
    readonly resource: string;
    readonly resourceURL: URL;
    readonly httpRequest: http.IncomingMessage;
    readonly remoteAddress: string;
    readonly webSocketVersion: number;
    readonly requestedExtensions: object[];
    readonly cookies: Cookie[];
}

interface Cookie {
    name: string;
    value: string;
    path?: string;
    domain?: string;
    expires?: Date;
    maxage?: number;
    secure?: boolean;
    httponly?: boolean;
}

interface RouteHandler {
    path: string | RegExp;
    protocol: string;
    callback: (request: WebSocketRouterRequest) => void;
}