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

package/dist/registrar/gce-registrar.js

@@ -0,0 +1,167 @@
+/*
+ * 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 {} from "@spine-event-engine/deployment";
+import { randomUUID } from "node:crypto";
+import { GceMetadataService } from "../metadata/gce-metadata-service.js";
+import { gceRegistrarLog } from "./gce-registrar-log.js";
+import { GceApplicationNode } from "../node/application-node.js";
+import { GceOperationRunner, systemGceDeadlines, systemGceScheduler, } from "./operations.js";
+/**
+ * Registers one ready GCE node and renews its lease.
+ */
+export class GceRegistrar {
+    #registry;
+    #node;
+    #metadata;
+    #port;
+    #identity;
+    #scheduler;
+    #now;
+    #deadlines;
+    #operationTimeoutMs;
+    #operations;
+    #logger;
+    #cancel;
+    #closed = false;
+    #started = false;
+    #confirmed = false;
+    #work = Promise.resolve();
+    #abort = new AbortController();
+    /**
+     * Creates a registrar with twenty-second renewal and sixty-second leases by default.
+     *
+     * @param options Supplies registry ownership, node derivation, and deterministic seams.
+     */
+    constructor(options) {
+        this.#registry = options.registry;
+        if (options.node === undefined && options.port === undefined)
+            throw new Error("GCE registrar requires a node or a metadata port.");
+        this.#node = options.node;
+        this.#metadata =
+            options.metadata ?? (options.node === undefined ? new GceMetadataService() : undefined);
+        this.#port = options.port;
+        this.#identity = options.identity ?? randomUUID();
+        this.#scheduler = options.scheduler ?? systemGceScheduler;
+        this.#now = options.now ?? Date.now;
+        this.#deadlines = options.deadlines ?? systemGceDeadlines;
+        if (options.operationTimeoutMs !== undefined &&
+            (!Number.isSafeInteger(options.operationTimeoutMs) || options.operationTimeoutMs < 1))
+            throw new RangeError("GCE registrar operation timeout must be a positive safe integer.");
+        this.#operationTimeoutMs = options.operationTimeoutMs ?? 20_000;
+        this.#operations = new GceOperationRunner(this.#deadlines, this.#operationTimeoutMs, this.#abort.signal);
+        this.#logger = options.logger;
+    }
+    /**
+     * Starts initial registration after the listener is ready.
+     *
+     * @returns Completes after the first registration attempt has settled.
+     * @throws Error When this registrar has already closed.
+     */
+    async start() {
+        if (this.#closed)
+            throw new Error("GCE registrar is closed.");
+        if (this.#started)
+            return;
+        this.#started = true;
+        // spine-log-boundary: deployment_gce.registrar_initial_result
+        const registered = await this.#enqueue(async () => {
+            await this.#resolveNode();
+            const node = this.#node;
+            if (node === undefined)
+                throw new Error("GCE registrar has no resolved node.");
+            return this.#operation((signal) => this.#registry.register({ node, registrationId: this.#identity, expiresAt: this.#now() + 60_000 }, signal));
+        }).catch(() => false);
+        this.#schedule();
+        this.#confirmed = registered;
+    }
+    /**
+     * Removes this registrar's lease after fencing scheduled work.
+     *
+     * @returns Completes after admitted work settles and owned-row removal is attempted.
+     */
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#abort.abort();
+        this.#cancel?.();
+        await this.#work;
+        const node = this.#node;
+        if (node !== undefined)
+            await this.#operation((signal) => this.#registry.remove(node.id, this.#identity, signal), false);
+    }
+    /**
+     * Exposes listener-ready start and pre-network-close removal to a server assembly.
+     *
+     * @returns The lifecycle callbacks accepted by `Server.addListenerLifecycle()`.
+     */
+    lifecycle() {
+        return { start: () => this.start(), close: () => this.close() };
+    }
+    #schedule() {
+        if (this.#closed)
+            return;
+        this.#cancel = this.#scheduler.schedule(20_000, () => {
+            // spine-log-boundary: deployment_gce.registrar_renew
+            void this.#enqueue(() => this.#renew()).catch(() => {
+                if (!this.#closed)
+                    gceRegistrarLog.warnRenewal(this.#logger);
+            });
+        });
+    }
+    async #renew() {
+        if (this.#closed)
+            return;
+        try {
+            await this.#resolveNode();
+            const node = this.#node;
+            if (node === undefined)
+                return;
+            if (this.#confirmed)
+                this.#confirmed = await this.#operation((signal) => this.#registry.renew(node.id, this.#identity, this.#now() + 60_000, signal));
+            else {
+                const existing = await this.#operation((signal) => this.#registry.lookup(node.id, this.#now(), signal));
+                this.#confirmed = existing?.registrationId === this.#identity;
+                if (!this.#confirmed)
+                    this.#confirmed = await this.#operation((signal) => this.#registry.register({ node, registrationId: this.#identity, expiresAt: this.#now() + 60_000 }, signal));
+            }
+            await this.#operation((signal) => this.#registry.cleanup(this.#now(), signal));
+        }
+        finally {
+            // A concurrent close may fence renewal while its registry operation is pending.
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (!this.#closed)
+                this.#schedule();
+        }
+    }
+    #enqueue(operation) {
+        const next = this.#work.then(operation, operation);
+        // spine-log-boundary: deployment_gce.registrar_work_tail
+        this.#work = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    #operation(operation, includeShutdown = true) {
+        return this.#operations.run(operation, includeShutdown);
+    }
+    async #resolveNode() {
+        if (this.#node !== undefined)
+            return;
+        const metadata = this.#metadata;
+        const port = this.#port;
+        if (metadata === undefined || port === undefined)
+            throw new Error("GCE registrar has no node source.");
+        this.#node = GceApplicationNode.create(await this.#operations.run((signal) => metadata.read(signal)), { port });
+    }
+}
+//# sourceMappingURL=gce-registrar.js.map

package/dist/registrar/gce-registrar.js.map

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

package/dist/registrar/operations.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Schedules deterministic registrar renewal work.
+ */
+export interface GceScheduler {
+    /**
+     * Schedules one renewal callback.
+     *
+     * @param delayMs Supplies a positive delay in milliseconds.
+     * @param onTick Receives the callback to run once after the delay.
+     * @returns Cancels the scheduled callback.
+     */
+    schedule(delayMs: number, onTick: () => void): () => void;
+}
+/**
+ * Creates one cancellable deadline for cooperative registrar operations.
+ */
+export interface GceDeadlineFactory {
+    /**
+     * Creates an operation deadline.
+     *
+     * @param timeoutMs Supplies a positive timeout in milliseconds.
+     * @returns An abort signal and an operation that releases the deadline handle.
+     */
+    create(timeoutMs: number): {
+        readonly signal: AbortSignal;
+        close(): void;
+    };
+}
+/**
+ * Supplies production renewal scheduling with unreferenced Node.js timer handles.
+ */
+export declare const systemGceScheduler: GceScheduler;
+/**
+ * Supplies production deadlines with unreferenced Node.js timer handles.
+ */
+export declare const systemGceDeadlines: GceDeadlineFactory;
+/**
+ * Runs registrar work under its deadline and optional shutdown signal.
+ */
+export declare class GceOperationRunner {
+    private readonly deadlines;
+    private readonly timeoutMs;
+    private readonly shutdown;
+    /**
+     * Creates an operation owner for one registrar lifecycle.
+     *
+     * @param deadlines Supplies the deadline factory.
+     * @param timeoutMs Supplies the operation timeout.
+     * @param shutdown Supplies the registrar shutdown signal.
+     */
+    constructor(deadlines: GceDeadlineFactory, timeoutMs: number, shutdown: AbortSignal);
+    /**
+     * Executes one registrar mutation and always releases its deadline handle.
+     *
+     * @param operation Receives the composed cancellation signal.
+     * @param includeShutdown Selects whether registrar shutdown cancels this operation.
+     * @returns The operation result.
+     */
+    run<Result>(operation: (signal: AbortSignal) => Promise<Result>, includeShutdown?: boolean): Promise<Result>;
+}
+//# sourceMappingURL=operations.d.ts.map

package/dist/registrar/operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/registrar/operations.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,MAAM,WAAW,YAAY;IAG3B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAGjC;;;;;OAKG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;QAAC,KAAK,IAAI,IAAI,CAAA;KAAE,CAAC;CAC5E;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,YAiBhC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,kBAsBhC,CAAC;AAEF;;GAEG;AACH,qBAAa,kBAAkB;IAW3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAV3B;;;;;;OAMG;gBAEgB,SAAS,EAAE,kBAAkB,EAC7B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,WAAW;IAGxC;;;;;;OAMG;IACG,GAAG,CAAC,MAAM,EACd,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,EACnD,eAAe,UAAO,GACrB,OAAO,CAAC,MAAM,CAAC;CAUnB"}

package/dist/registrar/operations.js

@@ -0,0 +1,96 @@
+/*
+ * 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.
+ */
+/**
+ * Supplies production renewal scheduling with unreferenced Node.js timer handles.
+ */
+export const systemGceScheduler = {
+    // prettier-ignore
+    /**
+     * Schedules one unreferenced renewal callback.
+     *
+     * @param delayMs Supplies the renewal delay in milliseconds.
+     * @param onTick Receives the callback to run once after the delay.
+     * @returns Cancels the scheduled callback.
+     */
+    schedule: (delayMs, onTick) => {
+        const timer = setTimeout(onTick, delayMs);
+        timer.unref();
+        return () => {
+            clearTimeout(timer);
+        };
+    },
+};
+/**
+ * Supplies production deadlines with unreferenced Node.js timer handles.
+ */
+export const systemGceDeadlines = {
+    // prettier-ignore
+    /**
+     * Creates one unreferenced operation deadline.
+     *
+     * @param timeoutMs Supplies the deadline duration in milliseconds.
+     * @returns The signal and its deadline-handle closer.
+     */
+    create(timeoutMs) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            controller.abort();
+        }, timeoutMs);
+        timer.unref();
+        return {
+            signal: controller.signal,
+            close: () => {
+                clearTimeout(timer);
+            },
+        };
+    },
+};
+/**
+ * Runs registrar work under its deadline and optional shutdown signal.
+ */
+export class GceOperationRunner {
+    deadlines;
+    timeoutMs;
+    shutdown;
+    // prettier-ignore
+    /**
+     * Creates an operation owner for one registrar lifecycle.
+     *
+     * @param deadlines Supplies the deadline factory.
+     * @param timeoutMs Supplies the operation timeout.
+     * @param shutdown Supplies the registrar shutdown signal.
+     */
+    constructor(deadlines, timeoutMs, shutdown) {
+        this.deadlines = deadlines;
+        this.timeoutMs = timeoutMs;
+        this.shutdown = shutdown;
+    }
+    /**
+     * Executes one registrar mutation and always releases its deadline handle.
+     *
+     * @param operation Receives the composed cancellation signal.
+     * @param includeShutdown Selects whether registrar shutdown cancels this operation.
+     * @returns The operation result.
+     */
+    async run(operation, includeShutdown = true) {
+        const deadline = this.deadlines.create(this.timeoutMs);
+        try {
+            return await operation(includeShutdown ? AbortSignal.any([this.shutdown, deadline.signal]) : deadline.signal);
+        }
+        finally {
+            deadline.close();
+        }
+    }
+}
+//# sourceMappingURL=operations.js.map

