@zhin.js/host-http 1.1.17 → 1.2.0

package/lib/bridge/flow.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Credit-based body streaming shared by both ends of the bridge (ADR 0054 §3).
+ *
+ * The sender ({@link pumpBody}) never has more than its credit in flight; the receiver
+ * ({@link InboundBody}) buffers at most the window and grants credit as its consumer reads.
+ */
+/**
+ * A copy that owns its whole `ArrayBuffer`. Structured clone serializes a view's entire backing
+ * buffer, so a pooled `Buffer` or a `subarray` would otherwise ship unrelated bytes.
+ */
+export declare function ownBytes(chunk: Uint8Array): Uint8Array;
+export declare class BridgeStreamClosedError extends Error {
+    constructor(message?: string);
+}
+/** Sender-side credit: {@link take} waits while the receiver has not granted more. */
+export declare class CreditGate {
+    #private;
+    constructor(initial: number);
+    get available(): number;
+    add(bytes: number): void;
+    /** Resolves with up to `max` bytes of credit (at least 1); rejects once closed. */
+    take(max: number): Promise<number>;
+    close(error?: Error): void;
+}
+export interface PumpBodyOptions {
+    readonly gate: CreditGate;
+    readonly maxChunkBytes: number;
+    send(chunk: Uint8Array): void;
+    /** Aborting stops the pump and cancels the source. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Reads `source` to the end and sends it in chunks that fit both the frame limit and the
+ * available credit. Rejects when the source errors, the gate closes or `signal` aborts; the
+ * source is cancelled in every failure case.
+ */
+export declare function pumpBody(source: ReadableStream<Uint8Array>, options: PumpBodyOptions): Promise<void>;
+export interface InboundBodyOptions {
+    /** Credit the sender started with; also the most this body buffers. */
+    readonly window: number;
+    /** Grants `bytes` more credit to the sender. */
+    grant(bytes: number): void;
+    /** The consumer cancelled the body; tell the sender to stop. */
+    cancel(reason: unknown): void;
+}
+/** Receiver side: a pull-driven `ReadableStream` that grants credit as its consumer reads. */
+export declare class InboundBody {
+    #private;
+    readonly stream: ReadableStream<Uint8Array>;
+    constructor(options: InboundBodyOptions);
+    /** Whether the stream reached a terminal state (end, error, cancel). */
+    get settled(): boolean;
+    get bufferedBytes(): number;
+    /** Queues a chunk; false when the sender exceeded its credit (protocol violation). */
+    push(chunk: Uint8Array): boolean;
+    end(): void;
+    fail(error: unknown): void;
+}

package/lib/bridge/flow.js

@@ -0,0 +1,188 @@
+/**
+ * Credit-based body streaming shared by both ends of the bridge (ADR 0054 §3).
+ *
+ * The sender ({@link pumpBody}) never has more than its credit in flight; the receiver
+ * ({@link InboundBody}) buffers at most the window and grants credit as its consumer reads.
+ */
+/**
+ * A copy that owns its whole `ArrayBuffer`. Structured clone serializes a view's entire backing
+ * buffer, so a pooled `Buffer` or a `subarray` would otherwise ship unrelated bytes.
+ */
+export function ownBytes(chunk) {
+    if (chunk.byteOffset === 0 && chunk.byteLength === chunk.buffer.byteLength && !(chunk.buffer instanceof SharedArrayBuffer)) {
+        return Object.getPrototypeOf(chunk) === Uint8Array.prototype ? chunk : new Uint8Array(chunk.buffer, 0, chunk.byteLength);
+    }
+    return new Uint8Array(chunk);
+}
+export class BridgeStreamClosedError extends Error {
+    constructor(message = 'Bridge stream closed') {
+        super(message);
+        this.name = 'BridgeStreamClosedError';
+    }
+}
+/** Sender-side credit: {@link take} waits while the receiver has not granted more. */
+export class CreditGate {
+    #credit;
+    #waiter;
+    #closed;
+    constructor(initial) {
+        this.#credit = initial;
+    }
+    get available() { return this.#credit; }
+    add(bytes) {
+        this.#credit += bytes;
+        this.#wake();
+    }
+    /** Resolves with up to `max` bytes of credit (at least 1); rejects once closed. */
+    async take(max) {
+        while (this.#credit <= 0) {
+            if (this.#closed)
+                throw this.#closed;
+            await new Promise((resolve) => { this.#waiter = resolve; });
+        }
+        if (this.#closed)
+            throw this.#closed;
+        const granted = Math.min(max, this.#credit);
+        this.#credit -= granted;
+        return granted;
+    }
+    close(error = new BridgeStreamClosedError()) {
+        this.#closed ??= error;
+        this.#wake();
+    }
+    #wake() {
+        const waiter = this.#waiter;
+        this.#waiter = undefined;
+        waiter?.();
+    }
+}
+/**
+ * Reads `source` to the end and sends it in chunks that fit both the frame limit and the
+ * available credit. Rejects when the source errors, the gate closes or `signal` aborts; the
+ * source is cancelled in every failure case.
+ */
+export async function pumpBody(source, options) {
+    const reader = source.getReader();
+    const onAbort = () => {
+        options.gate.close(new BridgeStreamClosedError('Bridge stream aborted'));
+        void reader.cancel(options.signal?.reason).catch(() => undefined);
+    };
+    if (options.signal?.aborted)
+        onAbort();
+    else
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        for (;;) {
+            const next = await reader.read();
+            if (next.done)
+                return;
+            const value = next.value;
+            const bytes = value instanceof Uint8Array
+                ? value
+                : typeof value === 'string' ? new TextEncoder().encode(value) : undefined;
+            if (!bytes)
+                throw new TypeError('Body chunks must be Uint8Array');
+            let offset = 0;
+            while (offset < bytes.byteLength) {
+                const size = await options.gate.take(Math.min(options.maxChunkBytes, bytes.byteLength - offset));
+                options.send(ownBytes(bytes.subarray(offset, offset + size)));
+                offset += size;
+            }
+        }
+    }
+    catch (error) {
+        await reader.cancel(error).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        options.signal?.removeEventListener('abort', onAbort);
+        reader.releaseLock();
+    }
+}
+/** Receiver side: a pull-driven `ReadableStream` that grants credit as its consumer reads. */
+export class InboundBody {
+    stream;
+    #options;
+    #queue = [];
+    #buffered = 0;
+    #ungranted = 0;
+    #ended = false;
+    #error;
+    #failed = false;
+    #cancelled = false;
+    #waiter;
+    constructor(options) {
+        this.#options = options;
+        this.stream = new ReadableStream({
+            pull: async (controller) => {
+                while (this.#queue.length === 0 && !this.#ended && !this.#failed) {
+                    await new Promise((resolve) => { this.#waiter = resolve; });
+                }
+                const chunk = this.#queue.shift();
+                if (chunk) {
+                    this.#buffered -= chunk.byteLength;
+                    this.#consumed(chunk.byteLength);
+                    controller.enqueue(chunk);
+                    return;
+                }
+                if (this.#failed)
+                    controller.error(this.#error);
+                else
+                    controller.close();
+            },
+            cancel: (reason) => {
+                this.#cancelled = true;
+                this.#queue.length = 0;
+                this.#buffered = 0;
+                if (!this.#ended && !this.#failed)
+                    this.#options.cancel(reason);
+                this.#ended = true;
+            },
+        }, { highWaterMark: 0 });
+    }
+    /** Whether the stream reached a terminal state (end, error, cancel). */
+    get settled() { return this.#ended || this.#failed; }
+    get bufferedBytes() { return this.#buffered; }
+    /** Queues a chunk; false when the sender exceeded its credit (protocol violation). */
+    push(chunk) {
+        if (this.#cancelled || this.settled)
+            return true;
+        if (this.#buffered + this.#ungranted + chunk.byteLength > this.#options.window)
+            return false;
+        this.#queue.push(chunk);
+        this.#buffered += chunk.byteLength;
+        this.#wake();
+        return true;
+    }
+    end() {
+        if (this.settled)
+            return;
+        this.#ended = true;
+        this.#wake();
+    }
+    fail(error) {
+        if (this.settled)
+            return;
+        this.#failed = true;
+        this.#error = error;
+        this.#queue.length = 0;
+        this.#buffered = 0;
+        this.#wake();
+    }
+    #consumed(bytes) {
+        this.#ungranted += bytes;
+        // Grant in batches. The sender stalls only with a full window in flight; once the queue is
+        // drained all of it is ungranted, so any threshold up to the window can never deadlock.
+        if (this.#ungranted >= Math.max(1, Math.floor(this.#options.window / 4))) {
+            const granted = this.#ungranted;
+            this.#ungranted = 0;
+            if (!this.#ended && !this.#failed)
+                this.#options.grant(granted);
+        }
+    }
+    #wake() {
+        const waiter = this.#waiter;
+        this.#waiter = undefined;
+        waiter?.();
+    }
+}

package/lib/bridge/index.d.ts

@@ -0,0 +1,6 @@
+/** `@zhin.js/host-http/bridge` — gateway ↔ instance control channel and HTTP bridge (ADR 0054 §3). */
+export * from './protocol.js';
+export * from './control-channel.js';
+export { BridgeStreamClosedError, CreditGate, InboundBody, ownBytes, pumpBody, type InboundBodyOptions, type PumpBodyOptions, } from './flow.js';
+export { createBridgedHttpHost, PRINCIPAL_REVOKED_CLOSE_CODE, sendableCloseCode, type BridgeChannel, type BridgedHttpHost, type BridgedHttpHostOptions, } from './bridged-host.js';
+export { InstanceTransportError, IpcInstanceTransport, type GatewayInstancePort, type InstanceChildProcessLike, type InstanceRequestContext, type InstanceTransport, type InstanceTransportErrorCode, type InstanceWsOpenInfo, type IpcInstanceTransportOptions, } from './instance-transport.js';

package/lib/bridge/index.js

@@ -0,0 +1,6 @@
+/** `@zhin.js/host-http/bridge` — gateway ↔ instance control channel and HTTP bridge (ADR 0054 §3). */
+export * from './protocol.js';
+export * from './control-channel.js';
+export { BridgeStreamClosedError, CreditGate, InboundBody, ownBytes, pumpBody, } from './flow.js';
+export { createBridgedHttpHost, PRINCIPAL_REVOKED_CLOSE_CODE, sendableCloseCode, } from './bridged-host.js';
+export { InstanceTransportError, IpcInstanceTransport, } from './instance-transport.js';

package/lib/bridge/instance-transport.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Gateway side of the HTTP bridge (ADR 0054 §3): {@link InstanceTransport} is what the gateway's
+ * HTTP server codes against; {@link IpcInstanceTransport} implements it over the instance's IPC
+ * control channel. The gateway authenticates, then forwards the Web `Request` (with the
+ * principal) and gets a streamed `Response` back; WebSockets are bridged frame by frame.
+ *
+ * Nothing here imports `node:http` or `ws`; the gateway converts its Node server objects to
+ * `Request` / `WsConnection` itself.
+ */
+import type { ConsolePluginPermissionInfo } from '@zhin.js/console-protocol';
+import type { ConsoleAuditEntry, ConsolePrincipal } from '../access-control.js';
+import type { WsConnection } from '../http-host.js';
+import type { HttpHostAddress } from '../host-options.js';
+import { type BridgeLimits, type BridgeRouteTable, type GatewayToInstanceMessage } from './protocol.js';
+/** Per-request data the gateway resolved before forwarding. */
+export interface InstanceRequestContext {
+    /**
+     * Principal the gateway authenticated. Required for `{apiBase}` routes (else the instance
+     * answers 401); for other routes pass it when the caller presented a valid credential.
+     */
+    readonly principal?: ConsolePrincipal;
+    readonly remoteAddress?: string;
+}
+/** An upgrade request the gateway wants the instance to accept. */
+export interface InstanceWsOpenInfo {
+    readonly url: URL;
+    readonly headers: Headers;
+    /** Required for `auth: 'host'` sockets (see {@link BridgeRouteTable.ws}). */
+    readonly principal?: ConsolePrincipal;
+    readonly remoteAddress?: string;
+}
+/**
+ * @public What the gateway's HTTP server talks to (B1.3 codes against this).
+ *
+ * - `ready`: the instance announced its route table and accepts requests; false before that,
+ *   after the instance exited, or when it speaks an incompatible protocol.
+ * - `routes()` / `onRoutes()`: the current table; listeners run on every new table (hot reload,
+ *   generation switch) and with {@link EMPTY_ROUTE_TABLE} when the instance goes away.
+ * - `fetch()`: forwards one request. The request body is streamed with backpressure; aborting
+ *   `request.signal` cancels the exchange in the instance. Resolves with the instance's
+ *   `Response` (body streamed with backpressure; cancelling it cancels the instance side).
+ *   Rejects with {@link InstanceTransportError}: `instance-offline` (not ready / went away
+ *   before the head), `timeout` (no head in time), `instance-error` (failed before the head),
+ *   `overloaded` (too many streams), or with `request.signal.reason` when aborted.
+ * - `openWebSocket()`: `peer` is the gateway's accepted client socket. Resolves true once the
+ *   instance accepted (frames then flow both ways, closes propagate); false when it rejected,
+ *   timed out or is offline: the caller then closes `peer`. Peer frames sent before acceptance
+ *   are queued.
+ */
+export interface InstanceTransport {
+    readonly ready: boolean;
+    routes(): BridgeRouteTable;
+    onRoutes(listener: (table: BridgeRouteTable) => void): () => void;
+    fetch(request: Request, context?: InstanceRequestContext): Promise<Response>;
+    openWebSocket(info: InstanceWsOpenInfo, peer: WsConnection): Promise<boolean>;
+}
+export type InstanceTransportErrorCode = 'instance-offline' | 'timeout' | 'instance-error' | 'overloaded';
+export declare class InstanceTransportError extends Error {
+    readonly code: InstanceTransportErrorCode;
+    constructor(code: InstanceTransportErrorCode, message: string);
+}
+/** The gateway's end of the IPC channel to the current instance child. */
+export interface GatewayInstancePort {
+    send(message: GatewayToInstanceMessage): void;
+}
+/** The subset of `ChildProcess` {@link IpcInstanceTransport.attachChildProcess} needs. */
+export interface InstanceChildProcessLike {
+    send?(message: unknown, callback?: (error: Error | null) => void): boolean;
+    on(event: 'message', listener: (message: unknown) => void): unknown;
+    on(event: 'exit' | 'disconnect', listener: () => void): unknown;
+    off(event: 'message', listener: (message: unknown) => void): unknown;
+    off(event: 'exit' | 'disconnect', listener: () => void): unknown;
+}
+export interface IpcInstanceTransportOptions {
+    readonly limits?: Partial<BridgeLimits>;
+    /** Time to wait for a response head. Default {@link DEFAULT_BRIDGE_RESPONSE_TIMEOUT_MS}. */
+    readonly responseTimeoutMs?: number;
+    /** Time to wait for `ws.accepted`. Default {@link DEFAULT_BRIDGE_WS_OPEN_TIMEOUT_MS}. */
+    readonly wsOpenTimeoutMs?: number;
+    /** Client socket backlog below which instance frames are acknowledged. Default 1 MiB. */
+    readonly wsLowWaterBytes?: number;
+}
+export declare class IpcInstanceTransport implements InstanceTransport {
+    #private;
+    constructor(options?: IpcInstanceTransportOptions);
+    /** Plugin permission catalog the instance last reported (kept across restarts). */
+    pluginPermissions(): readonly ConsolePluginPermissionInfo[];
+    onCatalog(listener: (catalog: readonly ConsolePluginPermissionInfo[]) => void): () => void;
+    /** Audit entries the instance wrote (the gateway owns the audit log). */
+    onAudit(listener: (entry: ConsoleAuditEntry) => void): () => void;
+    /** Tells the instance to close the live connections of `principalId` (a user id). */
+    revokePrincipal(principalId: string, reason?: string): void;
+    get ready(): boolean;
+    get activeStreams(): number;
+    routes(): BridgeRouteTable;
+    onRoutes(listener: (table: BridgeRouteTable) => void): () => void;
+    /** Addresses the gateway listens on; forwarded to the instance (`HttpHost.address`). */
+    setAddresses(addresses: readonly HttpHostAddress[]): void;
+    /** Binds the transport to a new instance child; an earlier one is detached first. */
+    attach(port: GatewayInstancePort): void;
+    /**
+     * Wires a spawned child (`serialization: 'advanced'`): its messages feed {@link receive},
+     * `exit` / `disconnect` detach. Returns the unwiring function.
+     */
+    attachChildProcess(child: InstanceChildProcessLike): () => void;
+    /** The instance is gone: fail every exchange and close every bridged socket. */
+    detach(reason?: string): void;
+    /** Feeds one raw message from the instance. Unknown / malformed messages are ignored. */
+    receive(raw: unknown): void;
+    fetch(request: Request, context?: InstanceRequestContext): Promise<Response>;
+    openWebSocket(info: InstanceWsOpenInfo, peer: WsConnection): Promise<boolean>;
+}