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

package/dist/server/managed-server-application.js

@@ -0,0 +1,937 @@
+/*
+ * 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 { fork } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { LogLayer, StructuredTransport } from "loglayer";
+import { runningServerAccess } from "./server.js";
+import { emitServerWarning } from "./server-log.js";
+import { NodeCoordinator } from "./node-coordinator.js";
+import { environmentDeliveryWorkerAccess } from "./environment-delivery-worker.js";
+import { managedChildSubscriptionAccess } from "./managed-child-subscription.js";
+import { InMemorySubscriptionRegistry } from "../stand/subscription-registry.js";
+const childMarker = "SPINE_MANAGED_SERVER_CHILD";
+const slotMarker = "SPINE_MANAGED_SERVER_SLOT";
+const incarnationMarker = "SPINE_MANAGED_SERVER_INCARNATION";
+const initialRestartDelayMs = 250;
+const maximumRestartDelayMs = 30_000;
+const healthyReadyMs = 60_000;
+const closeGraceMs = 1_000;
+const closeKillMs = 1_000;
+const endpointMaximumBytes = 256;
+const handleMembers = new WeakMap();
+const managedTestRegistries = new WeakMap();
+const lifecycleLogger = new LogLayer({
+    transport: new StructuredTransport({
+        logger: console,
+        level: "warn",
+        stringify: true,
+        messageField: "message",
+        dateField: "timestamp",
+        levelField: "severity",
+        levelFn: (level) => level.toUpperCase(),
+    }),
+}).child();
+/**
+ *
+ * Starts a managed parent and its complete-replica child processes.
+ */
+export const ManagedServerApplication = Object.freeze({
+    async start(options) {
+        return ManagedServerValues.start(options, false);
+    },
+    async run(options) {
+        return ManagedServerValues.start(options, true);
+    },
+});
+const ManagedServerValues = Object.freeze({
+    async start(options, manageProcessSignals) {
+        if (!Number.isSafeInteger(options.processCount) || options.processCount < 1) {
+            throw new Error("Managed server processCount must be a positive safe integer.");
+        }
+        ManagedServerCoordinatorValues.coordinatorPort(options.port);
+        if (process.env[childMarker] === "true")
+            return ManagedServerValues.child(options);
+        return ManagedServerValues.parent(options, manageProcessSignals);
+    },
+    async child(options) {
+        const server = await options.createServer({ host: "127.0.0.1", port: 0 });
+        try {
+            ManagedServerValues.requireVolatileRegistries(server);
+            await options.synchronize?.();
+        }
+        catch (error) {
+            try {
+                await server.close();
+            }
+            catch (cleanup) {
+                throw new AggregateError([error, cleanup], "Managed child setup and server cleanup failed.");
+            }
+            throw error;
+        }
+        // Node may emit an IPC EPIPE after a parent has already disappeared. The
+        // disconnect handler below owns shutdown; this listener prevents that
+        // transport detail from becoming an unhandled child-process exception.
+        const containIpcError = () => undefined;
+        process.on("error", containIpcError);
+        managedChildSubscriptionAccess.install((subscriptionId) => {
+            const notification = ManagedServerValues.send({
+                type: "subscription-installed",
+                slot: process.env[slotMarker],
+                incarnation: process.env[incarnationMarker],
+                subscriptionId,
+            });
+            // spine-log-boundary: server.managed_replica_subscription_ipc
+            void notification.catch(() => undefined);
+        });
+        let activated = false;
+        let releaseActivation;
+        const activation = new Promise((resolve) => {
+            releaseActivation = resolve;
+        });
+        let closing;
+        const close = () => {
+            if (closing !== undefined)
+                return closing;
+            const draining = ManagedServerValues.send({
+                type: "draining",
+                slot: process.env[slotMarker],
+                incarnation: process.env[incarnationMarker],
+            });
+            // spine-log-boundary: server.managed_replica_drain_ipc
+            const attempt = draining
+                .catch(() => undefined)
+                .then(() => {
+                environmentDeliveryWorkerAccess.cancelManagedChild();
+                managedChildSubscriptionAccess.clear();
+                releaseActivation();
+                return runningServerAccess.drainDelivery(server);
+            })
+                .then(() => {
+                return server.close();
+            })
+                .then(() => {
+                const closed = ManagedServerValues.send({
+                    type: "closed",
+                    slot: process.env[slotMarker],
+                    incarnation: process.env[incarnationMarker],
+                });
+                // spine-log-boundary: server.managed_replica_closed_ipc
+                return closed.catch(() => undefined);
+            }, (error) => {
+                const failed = ManagedServerValues.send({
+                    type: "close-failed",
+                    slot: process.env[slotMarker],
+                    incarnation: process.env[incarnationMarker],
+                });
+                // spine-log-boundary: server.managed_replica_close_failed_ipc
+                void failed.catch(() => undefined);
+                if (closing === attempt)
+                    closing = undefined;
+                throw error;
+            })
+                .then(() => {
+                process.off("disconnect", onDisconnect);
+                if (process.connected && typeof process.disconnect === "function")
+                    process.disconnect();
+                process.off("error", containIpcError);
+                process.off("message", onMessage);
+            });
+            closing = attempt;
+            return attempt;
+        };
+        const onMessage = (message) => {
+            if (message.type === "activate" && !activated) {
+                activated = true;
+                environmentDeliveryWorkerAccess.activateManagedChild();
+                releaseActivation();
+            }
+            else if (message.type === "close") {
+                ManagedServerValues.closeFromEvent(close);
+            }
+        };
+        const onDisconnect = () => {
+            ManagedServerValues.closeFromEvent(close);
+        };
+        process.on("message", onMessage);
+        process.once("disconnect", onDisconnect);
+        try {
+            await ManagedServerValues.send({
+                type: "synchronizing",
+                slot: process.env[slotMarker],
+                incarnation: process.env[incarnationMarker],
+                endpoint: server.baseUrl,
+            });
+        }
+        catch (error) {
+            await close();
+            throw error;
+        }
+        await activation;
+        await ManagedServerValues.send({
+            type: "ready",
+            slot: process.env[slotMarker],
+            incarnation: process.env[incarnationMarker],
+            endpoint: server.baseUrl,
+        });
+        return {
+            ready: true,
+            close,
+        };
+    },
+    parent(options, manageProcessSignals) {
+        return new ManagedServerCoordinator({ ...options, manageProcessSignals }).start();
+    },
+    closeFromEvent(close) {
+        // spine-log-boundary: server.managed_replica_child_close
+        void close().catch(() => {
+            emitServerWarning(lifecycleLogger, "Managed child close failed.", {
+                operation: "managed_replica.child_close",
+                reasonCode: "close_failed",
+            });
+        });
+    },
+    requireVolatileRegistries(server) {
+        const registries = runningServerAccess.subscriptionRegistries(server) ?? managedTestRegistries.get(server);
+        if (registries === undefined ||
+            registries.some((registry) => !(registry instanceof InMemorySubscriptionRegistry)))
+            throw new Error("Managed application replicas require an in-memory Stand subscription registry.");
+    },
+    send(message) {
+        return new Promise((resolve, reject) => {
+            if (process.send === undefined || !process.connected) {
+                reject(new Error("Managed child has no parent IPC channel."));
+                return;
+            }
+            try {
+                process.send(message, (error) => {
+                    if (error === null)
+                        resolve();
+                    else
+                        reject(error);
+                });
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error("Managed child READY IPC failed."));
+            }
+        });
+    },
+});
+/**
+ *
+ * Coordinates the parent-only lifecycle of managed application replicas.
+ *
+ * @internal
+ */
+export class ManagedServerCoordinator {
+    #slots;
+    #restart;
+    #options;
+    #dependencies;
+    #closing = false;
+    #starts = 0;
+    #ready;
+    #resolveReady;
+    #close;
+    #retired = new Set();
+    #retireTerminations = new Map();
+    #memberListeners = new Set();
+    #onSignal;
+    #nodeCoordinator;
+    /**
+     *
+     * Creates a coordinator for one configured replica cohort.
+     *
+     * @param options Configures complete child application replicas.
+     * @param dependencies Supplies private process and clock dependencies.
+     */
+    constructor(options, dependencies = ManagedServerCoordinatorValues.dependencies) {
+        this.#options = options;
+        this.#dependencies = dependencies;
+        this.#restart = ManagedServerCoordinatorValues.restart(options);
+        this.#slots = Array.from({ length: options.processCount }, (_, slot) => ({
+            slot,
+            failures: 0,
+            initialReady: false,
+            starting: false,
+            replacementTimer: undefined,
+            replica: undefined,
+        }));
+    }
+    /**
+     *
+     * Starts every initial replica and waits until all report READY.
+     *
+     * @returns The handle for the started managed cohort.
+     */
+    async start() {
+        this.#ready = new Promise((resolve) => {
+            this.#resolveReady = resolve;
+        });
+        if (this.#options.manageProcessSignals !== false)
+            this.#installSignalHandlers();
+        for (const slot of this.#slots)
+            this.#start(slot);
+        await this.#ready;
+        try {
+            const openCoordinator = this.#dependencies.openCoordinator;
+            if (openCoordinator !== undefined)
+                this.#nodeCoordinator = await openCoordinator({
+                    members: this,
+                    ...(this.#options.host === undefined ? {} : { host: this.#options.host }),
+                    ...(this.#options.port === undefined ? {} : { port: this.#options.port }),
+                });
+        }
+        catch (error) {
+            try {
+                await this.close();
+            }
+            catch (rollback) {
+                throw new AggregateError([error, rollback], "Managed replica Coordinator start and rollback failed.");
+            }
+            throw error;
+        }
+        const isReady = () => this.#slots.some((slot) => slot.replica?.readyAt !== undefined);
+        const handle = {
+            get ready() {
+                return isReady();
+            },
+            close: () => this.close(),
+        };
+        handleMembers.set(handle, this);
+        return handle;
+    }
+    #start(slot) {
+        if (this.#closing ||
+            slot.starting ||
+            slot.replica !== undefined ||
+            this.#starts >= this.#restart.concurrentStarts)
+            return;
+        slot.starting = true;
+        this.#starts++;
+        const incarnation = randomUUID();
+        let child;
+        try {
+            child = this.#dependencies.spawn(this.#options.moduleUrl, slot.slot, incarnation);
+        }
+        catch {
+            slot.starting = false;
+            this.#starts--;
+            // spine-log-boundary: server.managed_replica_start
+            emitServerWarning(lifecycleLogger, "Managed replica start failed.", {
+                operation: "managed_replica.start",
+                reasonCode: "start_failed",
+                slot: String(slot.slot),
+                incarnation,
+                attempt: String(slot.failures + 1),
+            });
+            this.#scheduleReplacement(slot);
+            this.#drainStarts();
+            return;
+        }
+        const replica = {
+            slot: slot.slot,
+            incarnation,
+            child,
+            endpoint: undefined,
+            readyAt: undefined,
+            synchronizing: false,
+            draining: false,
+            subscriptionWaiters: new Map(),
+            closeAttempt: undefined,
+            expectedExit: false,
+            terminal: false,
+        };
+        slot.replica = replica;
+        child.on("message", (message) => {
+            this.#onMessage(slot, replica, message);
+        });
+        child.once("exit", () => {
+            this.#retired.delete(replica);
+            this.#retireTerminations.delete(replica);
+            this.#onExit(slot, replica);
+        });
+        child.once("error", () => {
+            this.#onError(slot, replica);
+        });
+    }
+    #onMessage(slot, replica, message) {
+        const closeResult = ManagedServerCoordinatorValues.closeResultMessage(message, slot.slot, replica.incarnation);
+        if (closeResult !== undefined) {
+            if (slot.replica !== replica || !replica.draining || replica.closeAttempt === undefined)
+                return;
+            if (closeResult === "closed")
+                replica.closeAttempt.outcome.resolve(undefined);
+            else
+                replica.closeAttempt.outcome.reject(new Error("Managed child server close failed."));
+            return;
+        }
+        if (ManagedServerCoordinatorValues.subscriptionInstalledMessage(message, slot.slot, replica.incarnation)) {
+            if (slot.replica !== replica)
+                return;
+            this.#settleSubscriptionWaiter(replica, message.subscriptionId);
+            return;
+        }
+        if (ManagedServerCoordinatorValues.synchronizingMessage(message, slot.slot, replica.incarnation)) {
+            if (slot.replica !== replica || replica.endpoint !== undefined)
+                return;
+            replica.endpoint = message.endpoint;
+            replica.synchronizing = true;
+            this.#notifyReadyMembers();
+            if (this.#nodeCoordinator === undefined)
+                replica.child.send({ type: "activate" }, () => undefined);
+            return;
+        }
+        if (ManagedServerCoordinatorValues.drainingMessage(message, slot.slot, replica.incarnation)) {
+            if (slot.replica !== replica)
+                return;
+            replica.closeAttempt?.acknowledged.resolve(undefined);
+            if (replica.draining)
+                return;
+            replica.draining = true;
+            replica.expectedExit = true;
+            this.#notifyReadyMembers();
+            return;
+        }
+        if (!ManagedServerCoordinatorValues.readyMessage(message, slot.slot, replica.incarnation))
+            return;
+        if (slot.replica !== replica || replica.readyAt !== undefined || this.#closing)
+            return;
+        slot.starting = false;
+        this.#starts--;
+        replica.synchronizing = false;
+        replica.endpoint = message.endpoint;
+        replica.readyAt = this.#dependencies.clock.now();
+        slot.initialReady = true;
+        if (this.#slots.every((candidate) => candidate.initialReady))
+            this.#resolveReady?.();
+        this.#notifyReadyMembers();
+        this.#drainStarts();
+    }
+    #onExit(slot, replica) {
+        if (slot.replica !== replica || replica.terminal)
+            return;
+        replica.terminal = true;
+        this.#clearSubscriptionWaiters(replica, new Error("Managed child exited before subscription installed."));
+        slot.replica = undefined;
+        this.#notifyReadyMembers();
+        if (slot.starting) {
+            slot.starting = false;
+            this.#starts--;
+        }
+        if (this.#closing || replica.expectedExit)
+            return;
+        if (replica.readyAt !== undefined &&
+            this.#dependencies.clock.now() - replica.readyAt >= this.#restart.healthyReadyMs) {
+            slot.failures = 0;
+        }
+        // spine-log-boundary: server.managed_replica_exit
+        emitServerWarning(lifecycleLogger, "Managed replica exited unexpectedly.", {
+            operation: "managed_replica.exit",
+            reasonCode: "unexpected_exit",
+            slot: String(slot.slot),
+            incarnation: replica.incarnation,
+            attempt: String(slot.failures + 1),
+        });
+        this.#scheduleReplacement(slot);
+        this.#drainStarts();
+    }
+    #onError(slot, replica) {
+        if (slot.replica !== replica || replica.terminal)
+            return;
+        // A ChildProcess error can precede exit while the OS process still lives.
+        // Retire the incarnation once, then actively terminate that known child.
+        this.#onExit(slot, replica);
+        this.#terminateUnexpected(replica);
+    }
+    #scheduleReplacement(slot) {
+        slot.failures++;
+        const delay = Math.min(this.#restart.initialDelayMs * 2 ** Math.max(0, slot.failures - 1), this.#restart.maximumDelayMs);
+        slot.replacementTimer = this.#dependencies.clock.setTimeout(() => {
+            slot.replacementTimer = undefined;
+            this.#start(slot);
+        }, delay);
+        // spine-log-boundary: server.managed_replica_retry
+        emitServerWarning(lifecycleLogger, "Managed replica replacement scheduled.", {
+            operation: "managed_replica.replace",
+            reasonCode: "unexpected_exit",
+            slot: String(slot.slot),
+            attempt: String(slot.failures),
+            delay: String(delay),
+        });
+    }
+    #drainStarts() {
+        for (const slot of this.#slots) {
+            if (this.#starts >= this.#restart.concurrentStarts)
+                return;
+            if (slot.replica === undefined && slot.replacementTimer === undefined)
+                this.#start(slot);
+        }
+    }
+    /**
+     *
+     * Stops managed children and prevents later replacement starts.
+     *
+     * @returns Completion after child and retired-child cleanup succeeds.
+     */
+    close() {
+        const closing = this.#close;
+        if (closing !== undefined)
+            return closing;
+        const close = (async () => {
+            this.#closing = true;
+            this.#removeSignalHandlers();
+            for (const slot of this.#slots) {
+                if (slot.replacementTimer !== undefined)
+                    this.#dependencies.clock.clearTimeout(slot.replacementTimer);
+                slot.replacementTimer = undefined;
+            }
+            // `beginDrain()` makes the unary snapshot empty synchronously. Start every
+            // child quiescence attempt without waiting for its reconciliation promise:
+            // child close IPC must be issued in this turn, while the Coordinator keeps
+            // subscription relays alive until every child has settled.
+            const draining = this.#nodeCoordinator?.beginDrain();
+            for (const slot of this.#slots)
+                if (slot.replica !== undefined)
+                    this.#clearSubscriptionWaiters(slot.replica, new Error("Managed application is closing before subscription installed."));
+            const childCloses = [
+                ...this.#slots.map((slot) => this.#closeReplica(slot.replica)),
+                ...[...this.#retired].map((replica) => this.#closeRetired(replica)),
+            ];
+            const results = await Promise.allSettled([draining, ...childCloses]);
+            const failures = [];
+            for (const result of results)
+                if (result.status === "rejected")
+                    failures.push(result.reason);
+            if (failures.length === 1)
+                throw failures[0];
+            if (failures.length > 1)
+                throw new AggregateError(failures, "Managed child quiescence failed during drain.");
+            await this.#nodeCoordinator?.close();
+        })();
+        this.#close = close;
+        void close.then(undefined, () => {
+            if (this.#close === close)
+                this.#close = undefined;
+        });
+        return close;
+    }
+    #closeReplica(replica) {
+        return ManagedServerCoordinatorValues.close(replica, this.#dependencies.clock);
+    }
+    async #closeRetired(replica) {
+        replica.expectedExit = true;
+        await this.#terminateRetired(replica);
+        this.#retired.delete(replica);
+    }
+    #terminateUnexpected(replica) {
+        this.#retired.add(replica);
+        void this.#terminateRetired(replica);
+    }
+    #terminateRetired(replica) {
+        const prior = this.#retireTerminations.get(replica);
+        if (prior !== undefined)
+            return prior;
+        const termination = ManagedServerCoordinatorValues.terminate(replica.child, this.#dependencies.clock);
+        this.#retireTerminations.set(replica, termination);
+        void termination.then(() => {
+            this.#retireTerminations.delete(replica);
+            this.#retired.delete(replica);
+        }, () => {
+            this.#retireTerminations.delete(replica);
+            // spine-log-boundary: server.managed_replica_termination
+            emitServerWarning(lifecycleLogger, "Managed replica termination was bounded.", {
+                operation: "managed_replica.terminate",
+                reasonCode: "unresponsive",
+                slot: String(replica.slot),
+                incarnation: replica.incarnation,
+            });
+        });
+        return termination;
+    }
+    /**
+     *
+     * Returns ready child facts to the next Coordinator slice.
+     *
+     * @returns The ready child topology facts.
+     * @internal
+     */
+    readyMembers() {
+        return this.#members(false);
+    }
+    /**
+     * Returns READY and synchronizing members whose relays remain eligible.
+     *
+     * @returns Private relay member facts.
+     */
+    relayMembers() {
+        return this.#members(true);
+    }
+    /**
+     * Records an exact native subscription whose activation started for a member.
+     *
+     * @param member Supplies the member that owns the child subscription.
+     * @param subscription Supplies the activating native subscription.
+     */
+    onChildSubscriptionActivated(member, subscription) {
+        const replica = this.#replica(member);
+        const id = subscription.id?.value;
+        if (replica === undefined || id === undefined || replica.subscriptionWaiters.has(id))
+            return;
+        replica.subscriptionWaiters.set(id, ManagedServerCoordinatorValues.deferred());
+    }
+    /**
+     * Clears a pending child-installation wait after cancellation.
+     *
+     * @param member Supplies the member that owns the cancelled subscription.
+     * @param subscription Supplies the cancelled native subscription.
+     */
+    onChildSubscriptionCancelled(member, subscription) {
+        const replica = this.#replica(member);
+        const id = subscription.id?.value;
+        if (replica !== undefined && id !== undefined)
+            this.#settleSubscriptionWaiter(replica, id);
+    }
+    /**
+     * Activates synchronizing children after their retained relay children install.
+     *
+     * @returns Completion after each current child receives private activation.
+     */
+    async onRelaySynchronized() {
+        const synchronizing = this.#slots
+            .map((slot) => slot.replica)
+            .filter((replica) => replica !== undefined && replica.synchronizing && replica.readyAt === undefined);
+        await Promise.all(synchronizing.flatMap((replica) => [...replica.subscriptionWaiters.values()].map((waiter) => waiter.promise)));
+        for (const replica of synchronizing)
+            if (!replica.terminal && replica.synchronizing && replica.readyAt === undefined)
+                replica.child.send({ type: "activate" }, () => undefined);
+    }
+    #replica(member) {
+        const replica = this.#slots[member.slot]?.replica;
+        return replica?.incarnation === member.incarnation ? replica : undefined;
+    }
+    #clearSubscriptionWaiters(replica, error) {
+        for (const waiter of replica.subscriptionWaiters.values())
+            waiter.reject(error);
+        replica.subscriptionWaiters.clear();
+    }
+    #settleSubscriptionWaiter(replica, id) {
+        const waiter = replica.subscriptionWaiters.get(id);
+        if (waiter === undefined)
+            return;
+        replica.subscriptionWaiters.delete(id);
+        waiter.resolve(undefined);
+    }
+    #members(includeDraining) {
+        return this.#slots.flatMap((slot) => {
+            const replica = slot.replica;
+            if ((replica?.readyAt === undefined && !(includeDraining && replica?.synchronizing)) ||
+                (!includeDraining && replica.draining) ||
+                replica.endpoint === undefined ||
+                replica.child.pid === undefined)
+                return [];
+            return [
+                {
+                    slot: slot.slot,
+                    incarnation: replica.incarnation,
+                    pid: replica.child.pid,
+                    endpoint: replica.endpoint,
+                },
+            ];
+        });
+    }
+    /**
+     * Subscribes one private Coordinator to READY membership changes.
+     *
+     * @param onChange Runs after an admitted READY member or removed member changes.
+     * @returns Stops later private notifications.
+     * @internal
+     */
+    onReadyMembersChange(onChange) {
+        this.#memberListeners.add(onChange);
+        return () => this.#memberListeners.delete(onChange);
+    }
+    /**
+     * Subscribes one private Coordinator to relay-membership changes.
+     *
+     * @param onChange Runs after a relay member is admitted or removed.
+     * @returns Stops later relay-membership callbacks.
+     */
+    onRelayMembersChange(onChange) {
+        return this.onReadyMembersChange(onChange);
+    }
+    /**
+     * Returns the private public-listener endpoint for coordinator acceptance.
+     *
+     * @returns The listener endpoint after managed startup, when open.
+     * @internal
+     */
+    coordinatorEndpoint() {
+        return this.#nodeCoordinator?.baseUrl;
+    }
+    #notifyReadyMembers() {
+        for (const listener of this.#memberListeners)
+            listener();
+    }
+    #installSignalHandlers() {
+        if (this.#onSignal !== undefined)
+            return;
+        this.#onSignal = () => {
+            // spine-log-boundary: server.managed_replica_signal
+            void this.close()
+                .then(() => {
+                if (process.connected && typeof process.disconnect === "function")
+                    process.disconnect();
+            })
+                .catch(() => {
+                emitServerWarning(lifecycleLogger, "Managed replica signal close failed.", {
+                    operation: "managed_replica.signal",
+                    reasonCode: "close_failed",
+                });
+            });
+        };
+        process.on("SIGINT", this.#onSignal);
+        process.on("SIGTERM", this.#onSignal);
+    }
+    #removeSignalHandlers() {
+        if (this.#onSignal === undefined)
+            return;
+        process.off("SIGINT", this.#onSignal);
+        process.off("SIGTERM", this.#onSignal);
+        this.#onSignal = undefined;
+    }
+}
+/**
+ *
+ * Exposes private Coordinator topology facts to the next internal slice.
+ *
+ * @internal
+ */
+export const managedServerCoordinatorAccess = Object.freeze({
+    readyMembers(coordinator) {
+        return coordinator.readyMembers();
+    },
+    coordinatorEndpoint(coordinator) {
+        return coordinator.coordinatorEndpoint();
+    },
+});
+/**
+ *
+ * Exposes private managed-child facts to Coordinator forwarding tests.
+ *
+ * @internal
+ */
+export const managedServerApplicationAccess = Object.freeze({
+    readyMembers(handle) {
+        return handleMembers.get(handle)?.readyMembers() ?? [];
+    },
+    coordinatorEndpoint(handle) {
+        return handleMembers.get(handle)?.coordinatorEndpoint();
+    },
+    installRegistriesForTest(server, registries) {
+        managedTestRegistries.set(server, registries);
+    },
+});
+const ManagedServerCoordinatorValues = Object.freeze({
+    deferred() {
+        let resolve;
+        let reject;
+        const promise = new Promise((next, fail) => {
+            resolve = next;
+            reject = fail;
+        });
+        return { promise, resolve, reject };
+    },
+    coordinatorPort(value) {
+        if (!Number.isSafeInteger(value) || value < 1 || value > 65_535)
+            throw new Error("Managed server Coordinator port must be a safe integer between 1 and 65535.");
+        return value;
+    },
+    dependencies: {
+        clock: {
+            now: () => Date.now(),
+            setTimeout: (onTimeout, delay) => setTimeout(onTimeout, delay),
+            clearTimeout: (timer) => {
+                clearTimeout(timer);
+            },
+        },
+        spawn: (moduleUrl, slot, incarnation) => fork(fileURLToPath(moduleUrl), [], {
+            env: {
+                ...process.env,
+                [childMarker]: "true",
+                [slotMarker]: String(slot),
+                [incarnationMarker]: incarnation,
+            },
+            stdio: ["inherit", "inherit", "inherit", "ipc"],
+        }),
+        openCoordinator: (options) => NodeCoordinator.open(options),
+    },
+    restart(options) {
+        const restart = {
+            initialDelayMs: options.restart?.initialDelayMs ?? initialRestartDelayMs,
+            maximumDelayMs: options.restart?.maximumDelayMs ?? maximumRestartDelayMs,
+            healthyReadyMs: options.restart?.healthyReadyMs ?? healthyReadyMs,
+            concurrentStarts: options.restart?.concurrentStarts ?? Math.min(4, options.processCount),
+        };
+        for (const [name, value] of Object.entries(restart)) {
+            if (!Number.isSafeInteger(value) || value < 1)
+                throw new Error(`Managed server restart ${name} must be a positive safe integer.`);
+        }
+        if (restart.maximumDelayMs < restart.initialDelayMs)
+            throw new Error("Managed server restart maximumDelayMs must not be below initialDelayMs.");
+        if (restart.concurrentStarts > options.processCount)
+            throw new Error("Managed server restart concurrentStarts must not exceed processCount.");
+        return restart;
+    },
+    readyMessage(message, slot, incarnation) {
+        if (typeof message !== "object" || message === null)
+            return false;
+        const candidate = message;
+        return (candidate.type === "ready" &&
+            candidate.slot === String(slot) &&
+            candidate.incarnation === incarnation &&
+            typeof candidate.endpoint === "string" &&
+            canonicalLoopbackEndpoint(candidate.endpoint) !== undefined);
+    },
+    synchronizingMessage(message, slot, incarnation) {
+        if (typeof message !== "object" || message === null)
+            return false;
+        const candidate = message;
+        return (candidate.type === "synchronizing" &&
+            candidate.slot === String(slot) &&
+            candidate.incarnation === incarnation &&
+            typeof candidate.endpoint === "string" &&
+            canonicalLoopbackEndpoint(candidate.endpoint) !== undefined);
+    },
+    subscriptionInstalledMessage(message, slot, incarnation) {
+        if (typeof message !== "object" || message === null)
+            return false;
+        const candidate = message;
+        return (candidate.type === "subscription-installed" &&
+            candidate.slot === String(slot) &&
+            candidate.incarnation === incarnation &&
+            typeof candidate.subscriptionId === "string" &&
+            candidate.subscriptionId.length > 0);
+    },
+    drainingMessage(message, slot, incarnation) {
+        if (typeof message !== "object" || message === null)
+            return false;
+        const candidate = message;
+        return (candidate.type === "draining" &&
+            candidate.slot === String(slot) &&
+            candidate.incarnation === incarnation);
+    },
+    closeResultMessage(message, slot, incarnation) {
+        if (typeof message !== "object" || message === null)
+            return undefined;
+        const candidate = message;
+        if ((candidate.type !== "closed" && candidate.type !== "close-failed") ||
+            candidate.slot !== String(slot) ||
+            candidate.incarnation !== incarnation)
+            return undefined;
+        return candidate.type;
+    },
+    async close(replica, clock) {
+        if (replica === undefined)
+            return;
+        replica.expectedExit = true;
+        const { child } = replica;
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        const exited = new Promise((resolve) => child.once("exit", () => {
+            resolve();
+        }));
+        const closeAttempt = {
+            acknowledged: ManagedServerCoordinatorValues.deferred(),
+            outcome: ManagedServerCoordinatorValues.deferred(),
+        };
+        replica.closeAttempt = closeAttempt;
+        try {
+            if (child.connected)
+                child.send({ type: "close" }, () => undefined);
+            const observation = Promise.race([
+                closeAttempt.acknowledged.promise.then(() => "acknowledged"),
+                exited.then(() => "exited"),
+            ]);
+            if (await ManagedServerCoordinatorValues.within(observation, closeGraceMs, clock)) {
+                if ((await observation) === "exited")
+                    return;
+                await Promise.race([
+                    closeAttempt.outcome.promise,
+                    exited.then(() => {
+                        throw new Error("Managed child exited before graceful close completed.");
+                    }),
+                ]);
+                await ManagedServerCoordinatorValues.terminate(child, clock, exited);
+                return;
+            }
+            await ManagedServerCoordinatorValues.terminate(child, clock, exited, false);
+        }
+        finally {
+            if (replica.closeAttempt === closeAttempt)
+                replica.closeAttempt = undefined;
+        }
+    },
+    async terminate(child, clock, knownExit, allowGrace = true) {
+        if (child.exitCode !== null || child.signalCode !== null)
+            return;
+        const exited = knownExit ??
+            new Promise((resolve) => child.once("exit", () => {
+                resolve();
+            }));
+        if (allowGrace && (await ManagedServerCoordinatorValues.within(exited, closeGraceMs, clock)))
+            return;
+        child.kill("SIGTERM");
+        if (await ManagedServerCoordinatorValues.within(exited, closeKillMs, clock))
+            return;
+        child.kill("SIGKILL");
+        if (await ManagedServerCoordinatorValues.within(exited, closeKillMs, clock))
+            return;
+        throw new Error("Managed child did not exit after SIGKILL.");
+    },
+    within(promise, delay, clock) {
+        return new Promise((resolve) => {
+            const timer = clock.setTimeout(() => {
+                resolve(false);
+            }, delay);
+            void promise.then(() => {
+                clock.clearTimeout(timer);
+                resolve(true);
+            });
+        });
+    },
+});
+function canonicalLoopbackEndpoint(value) {
+    if (Buffer.byteLength(value, "utf8") > endpointMaximumBytes)
+        return undefined;
+    try {
+        const endpoint = new URL(value);
+        if (endpoint.protocol !== "http:" ||
+            endpoint.hostname !== "127.0.0.1" ||
+            endpoint.port === "" ||
+            endpoint.username !== "" ||
+            endpoint.password !== "" ||
+            endpoint.pathname !== "/" ||
+            endpoint.search !== "" ||
+            endpoint.hash !== "" ||
+            endpoint.origin !== value)
+            return undefined;
+        const port = Number(endpoint.port);
+        return Number.isSafeInteger(port) && port >= 1 && port <= 65_535 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=managed-server-application.js.map