package/dist/registrar/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../src/registrar/operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAiCH;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAiB;IAC9C,kBAAkB;IAElB;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC5B,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC1C,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,OAAO,GAAG,EAAE;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CAAC;IACJ,CAAC;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAuB;IACpD,kBAAkB;IAElB;;;;;OAKG;IACH,MAAM,CAAC,SAAS;QACd,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,UAAU,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC,EAAE,SAAS,CAAC,CAAC;QACd,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,OAAO;YACL,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,KAAK,EAAE,GAAG,EAAE;gBACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;SACF,CAAC;IACJ,CAAC;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,OAAO,kBAAkB;IAWV;IACA;IACA;IAZnB,kBAAkB;IAElB;;;;;;OAMG;IACH,YACmB,SAA6B,EAC7B,SAAiB,EACjB,QAAqB;QAFrB,cAAS,GAAT,SAAS,CAAoB;QAC7B,cAAS,GAAT,SAAS,CAAQ;QACjB,aAAQ,GAAR,QAAQ,CAAa;IACrC,CAAC;IAEJ;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,CACP,SAAmD,EACnD,eAAe,GAAG,IAAI;QAEtB,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvD,IAAI,CAAC;YACH,OAAO,MAAM,SAAS,CACpB,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CACtF,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;CACF"}

