@zlink-systems/framework 0.29.1 → 0.30.1

package/src/runtime/foundation/service-liveness-registry.ts

@@ -1,7 +1,7 @@
 import { UINT64_MAX } from '@zlink-systems/stream-wire';
 export interface ServiceProbe {
   readonly nodeRoutingId: string;
-  readonly connectionId: string;
+  readonly connectionId: string | bigint;
   readonly probeId: bigint;
 }
 
@@ -10,20 +10,52 @@ export interface ServiceLivenessTick {
   readonly timedOutNodes: readonly string[];
 }
 
-interface PeerState {
-  readonly connectionId: string;
+export const DEFAULT_SERVICE_PROBE_INTERVAL_MS = 5_000;
+export const DEFAULT_SERVICE_PEER_TIMEOUT_MS = 15_000;
+
+export class ServiceLivenessConnection {
   deadlineMs: number;
   nextProbeMs: number;
   outstandingProbe?: bigint;
-  ready: boolean;
-}
 
-export const DEFAULT_SERVICE_PROBE_INTERVAL_MS = 5_000;
-export const DEFAULT_SERVICE_PEER_TIMEOUT_MS = 15_000;
+  constructor(
+    readonly connectionId: string | bigint,
+    nowMs: number,
+    private readonly probeIntervalMs = DEFAULT_SERVICE_PROBE_INTERVAL_MS,
+    private readonly peerTimeoutMs = DEFAULT_SERVICE_PEER_TIMEOUT_MS
+  ) {
+    this.deadlineMs = nowMs + peerTimeoutMs;
+    this.nextProbeMs = nowMs;
+  }
+
+  readonly recordReceived = (nowMs = performance.now()): void => {
+    this.deadlineMs = Math.max(this.deadlineMs, nowMs + this.peerTimeoutMs);
+  };
+
+  isExpired(nowMs: number): boolean {
+    return nowMs >= this.deadlineMs;
+  }
+
+  tryGetProbe(nowMs: number, allocateProbeId: () => bigint): bigint | undefined {
+    if (nowMs < this.nextProbeMs) return undefined;
+    this.outstandingProbe ??= allocateProbeId();
+    do {
+      this.nextProbeMs += this.probeIntervalMs;
+    } while (this.nextProbeMs <= nowMs);
+    return this.outstandingProbe;
+  }
+
+  acknowledge(probeId: bigint, nowMs: number): boolean {
+    this.recordReceived(nowMs);
+    if (this.outstandingProbe !== probeId) return false;
+    this.outstandingProbe = undefined;
+    return true;
+  }
+}
 
 /** Uses monotonic milliseconds and never treats application traffic as a probe ACK. */
 export class ServiceLivenessRegistry {
-  private readonly peers = new Map<string, PeerState>();
+  private readonly peers = new Map<string, ServiceLivenessConnection>();
   private nextProbeId = 1n;
 
   constructor(
@@ -40,33 +72,31 @@ export class ServiceLivenessRegistry {
     }
   }
 
-  admit(nodeRoutingId: string, connectionId: string, nowMs: number): void {
+  admit(
+    nodeRoutingId: string,
+    connectionId: string | bigint,
+    nowMs: number
+  ): ServiceLivenessConnection {
     requireIdentity(nodeRoutingId, 'nodeRoutingId');
-    requireIdentity(connectionId, 'connectionId');
+    if (typeof connectionId === 'string') requireIdentity(connectionId, 'connectionId');
+    else if (connectionId === 0n) throw new TypeError('connectionId must be nonzero.');
     const current = this.peers.get(nodeRoutingId);
-    if (current?.connectionId === connectionId) return;
-    this.peers.set(nodeRoutingId, {
+    if (current?.connectionId === connectionId) return current;
+    const admitted = new ServiceLivenessConnection(
       connectionId,
-      deadlineMs: nowMs + this.peerTimeoutMs,
-      nextProbeMs: nowMs + this.probeIntervalMs,
-      ready: false
-    });
+      nowMs,
+      this.probeIntervalMs,
+      this.peerTimeoutMs
+    );
+    this.peers.set(nodeRoutingId, admitted);
+    return admitted;
   }
 
-  requestProbe(nodeRoutingId: string, connectionId: string, nowMs: number): boolean {
-    const current = this.peers.get(nodeRoutingId);
-    if (
-      current === undefined ||
-      current.connectionId !== connectionId ||
-      current.ready ||
-      current.outstandingProbe !== undefined
-    )
-      return false;
-    current.nextProbeMs = Math.min(current.nextProbeMs, nowMs);
-    return true;
+  recordReceived(connection: ServiceLivenessConnection, nowMs: number): void {
+    connection.recordReceived(nowMs);
   }
 
-  disconnect(nodeRoutingId: string, connectionId: string): boolean {
+  disconnect(nodeRoutingId: string, connectionId: string | bigint): boolean {
     const current = this.peers.get(nodeRoutingId);
     if (current === undefined || current.connectionId !== connectionId) return false;
     this.peers.delete(nodeRoutingId);
@@ -75,27 +105,18 @@ export class ServiceLivenessRegistry {
 
   acknowledge(
     nodeRoutingId: string,
-    connectionId: string,
+    connectionId: string | bigint,
     probeId: bigint,
     nowMs: number
   ): boolean {
     const current = this.peers.get(nodeRoutingId);
-    if (
-      current === undefined ||
-      current.connectionId !== connectionId ||
-      current.outstandingProbe !== probeId
-    ) {
-      return false;
-    }
-    current.outstandingProbe = undefined;
-    current.deadlineMs = nowMs + this.peerTimeoutMs;
-    current.ready = true;
-    return true;
+    if (current === undefined || current.connectionId !== connectionId) return false;
+    return current.acknowledge(probeId, nowMs);
   }
 
   acknowledgeProbe(
     nodeRoutingId: string,
-    connectionId: string,
+    connectionId: string | bigint,
     probeId: bigint
   ): ServiceProbe | undefined {
     const current = this.peers.get(nodeRoutingId);
@@ -109,21 +130,14 @@ export class ServiceLivenessRegistry {
     const probes: ServiceProbe[] = [];
     const timedOutNodes: string[] = [];
     for (const [nodeRoutingId, peer] of this.peers) {
-      if (peer.deadlineMs <= nowMs) {
+      if (peer.isExpired(nowMs)) {
         timedOutNodes.push(nodeRoutingId);
         this.peers.delete(nodeRoutingId);
         continue;
       }
-      if (peer.nextProbeMs > nowMs) continue;
-      peer.outstandingProbe ??= this.allocateProbeId();
-      probes.push({
-        nodeRoutingId,
-        connectionId: peer.connectionId,
-        probeId: peer.outstandingProbe
-      });
-      do {
-        peer.nextProbeMs += this.probeIntervalMs;
-      } while (peer.nextProbeMs <= nowMs);
+      const probeId = peer.tryGetProbe(nowMs, this.allocateProbeId);
+      if (probeId !== undefined)
+        probes.push({ nodeRoutingId, connectionId: peer.connectionId, probeId });
     }
     timedOutNodes.sort();
     return { probes, timedOutNodes };
@@ -133,16 +147,11 @@ export class ServiceLivenessRegistry {
     return this.peers.size;
   }
 
-  isReady(nodeRoutingId: string, connectionId: string): boolean {
-    const current = this.peers.get(nodeRoutingId);
-    return current?.connectionId === connectionId && current.ready;
-  }
-
-  private allocateProbeId(): bigint {
+  private readonly allocateProbeId = (): bigint => {
     const result = this.nextProbeId++;
     if (this.nextProbeId > UINT64_MAX) this.nextProbeId = 1n;
     return result;
-  }
+  };
 }
 
 function requireIdentity(value: string, field: string): void {

package/src/runtime/foundation/service-mailbox.ts

@@ -1,4 +1,5 @@
 import type { ApplicationJobRecordLease } from '../application-jobs/application-ingress-record-owner';
+import type { ReceiveRecord } from './service-runtime-contracts';
 
 export type ServiceMailboxDomain = 'application' | 'infrastructure';
 
@@ -23,6 +24,8 @@ export interface ServiceMailboxRecord {
   readonly stateful?: unknown;
   /** Host queue permit plus its ordinary Framework-owned ingress record. */
   readonly applicationJob?: ApplicationJobRecordLease;
+  /** Unregistered raw-pull terminal, retained by the existing mailbox owner. */
+  readonly completion?: ReceiveRecord;
 }
 
 export interface ServiceMailboxClaim {
@@ -85,7 +88,10 @@ export class ServiceMailbox {
   }
 
   tryEnqueue(record: ServiceMailboxRecord): boolean {
-    if (record.owner.length === 0 || record.parts.length === 0) {
+    if (
+      record.owner.length === 0 ||
+      (record.parts.length === 0 && record.completion === undefined)
+    ) {
       throw new TypeError('Mailbox records require an owner and retained payload.');
     }
     const target = this.domain(record.domain);

package/src/runtime/foundation/service-relocation-object-owner.ts

@@ -17,6 +17,7 @@ const DEFAULT_RELOCATION_CALLBACK_CONCURRENCY = 8;
 
 export interface ServiceRelocationSealedWork {
   readonly boundSessionState: Uint8Array;
+  readonly sessionBinding?: ServiceRelocationParticipant['sessionBinding'];
   readonly queuedMessages: readonly ServiceRelocationQueuedMessage[];
   readonly timers: readonly ServiceRelocationTimer[];
 }
@@ -185,6 +186,7 @@ export class ServiceRelocationObjectCaptureOwner {
           authorityOwnerGeneration: unit.authorityOwnerGeneration,
           applicationState: Buffer.from(await unit.captureApplicationState(signal)),
           boundSessionState: Buffer.from(work.boundSessionState),
+          ...(work.sessionBinding === undefined ? {} : { sessionBinding: work.sessionBinding }),
           queuedMessages: work.queuedMessages.map((message) => ({
             sequence: message.sequence,
             payload: Buffer.from(message.payload)

package/src/runtime/foundation/service-relocation-runtime.ts

@@ -39,6 +39,7 @@ export interface ServiceRelocationParticipant {
   readonly applicationStatePresent?: boolean;
   readonly applicationState: Uint8Array;
   readonly boundSessionState: Uint8Array;
+  readonly sessionBinding?: GeneratedRelocationEnvelopeV1['sessionBindings'][number];
   readonly queuedMessages: readonly ServiceRelocationQueuedMessage[];
   readonly timers: readonly ServiceRelocationTimer[];
 }
@@ -726,6 +727,11 @@ export function encodeServiceRelocationEnvelope(
           'timer due time'
         )
       })),
+      sessionBindings: participants.flatMap((participant, index) =>
+        participant.sessionBinding === undefined
+          ? []
+          : [{ ...participant.sessionBinding, participantId: BigInt(index + 1) }]
+      ),
       pendingTimerTicks: pending.map((value) => ({
         participantId: value.participantId,
         order: value.order,
@@ -765,11 +771,22 @@ export function decodeServiceRelocationEnvelope(
   const aggregateId = uuid(generated.relocationHigh, generated.relocationLow);
   if (aggregateId === undefined) throw new TypeError('Invalid relocation identity.');
   positiveBigInt(aggregateGeneration, 'aggregate generation');
+  const bindings = new Map(
+    generated.sessionBindings.map((binding) => [binding.participantId, binding])
+  );
+  for (const id of bindings.keys()) {
+    if (id > BigInt(generated.applicationStates.length))
+      throw new TypeError('Session binding participant is outside its inventory.');
+  }
   const participants = generated.applicationStates.map((state, index) => {
     if (state.participantId !== BigInt(index + 1)) {
       throw new TypeError('Application state participant order is invalid.');
     }
-    return wireParticipant(state.participantId, state.hasState, Buffer.from(state.payload));
+    const binding = bindings.get(state.participantId);
+    return {
+      ...wireParticipant(state.participantId, state.hasState, Buffer.from(state.payload)),
+      ...(binding === undefined ? {} : { sessionBinding: binding })
+    };
   });
   const byId = new Map(participants.map((value) => [value.participantId!, value]));
   for (const work of generated.savedWork) {

package/src/runtime/foundation/service-runtime-contracts.ts

@@ -422,7 +422,12 @@ export interface ServiceSpot {
   requestToChannel(
     channelName: string,
     parts: MessageLike | readonly MessageLike[],
-    options?: { flags?: number; timeoutMs?: number; applicationMetadata?: Buffer }
+    options?: {
+      flags?: number;
+      timeoutMs?: number;
+      applicationMetadata?: Buffer;
+      onAdmitted?: () => void;
+    }
   ): MeshOperationId;
   sendToSpot(
     targetNodeRid: unknown,
@@ -445,6 +450,7 @@ export interface ServiceSpot {
       timeoutMs?: number;
       applicationMetadata?: Buffer;
       routeFence?: ServiceDirectSpotRouteFence;
+      onAdmitted?: () => void;
       entrySpot?: boolean;
     }
   ): MeshOperationId;