@zlink-systems/framework 0.29.1 → 0.30.1

package/src/runtime/channels/spot-route-dispatch-strategy.ts

@@ -42,6 +42,7 @@ export interface ZLinkLocalSpotRouteDispatcher {
     context: {
       readonly channelName: string;
       readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
       readonly metadata?: ReadonlyMap<string, string>;
     }
   ): Promise<TReply>;
@@ -163,7 +164,8 @@ export class ZLinkSpotRouteDispatchStrategy {
     request: unknown,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    metadata?: ReadonlyMap<string, string>
+    metadata?: ReadonlyMap<string, string>,
+    onAdmitted?: () => void
   ): Promise<TReply> {
     return runWithOutboundFlow(this.options.flowCreationEnabled?.() ?? true, () =>
       this.routeRequestToSpotScoped<TReply>(
@@ -172,7 +174,8 @@ export class ZLinkSpotRouteDispatchStrategy {
         request,
         timeoutMs,
         signal,
-        metadata
+        metadata,
+        onAdmitted
       )
     );
   }
@@ -183,7 +186,8 @@ export class ZLinkSpotRouteDispatchStrategy {
     request: unknown,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    metadata?: ReadonlyMap<string, string>
+    metadata?: ReadonlyMap<string, string>,
+    onAdmitted?: () => void
   ): Promise<TReply> {
     throwIfAborted(signal);
     const localSpotRouteNode = this.targets.localRouteNode(spotRouteTarget);
@@ -194,7 +198,8 @@ export class ZLinkSpotRouteDispatchStrategy {
         packetName,
         request,
         timeoutMs,
-        signal
+        signal,
+        onAdmitted
       );
     }
     const codecs = codecsForFrameworkPacket(packetName, this.options.codecs);
@@ -216,7 +221,8 @@ export class ZLinkSpotRouteDispatchStrategy {
         parts,
         codecs,
         timeoutMs,
-        signal
+        signal,
+        onAdmitted
       );
       if (namedSpotNodeRequest !== undefined) return namedSpotNodeRequest;
     }