package/dist/registry/gce-registry-reader.d.ts

@@ -0,0 +1,23 @@
+import { type ApplicationNode, type LeasedNodeRegistry, type NodeSnapshotReader } from "@spine-event-engine/deployment";
+/**
+ * Reads complete live-node snapshots from the leased registry.
+ */
+export declare class GceRegistryReader implements NodeSnapshotReader {
+    private readonly registry;
+    private readonly now;
+    /**
+     * Creates a reader using an injected clock for deterministic expiry evaluation.
+     *
+     * @param registry Supplies the leased registry to read.
+     * @param now Supplies the current epoch time used for exact expiry filtering; defaults to `Date.now`.
+     */
+    constructor(registry: LeasedNodeRegistry, now?: () => number);
+    /**
+     * Reads every currently live node.
+     *
+     * @param signal Cancels the registry read during discovery close.
+     * @returns The complete live application-node snapshot.
+     */
+    read(signal: AbortSignal): Promise<readonly ApplicationNode[]>;
+}
+//# sourceMappingURL=gce-registry-reader.d.ts.map

package/dist/registry/gce-registry-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gce-registry-reader.d.ts","sourceRoot":"","sources":["../../src/registry/gce-registry-reader.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACxB,MAAM,gCAAgC,CAAC;AAExC;;GAEG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAUxD,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IARtB;;;;;OAKG;gBAEgB,QAAQ,EAAE,kBAAkB,EAC5B,GAAG,GAAE,MAAM,MAAiB;IAG/C;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC;CAG/D"}

