@zlink-systems/framework 0.26.0 → 0.27.0

package/dist/runtime/locations/relocation-blob.js

@@ -3,15 +3,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.relocationBlobReference = relocationBlobReference;
 exports.putNewRelocationBlob = putNewRelocationBlob;
 const node_crypto_1 = require("node:crypto");
-const MAX_REFERENCE_GENERATION_ATTEMPTS = 4;
+const abort_1 = require("../abort");
 function relocationBlobReference(value) {
     return { value };
 }
 async function putNewRelocationBlob(store, payload, retentionMs, signal) {
-    for (let attempt = 0; attempt < MAX_REFERENCE_GENERATION_ATTEMPTS; attempt += 1) {
+    let reference = relocationBlobReference((0, node_crypto_1.randomUUID)());
+    for (;; await (0, abort_1.macrotaskBoundary)()) {
         signal?.throwIfAborted();
-        const reference = relocationBlobReference((0, node_crypto_1.randomUUID)());
-        const result = await store.put(reference, payload, retentionMs, signal);
+        let result;
+        try {
+            result = await (0, abort_1.awaitWithAbort)(store.put(reference, payload, retentionMs, signal), signal);
+        }
+        catch {
+            signal?.throwIfAborted();
+            const read = await (0, abort_1.awaitWithAbort)(store.read(reference, signal), signal);
+            if (read.kind === 'found' && Buffer.compare(read.bytes, payload) === 0) {
+                return { reference, expiresAt: read.expiresAt, storeNow: read.storeNow };
+            }
+            if (read.kind === 'missing')
+                continue;
+            result = { kind: 'conflict', storeNow: read.storeNow };
+        }
         if (result.kind !== 'conflict') {
             return {
                 reference,
@@ -19,6 +32,6 @@ async function putNewRelocationBlob(store, payload, retentionMs, signal) {
                 storeNow: result.storeNow
             };
         }
+        reference = relocationBlobReference((0, node_crypto_1.randomUUID)());
     }
-    throw new Error('Unable to allocate a unique Relocation Store reference.');
 }

package/dist/runtime/locations/resolvers.d.ts

@@ -1,9 +1,8 @@
 import type { ActorRef, RoutingId, SpotId } from '../../contracts/Common';
-import { ZLinkLocationRole, ZLinkFrameworkRuntimeState, type ZLinkLocationReadiness, type ZLinkLocationRuntimeQuery, type ZLinkPeerLocationResolver, type ZLinkActorLocation, type ZLinkActorLocationKey, type ZLinkPeerLocation, type ZLinkPeerLocationFilter, type ZLinkRouteLocation, type ZLinkRouteLocationKey, type ZLinkSpotLocation, type ZLinkSpotLocationKey } from './internal-location-contracts';
-import type { ZLinkActorLocationStore, ZLinkAuthorityStore, ZLinkMeshNodeLocationStore, ZLinkPeerLocationStore, ZLinkRouteLocationStore, ZLinkSpotLocationStore } from './internal-store-contracts';
-import type { SpotHandle, ZLinkActorSpotHandleResolver, ZLinkSpotHandleResolver } from '../spots/spot-handle';
+import { type SpotHandle, type ZLinkActorSpotHandleResolver, type ZLinkSpotHandleResolver, type ResolvedSpotHandle } from '../spots/spot-handle';
 import type { ZLinkSpotRouteResolver, ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
-import { type ResolvedSpotHandle } from '../spots/spot-handle';
+import { ZLinkFrameworkRuntimeState, ZLinkLocationRole, type ZLinkActorLocation, type ZLinkActorLocationKey, type ZLinkLocationReadiness, type ZLinkLocationRuntimeQuery, type ZLinkPeerLocation, type ZLinkPeerLocationFilter, type ZLinkPeerLocationResolver, type ZLinkRouteLocation, type ZLinkRouteLocationKey, type ZLinkSpotLocation, type ZLinkSpotLocationKey } from './internal-location-contracts';
+import type { ZLinkActorLocationStore, ZLinkAuthorityStore, ZLinkMeshNodeLocationStore, ZLinkPeerLocationStore, ZLinkRouteLocationStore, ZLinkSpotLocationStore } from './internal-store-contracts';
 import { ZLinkOwnerLeaseTracker } from './lease-tracker';
 export interface ZLinkStoreLocationResolverStores {
     readonly authorityStore: ZLinkAuthorityStore;
@@ -92,7 +91,8 @@ export declare class ZLinkStoreLocationResolvers implements ZLinkPeerLocationRes
     resolveSpotHandle(meshName: string, spotId: RoutingId, signal?: AbortSignal): Promise<SpotHandle | undefined>;
     resolveActorSpotRef(meshName: string, actorId: string, signal?: AbortSignal): Promise<ResolvedSpotHandle | undefined>;
     resolveActorRef(actorId: string, signal?: AbortSignal): Promise<ActorRef | undefined>;
-    resolveDirectActorRoute(actorId: string, signal?: AbortSignal): Promise<ZLinkDirectActorRouteResolution>;
+    resolveDirectActorRoute(actorId: string, signal?: AbortSignal, deadlineMs?: number): Promise<ZLinkDirectActorRouteResolution>;
+    private resolveUncachedDirectActorRoute;
     private cacheDirectActorRoute;
     observeActorAuthorityVersion(actorId: string, storeVersion: string): void;
     resolveActorSpotHandle(meshName: string, actorId: string, signal?: AbortSignal): Promise<SpotHandle | undefined>;

package/dist/runtime/locations/resolvers.js

@@ -1,20 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkAuthoritySpotRouteResolver = exports.ZLinkLocationSpotRouteResolver = exports.DefaultZLinkLocationReadiness = exports.ZLinkStoreLocationResolvers = void 0;
-const framework_errors_internal_1 = require("../framework-errors-internal");
-const internal_location_contracts_1 = require("./internal-location-contracts");
+const location_store_pages_1 = require("./location-store-pages");
+const Errors_1 = require("../../contracts/Errors");
+const Options_1 = require("../../contracts/Locations/Options");
+const Spots_1 = require("../../contracts/Spots");
+const actor_authority_publication_1 = require("../actors/actor-authority-publication");
+const actor_request_deadline_1 = require("../actors/actor-request-deadline");
+const diagnostics_1 = require("../diagnostics");
+const state_lane_1 = require("../execution/state-lane");
 const service_authority_payload_codec_1 = require("../foundation/service-authority-payload-codec");
 const service_relocation_runtime_1 = require("../foundation/service-relocation-runtime");
-const actor_authority_publication_1 = require("../actors/actor-authority-publication");
-const authority_key_codec_1 = require("./authority-key-codec");
-const Spots_1 = require("../../contracts/Spots");
-const Errors_1 = require("../../contracts/Errors");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const routing_id_1 = require("../routing-id");
 const spot_handle_1 = require("../spots/spot-handle");
+const authority_key_codec_1 = require("./authority-key-codec");
 const canonical_codec_1 = require("./canonical-codec");
+const internal_location_contracts_1 = require("./internal-location-contracts");
 const lease_tracker_1 = require("./lease-tracker");
-const routing_id_1 = require("../routing-id");
-const state_lane_1 = require("../execution/state-lane");
-const diagnostics_1 = require("../diagnostics");
 /**
  * Authority payloads are writer-private.  The active outer row is the
  * cross-language route contract when a foreign writer's payload cannot be
@@ -61,18 +64,18 @@ class ZLinkStoreLocationResolvers {
     nextActorPlacement = 0n;
     constructor(options) {
         this.options = options;
-        this.liveRows = new lease_tracker_1.ZLinkLiveRowFilter(options.leaseTracker);
+        this.liveRows = new lease_tracker_1.ZLinkLiveRowFilter();
         this.monotonicNowMs = options.monotonicNowMs ?? (() => performance.now());
         this.authoritySpotResolver = new ZLinkAuthoritySpotRouteResolver(options.stores.authorityStore, (meshName) => meshName, undefined, options.leaseTracker, options.routeCacheMaxAgeMs, this.monotonicNowMs);
     }
     async listLivePeers(filter, signal) {
         const rows = await this.options.stores.peerStore.listPeers(filter, signal);
-        return await this.liveRows.filter(rows, (row) => row.ownerId, signal, (row) => (0, canonical_codec_1.isKnownZLinkLocationAutoConnectType)(row.autoConnectType) &&
+        return await this.liveRows.filter(rows, (row, signal) => this.options.leaseTracker.isOwnerLive(row.ownerId, signal), signal, (row) => (0, canonical_codec_1.isKnownZLinkLocationAutoConnectType)(row.autoConnectType) &&
             (0, canonical_codec_1.isKnownZLinkLocationRole)(row.role));
     }
     async resolveEntrySpotNode(spotId, meshNames, signal) {
         for (const meshName of meshNames) {
-            const descriptors = await this.liveRows.filter((await this.options.stores.locationStore.listMeshNodes(meshName, undefined, signal)).items, (descriptor) => descriptor.ownerId, signal);
+            const descriptors = await this.liveRows.filter(await (0, location_store_pages_1.listAllMeshNodeDescriptors)(this.options.stores.locationStore, meshName, signal), (descriptor, signal) => this.options.leaseTracker.isOwnerTokenLive(descriptor, signal), signal);
             const descriptor = descriptors.find((candidate) => candidate.entrySpotId === spotId &&
                 candidate.objectRole === internal_location_contracts_1.ZLinkObjectRole.Server &&
                 // An Entry Spot accepts new joins only while its owning node is Serving.
@@ -93,8 +96,8 @@ class ZLinkStoreLocationResolvers {
         return undefined;
     }
     async selectActorPlacement(meshName, actorType, excludedNodeRid, signal, excludedCandidateRids = new Set()) {
-        const descriptors = (await this.options.stores.locationStore.listMeshNodes(meshName, undefined, signal)).items;
-        const liveDescriptors = await this.liveRows.filter(descriptors, (descriptor) => descriptor.ownerId, signal);
+        const descriptors = await (0, location_store_pages_1.listAllMeshNodeDescriptors)(this.options.stores.locationStore, meshName, signal);
+        const liveDescriptors = await this.liveRows.filter(descriptors, (descriptor, signal) => this.options.leaseTracker.isOwnerTokenLive(descriptor, signal), signal);
         const candidates = liveDescriptors.filter((descriptor) => {
             const capacity = descriptor.populationCapacity.actors;
             return (descriptor.state === internal_location_contracts_1.ZLinkFrameworkRuntimeState.Serving &&
@@ -118,7 +121,7 @@ class ZLinkStoreLocationResolvers {
         return candidates[candidates.length - 1]?.rid;
     }
     async resolveRoute(key, signal) {
-        const row = await this.liveRows.resolve(await this.options.stores.routeStore.resolveRoute(key, signal), (candidate) => candidate.ownerId, signal);
+        const row = await this.liveRows.resolve(await this.options.stores.routeStore.resolveRoute(key, signal), (candidate, signal) => this.options.leaseTracker.isOwnerLive(candidate.ownerId, signal), signal);
         if (row === undefined) {
             this.options.events?.routeResolveMiss(key);
             return undefined;
@@ -192,10 +195,13 @@ class ZLinkStoreLocationResolvers {
         }
         return (await this.resolveActorRow({ meshName: '', actorId }, signal))?.actorRef;
     }
-    async resolveDirectActorRoute(actorId, signal) {
+    async resolveDirectActorRoute(actorId, signal, deadlineMs) {
         const cached = await this.lane.run(() => this.getCachedCore(this.directActorRoutes, actorId));
         if (cached !== undefined)
             return { kind: 'ready', route: cached };
+        return await (0, actor_request_deadline_1.waitActorReply)(this.resolveUncachedDirectActorRoute(actorId, signal), actorId, deadlineMs, signal);
+    }
+    async resolveUncachedDirectActorRoute(actorId, signal) {
         const current = await this.options.stores.authorityStore.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)('actor', actorId), signal);
         if (current.kind !== 'snapshot' || current.allocation.state !== 'active') {
             return { kind: 'missing' };
@@ -212,12 +218,14 @@ class ZLinkStoreLocationResolvers {
                 authorityGeneration: current.authorityOwnerGeneration,
                 remainingLeaseMs
             };
-            (0, diagnostics_1.emitActorOwnerLeaseObservation)({
-                actorId,
-                authorityGeneration: unavailable.authorityGeneration,
-                remainingLeaseMs,
-                decision: 'owner_unavailable'
-            });
+            if ((0, diagnostics_1.isRelocationDebugEnabled)()) {
+                (0, diagnostics_1.emitActorOwnerLeaseObservation)({
+                    actorId,
+                    authorityGeneration: unavailable.authorityGeneration,
+                    remainingLeaseMs,
+                    decision: 'owner_unavailable'
+                });
+            }
             return unavailable;
         }
         if (decoded === undefined ||
@@ -264,7 +272,7 @@ class ZLinkStoreLocationResolvers {
         return await this.lane.run(() => {
             if (route === undefined)
                 return undefined;
-            const maxAgeMs = this.options.routeCacheMaxAgeMs ?? 15000;
+            const maxAgeMs = this.options.routeCacheMaxAgeMs ?? Options_1.zlinkDefaultLocationOptions.routeCacheMaxAgeMs;
             if (maxAgeMs > 0) {
                 this.directActorRoutes.set(actorId, {
                     row: route,
@@ -292,7 +300,7 @@ class ZLinkStoreLocationResolvers {
         const cached = await this.lane.run(() => this.getCachedCore(this.spotRoutes, cacheKey));
         if (cached !== undefined)
             return cached;
-        const row = await this.liveRows.resolve(await this.options.stores.spotStore.resolveSpot(key, signal), (candidate) => candidate.ownerId, signal);
+        const row = await this.liveRows.resolve(await this.options.stores.spotStore.resolveSpot(key, signal), (candidate, signal) => this.options.leaseTracker.isOwnerTokenLive(candidate, signal), signal);
         if (row === undefined) {
             this.options.events?.spotResolveMiss(key);
             return undefined;
@@ -313,7 +321,7 @@ class ZLinkStoreLocationResolvers {
         return undefined;
     }
     async resolveMeshNodeState(meshName, nodeRid, expectedLifecycleGeneration, signal) {
-        const descriptor = (await this.options.stores.locationStore.listMeshNodes(meshName, undefined, signal)).items.find((candidate) => (0, routing_id_1.routingIdsEqual)(candidate.rid, nodeRid) &&
+        const descriptor = (await (0, location_store_pages_1.listAllMeshNodeDescriptors)(this.options.stores.locationStore, meshName, signal)).find((candidate) => (0, routing_id_1.routingIdsEqual)(candidate.rid, nodeRid) &&
             (expectedLifecycleGeneration === undefined ||
                 candidate.lifecycleGeneration === expectedLifecycleGeneration));
         return descriptor?.state;
@@ -333,7 +341,7 @@ class ZLinkStoreLocationResolvers {
             if (stored !== undefined)
                 break;
         }
-        const row = await this.liveRows.resolve(stored, (candidate) => candidate.ownerId, signal, (candidate) => candidate.actorRef.objectGeneration > 0n &&
+        const row = await this.liveRows.resolve(stored, (candidate, signal) => this.options.leaseTracker.isOwnerTokenLive(candidate, signal), signal, (candidate) => candidate.actorRef.objectGeneration > 0n &&
             candidate.ownerNodeGeneration > 0n &&
             candidate.membershipEpoch > 0n);
         if (row === undefined) {
@@ -426,7 +434,7 @@ class ZLinkStoreLocationResolvers {
         return entry.row;
     }
     async cacheReady(cache, key, row, ownerId, ownerLeaseGeneration, signal) {
-        const maxAgeMs = this.options.routeCacheMaxAgeMs ?? 15000;
+        const maxAgeMs = this.options.routeCacheMaxAgeMs ?? Options_1.zlinkDefaultLocationOptions.routeCacheMaxAgeMs;
         const remainingLeaseMs = await this.options.leaseTracker.remainingOwnerTokenLeaseMs({ ownerId, leaseGeneration: ownerLeaseGeneration }, signal);
         if (remainingLeaseMs <= 0)
             return false;
@@ -540,6 +548,7 @@ class ZLinkLocationSpotRouteResolver {
                 targetNodeRid: entrySpot.nodeRid,
                 spotId: entrySpot.spotId,
                 spotKind: Spots_1.ZLinkSpotKind.Entry,
+                targetSpotGeneration: entrySpot.targetNodeGeneration,
                 targetNodeGeneration: entrySpot.targetNodeGeneration,
                 targetOwnerId: entrySpot.targetOwnerId,
                 ownerLeaseGeneration: entrySpot.ownerLeaseGeneration,
@@ -565,7 +574,7 @@ class ZLinkAuthoritySpotRouteResolver {
     cache = new Map();
     routeEpochs = new Map();
     activeResolutions = new Map();
-    constructor(store, routerChannelIdForMesh, fallback, leaseTracker, routeCacheMaxAgeMs = 15000, monotonicNowMs = () => performance.now(), targetNodeStateResolver) {
+    constructor(store, routerChannelIdForMesh, fallback, leaseTracker, routeCacheMaxAgeMs = Options_1.zlinkDefaultLocationOptions.routeCacheMaxAgeMs, monotonicNowMs = () => performance.now(), targetNodeStateResolver) {
         this.store = store;
         this.routerChannelIdForMesh = routerChannelIdForMesh;
         this.fallback = fallback;

package/dist/runtime/locations/runtime.d.ts

@@ -70,6 +70,7 @@ export declare class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     private readonly clearTimer;
     private readonly monotonicNowMs;
     private readonly liveRows;
+    private readonly leaseTracker;
     private readonly ownershipLostHandlers;
     private readonly ownerLeaseRenewedHandlers;
     private readonly ownerLeaseRenewalFailedHandlers;
@@ -103,10 +104,12 @@ export declare class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     removeOwnerLeaseRenewedHandler(handler: (renewal: ZLinkOwnerLeaseRenewed) => void): void;
     addOwnerLeaseRenewalFailedHandler(handler: () => void): void;
     removeOwnerLeaseRenewalFailedHandler(handler: () => void): void;
-    start(nodeRid: RoutingId, signal?: AbortSignal): Promise<void>;
+    start(nodeRid: RoutingId): Promise<void>;
+    start(nodeRid: RoutingId, signal: AbortSignal): Promise<void>;
+    start(nodeRid: RoutingId, signal: AbortSignal, shutdownSignal: () => AbortSignal): Promise<void>;
     stop(signal?: AbortSignal): Promise<void>;
     cleanupOwner(signal?: AbortSignal): Promise<void>;
-    renewOwnerLeaseOnce(signal?: AbortSignal): Promise<boolean>;
+    renewOwnerLeaseOnce(signal?: AbortSignal, shutdownSignal?: () => AbortSignal): Promise<boolean>;
     private claimFreshOwnerLease;
     private claimOwnerLeaseWithConfirmation;
     private confirmOwnerLease;
@@ -138,9 +141,7 @@ export declare class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     private pageRequest;
     listServiceSummaries(filter: ZLinkLocationServiceSummaryFilter, page?: ZLinkPageRequest, signal?: AbortSignal): Promise<ZLinkLocationPage<ZLinkLocationServiceSummary>>;
     private meshNamesOf;
-    private listAllMeshNodeDescriptors;
     private pageInMemory;
-    private filterLive;
     private scheduleHeartbeat;
     private guardWrite;
     private guardStatusWrite;