@spine-event-engine/server 2.0.0-snapshot.2 → 2.0.0-snapshot.21

package/dist/server/server.js

@@ -15,17 +15,18 @@ import * as http2 from "node:http2";
 import { connectNodeAdapter } from "@connectrpc/connect-node";
 import { BoundedContext, BoundedContextBuilder, boundedContextAccess, } from "../context/bounded-context.js";
 import { SpineServices, spineServicesAccess, } from "../services/spine-services.js";
-import { BrowserServer } from "./browser-server.js";
+import { RegisteredTargets } from "../services/registered-targets.js";
 import { ProcessServerCoordinator } from "./process-server-coordinator.js";
 import { CloseErrors, RetryableCloseGroup } from "./retryable-close.js";
 import { ServerEnvironment, serverEnvironmentAccess } from "./server-environment.js";
-import { EnvironmentType } from "./environment.js";
 const defaultHost = "127.0.0.1";
 const defaultPort = 0;
 const defaultMessageMaxBytes = 4_194_304;
 const maximumMessageMaxBytes = 0xffff_ffff;
 const gracefulSessionDrainMs = 100;
 const runningContexts = new WeakMap();
+const serverHosts = new WeakMap();
+const assemblingStands = new WeakMap();
 /**
  * Configures and starts local Spine Connect/gRPC-compatible services.
  *
@@ -43,7 +44,6 @@ export class Server {
     #resources = [];
     #listenerLifecycles = [];
     #services;
-    #browser;
     #environment;
     #starting;
     #startingOwnership;
@@ -64,8 +64,8 @@ export class Server {
         this.#contexts.push(...(options.contexts ?? []));
         this.#resources.push(...(options.resources ?? []));
         this.#services = options.services ?? {};
-        this.#browser = options.browser;
         this.#environment = ServerEnvironment.instance();
+        serverHosts.set(this, this.#host);
     }
     /**
      * Creates a local-only server builder for one port.
@@ -169,8 +169,7 @@ export class Server {
      * Concurrent calls on one builder return one managed handle. Run-managed
      * siblings share an active generation but reject while caller-managed
      * ownership is active. The final local environment-owning run retirement
-     * permanently closes its environment; a standalone browser Gateway remains
-     * signal-managed but never owns or closes that environment. A failed final
+     * permanently closes its environment. A failed final
      * close stays retryable through `close()` or a later process signal.
      * Caller-managed servers never close their environment.
      *
@@ -180,10 +179,8 @@ export class Server {
         const current = this.#run;
         if (current !== undefined)
             return current;
-        const environment = ServerValues.isStandaloneBrowser(this.#browser)
-            ? undefined
-            : this.#environment;
-        const running = this.#start("server").then((server) => ProcessServerCoordinator.add(server, environment, environment === undefined ? undefined : serverEnvironmentAccess.loggerFor(environment), () => {
+        const environment = this.#environment;
+        const running = this.#start("server").then((server) => ProcessServerCoordinator.add(server, environment, serverEnvironmentAccess.loggerFor(environment), () => {
             if (this.#run === running) {
                 this.#run = undefined;
             }
@@ -196,129 +193,244 @@ export class Server {
         });
         return running;
     }
+    /**
+     * Builds contexts, attaches delivery, and opens the listener for one start attempt.
+     *
+     * @param ownership Whether the environment is managed by this Server.
+     * @returns The running listener after lifecycle startup.
+     */
     async #startOnce(ownership) {