package/dist/registry/gce-registry-reader.js

@@ -0,0 +1,42 @@
+/*
+ * 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 {} from "@spine-event-engine/deployment";
+/**
+ * Reads complete live-node snapshots from the leased registry.
+ */
+export class GceRegistryReader {
+    registry;
+    now;
+    // prettier-ignore
+    /**
+     * Creates a reader using an injected clock for deterministic expiry evaluation.
+     *
+     * @param registry Supplies the leased registry to read.
+     * @param now Supplies the current epoch time used for exact expiry filtering; defaults to `Date.now`.
+     */
+    constructor(registry, now = Date.now) {
+        this.registry = registry;
+        this.now = now;
+    }
+    /**
+     * Reads every currently live node.
+     *
+     * @param signal Cancels the registry read during discovery close.
+     * @returns The complete live application-node snapshot.
+     */
+    read(signal) {
+        return this.registry.read(this.now(), signal);
+    }
+}
+//# sourceMappingURL=gce-registry-reader.js.map

package/dist/registry/gce-registry-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gce-registry-reader.js","sourceRoot":"","sources":["../../src/registry/gce-registry-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAIN,MAAM,gCAAgC,CAAC;AAExC;;GAEG;AACH,MAAM,OAAO,iBAAiB;IAUT;IACA;IAVnB,kBAAkB;IAElB;;;;;OAKG;IACH,YACmB,QAA4B,EAC5B,MAAoB,IAAI,CAAC,GAAG;QAD5B,aAAQ,GAAR,QAAQ,CAAoB;QAC5B,QAAG,GAAH,GAAG,CAAyB;IAC5C,CAAC;IAEJ;;;;;OAKG;IACH,IAAI,CAAC,MAAmB;QACtB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC;CACF"}