Message Dispatch

Overview

When a client sends an RPC message over the WebSocket connection, the Gateway must determine which handler should process the request and ensure the message conforms to the expected protocol schema. The dispatch pipeline is the central routing mechanism that connects raw protocol frames to strongly-typed handler functions.

The pipeline is intentionally synchronous in its lookup phase — handler resolution is a simple dictionary lookup — but handlers themselves may be async. This design keeps the hot path fast while allowing individual handlers to perform I/O operations like database queries or external API calls.

Core Types

GatewayRequestHandler

Each handler is a function that receives a fully-populated options object and either returns void synchronously or returns a Promise for async operations.

/**
 * A single RPC handler function. Receives the parsed request,
 * the originating client, and a respond callback.
 */
type GatewayRequestHandler = (
  opts: GatewayRequestHandlerOptions
) => Promise<void> | void;

/**
 * The handler registry maps method names to their handlers.
 * Used by the dispatch pipeline to resolve incoming requests.
 */
type GatewayRequestHandlers = Record<string, GatewayRequestHandler>;

GatewayRequestHandlerOptions

The options object bundles everything a handler needs to process a request and send a response.

interface GatewayRequestHandlerOptions {
  /** The validated and parsed incoming request frame */
  req: RequestFrame;

  /** The connected client that sent this request */
  client: GatewayClient;

  /**
   * Callback to send a response back to the client.
   * @param ok      - Whether the request succeeded
   * @param payload - Optional success payload
   * @param error   - Optional error details
   * @param meta    - Optional response metadata
   */
  respond: RespondFn;

  /** Contextual information about the current request */
  context: GatewayRequestContext;
}

RespondFn

The respond function is the sole mechanism for handlers to send data back to the client. It enforces a consistent response envelope.

/**
 * Sends a typed response back to the requesting client.
 * Wraps the payload in a ResponseFrame automatically.
 */
type RespondFn = (
  ok: boolean,
  payload?: unknown,
  error?: string | { code: string; message: string },
  meta?: Record<string, unknown>
) => void;

Protocol Frames

Dispatch Pipeline

Every incoming message traverses five stages before reaching a handler. The pipeline is designed to fail fast — invalid frames are rejected before any handler code executes.

flowchart TD
    A[WebSocket Message Received] --> B[Parse JSON Frame]
    B --> C{Valid JSON?}
    C -- No --> D[Send Parse Error Response]
    C -- Yes --> E[validateRequestFrame]
    E --> F{Frame Valid?}
    F -- No --> G[Send Validation Error Response]
    F -- Yes --> H[Extract method from RequestFrame]
    H --> I{Handler Exists?}
    I -- No --> J[Send Method Not Found Response]
    I -- Yes --> K[Build GatewayRequestHandlerOptions]
    K --> L[Invoke Handler with opts]
    L --> M{Handler Throws?}
    M -- Yes --> N[Catch Error and Send Error Response]
    M -- No --> O[Handler calls respond fn]
    O --> P[Build ResponseFrame]
    P --> Q[Send to Client via WebSocket]
    D --> R[Log and Metrics]
    G --> R
    J --> R
    N --> R
    Q --> R

Request Validation

The validateRequestFrame() function ensures every incoming frame conforms to the protocol specification before any handler logic executes. This prevents handlers from needing to perform their own input validation.

Validator Categories

function parseIncomingFrame(raw: string): RequestFrame | null {
  try {
    const parsed = JSON.parse(raw);
    if (typeof parsed !== 'object' || parsed === null) return null;
    if (typeof parsed.id !== 'string') return null;
    if (typeof parsed.method !== 'string') return null;
    return parsed as RequestFrame;
  } catch {
    return null;
  }
}

function validateRequestFrame(frame: RequestFrame): ValidationResult {
  for (const validator of PROTOCOL_VALIDATORS) {
    const result = validator(frame);
    if (!result.ok) {
      return {
        ok: false,
        code: result.code,
        message: result.message,
        validator: validator.name,
      };
    }
  }
  return { ok: true };
}

function resolveHandler(
  handlers: GatewayRequestHandlers,
  method: string
): GatewayRequestHandler | undefined {
  return handlers[method];
}

async function dispatchToHandler(
  handler: GatewayRequestHandler,
  opts: GatewayRequestHandlerOptions
): Promise<void> {
  try {
    await handler(opts);
  } catch (err) {
    opts.respond(false, undefined, {
      code: 'INTERNAL_ERROR',
      message: err instanceof Error ? err.message : 'Unknown error',
    });
  }
}

Dispatch Sequence

The following sequence diagram shows the complete message lifecycle from client to handler and back.

sequenceDiagram
    participant C as Client
    participant WS as WebSocket Layer
    participant DP as Dispatch Pipeline
    participant V as validateRequestFrame
    participant R as Handler Registry
    participant H as Request Handler
    participant RS as RespondFn

    C->>WS: Send JSON RPC message
    WS->>DP: onMessage(raw)
    DP->>DP: JSON.parse(raw)
    alt parse failure
        DP-->>C: {ok: false, error: "PARSE_ERROR"}
    end
    DP->>V: validateRequestFrame(frame)
    V->>V: Run 80+ validators
    alt validation failure
        V-->>DP: {ok: false, code, message}
        DP-->>C: {ok: false, error: validationError}
    end
    V-->>DP: {ok: true}
    DP->>R: lookup(frame.method)
    alt handler not found
        R-->>DP: undefined
        DP-->>C: {ok: false, error: "METHOD_NOT_FOUND"}
    end
    R-->>DP: handler
    DP->>H: handler({req, client, respond, context})
    H->>RS: respond(true, payload)
    RS->>WS: Build ResponseFrame
    WS-->>C: Send JSON response

Error Handling

Handler Registration

Handlers are registered at Gateway startup by building the GatewayRequestHandlers map. Each entry maps a method name string to its handler function.

function buildHandlerRegistry(): GatewayRequestHandlers {
  return {
    'session.create': handleSessionCreate,
    'session.list': handleSessionList,
    'session.patch': handleSessionPatch,
    'session.delete': handleSessionDelete,
    'message.send': handleMessageSend,
    'message.stream': handleMessageStream,
    'assistant.resolve': handleAssistantResolve,
    'config.get': handleConfigGet,
    'config.set': handleConfigSet,
    'health.ping': handleHealthPing,
    // ... 70+ more handlers
  };
}

Request Context

Every handler receives a GatewayRequestContext object with per-request metadata used for tracing, logging, and session correlation.

Related Topics

• Routing Overview — full routing subsystem
• Session Management — session lifecycle and state tracking
• Assistant Identity — how assistant names and avatars are resolved
• Auth — authentication layer that precedes dispatch

Directory Map

src/gateway/
├── dispatch.ts                ← dispatch pipeline, handler invocation
├── handlers/
│   ├── index.ts               ← buildHandlerRegistry()
│   ├── session.ts             ← session.* handlers
│   ├── message.ts             ← message.* handlers
│   ├── assistant.ts           ← assistant.* handlers
│   └── config.ts              ← config.* handlers
├── protocol/
│   ├── index.ts               ← RequestFrame, ResponseFrame
│   ├── validators.ts          ← validateRequestFrame(), 80+ validators
│   └── types.ts               ← GatewayRequestHandlerOptions, RespondFn
└── client.ts                  ← GatewayClient, GatewayRequestContext