@cyanmycelium/mcp-broker-provider 0.1.0 → 0.1.1

package/README.md

@@ -32,12 +32,14 @@ A multiplexed tunnel socket carries traffic for several providers at once, so ev
 { "provider": "scene-1", "payload": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } }
 ```
 
-`./protocol` is the single definition of that format. The broker imports it rather than re-declaring the shape inline, so the two ends cannot drift.
+`./protocol` is the single definition of that format, and the broker imports it from here rather than re-declaring the shape inline, so the two ends cannot drift. The broker depends on this package because it is itself a provider: it publishes its own `_broker` introspection slot and its `_all` aggregate slot.
 
 Beyond the envelope it also covers:
 
 - `notifications/register`, sent as soon as the tunnel opens to claim a provider slot. Without it the broker only learns a provider name on its first real message, and an MCP client connecting in between is told the provider is not connected.
-- The tunnel error codes: `-32001` when the provider's credentials do not allow publishing on the requested slot, `-32000` when the slot is unavailable. `tunnelErrorOf()` lets a provider recognise them instead of handing an `id: null` error frame to an MCP server, which would classify it as an unknown notification and drop it silently.
+- The tunnel error codes: `-32001` when the provider's credentials do not allow publishing on the requested slot, `-32000` when the slot is unavailable.
+
+When the broker refuses a slot, the transport surfaces it through `onError` rather than forwarding it. An id-less error frame handed to an MCP server would be classified as an unknown notification and dropped without a word, so the publisher would never learn it was refused.
 
 Malformed frames decode to `undefined` rather than throwing: a tunnel socket is a public surface, and a peer sending garbage must not take the receiver down.
 
@@ -67,9 +69,9 @@ Transports created for the same tunnel URL share one WebSocket, whichever order
 
 ## Status
 
-`0.1.0` ships the protocol module and both transports. They still exist in `@cyanmycelium/mcp-core@0.4.x` as well, and are removed there in `0.5.0` — migrate your imports before upgrading.
+`0.1.0` ships the protocol module and both transports. They still exist in `@cyanmycelium/mcp-core@0.4.x` as well, and are removed there in `0.5.0`, migrate your imports before upgrading.
 
-The protocol is shared with the broker and, later, with the consumer side, so it is expected to graduate into its own `@cyanmycelium/mcp-broker-core` package. Import it through the `./protocol` subpath rather than the package root and that move will cost you one line.
+The protocol is shared with the broker, and later with the consumer side. Import it through the `./protocol` subpath rather than the package root, so it can move to a package of its own one day without touching your call sites.
 
 ## License
 

package/dist/index.d.ts

@@ -1,11 +1,112 @@
+export { TUNNEL_REGISTER_METHOD, TunnelEnvelope, TunnelError, TunnelErrorCode, TunnelErrorCodes, decodeEnvelope, encodeEnvelope, encodeEnvelopeMessage, encodeErrorEnvelope, encodeRegisterEnvelope, envelopeFrame, tunnelErrorOf } from './protocol/index.js';
+import { IMessageTransport } from '@cyanmycelium/mcp-core';
+
 /**
- * Provider side of the CyanMycelium MCP broker tunnel: what an application uses
- * to publish its MCP server to a broker slot.
+ * 1:1 WebSocket transport, wraps a single `WebSocket` connection to a broker
+ * provider slot, typically `ws://<broker>/provider/<name>`.
  *
- * The tunnel envelope protocol is also published on its own entry point,
- * `@cyanmycelium/mcp-broker-provider/protocol`, which the broker imports so both
- * ends of the tunnel share one definition of the wire format.
+ * One server owns one socket. When an application publishes several servers
+ * through the same broker, prefer {@link MultiplexTransport}, which shares a
+ * single socket between them.
+ *
+ * Call {@link connect} after setting the event callbacks to open the socket.
+ */
+declare class DirectTransport implements IMessageTransport {
+    private readonly _wsUrl;
+    private _ws;
+    onMessage: ((data: string) => void) | null;
+    onOpen: (() => void) | null;
+    onClose: (() => void) | null;
+    onError: ((error: Error) => void) | null;
+    constructor(wsUrl: string);
+    get isOpen(): boolean;
+    /**
+     * Opens the WebSocket connection and wires its events to the transport
+     * callbacks. Must be called after assigning `onOpen` / `onMessage` / etc.
+     */
+    connect(): void;
+    send(data: string): void;
+    close(): void;
+}
+
+/**
+ * Manages a single WebSocket connection shared by multiple {@link MultiplexTransport}
+ * instances. All traffic goes through the tunnel envelope protocol, whose
+ * definition lives in `./protocol` and is shared with the broker.
+ *
+ * Reconnection is handled centrally here, individual transports do not reconnect.
+ * Use {@link getOrCreate} to obtain a per-URL singleton.
+ */
+declare class MultiplexSocket {
+    /** Per-URL cache so all transports targeting the same tunnel share one socket. */
+    private static readonly _instances;
+    private readonly _wsUrl;
+    private readonly _transports;
+    private _ws;
+    private _reconnectAttempts;
+    private _stopped;
+    private constructor();
+    /** Returns (or creates) the singleton socket for a given tunnel URL. */
+    static getOrCreate(wsUrl: string): MultiplexSocket;
+    get isOpen(): boolean;
+    register(name: string, transport: MultiplexTransport): void;
+    unregister(name: string): void;
+    /**
+     * Claims the slot for `name` so the broker eagerly creates its provider
+     * state before any MCP client connects. Without it the broker only learns
+     * about a provider on its first real message, and a client connecting in
+     * between is told the provider is not connected.
+     */
+    private _announceProvider;
+    send(provider: string, data: string): void;
+    private _connect;
+    private _routeIncoming;
+    private _scheduleReconnect;
+}
+/**
+ * A transport that multiplexes multiple MCP servers over a single shared
+ * WebSocket connection using the envelope protocol `{ provider, payload }`.
+ *
+ * Use the static {@link create} factory to obtain an instance:
+ * ```typescript
+ * const t1 = MultiplexTransport.create("scene-1", "ws://localhost:3000/providers");
+ * const t2 = MultiplexTransport.create("scene-2", "ws://localhost:3000/providers");
+ * // t1 and t2 share a single WebSocket under the hood.
+ * ```
  */
