@zhin.js/host-http 1.1.17 → 1.2.1

package/lib/bridge/instance-transport.js

@@ -0,0 +1,532 @@
+import { sendableCloseCode } from './bridged-host.js';
+import { BridgeStreamClosedError, CreditGate, InboundBody, ownBytes, pumpBody } from './flow.js';
+import { DEFAULT_BRIDGE_LIMITS, DEFAULT_BRIDGE_RESPONSE_TIMEOUT_MS, DEFAULT_BRIDGE_WS_OPEN_TIMEOUT_MS, EMPTY_ROUTE_TABLE, fromBridgeHeaders, headSize, isBridgeProtocolCompatible, parseInstanceMessage, toBridgeHeaders, wsMessageSize, } from './protocol.js';
+export class InstanceTransportError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'InstanceTransportError';
+    }
+}
+const NULL_BODY_STATUSES = new Set([204, 205, 304]);
+const DRAIN_POLL_MS = 20;
+export class IpcInstanceTransport {
+    #limits;
+    /** Survives restarts: the last catalog the instance reported (plugins rarely change). */
+    #catalog = Object.freeze([]);
+    #catalogListeners = new Set();
+    #auditListeners = new Set();
+    #responseTimeoutMs;
+    #wsOpenTimeoutMs;
+    #wsLowWater;
+    #port;
+    #table = EMPTY_ROUTE_TABLE;
+    #tableReceived = false;
+    #incompatible = false;
+    #addresses;
+    #sequence = 0;
+    #exchanges = new Map();
+    #peers = new Map();
+    #routeListeners = new Set();
+    constructor(options = {}) {
+        this.#limits = Object.freeze({ ...DEFAULT_BRIDGE_LIMITS, ...options.limits });
+        this.#responseTimeoutMs = options.responseTimeoutMs ?? DEFAULT_BRIDGE_RESPONSE_TIMEOUT_MS;
+        this.#wsOpenTimeoutMs = options.wsOpenTimeoutMs ?? DEFAULT_BRIDGE_WS_OPEN_TIMEOUT_MS;
+        this.#wsLowWater = options.wsLowWaterBytes ?? 1024 * 1024;
+    }
+    /** Plugin permission catalog the instance last reported (kept across restarts). */
+    pluginPermissions() {
+        return this.#catalog;
+    }
+    onCatalog(listener) {
+        this.#catalogListeners.add(listener);
+        return () => { this.#catalogListeners.delete(listener); };
+    }
+    /** Audit entries the instance wrote (the gateway owns the audit log). */
+    onAudit(listener) {
+        this.#auditListeners.add(listener);
+        return () => { this.#auditListeners.delete(listener); };
+    }
+    /** Tells the instance to close the live connections of `principalId` (a user id). */
+    revokePrincipal(principalId, reason) {
+        if (!principalId)
+            return;
+        this.#send({ type: 'principal-revoked', payload: { principalId, ...(reason ? { reason: reason.slice(0, 64) } : {}) } });
+    }
+    get ready() {
+        return this.#port !== undefined && this.#tableReceived && !this.#incompatible;
+    }
+    get activeStreams() {
+        return this.#exchanges.size + this.#peers.size;
+    }
+    routes() {
+        return this.ready ? this.#table : EMPTY_ROUTE_TABLE;
+    }
+    onRoutes(listener) {
+        this.#routeListeners.add(listener);
+        return () => { this.#routeListeners.delete(listener); };
+    }
+    /** Addresses the gateway listens on; forwarded to the instance (`HttpHost.address`). */
+    setAddresses(addresses) {
+        this.#addresses = Object.freeze(addresses.map((address) => ({ ...address })));
+        this.#send({ type: 'host.addresses', payload: { addresses: this.#addresses } });
+    }
+    /** Binds the transport to a new instance child; an earlier one is detached first. */
+    attach(port) {
+        if (this.#port)
+            this.detach('Instance replaced');
+        this.#port = port;
+        this.#table = EMPTY_ROUTE_TABLE;
+        this.#tableReceived = false;
+        this.#incompatible = false;
+        if (this.#addresses)
+            this.#send({ type: 'host.addresses', payload: { addresses: this.#addresses } });
+    }
+    /**
+     * Wires a spawned child (`serialization: 'advanced'`): its messages feed {@link receive},
+     * `exit` / `disconnect` detach. Returns the unwiring function.
+     */
+    attachChildProcess(child) {
+        const port = {
+            send(message) {
+                try {
+                    child.send?.(message, () => undefined);
+                }
+                catch { /* channel closed */ }
+            },
+        };
+        const onMessage = (raw) => { if (this.#port === port)
+            this.receive(raw); };
+        const onGone = () => { if (this.#port === port)
+            this.detach('Instance exited'); };
+        this.attach(port);
+        child.on('message', onMessage);
+        child.on('exit', onGone);
+        child.on('disconnect', onGone);
+        return () => {
+            child.off('message', onMessage);
+            child.off('exit', onGone);
+            child.off('disconnect', onGone);
+            onGone();
+        };
+    }
+    /** The instance is gone: fail every exchange and close every bridged socket. */
+    detach(reason = 'Instance offline') {
+        if (!this.#port)
+            return;
+        const wasReady = this.ready;
+        this.#port = undefined;
+        this.#tableReceived = false;
+        for (const [id, exchange] of [...this.#exchanges]) {
+            this.#exchanges.delete(id);
+            const error = new InstanceTransportError('instance-offline', reason);
+            exchange.gate.close(error);
+            exchange.abort.abort(error);
+            exchange.settleHead(error);
+            exchange.body?.fail(error);
+        }
+        for (const peer of [...this.#peers.values()]) {
+            peer.settle(false);
+            peer.closePeer(1012, 'Instance restarting');
+        }
+        this.#table = EMPTY_ROUTE_TABLE;
+        if (wasReady)
+            this.#emitRoutes();
+    }
+    /** Feeds one raw message from the instance. Unknown / malformed messages are ignored. */
+    receive(raw) {
+        const message = parseInstanceMessage(raw, this.#limits);
+        if (message)
+            this.#dispatch(message);
+    }
+    // ---- HTTP
+    async fetch(request, context = {}) {
+        request.signal.throwIfAborted();
+        if (!this.ready)
+            throw new InstanceTransportError('instance-offline', 'Instance is offline');
+        if (this.activeStreams >= this.#limits.maxStreams)
+            throw new InstanceTransportError('overloaded', 'Too many concurrent instance streams');
+        const headers = toBridgeHeaders(request.headers);
+        if (headSize(request.url, headers) > this.#limits.maxHeadBytes)
+            return new Response(null, { status: 431 });
+        const id = `h${++this.#sequence}`;
+        let settleHead;
+        const head = new Promise((resolve) => { settleHead = resolve; });
+        const exchange = {
+            method: request.method.toUpperCase(),
+            gate: new CreditGate(this.#limits.initialCreditBytes),
+            abort: new AbortController(),
+            settleHead: (value) => { settleHead(value); },
+            headReceived: false,
+        };
+        this.#exchanges.set(id, exchange);
+        const hasBody = request.body !== null;
+        this.#send({
+            type: 'http.request',
+            id,
+            payload: {
+                method: request.method,
+                url: request.url,
+                headers,
+                body: hasBody,
+                ...(context.principal ? { principal: context.principal } : {}),
+                ...(context.remoteAddress ? { remoteAddress: context.remoteAddress } : {}),
+            },
+        });
+        const onClientAbort = () => { this.#cancelExchange(id, request.signal.reason, 'Client aborted'); };
+        request.signal.addEventListener('abort', onClientAbort, { once: true });
+        exchange.abort.signal.addEventListener('abort', () => request.signal.removeEventListener('abort', onClientAbort), { once: true });
+        const timer = setTimeout(() => {
+            this.#cancelExchange(id, new InstanceTransportError('timeout', `Instance did not answer within ${this.#responseTimeoutMs} ms`), 'Gateway timeout');
+        }, this.#responseTimeoutMs);
+        timer.unref?.();
+        if (hasBody) {
+            void pumpBody(request.body, {
+                gate: exchange.gate,
+                maxChunkBytes: this.#limits.maxChunkBytes,
+                signal: exchange.abort.signal,
+                send: (chunk) => this.#send({ type: 'http.request.body', id, payload: { chunk } }),
+            }).then(() => {
+                if (this.#exchanges.get(id) === exchange)
+                    this.#send({ type: 'http.request.end', id, payload: {} });
+            }, (error) => {
+                if (error instanceof BridgeStreamClosedError || exchange.abort.signal.aborted)
+                    return;
+                this.#cancelExchange(id, error, 'Request body failed');
+            });
+        }
+        const result = await head;
+        clearTimeout(timer);
+        if (result instanceof Error)
+            throw result;
+        // The body (created with the head, see #dispatch) may already hold chunks or have ended.
+        return new Response(exchange.body?.stream ?? null, {
+            status: result.status,
+            ...(result.statusText ? { statusText: result.statusText } : {}),
+            headers: fromBridgeHeaders(result.headers),
+        });
+    }
+    #cancelExchange(id, reason, message) {
+        const exchange = this.#exchanges.get(id);
+        if (!exchange)
+            return;
+        this.#exchanges.delete(id);
+        const error = reason instanceof Error ? reason : new Error(message);
+        exchange.gate.close(new BridgeStreamClosedError(message));
+        exchange.abort.abort(error);
+        exchange.settleHead(toError(reason, message));
+        exchange.body?.fail(error);
+        this.#send({ type: 'http.request.abort', id, payload: { message: message.slice(0, 256) } });
+    }
+    #finishExchange(id) {
+        const exchange = this.#exchanges.get(id);
+        if (!exchange)
+            return;
+        this.#exchanges.delete(id);
+        // Stop a request body the instance no longer reads.
+        exchange.gate.close(new BridgeStreamClosedError('Exchange finished'));
+        exchange.abort.abort(new BridgeStreamClosedError('Exchange finished'));
+    }
+    // ---- WebSocket
+    openWebSocket(info, peer) {
+        if (!this.ready || this.activeStreams >= this.#limits.maxStreams)
+            return Promise.resolve(false);
+        const headers = toBridgeHeaders(info.headers);
+        if (headSize(info.url.href, headers) > this.#limits.maxHeadBytes)
+            return Promise.resolve(false);
+        const id = `w${++this.#sequence}`;
+        const limits = this.#limits;
+        let resolveOpen;
+        const opened = new Promise((resolve) => { resolveOpen = resolve; });
+        const unsubscribe = [];
+        let timer;
+        let queuedBytes = 0;
+        const state = {
+            peer,
+            forward: (data) => {
+                const size = wsMessageSize(data);
+                if (state.unacked + size > limits.maxWsBufferedBytes) {
+                    this.#send({ type: 'ws.close', id, payload: { code: 1013, reason: 'Instance backpressure' } });
+                    state.closePeer(1013, 'Instance backpressure');
+                    return;
+                }
+                state.unacked += size;
+                this.#send({ type: 'ws.message', id, payload: { data: typeof data === 'string' ? data : ownBytes(data) } });
+            },
+            accepted: false,
+            closed: false,
+            unacked: 0,
+            pendingAck: 0,
+            queue: [],
+            settle: (accepted) => {
+                clearTimeout(timer);
+                timer = undefined;
+                resolveOpen(accepted);
+            },
+            closePeer: (code, reason) => {
+                if (state.closed)
+                    return;
+                state.cleanup();
+                try {
+                    peer.close(sendableCloseCode(code), reason);
+                }
+                catch { /* already closed */ }
+            },
+            cleanup: () => {
+                state.closed = true;
+                clearInterval(state.drainTimer);
+                clearTimeout(timer);
+                if (this.#peers.get(id) === state)
+                    this.#peers.delete(id);
+                for (const dispose of unsubscribe.splice(0))
+                    dispose();
+            },
+        };
+        this.#peers.set(id, state);
+        unsubscribe.push(peer.onMessage((data) => {
+            if (state.closed)
+                return;
+            if (wsMessageSize(data) > limits.maxWsMessageBytes) {
+                this.#send({ type: 'ws.close', id, payload: { code: 1009, reason: 'Message too big' } });
+                state.closePeer(1009, 'Message too big');
+                return;
+            }
+            if (state.accepted) {
+                state.forward(data);
+                return;
+            }
+            queuedBytes += wsMessageSize(data);
+            if (queuedBytes > limits.maxWsBufferedBytes) {
+                this.#send({ type: 'ws.close', id, payload: { code: 1013, reason: 'Instance backpressure' } });
+                state.settle(false);
+                state.closePeer(1013, 'Instance backpressure');
+                return;
+            }
+            state.queue.push(data);
+        }));
+        unsubscribe.push(peer.onClose((code, reason) => {
+            if (state.closed)
+                return;
+            state.cleanup();
+            state.settle(false);
+            this.#send({ type: 'ws.close', id, payload: { code: wireCloseCode(code), reason: (reason ?? '').slice(0, 123) } });
+        }));
+        timer = setTimeout(() => {
+            if (state.accepted || state.closed)
+                return;
+            this.#send({ type: 'ws.close', id, payload: { code: 1001, reason: 'Open timed out' } });
+            state.cleanup();
+            state.settle(false);
+        }, this.#wsOpenTimeoutMs);
+        timer.unref?.();
+        this.#send({
+            type: 'ws.open',
+            id,
+            payload: {
+                url: info.url.href,
+                headers,
+                ...(info.principal ? { principal: info.principal } : {}),
+                ...(info.remoteAddress ? { remoteAddress: info.remoteAddress } : {}),
+            },
+        });
+        return opened;
+    }
+    #acknowledge(id, state, peer) {
+        const flush = () => {
+            if (state.closed)
+                return true;
+            if (peer.bufferedAmount > this.#wsLowWater)
+                return false;
+            if (state.pendingAck > 0) {
+                this.#send({ type: 'ws.drain', id, payload: { bytes: state.pendingAck } });
+                state.pendingAck = 0;
+            }
+            return true;
+        };
+        if (state.drainTimer || flush())
+            return;
+        // The client reads slowly: hold the acknowledgement until its socket drained.
+        state.drainTimer = setInterval(() => {
+            if (!flush())
+                return;
+            clearInterval(state.drainTimer);
+            state.drainTimer = undefined;
+        }, DRAIN_POLL_MS);
+        state.drainTimer.unref?.();
+    }
+    // ---- dispatch
+    #dispatch(message) {
+        switch (message.type) {
+            case 'ready':
+                if (!isBridgeProtocolCompatible(message.payload.version)) {
+                    this.#incompatible = true;
+                    return;
+                }
+                if (message.payload.routes)
+                    this.#setTable(message.payload.routes);
+                return;
+            case 'routes':
+                this.#setTable(message.payload.table);
+                return;
+            case 'restart-request':
+                return;
+            case 'catalog': {
+                this.#catalog = deepFreeze(message.payload.pluginPermissions.map((entry) => ({ ...entry, owners: [...entry.owners] })));
+                for (const listener of [...this.#catalogListeners]) {
+                    try {
+                        listener(this.#catalog);
+                    }
+                    catch { /* observers never break the bridge */ }
+                }
+                return;
+            }
+            case 'audit':
+                for (const listener of [...this.#auditListeners]) {
+                    try {
+                        listener(message.payload.entry);
+                    }
+                    catch { /* audit never breaks the bridge */ }
+                }
+                return;
+            case 'http.response.head': {
+                const exchange = this.#exchanges.get(message.id);
+                if (!exchange || exchange.headReceived)
+                    return;
+                exchange.headReceived = true;
+                const id = message.id;
+                const wanted = message.payload.body && !NULL_BODY_STATUSES.has(message.payload.status) && exchange.method !== 'HEAD';
+                // Created synchronously: body chunks of the same IPC batch are dispatched right after.
+                if (wanted) {
+                    exchange.body = new InboundBody({
+                        window: this.#limits.initialCreditBytes,
+                        grant: (bytes) => { if (this.#exchanges.get(id) === exchange)
+                            this.#send({ type: 'http.response.credit', id, payload: { bytes } }); },
+                        cancel: (reason) => { this.#cancelExchange(id, reason, 'Response cancelled'); },
+                    });
+                }
+                exchange.settleHead(message.payload);
+                if (!message.payload.body)
+                    this.#finishExchange(id);
+                // Body not wanted (HEAD / null-body status): stop the instance side.
+                else if (!wanted)
+                    this.#cancelExchange(id, new Error('Response body not used'), 'Response body not used');
+                return;
+            }
+            case 'http.response.body': {
+                const exchange = this.#exchanges.get(message.id);
+                if (!exchange?.body)
+                    return;
+                if (!exchange.body.push(message.payload.chunk)) {
+                    this.#cancelExchange(message.id, new InstanceTransportError('instance-error', 'Response body exceeded the granted credit'), 'Credit exceeded');
+                }
+                return;
+            }
+            case 'http.response.end': {
+                const exchange = this.#exchanges.get(message.id);
+                if (!exchange)
+                    return;
+                exchange.body?.end();
+                this.#finishExchange(message.id);
+                return;
+            }
+            case 'http.response.error': {
+                const exchange = this.#exchanges.get(message.id);
+                if (!exchange)
+                    return;
+                const error = new InstanceTransportError('instance-error', message.payload.message);
+                exchange.settleHead(error);
+                exchange.body?.fail(error);
+                this.#finishExchange(message.id);
+                return;
+            }
+            case 'http.request.credit':
+                this.#exchanges.get(message.id)?.gate.add(message.payload.bytes);
+                return;
+            case 'ws.accepted': {
+                const state = this.#peers.get(message.id);
+                if (!state || state.accepted || state.closed)
+                    return;
+                state.accepted = true;
+                for (const data of state.queue.splice(0))
+                    state.forward(data);
+                state.settle(true);
+                return;
+            }
+            case 'ws.rejected': {
+                const state = this.#peers.get(message.id);
+                if (!state || state.accepted)
+                    return;
+                state.cleanup();
+                state.settle(false);
+                return;
+            }
+            case 'ws.message': {
+                const state = this.#peers.get(message.id);
+                if (!state || state.closed)
+                    return;
+                try {
+                    state.peer.send(message.payload.data);
+                }
+                catch { /* peer closing */ }
+                state.pendingAck += Math.max(1, wsMessageSize(message.payload.data));
+                this.#acknowledge(message.id, state, state.peer);
+                return;
+            }
+            case 'ws.close': {
+                const state = this.#peers.get(message.id);
+                if (!state)
+                    return;
+                state.settle(false);
+                state.closePeer(message.payload.code, message.payload.reason);
+                return;
+            }
+            case 'ws.drain': {
+                const state = this.#peers.get(message.id);
+                if (state)
+                    state.unacked = Math.max(0, state.unacked - message.payload.bytes);
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    #setTable(table) {
+        if (this.#tableReceived && table.revision <= this.#table.revision)
+            return;
+        this.#table = deepFreeze(table);
+        this.#tableReceived = true;
+        if (!this.#incompatible)
+            this.#emitRoutes();
+    }
+    #emitRoutes() {
+        const table = this.routes();
+        for (const listener of [...this.#routeListeners]) {
+            try {
+                listener(table);
+            }
+            catch { /* observers never break the bridge */ }
+        }
+    }
+    #send(message) {
+        try {
+            this.#port?.send(message);
+        }
+        catch { /* instance gone */ }
+    }
+}
+/** Codes a peer reported locally (1005 / 1006) travel as is; anything else invalid becomes 1000. */
+function wireCloseCode(code) {
+    return Number.isInteger(code) && code >= 1000 && code <= 4999 ? code : 1000;
+}
+function toError(reason, fallback) {
+    return reason instanceof Error ? reason : new Error(typeof reason === 'string' ? reason : fallback);
+}
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}