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

package/dist/stand/subscription-runtime.js

@@ -0,0 +1,380 @@
+/*
+ * 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.
+ */
+var _a;
+import { create, toBinary } from "@bufbuild/protobuf";
+import { SubscriptionIdSchema, SubscriptionSchema, } from "@spine-event-engine/proto/client";
+import { emitServerWarning } from "../server/server-log.js";
+import { SubscriptionObservers } from "./subscription-observer.js";
+import { standAccess } from "./stand.js";
+const subscriptionRuntimeLoggers = new WeakMap();
+const subscriptionRuntimes = new WeakSet();
+/**
+ * Coordinates the local delivery side of one paired bounded context's durable
+ * subscription registry.
+ *
+ * The runtime owns exactly one registry snapshot loop, timer, attachment map,
+ * and consumer map. It classifies a target from domain Stand metadata before
+ * attaching it: domain events observe only the domain bus, while entity-state
+ * updates observe only the paired System bus. This keeps a subscription ID and
+ * attachment identity attached once, while allowing all active service streams to share
+ * the same rendered update.
+ *
+ * @internal
+ */
+export class SubscriptionRuntime {
+    #domainStand;
+    #systemStand;
+    #domainEventBus;
+    #systemEventBus;
+    #registry;
+    #consumers = new Map();
+    #attachments = new Map();
+    #tail = Promise.resolve();
+    #timer;
+    #timerReconciliation;
+    #closing = false;
+    #closed;
+    /**
+     * Creates an unstarted runtime for a paired domain and System Stand.
+     *
+     * @param domainStand Supplies authoritative domain state metadata.
+     * @param systemStand Retained as the paired state-observer owner boundary.
+     * @param domainEventBus Delivers domain-event subscription targets.
+     * @param systemEventBus Delivers Entity state and lifecycle subscription targets.
+     * @param registry Stores canonical subscription definitions in the domain namespace.
+     */
+    constructor(domainStand, systemStand, domainEventBus, systemEventBus, registry) {
+        subscriptionRuntimes.add(this);
+        this.#domainStand = domainStand;
+        this.#systemStand = systemStand;
+        this.#domainEventBus = domainEventBus;
+        this.#systemEventBus = systemEventBus;
+        this.#registry = registry;
+    }
+    /**
+     * Starts immediate and ten-second complete-snapshot reconciliation.
+     */
+    start() {
+        if (this.#timer !== undefined || this.#closing)
+            return;
+        // spine-log-boundary: server.subscription_initial_reconcile
+        void this.reconcile().catch(() => {
+            this.#warnReconciliationFailure();
+        });
+        this.#timer = setInterval(() => {
+            void this.#reconcileTimer();
+        }, 10_000);
+        this.#timer.unref();
+    }
+    /**
+     * Adds a local stream consumer and reconciles before returning its handle.
+     *
+     * @param id Identifies the durable subscription definition.
+     * @param onUpdate Receives rendered subscription updates.
+     * @returns Resolves to the consumer removal handle.
+     */
+    consume(id, onUpdate) {
+        if (this.#closing)
+            return Promise.reject(new Error("Subscription runtime is closing."));
+        let consumers = this.#consumers.get(id);
+        if (consumers === undefined) {
+            consumers = new Set();
+            this.#consumers.set(id, consumers);
+        }
+        consumers.add(onUpdate);
+        return this.reconcile()
+            .then(() => this.#consumerHandle(id, onUpdate))
+            .catch((error) => {
+            this.#removeConsumer(id, onUpdate);
+            throw error;
+        });
+    }
+    /**
+     * Updates local attachments from one complete registry snapshot.
+     *
+     * @returns Resolves after the accepted snapshot is reconciled.
+     */
+    reconcile() {
+        const cycle = this.#tail.then(async () => {
+            if (this.#closing)
+                return;
+            await this.#registry.cleanup();
+            const entries = await this.#registry.snapshot();
+            const seen = new Set();
+            for (const entry of entries) {
+                const id = entry.subscription.id?.value;
+                if (id === undefined)
+                    continue;
+                seen.add(id);
+                if (entry.phase === "active")
+                    await this.#attach(id, entry);
+                else
+                    this.remove(id);
+            }
+            for (const id of this.#attachments.keys())
+                if (!seen.has(id))
+                    this.remove(id);
+        });
+        // spine-log-boundary: server.subscription_reconcile_tail
+        this.#tail = cycle.catch(() => undefined);
+        return cycle;
+    }
+    #reconcileTimer() {
+        if (this.#timerReconciliation !== undefined)
+            return this.#timerReconciliation;
+        const reconciliation = this.reconcile().finally(() => {
+            this.#timerReconciliation = undefined;
+        });
+        this.#timerReconciliation = reconciliation;
+        // spine-log-boundary: server.subscription_timer_reconcile
+        void reconciliation.catch(() => {
+            this.#warnReconciliationFailure();
+        });
+        return reconciliation;
+    }
+    #warnReconciliationFailure() {
+        const logger = subscriptionRuntimeLoggers.get(this);
+        if (logger === undefined)
+            return;
+        emitServerWarning(logger, "Subscription reconciliation failed.", {
+            operation: "subscription.reconcile",
+            reasonCode: "failed",
+        });
+    }
+    /**
+     * Removes all local delivery state for one canonical subscription ID.
+     *
+     * @param id Identifies the durable subscription definition.
+     */
+    remove(id) {
+        this.#consumers.delete(id);
+        this.#detach(id);
+    }
+    #detach(id) {
+        const attachment = this.#attachments.get(id);
+        if (attachment === undefined)
+            return;
+        this.#attachments.delete(id);
+        attachment.subscription.unsubscribe();
+    }
+    /**
+     * Returns the pair-owned durable registry.
+     *
+     * @returns Returns the durable subscription registry.
+     */
+    registry() {
+        return this.#registry;
+    }
+    /**
+     * Marks the runtime terminal and stops its reconciliation timer.
+     */
+    beginClose() {
+        this.#closing = true;
+        if (this.#timer !== undefined)
+            clearInterval(this.#timer);
+    }
+    /**
+     * Waits for accepted reconciliation and detaches every observer.
+     *
+     * @returns Resolves after every local observer has been detached.
+     */
+    async drainClose() {
+        this.beginClose();
+        await this.#tail;
+        const errors = [];
+        for (const id of [...this.#attachments.keys()]) {
+            try {
+                this.remove(id);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        this.#consumers.clear();
+        if (errors.length > 0)
+            throw new AggregateError(errors, "Subscription runtime close failed.");
+    }
+    /**
+     * Closes the shared registry after observer cleanup.
+     *
+     * @returns Resolves after the durable registry closes.
+     */
+    finishClose() {
+        this.#closed ??= this.#finishClose();
+        return this.#closed;
+    }
+    async #finishClose() {
+        const errors = [];
+        await _a.#closePart(() => this.drainClose(), errors);
+        await _a.#closePart(() => this.#registry.close(), errors);
+        if (errors.length > 0) {
+            throw new AggregateError(errors.flatMap((error) => error instanceof AggregateError
+                ? Array.from(error.errors, (nested) => nested)
+                : [error]), "Subscription runtime close failed.");
+        }
+    }
+    /**
+     * Performs all close phases for direct runtime owners.
+     *
+     * @returns Resolves after runtime shutdown completes.
+     */
+    close() {
+        return this.finishClose();
+    }
+    /**
+     * Starts failed-construction cleanup before the context has exposed the runtime.
+     *
+     * @internal
+     */
+    abortClose() {
+        this.#closed ??= this.#abortClose();
+    }
+    async #abortClose() {
+        this.beginClose();
+        const registryClose = _a.#closeThunk(() => this.#registry.close());
+        await Promise.allSettled([this.drainClose(), registryClose]);
+    }
+    #consumerHandle(id, onUpdate) {
+        let closed = false;
+        return Object.freeze({
+            get closed() {
+                return closed;
+            },
+            unsubscribe: () => {
+                if (closed)
+                    return;
+                closed = true;
+                this.#removeConsumer(id, onUpdate);
+            },
+        });
+    }
+    #removeConsumer(id, onUpdate) {
+        const consumers = this.#consumers.get(id);
+        consumers?.delete(onUpdate);
+        if (consumers?.size === 0)
+            this.#consumers.delete(id);
+    }
+    async #attach(id, expected) {
+        const current = await this.#registry.get(create(SubscriptionIdSchema, { value: id }));
+        if (current?.phase !== "active" || !sameEntry(current, expected) || this.#closing)
+            return;
+        const identity = entryIdentity(current);
+        if (sameBytes(this.#attachments.get(id)?.identity, identity))
+            return;
+        this.#detach(id);
+        const state = standAccess.observedState(this.#domainStand, current.subscription.topic?.target?.type);
+        const attachment = state === undefined
+            ? SubscriptionObservers.observeEvent(current.subscription, this.#domainEventBus, (update) => {
+                this.#notify(id, update);
+            })
+            : standAccess.observeState(this.#systemStand, current.subscription, state, this.#systemEventBus, (update) => {
+                this.#notify(id, update);
+            });
+        if (attachment !== undefined)
+            this.#attachments.set(id, { identity, subscription: attachment });
+    }
+    static async #closePart(work, errors) {
+        try {
+            await work();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    static async #closeThunk(work) {
+        await work();
+    }
+    #notify(id, update) {
+        for (const consumer of [...(this.#consumers.get(id) ?? [])]) {
+            const logger = subscriptionRuntimeLoggers.get(this);
+            try {
+                const invoke = consumer;
+                const outcome = invoke(update);
+                if (_a.#isPromiseLike(outcome)) {
+                    // spine-log-boundary: server.subscription_consumer_async_delivery
+                    void Promise.resolve(outcome).catch(() => {
+                        _a.#warnConsumerFailure(logger, id);
+                    });
+                }
+                // spine-log-boundary: server.subscription_consumer_delivery
+            }
+            catch {
+                // Individual best-effort stream consumers cannot suppress peers.
+                _a.#warnConsumerFailure(logger, id);
+            }
+        }
+    }
+    static #warnConsumerFailure(logger, id) {
+        if (logger === undefined)
+            return;
+        emitServerWarning(logger, "Subscription consumer delivery failed.", {
+            subscriptionId: id,
+            operation: "subscription.consumer",
+            reasonCode: "failed",
+        });
+    }
+    static #isPromiseLike(value) {
+        return ((typeof value === "object" || typeof value === "function") &&
+            value !== null &&
+            "then" in value &&
+            typeof value.then === "function");
+    }
+}
+_a = SubscriptionRuntime;
+/**
+ * Exposes framework-only subscription-runtime logging metadata installation.
+ *
+ * @internal
+ */
+export const subscriptionRuntimeAccess = Object.freeze({
+    installLogger(runtime, logger) {
+        if (!subscriptionRuntimes.has(runtime)) {
+            throw new TypeError("Subscription runtime logger requires a SubscriptionRuntime instance.");
+        }
+        subscriptionRuntimeLoggers.set(runtime, logger);
+    },
+    clearLogger(runtime) {
+        if (!subscriptionRuntimes.has(runtime)) {
+            throw new TypeError("Subscription runtime logger requires a SubscriptionRuntime instance.");
+        }
+        subscriptionRuntimeLoggers.delete(runtime);
+    },
+    loggerFor(runtime) {
+        if (!subscriptionRuntimes.has(runtime)) {
+            throw new TypeError("Subscription runtime logger requires a SubscriptionRuntime instance.");
+        }
+        const logger = subscriptionRuntimeLoggers.get(runtime);
+        if (logger === undefined)
+            throw new TypeError("Subscription runtime logger is not installed.");
+        return logger;
+    },
+});
+function entryIdentity(entry) {
+    const subscription = toBinary(SubscriptionSchema, entry.subscription);
+    const createdAt = new Uint8Array(8);
+    new DataView(createdAt.buffer).setFloat64(0, entry.createdAt);
+    const identity = new Uint8Array(subscription.length + createdAt.length);
+    identity.set(subscription);
+    identity.set(createdAt, subscription.length);
+    return identity;
+}
+function sameEntry(left, right) {
+    return (left.phase === right.phase &&
+        left.createdAt === right.createdAt &&
+        sameBytes(entryIdentity(left), entryIdentity(right)));
+}
+function sameBytes(left, right) {
+    return left?.length === right.length && left.every((value, index) => value === right[index]);
+}
+//# sourceMappingURL=subscription-runtime.js.map