-export * from "./protocol/index";
-export { DirectTransport } from "./direct.transport";
-export { MultiplexTransport } from "./multiplex.transport";
+declare class MultiplexTransport implements IMessageTransport {
+    private readonly _name;
+    private readonly _socket;
+    private _registered;
+    onMessage: ((data: string) => void) | null;
+    onOpen: (() => void) | null;
+    onClose: (() => void) | null;
+    onError: ((error: Error) => void) | null;
+    constructor(name: string, socket: MultiplexSocket);
+    /**
+     * Convenience factory: creates a {@link MultiplexTransport} backed by a
+     * shared {@link MultiplexSocket} for the given tunnel URL.
+     *
+     * Transports targeting the same `wsUrl` automatically share one WebSocket.
+     */
+    static create(name: string, wsUrl: string): MultiplexTransport;
+    get isOpen(): boolean;
+    /**
+     * Registers this transport with the shared socket.
+     *
+     * Safe to call multiple times, subsequent calls are no-ops.
+     */
+    activate(): void;
+    /**
+     * Opens the transport, the same way every other transport does.
+     *
+     * An alias of {@link activate} so callers never have to special-case this
+     * class: an MCP server or client just calls `connect()` on whatever
+     * transport it was handed.
+     */
+    connect(): void;
+    send(data: string): void;
+    close(): void;
+}
+
+export { DirectTransport, MultiplexTransport };

package/dist/index.js

