@ggui-ai/iframe-runtime 0.1.0-rc.1

package/dist/registry-subscribe.js

@@ -0,0 +1,319 @@
+/**
+ * Registry-driven subscribe orchestration — owns the renderer's
+ * "I have a parsed bootstrap, now drive the live-channel handshake to
+ * first ack" flow on top of `ChannelRegistry.bind()`.
+ *
+ * Replaces the pre-B3b `subscribe()` helper + the `RendererWebSocketManager`
+ * lifecycle class. The two retired modules paired a hand-rolled WS
+ * manager with a separate handshake helper; B3b unifies both behind
+ * the `@ggui-ai/channel-client` library so every WS frame type (push,
+ * data, props_update, drain_ack, channel_payload, channel_error,
+ * system, feedback) flows through one registry-owned transport.
+ *
+ * Composition:
+ *
+ *   1. Caller-supplied `ChannelRegistry` (populated by `runtime.ts`'s
+ *      triad-wiring `setup()` with every handler the iframe routes).
+ *   2. Compose the WS URL with the bootstrap token threaded as a
+ *      `?bootstrap=<encoded>` query string (mirrors the pre-B3b
+ *      `composeWsUrl` shape so server-side upgrade-path auth keeps
+ *      working).
+ *   3. Register `ack` + `error` handlers on the registry BEFORE bind
+ *      so the first inbound frame after socket open hits the
+ *      handshake-resolver closure.
+ *   4. Call `registry.bind({bootstrap, onStatusChange})` and capture
+ *      the returned typed `WsTransportHandle` (narrow on
+ *      `handle.kind === 'ws'`).
+ *
+ * The handshake resolves on the first `ack` (with the symmetric
+ * `CLIENT_SUPPORTED_VERSIONS` check) or rejects on:
+ *   - `UpgradeRequiredError` (pre-ack `error` with code UPGRADE_REQUIRED
+ *     OR ack carrying an unrecognised `serverVersion`)
+ *   - Plain `Error(payload.message)` (other pre-ack errors — typed
+ *     ProtocolError emitted in parallel)
+ *   - Plain `Error('subscribe-failed: transport went to failed state
+ *     before ack')` when the transport status transitions to `'failed'`
+ *     pre-ack.
+ *
+ * No timeout is enforced here — the runtime owns the visible "still
+ * connecting…" UX and decides when to give up. Surface this module is
+ * deliberately thin so the runtime can layer policy on top.
+ */
+import { CLIENT_SUPPORTED_VERSIONS, UPGRADE_REQUIRED } from '@ggui-ai/protocol/version';
+import { UpgradeRequiredError } from '@ggui-ai/protocol/errors/version-mismatch';
+import { fromAuthFailure, fromTransportFailure, fromUpgradeRequired, } from './protocol-error.js';
+/**
+ * Compose the WebSocket URL with the bootstrap token threaded as a
+ * query parameter. Servers that authenticate the upgrade path read
+ * the token from here; the same value also rides inside the subscribe
+ * payload so server-side handlers that consume credentials on the
+ * subscribe frame see it too.
+ */
+function composeWsUrl(base, bootstrap) {
+    const sep = base.indexOf('?') >= 0 ? '&' : '?';
+    return `${base}${sep}bootstrap=${encodeURIComponent(bootstrap)}`;
+}
+/**
+ * Lift a server-emitted `{type:'error'}` frame into the appropriate
+ * Error subclass. Returns `null` for a frame whose code is not
+ * UPGRADE_REQUIRED — the caller decides how to surface non-upgrade
+ * errors (typically a plain `Error` with the server's message).
+ */
+function liftUpgradeRequiredFromError(payload) {
+    if (payload.code !== UPGRADE_REQUIRED)
+        return null;
+    const details = payload.details;
+    let observedVersion;
+    if (details !== null &&
+        typeof details === 'object' &&
+        !Array.isArray(details) &&
+        typeof details.serverVersion === 'string') {
+        observedVersion = details.serverVersion;
+    }
+    return new UpgradeRequiredError({
+        ...(observedVersion !== undefined ? { observedVersion } : {}),
+        acceptedVersions: CLIENT_SUPPORTED_VERSIONS,
+        observedBy: 'server',
+    });
+}
+/**
+ * Collapse the `UpgradeRequiredError.observedVersion` variant
+ * (`string | readonly string[] | undefined`) onto the single string
+ * shape that `SchemaVersionMismatchEvent.observedVersion` carries.
+ * Undefined falls back to the sentinel `'unknown'` so hosts always
+ * have a rendered value.
+ */
+function normalizeObservedVersion(value) {
+    if (value === undefined)
+        return 'unknown';
+    if (typeof value === 'string')
+        return value;
+    return value.join(', ');
+}
+/**
+ * Map a pre-ack `error` frame onto a non-UPGRADE_REQUIRED ProtocolError.
+ * `SESSION_NOT_FOUND` / `AUTH_REJECTED` → `'auth'`; every other code
+ * → `'protocol'` with the extensibly-closed tail carrying the wire code
+ * verbatim.
+ */
+function classifyPreAckError(payload) {
+    if (payload.code === 'SESSION_NOT_FOUND' || payload.code === 'AUTH_REJECTED') {
+        return fromAuthFailure(payload.code, payload.message);
+    }
+    if (payload.code === 'TOKEN_EXPIRED') {
+        return fromAuthFailure('TOKEN_EXPIRED', payload.message);
+    }
+    return {
+        kind: 'protocol',
+        code: payload.code,
+        ...(payload.message !== undefined ? { message: payload.message } : {}),
+        ...(payload.details !== undefined ? { details: payload.details } : {}),
+    };
+}
+/**
+ * Open the WS via the registry, send subscribe (composed by the
+ * registry's `subscribeFrameBuilder`), await the first `ack`. Resolves
+ * with `{ handle, ack }` on success; rejects with
+ * `UpgradeRequiredError` on a version-handshake failure (either side);
+ * rejects with a plain `Error` on any other server-emitted pre-ack
+ * error.
+ *
+ * Once the promise settles, subsequent server frames flow through the
+ * registered channel handlers (props_update, drain_ack, push, data,
+ * etc.) — there is no longer a separate `onMessage` callback fanning
+ * frames across multiple handler chains.
+ */
+export function connectViaRegistry(opts) {
+    return new Promise((resolve, reject) => {
+        let receivedAck = false;
+        let settled = false;
+        let seenOpen = false;
+        const emitProtocolError = opts.onProtocolError ?? (() => { });
+        const emitObserve = opts.onObserve ?? (() => { });
+        // Defense-in-depth — live mode requires both wsUrl + token. The
+        // caller validates this before invoking; reject early with a
+        // typed transport failure if either is missing.
+        const wsUrl = opts.bootstrap.wsUrl;
+        const token = opts.bootstrap.token;
+        if (typeof wsUrl !== 'string' || wsUrl.length === 0 ||
+            typeof token !== 'string' || token.length === 0) {
+            const err = new Error('connectViaRegistry: bootstrap missing wsUrl/token — live-mode required');
+            emitProtocolError(fromTransportFailure('DISCONNECTED', false, err.message));
+            reject(err);
+            return;
+        }
+        // Register `ack` + `error` handlers BEFORE bind so the first
+        // inbound frame after socket open hits the handshake-resolver
+        // closure. The registry guards against double-registration; the
+        // caller must NOT have pre-registered handlers of these types.
+        opts.registry.register({
+            type: 'ack',
+            onMessage: (payload) => {
+                const ack = payload;
+                // Post-handshake ack — the WS reconnected and the server
+                // re-sent the subscribe ack with a fresh `stack` snapshot.
+                // Fan it onto the caller's resubscribe callback so the
+                // runtime can reapply the authoritative stack (a push or
+                // update that landed during the WS dropout window now
+                // restores). Skip the version handshake / settle bookkeeping
+                // — that already fired on the original ack.
+                if (settled) {
+                    opts.onResubscribeAck?.(ack);
+                    return;
+                }
+                const serverVersion = ack.serverVersion;
+                if (typeof serverVersion === 'string' &&
+                    !CLIENT_SUPPORTED_VERSIONS.includes(serverVersion)) {
+                    settled = true;
+                    receivedAck = true;
+                    const upgradeErr = new UpgradeRequiredError({
+                        observedVersion: serverVersion,
+                        acceptedVersions: CLIENT_SUPPORTED_VERSIONS,
+                        observedBy: 'client',
+                    });
+                    emitProtocolError(fromUpgradeRequired(upgradeErr));
+                    emitObserve({
+                        kind: 'schema-version-mismatch',
+                        observedVersion: serverVersion,
+                        acceptedVersions: CLIENT_SUPPORTED_VERSIONS,
+                        observedBy: 'client',
+                    });
+                    reject(upgradeErr);
+                    return;
+                }
+                settled = true;
+                receivedAck = true;
+                // Resolution is deferred — the typed handle is set by the
+                // `bind()` resolution path below. We just record the ack and
+                // let the bind continuation finish wiring.
+                ackResolverState.payload = ack;
+                ackResolverState.onAck?.();
+            },
+        });
+        opts.registry.register({
+            type: 'error',
+            onMessage: (payload) => {
+                // Post-ack error frames are NOT handled here — the runtime
+                // doesn't currently route post-ack `error` frames through a
+                // registered handler (they used to surface via the legacy
+                // `onMessage` callback; B3b drops that channel since
+                // post-ack errors are rare + the host inspector logs them
+                // through the typed ProtocolError emitter).
+                if (settled)
+                    return;
+                const errPayload = payload;
+                const upgrade = liftUpgradeRequiredFromError(errPayload);
+                if (upgrade !== null) {
+                    settled = true;
+                    emitProtocolError(fromUpgradeRequired(upgrade));
+                    emitObserve({
+                        kind: 'schema-version-mismatch',
+                        observedVersion: normalizeObservedVersion(upgrade.observedVersion),
+                        acceptedVersions: upgrade.acceptedVersions,
+                        observedBy: 'server',
+                    });
+                    reject(upgrade);
+                    return;
+                }
+                settled = true;
+                emitProtocolError(classifyPreAckError(errPayload));
+                reject(new Error(errPayload.message ?? errPayload.code));
+            },
+        });
+        // Captured-state closure so the ack handler can hand the resolved
+        // payload to the bind continuation without sharing a mutable
+        // local with the outer Promise body.
+        const ackResolverState = { payload: null, onAck: null };
+        const mappedStatusCallback = (status) => {
+            // `connecting` is the initial state from WSTransport — first
+            // surfaced concurrent with `start()`. Subsequent `connecting`
+            // transitions mean the reconnect ladder is firing (after a
+            // prior `open` → `closed`).
+            if (status === 'connecting') {
+                if (!seenOpen) {
+                    opts.onStatusChange('connecting');
+                }
+                else {
+                    opts.onStatusChange('reconnecting');
+                    emitObserve({
+                        kind: 'subscribe-failed',
+                        reason: 'transport-reconnecting',
+                        message: 'renderer WebSocket dropped; reconnect ladder running',
+                    });
+                }
+                return;
+            }
+            if (status === 'open') {
+                seenOpen = true;
+                opts.onStatusChange('connected');
+                return;
+            }
+            if (status === 'closed') {
+                // Graceful close — propagate as `disconnected` so the status
+                // DOM reflects the drop. WSTransport will fire `connecting`
+                // again on its reconnect path; we don't pre-empt.
+                opts.onStatusChange('disconnected');
+                return;
+            }
+            // `failed` — terminal. Map to `disconnected` for the
+            // protocol-level status; reject the handshake if we never
+            // saw an ack so callers don't hang on a dead transport.
+            opts.onStatusChange('disconnected');
+            emitProtocolError(fromTransportFailure('DISCONNECTED', false, 'transport went to failed state'));
+            if (!settled && !receivedAck) {
+                settled = true;
+                reject(new Error('connectViaRegistry: transport went to failed state before ack'));
+            }
+        };
+        const composedUrl = composeWsUrl(wsUrl, token);
+        // `bind()` selects the transport (WS for wsUrl+token bootstraps;
+        // the registry's selection logic narrows on bootstrap shape) and
+        // starts it. We override `bootstrap.wsUrl` with the composed URL
+        // so the registry's WS transport gets the token-threaded variant.
+        void opts.registry
+            .bind({
+            bootstrap: {
+                wsUrl: composedUrl,
+                token,
+                sessionId: opts.bootstrap.sessionId,
+                appId: opts.bootstrap.appId,
+            },
+            onStatusChange: mappedStatusCallback,
+        })
+            .then((bound) => {
+            // bound is `AnyTransportHandle`. Composed URL + token means
+            // the registry selected WSTransport — `kind === 'ws'` is the
+            // structural invariant. Narrow defensively.
+            if (bound.kind !== 'ws') {
+                if (!settled) {
+                    settled = true;
+                    reject(new Error("connectViaRegistry: registry returned non-ws transport despite wsUrl+token bootstrap"));
+                }
+                return;
+            }
+            const wsHandle = bound;
+            // If we already received the ack while bind was resolving,
+            // settle the outer Promise now.
+            if (ackResolverState.payload !== null) {
+                resolve({ handle: wsHandle, ack: ackResolverState.payload });
+                return;
+            }
+            // Otherwise wire the ack handler's continuation so it
+            // resolves with the handle when the first ack lands.
+            ackResolverState.onAck = () => {
+                const ack = ackResolverState.payload;
+                if (ack !== null) {
+                    resolve({ handle: wsHandle, ack });
+                }
+            };
+        })
+            .catch((err) => {
+            if (settled)
+                return;
+            settled = true;
+            const message = err instanceof Error ? err.message : String(err);
+            emitProtocolError(fromTransportFailure('DISCONNECTED', false, message));
+            reject(err instanceof Error ? err : new Error(message));
+        });
+    });
+}