@spine-event-engine/server 2.0.0-snapshot.16 → 2.0.0-snapshot.20

package/dist/server/server.js

@@ -15,6 +15,7 @@ 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 { 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";
@@ -25,6 +26,7 @@ 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.
  *
@@ -191,75 +193,236 @@ 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 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 = { host: this.#host, port: this.#port };
-        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 {
+            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) {
+            await this.#cleanupFailedAttachment(admission.contexts, undefined, error, admission);
+            throw error;
+        }
+    }
+    /**
+     * 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 {
+            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) {
+            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();
         }
@@ -270,7 +433,6 @@ export class Server {
                 this.#failedStartConsumed = true;
             throw error;
         }
-        return running;
     }
     async #retryFailedStartCleanup(cleanup) {
         const errors = [];
@@ -301,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)) {
@@ -314,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;
@@ -409,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;
@@ -425,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;
@@ -467,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.
      */
@@ -486,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)
@@ -498,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) {
@@ -527,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) => {
@@ -577,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 = () => {
@@ -596,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;
@@ -633,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) {
@@ -661,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(() => {
@@ -679,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) {
@@ -694,6 +985,13 @@ const ServerValues = Object.freeze({
         }
         return normalized;
     },
+    /**
+     * 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.`);