@zlink-systems/framework 0.30.1 → 0.30.2

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

@@ -1,3 +1,6 @@
+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';
@@ -8,7 +11,6 @@ import {
   type ZLinkActorRequestCall,
   type ZLinkActorSendCall,
   type ZLinkMessageSerializer,
-  ZLinkFrameworkErrorKind,
   ZLinkFrameworkException,
   ZLinkSpotKind
 } from '../../contracts';
@@ -27,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';
@@ -60,6 +61,7 @@ import {
   encodeStreamHeader,
   streamCodecForContentType,
   tryDecodeStreamFrame,
+  ZLinkStreamCodec,
   ZLinkStreamHeaderFlags,
   ZLinkStreamMessageKind
 } from '../streams/protocol';
@@ -186,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),
@@ -203,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);
@@ -414,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'
       );
@@ -437,16 +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,
@@ -498,6 +501,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
       () =>
         node.requestToActor(actor, toMessageLikeParts(parts), {
           flags: ZLINK_BACKEND_SEND_NONE,
+          routeFence: nativeActorRouteFence(route, actor),
           timeoutMs,
           onAdmitted
         }),
@@ -527,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;
@@ -597,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,
@@ -756,7 +730,7 @@ class DefaultZLinkActorRequestCall implements ZLinkActorRequestCall {
     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>(
@@ -804,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);
@@ -829,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
-  });
 }