Capability Negotiation

Parse Connection Parameters

Connection parameters are extracted from a combination of URL query parameters and HTTP headers. The client version and capability flags are required fields; missing values cause the connection to be rejected.

interface ConnectParams {
  // Authentication
  connectAuth: ConnectAuth;
  sessionId?: string;

  // Client identification
  clientVersion: string;
  platform: "android" | "ios" | "desktop" | "web";
  deviceId: string;

  // Capability flags
  capabilities: {
    canvas: boolean;
    canvasVersion?: number;
    canvasHostUrl?: string;
    canvasMaxWidth?: number;
    canvasMaxHeight?: number;
    canvasFormats?: string[];
    canvasExpiresInMs?: number;
  };
}

function parseConnectParams(
  url: URL,
  headers: Headers,
): ConnectParams | { error: string } {
  const version = url.searchParams.get("v");
  if (!version) {
    return { error: "missing-client-version" };
  }
  const platform = url.searchParams.get("platform");
  if (!platform || !["android", "ios", "desktop", "web"].includes(platform)) {
    return { error: "invalid-platform" };
  }
  return {
    connectAuth: extractAuth(headers),
    clientVersion: version,
    platform: platform as ConnectParams["platform"],
    deviceId: url.searchParams.get("deviceId") ?? generateDeviceId(),
    capabilities: {
      canvas: url.searchParams.get("canvas") === "true",
      canvasVersion: parseInt(url.searchParams.get("canvasVersion") ?? "0"),
      canvasHostUrl: url.searchParams.get("canvasHostUrl") ?? undefined,
      canvasMaxWidth: parseInt(url.searchParams.get("canvasMaxWidth") ?? "0"),
      canvasMaxHeight: parseInt(url.searchParams.get("canvasMaxHeight") ?? "0"),
      canvasFormats: url.searchParams.get("canvasFormats")?.split(","),
      canvasExpiresInMs: parseInt(url.searchParams.get("canvasExpiresInMs") ?? "0"),
    },
  };
}

Validate Client Version

The Gateway maintains a minimum supported version. Clients below this version are disconnected with a 4001 close code and must update before reconnecting.

Register in NodeRegistry

Once validated, the client's capabilities are registered in the NodeRegistry. The registry maintains a map of connection IDs to GatewayWsClient entries and emits events when capabilities change.

class NodeRegistry {
  private nodes: Map<string, GatewayWsClient> = new Map();
  private listeners: Map<string, Set<CapabilityListener>> = new Map();

  registerNode(connId: string, params: ConnectParams, socket: WebSocket, clientIp: string): void {
    const client: GatewayWsClient = {
      connId,
      clientIp,
      socket,
      connectedAtMs: Date.now(),
      canvasCapability: params.capabilities.canvas ? {
        supported: true,
        version: params.capabilities.canvasVersion ?? 1,
        maxWidth: params.capabilities.canvasMaxWidth ?? 1920,
        maxHeight: params.capabilities.canvasMaxHeight ?? 1080,
        formats: (params.capabilities.canvasFormats ?? ["png"]) as CanvasCapability["formats"],
      } : null,
      canvasHostUrl: params.capabilities.canvasHostUrl ?? null,
      canvasCapabilityExpiresAtMs: params.capabilities.canvasExpiresInMs
        ? Date.now() + params.capabilities.canvasExpiresInMs
        : null,
      clientVersion: params.clientVersion,
      platform: params.platform,
      deviceId: params.deviceId,
      lastPingMs: Date.now(),
      pendingMessages: 0,
      isAlive: true,
    };
    this.nodes.set(connId, client);
    this.emit("registered", connId, client);
  }

  getNode(connId: string): GatewayWsClient | undefined {
    return this.nodes.get(connId);
  }

  getNodesWithCapability(cap: string): GatewayWsClient[] {
    return Array.from(this.nodes.values()).filter(n => {
      if (cap === "canvas") return n.canvasCapability?.supported === true;
      return false;
    });
  }

  removeNode(connId: string): void {
    const node = this.nodes.get(connId);
    if (node) {
      this.nodes.delete(connId);
      this.emit("removed", connId, node);
    }
  }

  private emit(event: string, connId: string, client: GatewayWsClient): void {
    const set = this.listeners.get(event);
    if (set) set.forEach(fn => fn(connId, client));
  }
}

type CapabilityListener = (connId: string, client: GatewayWsClient) => void;

Capability Expiration & Renewal

The CronService periodically checks canvasCapabilityExpiresAtMs for each registered node. When a capability expires, the node is notified via WebSocket and expected to re-send updated capability flags within a grace period. If the node does not renew, the capability is set to null.