@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/actors/actor-client.ts

@@ -1,4 +1,9 @@
+import { isUtf8 } from 'node:buffer';
+import { channelErrorKindFromCode } from '../channels/channel-envelope';
+import { routingIdsEqual } from '../routing-id';
 import { ZlinkStreamContentType } from '@zlink-systems/stream-wire';
+import { createZLinkRequest } from '../messaging/request-result';
+import type { ZLinkRequest } from '../../contracts/Handlers/Attributes';
 import {
   type ActorRef,
   type RoutingId,
@@ -6,7 +11,6 @@ import {
   type ZLinkActorRequestCall,
   type ZLinkActorSendCall,
   type ZLinkMessageSerializer,
-  ZLinkFrameworkErrorKind,
   ZLinkFrameworkException,
   ZLinkSpotKind
 } from '../../contracts';
@@ -25,7 +29,6 @@ import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message
 import {
   isZLinkBackendResultError,
   RequestResult,
-  SubmitResult,
   ZLINK_BACKEND_SEND_NONE
 } from '../backend/runtime-values';
 import { ZLinkConfigurationException } from '../configuration';
@@ -58,6 +61,7 @@ import {
   encodeStreamHeader,
   streamCodecForContentType,
   tryDecodeStreamFrame,
+  ZLinkStreamCodec,
   ZLinkStreamHeaderFlags,
   ZLinkStreamMessageKind
 } from '../streams/protocol';
@@ -89,7 +93,8 @@ export interface ZLinkActorClientOptions {
     parts: readonly Message[],
     returnResponse: boolean,
     actor: ActorRef,
-    deadlineUnixMs?: number
+    deadlineUnixMs?: number,
+    onAdmitted?: () => void
   ) => Promise<unknown> | undefined;
   readonly sendErrorReporter?: (error: unknown) => void;
   readonly routeTransport?: ZLinkActorRoutedJoinTransport;
@@ -118,8 +123,17 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
   requestToActor(actorId: string, request: unknown): ZLinkActorRequestCall {
     requireActorId(actorId);
     return new DefaultZLinkActorRequestCall(
-      (packetName, timeoutMs, metadata, signal) =>
-        this.request(actorId, packetName, request, timeoutMs, metadata, signal, 'async'),
+      (packetName, timeoutMs, metadata, signal, onAdmitted) =>
+        this.request(
+          actorId,
+          packetName,
+          request,
+          timeoutMs,
+          metadata,
+          signal,
+          'async',
+          onAdmitted
+        ),
       (packetName, timeoutMs, metadata, signal) =>
         this.request(actorId, packetName, request, timeoutMs, metadata, signal, 'yield'),
       actorId,
@@ -174,7 +188,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
       const node = this.requireNode(meshName);
       if (
         this.options.routeTransport !== undefined &&
-        String(node.status().routingId) !== String(actor.nodeRid)
+        !routingIdsEqual(node.status().routingId, actor.nodeRid)
       ) {
         await this.options.routeTransport.sendToSpot(
           remoteActorRouteTarget(route),
@@ -191,7 +205,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
         );
         return { status: ZLinkSubmitStatus.Submitted };
       }
-      return await this.submitActorSend(meshName, toBackendActorRef(actor), parts);
+      return await this.submitActorSend(meshName, toBackendActorRef(actor), parts, route);
     } catch (error) {
       if (isStaleActorError(error)) {
         this.invalidateActorRoute(actorId);
@@ -211,7 +225,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
     timeoutMs: number | undefined,
     metadata: ReadonlyMap<string, string>,
     signal?: AbortSignal,
-    waitPolicy: 'async' | 'yield' = 'async'
+    waitPolicy: 'async' | 'yield' = 'async',
+    onAdmitted?: () => void
   ): Promise<TReply> {
     throwIfAborted(signal);
     const sourceSpotId = currentZLinkActorExecution()?.spotId ?? currentZLinkSpotSerialSourceId();
@@ -267,7 +282,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
         parts,
         true,
         routedActor,
-        deadlineUnixMs
+        deadlineUnixMs,
+        onAdmitted
       );
       if (handoff !== undefined) {
         const submissions = [handoff];
@@ -278,7 +294,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
             parts,
             true,
             routedActor,
-            deadlineUnixMs
+            deadlineUnixMs,
+            onAdmitted
           );
           if (duplicate !== undefined) submissions.push(duplicate);
         }
@@ -297,7 +314,8 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
         remainingActorRequestTimeout(actorId, deadlineMs),
         signal,
         route,
-        messageFollow
+        messageFollow,
+        onAdmitted
       );
     } catch (error) {
       if (isStaleActorError(error)) {
@@ -398,13 +416,15 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
   private async submitActorSend(
     meshName: string,
     actor: ZLinkBackendActorRef,
-    parts: readonly Message[]
+    parts: readonly Message[],
+    route: ZLinkResolvedActorRoute
   ): Promise<ZLinkSubmitResult> {
     const node = this.requireNode(meshName);
     try {
       return classifySubmitResult(
         await node.sendToActor(actor, toMessageLikeParts(parts), {
-          flags: ZLINK_BACKEND_SEND_NONE
+          flags: ZLINK_BACKEND_SEND_NONE,
+          routeFence: nativeActorRouteFence(route, actor)
         }),
         'Actor send'
       );
@@ -421,15 +441,15 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
     actor: ZLinkBackendActorRef,
     parts: readonly Message[],
     timeoutMs: number | undefined,
-    signal?: AbortSignal,
-    route?: ZLinkResolvedActorRoute,
-    messageFollowContext?: ZLinkActorMessageFollowContext
+    signal: AbortSignal | undefined,
+    route: ZLinkResolvedActorRoute,
+    messageFollowContext: ZLinkActorMessageFollowContext,
+    onAdmitted?: () => void
   ): Promise<TReply> {
     const node = this.requireNode(meshName);
     if (
       this.options.routeTransport !== undefined &&
-      String(node.status().routingId) !== String(actor.nodeRid) &&
-      route !== undefined
+      !routingIdsEqual(node.status().routingId, actor.nodeRid)
     ) {
       const relay = encodeRemoteActorPacketRelayPayload({
         actorId: actor.actorId,
@@ -459,7 +479,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
         this.options.routeTransport,
         remoteActorRouteTarget(route),
         relay,
-        { timeoutMs, signal },
+        { timeoutMs, signal, onAdmitted },
         `Remote Actor request is not available for '${actor.actorId}'.`,
         (replyParts) => JSON.parse(replyParts[0]?.getString('utf8') ?? '{}')
       );
@@ -481,7 +501,9 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
       () =>
         node.requestToActor(actor, toMessageLikeParts(parts), {
           flags: ZLINK_BACKEND_SEND_NONE,
-          timeoutMs
+          routeFence: nativeActorRouteFence(route, actor),
+          timeoutMs,
+          onAdmitted
         }),
       signal
     );
@@ -509,6 +531,15 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
   }
 }
 
+function nativeActorRouteFence(route: ZLinkResolvedActorRoute, actor: ZLinkBackendActorRef) {
+  return {
+    actor,
+    targetNodeGeneration: route.ownerNodeGeneration,
+    authorityOwnerGeneration: route.authorityOwnerGeneration,
+    ownerLeaseGeneration: route.ownerLeaseGeneration
+  };
+}
+
 function remoteActorRouteTarget(route: ZLinkResolvedActorRoute) {
   if (route.enclosingSpotRoute !== undefined) {
     return route.enclosingSpotRoute;
@@ -579,45 +610,6 @@ function requireActorId(actorId: string): void {
   }
 }
 
-export async function forwardEncodedActorPacket(
-  node: ZLinkBackendMeshNode,
-  completions: ZLinkMeshCompletionTable,
-  actor: ActorRef,
-  header: Buffer,
-  payload: Buffer,
-  returnResponse: boolean,
-  timeoutMs: number | undefined,
-  serializers?: ReadonlyMap<string, ZLinkMessageSerializer>
-): Promise<unknown> {
-  const target = toBackendActorRef(actor);
-  const parts = [header, payload];
-  const packetName = decodeStreamHeader(header).name;
-  if (!returnResponse) {
-    if (
-      (await node.sendToActor(target, parts, { flags: ZLINK_BACKEND_SEND_NONE })) !==
-      SubmitResult.Ok
-    ) {
-      throw routeNotConnected('Actor handoff send submit was not accepted.');
-    }
-    return undefined;
-  }
-  const completion = await completions.submit(() =>
-    node.requestToActor(target, parts, {
-      flags: ZLINK_BACKEND_SEND_NONE,
-      timeoutMs
-    })
-  );
-  if (completion.terminalResult !== RequestResult.Ok) {
-    closeMeshCompletion(completion);
-    throw mapRequestResult(
-      completion.terminalResult,
-      completion.failureErrno,
-      'Actor handoff request'
-    );
-  }
-  return decodeActorReply(completion.parts, serializers, packetName);
-}
-
 function toBackendActorRef(actor: ActorRef): ZLinkBackendActorRef {
   return {
     nodeRid: actor.nodeRid,
@@ -700,7 +692,8 @@ class DefaultZLinkActorRequestCall implements ZLinkActorRequestCall {
       packetName: string | undefined,
       timeoutMs: number | undefined,
       metadata: ReadonlyMap<string, string>,
-      signal?: AbortSignal
+      signal?: AbortSignal,
+      onAdmitted?: () => void
     ) => Promise<TReply>,
     private readonly yieldSubmitter: <TReply>(
       packetName: string | undefined,
@@ -728,20 +721,24 @@ class DefaultZLinkActorRequestCall implements ZLinkActorRequestCall {
     return this;
   }
 
-  submit<TReply>(signal?: AbortSignal): Promise<TReply> {
-    return this.execute<TReply>('async', signal);
+  submit<TReply>(signal?: AbortSignal): ZLinkRequest<TReply> {
+    this.rejectSelfActorRequest();
+    return createZLinkRequest((onAdmitted) => this.execute<TReply>('async', signal, onAdmitted));
   }
 
   yield<TReply>(signal?: AbortSignal): Promise<TReply> {
     this.rejectSelfActorRequest();
     const turn = requireZLinkYieldTurn(this.turn);
     const pending = this.execute<TReply>('yield', signal);
-    return turn.yieldPromise(pending);
+    return turn.yieldFrameworkPromise(pending);
   }
 
-  private execute<TReply>(waitPolicy: 'async' | 'yield', signal?: AbortSignal): Promise<TReply> {
+  private execute<TReply>(
+    waitPolicy: 'async' | 'yield',
+    signal?: AbortSignal,
+    onAdmitted?: () => void
+  ): Promise<TReply> {
     ensureSingleSubmit(this.executed);
-    this.rejectSelfActorRequest();
     this.executed = true;
     throwIfAborted(signal);
     const submitter = waitPolicy === 'async' ? this.asyncSubmitter : this.yieldSubmitter;
@@ -749,7 +746,8 @@ class DefaultZLinkActorRequestCall implements ZLinkActorRequestCall {
       this.packet ?? resolveFrameworkPacketName(this.request, undefined, 'Actor'),
       this.timeoutMs ?? this.defaultRequestTimeoutMs,
       this.selectedMetadata,
-      signal
+      signal,
+      onAdmitted
     );
   }
 
@@ -780,19 +778,21 @@ function decodeActorReply<TReply>(
         const header = decodeStreamHeader(frame.header);
         const payload = RuntimeMessage.from(frame.payload) as Message;
         try {
-          return decodeActorReplyPayload<TReply>(header.kind, payload, serializers, packetName);
+          return decodeActorReplyPayload<TReply>(
+            header.kind,
+            header.codec,
+            payload,
+            serializers,
+            packetName
+          );
         } finally {
           payload.close();
         }
       }
     }
-    if (reply.length >= 2) {
-      const header = decodeStreamHeader(reply[0].data());
-      return decodeActorReplyPayload<TReply>(header.kind, reply[1], serializers, packetName);
-    }
     throw createInternalFrameworkException(
       ZLinkFrameworkInternalErrorKind.RequestProtocolError,
-      'Actor request reply is empty.'
+      'Actor request reply must contain one valid STREAM frame.'
     );
   } finally {
     closeMessages(reply);
@@ -805,24 +805,39 @@ function closeMessages(parts: readonly Message[]): void {
 
 function decodeActorReplyPayload<TReply>(
   kind: ZLinkStreamMessageKind,
+  codec: ZLinkStreamCodec,
   payload: Message,
   serializers?: ReadonlyMap<string, ZLinkMessageSerializer>,
   packetName?: string
 ): TReply {
   if (kind === ZLinkStreamMessageKind.Error) {
-    const error = decodeFrameworkPayloadMessage<{
-      readonly message?: string;
-      readonly kind?: number;
-    }>(payload, serializers);
-    const wireKind = error.kind;
-    const publicKind =
-      typeof wireKind === 'number' &&
-      Number.isInteger(wireKind) &&
-      wireKind >= ZLinkFrameworkErrorKind.NotFound &&
-      wireKind <= ZLinkFrameworkErrorKind.InternalFailure
-        ? (wireKind as ZLinkFrameworkErrorKind)
-        : ZLinkFrameworkErrorKind.InternalFailure;
-    throw new ZLinkFrameworkException(publicKind, error.message ?? 'Actor request failed.');
+    if (codec !== ZLinkStreamCodec.Json || !isUtf8(payload.data())) {
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.RequestProtocolError,
+        'Actor Error reply requires UTF-8 JSON.'
+      );
+    }
+    const error = decodeFrameworkPayloadMessage<unknown>(payload);
+    if (
+      typeof error !== 'object' ||
+      error === null ||
+      typeof (error as { code?: unknown }).code !== 'string' ||
+      typeof (error as { message?: unknown }).message !== 'string'
+    ) {
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.RequestProtocolError,
+        'Actor Error reply requires code and message strings.'
+      );
+    }
+    const wire = error as { code: string; message: string };
+    const kind = channelErrorKindFromCode(wire.code);
+    if (kind === undefined) {
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.RequestProtocolError,
+        `Actor Error reply uses an unknown error code '${wire.code}'.`
+      );
+    }
+    throw new ZLinkFrameworkException(kind, wire.message);
   }
   return decodeFrameworkPayloadMessage<TReply>(
     payload,

package/src/runtime/actors/actor-context.ts

@@ -1,3 +1,4 @@
+import { routingIdsEqual } from '../routing-id';
 import {
   type RoutingId,
   type SpotId,
@@ -90,6 +91,11 @@ export class DefaultZLinkActorContext implements ZLinkActorContext {
     return this.state.actorId;
   }
 
+  /** Actor-turn view of the single current Session binding (§7). */
+  get currentSessionBinding() {
+    return this.state.boundSession;
+  }
+
   get objectGeneration(): bigint {
     return this.state.nativeActorRef?.generation ?? 1n;
   }
@@ -282,11 +288,24 @@ class DefaultZLinkActorJoinSpotCall implements ZLinkActorJoinSpotCall {
             deadline.close();
             requestMessage.close();
           }
+          if (result.sourceCleanup !== undefined) {
+            // Infrastructure cleanup has its own terminal, outside the public Failed conversion.
+            try {
+              const cleanup = result.sourceCleanup();
+              await (this.turn === undefined ? cleanup : this.turn.yieldFrameworkPromise(cleanup));
+            } catch (error) {
+              traceJoinError(this.actor, error, this.coordinator, ZLinkDispatchErrorAction.Drop);
+              throw error;
+            } finally {
+              this.state.endDeferredJoin();
+            }
+            return;
+          }
           if (
             !result.accepted ||
             sourceNodeRid === undefined ||
             result.actor === undefined ||
-            String(sourceNodeRid) === String(result.actor.nodeRid)
+            routingIdsEqual(sourceNodeRid, result.actor.nodeRid)
           ) {
             await notifyJoinCompletion(this.actor, operationId, result, this.messageSerializers);
           } else {
@@ -417,11 +436,24 @@ class DefaultZLinkActorJoinEntrySpotCall implements ZLinkActorJoinEntrySpotCall
             deadline.close();
             requestMessage.close();
           }
+          if (result.sourceCleanup !== undefined) {
+            // Infrastructure cleanup has its own terminal, outside the public Failed conversion.
+            try {
+              const cleanup = result.sourceCleanup();
+              await (this.turn === undefined ? cleanup : this.turn.yieldFrameworkPromise(cleanup));
+            } catch (error) {
+              traceJoinError(this.actor, error, this.coordinator, ZLinkDispatchErrorAction.Drop);
+              throw error;
+            } finally {
+              this.state.endDeferredJoin();
+            }
+            return;
+          }
           if (
             !result.accepted ||
             sourceNodeRid === undefined ||
             result.actor === undefined ||
-            String(sourceNodeRid) === String(result.actor.nodeRid)
+            routingIdsEqual(sourceNodeRid, result.actor.nodeRid)
           ) {
             await notifyJoinCompletion(this.actor, operationId, result, this.messageSerializers);
           } else {
@@ -580,7 +612,6 @@ async function notifyJoinFailure(
   error: unknown,
   coordinator?: ZLinkActorJoinCoordinator
 ): Promise<void> {
-  console.error(`actor join failure actor=${actor.context.actorId}`, error);
   const frameworkError =
     error instanceof ZLinkFrameworkException
       ? error
@@ -590,6 +621,20 @@ async function notifyJoinFailure(
           false,
           error
         );
+  traceJoinError(actor, error, coordinator, ZLinkDispatchErrorAction.ReplyError);
+  await actor.onJoinCompleted?.({
+    status: 'failed',
+    operationId,
+    kind: frameworkError.kind
+  });
+}
+
+function traceJoinError(
+  actor: ZLinkActor,
+  error: unknown,
+  coordinator: ZLinkActorJoinCoordinator | undefined,
+  errorAction: ZLinkDispatchErrorAction
+): void {
   //  The completion carries only an error kind, so trace the cause on the
   //  message flow under the same flow id as the Join that produced it.
   const tracePoint = coordinator?.messageFlow?.()?.begin(ZLinkMessageFlowOutcome.Error);
@@ -601,13 +646,8 @@ async function notifyJoinFailure(
     packetName: 'JoinSpot',
     actorId: actor.context.actorId,
     errorReason: ZLinkDispatchErrorReason.HandlerException,
-    errorAction: ZLinkDispatchErrorAction.ReplyError,
+    errorAction,
     errorType: errorDetails?.errorType,
     errorMessage: errorDetails?.errorMessage
   });
-  await actor.onJoinCompleted?.({
-    status: 'failed',
-    operationId,
-    kind: frameworkError.kind
-  });
 }