@@ -1,12 +1,266 @@
-/**
- * Provider side of the CyanMycelium MCP broker tunnel: what an application uses
- * to publish its MCP server to a broker slot.
- *
- * The tunnel envelope protocol is also published on its own entry point,
- * `@cyanmycelium/mcp-broker-provider/protocol`, which the broker imports so both
- * ends of the tunnel share one definition of the wire format.
- */
-export * from "./protocol/index";
-export { DirectTransport } from "./direct.transport";
-export { MultiplexTransport } from "./multiplex.transport";
+// src/protocol/envelope.ts
+var TUNNEL_REGISTER_METHOD = "notifications/register";
+var TunnelErrorCodes = {
+  /** The slot is taken by another upstream, or the provider is not connected. */
+  ProviderUnavailable: -32e3,
+  /** The provider's credentials do not allow publishing on this slot. */
+  RegistrationForbidden: -32001
+};
+function encodeEnvelope(provider, frame) {
+  return encodeEnvelopeMessage(provider, JSON.parse(frame));
+}
+function encodeEnvelopeMessage(provider, payload) {
+  const envelope = { provider, payload };
+  return JSON.stringify(envelope);
+}
+function decodeEnvelope(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+  const { provider, payload } = parsed;
+  if (typeof provider !== "string" || provider.length === 0 || payload === void 0) return void 0;
+  return { provider, payload };
+}
+function envelopeFrame(envelope) {
+  return JSON.stringify(envelope.payload);
+}
+function encodeRegisterEnvelope(provider) {
+  return encodeEnvelopeMessage(provider, { jsonrpc: "2.0", method: TUNNEL_REGISTER_METHOD });
+}
+function encodeErrorEnvelope(provider, code, message) {
+  return encodeEnvelopeMessage(provider, { jsonrpc: "2.0", id: null, error: { code, message } });
+}
+function tunnelErrorOf(payload) {
+  if (typeof payload !== "object" || payload === null) return void 0;
+  const { error } = payload;
+  if (typeof error !== "object" || error === null) return void 0;
+  const { code, message } = error;
+  if (typeof code !== "number" || typeof message !== "string") return void 0;
+  return error;
+}
+
+// src/direct.transport.ts
+var DirectTransport = class {
+  _wsUrl;
+  _ws = null;
+  onMessage = null;
+  onOpen = null;
+  onClose = null;
+  onError = null;
+  constructor(wsUrl) {
+    this._wsUrl = wsUrl;
+  }
+  get isOpen() {
+    return this._ws?.readyState === WebSocket.OPEN;
+  }
+  /**
+   * Opens the WebSocket connection and wires its events to the transport
+   * callbacks. Must be called after assigning `onOpen` / `onMessage` / etc.
+   */
+  connect() {
+    const ws = new WebSocket(this._wsUrl);
+    ws.onopen = () => {
+      this._ws = ws;
+      this.onOpen?.();
+    };
+    ws.onerror = () => {
+      this.onError?.(new Error(`DirectTransport: WebSocket error on ${this._wsUrl}`));
+    };
+    ws.onclose = () => {
+      this._ws = null;
+      this.onClose?.();
+    };
+    ws.onmessage = (event) => {
+      this.onMessage?.(event.data);
+    };
+  }
+  send(data) {
+    if (this._ws?.readyState === WebSocket.OPEN) {
+      this._ws.send(data);
+    }
+  }
+  close() {
+    this._ws?.close();
+    this._ws = null;
+  }
+};
+
+// src/multiplex.transport.ts
+var MultiplexSocket = class _MultiplexSocket {
+  /** Per-URL cache so all transports targeting the same tunnel share one socket. */
+  static _instances = /* @__PURE__ */ new Map();
+  _wsUrl;
+  _transports = /* @__PURE__ */ new Map();
+  _ws = null;
+  _reconnectAttempts = 0;
+  _stopped = false;
+  constructor(wsUrl) {
+    this._wsUrl = wsUrl;
+  }
+  /** Returns (or creates) the singleton socket for a given tunnel URL. */
+  static getOrCreate(wsUrl) {
+    let instance = _MultiplexSocket._instances.get(wsUrl);
+    if (!instance) {
+      instance = new _MultiplexSocket(wsUrl);
+      _MultiplexSocket._instances.set(wsUrl, instance);
+    }
+    return instance;
+  }
+  get isOpen() {
+    return this._ws?.readyState === WebSocket.OPEN;
+  }
+  // ── Registration ────────────────────────────────────────────────────────
+  register(name, transport) {
+    this._transports.set(name, transport);
+    if (this.isOpen) {
+      this._announceProvider(name);
+      transport.onOpen?.();
+    } else if (!this._ws) {
+      this._stopped = false;
+      this._connect();
+    }
+  }
+  unregister(name) {
+    this._transports.delete(name);
+    if (this._transports.size === 0) {
+      this._stopped = true;
+      this._ws?.close();
+      this._ws = null;
+      _MultiplexSocket._instances.delete(this._wsUrl);
+    }
+  }
+  /**
+   * Claims the slot for `name` so the broker eagerly creates its provider
+   * state before any MCP client connects. Without it the broker only learns
+   * about a provider on its first real message, and a client connecting in
+   * between is told the provider is not connected.
+   */
+  _announceProvider(name) {
+    if (this._ws?.readyState !== WebSocket.OPEN) return;
+    this._ws.send(encodeRegisterEnvelope(name));
+  }
+  // ── Sending ─────────────────────────────────────────────────────────────
+  send(provider, data) {
+    if (this._ws?.readyState !== WebSocket.OPEN) return;
+    this._ws.send(encodeEnvelope(provider, data));
+  }
+  // ── Connection lifecycle ────────────────────────────────────────────────
+  _connect() {
+    const ws = new WebSocket(this._wsUrl);
+    this._ws = ws;
+    ws.onopen = () => {
+      this._reconnectAttempts = 0;
+      for (const name of this._transports.keys()) {
+        this._announceProvider(name);
+      }
+      for (const transport of this._transports.values()) {
+        transport.onOpen?.();
+      }
+    };
+    ws.onerror = () => {
+      for (const transport of this._transports.values()) {
+        transport.onError?.(new Error(`MultiplexSocket: WebSocket error on ${this._wsUrl}`));
+      }
+    };
+    ws.onclose = () => {
+      this._ws = null;
+      for (const transport of this._transports.values()) {
+        transport.onClose?.();
+      }
+      if (!this._stopped) {
+        this._scheduleReconnect();
+      }
+    };
+    ws.onmessage = (event) => {
+      this._routeIncoming(event.data);
+    };
+  }
+  _routeIncoming(raw) {
+    const envelope = decodeEnvelope(raw);
+    if (!envelope) return;
+    const transport = this._transports.get(envelope.provider);
+    if (!transport) return;
+    const payload = envelope.payload;
+    if (payload !== null && (payload.id === null || payload.id === void 0)) {
+      const error = tunnelErrorOf(envelope.payload);
+      if (error) {
+        transport.onError?.(new Error(`Tunnel error ${error.code} on provider "${envelope.provider}": ${error.message}`));
+        return;
+      }
+    }
+    transport.onMessage?.(envelopeFrame(envelope));
+  }
+  _scheduleReconnect() {
+    const base = 1e3;
+    const max = 3e4;
+    const jitter = 0.5 + Math.random() * 0.5;
+    const delay = Math.min(base * 2 ** this._reconnectAttempts, max) * jitter;
+    this._reconnectAttempts++;
+    setTimeout(() => {
+      if (!this._stopped) this._connect();
+    }, delay);
+  }
+};
+var MultiplexTransport = class _MultiplexTransport {
+  _name;
+  _socket;
+  _registered = false;
+  onMessage = null;
+  onOpen = null;
+  onClose = null;
+  onError = null;
+  constructor(name, socket) {
+    this._name = name;
+    this._socket = socket;
+  }
+  /**
+   * Convenience factory: creates a {@link MultiplexTransport} backed by a
+   * shared {@link MultiplexSocket} for the given tunnel URL.
+   *
+   * Transports targeting the same `wsUrl` automatically share one WebSocket.
+   */
+  static create(name, wsUrl) {
+    return new _MultiplexTransport(name, MultiplexSocket.getOrCreate(wsUrl));
+  }
+  get isOpen() {
+    return this._socket.isOpen;
+  }
+  /**
+   * Registers this transport with the shared socket.
+   *
+   * Safe to call multiple times, subsequent calls are no-ops.
+   */
+  activate() {
+    if (!this._registered) {
+      this._registered = true;
+      this._socket.register(this._name, this);
+    }
+  }
+  /**
+   * Opens the transport, the same way every other transport does.
+   *
+   * An alias of {@link activate} so callers never have to special-case this
+   * class: an MCP server or client just calls `connect()` on whatever
+   * transport it was handed.
+   */
+  connect() {
+    this.activate();
+  }
+  send(data) {
+    this._socket.send(this._name, data);
+  }
+  close() {
+    if (this._registered) {
+      this._registered = false;
+      this._socket.unregister(this._name);
+    }
+  }
+};
+
+export { DirectTransport, MultiplexTransport, TUNNEL_REGISTER_METHOD, TunnelErrorCodes, decodeEnvelope, encodeEnvelope, encodeEnvelopeMessage, encodeErrorEnvelope, encodeRegisterEnvelope, envelopeFrame, tunnelErrorOf };
+//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"sources":["../src/protocol/envelope.ts","../src/direct.transport.ts","../src/multiplex.transport.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * The CyanMycelium tunnel envelope protocol.\n *\n * A multiplexed tunnel socket carries traffic for several providers at once, so\n * every JSON-RPC message is wrapped with the name of the provider slot it\n * belongs to. Both ends of the tunnel encode and decode with the helpers here:\n * the client transports that publish a provider, and the broker that routes\n * between providers and MCP clients.\n *\n * This module is the single definition of that wire format. It is deliberately\n * dependency-free and isomorphic, so the browser side and the Node broker share\n * exactly one implementation rather than two that drift apart.\n *\n * Wire format:\n * ```json\n * { \"provider\": \"scene-1\", \"payload\": { \"jsonrpc\": \"2.0\", \"id\": 1, \"result\": {} } }\n * ```\n */\n\n/** One framed message on a multiplexed tunnel socket. */\nexport interface TunnelEnvelope {\n    /** Name of the provider slot this message belongs to. */\n    provider: string;\n\n    /** The JSON-RPC message itself, already parsed. */\n    payload: unknown;\n}\n\n/**\n * Notification a client sends to claim a provider slot as soon as the tunnel\n * opens, before any MCP client shows up.\n *\n * Without it the broker only discovers a provider name on its first real\n * message, so an MCP client connecting in between is told the provider is not\n * connected. It is a plain JSON-RPC notification, which any peer that does not\n * recognize it ignores.\n */\nexport const TUNNEL_REGISTER_METHOD = \"notifications/register\";\n\n/** JSON-RPC error codes the broker returns on the tunnel itself. */\nexport const TunnelErrorCodes = {\n    /** The slot is taken by another upstream, or the provider is not connected. */\n    ProviderUnavailable: -32000,\n\n    /** The provider's credentials do not allow publishing on this slot. */\n    RegistrationForbidden: -32001,\n} as const;\n\nexport type TunnelErrorCode = (typeof TunnelErrorCodes)[keyof typeof TunnelErrorCodes];\n\n/** A JSON-RPC error as carried inside an envelope payload. */\nexport interface TunnelError {\n    code: number;\n    message: string;\n    data?: unknown;\n}\n\n/**\n * Wraps an already-serialized JSON-RPC frame for `provider`.\n *\n * @throws SyntaxError when `frame` is not valid JSON. Callers hold a frame they\n *         just serialized, so a failure here is a bug rather than bad input.\n */\nexport function encodeEnvelope(provider: string, frame: string): string {\n    return encodeEnvelopeMessage(provider, JSON.parse(frame));\n}\n\n/** Wraps an already-parsed JSON-RPC message for `provider`. */\nexport function encodeEnvelopeMessage(provider: string, payload: unknown): string {\n    const envelope: TunnelEnvelope = { provider, payload };\n    return JSON.stringify(envelope);\n}\n\n/**\n * Parses a raw tunnel frame.\n *\n * Returns `undefined` for anything malformed rather than throwing: a tunnel\n * socket is a public surface, and a peer sending garbage must not take the\n * receiver down. Both ends drop such frames silently.\n */\nexport function decodeEnvelope(raw: string): TunnelEnvelope | undefined {\n    let parsed: unknown;\n    try {\n        parsed = JSON.parse(raw);\n    } catch {\n        return undefined;\n    }\n    if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) return undefined;\n\n    const { provider, payload } = parsed as Partial<TunnelEnvelope>;\n    if (typeof provider !== \"string\" || provider.length === 0 || payload === undefined) return undefined;\n\n    return { provider, payload };\n}\n\n/** Serializes an envelope's payload back into a plain JSON-RPC frame. */\nexport function envelopeFrame(envelope: TunnelEnvelope): string {\n    return JSON.stringify(envelope.payload);\n}\n\n/** Builds the registration notification that claims `provider`. */\nexport function encodeRegisterEnvelope(provider: string): string {\n    return encodeEnvelopeMessage(provider, { jsonrpc: \"2.0\", method: TUNNEL_REGISTER_METHOD });\n}\n\n/**\n * Builds the error envelope the broker returns when it refuses a slot.\n *\n * The id is `null` because the refusal answers no particular request: it\n * reacts to the registration itself.\n */\nexport function encodeErrorEnvelope(provider: string, code: TunnelErrorCode | number, message: string): string {\n    return encodeEnvelopeMessage(provider, { jsonrpc: \"2.0\", id: null, error: { code, message } });\n}\n\n/**\n * Reads the JSON-RPC error out of an envelope payload, when there is one.\n *\n * Lets the client side notice a refused registration instead of handing an\n * `id: null` error frame to an MCP server, which would classify it as an\n * unknown notification and drop it without a word.\n */\nexport function tunnelErrorOf(payload: unknown): TunnelError | undefined {\n    if (typeof payload !== \"object\" || payload === null) return undefined;\n\n    const { error } = payload as { error?: unknown };\n    if (typeof error !== \"object\" || error === null) return undefined;\n\n    const { code, message } = error as Partial<TunnelError>;\n    if (typeof code !== \"number\" || typeof message !== \"string\") return undefined;\n\n    return error as TunnelError;\n}\n","import type { IMessageTransport } from \"@cyanmycelium/mcp-core\";\n\n/**\n * 1:1 WebSocket transport, wraps a single `WebSocket` connection to a broker\n * provider slot, typically `ws://<broker>/provider/<name>`.\n *\n * One server owns one socket. When an application publishes several servers\n * through the same broker, prefer {@link MultiplexTransport}, which shares a\n * single socket between them.\n *\n * Call {@link connect} after setting the event callbacks to open the socket.\n */\nexport class DirectTransport implements IMessageTransport {\n    private readonly _wsUrl: string;\n    private _ws: WebSocket | null = null;\n\n    onMessage: ((data: string) => void) | null = null;\n    onOpen: (() => void) | null = null;\n    onClose: (() => void) | null = null;\n    onError: ((error: Error) => void) | null = null;\n\n    constructor(wsUrl: string) {\n        this._wsUrl = wsUrl;\n    }\n\n    get isOpen(): boolean {\n        return this._ws?.readyState === WebSocket.OPEN;\n    }\n\n    /**\n     * Opens the WebSocket connection and wires its events to the transport\n     * callbacks. Must be called after assigning `onOpen` / `onMessage` / etc.\n     */\n    connect(): void {\n        const ws = new WebSocket(this._wsUrl);\n\n        ws.onopen = () => {\n            this._ws = ws;\n            this.onOpen?.();\n        };\n\n        ws.onerror = () => {\n            this.onError?.(new Error(`DirectTransport: WebSocket error on ${this._wsUrl}`));\n        };\n\n        ws.onclose = () => {\n            this._ws = null;\n            this.onClose?.();\n        };\n\n        ws.onmessage = (event: MessageEvent<string>) => {\n            this.onMessage?.(event.data);\n        };\n    }\n\n    send(data: string): void {\n        if (this._ws?.readyState === WebSocket.OPEN) {\n            this._ws.send(data);\n        }\n    }\n\n    close(): void {\n        this._ws?.close();\n        this._ws = null;\n    }\n}\n","import type { IMessageTransport } from \"@cyanmycelium/mcp-core\";\nimport { decodeEnvelope, encodeEnvelope, encodeRegisterEnvelope, envelopeFrame, tunnelErrorOf } from \"./protocol/index\";\n\n// ---------------------------------------------------------------------------\n// MultiplexSocket, shared WebSocket singleton (internal)\n// ---------------------------------------------------------------------------\n\n/**\n * Manages a single WebSocket connection shared by multiple {@link MultiplexTransport}\n * instances. All traffic goes through the tunnel envelope protocol, whose\n * definition lives in `./protocol` and is shared with the broker.\n *\n * Reconnection is handled centrally here, individual transports do not reconnect.\n * Use {@link getOrCreate} to obtain a per-URL singleton.\n */\nclass MultiplexSocket {\n    /** Per-URL cache so all transports targeting the same tunnel share one socket. */\n    private static readonly _instances = new Map<string, MultiplexSocket>();\n\n    private readonly _wsUrl: string;\n    private readonly _transports = new Map<string, MultiplexTransport>();\n    private _ws: WebSocket | null = null;\n    private _reconnectAttempts = 0;\n    private _stopped = false;\n\n    private constructor(wsUrl: string) {\n        this._wsUrl = wsUrl;\n    }\n\n    /** Returns (or creates) the singleton socket for a given tunnel URL. */\n    static getOrCreate(wsUrl: string): MultiplexSocket {\n        let instance = MultiplexSocket._instances.get(wsUrl);\n        if (!instance) {\n            instance = new MultiplexSocket(wsUrl);\n            MultiplexSocket._instances.set(wsUrl, instance);\n        }\n        return instance;\n    }\n\n    get isOpen(): boolean {\n        return this._ws?.readyState === WebSocket.OPEN;\n    }\n\n    // ── Registration ────────────────────────────────────────────────────────\n\n    register(name: string, transport: MultiplexTransport): void {\n        this._transports.set(name, transport);\n\n        // If the shared socket is already open, announce the new provider and\n        // notify the transport immediately.\n        if (this.isOpen) {\n            this._announceProvider(name);\n            transport.onOpen?.();\n        } else if (!this._ws) {\n            // First registration, open the connection.\n            this._stopped = false;\n            this._connect();\n        }\n    }\n\n    unregister(name: string): void {\n        this._transports.delete(name);\n\n        // Tear down the shared socket when no transports remain.\n        if (this._transports.size === 0) {\n            this._stopped = true;\n            this._ws?.close();\n            this._ws = null;\n            MultiplexSocket._instances.delete(this._wsUrl);\n        }\n    }\n\n    /**\n     * Claims the slot for `name` so the broker eagerly creates its provider\n     * state before any MCP client connects. Without it the broker only learns\n     * about a provider on its first real message, and a client connecting in\n     * between is told the provider is not connected.\n     */\n    private _announceProvider(name: string): void {\n        if (this._ws?.readyState !== WebSocket.OPEN) return;\n        this._ws.send(encodeRegisterEnvelope(name));\n    }\n\n    // ── Sending ─────────────────────────────────────────────────────────────\n\n    send(provider: string, data: string): void {\n        if (this._ws?.readyState !== WebSocket.OPEN) return;\n        this._ws.send(encodeEnvelope(provider, data));\n    }\n\n    // ── Connection lifecycle ────────────────────────────────────────────────\n\n    private _connect(): void {\n        const ws = new WebSocket(this._wsUrl);\n\n        // Held from construction, not from `onopen`: a transport registering\n        // while the handshake is still in flight must find this socket rather\n        // than open a second one. Readiness is decided by `readyState`, so a\n        // connecting socket is never mistaken for a usable one.\n        this._ws = ws;\n\n        ws.onopen = () => {\n            this._reconnectAttempts = 0;\n            // Announce all registered providers to the broker so it eagerly\n            // creates their slots before any MCP client connects.\n            for (const name of this._transports.keys()) {\n                this._announceProvider(name);\n            }\n            for (const transport of this._transports.values()) {\n                transport.onOpen?.();\n            }\n        };\n\n        ws.onerror = () => {\n            for (const transport of this._transports.values()) {\n                transport.onError?.(new Error(`MultiplexSocket: WebSocket error on ${this._wsUrl}`));\n            }\n        };\n\n        ws.onclose = () => {\n            this._ws = null;\n            for (const transport of this._transports.values()) {\n                transport.onClose?.();\n            }\n            if (!this._stopped) {\n                this._scheduleReconnect();\n            }\n        };\n\n        ws.onmessage = (event: MessageEvent<string>) => {\n            this._routeIncoming(event.data);\n        };\n    }\n\n    private _routeIncoming(raw: string): void {\n        const envelope = decodeEnvelope(raw);\n        if (!envelope) return; // malformed, drop silently\n\n        const transport = this._transports.get(envelope.provider);\n        if (!transport) return;\n\n        // A tunnel-level refusal (a rejected slot, an unavailable provider)\n        // carries no request id. Handing it to an MCP server would get it\n        // classified as an unknown notification and dropped without a word, so\n        // surface it as a transport error instead.\n        const payload = envelope.payload as { id?: unknown } | null;\n        if (payload !== null && (payload.id === null || payload.id === undefined)) {\n            const error = tunnelErrorOf(envelope.payload);\n            if (error) {\n                transport.onError?.(new Error(`Tunnel error ${error.code} on provider \"${envelope.provider}\": ${error.message}`));\n                return;\n            }\n        }\n\n        transport.onMessage?.(envelopeFrame(envelope));\n    }\n\n    private _scheduleReconnect(): void {\n        const base = 1_000;\n        const max = 30_000;\n        const jitter = 0.5 + Math.random() * 0.5;\n        const delay = Math.min(base * 2 ** this._reconnectAttempts, max) * jitter;\n\n        this._reconnectAttempts++;\n        setTimeout(() => {\n            if (!this._stopped) this._connect();\n        }, delay);\n    }\n}\n\n// ---------------------------------------------------------------------------\n// MultiplexTransport, per-server transport (public)\n// ---------------------------------------------------------------------------\n\n/**\n * A transport that multiplexes multiple MCP servers over a single shared\n * WebSocket connection using the envelope protocol `{ provider, payload }`.\n *\n * Use the static {@link create} factory to obtain an instance:\n * ```typescript\n * const t1 = MultiplexTransport.create(\"scene-1\", \"ws://localhost:3000/providers\");\n * const t2 = MultiplexTransport.create(\"scene-2\", \"ws://localhost:3000/providers\");\n * // t1 and t2 share a single WebSocket under the hood.\n * ```\n */\nexport class MultiplexTransport implements IMessageTransport {\n    private readonly _name: string;\n    private readonly _socket: MultiplexSocket;\n    private _registered = false;\n\n    onMessage: ((data: string) => void) | null = null;\n    onOpen: (() => void) | null = null;\n    onClose: (() => void) | null = null;\n    onError: ((error: Error) => void) | null = null;\n\n    constructor(name: string, socket: MultiplexSocket) {\n        this._name = name;\n        this._socket = socket;\n    }\n\n    /**\n     * Convenience factory: creates a {@link MultiplexTransport} backed by a\n     * shared {@link MultiplexSocket} for the given tunnel URL.\n     *\n     * Transports targeting the same `wsUrl` automatically share one WebSocket.\n     */\n    static create(name: string, wsUrl: string): MultiplexTransport {\n        return new MultiplexTransport(name, MultiplexSocket.getOrCreate(wsUrl));\n    }\n\n    get isOpen(): boolean {\n        return this._socket.isOpen;\n    }\n\n    /**\n     * Registers this transport with the shared socket.\n     *\n     * Safe to call multiple times, subsequent calls are no-ops.\n     */\n    activate(): void {\n        if (!this._registered) {\n            this._registered = true;\n            this._socket.register(this._name, this);\n        }\n    }\n\n    /**\n     * Opens the transport, the same way every other transport does.\n     *\n     * An alias of {@link activate} so callers never have to special-case this\n     * class: an MCP server or client just calls `connect()` on whatever\n     * transport it was handed.\n     */\n    connect(): void {\n        this.activate();\n    }\n\n    send(data: string): void {\n        this._socket.send(this._name, data);\n    }\n\n    close(): void {\n        if (this._registered) {\n            this._registered = false;\n            this._socket.unregister(this._name);\n        }\n    }\n}\n"]}

