@spine-event-engine/server 2.0.0-snapshot.25 → 2.0.0-snapshot.26

package/dist/browser/browser-server.js

@@ -34,6 +34,13 @@ const reservedPathSet = new Set(reservedSpineRpcPaths);
  * Hosts browser-facing Spine gateway routes independently from native server assembly.
  */
 export const browserServerImplementation = Object.freeze({
+    /**
+     * Starts a browser listener against the supplied native backend.
+     *
+     * @param native The native backend to expose through this browser host.
+     * @param input Browser configuration to validate before opening the listener.
+     * @returns The listening browser endpoint with coordinated native-backend cleanup.
+     */
     async open(native, input) {
         const running = BrowserServerValues.running(native);
         if (running !== undefined && !BrowserServerValues.isLoopback(running.host))
@@ -46,195 +53,15 @@ export const browserServerImplementation = Object.freeze({
             await BrowserServerValues.rollback(error, running === undefined ? [] : [() => running.close()]);
             throw error;
         }
-        const origins = BrowserServer.origins(options.origins);
-        const authRoutes = BrowserServer.authRoutes(options.authRoutes);
-        const activeAuth = new Set();
-        const maxActiveAuthRequests = options.maxActiveAuthRequests ?? 64;
-        if (!Number.isSafeInteger(maxActiveAuthRequests) || maxActiveAuthRequests < 1)
-            throw new Error("Browser maxActiveAuthRequests must be a positive safe integer.");
-        let draining = false;
-        const backendBaseUrls = native === undefined
-            ? options.backend === undefined
-                ? []
-                : BrowserServer.backendUrls(BrowserServerValues.backendUrlsFor(options.backend))
-            : Array.isArray(native)
-                ? BrowserServer.backendUrls(native)
-                : [
-                    typeof native === "string"
-                        ? native
-                        : BrowserServerValues.requiredRunning(running).baseUrl,
-                ];
-        const fixedNodes = backendBaseUrls.map((endpoint, index) => new ApplicationNode({ id: `fixed/${index.toString()}`, endpoint }));
-        let dynamic;
-        let stopDiscovery;
-        const forwarder = (dynamic = new DynamicUnaryForwarder({
-            create: async (node) => {
-                const manager = options.dynamicManagerFactory?.(node) ??
-                    new Http2SessionManager(node.endpoint, undefined, node.tlsServerName === undefined ? undefined : { servername: node.tlsServerName });
-                const client = new NativeSubscriptionCreator(createGrpcTransport({
-                    ...BrowserServer.dynamicTransportOptions(node),
-                    sessionManager: manager,
-                }));
-                return {
-                    forward: client.forward.bind(client),
-                    subscribe: client.subscribe.bind(client),
-                    activate: client.activate.bind(client),
-                    cancel: client.cancel.bind(client),
-                    dispose: client.dispose.bind(client),
-                    close: async () => {
-                        manager.abort();
-                    },
-                };
-            },
-        }));
-        const creator = new DynamicSubscriptionCreator(dynamic);
-        const bindings = options.bindings ??
-            new InMemorySubscriptionBindings({
-                nextId: () => globalThis.crypto.randomUUID(),
-                dispose: (definition, signal) => creator.cancel({ wire: definition }, signal),
-            });
-        const requests = BrowserServer.requests(options);
-        const admission = options.publicAccess === true
-            ? { publicAccess: true }
-            : { sessions: options.sessions };
-        const unary = new UnaryGateway({
-            ...(options.registry === undefined ? {} : { registry: options.registry }),
-            maxRequestBytes: 1_048_576,
-            ...admission,
-            authorize: options.authorize,
-            contexts: options.contexts,
-            clock: options.clock,
-            forward: forwarder.forward.bind(forwarder),
-        });
-        const subscriptions = new SubscriptionGateway({
-            bindings,
-            ...admission,
-            authorize: options.authorize,
-            contexts: options.contexts,
-            clock: options.clock,
-            creator,
-        });
-        try {
-            if (options.discovery !== undefined)
-                stopDiscovery = await BrowserServerValues.watch(options.discovery, dynamic);
-            else
-                await dynamic.reconcile(fixedNodes);
-            if (isDurableSubscriptionBindings(bindings))
-                attachDurableSubscriptionCleanup(bindings, (definition, signal) => creator.cancel({ wire: definition }, signal));
-            const durableBindings = bindings;
-            if (durableBindings.recoverActive !== undefined) {
-                const now = options.clock.now();
-                const nowMs = Number(now.seconds.toString()) * 1_000 +
-                    Math.floor(Number(now.nanos.toString()) / 1_000_000);
-                if (Number.isSafeInteger(nowMs))
-                    await durableBindings.recoverActive({
-                        nowMs,
-                        onDefinition: async (definition, whenExpires) => {
-                            await creator.rehydrate(definition);
-                            subscriptions.scheduleExpiry(whenExpires);
-                        },
-                    });
-            }
-        }
-        catch (error) {
-            const failures = [error];
-            for (const cleanup of [
-                () => subscriptions.close(),
-                () => stopDiscovery?.(),
-                () => dynamic.close(),
-                () => running?.close(),
-            ])
-                try {
-                    await cleanup();
-                }
-                catch (cleanupError) {
-                    failures.push(cleanupError);
-                }
-            if (failures.length === 1)
-                throw error;
-            throw new AggregateError(failures, "Browser subscription recovery startup rollback failed.");
-        }
-        const services = createNativeGatewayServices({ unary, subscriptions, requests });
-        const handler = connectNodeAdapter({
-            routes: (router) => {
-                router.service(AuthenticationService, services.authentication);
-                router.service(CommandService, services.command);
-                router.service(QueryService, services.query);
-                router.service(SubscriptionService, services.subscription);
-            },
-            readMaxBytes: options.readMaxBytes,
-            writeMaxBytes: options.writeMaxBytes,
-        });
-        const server = http.createServer((request, response) => {
-            if (draining) {
-                response.statusCode = 503;
-                response.end();
-                return;
-            }
-            const path = request.url ?? "";
-            const auth = authRoutes.get(path);
-            if (auth !== undefined && request.method === auth.method) {
-                if (activeAuth.size >= maxActiveAuthRequests) {
-                    response.statusCode = 503;
-                    response.end();
-                    return;
-                }
-                void BrowserServer.dispatchAuth(request, response, auth, activeAuth, options.writeMaxBytes);
-                return;
-            }
-            if (auth !== undefined) {
-                const origin = request.headers.origin;
-                if (request.method === "OPTIONS" && origin !== undefined && auth.origins.includes(origin)) {
-                    response.setHeader("access-control-allow-origin", origin);
-                    response.setHeader("access-control-allow-methods", `${auth.method},OPTIONS`);
-                    response.statusCode = 204;
-                }
-                else
-                    response.statusCode = request.method === "OPTIONS" ? 403 : 405;
-                response.end();
-                return;
-            }
-            const origin = request.headers.origin;
-            if (origin === undefined || !origins.has(origin)) {
-                response.statusCode = 403;
-                response.end();
-                return;
-            }
-            response.setHeader("access-control-allow-origin", origin);
-            response.setHeader("access-control-allow-credentials", "true");
-            response.setHeader("access-control-expose-headers", "grpc-status,grpc-message");
-            response.setHeader("vary", "Origin");
-            if (request.method === "OPTIONS") {
-                response.setHeader("access-control-allow-methods", "POST,OPTIONS");
-                response.setHeader("access-control-allow-headers", "authorization,content-type,connect-protocol-version,x-csrf-token");
-                response.setHeader("access-control-max-age", "600");
-                response.statusCode = 204;
-                response.end();
-                return;
-            }
-            handler(request, response);
-        });
-        let address;
-        try {
-            address = await BrowserServer.listen(server, options.host, options.port);
-        }
-        catch (error) {
-            const cleanup = await Promise.allSettled([
-                subscriptions.close(),
-                stopDiscovery?.(),
-                dynamic.close(),
-                BrowserServer.closeListener(server),
-                running?.close(),
-            ]);
-            const failures = cleanup.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
-            if (failures.length > 0)
-                throw new AggregateError([error, ...failures], "Server browser startup rollback failed.");
-            throw error;
-        }
-        return new RunningBrowserServer(server, running, subscriptions, address, activeAuth, () => {
-            draining = true;
-        }, stopDiscovery, dynamic);
+        return BrowserServerValues.openWithOptions(native, running, options);
     },
+    /**
+     * Starts the browser host and registers it for process-level shutdown.
+     *
+     * @param nativeOrOptions The local Server to start, or options for a standalone browser gateway.
+     * @param suppliedOptions Browser configuration when a local Server is supplied separately.
+     * @returns The running host registered with the process coordinator.
+     */
     async run(nativeOrOptions, suppliedOptions) {
         const options = suppliedOptions ?? nativeOrOptions;
         if (nativeOrOptions instanceof Server) {
@@ -250,6 +77,13 @@ export const browserServerImplementation = Object.freeze({
             : await BrowserServer.open(native, options);
         return ProcessServerCoordinator.add(running, native === undefined ? undefined : ServerEnvironment.instance(), undefined, () => undefined);
     },
+    /**
+     * Applies listener defaults and checks browser admission configuration before startup.
+     *
+     * @param mode Whether a native server is started locally or supplied as a separate backend.
+     * @param input Browser configuration to validate before opening the listener.
+     * @returns Normalized listener options after all preflight checks pass.
+     */
     preflight(mode, input) {
         const options = {
             ...input,
@@ -277,6 +111,12 @@ export const browserServerImplementation = Object.freeze({
             throw new Error("Browser maxActiveAuthRequests must be a positive safe integer.");
         return options;
     },
+    /**
+     * Builds credential extraction and transport-fact adapters for browser requests.
+     *
+     * @param options Browser listener, admission, and backend configuration.
+     * @returns Adapters that the gateway uses to admit each incoming request.
+     */
     requests(options) {
         return {
             credential: (context) => {
@@ -301,6 +141,12 @@ export const browserServerImplementation = Object.freeze({
             },
         };
     },
+    /**
+     * Validates a nonempty set of unique canonical HTTP(S) origins.
+     *
+     * @param values Browser origins to validate and deduplicate.
+     * @returns The validated origins for exact admission checks.
+     */
     origins(values) {
         const origins = new Set(values.map((value) => {
             let origin;
@@ -323,6 +169,12 @@ export const browserServerImplementation = Object.freeze({
             throw new Error("Server browser origins must be unique and non-empty.");
         return origins;
     },
+    /**
+     * Rejects backend URLs containing paths, credentials, queries, or fragments.
+     *
+     * @param value The backend origin to validate.
+     * @returns The original canonical backend origin.
+     */
     backendUrl(value) {
         let backend;
         try {
@@ -342,6 +194,12 @@ export const browserServerImplementation = Object.freeze({
         }
         return value;
     },
+    /**
+     * Validates a nonempty list of distinct native backend origins.
+     *
+     * @param values Native backend origins in routing order.
+     * @returns The validated backend origins in their configured order.
+     */
     backendUrls(values) {
         if (values.length < 1)
             throw new Error("Server browser backends must contain at least one origin.");
@@ -350,6 +208,12 @@ export const browserServerImplementation = Object.freeze({
             throw new Error("Server browser backends must be unique canonical HTTP(S) origins.");
         return urls;
     },
+    /**
+     * Selects the node endpoint and its configured TLS server name.
+     *
+     * @param node The application node whose native transport is being configured.
+     * @returns Transport settings preserving the node's TLS server-name override.
+     */
     dynamicTransportOptions(node) {
         return {
             baseUrl: node.endpoint,
@@ -358,6 +222,12 @@ export const browserServerImplementation = Object.freeze({
                 : { nodeOptions: { servername: node.tlsServerName } }),
         };
     },
+    /**
+     * Checks admission ports and production subscription-persistence requirements.
+     *
+     * @param options Browser listener, admission, and backend configuration.
+     * @param production Whether production persistence requirements must be enforced.
+     */
     requireDurableBindings(options, production) {
         const supplied = options;
         const standalone = options.backend !== undefined || options.discovery !== undefined;
@@ -396,6 +266,12 @@ export const browserServerImplementation = Object.freeze({
                 !bindings.namespace.trim()))
             throw new Error("Production standalone browser server requires named durable subscription bindings.");
     },
+    /**
+     * Validates authentication routes and rejects duplicate or reserved RPC paths.
+     *
+     * @param routes Optional HTTP authentication endpoints to validate and index.
+     * @returns Validated routes indexed by their exact HTTP path.
+     */
     authRoutes(routes) {
         const result = new Map();
         for (const route of routes ?? []) {
@@ -421,6 +297,16 @@ export const browserServerImplementation = Object.freeze({
         }
         return result;
     },
+    /**
+     * Executes an authentication route within its configured origin, size, and time bounds.
+     *
+     * @param request The incoming HTTP request.
+     * @param response The HTTP response to complete with the route outcome.
+     * @param route The matched authentication endpoint and its admission constraints.
+     * @param active Controllers tracked so shutdown can abort active authentication requests.
+     * @param writeMaxBytes The existing transport bound for the authentication response body.
+     * @returns Completion after the HTTP response and request cleanup settle.
+     */
     async dispatchAuth(request, response, route, active, writeMaxBytes) {
         const origin = request.headers.origin;
         if ((origin === undefined && route.allowMissingOrigin !== true) ||
@@ -528,6 +414,14 @@ export const browserServerImplementation = Object.freeze({
             active.delete(controller);
         }
     },
+    /**
+     * Binds the HTTP listener and propagates startup errors.
+     *
+     * @param server The HTTP listener being started or stopped.
+     * @param host The interface address on which to bind the listener.
+     * @param port The requested listener port; zero requests an ephemeral port.
+     * @returns The actual bound address, including an allocated ephemeral port.
+     */
     listen(server, host, port) {
         return new Promise((resolve, reject) => {
             const onError = (error) => {
@@ -540,6 +434,12 @@ export const browserServerImplementation = Object.freeze({
             });
         });
     },
+    /**
+     * Stops accepting connections and drains the HTTP listener.
+     *
+     * @param server The HTTP listener being started or stopped.
+     * @returns Completion after the listener closes; rejects on a close error.
+     */
     closeListener(server) {
         return new Promise((resolve, reject) => {
             if (!server.listening) {
@@ -570,22 +470,457 @@ export const browserServerTestAccess = Object.freeze({
 });
 const BrowserServer = browserServerImplementation;
 const BrowserServerValues = Object.freeze({
+    /**
+     * Builds the admitted browser listener from normalized options.
+     *
+     * @param native The native backend to expose through this browser host.
+     * @param running The local native listener to include in coordinated cleanup, when present.
+     * @param options Browser listener, admission, and backend configuration.
+     * @returns The listening host after membership and durable recovery are ready.
+     */
+    async openWithOptions(native, running, options) {
+        const activeAuth = new Set();
+        let draining = false;
+        const { dynamic, requests, unary, subscriptions, stopDiscovery } = await BrowserServerValues.readyGraph(native, running, options);
+        const server = BrowserServerValues.admittedListener(options, activeAuth, () => draining, unary, subscriptions, requests);
+        return BrowserServerValues.finishBrowser({
+            options,
+            running,
+            subscriptions,
+            stopDiscovery,
+            dynamic,
+            activeAuth,
+            server,
+            onDrain: () => {
+                draining = true;
+            },
+        });
+    },
+    /**
+     * Starts discovery and durable recovery after assembling the gateway graph.
+     *
+     * @param native The native backend to expose through this browser host.
+     * @param running The local native listener to include in coordinated cleanup, when present.
+     * @param options Browser listener, admission, and backend configuration.
+     * @returns Gateway collaborators and the discovery cleanup callback, when discovery is configured.
+     */
+    async readyGraph(native, running, options) {
+        const graph = BrowserServerValues.prepareBrowser(native, running, options);
+        const stopDiscovery = await BrowserServerValues.startMembership(options, running, graph.fixedNodes, graph.dynamic, graph.creator, graph.bindings, graph.subscriptions);
+        return { ...graph, stopDiscovery };
+    },
+    /**
+     * Applies configured browser origin and auth-route policy to the listener.
+     *
+     * @param options Browser listener, admission, and backend configuration.
+     * @param activeAuth Controllers tracked for cancellation during browser-host shutdown.
+     * @param draining Reports whether shutdown has stopped admission of new requests.
+     * @param unary The gateway that admits and forwards unary Spine requests.
+     * @param subscriptions The gateway managing admitted browser subscriptions.
+     * @param requests Adapters for extracting credentials and transport facts from HTTP headers.
+     * @returns An HTTP server configured with admission routes but not yet listening.
+     */
+    admittedListener(options, activeAuth, draining, unary, subscriptions, requests) {
+        const maxActiveAuthRequests = options.maxActiveAuthRequests ?? 64;
+        if (!Number.isSafeInteger(maxActiveAuthRequests) || maxActiveAuthRequests < 1)
+            throw new Error("Browser maxActiveAuthRequests must be a positive safe integer.");
+        return BrowserServerValues.createListener({
+            options,
+            origins: BrowserServer.origins(options.origins),
+            authRoutes: BrowserServer.authRoutes(options.authRoutes),
+            activeAuth,
+            maxActiveAuthRequests,
+            draining,
+            unary,
+            subscriptions,
+            requests,
+        });
+    },
+    /**
+     * Builds one native backend and the admission collaborators before discovery.
+     *
+     * @param native The native backend to expose through this browser host.
+     * @param running The local native listener to include in coordinated cleanup, when present.
+     * @param options Browser listener, admission, and backend configuration.
+     * @returns The backend, binding, and admission collaborators needed for startup.
+     */
+    prepareBrowser(native, running, options) {
+        const fixedNodes = BrowserServerValues.fixedNodes(native, running, options);
+        const dynamic = BrowserServerValues.dynamic(options);
+        const creator = new DynamicSubscriptionCreator(dynamic);
+        const bindings = BrowserServerValues.bindings(options, creator);
+        const { requests, unary, subscriptions } = BrowserServerValues.admission(options, dynamic, creator, bindings);
+        return { fixedNodes, dynamic, creator, bindings, requests, unary, subscriptions };
+    },
+    /**
+     * Returns durable bindings or constructs the local in-memory admission port.
+     *
+     * @param options Browser listener, admission, and backend configuration.
+     * @param creator The native subscription adapter used for creation, recovery, and cancellation.
+     * @returns The supplied binding store or a new process-local store with native cancellation.
+     */
+    bindings(options, creator) {
+        return (options.bindings ??
+            new InMemorySubscriptionBindings({
+                nextId: () => globalThis.crypto.randomUUID(),
+                dispose: (definition, signal) => creator.cancel({ wire: definition }, signal),
+            }));
+    },
+    /**
+     * Publishes one assembled listener after startup rollback is established.
+     *
+     * @param input Started browser resources and their coordinated shutdown callbacks.
+     * @returns The published browser endpoint with coordinated resource cleanup.
+     */
+    async finishBrowser(input) {
+        const address = await BrowserServerValues.listenStarted(input);
+        return new RunningBrowserServer(input.server, input.running, input.subscriptions, address, input.activeAuth, input.onDrain, input.stopDiscovery, input.dynamic);
+    },
+    /**
+     * Rolls back all started browser resources when listener bind fails.
+     *
+     * @param input Started browser resources and their coordinated shutdown callbacks.
+     * @returns The bound listener address; startup failures trigger resource cleanup.
+     */
+    async listenStarted(input) {
+        try {
+            return await BrowserServer.listen(input.server, input.options.host, input.options.port);
+        }
+        catch (error) {
+            const cleanup = await Promise.allSettled([
+                input.subscriptions.close(),
+                input.stopDiscovery?.(),
+                input.dynamic.close(),
+                BrowserServer.closeListener(input.server),
+                input.running?.close(),
+            ]);
+            const failures = cleanup.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+            if (failures.length > 0)
+                throw new AggregateError([error, ...failures], "Server browser startup rollback failed.");
+            throw error;
+        }
+    },
+    /**
+     * Resolves fixed native backends without changing dynamic discovery behavior.
+     *
+     * @param native The native backend to expose through this browser host.
+     * @param running The local native listener to include in coordinated cleanup, when present.
+     * @param options Browser listener, admission, and backend configuration.
+     * @returns Configured fixed endpoints represented as application nodes.
+     */
+    fixedNodes(native, running, options) {
+        const urls = native === undefined
+            ? options.backend === undefined
+                ? []
+                : BrowserServer.backendUrls(BrowserServerValues.backendUrlsFor(options.backend))
+            : Array.isArray(native)
+                ? BrowserServer.backendUrls(native)
+                : [
+                    typeof native === "string"
+                        ? native
+                        : BrowserServerValues.requiredRunning(running).baseUrl,
+                ];
+        return urls.map((endpoint, index) => new ApplicationNode({ id: `fixed/${index.toString()}`, endpoint }));
+    },
+    /**
+     * Creates the dynamically reconciled native transport adapter.
+     *
+     * @param options Browser listener, admission, and backend configuration.
+     * @returns A forwarder that creates native clients as node membership changes.
+     */
+    dynamic(options) {
+        return new DynamicUnaryForwarder({
+            create: (node) => BrowserServerValues.nativeClient(node, options),
+        });
+    },
+    /**
+     * Opens a native client with the configured reader proof producer.
+     *
+     * @param node The application node whose native transport is being configured.
+     * @param options Browser listener, admission, and backend configuration.
+     * @returns Native RPC operations and a callback that aborts their HTTP/2 session manager.
+     */
+    async nativeClient(node, options) {
+        const manager = options.dynamicManagerFactory?.(node) ??
+            new Http2SessionManager(node.endpoint, undefined, node.tlsServerName === undefined ? undefined : { servername: node.tlsServerName });
+        const client = new NativeSubscriptionCreator(createGrpcTransport({
+            ...BrowserServer.dynamicTransportOptions(node),
+            sessionManager: manager,
+        }), options.forwardingProof === undefined
+            ? undefined
+            : {
+                issuer: options.forwardingProof,
+                maxBytes: options.readMaxBytes,
+            });
+        return {
+            forward: client.forward.bind(client),
+            subscribe: client.subscribe.bind(client),
+            activate: client.activate.bind(client),
+            cancel: client.cancel.bind(client),
+            dispose: client.dispose.bind(client),
+            close: async () => {
+                manager.abort();
+            },
+        };
+    },
+    /**
+     * Creates unary and subscription admission around one reader-aware backend.
+     *
+     * @param options Browser listener, admission, and backend configuration.
+     * @param dynamic The native forwarder following current application-node membership.
+     * @param creator The native subscription adapter used for creation, recovery, and cancellation.
+     * @param bindings The store retaining browser-to-native subscription bindings.
+     * @returns Request adapters and gateways sharing the configured admission policy.
+     */
+    admission(options, dynamic, creator, bindings) {
+        const requests = BrowserServer.requests(options);
+        const admission = options.publicAccess === true
+            ? { publicAccess: true }
+            : { sessions: options.sessions };
+        const unary = new UnaryGateway({
+            ...(options.registry === undefined ? {} : { registry: options.registry }),
+            maxRequestBytes: 1_048_576,
+            ...admission,
+            authorize: options.authorize,
+            contexts: options.contexts,
+            clock: options.clock,
+            forward: dynamic.forward.bind(dynamic),
+        });
+        const subscriptions = new SubscriptionGateway({
+            bindings,
+            ...admission,
+            authorize: options.authorize,
+            contexts: options.contexts,
+            clock: options.clock,
+            creator,
+        });
+        return { requests, unary, subscriptions };
+    },
+    /**
+     * Starts discovery and rehydrates only durable subscriptions with reader identity.
+     *
+     * @param options Browser listener, admission, and backend configuration.
+     * @param running The local native listener to include in coordinated cleanup, when present.
+     * @param fixedNodes Backend nodes used when no discovery source is configured.
+     * @param dynamic The native forwarder following current application-node membership.
+     * @param creator The native subscription adapter used for creation, recovery, and cancellation.
+     * @param bindings The store retaining browser-to-native subscription bindings.
+     * @param subscriptions The gateway managing admitted browser subscriptions.
+     * @returns The discovery stop callback, or no callback for fixed membership.
+     */
+    async startMembership(options, running, fixedNodes, dynamic, creator, bindings, subscriptions) {
+        let stopDiscovery;
+        try {
+            if (options.discovery !== undefined)
+                stopDiscovery = await BrowserServerValues.watch(options.discovery, dynamic);
+            else
+                await dynamic.reconcile(fixedNodes);
+            if (isDurableSubscriptionBindings(bindings))
+                attachDurableSubscriptionCleanup(bindings, (definition, signal) => creator.cancel({ wire: definition }, signal));
+            await BrowserServerValues.recoverBindings(options, bindings, creator, subscriptions);
+            return stopDiscovery;
+        }
+        catch (error) {
+            return BrowserServerValues.rollbackMembership(error, running, subscriptions, stopDiscovery, dynamic);
+        }
+    },
+    /**
+     * Closes discovery, admission and native listeners after recovery failure.
+     *
+     * @param error The startup failure to preserve while cleanup is attempted.
+     * @param running The local native listener to include in coordinated cleanup, when present.
+     * @param subscriptions The gateway managing admitted browser subscriptions.
+     * @param stopDiscovery The callback that stops discovery updates, when discovery is configured.
+     * @param dynamic The native forwarder following current application-node membership.
+     * @returns No value; the startup failure is rethrown with any cleanup failures.
+     */
+    async rollbackMembership(error, running, subscriptions, stopDiscovery, dynamic) {
+        const failures = [error];
+        for (const cleanup of [
+            () => subscriptions.close(),
+            () => stopDiscovery?.(),
+            () => dynamic.close(),
+            () => running?.close(),
+        ])
+            try {
+                await cleanup();
+            }
+            catch (cleanupError) {
+                failures.push(cleanupError);
+            }
+        if (failures.length === 1)
+            throw error;
+        throw new AggregateError(failures, "Browser subscription recovery startup rollback failed.");
+    },
+    /**
+     * Restores live reader-bound definitions after membership is ready.
+     *
+     * @param options Browser listener, admission, and backend configuration.
+     * @param bindings The store retaining browser-to-native subscription bindings.
+     * @param creator The native subscription adapter used for creation, recovery, and cancellation.
+     * @param subscriptions The gateway managing admitted browser subscriptions.
+     * @returns Completion after retained definitions are rehydrated and expiry is scheduled.
+     */
+    async recoverBindings(options, bindings, creator, subscriptions) {
+        if (bindings.recoverActive === undefined)
+            return;
+        const now = options.clock.now();
+        const nowMs = Number(now.seconds.toString()) * 1_000 + Math.floor(Number(now.nanos.toString()) / 1_000_000);
+        if (!Number.isSafeInteger(nowMs))
+            return;
+        await bindings.recoverActive({
+            nowMs,
+            onDefinition: async (definition, whenExpires) => {
+                await creator.rehydrate(definition);
+                subscriptions.scheduleExpiry(whenExpires);
+            },
+        });
+    },
+    /**
+     * Binds admitted gateway services to one HTTP listener.
+     *
+     * @param input Gateway services and HTTP routing policy for this listener.
+     * @returns The unbound HTTP server serving the admitted Spine routes.
+     */
+    createListener(input) {
+        const services = createNativeGatewayServices({
+            unary: input.unary,
+            subscriptions: input.subscriptions,
+            requests: input.requests,
+        });
+        const handler = connectNodeAdapter({
+            routes: (router) => {
+                router.service(AuthenticationService, services.authentication);
+                router.service(CommandService, services.command);
+                router.service(QueryService, services.query);
+                router.service(SubscriptionService, services.subscription);
+            },
+            readMaxBytes: input.options.readMaxBytes,
+            writeMaxBytes: input.options.writeMaxBytes,
+        });
+        const context = { ...input, handler };
+        return http.createServer((request, response) => {
+            BrowserServerValues.routeRequest(request, response, context);
+        });
+    },
+    /**
+     * Applies drain, authentication and RPC routing to one HTTP request.
+     *
+     * @param request The incoming HTTP request.
+     * @param response The HTTP response to complete with the route outcome.
+     * @param context Listener admission policy, active requests, and the RPC routing callback.
+     */
+    routeRequest(request, response, context) {
+        if (context.draining()) {
+            response.statusCode = 503;
+            response.end();
+            return;
+        }
+        const auth = context.authRoutes.get(request.url ?? "");
+        if (auth !== undefined) {
+            BrowserServerValues.authRequest(request, response, auth, context);
+            return;
+        }
+        BrowserServerValues.rpcRequest(request, response, context);
+    },
+    /**
+     * Handles the configured browser authentication route and its preflight.
+     *
+     * @param request The incoming HTTP request.
+     * @param response The HTTP response to complete with the route outcome.
+     * @param auth The authentication route matched by the request path.
+     * @param context Listener admission policy, active requests, and the RPC routing callback.
+     */
+    authRequest(request, response, auth, context) {
+        if (request.method === auth.method) {
+            if (context.activeAuth.size >= context.maxActiveAuthRequests) {
+                response.statusCode = 503;
+                response.end();
+                return;
+            }
+            void BrowserServer.dispatchAuth(request, response, auth, context.activeAuth, context.options.writeMaxBytes);
+            return;
+        }
+        const origin = request.headers.origin;
+        if (request.method === "OPTIONS" && origin !== undefined && auth.origins.includes(origin)) {
+            response.setHeader("access-control-allow-origin", origin);
+            response.setHeader("access-control-allow-methods", `${auth.method},OPTIONS`);
+            response.statusCode = 204;
+        }
+        else
+            response.statusCode = request.method === "OPTIONS" ? 403 : 405;
+        response.end();
+    },
+    /**
+     * Checks browser origin admission before a Connect or gRPC request.
+     *
+     * @param request The incoming HTTP request.
+     * @param response The HTTP response to complete with the route outcome.
+     * @param context Listener admission policy, active requests, and the RPC routing callback.
+     */
+    rpcRequest(request, response, context) {
+        const origin = request.headers.origin;
+        if (origin === undefined || !context.origins.has(origin)) {
+            response.statusCode = 403;
+            response.end();
+            return;
+        }
+        response.setHeader("access-control-allow-origin", origin);
+        response.setHeader("access-control-allow-credentials", "true");
+        response.setHeader("access-control-expose-headers", "grpc-status,grpc-message");
+        response.setHeader("vary", "Origin");
+        if (request.method === "OPTIONS") {
+            response.setHeader("access-control-allow-methods", "POST,OPTIONS");
+            response.setHeader("access-control-allow-headers", "authorization,content-type,connect-protocol-version,x-csrf-token");
+            response.setHeader("access-control-max-age", "600");
+            response.statusCode = 204;
+            response.end();
+            return;
+        }
+        context.handler(request, response);
+    },
+    /**
+     * Subscribes the native forwarder to application-node discovery changes.
+     *
+     * @param source The source of application-node membership changes.
+     * @param forwarder The native forwarder to reconcile when membership changes.
+     * @returns The callback that stops watching node discovery.
+     */
     async watch(source, forwarder) {
         return await source.watch((nodes) => {
             void forwarder.reconcile(nodes);
         });
     },
+    /**
+     * Returns the local native listener or rejects an absent backend.
+     *
+     * @param value The possibly absent local native listener.
+     * @returns The supplied listener, or throws when it is absent.
+     */
     requiredRunning(value) {
         if (value === undefined)
             throw new Error("Browser server local backend is absent.");
         return value;
     },
+    /**
+     * Checks IPv4 loopback addresses and the supported IPv6 loopback forms.
+     *
+     * @param host The address to test for local loopback membership.
+     * @returns Whether the address denotes a supported loopback interface.
+     */
     isLoopback(host) {
         if (host === "::1" || host === "::ffff:127.0.0.1")
             return true;
         const match = /^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/u.exec(host);
         return match?.slice(1).every((part) => Number(part) <= 255) === true;
     },
+    /**
+     * Calls every supplied startup cleanup and preserves any cleanup failures.
+     *
+     * @param error The startup failure to preserve while cleanup is attempted.
+     * @param cleanups Startup cleanup callbacks to attempt in the supplied order.
+     * @returns No value; the original failure or an aggregate of startup and cleanup failures is thrown.
+     */
     async rollback(error, cleanups) {
         const failures = [error];
         for (const cleanup of cleanups)
@@ -599,17 +934,35 @@ const BrowserServerValues = Object.freeze({
             throw error;
         throw new AggregateError(failures, "Browser server startup rollback failed.");
     },
+    /**
+     * Returns the first native subscription client or rejects an empty configuration.
+     *
+     * @param values Native subscription clients in configured order.
+     * @returns The first configured client, or throws when none exists.
+     */
     firstCreator(values) {
         const creator = values[0];
         if (creator === undefined)
             throw new Error("Browser server backend is absent.");
         return creator;
     },
+    /**
+     * Returns an already running native listener from the backend configuration.
+     *
+     * @param native The native backend to expose through this browser host.
+     * @returns The supplied running listener, or undefined for URL-based or absent backends.
+     */
     running(native) {
         return native === undefined || typeof native === "string" || Array.isArray(native)
             ? undefined
             : native;
     },
+    /**
+     * Reads exactly one of the singular or plural backend URL options.
+     *
+     * @param backend The singular or plural backend URL configuration to inspect.
+     * @returns The configured backend origins without applying URL validation.
+     */
     backendUrlsFor(backend) {
         const source = backend;
         if (typeof source.baseUrl === "string" && source.baseUrls === undefined)
@@ -623,6 +976,9 @@ const BrowserServerValues = Object.freeze({
         throw new Error("Server browser backend must configure exactly one of baseUrl or baseUrls.");
     },
 });
+/**
+ * Closes the browser listener, discovery, admission and native backend together.
+ */
 class RunningBrowserServer {
     #server;
     #subscriptions;
@@ -641,6 +997,18 @@ class RunningBrowserServer {
     #discoveryStopped = false;
     #dynamicClosed = false;
     #nativeClosed = false;
+    /**
+     * Stores the running browser resources and exposes their bound address.
+     *
+     * @param server The HTTP listener being started or stopped.
+     * @param native The native backend to expose through this browser host.
+     * @param subscriptions The gateway managing admitted browser subscriptions.
+     * @param address The actual address returned when the browser listener bound successfully.
+     * @param activeAuth Controllers tracked for cancellation during browser-host shutdown.
+     * @param onDrain Stops admission of new browser requests before resources are closed.
+     * @param stopDiscovery The callback that stops discovery updates, when discovery is configured.
+     * @param dynamic The native forwarder following current application-node membership.
+     */
     constructor(server, native, subscriptions, address, activeAuth, onDrain, stopDiscovery, dynamic) {
         this.#server = server;
         this.#native = native;
@@ -654,6 +1022,11 @@ class RunningBrowserServer {
         const host = this.host.includes(":") && !this.host.startsWith("[") ? `[${this.host}]` : this.host;
         this.baseUrl = `http://${host}:${this.port.toString()}`;
     }
+    /**
+     * Returns a shared promise for concurrent shutdown attempts and permits retry after a failed attempt.
+     *
+     * @returns The shared shutdown attempt, which rejects if any cleanup phase fails.
+     */
     close() {
         this.#closed ??= this.#closeOnce().catch((error) => {
             this.#closed = undefined;
@@ -661,6 +1034,11 @@ class RunningBrowserServer {
         });
         return this.#closed;
     }
+    /**
+     * Stops admission and attempts each unfinished shutdown phase.
+     *
+     * @returns Completion after all unfinished phases are attempted; rejects with collected failures.
+     */
     async #closeOnce() {
         this.#onDrain();
         for (const controller of this.#activeAuth)
@@ -690,6 +1068,14 @@ class RunningBrowserServer {
             throw primary;
         }
     }
+    /**
+     * Marks successful shutdown work and collects failures without stopping later phases.
+     *
+     * @param operation An unfinished shutdown operation, or undefined when there is nothing to await.
+     * @param onSuccess Records completion so a later shutdown retry skips this phase.
+     * @param failures The shared collection receiving failures from shutdown phases.
+     * @returns Completion after success is recorded or the failure is collected.
+     */
     async #phase(operation, onSuccess, failures) {
         if (operation === undefined)
             return;
@@ -701,6 +1087,11 @@ class RunningBrowserServer {
             failures.push(error);
         }
     }
+    /**
+     * Returns the in-flight listener shutdown and resets it after settlement.
+     *
+     * @returns The current listener-close attempt or a newly started attempt.
+     */
     #closeListenerPhase() {
         const current = this.#listenerClose;
         if (current !== undefined)