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

package/dist/index.js

@@ -0,0 +1,157 @@
+/*
+ * 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.
+ */
+/* eslint-disable @typescript-eslint/no-unnecessary-condition, @typescript-eslint/require-await */
+import { ApplicationNode } from "./discovery/application-node.js";
+import { scheduledDiscoveryLog } from "./discovery/scheduled-discovery-log.js";
+export { ApplicationNode } from "./discovery/application-node.js";
+export { LeasedNodeRegistry, } from "./registry/leased-node-registry.js";
+const systemNodeScheduler = {
+    schedule(delayMs, onTick) {
+        const timer = setTimeout(onTick, delayMs);
+        timer.unref();
+        return () => {
+            clearTimeout(timer);
+        };
+    },
+};
+/**
+ * Publishes complete snapshots on an injected, cancellable schedule.
+ */
+export class ScheduledNodeDiscovery {
+    #reader;
+    #scheduler;
+    #intervalMs;
+    #logger;
+    #cancel;
+    #controller;
+    #watcher;
+    #refreshing;
+    #closed = false;
+    /**
+     * Creates a scheduled source with a ten-second default refresh interval.
+     *
+     * @param options Supplies the snapshot reader, optional scheduler, and interval.
+     */
+    constructor(options) {
+        if (options.intervalMs !== undefined &&
+            (!Number.isSafeInteger(options.intervalMs) || options.intervalMs < 1))
+            throw new RangeError("Node refresh interval must be a positive safe integer.");
+        this.#reader = options.reader;
+        this.#scheduler = options.scheduler ?? systemNodeScheduler;
+        this.#intervalMs = options.intervalMs ?? 10_000;
+        this.#logger = options.logger;
+    }
+    /**
+     * Starts the only scheduled complete-snapshot watch.
+     *
+     * A second active watch or a watch after `close()` is rejected.
+     *
+     * @param onSnapshot Receives each successful complete snapshot.
+     * @returns Stops scheduling and cancels an in-flight read.
+     */
+    watch(onSnapshot) {
+        if (this.#closed)
+            throw new Error("Node discovery is closed.");
+        if (this.#watcher !== undefined)
+            throw new Error("Node discovery supports one active watch.");
+        this.#watcher = onSnapshot;
+        this.#schedule(0);
+        return () => this.close();
+    }
+    /**
+     * Stops scheduled refresh work permanently.
+     *
+     * This operation is idempotent, cancels scheduling, and joins the active
+     * snapshot read after requesting its cancellation.
+     *
+     * @returns Completes after the active read settles.
+     */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#cancel?.();
+        this.#controller?.abort();
+        this.#watcher = undefined;
+        await this.#refreshing;
+    }
+    #schedule(delayMs) {
+        this.#cancel = this.#scheduler.schedule(delayMs, () => {
+            // spine-log-boundary: deployment.scheduled_discovery_refresh_tail
+            this.#refreshing = this.#refresh().catch(() => undefined);
+        });
+    }
+    async #refresh() {
+        if (this.#closed)
+            return;
+        const controller = new AbortController();
+        this.#controller = controller;
+        try {
+            const nodes = await this.#reader.read(controller.signal);
+            if (!this.#closed)
+                this.#watcher?.([...nodes]);
+        }
+        catch {
+            if (this.#closed || controller.signal.aborted)
+                return;
+            // spine-log-boundary: deployment.scheduled_discovery_refresh
+            scheduledDiscoveryLog.warn(this.#logger);
+            // Retain the last successful snapshot and retry at the configured interval.
+        }
+        finally {
+            this.#controller = undefined;
+            if (!this.#closed)
+                this.#schedule(this.#intervalMs);
+        }
+    }
+}
+/**
+ * Publishes mutable static membership for local and combined deployments.
+ */
+export class StaticNodeDiscovery {
+    #nodes;
+    #watchers = new Set();
+    /**
+     * Creates a source with an initial complete static node set.
+     *
+     * @param nodes Supplies the initial complete static node set.
+     */
+    constructor(nodes) {
+        this.#nodes = [...nodes];
+    }
+    /**
+     * Publishes a replacement complete node set.
+     *
+     * @param nodes Supplies replacement membership.
+     */
+    replace(nodes) {
+        this.#nodes = [...nodes];
+        for (const onSnapshot of this.#watchers)
+            onSnapshot([...this.#nodes]);
+    }
+    /**
+     * Starts delivery of current and subsequent complete snapshots.
+     *
+     * @param onSnapshot Receives the current and subsequent complete snapshots.
+     * @returns An operation that removes this snapshot receiver.
+     */
+    watch(onSnapshot) {
+        this.#watchers.add(onSnapshot);
+        onSnapshot([...this.#nodes]);
+        return async () => {
+            this.#watchers.delete(onSnapshot);
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/internal/backend-membership-kernel.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Performs backend operations for one member managed by the internal kernel.
+ */
+export interface BackendMemberClient<Request, Child, Update> {
+    /**
+     * Returns one unary response from the member.
+     *
+     * @param request Supplies the request to forward.
+     * @returns The backend response bytes.
+     */
+    forward(request: Request): Promise<Uint8Array>;
+    /**
+     * Creates the member's child subscription for one logical definition.
+     *
+     * @param definition Supplies the member-specific subscription definition.
+     * @param signal Cancels child creation.
+     * @returns The created child subscription.
+     */
+    subscribe(definition: Uint8Array, signal: AbortSignal): Promise<Child>;
+    /**
+     * Delivers updates from an active child subscription.
+     *
+     * @param child Supplies the child subscription to activate.
+     * @param updates Receives relayed child updates.
+     * @param signal Cancels update relay.
+     * @returns Completion of the child activation.
+     */
+    activate(child: Child, updates: (update: Update) => Promise<void>, signal: AbortSignal): Promise<void>;
+    /**
+     * Removes one child subscription.
+     *
+     * @param child Supplies the child to dispose.
+     * @param signal Cancels disposal when supported.
+     * @returns Completion of disposal.
+     */
+    dispose(child: Child, signal: AbortSignal): Promise<void>;
+    /**
+     * Closes this member connection.
+     *
+     * @returns Completion of member cleanup.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Configures the provider-neutral internal member owner.
+ */
+export interface BackendMembershipKernelOptions<Member, Request, Child, Update> {
+    /**
+     * Connects to one discovered member.
+     *
+     * @param member Supplies the discovered member.
+     * @param signal Cancels connection creation.
+     * @returns The connected member client.
+     */
+    readonly create: (member: Member, signal: AbortSignal) => Promise<BackendMemberClient<Request, Child, Update>>;
+    /**
+     * Returns the stable identity of a discovered member.
+     *
+     * @param member Supplies the member to identify.
+     * @returns The stable member identity.
+     */
+    readonly memberKey: (member: Member) => string;
+    /**
+     * Returns whether two snapshots describe the same member endpoint.
+     *
+     * @param left Supplies one member snapshot.
+     * @param right Supplies the other member snapshot.
+     * @returns Whether both snapshots represent the same endpoint.
+     */
+    readonly sameMember: (left: Member, right: Member) => boolean;
+    /**
+     * Returns the logical identity from one retained definition.
+     *
+     * @param definition Supplies the logical subscription definition.
+     * @returns Its logical identity, when available.
+     */
+    readonly definitionKey: (definition: Uint8Array) => string | undefined;
+    /**
+     * Returns a logical definition rewritten for a specific child member.
+     *
+     * @param definition Supplies the logical subscription definition.
+     * @param member Supplies the child member.
+     * @returns The rewritten child definition.
+     */
+    readonly childDefinition: (definition: Uint8Array, member: Member) => Uint8Array;
+    /**
+     * Returns a created child subscription envelope size in bytes.
+     *
+     * @param child Supplies the child subscription.
+     * @returns The child envelope byte size.
+     */
+    readonly childSize: (child: Child) => number;
+    /**
+     * Limits parallel member and child creation when supplied.
+     */
+    readonly maxConcurrentStarts?: number;
+    /**
+     * Rejects child subscription envelopes above this size when supplied.
+     */
+    readonly maxChildBytes?: number;
+}
+/**
+ * Manages ephemeral backend membership and its native subscription children.
+ * Logical-definition persistence intentionally remains with callers.
+ */
+export declare class BackendMembershipKernel<Member, Request, Child, Update> {
+    #private;
+    /**
+     * Creates a kernel with bounded member and child creation.
+     *
+     * @param options Configures member creation and child subscription handling.
+     */
+    constructor(options: BackendMembershipKernelOptions<Member, Request, Child, Update>);
+    /**
+     * Updates the live member set from a complete discovery snapshot.
+     *
+     * @param members Supplies the complete member snapshot.
+     * @returns Completion of member reconciliation.
+     */
+    reconcile(members: readonly Member[]): Promise<void>;
+    /**
+     * Creates children for one retained logical subscription definition.
+     *
+     * @param definition Supplies the logical subscription definition.
+     * @param signal Cancels subscription creation.
+     * @param maxChildBytes Limits each child envelope size.
+     * @returns Completion of child creation.
+     */
+    subscribe(definition: Uint8Array, signal: AbortSignal, maxChildBytes?: number): Promise<void>;
+    /**
+     * Updates live children for one previously retained logical definition.
+     *
+     * @param definition Supplies the retained logical definition.
+     * @param maxChildBytes Limits each child envelope size.
+     * @returns Completion of child recreation.
+     */
+    rehydrate(definition: Uint8Array, maxChildBytes?: number): Promise<void>;
+    /**
+     * Creates update relay for a retained logical definition until cancellation.
+     *
+     * @param definition Supplies the retained logical definition.
+     * @param updates Receives relayed child updates.
+     * @param signal Cancels update relay.
+     * @returns Completion after cancellation.
+     */
+    activate(definition: Uint8Array, updates: (update: Update) => Promise<void>, signal: AbortSignal): Promise<void>;
+    /**
+     * Clears one logical definition and its live child subscriptions.
+     *
+     * @param definition Supplies the logical definition to remove.
+     * @param signal Cancels child cleanup when supported.
+     * @returns Completion of child cleanup.
+     */
+    cancel(definition: Uint8Array, signal: AbortSignal): Promise<void>;
+    /**
+     * Returns a unary response from the next available member.
+     *
+     * @param request Supplies the request to forward.
+     * @returns The backend response bytes.
+     */
+    forward(request: Request): Promise<Uint8Array>;
+    /**
+     * Clears live work and closes every member connection.
+     *
+     * @returns Completion of member cleanup.
+     */
+    close(): Promise<void>;
+    /**
+     * Resolves when an abort signal is observed.
+     *
+     * @param signal Supplies the signal to observe.
+     * @returns Completion after the signal aborts.
+     */
+    static waitForAbort(signal: AbortSignal): Promise<void>;
+}
+//# sourceMappingURL=backend-membership-kernel.d.ts.map

package/dist/internal/backend-membership-kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-membership-kernel.d.ts","sourceRoot":"","sources":["../../src/internal/backend-membership-kernel.ts"],"names":[],"mappings":"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"}