package/dist/protocol/index.d.ts

@@ -1 +1,87 @@
-export * from "./envelope";
+/**
+ * The CyanMycelium tunnel envelope protocol.
+ *
+ * A multiplexed tunnel socket carries traffic for several providers at once, so
+ * every JSON-RPC message is wrapped with the name of the provider slot it
+ * belongs to. Both ends of the tunnel encode and decode with the helpers here:
+ * the client transports that publish a provider, and the broker that routes
+ * between providers and MCP clients.
+ *
+ * This module is the single definition of that wire format. It is deliberately
+ * dependency-free and isomorphic, so the browser side and the Node broker share
+ * exactly one implementation rather than two that drift apart.
+ *
+ * Wire format:
+ * ```json
+ * { "provider": "scene-1", "payload": { "jsonrpc": "2.0", "id": 1, "result": {} } }
+ * ```
+ */
+/** One framed message on a multiplexed tunnel socket. */
+interface TunnelEnvelope {
+    /** Name of the provider slot this message belongs to. */
+    provider: string;
+    /** The JSON-RPC message itself, already parsed. */
+    payload: unknown;
+}
+/**
+ * Notification a client sends to claim a provider slot as soon as the tunnel
+ * opens, before any MCP client shows up.
+ *
+ * Without it the broker only discovers a provider name on its first real
+ * message, so an MCP client connecting in between is told the provider is not
+ * connected. It is a plain JSON-RPC notification, which any peer that does not
+ * recognize it ignores.
+ */
+declare const TUNNEL_REGISTER_METHOD = "notifications/register";
+/** JSON-RPC error codes the broker returns on the tunnel itself. */
+declare const TunnelErrorCodes: {
+    /** The slot is taken by another upstream, or the provider is not connected. */
+    readonly ProviderUnavailable: -32000;
+    /** The provider's credentials do not allow publishing on this slot. */
+    readonly RegistrationForbidden: -32001;
+};
+type TunnelErrorCode = (typeof TunnelErrorCodes)[keyof typeof TunnelErrorCodes];
+/** A JSON-RPC error as carried inside an envelope payload. */
+interface TunnelError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/**
+ * Wraps an already-serialized JSON-RPC frame for `provider`.
+ *
+ * @throws SyntaxError when `frame` is not valid JSON. Callers hold a frame they
+ *         just serialized, so a failure here is a bug rather than bad input.
+ */
+declare function encodeEnvelope(provider: string, frame: string): string;
+/** Wraps an already-parsed JSON-RPC message for `provider`. */
+declare function encodeEnvelopeMessage(provider: string, payload: unknown): string;
+/**
+ * Parses a raw tunnel frame.
+ *
+ * Returns `undefined` for anything malformed rather than throwing: a tunnel
+ * socket is a public surface, and a peer sending garbage must not take the
+ * receiver down. Both ends drop such frames silently.
+ */
+declare function decodeEnvelope(raw: string): TunnelEnvelope | undefined;
+/** Serializes an envelope's payload back into a plain JSON-RPC frame. */
+declare function envelopeFrame(envelope: TunnelEnvelope): string;
+/** Builds the registration notification that claims `provider`. */
+declare function encodeRegisterEnvelope(provider: string): string;
+/**
+ * Builds the error envelope the broker returns when it refuses a slot.
+ *
+ * The id is `null` because the refusal answers no particular request: it
+ * reacts to the registration itself.
+ */
+declare function encodeErrorEnvelope(provider: string, code: TunnelErrorCode | number, message: string): string;
+/**
+ * Reads the JSON-RPC error out of an envelope payload, when there is one.
+ *
+ * Lets the client side notice a refused registration instead of handing an
+ * `id: null` error frame to an MCP server, which would classify it as an
+ * unknown notification and drop it without a word.
+ */
+declare function tunnelErrorOf(payload: unknown): TunnelError | undefined;
+
+export { TUNNEL_REGISTER_METHOD, type TunnelEnvelope, type TunnelError, type TunnelErrorCode, TunnelErrorCodes, decodeEnvelope, encodeEnvelope, encodeEnvelopeMessage, encodeErrorEnvelope, encodeRegisterEnvelope, envelopeFrame, tunnelErrorOf };

