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

package/dist/server/managed-server-application.d.ts

@@ -61,11 +61,11 @@ export interface ManagedServerApplicationOptions {
      *
      * Builds one complete local application server in a child process.
      *
-     * The framework owns the returned `Server` for the managed child lifetime.
+     * The framework manages the returned `Server` for the child lifetime.
      * Every assembled Bounded Context must use its actual
      * `InMemorySubscriptionRegistry`: managed mode rejects persistent and custom
      * registries, then closes the assembled server before the child can report
-     * READY. This prevents child-local durable subscription ownership.
+     * READY. This prevents durable subscriptions in a child-local registry.
      *
      * @param options Supplies the child-only loopback listener address.
      * @returns The assembled local application server.
@@ -126,10 +126,10 @@ export declare const ManagedServerApplication: Readonly<{
     /**
      *
      * Starts a managed parent and complete-replica children without taking
-     * process-signal ownership.
+     * process-signal handling.
      *
      * The caller closes the returned handle. This is for an embedding host that
-     * already owns `SIGINT` and `SIGTERM` handling.
+     * already handles `SIGINT` and `SIGTERM`.
      *
      * @param options Configures the managed application replicas.
      * @returns The started managed application handle.
@@ -255,14 +255,14 @@ export declare class ManagedServerCoordinator {
     /**
      * Records an exact native subscription whose activation started for a member.
      *
-     * @param member Supplies the member that owns the child subscription.
+     * @param member Identifies the member whose child subscription is activating.
      * @param subscription Supplies the activating native subscription.
      */
     onChildSubscriptionActivated(member: ReadyCoordinatorMember, subscription: Subscription): void;
     /**
      * Clears a pending child-installation wait after cancellation.
      *
-     * @param member Supplies the member that owns the cancelled subscription.
+     * @param member Identifies the member whose child subscription was cancelled.
      * @param subscription Supplies the cancelled native subscription.
      */
     onChildSubscriptionCancelled(member: ReadyCoordinatorMember, subscription: Subscription): void;
@@ -309,7 +309,19 @@ type ReadyMember = ReadyCoordinatorMember;
  * @internal
  */
 export declare const managedServerCoordinatorAccess: Readonly<{
+    /**
+     * Returns currently ready members for private coordinator inspection.
+     *
+     * @param coordinator The managed coordinator to inspect.
+     * @returns The currently ready coordinator members.
+     */
     readyMembers(coordinator: ManagedServerCoordinator): readonly ReadyMember[];
+    /**
+     * Returns the private coordinator endpoint when available.
+     *
+     * @param coordinator The managed coordinator to inspect.
+     * @returns The loopback endpoint when the coordinator is open.
+     */
     coordinatorEndpoint(coordinator: ManagedServerCoordinator): string | undefined;
 }>;
 /**
@@ -319,8 +331,26 @@ export declare const managedServerCoordinatorAccess: Readonly<{
  * @internal
  */
 export declare const managedServerApplicationAccess: Readonly<{
+    /**
+     * Returns currently ready members for private coordinator inspection.
+     *
+     * @param handle The application handle to inspect.
+     * @returns The currently ready coordinator members.
+     */
     readyMembers(handle: ManagedServerApplicationHandle): readonly ReadyMember[];
+    /**
+     * Returns the private coordinator endpoint when available.
+     *
+     * @param handle The application handle to inspect.
+     * @returns The loopback endpoint when the coordinator is open.
+     */
     coordinatorEndpoint(handle: ManagedServerApplicationHandle): string | undefined;
+    /**
+     * Associates in-memory registries with an assembled test server.
+     *
+     * @param server The assembled child server to inspect.
+     * @param registries The registries supplied by a test server.
+     */
     installRegistriesForTest(server: RunningServer, registries: readonly InMemorySubscriptionRegistry[]): void;
 }>;
 export {};

package/dist/server/managed-server-application.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"managed-server-application.d.ts","sourceRoot":"","sources":["../../src/server/managed-server-application.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"managed-server-application.d.ts","sourceRoot":"","sources":["../../src/server/managed-server-application.ts"],"names":[],"mappings":"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"}

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

@@ -11,6 +11,7 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
+import { Time } from "@spine-event-engine/core/time";
 import { fork } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
@@ -48,14 +49,33 @@ const lifecycleLogger = new LogLayer({
  * Starts a managed parent and its complete-replica child processes.
  */
 export const ManagedServerApplication = Object.freeze({
+    /**
+     * Validates replica count and port, then starts the parent coordinator or child application.
+     *
+     * @param options The replica count, listener, child module, and assembly callback.
+     * @returns The started application handle.
+     */
     async start(options) {
         return ManagedServerValues.start(options, false);
     },
+    /**
+     * Starts managed replicas and installs process signal handling.
+     *
+     * @param options The replica count, listener, and child assembly settings.
+     * @returns The started application handle.
+     */
     async run(options) {
         return ManagedServerValues.start(options, true);
     },
 });
 const ManagedServerValues = Object.freeze({
+    /**
+     * Validates replica count and port, then starts the parent coordinator or child application.
+     *
+     * @param options The replica count, listener, child module, and assembly callback.
+     * @param manageProcessSignals Whether the parent installs SIGINT and SIGTERM handlers.
+     * @returns The started application handle.
+     */
     async start(options, manageProcessSignals) {
         if (!Number.isSafeInteger(options.processCount) || options.processCount < 1) {
             throw new Error("Managed server processCount must be a positive safe integer.");
@@ -65,6 +85,12 @@ const ManagedServerValues = Object.freeze({
             return ManagedServerValues.child(options);
         return ManagedServerValues.parent(options, manageProcessSignals);
     },
+    /**
+     * Creates a child server, checks volatile registries, synchronizes, and participates in parent IPC.
+     *
+     * @param options The child server assembly and synchronization settings.
+     * @returns The active child application handle.
+     */
     async child(options) {
         const server = await options.createServer({ host: "127.0.0.1", port: 0 });
         try {
@@ -81,7 +107,7 @@ const ManagedServerValues = Object.freeze({
             throw error;
         }
         // Node may emit an IPC EPIPE after a parent has already disappeared. The
-        // disconnect handler below owns shutdown; this listener prevents that
+        // disconnect handler below handles shutdown; this listener prevents that
         // transport detail from becoming an unhandled child-process exception.
         const containIpcError = () => undefined;
         process.on("error", containIpcError);
@@ -190,9 +216,21 @@ const ManagedServerValues = Object.freeze({
             close,
         };
     },
+    /**
+     * Starts a coordinator for the configured complete-replica cohort.
+     *
+     * @param options The parent cohort and listener settings.
+     * @param manageProcessSignals Whether the parent installs SIGINT and SIGTERM handlers.
+     * @returns The started parent cohort handle.
+     */
     parent(options, manageProcessSignals) {
         return new ManagedServerCoordinator({ ...options, manageProcessSignals }).start();
     },
+    /**
+     * Starts child shutdown after an IPC close or disconnect event and logs failure.
+     *
+     * @param close The child shutdown callback.
+     */
     closeFromEvent(close) {
         // spine-log-boundary: server.managed_replica_child_close
         void close().catch(() => {
@@ -202,12 +240,23 @@ const ManagedServerValues = Object.freeze({
             });
         });
     },
+    /**
+     * Rejects child servers without exclusively in-memory subscription registries.
+     *
+     * @param server The assembled child server to inspect.
+     */
     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.");
     },
+    /**
+     * Sends a child lifecycle notification over the connected parent IPC channel.
+     *
+     * @param message The child lifecycle notification to send.
+     * @returns Completion after the parent IPC channel acknowledges the send.
+     */
     send(message) {
         return new Promise((resolve, reject) => {
             if (process.send === undefined || !process.connected) {
@@ -312,6 +361,11 @@ export class ManagedServerCoordinator {
         handleMembers.set(handle, this);
         return handle;
     }
+    /**
+     * Starts a child for an available slot while respecting the concurrent-start limit.
+     *
+     * @param slot The replica slot to start or update.
+     */
     #start(slot) {
         if (this.#closing ||
             slot.starting ||
@@ -366,6 +420,13 @@ export class ManagedServerCoordinator {
             this.#onError(slot, replica);
         });
     }
+    /**
+     * Processes a matching child lifecycle notification and updates readiness or shutdown state.
+     *
+     * @param slot The replica slot to start or update.
+     * @param replica The child incarnation associated with the event.
+     * @param message The untrusted child IPC notification.
+     */
     #onMessage(slot, replica, message) {
         const closeResult = ManagedServerCoordinatorValues.closeResultMessage(message, slot.slot, replica.incarnation);
         if (closeResult !== undefined) {
@@ -419,6 +480,12 @@ export class ManagedServerCoordinator {
         this.#notifyReadyMembers();
         this.#drainStarts();
     }
+    /**
+     * Retires an exited incarnation and schedules replacement after an unexpected exit.
+     *
+     * @param slot The replica slot to start or update.
+     * @param replica The child incarnation associated with the event.
+     */
     #onExit(slot, replica) {
         if (slot.replica !== replica || replica.terminal)
             return;
@@ -447,6 +514,12 @@ export class ManagedServerCoordinator {
         this.#scheduleReplacement(slot);
         this.#drainStarts();
     }
+    /**
+     * Retires a child after a process error and starts bounded termination.
+     *
+     * @param slot The replica slot to start or update.
+     * @param replica The child incarnation associated with the event.
+     */
     #onError(slot, replica) {
         if (slot.replica !== replica || replica.terminal)
             return;
@@ -455,6 +528,11 @@ export class ManagedServerCoordinator {
         this.#onExit(slot, replica);
         this.#terminateUnexpected(replica);
     }
+    /**
+     * Schedules exponential replacement delay capped by the configured maximum.
+     *
+     * @param slot The replica slot to start or update.
+     */
     #scheduleReplacement(slot) {
         slot.failures++;
         const delay = Math.min(this.#restart.initialDelayMs * 2 ** Math.max(0, slot.failures - 1), this.#restart.maximumDelayMs);
@@ -471,6 +549,10 @@ export class ManagedServerCoordinator {
             delay: String(delay),
         });
     }
+    /**
+     * Fills available concurrent-start capacity with unscheduled empty slots.
+     *
+     */
     #drainStarts() {
         for (const slot of this.#slots) {
             if (this.#starts >= this.#restart.concurrentStarts)
@@ -527,18 +609,41 @@ export class ManagedServerCoordinator {
         });
         return close;
     }
+    /**
+     * Closes the current replica through the bounded child shutdown procedure.
+     *
+     * @param replica The child incarnation associated with the event.
+     * @returns Completion after child shutdown.
+     */
     #closeReplica(replica) {
         return ManagedServerCoordinatorValues.close(replica, this.#dependencies.clock);
     }
+    /**
+     * Terminates a retired replica and removes it from the pending set.
+     *
+     * @param replica The child incarnation associated with the event.
+     * @returns Completion after the retired process exits.
+     */
     async #closeRetired(replica) {
         replica.expectedExit = true;
         await this.#terminateRetired(replica);
         this.#retired.delete(replica);
     }
+    /**
+     * Records a failed child for bounded background termination.
+     *
+     * @param replica The child incarnation associated with the event.
+     */
     #terminateUnexpected(replica) {
         this.#retired.add(replica);
         void this.#terminateRetired(replica);
     }
+    /**
+     * Reuses or starts bounded termination for one retired incarnation.
+     *
+     * @param replica The child incarnation associated with the event.
+     * @returns The shared termination attempt for this child.
+     */
     #terminateRetired(replica) {
         const prior = this.#retireTerminations.get(replica);
         if (prior !== undefined)
@@ -581,7 +686,7 @@ export class ManagedServerCoordinator {
     /**
      * Records an exact native subscription whose activation started for a member.
      *
-     * @param member Supplies the member that owns the child subscription.
+     * @param member Identifies the member whose child subscription is activating.
      * @param subscription Supplies the activating native subscription.
      */
     onChildSubscriptionActivated(member, subscription) {
@@ -594,7 +699,7 @@ export class ManagedServerCoordinator {
     /**
      * Clears a pending child-installation wait after cancellation.
      *
-     * @param member Supplies the member that owns the cancelled subscription.
+     * @param member Identifies the member whose child subscription was cancelled.
      * @param subscription Supplies the cancelled native subscription.
      */
     onChildSubscriptionCancelled(member, subscription) {
@@ -617,15 +722,33 @@ export class ManagedServerCoordinator {
             if (!replica.terminal && replica.synchronizing && replica.readyAt === undefined)
                 replica.child.send({ type: "activate" }, () => undefined);
     }
+    /**
+     * Finds the current replica only when both slot and incarnation match.
+     *
+     * @param member The member slot and incarnation to resolve.
+     * @returns The matching current replica, if any.
+     */
     #replica(member) {
         const replica = this.#slots[member.slot]?.replica;
         return replica?.incarnation === member.incarnation ? replica : undefined;
     }
+    /**
+     * Rejects pending subscription installation waits after a child exits.
+     *
+     * @param replica The child incarnation associated with the event.
+     * @param error The error reported to pending subscription waits.
+     */
     #clearSubscriptionWaiters(replica, error) {
         for (const waiter of replica.subscriptionWaiters.values())
             waiter.reject(error);
         replica.subscriptionWaiters.clear();
     }
+    /**
+     * Completes and removes the pending installation wait for a subscription ID.
+     *
+     * @param replica The child incarnation associated with the event.
+     * @param id The installed subscription identifier.
+     */
     #settleSubscriptionWaiter(replica, id) {
         const waiter = replica.subscriptionWaiters.get(id);
         if (waiter === undefined)
@@ -633,6 +756,12 @@ export class ManagedServerCoordinator {
         replica.subscriptionWaiters.delete(id);
         waiter.resolve(undefined);
     }
+    /**
+     * Collects active child facts eligible for routing or relay synchronization.
+     *
+     * @param includeDraining Whether synchronizing and draining replicas may participate in relay membership.
+     * @returns The eligible child members with endpoint and process ID.
+     */
     #members(includeDraining) {
         return this.#slots.flatMap((slot) => {
             const replica = slot.replica;
@@ -680,10 +809,18 @@ export class ManagedServerCoordinator {
     coordinatorEndpoint() {
         return this.#nodeCoordinator?.baseUrl;
     }
+    /**
+     * Calls listeners after the available child membership changes.
+     *
+     */
     #notifyReadyMembers() {
         for (const listener of this.#memberListeners)
             listener();
     }
+    /**
+     * Registers managed shutdown handlers for SIGINT and SIGTERM once.
+     *
+     */
     #installSignalHandlers() {
         if (this.#onSignal !== undefined)
             return;
@@ -704,6 +841,10 @@ export class ManagedServerCoordinator {
         process.on("SIGINT", this.#onSignal);
         process.on("SIGTERM", this.#onSignal);
     }
+    /**
+     * Unregisters managed shutdown handlers when the coordinator closes.
+     *
+     */
     #removeSignalHandlers() {
         if (this.#onSignal === undefined)
             return;
@@ -719,9 +860,21 @@ export class ManagedServerCoordinator {
  * @internal
  */
 export const managedServerCoordinatorAccess = Object.freeze({
+    /**
+     * Returns currently ready members for private coordinator inspection.
+     *
+     * @param coordinator The managed coordinator to inspect.
+     * @returns The currently ready coordinator members.
+     */
     readyMembers(coordinator) {
         return coordinator.readyMembers();
     },
+    /**
+     * Returns the private coordinator endpoint when available.
+     *
+     * @param coordinator The managed coordinator to inspect.
+     * @returns The loopback endpoint when the coordinator is open.
+     */
     coordinatorEndpoint(coordinator) {
         return coordinator.coordinatorEndpoint();
     },
@@ -733,17 +886,41 @@ export const managedServerCoordinatorAccess = Object.freeze({
  * @internal
  */
 export const managedServerApplicationAccess = Object.freeze({
+    /**
+     * Returns currently ready members for private coordinator inspection.
+     *
+     * @param handle The application handle to inspect.
+     * @returns The currently ready coordinator members.
+     */
     readyMembers(handle) {
         return handleMembers.get(handle)?.readyMembers() ?? [];
     },
+    /**
+     * Returns the private coordinator endpoint when available.
+     *
+     * @param handle The application handle to inspect.
+     * @returns The loopback endpoint when the coordinator is open.
+     */
     coordinatorEndpoint(handle) {
         return handleMembers.get(handle)?.coordinatorEndpoint();
     },
+    /**
+     * Associates in-memory registries with an assembled test server.
+     *
+     * @param server The assembled child server to inspect.
+     * @param registries The registries supplied by a test server.
+     */
     installRegistriesForTest(server, registries) {
         managedTestRegistries.set(server, registries);
     },
 });
 const ManagedServerCoordinatorValues = Object.freeze({
+    /**
+     * Creates a promise with separately accessible resolve and reject callbacks.
+     *
+     * @typeParam Value The eventual result carried by the deferred promise.
+     * @returns The promise and its settlement callbacks.
+     */
     deferred() {
         let resolve;
         let reject;
@@ -753,6 +930,12 @@ const ManagedServerCoordinatorValues = Object.freeze({
         });
         return { promise, resolve, reject };
     },
+    /**
+     * Checks that the front-facing listener port is a safe integer from zero through 65535.
+     *
+     * @param value The candidate front-facing listener port.
+     * @returns The validated listener port.
+     */
     coordinatorPort(value) {
         if (!Number.isSafeInteger(value) || value < 0 || value > 65_535)
             throw new Error("Managed server Coordinator port must be a safe integer between 0 and 65535.");
@@ -760,7 +943,7 @@ const ManagedServerCoordinatorValues = Object.freeze({
     },
     dependencies: {
         clock: {
-            now: () => Date.now(),
+            now: () => Time.currentTimeMillis(),
             setTimeout: (onTimeout, delay) => setTimeout(onTimeout, delay),
             clearTimeout: (timer) => {
                 clearTimeout(timer);
@@ -777,6 +960,12 @@ const ManagedServerCoordinatorValues = Object.freeze({
         }),
         openCoordinator: (options) => NodeCoordinator.open(options),
     },
+    /**
+     * Validates restart delays and concurrent-start bounds after applying defaults.
+     *
+     * @param options The requested process count and restart settings.
+     * @returns The validated restart policy with defaults applied.
+     */
     restart(options) {
         const restart = {
             initialDelayMs: options.restart?.initialDelayMs ?? initialRestartDelayMs,
@@ -794,6 +983,14 @@ const ManagedServerCoordinatorValues = Object.freeze({
             throw new Error("Managed server restart concurrentStarts must not exceed processCount.");
         return restart;
     },
+    /**
+     * Checks a READY notification against the expected slot, incarnation, and loopback endpoint.
+     *
+     * @param message The candidate child IPC notification.
+     * @param slot The expected replica slot.
+     * @param incarnation The expected child incarnation token.
+     * @returns Whether the message is a valid READY notification.
+     */
     readyMessage(message, slot, incarnation) {
         if (typeof message !== "object" || message === null)
             return false;
@@ -804,6 +1001,14 @@ const ManagedServerCoordinatorValues = Object.freeze({
             typeof candidate.endpoint === "string" &&
             canonicalLoopbackEndpoint(candidate.endpoint) !== undefined);
     },
+    /**
+     * Checks a SYNCHRONIZING notification against the expected child and endpoint.
+     *
+     * @param message The candidate child IPC notification.
+     * @param slot The expected replica slot.
+     * @param incarnation The expected child incarnation token.
+     * @returns Whether the message is a valid SYNCHRONIZING notification.
+     */
     synchronizingMessage(message, slot, incarnation) {
         if (typeof message !== "object" || message === null)
             return false;
@@ -814,6 +1019,14 @@ const ManagedServerCoordinatorValues = Object.freeze({
             typeof candidate.endpoint === "string" &&
             canonicalLoopbackEndpoint(candidate.endpoint) !== undefined);
     },
+    /**
+     * Checks a subscription-installed notification for the expected child and nonblank ID.
+     *
+     * @param message The candidate child IPC notification.
+     * @param slot The expected replica slot.
+     * @param incarnation The expected child incarnation token.
+     * @returns Whether the message is a matching subscription notification.
+     */
     subscriptionInstalledMessage(message, slot, incarnation) {
         if (typeof message !== "object" || message === null)
             return false;
@@ -824,6 +1037,14 @@ const ManagedServerCoordinatorValues = Object.freeze({
             typeof candidate.subscriptionId === "string" &&
             candidate.subscriptionId.length > 0);
     },
+    /**
+     * Checks a DRAINING notification against the expected slot and incarnation.
+     *
+     * @param message The candidate child IPC notification.
+     * @param slot The expected replica slot.
+     * @param incarnation The expected child incarnation token.
+     * @returns Whether the message is a matching DRAINING notification.
+     */
     drainingMessage(message, slot, incarnation) {
         if (typeof message !== "object" || message === null)
             return false;
@@ -832,6 +1053,14 @@ const ManagedServerCoordinatorValues = Object.freeze({
             candidate.slot === String(slot) &&
             candidate.incarnation === incarnation);
     },
+    /**
+     * Matches a CLOSED or CLOSE-FAILED notification from the expected child.
+     *
+     * @param message The candidate child IPC notification.
+     * @param slot The expected replica slot.
+     * @param incarnation The expected child incarnation token.
+     * @returns The close outcome for a matching notification, or undefined.
+     */
     closeResultMessage(message, slot, incarnation) {
         if (typeof message !== "object" || message === null)
             return undefined;
@@ -842,6 +1071,13 @@ const ManagedServerCoordinatorValues = Object.freeze({
             return undefined;
         return candidate.type;
     },
+    /**
+     * Closes a child after bounded graceful shutdown and signal escalation.
+     *
+     * @param replica The replica to close, if still present.
+     * @param clock The clock and timer adapter for bounded waits.
+     * @returns Completion after the child exits or a shutdown error is reported.
+     */
     async close(replica, clock) {
         if (replica === undefined)
             return;
@@ -883,6 +1119,15 @@ const ManagedServerCoordinatorValues = Object.freeze({
                 replica.closeAttempt = undefined;
         }
     },
+    /**
+     * Waits for child exit, then escalates through SIGTERM and SIGKILL within bounded intervals.
+     *
+     * @param child The child process to terminate.
+     * @param clock The clock and timer adapter for bounded waits.
+     * @param knownExit An existing promise for child exit, when available.
+     * @param allowGrace Whether to wait for graceful exit before signaling.
+     * @returns Completion after child exit or failure to terminate.
+     */
     async terminate(child, clock, knownExit, allowGrace = true) {
         if (child.exitCode !== null || child.signalCode !== null)
             return;
@@ -900,6 +1145,14 @@ const ManagedServerCoordinatorValues = Object.freeze({
             return;
         throw new Error("Managed child did not exit after SIGKILL.");
     },
+    /**
+     * Checks whether a promise settles before the supplied timer fires.
+     *
+     * @param promise The asynchronous operation to await.
+     * @param delay The maximum wait in milliseconds.
+     * @param clock The clock and timer adapter for bounded waits.
+     * @returns Whether the promise settled within the delay.
+     */
     within(promise, delay, clock) {
         return new Promise((resolve) => {
             const timer = clock.setTimeout(() => {