@zlink-systems/framework 0.10.0 → 0.11.0

package/dist/runtime/backend/runtime-values.d.ts

@@ -45,6 +45,7 @@ export declare class ZLinkBackendResultError extends Error {
 }
 export declare function isZLinkBackendResultError(error: unknown): error is ZLinkBackendResultError;
 export declare function isBackendNotConnectedError(error: unknown): boolean;
+export declare function isBackendRequestTimeoutError(error: unknown): boolean;
 export type ZLinkBackendMessageLike = Message | Buffer | Uint8Array | string;
 export interface ZLinkBackendSendSubmitBuilder {
     message(message: ZLinkBackendMessageLike): ZLinkBackendSendSubmitBuilder;

package/dist/runtime/backend/runtime-values.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkBackendResultError = exports.ZLINK_BACKEND_RECV_DONT_WAIT = exports.ZLINK_BACKEND_SEND_NONE = exports.SubmitResult = exports.RequestResult = void 0;
 exports.isZLinkBackendResultError = isZLinkBackendResultError;
 exports.isBackendNotConnectedError = isBackendNotConnectedError;
+exports.isBackendRequestTimeoutError = isBackendRequestTimeoutError;
 exports.RequestResult = Object.freeze({
     Ok: 0,
     TimedOut: 101,
@@ -64,3 +65,8 @@ function isBackendNotConnectedError(error) {
     const result = error.result;
     return result === exports.SubmitResult.NotConnected || result === exports.RequestResult.NotConnected;
 }
+function isBackendRequestTimeoutError(error) {
+    return isZLinkBackendResultError(error)
+        && error.operation === 'request'
+        && error.result === exports.RequestResult.TimedOut;
+}

package/dist/runtime/channels/channel-socket-registry.js

@@ -15,6 +15,7 @@ const runtime_state_projections_1 = require("../foundation/runtime-state-project
 const service_wire_m6a_codec_1 = require("../foundation/service-wire-m6a-codec");
 const client_server_service_wire_1 = require("./client-server-service-wire");
 const fanout_service_wire_1 = require("./fanout-service-wire");
+const runtime_values_1 = require("../backend/runtime-values");
 const MAX_LIFECYCLE_GENERATION = 0x7fffffffffffffffn;
 const CLIENT_SERVER_PROBE_INTERVAL_MS = 5_000;
 const CLIENT_SERVER_PEER_DEADLINE_MS = 15_000;
@@ -952,6 +953,7 @@ class ZLinkChannelSocketRegistry {
             return;
         const admissionAttempt = Symbol(connectionId);
         connection.admissionAttempt = admissionAttempt;
+        let retryAdmission = false;
         try {
             const admission = await requestClientServerAdmission(connection.dealer, channelName, 'default', 15_000);
             if (this.clientServerConnections.get(connectionId) !== connection
@@ -972,12 +974,21 @@ class ZLinkChannelSocketRegistry {
                 || connection.admissionAttempt !== admissionAttempt)
                 return;
             this.removeReadyConnection(connectionId);
+            if ((0, runtime_values_1.isBackendRequestTimeoutError)(error)) {
+                retryAdmission = true;
+                return;
+            }
             throw error;
         }
         finally {
             if (this.clientServerConnections.get(connectionId) === connection
+                && connection.physicalConnectionId === physicalConnectionId
                 && connection.admissionAttempt === admissionAttempt) {
                 connection.admissionAttempt = undefined;
+                if (retryAdmission) {
+                    void this.admitConfiguredClientServerConnection(channelName, connectionId)
+                        .catch(error => this.oneWayFailureSink?.(error));
+                }
             }
         }
     }

package/dist/runtime/channels/client-server-location-runtime.js

@@ -8,6 +8,7 @@ const runtime_message_1 = require("../backend/runtime-message");
 const client_server_service_wire_1 = require("./client-server-service-wire");
 const runtime_state_projections_1 = require("../foundation/runtime-state-projections");
 const state_lane_1 = require("../execution/state-lane");
+const runtime_values_1 = require("../backend/runtime-values");
 /**
  * Owns the dedicated ClientServer discovery domain. It never converts these
  * descriptors into RouteMesh peer rows.
@@ -260,6 +261,7 @@ class ZLinkClientServerLocationRuntime {
         if (current === undefined) {
             return;
         }
+        let retryAdmission = false;
         try {
             const admission = await requestAdmission(current.dealer, current.target.descriptor, this.options.ownerLeaseRenewTimeoutMs);
             const admittedDescriptor = await this.lane.run(() => {
@@ -294,13 +296,23 @@ class ZLinkClientServerLocationRuntime {
                 current.target.dealer = undefined;
                 await this.sockets.closeClientServerConnection(connectionId);
             }
+            if ((0, runtime_values_1.isBackendRequestTimeoutError)(error)) {
+                retryAdmission = true;
+                return;
+            }
             throw error;
         }
         finally {
-            await this.lane.run(() => {
-                if (this.connections.get(connectionId) === current.target)
-                    current.target.handshakeInFlight = false;
+            const shouldRetry = await this.lane.run(() => {
+                if (this.connections.get(connectionId) !== current.target)
+                    return false;
+                current.target.handshakeInFlight = false;
+                return retryAdmission;
             });
+            if (shouldRetry) {
+                void this.handleTransportReady(connectionId, _routingId, _endpoint)
+                    .catch(error => this.locationRuntime.reportDiscoveryFailure(error));
+            }
         }
     }
     async removeSupersededConnections(admitted) {

package/dist/runtime/locations/location-store-repository.d.ts

@@ -56,6 +56,7 @@ export declare class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationS
     private removeOwnedAuthorities;
     private removeOwnerCleanupBatch;
     private updateDescriptor;
+    private writeDescriptorWithReconciliation;
     private removeDescriptor;
     private listDescriptors;
     private updateOwnedLocation;

package/dist/runtime/locations/location-store-repository.js

@@ -23,6 +23,7 @@ const MAX_CREATION_TERMINAL_BYTES = 1024 * 1024;
 const CREATION_TERMINAL_RETENTION_MS = 5 * 60 * 1000;
 const AGGREGATE_COMMIT_RETRY_WINDOW_MS = 5_000;
 const MAX_AGGREGATE_COMMIT_CONFLICT_RETRIES = 64;
+const MAX_DESCRIPTOR_WRITE_RETRIES = 3;
 const MAX_OWNER_CLEANUP_BATCH_ROWS = 2_047;
 /**
  * Maps framework domain records to the minimal provider SPI.
@@ -1225,62 +1226,7 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
         return result.kind === 'applied' ? 'released' : 'stale';
     }
     async updateMeshNode(descriptor, intent, signal) {
-        const leaseKey = ownerKey(descriptor.ownerId);
-        const rowKey = meshKey(descriptor.meshName, descriptor.rid);
-        const [lease, current] = await Promise.all([
-            this.provider.read(leaseKey, signal),
-            this.provider.read(rowKey, signal)
-        ]);
-        if (lease.kind === 'missing')
-            return rejected(lease.storeNow);
-        if (liveOwnerLeaseGeneration(lease) !== descriptor.leaseGeneration) {
-            return rejected(lease.value.storeNow);
-        }
-        let generation = 1n;
-        let rowCondition = { kind: 'missing', key: rowKey };
-        if (current.kind === 'found') {
-            const record = decodeCanonicalDescriptorRecord(current.value.bytes);
-            const stored = reviveMeshDescriptor(record.descriptor);
-            generation = descriptorStoreGeneration(record, current.value.version.value);
-            if (sameMeshDescriptor(stored, descriptor)) {
-                return { status: Locations_1.ZLinkLocationWriteStatus.Stored, generation, updatedAt: current.value.storeNow };
-            }
-            const currentLease = await this.provider.read(ownerKey(stored.ownerId), signal);
-            const currentLeaseGeneration = liveOwnerLeaseGeneration(currentLease);
-            const takeover = canTakeOverStoredLocation(intent, stored.ownerId, stored.leaseGeneration, descriptor.ownerId, descriptor.leaseGeneration, currentLeaseGeneration);
-            const renew = intent === 2
-                && stored.ownerId === descriptor.ownerId
-                && stored.leaseGeneration === descriptor.leaseGeneration
-                && stored.lifecycleGeneration === descriptor.lifecycleGeneration
-                && descriptor.descriptorRevision > stored.descriptorRevision;
-            if (!takeover && !renew) {
-                return {
-                    status: Locations_1.ZLinkLocationWriteStatus.IgnoredStale,
-                    generation,
-                    updatedAt: current.value.storeNow
-                };
-            }
-            if (takeover)
-                generation += 1n;
-            rowCondition = { kind: 'version', key: rowKey, expected: current.value.version };
-        }
-        else if (intent === 2) {
-            return rejected(lease.value.storeNow);
-        }
-        const result = await this.provider.write({
-            conditions: [
-                { kind: 'version', key: leaseKey, expected: lease.value.version },
-                rowCondition
-            ],
-            mutations: [{
-                    kind: 'put',
-                    key: rowKey,
-                    bytes: encodeCanonicalDescriptorRecord(generation, persistMeshDescriptor(descriptor))
-                }]
-        }, signal);
-        if (result.kind === 'conflict')
-            return rejected(result.storeNow);
-        return { status: Locations_1.ZLinkLocationWriteStatus.Stored, generation, updatedAt: result.storeNow };
+        return this.updateDescriptor(meshKey(descriptor.meshName, descriptor.rid), descriptor, intent, reviveMeshDescriptor, sameMeshDescriptor, canRenewMesh, signal);
     }
     async removeMeshNode(key, owner, signal) {
         const rowKey = meshKey(key.meshName, key.rid);
@@ -1656,11 +1602,10 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
         ]);
         if (lease.kind === 'missing')
             return rejected(lease.storeNow);
-        if (liveOwnerLeaseGeneration(lease) !== descriptor.leaseGeneration) {
+        if (!matchesLiveOwnerLease(lease, descriptor.ownerId, descriptor.leaseGeneration)) {
             return rejected(lease.value.storeNow);
         }
         let generation = 1n;
-        let rowCondition = { kind: 'missing', key: rowKey };
         if (current.kind === 'found') {
             const record = decodeCanonicalDescriptorRecord(current.value.bytes);
             const stored = revive(record.descriptor);
@@ -1681,25 +1626,44 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
             }
             if (takeover)
                 generation += 1n;
-            rowCondition = { kind: 'version', key: rowKey, expected: current.value.version };
         }
         else if (intent === 2) {
             return rejected(lease.value.storeNow);
         }
-        const result = await this.provider.write({
-            conditions: [
-                { kind: 'version', key: leaseKey, expected: lease.value.version },
-                rowCondition
-            ],
-            mutations: [{
-                    kind: 'put',
-                    key: rowKey,
-                    bytes: encodeCanonicalDescriptorRecord(generation, descriptor)
-                }]
-        }, signal);
-        if (result.kind === 'conflict')
-            return rejected(result.storeNow);
-        return { status: Locations_1.ZLinkLocationWriteStatus.Stored, generation, updatedAt: result.storeNow };
+        return this.writeDescriptorWithReconciliation(leaseKey, descriptor.ownerId, descriptor.leaseGeneration, lease, rowKey, current, encodeCanonicalDescriptorRecord(generation, descriptor), generation, signal);
+    }
+    async writeDescriptorWithReconciliation(leaseKey, ownerId, leaseGeneration, liveLease, rowKey, predecessor, encodedDescriptor, generation, signal) {
+        let currentLease = liveLease;
+        let currentRow = predecessor;
+        for (let attempt = 0; attempt <= MAX_DESCRIPTOR_WRITE_RETRIES; attempt += 1) {
+            const rowCondition = currentRow.kind === 'found'
+                ? { kind: 'version', key: rowKey, expected: currentRow.value.version }
+                : { kind: 'missing', key: rowKey };
+            const result = await this.provider.write({
+                conditions: [
+                    { kind: 'version', key: leaseKey, expected: currentLease.value.version },
+                    rowCondition
+                ],
+                mutations: [{ kind: 'put', key: rowKey, bytes: encodedDescriptor }]
+            }, signal);
+            if (result.kind === 'applied') {
+                return { status: Locations_1.ZLinkLocationWriteStatus.Stored, generation, updatedAt: result.storeNow };
+            }
+            if (attempt === MAX_DESCRIPTOR_WRITE_RETRIES)
+                return ignoredStale(result.storeNow);
+            const [refreshedLease, refreshedRow] = await Promise.all([
+                this.provider.read(leaseKey, signal),
+                this.provider.read(rowKey, signal)
+            ]);
+            if (refreshedLease.kind === 'missing'
+                || !matchesLiveOwnerLease(refreshedLease, ownerId, leaseGeneration)
+                || !sameDescriptorPredecessor(predecessor, refreshedRow)) {
+                return ignoredStale(result.storeNow);
+            }
+            currentLease = refreshedLease;
+            currentRow = refreshedRow;
+        }
+        throw new Error('Descriptor write retry loop exhausted unexpectedly.');
     }
     async removeDescriptor(rowKey, owner, revive, signal) {
         const current = await this.provider.read(rowKey, signal);
@@ -2933,10 +2897,24 @@ function sameCreationTarget(snapshot, target) {
         && snapshot.ownerLeaseGeneration === target.owner.leaseGeneration;
 }
 function sameLiveOwner(lease, snapshot) {
-    if (liveOwnerLeaseGeneration(lease) !== snapshot.ownerLeaseGeneration)
+    if (lease.kind === 'missing')
+        return false;
+    return matchesLiveOwnerLease(lease, snapshot.ownerId, snapshot.ownerLeaseGeneration);
+}
+function matchesLiveOwnerLease(lease, ownerId, leaseGeneration) {
+    if (lease.value.expiresAt === undefined
+        || lease.value.expiresAt.getTime() <= lease.value.storeNow.getTime()) {
         return false;
+    }
     const owner = decodeOwnerRecord(lease.value.bytes);
-    return owner.ownerId === snapshot.ownerId;
+    return owner.ownerId === ownerId
+        && BigInt(owner.leaseGeneration) === leaseGeneration;
+}
+function sameDescriptorPredecessor(expected, current) {
+    if (expected.kind === 'missing' || current.kind === 'missing') {
+        return expected.kind === current.kind;
+    }
+    return Buffer.from(expected.value.bytes).equals(Buffer.from(current.value.bytes));
 }
 function liveOwnerLeaseGeneration(lease) {
     if (lease.kind === 'missing'
@@ -3118,6 +3096,10 @@ function sameClientServerDescriptor(left, right) {
 function sameFanoutDescriptor(left, right) {
     return descriptorFingerprint(left, ['updatedAt']) === descriptorFingerprint(right, ['updatedAt']);
 }
+function canRenewMesh(current, next) {
+    return sameOwnerGeneration(current, next)
+        && next.descriptorRevision > current.descriptorRevision;
+}
 function canRenewClientServer(current, next) {
     return sameOwnerGeneration(current, next)
         && next.descriptorRevision > current.descriptorRevision
@@ -3188,6 +3170,13 @@ function rejected(updatedAt) {
         updatedAt
     };
 }
+function ignoredStale(updatedAt) {
+    return {
+        status: Locations_1.ZLinkLocationWriteStatus.IgnoredStale,
+        generation: 0n,
+        updatedAt
+    };
+}
 function requireOwnerInput(ownerId, leaseTtlMs) {
     if (Buffer.byteLength(ownerId, 'utf8') < 1 || ownerId.includes('\0')) {
         throw new TypeError('Owner ID must be non-empty UTF-8 without NUL.');

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "@zlink-systems/framework",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zlink-systems/zlink.git",
+    "directory": "framework/languages/node/packages/framework"
+  },
+  "homepage": "https://zlink.systems/",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -13,7 +19,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.221.0",
-    "@zlink-systems/stream-wire": "0.10.0",
-    "@zlink-systems/zlink": "0.17.3"
+    "@zlink-systems/stream-wire": "0.11.0",
+    "@zlink-systems/zlink": "0.17.6"
   }
 }

package/src/runtime/backend/runtime-values.ts

@@ -68,6 +68,12 @@ export function isBackendNotConnectedError(error: unknown): boolean {
   const result = error.result;
   return result === SubmitResult.NotConnected || result === RequestResult.NotConnected;
 }
+
+export function isBackendRequestTimeoutError(error: unknown): boolean {
+  return isZLinkBackendResultError(error)
+    && error.operation === 'request'
+    && error.result === RequestResult.TimedOut;
+}
 export type ZLinkBackendMessageLike = Message | Buffer | Uint8Array | string;
 export interface ZLinkBackendSendSubmitBuilder {
   message(message: ZLinkBackendMessageLike): ZLinkBackendSendSubmitBuilder;

package/src/runtime/channels/channel-socket-registry.ts

@@ -53,6 +53,9 @@ import {
 } from './fanout-service-wire';
 import type { ZLinkChannelEnvelopeHeader } from './channel-envelope';
 import type { ApplicationJobQueue } from '../host/application-job-queue';
+import {
+  isBackendRequestTimeoutError
+} from '../backend/runtime-values';
 
 const MAX_LIFECYCLE_GENERATION = 0x7fff_ffff_ffff_ffffn;
 const CLIENT_SERVER_PROBE_INTERVAL_MS = 5_000;
@@ -1213,6 +1216,7 @@ export class ZLinkChannelSocketRegistry {
     if (connection.admissionAttempt !== undefined) return;
     const admissionAttempt = Symbol(connectionId);
     connection.admissionAttempt = admissionAttempt;
+    let retryAdmission = false;
     try {
       const admission = await requestClientServerAdmission(
         connection.dealer,
@@ -1242,11 +1246,20 @@ export class ZLinkChannelSocketRegistry {
         || connection.physicalConnectionId !== physicalConnectionId
         || connection.admissionAttempt !== admissionAttempt) return;
       this.removeReadyConnection(connectionId);
+      if (isBackendRequestTimeoutError(error)) {
+        retryAdmission = true;
+        return;
+      }
       throw error;
     } finally {
       if (this.clientServerConnections.get(connectionId) === connection
+        && connection.physicalConnectionId === physicalConnectionId
         && connection.admissionAttempt === admissionAttempt) {
         connection.admissionAttempt = undefined;
+        if (retryAdmission) {
+          void this.admitConfiguredClientServerConnection(channelName, connectionId)
+            .catch(error => this.oneWayFailureSink?.(error));
+        }
       }
     }
   }

package/src/runtime/channels/client-server-location-runtime.ts

@@ -24,6 +24,9 @@ import {
 } from './client-server-service-wire';
 import { discoveryAvailabilityForRuntimeState } from '../foundation/runtime-state-projections';
 import { ZLinkStateLane } from '../execution/state-lane';
+import {
+  isBackendRequestTimeoutError
+} from '../backend/runtime-values';
 
 interface ActiveClientServerTarget {
   descriptor: ZLinkClientServerServerDescriptor;
@@ -331,6 +334,7 @@ export class ZLinkClientServerLocationRuntime {
     if (current === undefined) {
       return;
     }
+    let retryAdmission = false;
     try {
       const admission = await requestAdmission(
         current.dealer,
@@ -370,11 +374,21 @@ export class ZLinkClientServerLocationRuntime {
         current.target.dealer = undefined;
         await this.sockets.closeClientServerConnection(connectionId);
       }
+      if (isBackendRequestTimeoutError(error)) {
+        retryAdmission = true;
+        return;
+      }
       throw error;
     } finally {
-      await this.lane.run(() => {
-        if (this.connections.get(connectionId) === current.target) current.target.handshakeInFlight = false;
+      const shouldRetry = await this.lane.run(() => {
+        if (this.connections.get(connectionId) !== current.target) return false;
+        current.target.handshakeInFlight = false;
+        return retryAdmission;
       });
+      if (shouldRetry) {
+        void this.handleTransportReady(connectionId, _routingId, _endpoint)
+          .catch(error => this.locationRuntime.reportDiscoveryFailure(error));
+      }
     }
   }