super-dsh 0.1.6 → 0.1.9

package/superd-hub/dist/mesh-gateway.d.ts

@@ -0,0 +1,67 @@
+import type { MuxClientSocket } from './mux-client.js';
+import type { GatewayFace } from './targets.js';
+export type { MuxClientSocket } from './mux-client.js';
+/**
+ * The default ws seam: connect one `ws` WebSocket to `url` with `headers`
+ * riding the upgrade request (the pairing Cookie), presented as T1's
+ * {@link MuxClientSocket}.
+ *
+ * The adapter is crash-proof by construction (fix round 1):
+ *  - an `'error'` listener is ALWAYS registered: an unreachable peer
+ *    (ECONNREFUSED) or a rejected upgrade (non-101, e.g. a dead cookie's
+ *    HTTP 401) emits `'error'` with no listener of its own — an uncaught
+ *    exception that kills the hub process. The listener is a no-op: ws
+ *    guarantees `'close'` follows `'error'`, and the close path already
+ *    classifies (in-flight streams fail `gateway/socket-closed`) and retires
+ *    the connection for redial. WS-lane auth failure therefore classifies
+ *    as a socket cut post-fix — acceptable: the next POST-lane call is the
+ *    one that reports `gateway/auth-expired`.
+ *  - `ws` THROWS on sends made while CONNECTING, and its post-close send
+ *    bookkeeping can itself throw in teardown windows, so every send is
+ *    guarded: pre-open sends queue (flushed in order on 'open'), post-close
+ *    sends are swallowed — the stream is dead and the close path owns the
+ *    teardown. WS-level pings stay at the WS layer: `on('message')` fires
+ *    for text data frames only, so protocol-level ping/pong NEVER surfaces
+ *    as text.
+ */
+export declare function defaultWsFactory(url: string, headers: Record<string, string>): MuxClientSocket;
+/** Options for {@link createRemoteGateway}. */
+export interface RemoteGatewayOptions {
+    /** The peer hub origin (`http(s)://host[:port]`; the mux lane maps it to ws(s)). */
+    origin: string;
+    /** The remote agent's demux key (`?agent=` on both lanes; ignored by the native face). */
+    agentKey: string;
+    /** The machine's pairing cookie, read per call (the jar fronting `MachineRow.cookie`). */
+    cookie: () => string;
+    /** Fetch override (tests); defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Socket factory override (tests); defaults to {@link defaultWsFactory}. */
+    wsFactory?: (url: string, headers: Record<string, string>) => MuxClientSocket;
+    /** Which peer surface to address (see the header's face table): 'foreign' =
+     * the `/hub` family with the `?agent=` demux (default); 'native' = ctx0's
+     * own `/api` surface, no demux key — how a browser ON the peer consumes its
+     * native DSH. */
+    face?: 'foreign' | 'native';
+    /** Idle ms with zero live streams before the ws closes (default 30 s; test hook for short real timers). */
+    idleCloseMs?: number;
+}
+/** A wire-form gateway: a {@link GatewayFace} plus the carrier call shape and a hard close. */
+export interface RemoteGateway extends GatewayFace {
+    /**
+     * CarrierGatewayFace shape — the canonical order `worldMuxOf` calls with
+     * (`(endpoint, payload, uplink, peer, signal, control)`); the uplink is
+     * bridged into the wire upstream lane.
+     */
+    openWireStream(endpoint: string, payload: unknown, uplink: AsyncIterable<unknown> | Iterable<unknown>, peer: undefined, signal: AbortSignal, control: AbortController): AsyncIterable<unknown>;
+    /** GatewayFace shape — no uplink lane; the stream's uplink half-closes immediately. */
+    openWireStream(endpoint: string, payload: unknown, signal: AbortSignal): AsyncIterable<unknown>;
+    /** Hard-close the shared connection now (machine unpair); in-flight streams fail `gateway/disposed`. */
+    dispose(): void;
+}
+/**
+ * Build one remote agent's wire gateway toward a paired hub's `/hub` family.
+ * @param options - see {@link RemoteGatewayOptions}.
+ * @returns the {@link RemoteGateway} (a GatewayFace; register it with
+ * `registerForeignTarget` — callers cannot tell it from a local world gateway).
+ */
+export declare function createRemoteGateway(options: RemoteGatewayOptions): RemoteGateway;

package/superd-hub/dist/mesh-gateway.js

