CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-websocket

Websocket Client & Server Library implementing the WebSocket protocol as specified in RFC 6455

Pending
Overview
Eval results
Files

router-request.mddocs/

Router Request Handling

Router-specific request handling providing path and protocol-based routing capabilities with simplified request processing within the router context.

Capabilities

WebSocketRouterRequest

Represents a WebSocket request within a router context, providing a simplified interface for route handlers.

/**
 * 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
     * @returns WebSocketConnection instance
     */
    accept(origin?: string, cookies?: Cookie[]): WebSocketConnection;
    
    /**
     * Reject the connection
     * @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 WebSocketRequest */
    readonly webSocketRequest: WebSocketRequest;
    
    /** Resolved protocol for this route */
    readonly protocol: string;
    
    /** Origin header value */
    readonly origin: string;
    
    /** Requested resource path */
    readonly resource: string;
    
    /** Parsed URL object */
    readonly resourceURL: URL;
    
    /** Original HTTP request object */
    readonly httpRequest: http.IncomingMessage;
    
    /** Client IP address */
    readonly remoteAddress: string;
    
    /** Requested WebSocket version */
    readonly webSocketVersion: number;
    
    /** Array of requested extension objects */
    readonly requestedExtensions: object[];
    
    /** Array of parsed cookie objects */
    readonly cookies: Cookie[];
}

Events:

  • 'requestAccepted' - (WebSocketConnection) - Request accepted
  • 'requestRejected' - (WebSocketRouterRequest) - Request rejected

Usage Example:

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

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

const wsServer = new WebSocket.server({
    httpServer: httpServer,
    autoAcceptConnections: false
});

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

// Route chat requests
router.mount('/chat', 'chat-protocol', function(request) {
    console.log('Chat request from:', request.origin);
    console.log('Resource:', request.resource);
    console.log('Protocol:', request.protocol);
    
    // Validate request
    if (!isOriginAllowed(request.origin)) {
        request.reject(403, 'Origin not allowed');
        return;
    }
    
    // Accept connection
    const connection = request.accept(request.origin, [
        { name: 'sessionId', value: 'chat123', httponly: true }
    ]);
    
    console.log('Chat connection established');
    
    // Handle chat messages
    connection.on('message', function(message) {
        if (message.type === 'utf8') {
            console.log('Chat message:', message.utf8Data);
            // Broadcast to other chat clients
            broadcastToChatClients(message.utf8Data);
        }
    });
});

// Route API requests with wildcard
router.mount('/api/*', '*', function(request) {
    console.log('API request:', request.resource);
    console.log('Requested protocols:', request.webSocketRequest.requestedProtocols);
    
    // Accept any protocol for API
    const connection = request.accept();
    
    // Handle API communication
    connection.on('message', function(message) {
        if (message.type === 'utf8') {
            try {
                const apiCall = JSON.parse(message.utf8Data);
                handleApiCall(connection, apiCall);
            } catch (e) {
                connection.close(1003, 'Invalid JSON');
            }
        }
    });
});

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

function isOriginAllowed(origin) {
    // Implement origin validation logic
    return origin === 'http://localhost:3000' || origin === 'https://example.com';
}

function broadcastToChatClients(message) {
    // Implement chat broadcasting logic
    wsServer.connections.forEach(function(connection) {
        if (connection.connected) {
            connection.sendUTF(message);
        }
    });
}

function handleApiCall(connection, apiCall) {
    // Implement API call handling
    const response = {
        id: apiCall.id,
        result: 'API response for: ' + apiCall.method
    };
    connection.sendUTF(JSON.stringify(response));
}

Advanced Router Request Handling

Protocol Resolution:

// The router resolves protocols based on the route definition
router.mount('/specific', 'exact-protocol', function(request) {
    // request.protocol will be 'exact-protocol'
    console.log('Resolved protocol:', request.protocol);
});

router.mount('/any-protocol', '*', function(request) {
    // request.protocol will be the first requested protocol by client
    console.log('Client requested protocols:', request.webSocketRequest.requestedProtocols);
    console.log('Resolved protocol:', request.protocol);
});

Request Information Access:

router.mount('/debug', '*', function(request) {
    console.log('Request details:');
    console.log('  Resource:', request.resource);
    console.log('  Origin:', request.origin);
    console.log('  Remote Address:', request.remoteAddress);
    console.log('  WebSocket Version:', request.webSocketVersion);
    console.log('  Extensions:', request.requestedExtensions);
    console.log('  Cookies:', request.cookies);
    console.log('  Headers:', request.httpRequest.headers);
    
    const connection = request.accept();
    // Handle connection...
});

Error Handling:

router.mount('/secure', 'secure-protocol', function(request) {
    try {
        // Validate authentication
        const authHeader = request.httpRequest.headers.authorization;
        if (!authHeader || !validateToken(authHeader)) {
            request.reject(401, 'Unauthorized');
            return;
        }
        
        // Validate SSL
        if (!request.httpRequest.connection.encrypted) {
            request.reject(400, 'SSL required');
            return;
        }
        
        const connection = request.accept();
        
        connection.on('error', function(error) {
            console.error('Connection error:', error);
        });
        
    } catch (error) {
        console.error('Route handler error:', error);
        request.reject(500, 'Internal server error');
    }
});

Types

Cookie Object

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

Install with Tessl CLI

npx tessl i tessl/npm-websocket

docs

client.md

connection.md

frame.md

index.md

router-request.md

server.md

utilities.md

tile.json