@spine-event-engine/server 2.0.0-snapshot.11

package/dist/server/server.js

@@ -0,0 +1,704 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+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 { ProcessServerCoordinator } from "./process-server-coordinator.js";
+import { CloseErrors, RetryableCloseGroup } from "./retryable-close.js";
+import { ServerEnvironment, serverEnvironmentAccess } from "./server-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();
+/**
+ * Configures and starts local Spine Connect/gRPC-compatible services.
+ *
+ * A server assembles its bounded contexts, completes finite environment
+ * delivery recovery, and opens its generated services before accepting network
+ * requests. It also owns the ordered cleanup of contexts and resources added
+ * to this assembly.
+ */
+export class Server {
+    #host;
+    #port;
+    #readMaxBytes;
+    #writeMaxBytes;
+    #contexts = [];
+    #resources = [];
+    #listenerLifecycles = [];
+    #services;
+    #environment;
+    #starting;
+    #startingOwnership;
+    #run;
+    #failedStartCleanup;
+    #failedListenerLifecycle;
+    #failedStartConsumed = false;
+    /**
+     * Creates a server builder.
+     *
+     * @param options Configures local network, contexts, resources, and services.
+     */
+    constructor(options = {}) {
+        this.#host = ServerValues.normalizeHost(options.host);
+        this.#port = options.port ?? defaultPort;
+        this.#readMaxBytes = ServerValues.normalizeMessageMaxBytes(options.readMaxBytes ?? defaultMessageMaxBytes, "readMaxBytes");
+        this.#writeMaxBytes = ServerValues.normalizeMessageMaxBytes(options.writeMaxBytes ?? defaultMessageMaxBytes, "writeMaxBytes");
+        this.#contexts.push(...(options.contexts ?? []));
+        this.#resources.push(...(options.resources ?? []));
+        this.#services = options.services ?? {};
+        this.#environment = ServerEnvironment.instance();
+        serverHosts.set(this, this.#host);
+    }
+    /**
+     * Creates a local-only server builder for one port.
+     *
+     * @param port Selects the listener port, or zero for an ephemeral port.
+     * @param options Supplies all server options except the port.
+     * @returns A configured server builder.
+     */
+    static atPort(port, options = {}) {
+        return new Server({ ...options, port });
+    }
+    /**
+     * Adds one bounded context or builder to the assembly.
+     *
+     * Builders assemble during {@link start} before recovery and listener open.
+     * They use {@link ServerEnvironment.storageFactory} unless a more specific
+     * `withStorageFactory(...)` factory is selected. The running server owns and
+     * closes added contexts only after services, sessions, and active work stop.
+     *
+     * @param context Supplies the context or builder to expose.
+     * @returns This server builder.
+     */
+    add(context) {
+        this.#contexts.push(context);
+        return this;
+    }
+    /**
+     * Adds a framework closeable owned by this server assembly.
+     *
+     * @param resource Supplies the resource to close after contexts.
+     * @returns This server builder.
+     */
+    addResource(resource) {
+        this.#resources.push(resource);
+        return this;
+    }
+    /**
+     * Adds work that starts after listener readiness and closes before network intake stops.
+     *
+     * Failed starts roll back admitted lifecycles in reverse admission order. A
+     * failed close remains retryable and prevents network shutdown until it settles.
+     *
+     * @param lifecycle Supplies listener-coupled lifecycle work, such as GCE registration.
+     * @returns This server builder.
+     */
+    addListenerLifecycle(lifecycle) {
+        this.#listenerLifecycles.push(lifecycle);
+        return this;
+    }
+    /**
+     * Starts the server after completing assembly and delivery recovery.
+     *
+     * Built contexts attach to delivery in deterministic input order before the
+     * generated services and listener open. A failed assembly or listener open
+     * leaves no listener and closes acquired resources. Network cleanup is a hard
+     * gate before delivery or dependencies close.
+     * It shares only a caller-managed active environment generation, rejects
+     * while run-managed ownership is active, installs no signal handlers, and
+     * never closes the environment.
+     * A later call after incomplete cleanup retries only that cleanup and leaves
+     * this server terminal. A fresh server may reuse the singleton environment.
+     * Concurrent callers share one start or cleanup attempt.
+     *
+     * @returns The running server once its listener accepts requests.
+     */
+    start() {
+        return this.#start("caller");
+    }
+    #start(ownership) {
+        const current = this.#starting;
+        if (current !== undefined) {
+            if (this.#startingOwnership !== ownership) {
+                return Promise.reject(new Error("Server cannot mix caller-managed and run-managed startup attempts."));
+            }
+            return current;
+        }
+        if (this.#failedStartConsumed) {
+            return Promise.reject(new Error("Server cannot restart after failed-start cleanup has completed."));
+        }
+        const cleanup = this.#failedStartCleanup;
+        const lifecycle = this.#failedListenerLifecycle;
+        const starting = lifecycle !== undefined
+            ? this.#retryFailedListenerLifecycle(lifecycle)
+            : cleanup === undefined
+                ? this.#startOnce(ownership)
+                : this.#retryFailedStartCleanup(cleanup);
+        this.#starting = starting;
+        this.#startingOwnership = ownership;
+        void starting.then(() => {
+            this.#finishStart(starting);
+        }, () => {
+            this.#finishStart(starting);
+        });
+        return starting;
+    }
+    /**
+     * Starts this server with process-owned `SIGINT` and `SIGTERM` shutdown.
+     *
+     * This is the normal application entry point. Embedded applications should
+     * use {@link start} and keep ownership of process signals themselves.
+     * 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 failed final
+     * close stays retryable through `close()` or a later process signal.
+     * Caller-managed servers never close their environment.
+     *
+     * @returns The running server after its listener accepts requests.
+     */
+    run() {
+        const current = this.#run;
+        if (current !== undefined)
+            return current;
+        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;
+            }
+        }));
+        this.#run = running;
+        void running.catch(() => {
+            if (this.#run === running) {
+                this.#run = undefined;
+            }
+        });
+        return running;
+    }
+    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;
+        try {
+            attachment = await serverEnvironmentAccess.attach(this.#environment, {
+                ownership,
+                descriptors: contexts.map((context) => boundedContextAccess.delivery(context)),
+            });
+        }
+        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);
+        });
+        const host = typeof address.address === "string" ? address.address : this.#host;
+        const running = new RunningHttp2Server({
+            server: httpServer,
+            sessions,
+            environment: this.#environment,
+            attachment,
+            services,
+            host,
+            port: address.port,
+            closeables,
+            listenerLifecycles: this.#listenerLifecycles,
+        });
+        runningContexts.set(running, contexts);
+        try {
+            await running.startLifecycles();
+        }
+        catch (error) {
+            if (running.hasPendingClose())
+                this.#failedListenerLifecycle = running;
+            else
+                this.#failedStartConsumed = true;
+            throw error;
+        }
+        return running;
+    }
+    async #retryFailedStartCleanup(cleanup) {
+        const errors = [];
+        if (!(await this.#closeFailedStartNetwork(cleanup, errors))) {
+            ServerValues.throwCleanupErrors(errors);
+        }
+        await this.#advanceFailedStartCleanup(cleanup, errors);
+        if (errors.length > 0) {
+            ServerValues.throwCleanupErrors(errors);
+        }
+        throw new Error("Server deferred cleanup completed after an earlier failed start.");
+    }
+    async #retryFailedListenerLifecycle(running) {
+        await running.close();
+        this.#failedListenerLifecycle = undefined;
+        this.#failedStartConsumed = true;
+        throw new Error("Server deferred cleanup completed after an earlier failed start.");
+    }
+    async #cleanupFailedListenerStart(cleanup, startError) {
+        const errors = [];
+        if (!(await this.#closeFailedStartNetwork(cleanup, errors))) {
+            return ServerValues.throwListenerStartError(startError, errors);
+        }
+        await this.#advanceFailedStartCleanup(cleanup, errors);
+        return ServerValues.throwListenerStartError(startError, errors);
+    }
+    async #advanceFailedStartCleanup(cleanup, errors) {
+        if (!(await this.#advanceFailedStartAttachment(cleanup, errors))) {
+            return;
+        }
+        const failedStartRollback = cleanup.failedStartRollback;
+        if (failedStartRollback !== undefined &&
+            serverEnvironmentAccess.failedStartRetryPending(this.#environment, failedStartRollback.rejection)) {
+            try {
+                await serverEnvironmentAccess.retryFailedStart(this.#environment);
+            }
+            catch (error) {
+                if (serverEnvironmentAccess.failedStartRetryPending(this.#environment, failedStartRollback.rejection)) {
+                    throw error;
+                }
+                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;
+        if (network === undefined) {
+            return true;
+        }
+        try {
+            await ServerValues.closeNetwork(network.server, network.sessions);
+            delete cleanup.network;
+            return true;
+        }
+        catch (error) {
+            CloseErrors.collect(error, errors);
+            return false;
+        }
+    }
+    async #advanceFailedStartAttachment(cleanup, errors) {
+        const attachment = cleanup.attachment;
+        if (attachment === undefined) {
+            return true;
+        }
+        try {
+            if (serverEnvironmentAccess.detachRetryPending(this.#environment, attachment)) {
+                await serverEnvironmentAccess.retryDetach(this.#environment, attachment);
+            }
+            else {
+                await serverEnvironmentAccess.detach(this.#environment, attachment);
+            }
+            delete cleanup.attachment;
+            return true;
+        }
+        catch (error) {
+            CloseErrors.collect(error, errors);
+        }
+        try {
+            if (serverEnvironmentAccess.endpointSafe(this.#environment, attachment)) {
+                return true;
+            }
+        }
+        catch (error) {
+            CloseErrors.collect(error, errors);
+        }
+        return false;
+    }
+    #finishStart(starting) {
+        if (this.#starting === starting) {
+            this.#starting = undefined;
+            this.#startingOwnership = undefined;
+        }
+    }
+}
+/**
+ * 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.
+ *
+ * @internal
+ */
+export const runningServerAccess = Object.freeze({
+    subscriptionRegistries(server) {
+        return runningContexts
+            .get(server)
+            ?.map((context) => boundedContextAccess.subscriptionRegistry(context));
+    },
+    drainDelivery(server) {
+        return server instanceof RunningHttp2Server ? server.drainDelivery() : Promise.resolve();
+    },
+});
+class RunningHttp2Server {
+    #server;
+    #sessions;
+    #closeables;
+    #listenerLifecycles;
+    #startedLifecycles = [];
+    #environment;
+    #attachment;
+    #services;
+    host;
+    port;
+    baseUrl;
+    #closed;
+    #networkClosed = false;
+    #attachmentDetached = false;
+    #closeGroup;
+    constructor(options) {
+        this.#server = options.server;
+        this.#sessions = options.sessions;
+        this.#closeables = options.closeables;
+        this.#listenerLifecycles = options.listenerLifecycles;
+        this.#environment = options.environment;
+        this.#attachment = options.attachment;
+        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.");
+    }
+    close() {
+        this.#closed ??= this.#closeOnce().catch((error) => {
+            this.#closed = undefined;
+            throw error;
+        });
+        return this.#closed;
+    }
+    /**
+     * Starts listener-ready attachments after the native listener accepts connections.
+     *
+     * @returns Completes after all attachments start or their admitted rollback settles.
+     */
+    async startLifecycles() {
+        try {
+            for (const lifecycle of this.#listenerLifecycles) {
+                await lifecycle.start();
+                this.#startedLifecycles.push(lifecycle);
+            }
+        }
+        catch (error) {
+            try {
+                await this.close();
+            }
+            catch (rollback) {
+                throw new AggregateError([error, rollback], "Server listener lifecycle start and rollback failed.");
+            }
+            throw error;
+        }
+    }
+    hasPendingClose() {
+        return this.#closed === undefined;
+    }
+    /**
+     * Drains the server-owned Delivery attachment while network sessions remain available.
+     *
+     * @returns Completion after the attachment drains.
+     */
+    async drainDelivery() {
+        if (this.#attachmentDetached)
+            return;
+        if (serverEnvironmentAccess.detachRetryPending(this.#environment, this.#attachment)) {
+            await serverEnvironmentAccess.retryDetach(this.#environment, this.#attachment);
+        }
+        else {
+            await serverEnvironmentAccess.detach(this.#environment, this.#attachment);
+        }
+        this.#attachmentDetached = true;
+    }
+    async #closeOnce() {
+        while (this.#startedLifecycles.length > 0) {
+            const lifecycle = this.#startedLifecycles.at(-1);
+            if (lifecycle === undefined)
+                break;
+            await lifecycle.close();
+            this.#startedLifecycles.pop();
+        }
+        if (!this.#networkClosed) {
+            await ServerValues.closeNetwork(this.#server, this.#sessions);
+            this.#networkClosed = true;
+        }
+        const detachErrors = [];
+        let detachRejected = false;
+        if (!this.#attachmentDetached) {
+            try {
+                if (serverEnvironmentAccess.detachRetryPending(this.#environment, this.#attachment)) {
+                    await serverEnvironmentAccess.retryDetach(this.#environment, this.#attachment);
+                }
+                else {
+                    await serverEnvironmentAccess.detach(this.#environment, this.#attachment);
+                }
+                this.#attachmentDetached = true;
+            }
+            catch (error) {
+                detachRejected = true;
+                CloseErrors.collect(error, detachErrors);
+            }
+            if (detachRejected) {
+                let endpointSafe = false;
+                try {
+                    endpointSafe = serverEnvironmentAccess.endpointSafe(this.#environment, this.#attachment);
+                }
+                catch (error) {
+                    CloseErrors.collect(error, detachErrors);
+                }
+                if (!endpointSafe) {
+                    ServerValues.throwRunningDetachErrors(detachErrors);
+                }
+            }
+        }
+        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);
+        }
+        spineServicesAccess.clearLogger(this.#services);
+    }
+}
+/**
+ *
+ * @internal Groups private server assembly, network, and shutdown operations.
+ */
+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;
+        }
+    },
+    createHttpServer(services, sessions, readMaxBytes, writeMaxBytes) {
+        const server = http2.createServer(connectNodeAdapter({
+            routes: (router) => {
+                services.register(router);
+            },
+            readMaxBytes,
+            writeMaxBytes,
+        }));
+        server.on("session", (session) => {
+            sessions.add(session);
+            session.on("close", () => sessions.delete(session));
+        });
+        return server;
+    },
+    listen(server, host, port) {
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                server.off("error", onError);
+                server.off("listening", onListening);
+            };
+            const onError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            const onListening = () => {
+                cleanup();
+                resolve(server.address());
+            };
+            server.once("error", onError);
+            server.once("listening", onListening);
+            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];
+    },
+    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.");
+    },
+    throwCleanupErrors(errors) {
+        if (errors.length === 1) {
+            throw errors[0];
+        }
+        throw new AggregateError(errors, "Server deferred failed-start cleanup failed.");
+    },
+    throwListenerStartError(startError, cleanupErrors) {
+        if (cleanupErrors.length === 0) {
+            throw startError;
+        }
+        const errors = [];
+        CloseErrors.collect(startError, errors);
+        for (const error of cleanupErrors) {
+            CloseErrors.collect(error, errors);
+        }
+        throw new AggregateError(errors, "Server start failed while opening listener and cleanup also failed.");
+    },
+    throwRunningDetachErrors(errors) {
+        if (errors.length === 1) {
+            throw errors[0];
+        }
+        throw new AggregateError(errors, "Server close failed while detaching delivery.");
+    },
+    async closeNetwork(server, sessions) {
+        const closed = ServerValues.closeHttpServer(server);
+        await ServerValues.closeSessions(sessions);
+        await closed;
+        await ServerValues.nextTurn();
+    },
+    closeHttpServer(server) {
+        return new Promise((resolve, reject) => {
+            if (!server.listening) {
+                resolve();
+                return;
+            }
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        });
+    },
+    async closeSessions(sessions) {
+        await Promise.all([...sessions].map((session) => ServerValues.closeSession(session)));
+    },
+    closeSession(session) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                session.destroy();
+                resolve();
+            }, gracefulSessionDrainMs);
+            const finishGracefulClose = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            timer.unref();
+            session.once("close", finishGracefulClose);
+            session.close();
+        });
+    },
+    nextTurn() {
+        return new Promise((resolve) => {
+            setImmediate(resolve);
+        });
+    },
+    formatHostForUrl(host) {
+        return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+    },
+    normalizeHost(host) {
+        const normalized = host?.trim() ?? defaultHost;
+        if (normalized.length === 0) {
+            throw new Error("Server host must not be blank.");
+        }
+        return normalized;
+    },
+    normalizeMessageMaxBytes(value, name) {
+        if (!Number.isInteger(value) || value < 1 || value > maximumMessageMaxBytes) {
+            throw new Error(`Server ${name} must be an integer from 1 through 4294967295.`);
+        }
+        return value;
+    },
+});
+//# sourceMappingURL=server.js.map