@zlink-systems/framework 0.27.0 → 0.29.0

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

@@ -17,9 +17,14 @@ export class ZLinkActorSerialExecutor {
   constructor(
     private readonly actorId: string,
     private readonly sourceSpotId: unknown,
-    options?: ZLinkSerialSchedulerOptions
+    options?: ZLinkSerialSchedulerOptions,
+    sharedOwner?: ZLinkSerialExecutionQueue
   ) {
-    this.scheduler = new ZLinkSerialExecutionQueue((record) => this.runRecord(record), options);
+    this.scheduler = new ZLinkSerialExecutionQueue(
+      (record) => this.runRecord(record),
+      options,
+      sharedOwner
+    );
   }
 
   execute<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T> {

package/src/runtime/actors/actor-request-deadline.ts

@@ -1,49 +1,4 @@
-import { awaitWithAbort } from '../abort';
-import {
-  createInternalFrameworkException,
-  ZLinkFrameworkInternalErrorKind
-} from '../framework-errors-internal';
-
-export function remainingActorRequestTimeout(
-  actorId: string,
-  deadlineMs: number | undefined
-): number | undefined {
-  if (deadlineMs === undefined) return undefined;
-  const remaining = deadlineMs - performance.now();
-  if (remaining <= 0) {
-    throw createInternalFrameworkException(
-      ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
-      `Actor request '${actorId}' exceeded its deadline.`
-    );
-  }
-  return Math.max(1, Math.ceil(remaining));
-}
-
-/** Only actual Store, delivery-gate, and handoff waits acquire a deadline handle. */
-export async function waitActorReply<T>(
-  reply: Promise<T>,
-  actorId: string,
-  deadlineMs: number | undefined,
-  signal?: AbortSignal
-): Promise<T> {
-  if (deadlineMs === undefined) return await awaitWithAbort(reply, signal);
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  const timeout = new Promise<never>((_resolve, reject) => {
-    const remaining = remainingActorRequestTimeout(actorId, deadlineMs);
-    timer = setTimeout(
-      () =>
-        reject(
-          createInternalFrameworkException(
-            ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
-            `Actor request '${actorId}' exceeded its deadline.`
-          )
-        ),
-      remaining
-    );
-  });
-  try {
-    return await awaitWithAbort(Promise.race([reply, timeout]), signal);
-  } finally {
-    clearTimeout(timer);
-  }
-}
+export {
+  remainingRequestTimeout as remainingActorRequestTimeout,
+  waitRequestReply as waitActorReply
+} from '../messaging/request-deadline';

package/src/runtime/actors/actor-routed-join-transport.ts

@@ -18,20 +18,18 @@ export interface ZLinkActorRoutedJoinTransport {
     routerChannelId: string,
     targetNodeRid: string,
     packetName: string | undefined,
-    message: unknown,
-    signal?: AbortSignal
+    message: unknown
   ): Promise<ZLinkSubmitResult>;
   submitInfrastructure?(
     routerChannelId: string,
     targetNodeRid: string,
     packetName: string | undefined,
-    message: unknown,
-    signal?: AbortSignal
+    message: unknown
   ): Promise<ZLinkSubmitResult>;
   sendToSpot(
     spotRouteTarget: ZLinkSpotRouteTarget,
     message: unknown,
-    options: { readonly packetName?: string; readonly signal?: AbortSignal }
+    options: { readonly packetName?: string }
   ): Promise<ZLinkSubmitResult>;
   requestRawToSpot?(
     spotRouteTarget: ZLinkSpotRouteTarget,

package/src/runtime/backend/contracts/index.ts

@@ -492,7 +492,6 @@ export interface ZLinkBackendDealerSocket extends ZLinkBackendConnectableSocket
   sendHighWaterMark: number;
   receiveHighWaterMark: number;
   receiveTimeoutMs: number;
-  sendTimeoutMs: number;
   maxMessageSize: number;
   send(message: Message | readonly Message[]): Promise<void>;
   request(message: Message | readonly Message[], timeoutMs?: number): Promise<readonly Message[]>;
@@ -523,7 +522,6 @@ export interface ZLinkBackendRouterSocket extends ZLinkBackendConnectableSocket
   sendHighWaterMark: number;
   receiveHighWaterMark: number;
   receiveTimeoutMs: number;
-  sendTimeoutMs: number;
   maxMessageSize: number;
   setRoutingId(routingId: RoutingId): void;
   recv(flags?: ZLinkBackendRecvFlags): Received | undefined;
@@ -577,7 +575,6 @@ export interface ZLinkBackendStreamPacket {
 }
 
 export interface ZLinkBackendStreamSocket extends ZLinkBackendSocket {
-  readonly sendTimeoutMs: number;
   readonly sendHighWaterMark: number;
   /** Framework stream ingress uses this bound for packet payload validation. */
   maxMessageSize: number;
@@ -588,11 +585,7 @@ export interface ZLinkBackendStreamSocket extends ZLinkBackendSocket {
     payload: Message | readonly Message[],
     flags: ZLinkBackendSendFlags
   ): boolean;
-  submit(
-    routingId: RoutingId,
-    payload: Message | readonly Message[],
-    timeoutMs?: number
-  ): Promise<void>;
+  submit(routingId: RoutingId, payload: Message | readonly Message[]): Promise<void>;
   disconnectPeer(routingId: RoutingId): void;
   bindActor(
     sessionRid: RoutingId,

package/src/runtime/backend/node/node-backend-adapter-support.ts

@@ -1,5 +1,9 @@
 import { constants as osConstants } from 'node:os';
-import { requireOneWayCompletion, ZLinkSubmitStatus } from '../../messaging/submission-result';
+import { waitRequestReply } from '../../messaging/request-deadline';
+import {
+  requireClassicFanoutCompletion,
+  ZLinkSubmitStatus
+} from '../../messaging/submission-result';
 import { loadBinding } from '../node-backend-adapter';
 import { SubmitResult, ZLinkBackendResultError } from '../runtime-values';
 const nativeErrnoValues = osConstants.errno;
@@ -92,7 +96,7 @@ export function submitBindingPublish(
       (translated.result === SubmitResult.Backpressured ||
         translated.result === SubmitResult.NotAdmitted)
     ) {
-      requireOneWayCompletion(
+      requireClassicFanoutCompletion(
         { status: ZLinkSubmitStatus.Backpressured },
         'Classic fanout publish'
       );
@@ -119,6 +123,7 @@ export async function submitBindingAsyncSend(
   operation: ZLinkBindingAsyncSendOperation,
   payload: unknown
 ): Promise<void> {
+  let submission: import('@zlink-systems/zlink').SendSubmission;
   try {
     let current: ZLinkBindingAsyncSendSubmitOperation | undefined;
     const parts = Array.isArray(payload) ? payload : [payload];
@@ -127,9 +132,16 @@ export async function submitBindingAsyncSend(
       current = current === undefined ? operation.message(nativePart) : current.message(nativePart);
     }
     current ??= operation.message(Buffer.alloc(0));
-    await current.submit().admitted;
+    submission = current.submit();
   } catch (error) {
-    throw translateBindingResultError(error);
+    throw translateBindingResultError(error, 'submit');
+  }
+  if (submission.result === SubmitResult.Backpressured) {
+    try {
+      await submission.admitted;
+    } catch (error) {
+      throw translateBindingResultError(error, 'completion');
+    }
   }
 }
 
@@ -156,6 +168,7 @@ export async function submitBindingRequest(
   payload: unknown,
   timeoutMs: number | undefined
 ): Promise<readonly unknown[]> {
+  const deadlineMs = timeoutMs === undefined ? undefined : performance.now() + timeoutMs;
   try {
     let current: ZLinkBindingRequestSubmitOperation | undefined;
     if (Array.isArray(payload)) {
@@ -171,12 +184,39 @@ export async function submitBindingRequest(
     if (timeoutMs !== undefined) {
       current = current.timeout(timeoutMs);
     }
-    return await current.submit().reply;
+    return await bindingRequestReply(current.submit(), deadlineMs);
   } catch (error) {
     throw translateBindingResultError(error);
   }
 }
 
+export async function bindingRequestReply(
+  submission: import('@zlink-systems/zlink').RequestSubmission,
+  deadlineMs: number | undefined
+): Promise<import('@zlink-systems/zlink').Message[]> {
+  const reply = submission.reply;
+  if (submission.result === SubmitResult.Backpressured) {
+    try {
+      const [, replies] = await waitRequestReply(
+        Promise.all([submission.admitted, reply]),
+        'Request',
+        deadlineMs
+      );
+      return replies;
+    } catch (error) {
+      void reply.then(closeBindingReply, () => undefined);
+      throw error;
+    }
+  }
+  return reply;
+}
+
+export function closeBindingReply(
+  replies: readonly import('@zlink-systems/zlink').Message[]
+): void {
+  for (const reply of replies) reply.close();
+}
+
 /**
  * Closes a binding handle once. An already closed or terminated handle counts as
  * closed. A busy close propagates to the caller.

package/src/runtime/backend/node/node-dealer-channel-client-transport.ts

@@ -24,10 +24,8 @@ export class ZLinkDealerChannelClientTransport implements ZLinkChannelClientTran
     channelName: string,
     packetName: string | undefined,
     message: Message,
-    signal?: AbortSignal,
     metadata: ReadonlyMap<string, string> = EMPTY_METADATA
   ): Promise<ZLinkSubmitResult> {
-    throwIfAborted(signal);
     // Call-scoped flow (spec 27 §4): the envelope flow pair does not outlive
     // this outbound call.
     await runWithOutboundFlow(

package/src/runtime/backend/node/node-raw-binding-port.ts

@@ -7,7 +7,6 @@ import {
   createDealerSocket,
   createRouterSocket,
   ReceiveFlowState,
-  SubmitResult,
   type Context,
   type DealerSocket,
   type MonitorEvent,
@@ -18,11 +17,13 @@ import {
   type RequestOperation,
   type RequestSubmitOperation,
   type RouterSocket,
-  type SendOperation,
-  type SendSubmitOperation,
   type Socket
 } from '@zlink-systems/zlink';
-import { translateBindingResultError } from './node-backend-adapter-support';
+import {
+  translateBindingResultError,
+  bindingRequestReply,
+  submitBindingAsyncSend
+} from './node-backend-adapter-support';
 import { isEndpointCloseIgnorableError } from './node-socket-backend-adapter';
 import { ZLinkNodeEventLoopPoller } from './node-event-loop-poller';
 import type {
@@ -266,15 +267,10 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
     this.connect(endpoint);
   }
 
-  async send(targetRid: string, parts: readonly Uint8Array[]): Promise<void> {
+  send(targetRid: string, parts: readonly Uint8Array[]): Promise<void> {
     this.requireOpen();
-    const submission = appendSendParts(
-      this.socket.send(bindingRoutingId(targetRid)),
-      parts
-    ).submit();
-    if (submission.result === SubmitResult.Backpressured) {
-      await submission.admitted;
-    }
+    requireParts(parts);
+    return submitBindingAsyncSend(this.socket.send(bindingRoutingId(targetRid)), parts);
   }
 
   async request(
@@ -283,6 +279,7 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
     timeoutMs: number
   ): Promise<readonly Buffer[]> {
     this.requireOpen();
+    const deadlineMs = performance.now() + timeoutMs;
     let submission: ReturnType<RequestSubmitOperation['submit']>;
     try {
       submission = appendRequestParts(this.socket.request(bindingRoutingId(targetRid)), parts)
@@ -292,7 +289,7 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
       throw translateBindingResultError(error, 'submit');
     }
     try {
-      const replies = await requestReply(submission);
+      const replies = await bindingRequestReply(submission, deadlineMs);
       return copyAndClose(replies);
     } catch (error) {
       throw translateBindingResultError(error, 'completion');
@@ -338,16 +335,15 @@ class NodeRawDealerPort extends NodeRawSocketPort<DealerSocket> implements ZLink
     this.socket.setRoutingId(bindingRoutingId(routingId));
   }
 
-  async send(parts: readonly Uint8Array[]): Promise<void> {
+  send(parts: readonly Uint8Array[]): Promise<void> {
     this.requireOpen();
-    const submission = appendSendParts(this.socket.send(), parts).submit();
-    if (submission.result === SubmitResult.Backpressured) {
-      await submission.admitted;
-    }
+    requireParts(parts);
+    return submitBindingAsyncSend(this.socket.send(), parts);
   }
 
   async request(parts: readonly Uint8Array[], timeoutMs: number): Promise<readonly Buffer[]> {
     this.requireOpen();
+    const deadlineMs = performance.now() + timeoutMs;
     let submission: ReturnType<RequestSubmitOperation['submit']>;
     try {
       submission = appendRequestParts(this.socket.request(), parts).timeout(timeoutMs).submit();
@@ -355,7 +351,7 @@ class NodeRawDealerPort extends NodeRawSocketPort<DealerSocket> implements ZLink
       throw translateBindingResultError(error, 'submit');
     }
     try {
-      const replies = await requestReply(submission);
+      const replies = await bindingRequestReply(submission, deadlineMs);
       return copyAndClose(replies);
     } catch (error) {
       throw translateBindingResultError(error, 'completion');
@@ -368,16 +364,6 @@ class NodeRawDealerPort extends NodeRawSocketPort<DealerSocket> implements ZLink
   }
 }
 
-async function requestReply(
-  submission: ReturnType<RequestSubmitOperation['submit']>
-): Promise<Message[]> {
-  if (submission.result === SubmitResult.Backpressured) {
-    const [, replies] = await Promise.all([submission.admitted, submission.reply]);
-    return replies;
-  }
-  return submission.reply;
-}
-
 class NodeRawMonitorPort implements ZLinkRawMonitorPort {
   private closed = false;
 
@@ -410,18 +396,6 @@ class NodeRawMonitorPort implements ZLinkRawMonitorPort {
   }
 }
 
-function appendSendParts(
-  operation: SendOperation,
-  parts: readonly Uint8Array[]
-): SendSubmitOperation {
-  requireParts(parts);
-  let next = operation.message(parts[0]);
-  for (let index = 1; index < parts.length; index += 1) {
-    next = next.message(parts[index]);
-  }
-  return next;
-}
-
 function appendRequestParts(
   operation: RequestOperation,
   parts: readonly Uint8Array[]

package/src/runtime/backend/node/node-raw-mesh-backend.ts

@@ -297,19 +297,13 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   selectObjectPlacement(stableType: string): ZLinkBackendObjectPlacement {
     const runtime = this.requireRuntime();
     const localNodeRid = runtime.topology.localDescriptor().nodeRoutingId;
-    const status = runtime.topology.objectPlacementStatus(
+    const { status, descriptor } = runtime.topology.selectObjectPlacementWithStatus(
       stableType,
       (candidate) =>
         candidate.nodeRoutingId === localNodeRid ||
         runtime.isPeerRouteReady(candidate.nodeRoutingId)
     );
     if (status !== 'available') return { kind: status };
-    const descriptor = runtime.topology.selectObjectPlacement(
-      stableType,
-      (candidate) =>
-        candidate.nodeRoutingId === localNodeRid ||
-        runtime.isPeerRouteReady(candidate.nodeRoutingId)
-    );
     return descriptor === undefined
       ? { kind: 'unavailable' }
       : {

package/src/runtime/backend/node/node-socket-backend-adapter.ts

@@ -194,7 +194,7 @@ export function wrapSocket<T extends { close(): void }>(
       }
       return submitBindingAsyncSend(operation, payload);
     },
-    submit(routingId: unknown, payload: unknown, _timeoutMs?: number): Promise<void> {
+    submit(routingId: unknown, payload: unknown): Promise<void> {
       if (!hasStream) throw new TypeError('Async stream send requires a STREAM socket.');
       return submitBindingAsyncSend(
         (nativeInstance as T & { send(routingId: unknown): ZLinkBindingAsyncSendOperation }).send(

package/src/runtime/channels/channel-clients.ts

@@ -20,6 +20,7 @@ import {
 import {
   requireOneWayCompletion,
   requirePublishCompletion,
+  requireClassicFanoutCompletion,
   throwAlreadySubmitted,
   ZLinkSubmitStatus,
   type ZLinkSubmitResult
@@ -176,14 +177,13 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
   sendToNode(meshName: string, targetNodeRid: string, message: unknown): ZLinkSendCall {
     return new DefaultZLinkSendCall(
       () => this.requireMesh(meshName),
-      async (packetName, metadata, signal) =>
+      async (packetName, metadata) =>
         normalizeSubmitResult(
           await this.requireTransport().submit(
             meshName,
             targetNodeRid,
             packetName,
             message,
-            signal,
             metadata
           )
         )
@@ -210,7 +210,7 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
   sendToChannel(channelName: string, message: unknown): ZLinkSendCall {
     return new DefaultZLinkSendCall(
       () => this.requireChannelRoute(channelName),
-      async (packetName, metadata, signal) => {
+      async (packetName, metadata) => {
         const route = this.requireChannelRoute(channelName);
         if (route.kind === 'route-mesh') {
           return normalizeSubmitResult(
@@ -219,19 +219,12 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
               channelName,
               packetName,
               message,
-              signal,
               metadata
             )
           );
         }
         return normalizeSubmitResult(
-          await this.requireChannelTransport().send(
-            channelName,
-            packetName,
-            message,
-            signal,
-            metadata
-          )
+          await this.requireChannelTransport().send(channelName, packetName, message, metadata)
         );
       }
     );
@@ -271,9 +264,8 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
       () => {
         this.requireSpotTransport();
       },
-      async (_packetName, metadata, signal) => {
+      async (_packetName, metadata) => {
         await sendToSpotHandle(this.requireSpotTransport(), spot, message, {
-          signal,
           metadata,
           spotRouterChannelIdForMesh: this.spotRouterChannelIdForMesh
         });
@@ -431,8 +423,7 @@ class DefaultZLinkSendCall implements ZLinkSendCall {
     private readonly validate: () => void,
     private readonly submitter: (
       packetName: string | undefined,
-      metadata: ReadonlyMap<string, string>,
-      signal?: AbortSignal
+      metadata: ReadonlyMap<string, string>
     ) => Promise<ZLinkSubmitResult>
   ) {}
 
@@ -450,12 +441,11 @@ class DefaultZLinkSendCall implements ZLinkSendCall {
     return this;
   }
 
-  async submit(signal?: AbortSignal): Promise<void> {
+  async submit(): Promise<void> {
     ensureNotExecuted(this.executed);
     this.validate();
     this.executed = true;
-    throwIfAborted(signal);
-    const result = await this.submitter(undefined, new Map(this.selectedMetadata), signal);
+    const result = await this.submitter(undefined, new Map(this.selectedMetadata));
     requireOneWayCompletion(result, 'One-way send');
   }
 }
@@ -580,6 +570,6 @@ class DefaultZLinkFanoutPublishCall implements ZLinkFanoutPublishCall {
     this.executed = true;
     throwIfAborted(signal);
     const result = await this.submitter(signal);
-    requireOneWayCompletion(result, 'Classic fanout publish');
+    requireClassicFanoutCompletion(result, 'Classic fanout publish');
   }
 }

package/src/runtime/channels/channel-envelope.ts

@@ -86,33 +86,18 @@ export function encodeChannelEnvelopeParts(
   createFlow = true,
   metadata: ReadonlyMap<string, string> = EMPTY_OUTBOUND_METADATA
 ): readonly MessageLike[] {
-  const messageName = resolveFrameworkPacketName(payload, packetName, 'Channel');
-  const encoded = encodePayload(
+  return encodeChannelEnvelopePartsAtDeadline(
+    kind,
+    channelName,
+    packetName,
     payload,
-    codecsForFrameworkPacket(messageName, codecs),
-    messageName,
-    'payload'
+    timeoutMs === undefined ? undefined : Date.now() + timeoutMs,
+    topic,
+    codecs,
+    correlationId,
+    createFlow,
+    metadata
   );
-  const flow = createFlow ? currentOrCreateFlow('Application') : undefined;
-  const envelopeCorrelationId = correlationIdForOutboundKind(kind, correlationId);
-  return [
-    encodeChannelHeader(
-      kind,
-      channelName,
-      messageName,
-      encoded.contentType,
-      envelopeCorrelationId,
-      timeoutMs === undefined ? null : new Date(Date.now() + timeoutMs).toISOString(),
-      topic ?? null,
-      null,
-      null,
-      undefined,
-      applicationMetadataRecord(metadata),
-      flow?.flowId,
-      flow?.flowOrigin
-    ),
-    encoded.message
-  ];
 }
 
 /**
@@ -126,14 +111,17 @@ export function encodeChannelEnvelopePartsAtDeadline(
   channelName: string,
   packetName: string | undefined,
   payload: unknown,
-  deadlineUnixMs: number,
+  deadlineUnixMs: number | undefined,
   topic?: string,
   codecs?: ZLinkChannelEnvelopeCodecRegistry,
   correlationId?: string,
   createFlow = true,
   metadata: ReadonlyMap<string, string> = EMPTY_OUTBOUND_METADATA
 ): readonly MessageLike[] {
-  if (!Number.isSafeInteger(deadlineUnixMs) || deadlineUnixMs <= 0) {
+  if (
+    deadlineUnixMs !== undefined &&
+    (!Number.isSafeInteger(deadlineUnixMs) || deadlineUnixMs <= 0)
+  ) {
     throw new RangeError('deadlineUnixMs must be a positive safe integer.');
   }
   const messageName = resolveFrameworkPacketName(payload, packetName, 'Channel');
@@ -152,7 +140,7 @@ export function encodeChannelEnvelopePartsAtDeadline(
       messageName,
       encoded.contentType,
       envelopeCorrelationId,
-      new Date(deadlineUnixMs).toISOString(),
+      deadlineUnixMs === undefined ? null : new Date(deadlineUnixMs).toISOString(),
       topic ?? null,
       null,
       null,