@zhin.js/gateway 0.0.1-bootstrap.0 → 1.1.2

package/lib/http/gateway-events.js

@@ -0,0 +1,185 @@
+import { GATEWAY_PACKAGES_PROGRESS, GATEWAY_PACKAGES_PROGRESS_PATH } from '@zhin.js/console-protocol';
+import { jsonResponse } from '@zhin.js/host-http';
+const KEEPALIVE_MS = 15_000;
+/** Console event the client reloads its entries on (`CONSOLE_ENTRY_LIFECYCLE_EVENTS`). */
+export const PLUGIN_LIFECYCLE_UPDATED = 'plugin:lifecycle-updated';
+/** Gateway frames held while an instance frame is half written. */
+const MAX_PENDING_FRAMES = 1_024;
+/** Chunks queued for a client that does not read; beyond it the stream ends (the client resumes). */
+const MAX_QUEUED_CHUNKS = 4_096;
+const SSE_HEADERS = Object.freeze({
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-cache, no-transform',
+    'x-accel-buffering': 'no',
+});
+export function gatewayEventFrame(type, data) {
+    return `event: ${type}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+/** Registers the gateway's event routes; returns the unregister function. */
+export function registerGatewayEventRoutes(options) {
+    const { server } = options;
+    const base = server.apiBase;
+    const keepAliveMs = options.keepAliveMs ?? KEEPALIVE_MS;
+    const encoder = new TextEncoder();
+    /** A client stream fed with gateway frames (plus, when merging, the instance's). */
+    const open = (request) => {
+        let controller;
+        let finished = false;
+        const cleanups = [];
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            for (const cleanup of cleanups.splice(0)) {
+                try {
+                    cleanup();
+                }
+                catch { /* keep closing */ }
+            }
+            try {
+                controller.close();
+            }
+            catch { /* already closed */ }
+        };
+        const stream = new ReadableStream({
+            start(value) { controller = value; },
+            cancel() { finish(); },
+        });
+        const write = (text) => {
+            if (finished)
+                return;
+            try {
+                if ((controller.desiredSize ?? 1) < -MAX_QUEUED_CHUNKS) {
+                    finish();
+                    return;
+                }
+                controller.enqueue(encoder.encode(text));
+            }
+            catch {
+                finish();
+            }
+        };
+        request.signal.addEventListener('abort', finish, { once: true });
+        const timer = setInterval(() => write(': keepalive\n\n'), keepAliveMs);
+        timer.unref?.();
+        cleanups.push(() => clearInterval(timer));
+        return { stream, write, finish, cleanups, get finished() { return finished; } };
+    };
+    /**
+     * Progress frames; on the Console event stream (`lifecycle`) a succeeded enable / disable that
+     * changed `disable_plugins` is followed by `plugin:lifecycle-updated` `{ instanceKey, enabled }`,
+     * the event the instance used to publish for the Console switch (the Console reloads its entries).
+     */
+    const subscribeProgress = (deliver, lifecycle = false) => options.packages?.subscribe((event) => {
+        deliver(gatewayEventFrame(GATEWAY_PACKAGES_PROGRESS, event));
+        const plugin = event.type === 'result' && event.result.ok ? event.result.plugin : undefined;
+        if (lifecycle && plugin?.changed) {
+            deliver(gatewayEventFrame(PLUGIN_LIFECYCLE_UPDATED, { instanceKey: plugin.instanceKey, enabled: plugin.enabled }));
+        }
+    });
+    const events = async (request, context) => {
+        if (!server.instanceReady)
+            return offlineStream(request);
+        const upstream = await server.forward(request, context);
+        const type = upstream.headers.get('content-type') ?? '';
+        // Errors (401 / 403 / 503 …) and non-SSE answers pass through unchanged.
+        if (!upstream.ok || !upstream.body || !type.includes('text/event-stream')) {
+            if (upstream.status === 503 && !server.instanceReady) {
+                await upstream.body?.cancel().catch(() => undefined);
+                return offlineStream(request);
+            }
+            return upstream;
+        }
+        const client = open(request);
+        const reader = upstream.body.getReader();
+        client.cleanups.push(() => { void reader.cancel().catch(() => undefined); });
+        // Gateway frames wait while an instance frame is half written.
+        const pending = [];
+        let partial = '';
+        const decoder = new TextDecoder();
+        const flushPending = () => {
+            for (const frame of pending.splice(0))
+                client.write(frame);
+        };
+        const stop = subscribeProgress((frame) => {
+            if (partial) {
+                if (pending.length < MAX_PENDING_FRAMES)
+                    pending.push(frame);
+                return;
+            }
+            client.write(frame);
+        }, true);
+        if (stop)
+            client.cleanups.push(stop);
+        void (async () => {
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done || client.finished)
+                        break;
+                    const text = decoder.decode(value, { stream: true });
+                    client.write(text);
+                    partial = trailingPartialFrame(partial + text);
+                    if (!partial)
+                        flushPending();
+                }
+            }
+            catch { /* instance side ended */ }
+            client.finish();
+        })();
+        const headers = new Headers(upstream.headers);
+        headers.delete('content-length');
+        return new Response(client.stream, { status: upstream.status, headers });
+    };
+    const offlineStream = (request) => {
+        const client = open(request);
+        client.write(': gateway\n\n');
+        const stop = subscribeProgress((frame) => client.write(frame), true);
+        if (stop)
+            client.cleanups.push(stop);
+        // Reconnect to the merged stream once the instance is back.
+        const unwatch = options.instance?.onChange(() => { if (server.instanceReady)
+            client.finish(); });
+        if (unwatch)
+            client.cleanups.push(unwatch);
+        return new Response(client.stream, { status: 200, headers: SSE_HEADERS });
+    };
+    const history = async (request, context) => {
+        if (server.instanceReady)
+            return server.forward(request, context);
+        const runtimeId = context.url.searchParams.get('runtimeId') ?? 'gateway';
+        const after = Number(context.url.searchParams.get('after') ?? 0);
+        const cursor = Number.isSafeInteger(after) && after >= 0 ? after : 0;
+        const page = Object.freeze({
+            runtimeId,
+            items: Object.freeze([]),
+            oldestAvailableEventId: null,
+            latestEventId: cursor,
+            nextAfter: cursor,
+            hasMore: false,
+            gap: false,
+        });
+        return jsonResponse(200, { success: true, data: page }, { 'cache-control': 'no-store' });
+    };
+    const progress = (request) => {
+        const client = open(request);
+        client.write(': gateway packages\n\n');
+        const stop = subscribeProgress((frame) => client.write(frame));
+        if (stop)
+            client.cleanups.push(stop);
+        return new Response(client.stream, { status: 200, headers: SSE_HEADERS });
+    };
+    const registrations = [
+        server.route('GET', `${base}/events`, events, { summary: 'Console SSE stream (instance events merged with gateway events)', tags: ['console'] }),
+        server.route('GET', `${base}/events/history`, history, { summary: 'Console event history (empty while the instance is offline)', tags: ['console'] }),
+        server.route('GET', `${base}${GATEWAY_PACKAGES_PROGRESS_PATH}`, progress, { summary: 'Package transaction progress (SSE)', tags: ['gateway'] }),
+    ];
+    return () => { for (const unregister of registrations)
+        unregister(); };
+}
+/** The text after the last complete SSE frame (empty when the buffer ends on a frame boundary). */
+export function trailingPartialFrame(buffer) {
+    const normalized = buffer.replace(/\r\n/gu, '\n');
+    const boundary = normalized.lastIndexOf('\n\n');
+    return boundary < 0 ? normalized : normalized.slice(boundary + 2);
+}

package/lib/http/gateway-http-server.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The gateway's HTTP server (ADR 0054 §2 / §3): the project's only listener.
+ *
+ * Request flow:
+ * 1. gateway-owned routes ({@link GatewayHttpServer.route} / `ws`) — health, `/auth/*`,
+ *    terminal, the merged Console event stream, package progress; gateway-owned Console RPC
+ *    (`gateway.*`, `iam.*`, `onboarding.update`) inside `POST {base}/console/request`;
+ * 2. `{base}/…` — authenticated and authorized here, then forwarded with the principal;
+ * 3. anything else (plugin webhooks, adapter reverse WebSockets, static pages) — forwarded as-is;
+ *    those routes authenticate themselves.
+ *
+ * The instance being offline never takes gateway-owned routes down: forwarded requests get
+ * `503 { code: 'instance_unavailable', state }` with `Retry-After`; an instance that does not
+ * answer in time gives `504 { code: 'instance_timeout' }`, any other bridge failure
+ * `502 { code: 'instance_error' }` (mapped from {@link InstanceTransportError}).
+ */
+import { TokenRegistry, type HttpHandler, type HttpHostAddress, type HttpRouteRegistration, type ResolvedHttpConfig, type RouteContext, type RouteMeta, type WsHandle, type WsRouteOptions } from '@zhin.js/host-http';
+import { type InstanceTransport } from '@zhin.js/host-http/bridge';
+import { type GatewayConsoleRpc, type GatewayRpcHandler } from './console-rpc.js';
+export declare const DEFAULT_GATEWAY_RETRY_AFTER_SECONDS = 5;
+/** Default cap on a forwarded request body (uploads go through the instance). */
+export declare const DEFAULT_GATEWAY_MAX_REQUEST_BODY_BYTES: number;
+/** Where the server finds the instance; both are read per request. */
+export interface GatewayInstanceSource {
+    /** Current transport; undefined while no instance process exists. */
+    transport(): InstanceTransport | undefined;
+    /** Supervisor state reported in 503 bodies and `/pub/health` (e.g. `starting`, `crashed`). */
+    state(): string;
+}
+export interface GatewayHttpServerOptions {
+    /** Resolved `http.*` config: the primary listener plus `listeners` (extra ports, TLS). */
+    readonly http?: ResolvedHttpConfig;
+    readonly instance: GatewayInstanceSource;
+    /**
+     * Console authentication. The access provider (users, sessions, API tokens) is installed on it
+     * by the IAM module; defaults to a registry over `http.token`.
+     */
+    readonly tokenRegistry?: TokenRegistry;
+    readonly retryAfterSeconds?: number;
+    readonly maxRequestBodyBytes?: number;
+    /**
+     * Gateway-owned Console RPC (`gateway.*`) answered on `POST {base}/console/request`; every other
+     * RPC type on that route is forwarded to the instance unchanged.
+     */
+    readonly consoleRpc?: GatewayConsoleRpc;
+}
+/** One router, many listeners: every listener serves the same surface. */
+export declare class GatewayHttpServer {
+    #private;
+    readonly tokenRegistry: TokenRegistry;
+    readonly apiBase: string;
+    constructor(options: GatewayHttpServerOptions);
+    /** Registers a gateway-owned route; it takes precedence over the instance's routes. */
+    route(method: string, path: string, handler: HttpHandler, meta?: RouteMeta): HttpRouteRegistration;
+    /** Registers a gateway-owned WebSocket route. */
+    ws(path: string, options?: WsRouteOptions): WsHandle;
+    /**
+     * Answers further RPC types on `POST {base}/console/request` (e.g. `iam.*`); the handler checks
+     * the per-RPC permission itself. Returns an unregister function.
+     */
+    useConsoleRpc(handler: GatewayRpcHandler): () => void;
+    /** Whether an instance is connected and serving its route table. */
+    get instanceReady(): boolean;
+    /**
+     * Forwards one request to the instance (the router already authenticated and authorized it):
+     * the instance's response, or the documented 502 / 503 / 504 / 413 gateway responses.
+     */
+    forward(request: Request, context: RouteContext): Promise<Response>;
+    /** Handles one request without a socket (tests, local socket bridge). */
+    handle(request: Request, info?: {
+        readonly remoteAddress?: string;
+    }): Promise<Response>;
+    /** Primary listener address. */
+    get address(): HttpHostAddress | undefined;
+    /** Addresses of every bound listener, primary first. */
+    get addresses(): readonly HttpHostAddress[];
+    listen(): Promise<HttpHostAddress>;
+    close(): Promise<void>;
+    /**
+     * A `{base}/…` request from the local control socket (`gateway.http.request`, ADR 0054 §6).
+     * Without `token` the socket's owner check is the authentication: the request runs as
+     * {@link LOCAL_OWNER_PRINCIPAL}. With `token` (an explicit `ZHIN_CONSOLE_TOKEN`) it is
+     * authenticated like an HTTP request with that Bearer credential and runs — and is audited — as
+     * its principal. Either way the request takes the HTTP route table: gateway-owned routes (e.g.
+     * `{base}/auth/me`), the `POST {base}/console/request` split, then the instance. Event streams
+     * cannot be carried in one socket reply; the socket handler refuses them. Only the path and query
+     * of `path` are used; paths outside `{base}` are refused.
+     */
+    localRequest(input: {
+        readonly method: string;
+        readonly path: string;
+        readonly body?: string;
+        readonly token?: string;
+    }): Promise<Response>;
+}