package/dist/stand/subscription-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-runtime.js","sourceRoot":"","sources":["../../src/stand/subscription-runtime.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -0,0 +1,36 @@
+import { type BoundedContext } from "../context/bounded-context.js";
+import type { Command, Event } from "@spine-event-engine/proto";
+export { unpackExternalEvent, wrapBoundedContextOnline, wrapExternalEvent, wrapExternalEventsWanted, } from "../integration/external-messages.js";
+/**
+ * Provides deterministic server-environment cleanup for package tests.
+ */
+export declare const ServerTests: {
+    readonly resetEnvironment: () => Promise<void>;
+};
+/**
+ * Resets shared server facilities before the next test creates a server.
+ */
+declare const serverTestReset: () => Promise<void>;
+export { serverTestReset as resetServerEnvironmentForTest };
+/**
+ * Posts a locally constructed Event through the bounded context's external intake path.
+ *
+ * @param context Receives the external Event.
+ * @param event Event envelope whose external origin is preserved.
+ * @returns Completion after external dispatch admission.
+ */
+export declare function postExternalEvent(context: BoundedContext, event: Event): Promise<void>;
+/**
+ * Observes produced signals admitted by one bounded context.
+ *
+ * @param context Produces the observed signals.
+ * @param observer Receives cloned admitted Command and Event envelopes.
+ * @returns A handle that stops observation.
+ */
+export declare function observeProducedSignals(context: BoundedContext, observer: {
+    readonly onCommand?: (command: Readonly<Command>) => void;
+    readonly onEvent?: (event: Readonly<Event>) => void;
+}): {
+    readonly close: () => void;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAeA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC1F,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAEhE,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,qCAAqC,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE;IAAE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CASxE,CAAC;AAEH;;GAEG;AACH,QAAA,MAAM,eAAe,EAAE,MAAM,OAAO,CAAC,IAAI,CAAgC,CAAC;AAE1E,OAAO,EAAE,eAAe,IAAI,6BAA6B,EAAE,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtF;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE;IACR,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC1D,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;CACrD,GACA;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAEhC"}

package/dist/testing/index.js

@@ -0,0 +1,54 @@
+/*
+ * 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 { ServerEnvironmentLifecycle } from "../server/server-environment.js";
+import { boundedContextAccess } from "../context/bounded-context.js";
+export { unpackExternalEvent, wrapBoundedContextOnline, wrapExternalEvent, wrapExternalEventsWanted, } from "../integration/external-messages.js";
+/**
+ * Provides deterministic server-environment cleanup for package tests.
+ */
+export const ServerTests = Object.freeze({
+    // prettier-ignore
+    /**
+     * Resets shared server facilities before the next test creates a server.
+     */
+    resetEnvironment() {
+        return ServerEnvironmentLifecycle.resetForTest();
+    },
+});
+/**
+ * Resets shared server facilities before the next test creates a server.
+ */
+const serverTestReset = ServerTests.resetEnvironment;
+export { serverTestReset as resetServerEnvironmentForTest };
+/**
+ * Posts a locally constructed Event through the bounded context's external intake path.
+ *
+ * @param context Receives the external Event.
+ * @param event Event envelope whose external origin is preserved.
+ * @returns Completion after external dispatch admission.
+ */
+export function postExternalEvent(context, event) {
+    return boundedContextAccess.postExternalEvent(context, event);
+}
+/**
+ * Observes produced signals admitted by one bounded context.
+ *
+ * @param context Produces the observed signals.
+ * @param observer Receives cloned admitted Command and Event envelopes.
+ * @returns A handle that stops observation.
+ */
+export function observeProducedSignals(context, observer) {
+    return boundedContextAccess.observeProducedSignals(context, observer);
+}
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAuB,MAAM,+BAA+B,CAAC;AAG1F,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,qCAAqC,CAAC;AAE7C;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAuD,MAAM,CAAC,MAAM,CAAC;IAC3F,kBAAkB;IAElB;;OAEG;IACH,gBAAgB;QACd,OAAO,0BAA0B,CAAC,YAAY,EAAE,CAAC;IACnD,CAAC;CACF,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,eAAe,GAAwB,WAAW,CAAC,gBAAgB,CAAC;AAE1E,OAAO,EAAE,eAAe,IAAI,6BAA6B,EAAE,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAuB,EAAE,KAAY;IACrE,OAAO,oBAAoB,CAAC,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAuB,EACvB,QAGC;IAED,OAAO,oBAAoB,CAAC,sBAAsB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;AACxE,CAAC"}