Does OmniRoute Support WebSocket Routing? Full Implementation Breakdown

Yes. OmniRoute includes a full-featured WebSocket routing layer that powers the live-dashboard event stream, the OpenAI-compatible chat WebSocket endpoint, and the Responses-over-WebSocket bridge.

OmniRoute is an open-source routing platform that integrates WebSocket routing directly into its core architecture. The implementation spans authentication handshakes, live event broadcasting, and LLM response streaming across multiple server and client modules. According to the diegosouzapw/OmniRoute source code, the system handles upgrades, path resolution, and multi-turn message proxying through dedicated TypeScript files.

How the WebSocket Handshake Works

In src/app/api/v1/ws/route.ts, the API route processes incoming GET requests for WebSocket negotiation. A standard request triggers an upgrade handshake, and if the client cannot upgrade, the server returns a 426 Upgrade Required response. When the caller includes the handshake=1 query parameter, the route returns JSON containing the connection path, authentication tokens, and protocol details required to establish the persistent socket.

API Route and Upgrade Handling

The entry point for all WebSocket routing traffic is src/app/api/v1/ws/route.ts. This Next.js API route manages CORS headers and determines whether to proceed with the HTTP upgrade or return connection metadata. It serves as the gateway for both the live-dashboard daemon and the chat bridge endpoints.

Authentication and Token Generation

The src/lib/ws/handshake.ts module authorizes every handshake request before any socket is allocated. It validates API-key or credential-based authentication, then populates the wsAuth token and wsPath fields that the client consumes to open the final WebSocket connection. This design keeps authentication logic decoupled from the persistent server daemons.

WebSocket Server Architecture

Live Dashboard Daemon

The actual event broadcasting server runs inside src/server/ws/liveServer.ts. This daemon pushes live-dashboard telemetry to connected clients and enforces network policies through src/server/ws/liveServerAllowList.ts, which maintains an explicit allow-list of permitted client IPs. Together these files provide both real-time streaming and perimeter security for the WebSocket routing layer.

Path Resolution Logic

Before a client connects, src/shared/utils/wsPath.ts derives the public WebSocket pathname—defaulting to /live-ws—from the NEXT_PUBLIC_LIVE_WS_PUBLIC_URL environment variable. This utility centralizes path handling so that both the handshake API and the live server reference a single source of truth for route configuration.

Client Implementation Examples

Connecting to the Live Dashboard

The following client-side JavaScript performs the handshake and then opens an authenticated WebSocket to the live-dashboard daemon:

// Example: Open a WebSocket connection to the live‑dashboard daemon
const ws = new WebSocket('ws://localhost:20132/live-ws?handshake=1');

// First, perform the handshake to obtain auth details
ws.addEventListener('open', async () => {
  const handshakeResp = await fetch(
    `${location.origin}/api/v1/ws?handshake=1`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );
  const { wsAuth, path, protocol } = await handshakeResp.json();

  // Attach auth token as a query param (or header, depending on server config)
  const wsUrl = `ws://localhost:20132${path}?auth=${wsAuth}`;
  const wsConn = new WebSocket(wsUrl);

  // Send a request adhering to the protocol defined in the handshake
  wsConn.addEventListener('open', () => {
    wsConn.send(JSON.stringify({
      type: 'request',
      id: 'req-1',
      payload: { model: 'openai/gpt-4', messages: [] }
    }));
  });

  // Listen for responses
  wsConn.addEventListener('message', ev => {
    const msg = JSON.parse(ev.data);
    console.log('Received:', msg);
  });
});

Using the Responses-over-WebSocket Bridge

For LLM inference streaming, clients can use the Responses-over-WebSocket bridge. The example below uses the ws library to send JSON-RPC-like requests and receive streamed tokens:

// Example: Use the Responses‑over‑WebSocket bridge (client side)
import { WebSocket } from 'ws';

async function startResponsesWs() {
  const respWs = new WebSocket('ws://localhost:20132/api/v1/responses?api_key=local-token');

  respWs.on('open', () => {
    // Send a `response.create` request (JSON‑RPC‑like)
    respWs.send(JSON.stringify({
      method: 'response.create',
      id: 'r1',
      params: { model: 'openai/gpt-4', messages: [{ role: 'user', content: 'Hello' }] }
    }));
  });

  respWs.on('message', data => {
    const msg = JSON.parse(data.toString());
    console.log('Response:', msg);
  });
}

Testing and Validation

OmniRoute validates its WebSocket routing layer through dedicated unit tests. The file tests/unit/v1-ws-bridge.test.ts confirms that the /api/v1/ws endpoint performs proper upgrade handling and handshake authentication. Additional suites such as tests/unit/responses-ws-proxy-*.test.ts verify multi-turn history logging and compression parity for the Responses-over-WebSocket proxy.

OpenAPI Documentation

Client generators and API explorers can reference docs/openapi.yaml in the repository. This specification formally documents the /api/v1/ws endpoint, including its handshake parameters and expected response schema, making it straightforward to generate typed clients for the WebSocket routing interface.

Summary

• OmniRoute supports WebSocket routing through a dedicated handshake API at /api/v1/ws implemented in src/app/api/v1/ws/route.ts.
• Authentication tokens and paths are generated by src/lib/ws/handshake.ts before any persistent connection is established.
• The live-dashboard event stream runs on the daemon in src/server/ws/liveServer.ts, protected by src/server/ws/liveServerAllowList.ts.
• Path resolution is centralized in src/shared/utils/wsPath.ts, which derives routes from the NEXT_PUBLIC_LIVE_WS_PUBLIC_URL environment variable.
• Client code can connect to the live dashboard or use the Responses-over-WebSocket bridge for streaming LLM responses.
• Comprehensive unit tests in tests/unit/v1-ws-bridge.test.ts and tests/unit/responses-ws-proxy-*.test.ts validate upgrade flows and message proxying.

Frequently Asked Questions

Does OmniRoute support WebSocket routing natively?

Yes. As implemented in diegosouzapw/OmniRoute, the framework includes native WebSocket routing across multiple subsystems. The src/app/api/v1/ws/route.ts file handles HTTP upgrades, while src/server/ws/liveServer.ts maintains the persistent event socket.

How does OmniRoute authenticate WebSocket connections?

The src/lib/ws/handshake.ts module validates API keys or credentials during the initial HTTP handshake. Upon success, it returns a wsAuth token and a wsPath that the client uses to open the final authenticated WebSocket connection.

Which OmniRoute features rely on WebSocket routing?

The live-dashboard telemetry stream, the OpenAI-compatible chat endpoint, and the Responses-over-WebSocket bridge all depend on the same core WebSocket routing layer. Each feature uses the shared handshake and path utilities but targets different runtime daemons or API routes.

Is the OmniRoute WebSocket API documented for client generation?

Yes. The repository includes docs/openapi.yaml, which formally specifies the /api/v1/ws endpoint. This allows OpenAPI client generators to produce typed interfaces for the handshake and connection logic automatically.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}