@@ -226,7 +232,8 @@ export class ZLinkSpotRouteDispatchStrategy {
         parts,
         codecs,
         timeoutMs,
-        signal
+        signal,
+        onAdmitted
       );
     }
     if (this.targets.hasBoundRouteRouter(spotRouteTarget.routerChannelId)) {
@@ -236,7 +243,8 @@ export class ZLinkSpotRouteDispatchStrategy {
         codecs,
         ZLINK_SEND_DONT_WAIT,
         timeoutMs,
-        signal
+        signal,
+        onAdmitted
       );
     }
     const spotNodeRequest = this.spotNodeTransport.request<TReply>(
@@ -244,7 +252,8 @@ export class ZLinkSpotRouteDispatchStrategy {
       parts,
       codecs,
       timeoutMs,
-      signal
+      signal,
+      onAdmitted
     );
     if (spotNodeRequest !== undefined) {
       return spotNodeRequest;
@@ -255,7 +264,8 @@ export class ZLinkSpotRouteDispatchStrategy {
       codecs,
       0,
       timeoutMs,
-      signal
+      signal,
+      onAdmitted
     );
   }
 
@@ -265,7 +275,8 @@ export class ZLinkSpotRouteDispatchStrategy {
     packetName: string | undefined,
     request: unknown,
     timeoutMs: number | undefined,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    onAdmitted?: () => void
   ): Promise<TReply> {
     return this.sourceSpotRouter.request<TReply>(
       sourceSpot,
@@ -273,7 +284,8 @@ export class ZLinkSpotRouteDispatchStrategy {
       packetName,
       request,
       timeoutMs,
-      signal
+      signal,
+      onAdmitted
     );
   }
 
@@ -292,14 +304,16 @@ export class ZLinkSpotRouteDispatchStrategy {
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: Message,
     timeoutMs: number | undefined,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    onAdmitted?: () => void
   ): Promise<readonly Message[]> {
     return this.sourceSpotRouter.requestRaw(
       sourceSpot,
       spotRouteTarget,
       request,
       timeoutMs,
-      signal
+      signal,
+      onAdmitted
     );
   }
 
@@ -307,7 +321,8 @@ export class ZLinkSpotRouteDispatchStrategy {
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: Message,
     timeoutMs: number | undefined,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    onAdmitted?: () => void
   ): Promise<readonly Message[]> {
     throwIfAborted(signal);
     if (this.targets.hasNamedSpotNode(spotRouteTarget.routerChannelId)) {
@@ -315,23 +330,37 @@ export class ZLinkSpotRouteDispatchStrategy {
         spotRouteTarget,
         request,
         timeoutMs,
-        signal
+        signal,
+        onAdmitted
       );
       if (namedSpotNodeRequest !== undefined) return namedSpotNodeRequest;
     }
     if (this.bridgeTransport.has(spotRouteTarget.routerChannelId)) {
-      return this.bridgeTransport.requestRaw(spotRouteTarget, request, timeoutMs, signal);
+      return this.bridgeTransport.requestRaw(
+        spotRouteTarget,
+        request,
+        timeoutMs,
+        signal,
+        onAdmitted
+      );
     }
     const spotNodeRequest = this.spotNodeTransport.requestRaw(
       spotRouteTarget,
       request,
       timeoutMs,
-      signal
+      signal,
+      onAdmitted
     );
     if (spotNodeRequest !== undefined) {
       return spotNodeRequest;
     }
 
-    return this.routerSocketTransport.requestRaw(spotRouteTarget, request, timeoutMs, signal);
+    return this.routerSocketTransport.requestRaw(
+      spotRouteTarget,
+      request,
+      timeoutMs,
+      signal,
+      onAdmitted
+    );
   }
 }

package/src/runtime/diagnostics/message-flow.ts

@@ -35,7 +35,7 @@ export const DEFAULT_ZLINK_DIAGNOSTICS: ZLinkDiagnosticsOptions = {
   includeMessageSizes: false
 };
 
-const telemetryLogger = openTelemetryLogs.getLogger('@zlink-systems/framework');
+export const telemetryLogger = openTelemetryLogs.getLogger('@zlink-systems/framework');
 const telemetryTracer = openTelemetryTrace.getTracer('@zlink-systems/framework');
 
 let diagnosticsGeneration = 0n;

package/src/runtime/execution/serial-execution-queue.ts

@@ -9,6 +9,7 @@ import {
 export type ZLinkSerialWorkLane = 'application' | 'lifecycle';
 
 export interface ZLinkSerialWorkOptions {
+  readonly onAdmitted?: () => void;
   readonly lane?: ZLinkSerialWorkLane;
   readonly payloadBytes?: number;
   readonly metadataBytes?: number;
@@ -269,6 +270,7 @@ export class ZLinkSerialExecutionQueue {
       release();
       throw error;
     }
+    options.onAdmitted?.();
     this.scheduleDrain();
     return result;
   }

package/src/runtime/foundation/actor-join-recovery-codec.ts

@@ -131,7 +131,7 @@ export function encodeCanonicalActorJoinRecoverySavedWork(
   const replyContentType =
     operationId === undefined
       ? null
-      : requireText(input.replyContentType, 'Actor Join reply content type');
+      : (nullableText(input.replyContentType ?? null, 'Actor Join reply content type') ?? null);
   const metadata = encodeMetadataJson({
     Request: {
       ActorId: requireText(input.actorId, 'Actor id'),
@@ -288,7 +288,7 @@ export function decodeCanonicalActorJoinRecoverySavedWork(
   const operationLow = integer(metadata.OperationIdLow, 'OperationIdLow');
   const hasOperation = operationHigh !== 0n || operationLow !== 0n;
   const replyContentType = nullableText(metadata.ReplyContentType, 'ReplyContentType');
-  if (hasOperation !== (replyContentType !== undefined)) {
+  if (!hasOperation && replyContentType !== undefined) {
     throw new TypeError('Canonical Actor Join recovery reply identity is invalid.');
   }
   const targetNodeRid = base64(metadata.TargetNodeRid, 'TargetNodeRid');

package/src/runtime/foundation/durable-service-request.ts

@@ -0,0 +1,137 @@
+import { awaitWithAbort } from '../abort';
+import { RequestResult, SubmitResult, isZLinkBackendResultError } from '../backend/runtime-values';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
+
+export interface PeerRouteObservation {
+  readonly generation?: bigint;
+  readonly ready: boolean;
+}
+
+export interface DurableServiceRequestPort {
+  readonly requestStopSignal?: AbortSignal;
+  observePeerRoute(target: string): PeerRouteObservation;
+  observePeerRouteChanged(listener: (target: string) => void): () => void;
+  observePeerConnectionIntentRemoved(listener: (target: string) => void): () => void;
+  requestService(
+    target: string,
+    parts: readonly Uint8Array[],
+    timeoutMs: number,
+    onAdmitted?: () => void
+  ): Promise<readonly Buffer[]>;
+}
+
+/** Actor model §8.1: a ready edge or a typed transport failure owns replay. */
+export async function requestDurableService(
+  port: DurableServiceRequestPort,
+  target: string,
+  parts: readonly Uint8Array[],
+  deadlineMs: number,
+  operationKind: string,
+  signal?: AbortSignal,
+  onSubmitted?: (signal: AbortSignal) => Promise<void>
+): Promise<readonly Buffer[]> {
+  let wasAdmitted = false;
+  const stop = new AbortController();
+  const exhausted = (cause?: unknown) =>
+    createInternalFrameworkException(
+      wasAdmitted
+        ? ZLinkFrameworkInternalErrorKind.DeadlineExceeded
+        : ZLinkFrameworkInternalErrorKind.RouteNotConnected,
+      `${operationKind} exhausted its end-to-end deadline.`,
+      true,
+      cause
+    );
+  const timer = setTimeout(
+    () => stop.abort(exhausted()),
+    Math.max(0, Math.ceil(deadlineMs - performance.now()))
+  );
+  const unobserveIntent = port.observePeerConnectionIntentRemoved((rid) => {
+    if (rid === target)
+      stop.abort(
+        createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.RouteNotConnected,
+          `${operationKind} target node lifecycle ended.`,
+          true
+        )
+      );
+  });
+  const cancellation = AbortSignal.any([
+    stop.signal,
+    ...(signal === undefined ? [] : [signal]),
+    ...(port.requestStopSignal === undefined ? [] : [port.requestStopSignal])
+  ]);
+  try {
+    for (;;) {
+      cancellation.throwIfAborted();
+      const remainingMs = Math.ceil(deadlineMs - performance.now());
+      if (remainingMs <= 0) throw exhausted();
+      let changed!: () => void;
+      const transition = new Promise<void>((resolve) => {
+        changed = resolve;
+      });
+      let submittedGeneration: bigint | undefined;
+      const attemptStop = new AbortController();
+      const attemptSignal = AbortSignal.any([cancellation, attemptStop.signal]);
+      const unobserveRoute = port.observePeerRouteChanged((rid) => {
+        if (rid !== target) return;
+        const route = port.observePeerRoute(target);
+        if (
+          submittedGeneration === undefined
+            ? route.ready
+            : route.generation !== undefined && route.generation !== submittedGeneration
+        ) {
+          changed();
+          attemptStop.abort();
+        }
+      });
+      try {
+        const route = port.observePeerRoute(target);
+        if (!route.ready) {
+          await awaitWithAbort(transition, cancellation);
+          continue;
+        }
+        submittedGeneration = route.generation;
+        const reply = port.requestService(target, parts, remainingMs, () => {
+          wasAdmitted = true;
+        });
+        const request =
+          onSubmitted === undefined
+            ? reply
+            : Promise.race([
+                reply,
+                Promise.resolve()
+                  .then(() => onSubmitted(attemptSignal))
+                  .then(() => reply)
+              ]);
+        const result = await awaitWithAbort(
+          Promise.race([request.then((parts) => ({ parts })), transition.then(() => undefined)]),
+          cancellation
+        );
+        if (result !== undefined) return result.parts;
+      } catch (error) {
+        cancellation.throwIfAborted();
+        if (!durableRequestCanReplay(error)) throw error;
+        if (isZLinkBackendResultError(error) && error.operation === 'request') wasAdmitted = true;
+      } finally {
+        attemptStop.abort();
+        unobserveRoute();
+      }
+    }
+  } finally {
+    clearTimeout(timer);
+    unobserveIntent();
+  }
+}
+
+export function durableRequestCanReplay(error: unknown): boolean {
+  if (!isZLinkBackendResultError(error)) return false;
+  return error.operation === 'request'
+    ? error.result === RequestResult.NotConnected || error.result === RequestResult.TimedOut
+    : error.result === SubmitResult.NotConnected ||
+        error.result === SubmitResult.NotFound ||
+        error.result === SubmitResult.NotAdmitted ||
+        error.result === SubmitResult.Backpressured;
+}

package/src/runtime/foundation/operation-identity.ts

@@ -19,12 +19,16 @@ export type ZLinkOperationIdentityKey = string & {
 export function operationIdentityKey(
   operationId: ZLinkOperationIdentity128
 ): ZLinkOperationIdentityKey {
+  validateOperationIdentity(operationId);
+  return `${operationId.high.toString(16)}:${operationId.low.toString(16)}` as ZLinkOperationIdentityKey;
+}
+
+export function validateOperationIdentity(operationId: ZLinkOperationIdentity128): void {
   requireUnsigned64(operationId.high, 'operationId.high');
   requireUnsigned64(operationId.low, 'operationId.low');
   if (operationId.high === 0n && operationId.low === 0n) {
     throw new RangeError('Operation identity must not be all zero.');
   }
-  return `${operationId.high.toString(16)}:${operationId.low.toString(16)}` as ZLinkOperationIdentityKey;
 }
 
 export function createRandomOperationIdentity(