package/dist/protocol/index.js

@@ -1,2 +1,48 @@
-export * from "./envelope";
+// src/protocol/envelope.ts
+var TUNNEL_REGISTER_METHOD = "notifications/register";
+var TunnelErrorCodes = {
+  /** The slot is taken by another upstream, or the provider is not connected. */
+  ProviderUnavailable: -32e3,
+  /** The provider's credentials do not allow publishing on this slot. */
+  RegistrationForbidden: -32001
+};
+function encodeEnvelope(provider, frame) {
+  return encodeEnvelopeMessage(provider, JSON.parse(frame));
+}
+function encodeEnvelopeMessage(provider, payload) {
+  const envelope = { provider, payload };
+  return JSON.stringify(envelope);
+}
+function decodeEnvelope(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+  const { provider, payload } = parsed;
+  if (typeof provider !== "string" || provider.length === 0 || payload === void 0) return void 0;
+  return { provider, payload };
+}
+function envelopeFrame(envelope) {
+  return JSON.stringify(envelope.payload);
+}
+function encodeRegisterEnvelope(provider) {
+  return encodeEnvelopeMessage(provider, { jsonrpc: "2.0", method: TUNNEL_REGISTER_METHOD });
+}
+function encodeErrorEnvelope(provider, code, message) {
+  return encodeEnvelopeMessage(provider, { jsonrpc: "2.0", id: null, error: { code, message } });
+}
+function tunnelErrorOf(payload) {
+  if (typeof payload !== "object" || payload === null) return void 0;
+  const { error } = payload;
+  if (typeof error !== "object" || error === null) return void 0;
+  const { code, message } = error;
+  if (typeof code !== "number" || typeof message !== "string") return void 0;
+  return error;
+}
+
+export { TUNNEL_REGISTER_METHOD, TunnelErrorCodes, decodeEnvelope, encodeEnvelope, encodeEnvelopeMessage, encodeErrorEnvelope, encodeRegisterEnvelope, envelopeFrame, tunnelErrorOf };
+//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/protocol/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/protocol/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}
+{"version":3,"sources":["../../src/protocol/envelope.ts"],"names":[],"mappings":";AAqCO,IAAM,sBAAA,GAAyB;AAG/B,IAAM,gBAAA,GAAmB;AAAA;AAAA,EAE5B,mBAAA,EAAqB,KAAA;AAAA;AAAA,EAGrB,qBAAA,EAAuB;AAC3B;AAiBO,SAAS,cAAA,CAAe,UAAkB,KAAA,EAAuB;AACpE,EAAA,OAAO,qBAAA,CAAsB,QAAA,EAAU,IAAA,CAAK,KAAA,CAAM,KAAK,CAAC,CAAA;AAC5D;AAGO,SAAS,qBAAA,CAAsB,UAAkB,OAAA,EAA0B;AAC9E,EAAA,MAAM,QAAA,GAA2B,EAAE,QAAA,EAAU,OAAA,EAAQ;AACrD,EAAA,OAAO,IAAA,CAAK,UAAU,QAAQ,CAAA;AAClC;AASO,SAAS,eAAe,GAAA,EAAyC;AACpE,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI;AACA,IAAA,MAAA,GAAS,IAAA,CAAK,MAAM,GAAG,CAAA;AAAA,EAC3B,CAAA,CAAA,MAAQ;AACJ,IAAA,OAAO,MAAA;AAAA,EACX;AACA,EAAA,IAAI,OAAO,WAAW,QAAA,IAAY,MAAA,KAAW,QAAQ,KAAA,CAAM,OAAA,CAAQ,MAAM,CAAA,EAAG,OAAO,MAAA;AAEnF,EAAA,MAAM,EAAE,QAAA,EAAU,OAAA,EAAQ,GAAI,MAAA;AAC9B,EAAA,IAAI,OAAO,aAAa,QAAA,IAAY,QAAA,CAAS,WAAW,CAAA,IAAK,OAAA,KAAY,QAAW,OAAO,MAAA;AAE3F,EAAA,OAAO,EAAE,UAAU,OAAA,EAAQ;AAC/B;AAGO,SAAS,cAAc,QAAA,EAAkC;AAC5D,EAAA,OAAO,IAAA,CAAK,SAAA,CAAU,QAAA,CAAS,OAAO,CAAA;AAC1C;AAGO,SAAS,uBAAuB,QAAA,EAA0B;AAC7D,EAAA,OAAO,sBAAsB,QAAA,EAAU,EAAE,SAAS,KAAA,EAAO,MAAA,EAAQ,wBAAwB,CAAA;AAC7F;AAQO,SAAS,mBAAA,CAAoB,QAAA,EAAkB,IAAA,EAAgC,OAAA,EAAyB;AAC3G,EAAA,OAAO,qBAAA,CAAsB,QAAA,EAAU,EAAE,OAAA,EAAS,KAAA,EAAO,EAAA,EAAI,IAAA,EAAM,KAAA,EAAO,EAAE,IAAA,EAAM,OAAA,EAAQ,EAAG,CAAA;AACjG;AASO,SAAS,cAAc,OAAA,EAA2C;AACrE,EAAA,IAAI,OAAO,OAAA,KAAY,QAAA,IAAY,OAAA,KAAY,MAAM,OAAO,MAAA;AAE5D,EAAA,MAAM,EAAE,OAAM,GAAI,OAAA;AAClB,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,KAAU,MAAM,OAAO,MAAA;AAExD,EAAA,MAAM,EAAE,IAAA,EAAM,OAAA,EAAQ,GAAI,KAAA;AAC1B,EAAA,IAAI,OAAO,IAAA,KAAS,QAAA,IAAY,OAAO,OAAA,KAAY,UAAU,OAAO,MAAA;AAEpE,EAAA,OAAO,KAAA;AACX","file":"index.js","sourcesContent":["/**\n * The CyanMycelium tunnel envelope protocol.\n *\n * A multiplexed tunnel socket carries traffic for several providers at once, so\n * every JSON-RPC message is wrapped with the name of the provider slot it\n * belongs to. Both ends of the tunnel encode and decode with the helpers here:\n * the client transports that publish a provider, and the broker that routes\n * between providers and MCP clients.\n *\n * This module is the single definition of that wire format. It is deliberately\n * dependency-free and isomorphic, so the browser side and the Node broker share\n * exactly one implementation rather than two that drift apart.\n *\n * Wire format:\n * ```json\n * { \"provider\": \"scene-1\", \"payload\": { \"jsonrpc\": \"2.0\", \"id\": 1, \"result\": {} } }\n * ```\n */\n\n/** One framed message on a multiplexed tunnel socket. */\nexport interface TunnelEnvelope {\n    /** Name of the provider slot this message belongs to. */\n    provider: string;\n\n    /** The JSON-RPC message itself, already parsed. */\n    payload: unknown;\n}\n\n/**\n * Notification a client sends to claim a provider slot as soon as the tunnel\n * opens, before any MCP client shows up.\n *\n * Without it the broker only discovers a provider name on its first real\n * message, so an MCP client connecting in between is told the provider is not\n * connected. It is a plain JSON-RPC notification, which any peer that does not\n * recognize it ignores.\n */\nexport const TUNNEL_REGISTER_METHOD = \"notifications/register\";\n\n/** JSON-RPC error codes the broker returns on the tunnel itself. */\nexport const TunnelErrorCodes = {\n    /** The slot is taken by another upstream, or the provider is not connected. */\n    ProviderUnavailable: -32000,\n\n    /** The provider's credentials do not allow publishing on this slot. */\n    RegistrationForbidden: -32001,\n} as const;\n\nexport type TunnelErrorCode = (typeof TunnelErrorCodes)[keyof typeof TunnelErrorCodes];\n\n/** A JSON-RPC error as carried inside an envelope payload. */\nexport interface TunnelError {\n    code: number;\n    message: string;\n    data?: unknown;\n}\n\n/**\n * Wraps an already-serialized JSON-RPC frame for `provider`.\n *\n * @throws SyntaxError when `frame` is not valid JSON. Callers hold a frame they\n *         just serialized, so a failure here is a bug rather than bad input.\n */\nexport function encodeEnvelope(provider: string, frame: string): string {\n    return encodeEnvelopeMessage(provider, JSON.parse(frame));\n}\n\n/** Wraps an already-parsed JSON-RPC message for `provider`. */\nexport function encodeEnvelopeMessage(provider: string, payload: unknown): string {\n    const envelope: TunnelEnvelope = { provider, payload };\n    return JSON.stringify(envelope);\n}\n\n/**\n * Parses a raw tunnel frame.\n *\n * Returns `undefined` for anything malformed rather than throwing: a tunnel\n * socket is a public surface, and a peer sending garbage must not take the\n * receiver down. Both ends drop such frames silently.\n */\nexport function decodeEnvelope(raw: string): TunnelEnvelope | undefined {\n    let parsed: unknown;\n    try {\n        parsed = JSON.parse(raw);\n    } catch {\n        return undefined;\n    }\n    if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) return undefined;\n\n    const { provider, payload } = parsed as Partial<TunnelEnvelope>;\n    if (typeof provider !== \"string\" || provider.length === 0 || payload === undefined) return undefined;\n\n    return { provider, payload };\n}\n\n/** Serializes an envelope's payload back into a plain JSON-RPC frame. */\nexport function envelopeFrame(envelope: TunnelEnvelope): string {\n    return JSON.stringify(envelope.payload);\n}\n\n/** Builds the registration notification that claims `provider`. */\nexport function encodeRegisterEnvelope(provider: string): string {\n    return encodeEnvelopeMessage(provider, { jsonrpc: \"2.0\", method: TUNNEL_REGISTER_METHOD });\n}\n\n/**\n * Builds the error envelope the broker returns when it refuses a slot.\n *\n * The id is `null` because the refusal answers no particular request: it\n * reacts to the registration itself.\n */\nexport function encodeErrorEnvelope(provider: string, code: TunnelErrorCode | number, message: string): string {\n    return encodeEnvelopeMessage(provider, { jsonrpc: \"2.0\", id: null, error: { code, message } });\n}\n\n/**\n * Reads the JSON-RPC error out of an envelope payload, when there is one.\n *\n * Lets the client side notice a refused registration instead of handing an\n * `id: null` error frame to an MCP server, which would classify it as an\n * unknown notification and drop it without a word.\n */\nexport function tunnelErrorOf(payload: unknown): TunnelError | undefined {\n    if (typeof payload !== \"object\" || payload === null) return undefined;\n\n    const { error } = payload as { error?: unknown };\n    if (typeof error !== \"object\" || error === null) return undefined;\n\n    const { code, message } = error as Partial<TunnelError>;\n    if (typeof code !== \"number\" || typeof message !== \"string\") return undefined;\n\n    return error as TunnelError;\n}\n"]}