@zhin.js/host-http 1.1.17 → 1.2.1

package/lib/bridge/bridged-host.js

@@ -0,0 +1,497 @@
+/**
+ * Instance side of the HTTP bridge (ADR 0054 §2 / §3): `BridgedHttpHost` implements the same
+ * {@link HttpHost} surface as the in-process Node server, but serves requests that the gateway
+ * forwards over the control channel. Routing, CORS, generation admission and Console
+ * authorization are the shared router's (`createHttpRouter`), running in `forwarded`
+ * authentication mode: the gateway authenticated the caller and the principal travels with the
+ * request; the router still authorizes it against the Console permission map.
+ *
+ * Console accounts live in the gateway (ADR 0054 §7): the instance never resolves a bearer. Its
+ * token registry is closed (no bootstrap token, no open Host): every grant arrives as the
+ * forwarded principal. Audit entries the instance writes go to the gateway (`audit`), the plugin
+ * permission catalog of the current generation is reported (`catalog`), and `principal-revoked`
+ * closes that user's live exchanges and sockets.
+ *
+ * Nothing here imports `node:http` or `ws`.
+ */
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import { generationAdmissionBinder, } from '@zhin.js/plugin-runtime';
+import { createHttpRouter, } from '../http-host.js';
+import { TokenRegistry } from '../token-registry.js';
+import { httpHostAddressProvider } from '../addresses.js';
+import { CreditGate, InboundBody, ownBytes, pumpBody } from './flow.js';
+import { DEFAULT_BRIDGE_LIMITS, fromBridgeHeaders, parseBridgePrincipal, toBridgeHeaders, wsMessageSize, } from './protocol.js';
+const logger = getLogger('http');
+const BODYLESS_METHODS = new Set(['GET', 'HEAD']);
+/** Close code / reason used when the gateway revoked the socket's principal. */
+export const PRINCIPAL_REVOKED_CLOSE_CODE = 4401;
+export function createBridgedHttpHost(options) {
+    const limits = Object.freeze({ ...DEFAULT_BRIDGE_LIMITS, ...options.limits });
+    const { channel } = options;
+    let addresses = Object.freeze([]);
+    const tokenRegistry = new TokenRegistry();
+    const router = createHttpRouter({
+        ...options,
+        tokenRegistry,
+        authentication: 'forwarded',
+        address: () => addresses[0],
+        secure: false,
+    });
+    const exchanges = new Map();
+    const sockets = new Map();
+    let listening = false;
+    let closed = false;
+    let revision = 0;
+    let generation;
+    let lastSent;
+    let publishScheduled = false;
+    let closeResult;
+    const disposers = [];
+    let lastCatalog;
+    const revokedListeners = new Set();
+    const send = (message) => {
+        try {
+            channel.send(message);
+        }
+        catch { /* channel gone */ }
+    };
+    // Closed registry: initialized (no open Host, no bootstrap token), never resolves a bearer;
+    // audit entries are written by the gateway.
+    const forwardedAccess = Object.freeze({
+        initialized: () => true,
+        authenticate: async () => null,
+        audit: (entry) => {
+            if (listening && !closed)
+                send({ type: 'audit', payload: { entry: cloneableAudit(entry) } });
+        },
+    });
+    tokenRegistry.useAccessProvider(forwardedAccess);
+    /** Reports the plugin permission catalog when it changed (or always with `force`). */
+    function sendCatalog(force) {
+        if (!listening || closed)
+            return;
+        let pluginPermissions;
+        try {
+            pluginPermissions = JSON.parse(JSON.stringify(tokenRegistry.pluginPermissions()));
+        }
+        catch {
+            return;
+        }
+        const fingerprint = JSON.stringify(pluginPermissions);
+        if (!force && fingerprint === lastCatalog)
+            return;
+        lastCatalog = fingerprint;
+        send({ type: 'catalog', payload: { pluginPermissions } });
+    }
+    function revokePrincipal(principalId) {
+        for (const [id, exchange] of [...exchanges]) {
+            if (exchange.principalId === principalId)
+                abortExchange(id, 'Credentials revoked', true);
+        }
+        for (const socket of [...sockets.values()]) {
+            if (socket.principalId === principalId)
+                socket.finish(PRINCIPAL_REVOKED_CLOSE_CODE, 'Credentials revoked', true);
+        }
+        for (const listener of [...revokedListeners]) {
+            try {
+                listener(principalId);
+            }
+            catch { /* listener failure stays local */ }
+        }
+    }
+    function routeTable() {
+        if (closed) {
+            return Object.freeze({ revision, ...(generation !== undefined ? { generation } : {}), apiBase: router.apiBase, http: Object.freeze([]), ws: Object.freeze([]) });
+        }
+        return Object.freeze({
+            revision,
+            ...(generation !== undefined ? { generation } : {}),
+            apiBase: router.apiBase,
+            http: Object.freeze(router.listRoutes().map((route) => {
+                const meta = cloneableMeta(route.meta);
+                return Object.freeze({ method: route.method, pattern: route.pattern, ...(meta ? { meta } : {}) });
+            })),
+            ws: router.listWsRoutes(),
+        });
+    }
+    function sendRoutes(force) {
+        if (!listening)
+            return;
+        const table = routeTable();
+        const fingerprint = JSON.stringify([table.generation, table.http, table.ws]);
+        if (!force && fingerprint === lastSent)
+            return;
+        lastSent = fingerprint;
+        revision += 1;
+        // The catalog follows the generation: report it before the table that serves it.
+        sendCatalog(false);
+        send({ type: 'routes', payload: { table: { ...table, revision } } });
+    }
+    // Registration bursts (a generation registering dozens of routes) coalesce into one table.
+    const schedulePublish = () => {
+        if (!listening || publishScheduled)
+            return;
+        publishScheduled = true;
+        queueMicrotask(() => {
+            publishScheduled = false;
+            sendRoutes(false);
+        });
+    };
+    // ---- HTTP
+    async function handleRequest(message) {
+        const { id, payload } = message;
+        if (exchanges.has(id) || sockets.has(id))
+            return;
+        if (!listening || closed || exchanges.size + sockets.size >= limits.maxStreams) {
+            send({ type: 'http.response.head', id, payload: { status: 503, headers: [], body: false } });
+            send({ type: 'http.response.end', id, payload: {} });
+            return;
+        }
+        const principal = payload.principal === undefined ? undefined : parseBridgePrincipal(payload.principal);
+        const principalId = userIdOf(principal);
+        const exchange = {
+            abort: new AbortController(),
+            gate: new CreditGate(limits.initialCreditBytes),
+            ...(principalId ? { principalId } : {}),
+        };
+        exchanges.set(id, exchange);
+        const method = payload.method.toUpperCase();
+        if (payload.body && !BODYLESS_METHODS.has(method)) {
+            exchange.body = new InboundBody({
+                window: limits.initialCreditBytes,
+                grant: (bytes) => { if (exchanges.get(id) === exchange)
+                    send({ type: 'http.request.credit', id, payload: { bytes } }); },
+                // The gateway stops sending once the response ends; nothing to tell it now.
+                cancel: () => undefined,
+            });
+        }
+        try {
+            let request;
+            try {
+                request = new Request(payload.url, {
+                    method,
+                    headers: fromBridgeHeaders(payload.headers),
+                    signal: exchange.abort.signal,
+                    ...(exchange.body ? { body: exchange.body.stream, duplex: 'half' } : {}),
+                });
+            }
+            catch {
+                sendHead(id, new Response(null, { status: 400 }));
+                send({ type: 'http.response.end', id, payload: {} });
+                return;
+            }
+            const response = await router.handle(request, {
+                ...(payload.remoteAddress ? { remoteAddress: payload.remoteAddress } : {}),
+                ...(principal ? { principal } : {}),
+            });
+            if (exchange.abort.signal.aborted) {
+                await response.body?.cancel(exchange.abort.signal.reason).catch(() => undefined);
+                return;
+            }
+            sendHead(id, response);
+            if (response.body) {
+                await pumpBody(response.body, {
+                    gate: exchange.gate,
+                    maxChunkBytes: limits.maxChunkBytes,
+                    signal: exchange.abort.signal,
+                    send: (chunk) => send({ type: 'http.response.body', id, payload: { chunk } }),
+                });
+            }
+            if (!exchange.abort.signal.aborted)
+                send({ type: 'http.response.end', id, payload: {} });
+        }
+        catch (error) {
+            if (!exchange.abort.signal.aborted) {
+                logger.debug(formatCompact({ op: 'bridge_response_failed', error: errorText(error) }));
+                send({ type: 'http.response.error', id, payload: { message: errorText(error).slice(0, 512) } });
+            }
+        }
+        finally {
+            if (exchanges.get(id) === exchange)
+                exchanges.delete(id);
+            exchange.gate.close();
+            exchange.body?.fail(new Error('Exchange finished'));
+        }
+    }
+    function sendHead(id, response) {
+        send({
+            type: 'http.response.head',
+            id,
+            payload: {
+                status: response.status,
+                ...(response.statusText ? { statusText: response.statusText.slice(0, 256) } : {}),
+                headers: toBridgeHeaders(response.headers),
+                body: response.body !== null,
+            },
+        });
+    }
+    function abortExchange(id, reason, notify) {
+        const exchange = exchanges.get(id);
+        if (!exchange)
+            return;
+        exchanges.delete(id);
+        const error = new Error(reason);
+        exchange.abort.abort(error);
+        exchange.gate.close(error);
+        exchange.body?.fail(error);
+        if (notify)
+            send({ type: 'http.response.error', id, payload: { message: reason } });
+    }
+    // ---- WebSocket
+    async function handleWsOpen(message) {
+        const { id, payload } = message;
+        if (exchanges.has(id) || sockets.has(id))
+            return;
+        if (!listening || closed || exchanges.size + sockets.size >= limits.maxStreams) {
+            send({ type: 'ws.rejected', id, payload: { status: 503 } });
+            return;
+        }
+        let url;
+        try {
+            url = new URL(payload.url);
+        }
+        catch {
+            send({ type: 'ws.rejected', id, payload: { status: 404 } });
+            return;
+        }
+        const principal = payload.principal === undefined ? undefined : parseBridgePrincipal(payload.principal);
+        // Reserve the id while the upgrade is decided, so a racing ws.close is not lost.
+        const socket = createSocket(id);
+        const principalId = userIdOf(principal);
+        if (principalId)
+            socket.principalId = principalId;
+        sockets.set(id, socket);
+        const decision = await router.upgrade({
+            url,
+            headers: fromBridgeHeaders(payload.headers),
+            ...(payload.remoteAddress ? { remoteAddress: payload.remoteAddress } : {}),
+            ...(principal ? { principal } : {}),
+        }).catch(() => ({ accepted: false, status: 404 }));
+        if (!decision.accepted) {
+            sockets.delete(id);
+            if (!socket.closed)
+                send({ type: 'ws.rejected', id, payload: { status: decision.status } });
+            return;
+        }
+        if (socket.closed || closed) {
+            sockets.delete(id);
+            decision.reject();
+            if (!socket.closed)
+                send({ type: 'ws.rejected', id, payload: { status: 503 } });
+            return;
+        }
+        send({ type: 'ws.accepted', id, payload: {} });
+        const transport = {
+            send(data) {
+                if (socket.closed)
+                    return;
+                const size = wsMessageSize(data);
+                if (size > limits.maxWsMessageBytes) {
+                    socket.finish(1009, 'Message too big', true);
+                    return;
+                }
+                if (socket.buffered + size > limits.maxWsBufferedBytes) {
+                    socket.finish(1013, 'Bridge backpressure', true);
+                    return;
+                }
+                socket.buffered += size;
+                send({ type: 'ws.message', id, payload: { data: typeof data === 'string' ? data : ownBytes(data) } });
+            },
+            close(code = 1000, reason = '') {
+                socket.finish(code, reason, true);
+            },
+            onMessage(listener) {
+                socket.messageListeners.add(listener);
+                return () => { socket.messageListeners.delete(listener); };
+            },
+            onClose(listener) {
+                socket.closeListeners.add(listener);
+                return () => { socket.closeListeners.delete(listener); };
+            },
+            get bufferedAmount() { return socket.buffered; },
+        };
+        decision.accept(transport);
+    }
+    function createSocket(id) {
+        const socket = {
+            messageListeners: new Set(),
+            closeListeners: new Set(),
+            buffered: 0,
+            closed: false,
+            finish(code, reason, notify) {
+                if (socket.closed)
+                    return;
+                socket.closed = true;
+                if (sockets.get(id) === socket)
+                    sockets.delete(id);
+                if (notify)
+                    send({ type: 'ws.close', id, payload: { code: sendableCloseCode(code), reason: reason.slice(0, 123) } });
+                for (const listener of [...socket.closeListeners]) {
+                    try {
+                        listener(code, reason);
+                    }
+                    catch { /* listener failure stays local */ }
+                }
+                socket.closeListeners.clear();
+                socket.messageListeners.clear();
+            },
+        };
+        return socket;
+    }
+    function deliverWsMessage(id, data) {
+        const socket = sockets.get(id);
+        if (!socket || socket.closed)
+            return;
+        for (const listener of [...socket.messageListeners]) {
+            try {
+                listener(data);
+            }
+            catch (error) {
+                logger.warn(formatCompact({ op: 'ws_message_listener_failed', error: errorText(error) }));
+            }
+        }
+        send({ type: 'ws.drain', id, payload: { bytes: Math.max(1, wsMessageSize(data)) } });
+    }
+    // ---- channel
+    const onMessage = (message) => {
+        switch (message.type) {
+            case 'host.addresses':
+                addresses = Object.freeze(message.payload.addresses.map((address) => Object.freeze({ ...address })));
+                return;
+            case 'http.request':
+                void handleRequest(message);
+                return;
+            case 'principal-revoked':
+                revokePrincipal(message.payload.principalId);
+                return;
+            case 'http.request.body': {
+                const exchange = exchanges.get(message.id);
+                if (exchange?.body && !exchange.body.push(message.payload.chunk)) {
+                    abortExchange(message.id, 'Request body exceeded the granted credit', true);
+                }
+                return;
+            }
+            case 'http.request.end':
+                exchanges.get(message.id)?.body?.end();
+                return;
+            case 'http.request.abort':
+                abortExchange(message.id, message.payload.message, false);
+                return;
+            case 'http.response.credit':
+                exchanges.get(message.id)?.gate.add(message.payload.bytes);
+                return;
+            case 'ws.open':
+                void handleWsOpen(message);
+                return;
+            case 'ws.message':
+                deliverWsMessage(message.id, message.payload.data);
+                return;
+            case 'ws.close':
+                sockets.get(message.id)?.finish(message.payload.code, message.payload.reason, false);
+                return;
+            case 'ws.drain': {
+                const socket = sockets.get(message.id);
+                if (socket)
+                    socket.buffered = Math.max(0, socket.buffered - message.payload.bytes);
+                return;
+            }
+            default:
+                return;
+        }
+    };
+    const onDisconnect = () => {
+        for (const id of [...exchanges.keys()])
+            abortExchange(id, 'Gateway disconnected', false);
+        for (const socket of [...sockets.values()])
+            socket.finish(1006, 'Gateway disconnected', false);
+    };
+    const host = {
+        [generationAdmissionBinder]: (admission) => router[generationAdmissionBinder](admission),
+        [httpHostAddressProvider]: () => addresses,
+        ws: (pathname, wsOptions) => router.ws(pathname, wsOptions),
+        route: (method, path, handler, meta) => router.route(method, path, handler, meta),
+        listRoutes: () => router.listRoutes(),
+        get address() { return addresses[0]; },
+        get tokenRegistry() { return router.tokenRegistry; },
+        get activeStreams() { return exchanges.size + sockets.size; },
+        routeTable,
+        publishRoutes(next) {
+            if (next !== undefined)
+                generation = next;
+            sendRoutes(true);
+        },
+        onPrincipalRevoked(listener) {
+            revokedListeners.add(listener);
+            return () => { revokedListeners.delete(listener); };
+        },
+        async listen() {
+            if (closed)
+                throw new Error('HTTP Host is closed');
+            if (!listening) {
+                listening = true;
+                disposers.push(channel.onMessage(onMessage), channel.onDisconnect(onDisconnect), router.onRoutesChanged(schedulePublish));
+                // Like a listening server, a listening bridge keeps the instance alive until close().
+                if (channel.hold)
+                    disposers.push(channel.hold());
+                sendCatalog(true);
+                sendRoutes(true);
+                logger.debug(formatCompact({ op: 'bridge_listening', routes: router.routeCount, ws: router.wsPaths.length }));
+            }
+            return addresses[0];
+        },
+        close() {
+            closeResult ??= (async () => {
+                const wasListening = listening;
+                closed = true;
+                for (const id of [...exchanges.keys()])
+                    abortExchange(id, 'Instance stopping', wasListening);
+                for (const socket of [...sockets.values()])
+                    socket.finish(1001, 'Instance stopping', wasListening);
+                if (wasListening)
+                    sendRoutes(true);
+                listening = false;
+                router.close();
+                for (const dispose of disposers.splice(0))
+                    dispose();
+            })();
+            return closeResult;
+        },
+    };
+    return host;
+}
+/** Route meta that survives structured clone (JSON data only); otherwise dropped. */
+function cloneableMeta(meta) {
+    if (!meta)
+        return undefined;
+    try {
+        return JSON.parse(JSON.stringify(meta));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** User id of a forwarded user / API-token principal (what `principal-revoked` names). */
+function userIdOf(principal) {
+    return principal && principal.kind !== 'bootstrap' ? principal.userId : undefined;
+}
+/** An audit entry that survives structured clone (JSON detail only). */
+function cloneableAudit(entry) {
+    try {
+        return JSON.parse(JSON.stringify(entry));
+    }
+    catch {
+        const { detail: _detail, ...rest } = entry;
+        return rest;
+    }
+}
+/** Close codes a peer may put on the wire; reserved ones (1005, 1006, 1015) become 1000. */
+export function sendableCloseCode(code) {
+    if (!Number.isInteger(code))
+        return 1000;
+    if ((code >= 1000 && code <= 1003) || (code >= 1007 && code <= 1014) || (code >= 3000 && code <= 4999))
+        return code;
+    return 1000;
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/lib/bridge/control-channel.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Instance side of the gateway control channel (ADR 0054 §3).
+ *
+ * Wraps the child-process IPC port (`process.send` / `process.on('message')`). The channel is
+ * unref'd so an idle IPC pipe never keeps a stopped instance alive.
+ */
+import { type BridgeRouteTable, type GatewayShutdownPayload, type GatewayToInstanceMessage, type InstanceToGatewayMessage } from './protocol.js';
+/** The subset of `process` the control channel needs; tests pass a fake. */
+export interface InstanceIpcPort {
+    send?(message: unknown, callback?: (error: Error | null) => void): boolean;
+    on(event: 'message', listener: (message: unknown) => void): unknown;
+    on(event: 'disconnect', listener: () => void): unknown;
+    off(event: 'message', listener: (message: unknown) => void): unknown;
+    off(event: 'disconnect', listener: () => void): unknown;
+    readonly connected?: boolean;
+    readonly channel?: {
+        unref?(): void;
+        ref?(): void;
+    } | null;
+}
+export interface InstanceReadyDetails {
+    readonly generation?: number;
+    /** Route table at ready time (ADR 0054 §3 `ready { routes }`). */
+    readonly routes?: BridgeRouteTable;
+}
+export interface InstanceControlChannel {
+    /** Announces that startup completed (carries the protocol version). */
+    ready(details?: InstanceReadyDetails): void;
+    /** Asks the gateway for a whole-process restart; replaces the former exit code 75. */
+    requestRestart(reason: string): void;
+    onShutdown(listener: (payload: GatewayShutdownPayload) => void): () => void;
+    /** Every validated gateway message (bridge streams, addresses, shutdown). */
+    onMessage(listener: (message: GatewayToInstanceMessage) => void): () => void;
+    /** Sends one bridge message; dropped once the channel is gone. */
+    send(message: InstanceToGatewayMessage): void;
+    /**
+     * Keeps the process alive through the channel (as a listening server would) until the
+     * returned release runs. Holds are counted; the channel is unref'd again at zero.
+     */
+    hold(): () => void;
+    /** Protocol version the gateway announced through {@link INSTANCE_CHILD_ENV}, when numeric. */
+    readonly gatewayVersion?: number;
+    /** The gateway went away (the IPC channel closed). */
+    onDisconnect(listener: () => void): () => void;
+    readonly connected: boolean;
+    close(): void;
+}
+/**
+ * Opens the control channel when the gateway started this process: the IPC channel must be
+ * present and {@link INSTANCE_CHILD_ENV} set. Returns `undefined` otherwise (not supervised).
+ *
+ * The marker matters: other parents also open an IPC channel (test runners' fork workers,
+ * process managers). Treating their channel as the gateway would send control messages to
+ * them and exit the process on a restart request.
+ *
+ * Throws {@link BridgeProtocolMismatchError} when the marker names a protocol version this build
+ * cannot speak: the instance must not start against an incompatible gateway.
+ */
+export declare function openInstanceControlChannel(port?: InstanceIpcPort, pid?: number, environment?: Readonly<Record<string, string | undefined>>): InstanceControlChannel | undefined;

package/lib/bridge/control-channel.js

@@ -0,0 +1,131 @@
+/**
+ * Instance side of the gateway control channel (ADR 0054 §3).
+ *
+ * Wraps the child-process IPC port (`process.send` / `process.on('message')`). The channel is
+ * unref'd so an idle IPC pipe never keeps a stopped instance alive.
+ */
+import { BridgeProtocolMismatchError, INSTANCE_BRIDGE_PROTOCOL_VERSION, INSTANCE_CHILD_ENV, isBridgeProtocolCompatible, parseGatewayMessage, } from './protocol.js';
+/**
+ * Opens the control channel when the gateway started this process: the IPC channel must be
+ * present and {@link INSTANCE_CHILD_ENV} set. Returns `undefined` otherwise (not supervised).
+ *
+ * The marker matters: other parents also open an IPC channel (test runners' fork workers,
+ * process managers). Treating their channel as the gateway would send control messages to
+ * them and exit the process on a restart request.
+ *
+ * Throws {@link BridgeProtocolMismatchError} when the marker names a protocol version this build
+ * cannot speak: the instance must not start against an incompatible gateway.
+ */
+export function openInstanceControlChannel(port = process, pid = process.pid, environment = process.env) {
+    const marker = environment[INSTANCE_CHILD_ENV];
+    if (!marker)
+        return undefined;
+    if (typeof port.send !== 'function' || port.connected === false)
+        return undefined;
+    const gatewayVersion = /^\d+$/u.test(marker) ? Number(marker) : undefined;
+    if (gatewayVersion !== undefined && !isBridgeProtocolCompatible(gatewayVersion)) {
+        throw new BridgeProtocolMismatchError(gatewayVersion, 'gateway');
+    }
+    port.channel?.unref?.();
+    const shutdownListeners = new Set();
+    const messageListeners = new Set();
+    const disconnectListeners = new Set();
+    let connected = true;
+    let closed = false;
+    let holds = 0;
+    const releaseHold = () => {
+        holds -= 1;
+        if (holds === 0)
+            port.channel?.unref?.();
+    };
+    const onMessage = (raw) => {
+        const message = parseGatewayMessage(raw);
+        if (!message)
+            return;
+        for (const listener of [...messageListeners]) {
+            try {
+                listener(message);
+            }
+            catch { /* one consumer never breaks the channel */ }
+        }
+        if (message.type !== 'shutdown')
+            return;
+        for (const listener of [...shutdownListeners])
+            listener(message.payload);
+    };
+    const onDisconnect = () => {
+        connected = false;
+        for (const listener of [...disconnectListeners])
+            listener();
+    };
+    port.on('message', onMessage);
+    port.on('disconnect', onDisconnect);
+    const send = (message) => {
+        if (!connected || closed)
+            return;
+        try {
+            // The callback swallows EPIPE when the gateway is already gone.
+            port.send?.(message, () => undefined);
+        }
+        catch { /* channel closed */ }
+    };
+    return {
+        ready(details = {}) {
+            send({
+                type: 'ready',
+                payload: {
+                    version: INSTANCE_BRIDGE_PROTOCOL_VERSION,
+                    pid,
+                    ...(details.generation !== undefined ? { generation: details.generation } : {}),
+                    ...(details.routes ? { routes: details.routes } : {}),
+                },
+            });
+        },
+        send,
+        hold() {
+            if (closed)
+                return () => undefined;
+            holds += 1;
+            if (holds === 1)
+                port.channel?.ref?.();
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                releaseHold();
+            };
+        },
+        onMessage(listener) {
+            messageListeners.add(listener);
+            return () => { messageListeners.delete(listener); };
+        },
+        ...(gatewayVersion !== undefined ? { gatewayVersion } : {}),
+        requestRestart(reason) {
+            send({ type: 'restart-request', payload: { reason } });
+        },
+        onShutdown(listener) {
+            shutdownListeners.add(listener);
+            return () => { shutdownListeners.delete(listener); };
+        },
+        onDisconnect(listener) {
+            disconnectListeners.add(listener);
+            return () => { disconnectListeners.delete(listener); };
+        },
+        get connected() { return connected && !closed; },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            if (holds > 0) {
+                holds = 0;
+                port.channel?.unref?.();
+            }
+            port.off('message', onMessage);
+            port.off('disconnect', onDisconnect);
+            shutdownListeners.clear();
+            messageListeners.clear();
+            disconnectListeners.clear();
+        },
+    };
+}