-        const browser = this.#browser;
-        const standalone = ServerValues.isStandaloneBrowser(browser);
-        if (browser?.backend !== undefined)
-            BrowserServer.backendUrls(ServerValues.browserBackendUrls(browser.backend));
-        if (standalone &&
-            (this.#contexts.length > 0 ||
-                this.#resources.length > 0 ||
-                Object.keys(this.#services).length > 0 ||
-                this.#listenerLifecycles.length > 0))
-            throw new Error("Standalone browser server cannot own local contexts, services, or resources.");
-        if (browser !== undefined)
-            BrowserServer.requireDurableBindings(browser, this.#environment.environment.type === EnvironmentType.Production);
-        if (standalone && browser !== undefined)
-            return BrowserServer.open(browser.backend === undefined
-                ? undefined
-                : BrowserServer.backendUrls(ServerValues.browserBackendUrls(browser.backend)), {
-                ...browser,
-                host: browser.host ?? this.#host,
-                port: browser.port ?? this.#port,
-                readMaxBytes: this.#readMaxBytes,
-                writeMaxBytes: this.#writeMaxBytes,
-                production: this.#environment.environment.type === EnvironmentType.Production,
-            });
-        const contexts = await ServerValues.buildContexts(this.#contexts, this.#environment.storageFactory);
-        const logger = serverEnvironmentAccess.loggerFor(this.#environment);
-        for (const context of contexts) {
-            boundedContextAccess.installLogger(context, logger);
-            serverEnvironmentAccess.warnVolatileRegistry(this.#environment, context);
-        }
-        let attachment;
+        const admission = { token: {}, contexts: [] };
+        const contexts = await this.#prepareContexts(admission);
+        const { attachment, routes } = await this.#attachContexts(contexts, ownership, admission);
+        const running = await this.#openListener(contexts, attachment, routes);
+        await this.#startLifecycles(running);
+        return running;
+    }
+    /**
+     * Opens the service listener with retryable cleanup for every preparation phase.
+     *
+     * @param contexts Contexts exposed by the listener.
+     * @param attachment Active environment delivery attachment.
+     * @param routes Routes installed for these contexts.
+     * @returns The prepared running listener.
+     */
+    async #openListener(contexts, attachment, routes) {
+        const closeables = [...contexts, ...this.#resources];
+        const cleanup = {
+            closeGroup: new RetryableCloseGroup(closeables, "Server start cleanup failed while closing owned contexts/resources."),
+            attachment,
+            routes,
+            failedStartRollback: undefined,
+        };
         try {
-            attachment = await serverEnvironmentAccess.attach(this.#environment, {
-                ownership,
-                descriptors: contexts.map((context) => boundedContextAccess.delivery(context)),
-            });
+            return await this.#prepareListener(contexts, attachment, routes, closeables, cleanup);
         }
         catch (error) {
-            const closeGroup = new RetryableCloseGroup([...contexts, ...this.#resources], "Server start cleanup failed while closing owned contexts/resources.");
-            if (serverEnvironmentAccess.failedStartRetryPending(this.#environment, error)) {
-                this.#failedStartCleanup = {
-                    closeGroup,
-                    failedStartRollback: { rejection: error },
-                };
-            }
-            else {
-                try {
-                    await closeGroup.close();
-                }
-                catch (cleanupError) {
-                    this.#failedStartCleanup = {
-                        closeGroup,
-                        failedStartRollback: undefined,
-                    };
-                    throw ServerValues.attachmentCleanupError(error, cleanupError);
-                }
-                this.#failedStartConsumed = true;
-            }
-            throw error;
-        }
-        const closeables = [...contexts, ...this.#resources];
-        const services = new SpineServices({
-            contexts,
-            ...this.#services,
-        });
-        spineServicesAccess.installLogger(services, logger);
-        const sessions = new Set();
-        const httpServer = ServerValues.createHttpServer(services, sessions, this.#readMaxBytes, this.#writeMaxBytes);
-        const listener = this.#browser === undefined
-            ? { host: this.#host, port: this.#port }
-            : { host: defaultHost, port: defaultPort };
-        const address = await ServerValues.listen(httpServer, listener.host, listener.port).catch(async (error) => {
-            const cleanup = {
-                closeGroup: new RetryableCloseGroup(closeables, "Server start cleanup failed while closing owned contexts/resources."),
-                network: { server: httpServer, sessions },
-                attachment,
-                failedStartRollback: undefined,
-            };
             this.#failedStartCleanup = cleanup;
             return this.#cleanupFailedListenerStart(cleanup, error);
-        });
+        }
+    }
+    /**
+     * Constructs services and the HTTP adapter, then binds the listener.
+     *
+     * @param contexts Contexts exposed by this Server.
+     * @param attachment Active delivery attachment.
+     * @param routes Installed state routes.
+     * @param closeables Contexts and resources for eventual shutdown.
+     * @param cleanup Retained cleanup state if preparation fails.
+     * @returns The prepared running listener.
+     */
+    async #prepareListener(contexts, attachment, routes, closeables, cleanup) {
+        const services = new SpineServices({ contexts, ...this.#services });
+        cleanup.services = services;
+        spineServicesAccess.installLogger(services, serverEnvironmentAccess.loggerFor(this.#environment));
+        const { httpServer, sessions } = this.#createHttpListener(services);
+        cleanup.network = { server: httpServer, sessions };
+        const address = await ServerValues.listen(httpServer, this.#host, this.#port);
         const host = typeof address.address === "string" ? address.address : this.#host;
-        const running = new RunningHttp2Server({
+        return this.#createRunningServer({
             server: httpServer,
             sessions,
             environment: this.#environment,
             attachment,
+            routes,
             services,
             host,
             port: address.port,
+            contexts,
             closeables,
+        });
+    }
+    /**
+     * Prepares an HTTP listener and its tracked sessions for startup.
+     *
+     * @param services Service routes exposed by the listener.
+     * @returns The unbound listener and its session set.
+     */
+    #createHttpListener(services) {
+        const sessions = new Set();
+        const httpServer = ServerValues.createHttpServer(services, sessions, this.#readMaxBytes, this.#writeMaxBytes);
+        return { httpServer, sessions };
+    }
+    /**
+     * Creates the listener handle and associates its context set.
+     *
+     * @param options Listener resources prepared during startup.
+     * @returns The not-yet-started listener handle.
+     */
+    #createRunningServer(options) {
+        const running = new RunningHttp2Server({
+            ...options,
             listenerLifecycles: this.#listenerLifecycles,
         });
-        runningContexts.set(running, contexts);
+        runningContexts.set(running, options.contexts);
+        return running;
+    }
+    /**
+     * Reserves prebuilt contexts before awaiting builders, then assembles each builder.
+     *
+     * @param admission Attempt-local reservations retained through cleanup.
+     * @returns Prepared contexts for this Server.
+     */
+    async #prepareContexts(admission) {
+        const contexts = [];
+        let conflict;
+        let conflicted = false;
+        for (const entry of this.#contexts) {
+            if (boundedContextAccess.isBuilder(entry))
+                continue;
+            try {
+                this.#admitContext(entry, admission);
+            }
+            catch (error) {
+                if (!conflicted)
+                    conflict = error;
+                conflicted = true;
+            }
+        }
         try {
-            await running.startLifecycles();
+            if (conflicted)
+                throw conflict;
+            for (const entry of this.#contexts) {
+                const context = boundedContextAccess.isBuilder(entry)
+                    ? await boundedContextAccess.build(entry, this.#environment.storageFactory)
+                    : entry;
+                if (boundedContextAccess.isBuilder(entry))
+                    this.#admitContext(context, admission);
+                contexts.push(context);
+            }
+            return contexts;
         }
         catch (error) {
-            if (running.hasPendingClose())
-                this.#failedListenerLifecycle = running;
-            else
-                this.#failedStartConsumed = true;
+            await this.#cleanupFailedAttachment(admission.contexts, undefined, error, admission);
             throw error;
         }
-        if (browser === undefined)
-            return running;
+    }
+    /**
+     * Reserves one context Stand while this Server assembles its routes.
+     *
+     * @param context Context to reserve.
+     * @param admission Attempt-local reservations and token.
+     */
+    #admitContext(context, admission) {
+        const stand = context.stand();
+        const token = assemblingStands.get(stand);
+        if (token !== undefined || RegisteredTargets.forStand(stand) !== undefined) {
+            throw new Error("Stand is already associated with another Server or assembly.");
+        }
+        assemblingStands.set(stand, admission.token);
+        admission.contexts.push(context);
+    }
+    /**
+     * Clears only reservations made by the given assembly attempt.
+     *
+     * @param admission Attempt whose reserved Stands may be released.
+     */
+    #releaseAdmission(admission) {
+        for (const context of admission.contexts) {
+            const stand = context.stand();
+            if (assemblingStands.get(stand) === admission.token)
+                assemblingStands.delete(stand);
+        }
+        admission.contexts.length = 0;
+    }
+    /**
+     * Validates state routes before delivery recovery can invoke handlers.
+     *
+     * @param contexts Built contexts for this Server.
+     * @param ownership Environment attachment mode.
+     * @param admission Reservations transferred to installed routes before attachment.
+     * @returns The environment attachment and its installed routes.
+     */
+    async #attachContexts(contexts, ownership, admission) {
+        const freshContexts = contexts.filter((context) => RegisteredTargets.forStand(context.stand()) === undefined);
+        let routes;
         try {
-            return await BrowserServer.open(running, {
-                ...browser,
-                host: browser.host ?? this.#host,
-                port: browser.port ?? this.#port,
-                readMaxBytes: this.#readMaxBytes,
-                writeMaxBytes: this.#writeMaxBytes,
-                production: this.#environment.environment.type === EnvironmentType.Production,
+            routes = new RegisteredTargets(contexts);
+            routes.install(contexts);
+            this.#releaseAdmission(admission);
+            const logger = serverEnvironmentAccess.loggerFor(this.#environment);
+            for (const context of contexts) {
+                boundedContextAccess.installLogger(context, logger);
+                serverEnvironmentAccess.warnVolatileRegistry(this.#environment, context);
+            }
+            const attachment = await serverEnvironmentAccess.attach(this.#environment, {
+                ownership,
+                descriptors: contexts.map((context) => boundedContextAccess.delivery(context)),
             });
+            return { attachment, routes };
         }
         catch (error) {
-            try {
-                await running.close();
-            }
-            catch (closeError) {
-                throw new AggregateError([error, closeError], "Server browser startup failed and rollback failed.");
-            }
+            await this.#cleanupFailedAttachment(freshContexts, routes, error, admission);
+            throw error;
+        }
+    }
+    /**
+     * Retains retryable cleanup when route validation or attachment fails.
+     *
+     * @param contexts Fresh contexts to close after failure.
+     * @param routes Routes installed by this attempt, if any.
+     * @param error Original route or attachment failure.
+     * @param admission Reservations retained until context cleanup succeeds.
+     */
+    async #cleanupFailedAttachment(contexts, routes, error, admission) {
+        const closeGroup = new RetryableCloseGroup([...contexts, ...this.#resources], "Server start cleanup failed while closing owned contexts/resources.");
+        if (serverEnvironmentAccess.failedStartRetryPending(this.#environment, error)) {
+            this.#failedStartCleanup = {
+                closeGroup,
+                failedStartRollback: { rejection: error },
+                routes,
+                admission,
+            };
+            return;
+        }
+        try {
+            await closeGroup.close();
+        }
+        catch (cleanupError) {
+            this.#failedStartCleanup = { closeGroup, failedStartRollback: undefined, routes, admission };
+            throw ServerValues.attachmentCleanupError(error, cleanupError);
+        }
+        routes?.release();
+        if (admission !== undefined)
+            this.#releaseAdmission(admission);
+        this.#failedStartConsumed = true;
+    }
+    /**
+     * Starts listener lifecycles and preserves failed close retries.
+     *
+     * @param running Listener whose lifecycles begin.
+     */
+    async #startLifecycles(running) {
+        try {
+            await running.startLifecycles();
+        }
+        catch (error) {
+            if (running.hasPendingClose())
+                this.#failedListenerLifecycle = running;
+            else
+                this.#failedStartConsumed = true;
             throw error;
         }
     }
@@ -351,6 +463,32 @@ export class Server {
         if (!(await this.#advanceFailedStartAttachment(cleanup, errors))) {
             return;
         }
+        await this.#retryFailedStartRollback(cleanup, errors);
+        let closeFailed = false;
+        try {
+            await cleanup.closeGroup.close();
+        }
+        catch (error) {
+            closeFailed = true;
+            CloseErrors.collect(error, errors);
+        }
+        if (!closeFailed && cleanup.attachment === undefined && this.#failedStartCleanup === cleanup) {
+            cleanup.routes?.release();
+            if (cleanup.admission !== undefined)
+                this.#releaseAdmission(cleanup.admission);
+            if (cleanup.services !== undefined)
+                spineServicesAccess.clearLogger(cleanup.services);
+            this.#failedStartCleanup = undefined;
+            this.#failedStartConsumed = true;
+        }
+    }
+    /**
+     * Retries environment rollback before closing contexts from a failed start.
+     *
+     * @param cleanup Retained failed-start state.
+     * @param errors Errors collected across cleanup phases.
+     */
+    async #retryFailedStartRollback(cleanup, errors) {
         const failedStartRollback = cleanup.failedStartRollback;
         if (failedStartRollback !== undefined &&
             serverEnvironmentAccess.failedStartRetryPending(this.#environment, failedStartRollback.rejection)) {
@@ -364,18 +502,6 @@ export class Server {
                 CloseErrors.collect(error, errors);
             }
         }
-        let closeFailed = false;
-        try {
-            await cleanup.closeGroup.close();
-        }
-        catch (error) {
-            closeFailed = true;
-            CloseErrors.collect(error, errors);
-        }
-        if (!closeFailed && cleanup.attachment === undefined && this.#failedStartCleanup === cleanup) {
-            this.#failedStartCleanup = undefined;
-            this.#failedStartConsumed = true;
-        }
     }
     async #closeFailedStartNetwork(cleanup, errors) {
         const network = cleanup.network;
@@ -427,6 +553,23 @@ export class Server {
         }
     }
 }
+/**
+ * Checks whether browser composition may start a private native listener.
+ *
+ * @internal
+ */
+export const serverBuilderAccess = Object.freeze({
+    isLoopback(server) {
+        const host = serverHosts.get(server);
+        return host !== undefined && isLoopbackHost(host);
+    },
+});
+function isLoopbackHost(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;
+}
 /**
  * Provides framework-only `RunningServer` context facts.
  *
@@ -442,14 +585,19 @@ export const runningServerAccess = Object.freeze({
         return server instanceof RunningHttp2Server ? server.drainDelivery() : Promise.resolve();
     },
 });
+/**
+ * Holds listener resources and closes them in recovery-safe phases.
+ */
 class RunningHttp2Server {
     #server;
     #sessions;
     #closeables;
+    #contexts;
     #listenerLifecycles;
     #startedLifecycles = [];
     #environment;
     #attachment;
+    #routes;
     #services;
     host;
     port;
@@ -458,19 +606,31 @@ class RunningHttp2Server {
     #networkClosed = false;
     #attachmentDetached = false;
     #closeGroup;
+    /**
+     * Captures the running listener's network, environment, and cleanup resources.
+     *
+     * @param options Resources prepared by Server startup.
+     */
     constructor(options) {
         this.#server = options.server;
         this.#sessions = options.sessions;
         this.#closeables = options.closeables;
+        this.#contexts = options.contexts;
         this.#listenerLifecycles = options.listenerLifecycles;
         this.#environment = options.environment;
         this.#attachment = options.attachment;
+        this.#routes = options.routes;
         this.#services = options.services;
         this.host = options.host;
         this.port = options.port;
         this.baseUrl = `http://${ServerValues.formatHostForUrl(options.host)}:${options.port.toString()}`;
         this.#closeGroup = new RetryableCloseGroup(this.#closeables, "Server close failed while closing owned contexts/resources.");
     }
+    /**
+     * Closes this listener once, preserving a failed close for retry.
+     *
+     * @returns Completion after resources close.
+     */
     close() {
         this.#closed ??= this.#closeOnce().catch((error) => {
             this.#closed = undefined;
@@ -500,11 +660,16 @@ class RunningHttp2Server {
             throw error;
         }
     }
+    /**
+     * Checks whether a failed lifecycle start still needs close retry.
+     *
+     * @returns `true` when no close completion is retained.
+     */
     hasPendingClose() {
         return this.#closed === undefined;
     }
     /**
-     * Drains the server-owned Delivery attachment while network sessions remain available.
+     * Completes the server's Delivery detachment while network sessions remain available.
      *
      * @returns Completion after the attachment drains.
      */
@@ -519,7 +684,35 @@ class RunningHttp2Server {
         }
         this.#attachmentDetached = true;
     }
+    /**
+     * Closes network, delivery, accepted context work, and registered resources.
+     *
+     * @returns Completion after all resources close.
+     */
     async #closeOnce() {
+        await this.#closeListenerAndNetwork();
+        const { detachErrors, detachRejected } = await this.#detachDelivery();
+        await this.#drainContexts();
+        try {
+            await this.#closeGroup.close();
+            this.#routes.release();
+        }
+        catch (error) {
+            if (!detachRejected)
+                throw error;
+            CloseErrors.collect(error, detachErrors);
+            throw new AggregateError(detachErrors, "Server close failed while detaching delivery and closing owned contexts/resources.");
+        }
+        if (detachRejected)
+            ServerValues.throwRunningDetachErrors(detachErrors);
+        spineServicesAccess.clearLogger(this.#services);
+    }
+    /**
+     * Closes lifecycle attachments and network intake before delivery detachment.
+     *
+     * @returns Completion after the listener and sessions close.
+     */
+    async #closeListenerAndNetwork() {
         while (this.#startedLifecycles.length > 0) {
             const lifecycle = this.#startedLifecycles.at(-1);
             if (lifecycle === undefined)
@@ -531,6 +724,13 @@ class RunningHttp2Server {
             await ServerValues.closeNetwork(this.#server, this.#sessions);
             this.#networkClosed = true;
         }
+    }
+    /**
+     * Completes Delivery detachment while retaining errors for safe endpoint cleanup.
+     *
+     * @returns Detachment errors and whether detachment itself was rejected.
+     */
+    async #detachDelivery() {
         const detachErrors = [];
         let detachRejected = false;
         if (!this.#attachmentDetached) {
@@ -560,42 +760,38 @@ class RunningHttp2Server {
                 }
             }
         }
-        try {
-            await this.#closeGroup.close();
-        }
-        catch (error) {
-            if (!detachRejected) {
-                throw error;
-            }
-            CloseErrors.collect(error, detachErrors);
-            throw new AggregateError(detachErrors, "Server close failed while detaching delivery and closing owned contexts/resources.");
-        }
-        if (detachRejected) {
-            ServerValues.throwRunningDetachErrors(detachErrors);
+        return { detachErrors, detachRejected };
+    }
+    /**
+     * Waits for every context's accepted work before any Stand closes.
+     *
+     * @returns Completion after all context work drains.
+     */
+    async #drainContexts() {
+        for (const context of this.#contexts)
+            boundedContextAccess.beginClose(context);
+        const drained = await Promise.allSettled(this.#contexts.map((context) => boundedContextAccess.drainWork(context)));
+        const drainErrors = drained.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+        if (drainErrors.length > 0) {
+            throw new AggregateError(drainErrors, "Server close failed while draining contexts.");
         }
-        spineServicesAccess.clearLogger(this.#services);
     }
 }
 /**
+ * Groups private server assembly, network, and shutdown operations.
  *
- * @internal Groups private server assembly, network, and shutdown operations.
+ * @internal
  */
 const ServerValues = Object.freeze({
-    async buildContexts(entries, defaultStorageFactory) {
-        const contexts = [];
-        try {
-            for (const entry of entries) {
-                contexts.push(boundedContextAccess.isBuilder(entry)
-                    ? await boundedContextAccess.build(entry, defaultStorageFactory)
-                    : entry);
-            }
-            return contexts;
-        }
-        catch (error) {
-            await ServerValues.cleanupBuiltContexts(contexts, error);
-            throw error;
-        }
-    },
+    /**
+     * Creates the HTTP/2 listener with Connect routes and session tracking.
+     *
+     * @param services Public service adapters.
+     * @param sessions Set collecting active HTTP/2 sessions.
+     * @param readMaxBytes Maximum request size.
+     * @param writeMaxBytes Maximum response size.
+     * @returns An unbound HTTP/2 server.
+     */
     createHttpServer(services, sessions, readMaxBytes, writeMaxBytes) {
         const server = http2.createServer(connectNodeAdapter({
             routes: (router) => {
@@ -610,6 +806,14 @@ const ServerValues = Object.freeze({
         });
         return server;
     },
+    /**
+     * Binds a listener and resolves its actual address.
+     *
+     * @param server HTTP/2 server to bind.
+     * @param host Network host.
+     * @param port Requested port, including zero for an ephemeral port.
+     * @returns Bound listener address.
+     */
     listen(server, host, port) {
         return new Promise((resolve, reject) => {
             const cleanup = () => {
@@ -629,32 +833,38 @@ const ServerValues = Object.freeze({
             server.listen(port, host);
         });
     },
-    async cleanupBuiltContexts(contexts, startError) {
-        try {
-            await new RetryableCloseGroup(contexts, "Server start cleanup failed while closing owned contexts/resources.").close();
-        }
-        catch (error) {
-            throw new AggregateError([startError, ...ServerValues.toCleanupErrors(error)], "Server start failed while building bounded contexts.");
-        }
-    },
-    toCleanupErrors(error) {
-        if (error instanceof AggregateError) {
-            return error.errors;
-        }
-        return [error];
-    },
+    /**
+     * Collects attachment and immediate cleanup failures for startup reporting.
+     *
+     * @param startError Attachment or duplicate registration failure.
+     * @param cleanupError Failure while closing prepared resources.
+     * @returns Both failures in one AggregateError.
+     */
     attachmentCleanupError(startError, cleanupError) {
         const errors = [];
         CloseErrors.collect(startError, errors);
         CloseErrors.collect(cleanupError, errors);
         return new AggregateError(errors, "Server attachment failed and immediate dependency cleanup also failed.");
     },
+    /**
+     * Throws one deferred cleanup failure or groups several.
+     *
+     * @param errors Deferred cleanup failures.
+     * @returns Never; this method throws.
+     */
     throwCleanupErrors(errors) {
         if (errors.length === 1) {
             throw errors[0];
         }
         throw new AggregateError(errors, "Server deferred failed-start cleanup failed.");
     },
+    /**
+     * Throws a listener-start failure with any rollback failures.
+     *
+     * @param startError Original listener failure.
+     * @param cleanupErrors Failures while closing startup resources.
+     * @returns Never; this method throws.
+     */
     throwListenerStartError(startError, cleanupErrors) {
         if (cleanupErrors.length === 0) {
             throw startError;
@@ -666,18 +876,37 @@ const ServerValues = Object.freeze({
         }
         throw new AggregateError(errors, "Server start failed while opening listener and cleanup also failed.");
     },
+    /**
+     * Throws one delivery-detachment error or groups several.
+     *
+     * @param errors Delivery-detachment failures.
+     * @returns Never; this method throws.
+     */
     throwRunningDetachErrors(errors) {
         if (errors.length === 1) {
             throw errors[0];
         }
         throw new AggregateError(errors, "Server close failed while detaching delivery.");
     },
+    /**
+     * Closes the HTTP/2 server and all tracked sessions.
+     *
+     * @param server Listener being closed.
+     * @param sessions Sessions admitted by the listener.
+     * @returns Completion after the network releases its resources.
+     */
     async closeNetwork(server, sessions) {
         const closed = ServerValues.closeHttpServer(server);
         await ServerValues.closeSessions(sessions);
         await closed;
         await ServerValues.nextTurn();
     },
+    /**
+     * Closes the listener, including a listener that never started.
+     *
+     * @param server Listener being closed.
+     * @returns Completion after the listener closes.
+     */
     closeHttpServer(server) {
         return new Promise((resolve, reject) => {
             if (!server.listening) {
@@ -694,9 +923,21 @@ const ServerValues = Object.freeze({
             });
         });
     },
+    /**
+     * Closes all active HTTP/2 sessions.
+     *
+     * @param sessions Active sessions to close.
+     * @returns Completion after every session closes.
+     */
     async closeSessions(sessions) {
         await Promise.all([...sessions].map((session) => ServerValues.closeSession(session)));
     },
+    /**
+     * Closes one session gracefully or destroys it after a bounded wait.
+     *
+     * @param session Active HTTP/2 session.
+     * @returns Completion after close or forced destruction.
+     */
     closeSession(session) {
         return new Promise((resolve) => {
             const timer = setTimeout(() => {
@@ -712,14 +953,31 @@ const ServerValues = Object.freeze({
             session.close();
         });
     },
+    /**
+     * Waits one event-loop turn for pending close callbacks.
+     *
+     * @returns Completion on the next turn.
+     */
     nextTurn() {
         return new Promise((resolve) => {
             setImmediate(resolve);
         });
     },
+    /**
+     * Wraps an IPv6 host for URL authority syntax.
+     *
+     * @param host Bound network host.
+     * @returns Host formatted for the base URL.
+     */
     formatHostForUrl(host) {
         return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
     },
+    /**
+     * Normalizes a non-blank host for listener binding.
+     *
+     * @param host Configured host, if supplied.
+     * @returns Normalized host or the loopback default.
+     */
     normalizeHost(host) {
         const normalized = host?.trim() ?? defaultHost;
         if (normalized.length === 0) {
@@ -727,21 +985,13 @@ const ServerValues = Object.freeze({
         }
         return normalized;
     },
-    browserBackendUrls(backend) {
-        const source = backend;
-        if (typeof source.baseUrl === "string" && source.baseUrls === undefined)
-            return [source.baseUrl];
-        if (source.baseUrl === undefined && Array.isArray(source.baseUrls)) {
-            const values = source.baseUrls;
-            if (values.some((value) => typeof value !== "string"))
-                throw new Error("Server browser backend URLs must be strings.");
-            return values;
-        }
-        throw new Error("Server browser backend must configure exactly one of baseUrl or baseUrls.");
-    },
-    isStandaloneBrowser(browser) {
-        return browser?.backend !== undefined || browser?.discovery !== undefined;
-    },
+    /**
+     * Validates a configured HTTP message-size limit.
+     *
+     * @param value Requested byte limit.
+     * @param name Option name used in diagnostics.
+     * @returns Accepted byte limit.
+     */
     normalizeMessageMaxBytes(value, name) {
         if (!Number.isInteger(value) || value < 1 || value > maximumMessageMaxBytes) {
             throw new Error(`Server ${name} must be an integer from 1 through 4294967295.`);