@@ -0,0 +1,408 @@
+/**
+ * RemoteGatewayFace (machine-mesh P2 Task 2) — the wire form of a
+ * {@link GatewayFace}: one paired remote agent's dispatch/stream surface,
+ * reached over the PEER hub exactly as that hub would serve it locally —
+ * on ONE of two surfaces, selected by {@link RemoteGatewayOptions.face}:
+ *
+ *   foreign (default) — the `/hub` family (hub-route is the server half):
+ *     dispatchRpc     POST <origin>/hub/api?agent=<agentKey>
+ *     openWireStream  WS   <origin ws(s)>/hub/api/remote.mux?agent=<agentKey>
+ *   native — ctx0's OWN envelope+mux surface, exactly how a browser ON the
+ *     peer consumes its native DSH (NO demux key anywhere — the peer's
+ *     native agent row federates as `key:'native'` with a minted a6, and the
+ *     `/hub` family would 404 it as foreign-only):
+ *     dispatchRpc     POST <origin>/api/<endpoint>   (endpoint in the PATH)
+ *     openWireStream  WS   <origin ws(s)>/api/remote.mux
+ *
+ *   The native unary URL mirrors upstream byte-exactly: the client builds
+ *   `` `${channel}/${endpoint}`.slice(1) `` and the server decodes with
+ *   `endpointFromPath` (a raw pathname slice, NO decodeURIComponent) — so the
+ *   endpoint rides the path RAW, never percent-encoded (an encoded path would
+ *   fail the server's ENDPOINT_SEGMENT_PATTERN; segments are already
+ *   restricted to `[A-Za-z0-9_$.-]`, so nothing ever needs encoding). A bare
+ *   `/api` carries no endpoint → 404.
+ *
+ * Everything else (envelope shape, cookie, Result verbatim, error taxonomy,
+ * connection lifecycle) is face-independent.
+ * Every call rides the machine's pairing cookie ({@link RemoteGatewayOptions.cookie},
+ * the per-machine jar fronting the persisted `MachineRow.cookie`).
+ *
+ * ## Mux connection lifecycle — ONE per gateway
+ * Lazy (dialed by the first stream), SHARED by every concurrent stream
+ * (per-call logical streams multiplex over it, T1 counter ids), IDLE-CLOSED
+ * {@link DEFAULT_IDLE_CLOSE_MS} after the last stream retires (the timer is
+ * `unref`d), and REDIALED transparently after any transport cut: on socket
+ * close the MuxClient fails every in-flight stream with
+ * `gateway/socket-closed`, the dead connection is dropped, and the next call
+ * dials fresh. The wire stream itself opens lazily on the returned iterable's
+ * first read — an iterable never iterated holds no connection and no stream.
+ *
+ * ## Heartbeat ruling (carried from the T1 review, controller ruling)
+ * The remote's heartbeat is WS-LEVEL ping/pong (WorldMuxServer pings its
+ * clients and terminates after two missed pongs); `ws` auto-answers those
+ * pings at the protocol layer and they NEVER surface as text (`on('message')`
+ * fires for data frames only — surfacing them would 1008-close the socket,
+ * since the server's parser has no ping case). Accordingly the MuxClient is
+ * configured with {@link HEARTBEAT_OFF_MS} (6 h), putting its JSON-text
+ * silence watchdog effectively OFF — an idle-but-alive connection is never
+ * torn down by the client — and liveness rides WS events alone: a dead peer
+ * surfaces as ws `close` → in-flight streams fail, the next call reconnects.
+ *
+ * ## Call shapes (the carrier lesson: canonical parameter order)
+ * `openWireStream` accepts BOTH faces with one runtime dispatch (an uplink
+ * iterable is recognizably not an AbortSignal):
+ *  - GatewayFace: `(endpoint, payload, signal)` — the face `targets.ts`
+ *    freezes. It carries NO uplink lane, so the stream's uplink is
+ *    half-closed immediately (`end` right after `open`): a server handler
+ *    reading uplink sees EOF instead of hanging.
+ *  - CarrierGatewayFace: `(endpoint, payload, uplink, peer, signal, control)`
+ *    — the exact order `worldMuxOf` calls with. The uplink is bridged into
+ *    the wire upstream lane with the T1 channel idiom
+ *    `for await (const v of uplink) await upstream.next(v); handle.end()`
+ *    (read-one-send-one, zero buffering; a `done` read — dead stream — stops
+ *    the pump quietly). `control` is accepted for shape
+ *    parity only — cancellation rides the mux `cancel` frame, which is what
+ *    actually stops the server-side stream.
+ *
+ * ## Error taxonomy (every throw is a plain `{code,message}` body — the
+ * brief-pinned shape; `wireErrorOf` normalizes it onto the wire downstream)
+ *  - `gateway/unreachable` — network failure, or a non-200 answer that is
+ *    not 401 (the status rides the message).
+ *  - `gateway/auth-expired` — 401 anywhere: the MACHINE-LEVEL classification
+ *    (the pairing cookie is dead) the roster downgrade consumes; never a
+ *    per-request retry.
+ *  - `gateway/bad-response` — 200 but the body is not a `server-response`
+ *    envelope for the rpc we sent.
+ *  - `gateway/aborted` — the caller's AbortSignal fired.
+ *  - stream cuts — T1 `MuxClientError` codes pass through verbatim:
+ *    `gateway/socket-closed` (peer cut / transport died),
+ *    `gateway/disposed`, `gateway/protocol`; `gateway/heartbeat-silence` is
+ *    dormant by the heartbeat ruling above. A REMOTE error frame keeps the
+ *    remote's own code/message/details.
+ *
+ * ## Payload rule (T1 carry)
+ * `undefined` payloads are coerced to `null` on both lanes before the wire
+ * (T1's serializer drops the key for `undefined`, which the server's parser
+ * rejects); wire streamIds are T1's own stringified counters.
+ */
+import { createRequire } from 'node:module';
+import { MuxClient } from './mux-client.js';
+/** Text-watchdog-off horizon (see the heartbeat ruling in the header). */
+const HEARTBEAT_OFF_MS = 6 * 60 * 60 * 1000;
+/** Idle window before the shared ws closes with zero live streams. */
+const DEFAULT_IDLE_CLOSE_MS = 30_000;
+/** Specifier widened on purpose: `ws` is a runtime peer, not a typed dep. */
+const WS_MODULE = 'ws';
+let wsConstructor;
+/** Synchronously load the ws constructor once (createRequire — rpc.ts precedent). */
+function loadWs() {
+    if (wsConstructor !== undefined)
+        return wsConstructor;
+    const require = createRequire(import.meta.url);
+    const mod = require(WS_MODULE);
+    const boxed = mod;
+    wsConstructor = (typeof mod === 'function' ? mod : boxed.default);
+    return wsConstructor;
+}
+/**
+ * The default ws seam: connect one `ws` WebSocket to `url` with `headers`
+ * riding the upgrade request (the pairing Cookie), presented as T1's
+ * {@link MuxClientSocket}.
+ *
+ * The adapter is crash-proof by construction (fix round 1):
+ *  - an `'error'` listener is ALWAYS registered: an unreachable peer
+ *    (ECONNREFUSED) or a rejected upgrade (non-101, e.g. a dead cookie's
+ *    HTTP 401) emits `'error'` with no listener of its own — an uncaught
+ *    exception that kills the hub process. The listener is a no-op: ws
+ *    guarantees `'close'` follows `'error'`, and the close path already
+ *    classifies (in-flight streams fail `gateway/socket-closed`) and retires
+ *    the connection for redial. WS-lane auth failure therefore classifies
+ *    as a socket cut post-fix — acceptable: the next POST-lane call is the
+ *    one that reports `gateway/auth-expired`.
+ *  - `ws` THROWS on sends made while CONNECTING, and its post-close send
+ *    bookkeeping can itself throw in teardown windows, so every send is
+ *    guarded: pre-open sends queue (flushed in order on 'open'), post-close
+ *    sends are swallowed — the stream is dead and the close path owns the
+ *    teardown. WS-level pings stay at the WS layer: `on('message')` fires
+ *    for text data frames only, so protocol-level ping/pong NEVER surfaces
+ *    as text.
+ */
+export function defaultWsFactory(url, headers) {
+    const WebSocketCtor = loadWs();
+    const socket = new WebSocketCtor(url, { headers });
+    socket.on('error', () => { }); // crash guard: 'close' (and its classification) always follows
+    let open = false;
+    let closed = false;
+    const pending = [];
+    socket.on('open', () => {
+        open = true;
+        for (const data of pending.splice(0))
+            socket.send(data);
+    });
+    socket.on('close', () => {
+        closed = true;
+        open = false;
+        pending.length = 0;
+    });
+    return {
+        send: (data) => {
+            if (closed)
+                return;
+            if (!open) {
+                pending.push(data);
+                return;
+            }
+            try {
+                socket.send(data);
+            }
+            catch {
+                // CONNECTING/CLOSING race or sendAfterClose bookkeeping — the close
+                // path owns teardown; a lost frame on a dying socket changes nothing.
+            }
+        },
+        onMessage: (cb) => {
+            socket.on('message', (data) => { cb(String(data)); });
+        },
+        onClose: (cb) => { socket.on('close', () => { cb(); }); },
+        close: () => { socket.close(); },
+    };
+}
+/** The ws(s) URL of the peer's mux lane (foreign: the `/hub` family with
+ * the demux key; native: ctx0's own surface, no query). */
+function muxUrlOf(origin, agentKey, face) {
+    const url = new URL(origin);
+    url.protocol = url.protocol === 'https:' || url.protocol === 'wss:' ? 'wss:' : 'ws:';
+    url.pathname = `${url.pathname.replace(/\/+$/, '')}${face === 'native' ? '/api/remote.mux' : '/hub/api/remote.mux'}`;
+    if (face === 'foreign')
+        url.search = `agent=${encodeURIComponent(agentKey)}`;
+    return url.toString();
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** An uplink lane is recognizable at the seam: iterables (sync or async —
+ * `for await` bridges sync ones) are never AbortSignals. */
+function isUplinkLane(value) {
+    return typeof value === 'object' && value !== null
+        && (Symbol.asyncIterator in value || Symbol.iterator in value);
+}
+/** One gateway/* failure body — the brief-pinned thrown shape. */
+function wireFail(code, message) {
+    return { code, message };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+class RemoteGatewayImpl {
+    origin;
+    agentKey;
+    cookieFn;
+    fetchImpl;
+    wsFactory;
+    idleCloseMs;
+    face;
+    muxUrl;
+    nextRpcId = 1;
+    connection;
+    idleTimer;
+    constructor(options) {
+        this.origin = options.origin;
+        this.agentKey = options.agentKey;
+        this.cookieFn = options.cookie;
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.wsFactory = options.wsFactory ?? defaultWsFactory;
+        this.idleCloseMs = options.idleCloseMs ?? DEFAULT_IDLE_CLOSE_MS;
+        this.face = options.face ?? 'foreign';
+        this.muxUrl = muxUrlOf(options.origin, options.agentKey, this.face);
+    }
+    async dispatchRpc(endpoint, payload, signal) {
+        // Foreign: the /hub family with the demux key. Native: ctx0's own
+        // surface with the endpoint in the PATH, raw (see the header's URL-truth
+        // note) — exactly the URL a browser on the peer posts.
+        const url = this.face === 'native'
+            ? `${this.origin}/api/${endpoint}`
+            : `${this.origin}/hub/api?agent=${encodeURIComponent(this.agentKey)}`;
+        const rpcId = String(this.nextRpcId);
+        this.nextRpcId += 1;
+        const body = JSON.stringify({
+            type: 'client-request',
+            rpcId,
+            method: endpoint,
+            payload: payload === undefined ? null : payload, // the payload rule: never undefined
+        });
+        const cookie = this.cookieFn();
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    ...(cookie === '' ? {} : { cookie }),
+                },
+                body,
+                signal,
+            });
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw wireFail('gateway/aborted', `mesh-gateway: ${endpoint} aborted`);
+            throw wireFail('gateway/unreachable', `mesh-gateway: POST ${url} failed — ${messageOf(error)}`);
+        }
+        if (response.status === 401) {
+            throw wireFail('gateway/auth-expired', `mesh-gateway: ${endpoint} answered 401 — the pairing cookie is expired (machine-level downgrade material)`);
+        }
+        if (response.status !== 200) {
+            throw wireFail('gateway/unreachable', `mesh-gateway: ${endpoint} answered unexpected status ${response.status} from ${this.origin}`);
+        }
+        let text;
+        try {
+            text = await response.text();
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw wireFail('gateway/aborted', `mesh-gateway: ${endpoint} aborted mid-body`);
+            throw wireFail('gateway/unreachable', `mesh-gateway: reading ${endpoint} response failed — ${messageOf(error)}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw wireFail('gateway/bad-response', `mesh-gateway: ${endpoint} response is not JSON`);
+        }
+        if (!isRecord(parsed) || parsed['type'] !== 'server-response' || parsed['rpcId'] !== rpcId || !('result' in parsed)) {
+            throw wireFail('gateway/bad-response', `mesh-gateway: ${endpoint} response is not a server-response envelope for rpc ${rpcId}`);
+        }
+        // The Result ({ok,value} | {ok:false,error}) is DATA: returned verbatim,
+        // never unwrapped or thrown — the caller classifies.
+        return parsed['result'];
+    }
+    openWireStream(endpoint, payload, uplinkOrSignal, _peer, signal, _control) {
+        const carrierShape = isUplinkLane(uplinkOrSignal);
+        const uplink = carrierShape ? uplinkOrSignal : undefined;
+        const abortSignal = carrierShape ? signal : uplinkOrSignal;
+        const gateway = this;
+        // The wire stream opens on the first read — an iterable never iterated
+        // dials nothing and leaks nothing.
+        async function* downlink() {
+            if (abortSignal?.aborted)
+                return;
+            const conn = gateway.acquireConnection();
+            let handle;
+            try {
+                handle = conn.client.openStream(endpoint, payload === undefined ? null : payload);
+            }
+            catch (error) {
+                gateway.releaseConnection(conn);
+                throw error;
+            }
+            if (uplink === undefined) {
+                // The GatewayFace shape carries no uplink lane: half-close at once so
+                // a server handler reading uplink sees EOF instead of hanging.
+                handle.end();
+            }
+            else {
+                // T1 ruling idiom: one read of the channel iterator sends one item
+                // frame; empty/errored uplink settles to end/cancel. A `done` read
+                // means the stream died (socket cut / cancel) — stop pumping quietly
+                // instead of draining the source against a dead wire.
+                const push = handle.upstream[Symbol.asyncIterator]();
+                void (async () => {
+                    try {
+                        for await (const value of uplink) {
+                            if ((await push.next(value)).done)
+                                return;
+                        }
+                    }
+                    catch {
+                        handle.cancel();
+                        return;
+                    }
+                    handle.end();
+                })();
+            }
+            const onAbort = () => { handle.cancel(); };
+            abortSignal?.addEventListener('abort', onAbort, { once: true });
+            try {
+                yield* handle.items;
+            }
+            finally {
+                abortSignal?.removeEventListener('abort', onAbort);
+                handle.cancel(); // no-op when the stream settled; cancels the wire on early exit
+                gateway.releaseConnection(conn);
+            }
+        }
+        return downlink();
+    }
+    dispose() {
+        this.clearIdleTimer();
+        const conn = this.connection;
+        this.connection = undefined;
+        conn?.client.dispose();
+    }
+    /** Take a live-stream slot on the shared connection, dialing it if needed. */
+    acquireConnection() {
+        this.clearIdleTimer();
+        let conn = this.connection;
+        if (conn === undefined) {
+            conn = this.connect();
+            this.connection = conn;
+        }
+        conn.live += 1;
+        return conn;
+    }
+    /** Drop a live-stream slot; the last one out arms the idle-close timer. */
+    releaseConnection(conn) {
+        conn.live = Math.max(0, conn.live - 1);
+        if (conn.live > 0 || this.connection !== conn || this.idleTimer !== undefined)
+            return;
+        const timer = setTimeout(() => {
+            this.idleTimer = undefined;
+            if (this.connection === conn && conn.live === 0) {
+                this.connection = undefined;
+                conn.client.dispose();
+            }
+        }, this.idleCloseMs);
+        timer.unref();
+        this.idleTimer = timer;
+    }
+    /** Dial the mux ws and wrap it so a transport cut retires the connection. */
+    connect() {
+        const cookie = this.cookieFn();
+        const headers = cookie === '' ? {} : { cookie };
+        const socket = this.wsFactory(this.muxUrl, headers);
+        let conn;
+        const wrapped = {
+            send: (data) => { socket.send(data); },
+            onMessage: (cb) => { socket.onMessage(cb); },
+            onClose: (cb) => {
+                socket.onClose(() => {
+                    cb(); // the MuxClient tears its streams down first (T1 contract) …
+                    if (this.connection === conn) {
+                        this.connection = undefined; // … then the dead connection is dropped: the next call redials
+                        this.clearIdleTimer();
+                    }
+                });
+            },
+            close: () => { socket.close(); },
+        };
+        const client = new MuxClient(wrapped, { heartbeatIntervalMs: HEARTBEAT_OFF_MS });
+        conn = { client, live: 0 };
+        return conn;
+    }
+    clearIdleTimer() {
+        if (this.idleTimer === undefined)
+            return;
+        clearTimeout(this.idleTimer);
+        this.idleTimer = undefined;
+    }
+}
+/**
+ * Build one remote agent's wire gateway toward a paired hub's `/hub` family.
+ * @param options - see {@link RemoteGatewayOptions}.
+ * @returns the {@link RemoteGateway} (a GatewayFace; register it with
+ * `registerForeignTarget` — callers cannot tell it from a local world gateway).
+ */
+export function createRemoteGateway(options) {
+    return new RemoteGatewayImpl(options);
+}