@zlink-systems/framework 0.21.0 → 0.23.0

package/src/runtime/streams/managed-stream.ts

@@ -10,10 +10,7 @@ import type {
   ZLinkMessageSerializer,
   ZLinkStream
 } from '../../contracts';
-import {
-  ZLinkSubmitStatus,
-  type ZLinkSubmitResult
-} from '../messaging/submission-result';
+import { ZLinkSubmitStatus, type ZLinkSubmitResult } from '../messaging/submission-result';
 import type { Message } from '../../contracts/Common/Message';
 import { throwIfAborted } from '../abort';
 import { encodeFrameworkPayloadMessage } from '../messaging/payload-codec';
@@ -36,6 +33,8 @@ import {
   type ZLinkMeshCompletionTable
 } from '../backend/mesh-completion-table';
 import {
+  encodeActorBoundFrame,
+  encodeActorUnboundFrame,
   encodeSessionClosingFrame,
   encodeStreamControlFrame,
   ZLinkStreamCloseReasonCode
@@ -54,15 +53,17 @@ export interface ZLinkNativeSessionRoute {
   readonly completions: ZLinkMeshCompletionTable;
 }
 
+interface ZLinkManagedActorBinding {
+  readonly actor: ZLinkBackendActorRef;
+  readonly bindingGeneration?: bigint;
+  readonly route?: ZLinkNativeSessionRoute;
+}
+
 export class ZLinkManagedStream implements ZLinkStream {
   private currentLocalAddr: string | undefined;
   private currentRemoteAddr: string | undefined;
   private transportClosed = false;
-  private readonly nativeActorBindings = new Map<string, {
-    readonly actor: ZLinkBackendActorRef;
-    readonly bindingGeneration: bigint;
-    readonly route?: ZLinkNativeSessionRoute;
-  }>();
+  private readonly nativeActorBindings = new Map<string, ZLinkManagedActorBinding>();
 
   constructor(
     private readonly socket: ZLinkBackendStreamSocket,
@@ -138,12 +139,11 @@ export class ZLinkManagedStream implements ZLinkStream {
     signal?: AbortSignal
   ): Promise<ZLinkSubmitResult> {
     throwIfAborted(signal);
-    return await this.sendBoundActor(actorId, parts, ZLINK_SEND_DONT_WAIT)
+    return (await this.sendBoundActor(actorId, parts, ZLINK_SEND_DONT_WAIT))
       ? { status: ZLinkSubmitStatus.Submitted }
       : { status: ZLinkSubmitStatus.Backpressured };
   }
 
-
   async close(signal?: AbortSignal): Promise<void> {
     throwIfAborted(signal);
     this.markTransportClosed();
@@ -196,12 +196,12 @@ export class ZLinkManagedStream implements ZLinkStream {
         `Stream session '${this.sessionId}' is disconnected.`
       );
     }
+    const nativeActor = toNativeActorRef(actor);
     const route = this.nativeRoute(actor.meshName);
     if (route !== undefined) {
       if (route.service.status().state === 1) {
         route.service.start();
       }
-      const nativeActor = toNativeActorRef(actor);
       await this.ensureNativeActorRoute(route, actor, timeoutMs, signal);
       if (this.isTransportClosed()) {
         throw createInternalFrameworkException(
@@ -211,25 +211,29 @@ export class ZLinkManagedStream implements ZLinkStream {
       }
       await this.requireSuccessfulCompletion(
         route.completions.submit(
-          () => route.service.bindActor(
-            this.backendRoutingId(),
-            nativeActor,
-            timeoutMs,
-            onBindingReplaced === undefined
-              ? undefined
-              : (_actorId, retiredSession, replacedActor) => {
-                  onBindingReplaced(replacedActor, retiredSession);
-                },
-            toStreamSessionActorAuthorityFence(authorityFence)
-          ),
+          () =>
+            route.service.bindActor(
+              this.backendRoutingId(),
+              nativeActor,
+              timeoutMs,
+              onBindingReplaced === undefined
+                ? undefined
+                : (_actorId, retiredSession, replacedActor) => {
+                    onBindingReplaced(replacedActor, retiredSession);
+                  },
+              toStreamSessionActorAuthorityFence(authorityFence)
+            ),
           signal
         ),
-        `Actor '${actor.actorId}' native session bind`,
+        `Actor '${actor.actorId}' native session bind`
       );
-      const binding = route.service.bindings(this.backendRoutingId())
-        .find((candidate) =>
-          candidate.actor.actorId === nativeActor.actorId
-          && candidate.actor.generation === nativeActor.generation);
+      const binding = route.service
+        .bindings(this.backendRoutingId())
+        .find(
+          (candidate) =>
+            candidate.actor.actorId === nativeActor.actorId &&
+            candidate.actor.generation === nativeActor.generation
+        );
       if (binding === undefined) {
         throw createInternalFrameworkException(
           ZLinkFrameworkInternalErrorKind.RouteNotConnected,
@@ -240,12 +244,13 @@ export class ZLinkManagedStream implements ZLinkStream {
         try {
           await this.requireSuccessfulCompletion(
             route.completions.submit(
-              () => route.service.unbindActor(
-                this.backendRoutingId(),
-                nativeActor as never,
-                binding.bindingGeneration,
-                timeoutMs
-              ),
+              () =>
+                route.service.unbindActor(
+                  this.backendRoutingId(),
+                  nativeActor as never,
+                  binding.bindingGeneration,
+                  timeoutMs
+                ),
               signal
             ),
             `Actor '${actor.actorId}' native session unbind`,
@@ -268,7 +273,13 @@ export class ZLinkManagedStream implements ZLinkStream {
       });
       return;
     }
-    await this.socket.bindActor(this.backendRoutingId(), toBackendActorRef(actor), timeoutMs, signal);
+    await this.socket.bindActor(
+      this.backendRoutingId(),
+      toBackendActorRef(actor),
+      timeoutMs,
+      signal
+    );
+    this.nativeActorBindings.set(actor.actorId, { actor: nativeActor });
   }
 
   private async ensureNativeActorRoute(
@@ -282,23 +293,24 @@ export class ZLinkManagedStream implements ZLinkStream {
       signal
     );
     try {
-      const resolved = completion.kindData?.kind === 'actorLookupCompletion'
-        ? completion.kindData.location.actor
-        : undefined;
+      const resolved =
+        completion.kindData?.kind === 'actorLookupCompletion'
+          ? completion.kindData.location.actor
+          : undefined;
       if (
-        completion.terminalResult !== 0
-        || completion.failureErrno !== 0
-        || resolved === undefined
-        || resolved.actorId !== actor.actorId
-        || resolved.generation !== actor.objectGeneration
-        || String(resolved.nodeRid) !== String(actor.nodeRid)
+        completion.terminalResult !== 0 ||
+        completion.failureErrno !== 0 ||
+        resolved === undefined ||
+        resolved.actorId !== actor.actorId ||
+        resolved.generation !== actor.objectGeneration ||
+        String(resolved.nodeRid) !== String(actor.nodeRid)
       ) {
         throw createInternalFrameworkException(
           ZLinkFrameworkInternalErrorKind.ActorRouteNotFound,
-          `Actor '${actor.actorId}' native route fence does not match its ActorRef `
-          + `(expected ${String(actor.nodeRid)}/${actor.objectGeneration}, `
-          + `resolved ${resolved === undefined ? 'none' : `${String(resolved.nodeRid)}/${resolved.generation}`}, `
-          + `terminal=${completion.terminalResult}, failure=${completion.failureErrno}).`
+          `Actor '${actor.actorId}' native route fence does not match its ActorRef ` +
+            `(expected ${String(actor.nodeRid)}/${actor.objectGeneration}, ` +
+            `resolved ${resolved === undefined ? 'none' : `${String(resolved.nodeRid)}/${resolved.generation}`}, ` +
+            `terminal=${completion.terminalResult}, failure=${completion.failureErrno}).`
         );
       }
     } finally {
@@ -317,19 +329,20 @@ export class ZLinkManagedStream implements ZLinkStream {
     const binding = this.nativeActorBindings.get(actorId);
     if (binding?.route !== undefined) {
       const route = binding.route;
-      if (!this.hasNativeBinding(route, actorId, binding.bindingGeneration)) {
+      if (!this.hasNativeBinding(route, actorId, binding.bindingGeneration!)) {
         this.nativeActorBindings.delete(actorId);
         return;
       }
       try {
         await this.requireSuccessfulCompletion(
           route.completions.submit(
-            () => route.service.unbindActor(
-              this.backendRoutingId(),
-              binding.actor as never,
-              binding.bindingGeneration,
-              timeoutMs
-            ),
+            () =>
+              route.service.unbindActor(
+                this.backendRoutingId(),
+                binding.actor as never,
+                binding.bindingGeneration!,
+                timeoutMs
+              ),
             signal
           ),
           `Actor '${actorId}' native session unbind`,
@@ -343,7 +356,7 @@ export class ZLinkManagedStream implements ZLinkStream {
         // tombstone. A transport teardown can therefore report an internal
         // completion after the exact binding is already gone. Treat only that
         // exact missing binding as stale cleanup; preserve other failures.
-        if (this.hasNativeBinding(route, actorId, binding.bindingGeneration)) {
+        if (this.hasNativeBinding(route, actorId, binding.bindingGeneration!)) {
           throw error;
         }
       }
@@ -353,6 +366,26 @@ export class ZLinkManagedStream implements ZLinkStream {
       return;
     }
     await this.socket.unbindActor(this.backendRoutingId(), actorId, timeoutMs, signal);
+    if (binding !== undefined && this.nativeActorBindings.get(actorId) === binding) {
+      this.nativeActorBindings.delete(actorId);
+    }
+  }
+
+  async enqueueActorBound(actorSlot: number, actorId: string): Promise<void> {
+    await this.submitActorBindingControl(encodeActorBoundFrame(actorSlot, actorId));
+  }
+
+  async enqueueActorUnbound(actorSlot: number): Promise<void> {
+    await this.submitActorBindingControl(encodeActorUnboundFrame(actorSlot));
+  }
+
+  private async submitActorBindingControl(frame: Uint8Array): Promise<void> {
+    const message = NativeMessage.from(frame);
+    try {
+      await this.socket.submit(this.backendRoutingId(), message);
+    } finally {
+      message.close();
+    }
   }
 
   async sendBoundActor(
@@ -370,24 +403,21 @@ export class ZLinkManagedStream implements ZLinkStream {
     if (binding?.route !== undefined) {
       const nativeParts = parts.map((part) => NativeMessage.from(part.data()));
       try {
-        return await binding.route.service.sendToActor(
-          this.backendRoutingId(),
-          binding.actor as never,
-          nativeParts,
-          { flags: flags ?? 0 }
-        ) === 0;
+        return (
+          (await binding.route.service.sendToActor(
+            this.backendRoutingId(),
+            binding.actor as never,
+            nativeParts,
+            { flags: flags ?? 0 }
+          )) === 0
+        );
       } finally {
         for (const part of nativeParts) {
           part.close();
         }
       }
     }
-    return this.socket.sendBoundActor(
-      this.backendRoutingId(),
-      actorId,
-      parts,
-      flags ?? 0
-    );
+    return this.socket.sendBoundActor(this.backendRoutingId(), actorId, parts, flags ?? 0);
   }
 
   updateAddresses(localAddr: string | undefined, remoteAddr: string | undefined): void {
@@ -406,9 +436,12 @@ export class ZLinkManagedStream implements ZLinkStream {
     bindingGeneration: bigint
   ): boolean {
     try {
-      return route.service.bindings(this.backendRoutingId()).some(candidate =>
-        candidate.actor.actorId === actorId
-        && candidate.bindingGeneration === bindingGeneration);
+      return route.service
+        .bindings(this.backendRoutingId())
+        .some(
+          (candidate) =>
+            candidate.actor.actorId === actorId && candidate.bindingGeneration === bindingGeneration
+        );
     } catch {
       // A closed native service owns the teardown state. Keep the original
       // error when its binding snapshot is unavailable.
@@ -428,8 +461,8 @@ export class ZLinkManagedStream implements ZLinkStream {
     const completion = await completionPromise;
     try {
       if (
-        completion.terminalResult !== 0
-        && !acceptedTerminalResults.has(completion.terminalResult)
+        completion.terminalResult !== 0 &&
+        !acceptedTerminalResults.has(completion.terminalResult)
       ) {
         throw wireReplyFailureException(
           completion.terminalResult,
@@ -443,15 +476,15 @@ export class ZLinkManagedStream implements ZLinkStream {
   }
 
   private nativeRoute(meshName: string): ZLinkNativeSessionRoute | undefined {
-    return this.nativeSessionRouteForMesh?.(meshName)
-      ?? (
-        this.nativeSessionService !== undefined && this.meshCompletions !== undefined
-          ? {
-              service: this.nativeSessionService,
-              completions: this.meshCompletions
-            }
-          : undefined
-      );
+    return (
+      this.nativeSessionRouteForMesh?.(meshName) ??
+      (this.nativeSessionService !== undefined && this.meshCompletions !== undefined
+        ? {
+            service: this.nativeSessionService,
+            completions: this.meshCompletions
+          }
+        : undefined)
+    );
   }
 }
 
@@ -460,18 +493,18 @@ export function streamSessionIdFromRoutingId(routingId: unknown): string {
     return routingId;
   }
   if (
-    typeof routingId === 'object'
-    && routingId !== null
-    && 'toHex' in routingId
-    && typeof (routingId as { toHex?: unknown }).toHex === 'function'
+    typeof routingId === 'object' &&
+    routingId !== null &&
+    'toHex' in routingId &&
+    typeof (routingId as { toHex?: unknown }).toHex === 'function'
   ) {
     return (routingId as { toHex(): string }).toHex();
   }
   if (
-    typeof routingId === 'object'
-    && routingId !== null
-    && 'toString' in routingId
-    && typeof (routingId as { toString?: unknown }).toString === 'function'
+    typeof routingId === 'object' &&
+    routingId !== null &&
+    'toString' in routingId &&
+    typeof (routingId as { toString?: unknown }).toString === 'function'
   ) {
     return (routingId as { toString(): string }).toString();
   }

package/src/runtime/streams/native-fallback-bound-session.ts

@@ -63,7 +63,9 @@ export class ZLinkNativeFallbackBoundSession implements ZLinkBoundSession {
     const remoteTarget = this.options.remoteBoundSessionTargetProvider();
     if (remoteTarget !== undefined) {
       const spotKind: ZLinkSpotKind | undefined =
-        'spotKind' in remoteTarget ? remoteTarget.spotKind as ZLinkSpotKind | undefined : undefined;
+        'spotKind' in remoteTarget
+          ? (remoteTarget.spotKind as ZLinkSpotKind | undefined)
+          : undefined;
       const payload = encodeRemoteActorPacketRelayPayload({
         actorId: this.options.actorId,
         routerChannelId: remoteTarget.routerChannelId,
@@ -76,27 +78,26 @@ export class ZLinkNativeFallbackBoundSession implements ZLinkBoundSession {
         spotId: remoteTarget.spotId,
         spotKind: spotKind ?? ZLinkSpotKind.Entry
       };
-      if (await tryRequestRoutedJson(
-        this.options.routedTransport,
-        target,
-        payload,
-        { timeoutMs: this.options.requestTimeoutMs, signal }
-      )) {
+      if (
+        await tryRequestRoutedJson(this.options.routedTransport, target, payload, {
+          timeoutMs: this.options.requestTimeoutMs,
+          signal
+        })
+      ) {
         return;
       }
-      await this.options.routedTransport.sendToSpot(
-        target,
-        payload,
-        { packetName: ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET, signal }
-      );
+      await this.options.routedTransport.sendToSpot(target, payload, {
+        packetName: ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
+        signal
+      });
       return;
     }
     const actorRef = this.options.actorRefProvider();
     const node = this.options.nativeActorNodeProvider();
     if (
-      actorRef !== undefined
-      && node !== undefined
-      && currentBindingGeneration(actorRef) !== undefined
+      actorRef !== undefined &&
+      node !== undefined &&
+      currentBindingGeneration(actorRef) !== undefined
     ) {
       await this.options.runtime.disconnectNativeBoundSession(node, actorRef, signal);
       return;
@@ -129,7 +130,11 @@ class ZLinkNativeFallbackBoundSessionSendCall implements ZLinkBoundSessionSendCa
     if (this.executed) {
       throwAlreadySubmitted('Bound session send call');
     }
-    const packetName = resolveFrameworkPacketName(this.message, this.selectedPacketName, 'Bound session');
+    const packetName = resolveFrameworkPacketName(
+      this.message,
+      this.selectedPacketName,
+      'Bound session'
+    );
     this.executed = true;
     throwIfAborted(signal);
     const result = await this.execute(packetName, signal);
@@ -144,13 +149,15 @@ class ZLinkNativeFallbackBoundSessionSendCall implements ZLinkBoundSessionSendCa
     // Call-scoped flow (spec 27 §4): the relay JSON flow pair and any nested
     // routed-transport envelope share one ambient flow that does not outlive
     // this submit call.
-    return runWithOutboundFlow(
-      this.options.flowCreationEnabled?.() ?? true,
-      () => this.executeScoped(packetName, signal)
+    return runWithOutboundFlow(this.options.flowCreationEnabled?.() ?? true, () =>
+      this.executeScoped(packetName, signal)
     );
   }
 
-  private async executeScoped(packetName: string, signal?: AbortSignal): Promise<ZLinkSubmitResult> {
+  private async executeScoped(
+    packetName: string,
+    signal?: AbortSignal
+  ): Promise<ZLinkSubmitResult> {
     const localActor = this.options.localActorProvider?.() === true;
     const remoteTarget = this.options.remoteBoundSessionTargetProvider();
     const sealedRemoteTarget = remoteTarget?.relocationSealId !== undefined;
@@ -175,11 +182,7 @@ class ZLinkNativeFallbackBoundSessionSendCall implements ZLinkBoundSessionSendCa
       const actorRef = this.options.actorRefProvider();
       const node = this.options.nativeActorNodeProvider();
       const bindingGeneration = currentBindingGeneration(actorRef);
-      if (
-        actorRef !== undefined
-        && node !== undefined
-        && bindingGeneration !== undefined
-      ) {
+      if (actorRef !== undefined && node !== undefined && bindingGeneration !== undefined) {
         nativeAttempted = true;
         const result = await this.options.runtime.sendNativeBoundSession(
           node,
@@ -200,8 +203,9 @@ class ZLinkNativeFallbackBoundSessionSendCall implements ZLinkBoundSessionSendCa
     }
     if (remoteTarget !== undefined) {
       const actorRef = this.options.actorRefProvider();
-      const ownershipGeneration = (actorRef as (ActorRef & { ownershipGeneration?: bigint }) | undefined)
-        ?.ownershipGeneration;
+      const ownershipGeneration = (
+        actorRef as (ActorRef & { ownershipGeneration?: bigint }) | undefined
+      )?.ownershipGeneration;
       const payload = encodeRemoteBoundSessionSendPayload({
         actorId: this.options.actorId,
         actorMeshName: actorRef?.meshName,
@@ -220,27 +224,28 @@ class ZLinkNativeFallbackBoundSessionSendCall implements ZLinkBoundSessionSendCa
           ? currentOrCreateFlow('Application')
           : undefined)
       });
-      const submit = this.options.routedTransport.submitInfrastructure
-        ?? this.options.routedTransport.submit;
-      const result = submit === undefined
-        ? await this.options.routedTransport.sendToSpot(
-            {
-              routerChannelId: remoteTarget.routerChannelId,
-              targetNodeRid: remoteTarget.targetNodeRid,
-              spotId: remoteTarget.spotId,
-              spotKind: ZLinkSpotKind.Entry
-            },
-            payload,
-            { packetName: ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET, signal }
-          )
-        : await submit.call(
-            this.options.routedTransport,
-            remoteTarget.routerChannelId,
-            String(remoteTarget.targetNodeRid),
-            ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET,
-            payload,
-            signal
-          );
+      const submit =
+        this.options.routedTransport.submitInfrastructure ?? this.options.routedTransport.submit;
+      const result =
+        submit === undefined
+          ? await this.options.routedTransport.sendToSpot(
+              {
+                routerChannelId: remoteTarget.routerChannelId,
+                targetNodeRid: remoteTarget.targetNodeRid,
+                spotId: remoteTarget.spotId,
+                spotKind: ZLinkSpotKind.Entry
+              },
+              payload,
+              { packetName: ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET, signal }
+            )
+          : await submit.call(
+              this.options.routedTransport,
+              remoteTarget.routerChannelId,
+              String(remoteTarget.targetNodeRid),
+              ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET,
+              payload,
+              signal
+            );
       this.traceSubmitted(result, packetName);
       return result;
     }
@@ -259,10 +264,10 @@ class ZLinkNativeFallbackBoundSessionSendCall implements ZLinkBoundSessionSendCa
     const node = this.options.nativeActorNodeProvider();
     const bindingGeneration = currentBindingGeneration(actorRef);
     if (
-      !nativeAttempted
-      && actorRef !== undefined
-      && node !== undefined
-      && bindingGeneration !== undefined
+      !nativeAttempted &&
+      actorRef !== undefined &&
+      node !== undefined &&
+      bindingGeneration !== undefined
     ) {
       const result = await this.options.runtime.sendNativeBoundSession(
         node,