@zlink-systems/framework 0.29.1 → 0.30.1

package/src/runtime/backend/mesh-dispatch-pump.ts

@@ -58,6 +58,7 @@ export interface ZLinkMeshDispatchFailureContext {
 }
 
 export class ZLinkMeshDispatchPump {
+  private readonly dispatchOwnedRecord = this.dispatchRecord.bind(this);
   private pendingDomains: number = ReadyDomain.None;
   private infrastructureScheduled = false;
   private disposed = false;
@@ -180,6 +181,36 @@ export class ZLinkMeshDispatchPump {
     return new Promise((resolve) => this.idleApplicationWorkers.add(resolve));
   }
 
+  private dispatchRecord(owner: ReadyRecord, record: ReceiveRecord): void | Promise<void> {
+    let result: void | Promise<void>;
+    try {
+      result = this.options.dispatch(owner, record);
+    } catch (error) {
+      this.reportDispatchError(error, meshDispatchFailureContext(record));
+      return;
+    }
+    return result === undefined
+      ? this.finishRecord(record)
+      : Promise.resolve(result).then(
+          () => this.finishRecord(record),
+          (error) => this.reportDispatchError(error, meshDispatchFailureContext(record))
+        );
+  }
+
+  private finishRecord(record: ReceiveRecord): void | Promise<void> {
+    let result: void | Promise<void>;
+    try {
+      result = record.onTerminalCompletion?.();
+    } catch (error) {
+      this.reportDispatchError(error, meshDispatchFailureContext(record));
+      return;
+    }
+    if (result !== undefined)
+      return Promise.resolve(result).catch((error) =>
+        this.reportDispatchError(error, meshDispatchFailureContext(record))
+      );
+  }
+
   private reportDispatchError(error: unknown, context?: ZLinkMeshDispatchFailureContext): void {
     this.options.reportError?.(error, context);
   }
@@ -253,7 +284,7 @@ export class ZLinkMeshDispatchPump {
   ): Promise<boolean> {
     let claimsDrained = 0;
     try {
-      for (;;) {
+      while (!this.disposed) {
         if (claimBudget !== undefined && claimsDrained >= claimBudget) {
           // Lifecycle work has priority, but a bounded turn lets application
           // work make progress when lifecycle records keep arriving.
@@ -282,19 +313,18 @@ export class ZLinkMeshDispatchPump {
               );
               const capacity =
                 owner.ordinaryIngressPreAdmitted === true ? MESH_DISPATCH_RECEIVE_CAPACITY : 1;
-              for (;;) {
-                let claimPermit =
-                  owner.terminalCompletion === true ||
-                  owner.ordinaryIngressPreAdmitted === true ||
-                  domain === ReadyDomain.Infrastructure
-                    ? undefined
-                    : await this.acquirePermit();
-                try {
-                  if (this.capacityStop.signal.aborted) return;
-                  ownerReceiveBatch.reset(capacity);
-                  const received = claim.recvBatch(ownerReceiveBatch, ZLINK_BACKEND_RECV_DONT_WAIT);
-                  if (!received.ok) break;
-                  // This owner keeps its claim while it drains, so its records stay in FIFO order.
+              let claimPermit =
+                owner.terminalCompletion === true ||
+                owner.ordinaryIngressPreAdmitted === true ||
+                domain === ReadyDomain.Infrastructure
+                  ? undefined
+                  : await this.acquirePermit();
+              try {
+                if (this.capacityStop.signal.aborted) return;
+                ownerReceiveBatch.reset(capacity);
+                const received = claim.recvBatch(ownerReceiveBatch, ZLINK_BACKEND_RECV_DONT_WAIT);
+                if (received.ok) {
+                  // The bounded batch stays in claim order until its records finish.
                   try {
                     for (const record of received.records) {
                       if (this.disposed) break;
@@ -305,16 +335,9 @@ export class ZLinkMeshDispatchPump {
                         );
                       }
                       this.recordsSinceYield += 1;
-                      const dispatch = async () => {
-                        try {
-                          await this.options.dispatch(owner, record);
-                          await record.onTerminalCompletion?.();
-                        } catch (error) {
-                          this.reportDispatchError(error, meshDispatchFailureContext(record));
-                        }
-                      };
                       if (permit === undefined) {
-                        await dispatch();
+                        const dispatched = this.dispatchRecord(owner, record);
+                        if (dispatched !== undefined) await dispatched;
                       } else {
                         if (
                           domain === ReadyDomain.Application &&
@@ -325,10 +348,14 @@ export class ZLinkMeshDispatchPump {
                         // and detached handler handoff. Only unused permits remain
                         // owned by the receive attempt's finally block.
                         if (permit === claimPermit) claimPermit = undefined;
-                        await runWithApplicationJobPermit(permit, dispatch);
+                        const dispatched = runWithApplicationJobPermit(
+                          permit,
+                          this.dispatchOwnedRecord,
+                          owner,
+                          record
+                        );
+                        if (dispatched !== undefined) await dispatched;
                       }
-                      const yieldTurn = this.yieldIfNeeded();
-                      if (yieldTurn !== undefined) await yieldTurn;
                     }
                   } finally {
                     // Batch ownership includes records whose dispatch never began,
@@ -338,14 +365,16 @@ export class ZLinkMeshDispatchPump {
                       record.releaseRetainedIngress?.();
                     }
                   }
-                } finally {
-                  claimPermit?.releaseAfterInternalProcessing();
                 }
+              } finally {
+                claimPermit?.releaseAfterInternalProcessing();
               }
             } finally {
               claim.release();
               if (receiveBatch === undefined) ownerReceiveBatch?.close();
             }
+            const yieldTurn = this.yieldIfNeeded();
+            if (yieldTurn !== undefined) await yieldTurn;
           };
           // An application worker drains the one owner it claimed. Infrastructure owners
           // drain independently, so a suspended owner does not hold the other claims.
@@ -366,10 +395,8 @@ export class ZLinkMeshDispatchPump {
         this.recordsSinceYield += 1;
         const yieldTurn = this.yieldIfNeeded();
         if (yieldTurn !== undefined) await yieldTurn;
-        if (!drained.hasResidue) {
-          return false;
-        }
       }
+      return false;
     } finally {
       readyBatch.reset();
     }
@@ -394,7 +421,7 @@ export class ZLinkMeshDispatchPump {
 
   private async acquirePermit(): Promise<ApplicationJobPermitPort | undefined> {
     try {
-      return await this.options.applicationJobQueue.acquire(this.capacityStop.signal);
+      return await this.options.applicationJobQueue.acquire(this.capacityStop.signal, 'remote');
     } catch (error) {
       if (this.disposed || this.capacityStop.signal.aborted) return undefined;
       throw error;

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

@@ -1,4 +1,9 @@
-import type { Context, CoreHwmBudgetSnapshot, TopicMessage } from '@zlink-systems/zlink';
+import type {
+  Context,
+  CoreHwmBudgetSnapshot,
+  ReceiveFlowState,
+  TopicMessage
+} from '@zlink-systems/zlink';
 import type { ZLinkCoreHwmOptions } from '../../../contracts/Configuration';
 import type {
   ZLinkBackendAdapterFactory,
@@ -60,10 +65,12 @@ class ZLinkNodeChannelBackendAdapter implements ZLinkChannelBackendAdapter {
   }
 
   createRouterSocket(context: ZLinkBackendContext): ZLinkBackendRouterSocket {
-    return wrapSocket(
-      zlink.createRouterSocket(asNodeContext(context)),
-      true
-    ) as unknown as ZLinkBackendRouterSocket;
+    const socket = zlink.createRouterSocket(asNodeContext(context));
+    const adapter = wrapSocket(socket, true);
+    adapter.setReceiveFlowState = (state: ReceiveFlowState): void => {
+      socket.setReceiveFlowState(state);
+    };
+    return adapter as unknown as ZLinkBackendRouterSocket;
   }
 
   createPublisherSocket(context: ZLinkBackendContext): ZLinkBackendPublisherSocket {

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

@@ -7,6 +7,7 @@ import {
 import { loadBinding } from '../node-backend-adapter';
 import { SubmitResult, ZLinkBackendResultError } from '../runtime-values';
 const nativeErrnoValues = osConstants.errno;
+const completedSend: Promise<void> = Promise.resolve();
 
 export type ZLinkBindingModule = typeof import('@zlink-systems/zlink');
 export const zlink = loadBinding() as ZLinkBindingModule;
@@ -119,10 +120,22 @@ export function submitBindingReply(operation: ZLinkBindingReplyOperation, payloa
   }
 }
 
-export async function submitBindingAsyncSend(
+export function submitBindingAsyncSend(
   operation: ZLinkBindingAsyncSendOperation,
   payload: unknown
 ): Promise<void> {
+  try {
+    const submission = submitBindingSend(operation, payload);
+    return submission.result === SubmitResult.Backpressured ? submission.admitted : completedSend;
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+
+export function submitBindingSend(
+  operation: ZLinkBindingAsyncSendOperation,
+  payload: unknown
+): import('../raw-binding-port').ZLinkRawSendSubmission {
   let submission: import('@zlink-systems/zlink').SendSubmission;
   try {
     let current: ZLinkBindingAsyncSendSubmitOperation | undefined;
@@ -137,12 +150,15 @@ export async function submitBindingAsyncSend(
     throw translateBindingResultError(error, 'submit');
   }
   if (submission.result === SubmitResult.Backpressured) {
-    try {
-      await submission.admitted;
-    } catch (error) {
-      throw translateBindingResultError(error, 'completion');
-    }
+    return {
+      result: submission.result,
+      admitted: submission.admitted.catch((error) => {
+        throw translateBindingResultError(error, 'completion');
+      })
+    };
   }
+  // Binding SendSubmission is the closed OK | BACKPRESSURED snapshot.
+  return submission as import('../raw-binding-port').ZLinkRawSendSubmission;
 }
 
 export function submitBindingSyncSend(
@@ -166,7 +182,9 @@ export function submitBindingSyncSend(
 export async function submitBindingRequest(
   operation: ZLinkBindingRequestOperation,
   payload: unknown,
-  timeoutMs: number | undefined
+  timeoutMs: number | undefined,
+  recordReceived?: () => void,
+  onAdmitted?: () => void
 ): Promise<readonly unknown[]> {
   const deadlineMs = timeoutMs === undefined ? undefined : performance.now() + timeoutMs;
   try {
@@ -184,7 +202,7 @@ export async function submitBindingRequest(
     if (timeoutMs !== undefined) {
       current = current.timeout(timeoutMs);
     }
-    return await bindingRequestReply(current.submit(), deadlineMs);
+    return await bindingRequestReply(current.submit(), deadlineMs, recordReceived, onAdmitted);
   } catch (error) {
     throw translateBindingResultError(error);
   }
@@ -192,23 +210,35 @@ export async function submitBindingRequest(
 
 export async function bindingRequestReply(
   submission: import('@zlink-systems/zlink').RequestSubmission,
-  deadlineMs: number | undefined
+  deadlineMs: number | undefined,
+  recordReceived?: () => void,
+  onAdmitted?: () => void
 ): 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]),
+        Promise.all([submission.admitted.then(() => onAdmitted?.()), reply]),
         'Request',
         deadlineMs
       );
+      recordReceived?.();
       return replies;
     } catch (error) {
-      void reply.then(closeBindingReply, () => undefined);
+      void reply.then(
+        (parts) => {
+          recordReceived?.();
+          closeBindingReply(parts);
+        },
+        () => undefined
+      );
       throw error;
     }
   }
-  return reply;
+  onAdmitted?.();
+  const replies = await reply;
+  recordReceived?.();
+  return replies;
 }
 
 export function closeBindingReply(
@@ -248,25 +278,6 @@ export function isContextTerminatedError(error: unknown): boolean {
   return error instanceof Error && /context was terminated/i.test(error.message);
 }
 
-export function disableSocketLinger(target: unknown): void {
-  if (
-    target !== null &&
-    typeof target === 'object' &&
-    'options' in target &&
-    typeof target.options === 'object' &&
-    target.options !== null &&
-    'linger' in target.options
-  ) {
-    try {
-      (target.options as { linger: number }).linger = 0;
-    } catch (error) {
-      if (!isContextTerminatedError(error)) {
-        throw error;
-      }
-    }
-  }
-}
-
 export function toNativeRoutingId(routingId: unknown): unknown {
   if (typeof routingId === 'string') return zlink.RoutingId.from(routingId);
   const toHex = (routingId as { readonly toHex?: unknown } | null)?.toHex;

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

@@ -1,3 +1,4 @@
+import { bindingRequestReply } from './node-backend-adapter-support';
 import type { DealerSocket, Message, PubSocket } from '@zlink-systems/zlink';
 import { ZLinkConfigurationException } from '../../configuration';
 import { ZLinkSubmitStatus, type ZLinkSubmitResult } from '../../messaging/submission-result';
@@ -56,7 +57,8 @@ export class ZLinkDealerChannelClientTransport implements ZLinkChannelClientTran
     request: Message,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    metadata: ReadonlyMap<string, string> = EMPTY_METADATA
+    metadata: ReadonlyMap<string, string> = EMPTY_METADATA,
+    onAdmitted?: () => void
   ): Promise<TReply> {
     throwIfAborted(signal);
     const operation = runWithOutboundFlow(true, () =>
@@ -78,7 +80,15 @@ export class ZLinkDealerChannelClientTransport implements ZLinkChannelClientTran
     );
     if (timeoutMs !== undefined) operation.timeout(timeoutMs);
     const reply = await submitRequestOperation(
-      { submit: () => operation.submit().reply },
+      {
+        submit: () =>
+          bindingRequestReply(
+            operation.submit(),
+            timeoutMs === undefined ? undefined : performance.now() + timeoutMs,
+            undefined,
+            onAdmitted
+          )
+      },
       'channel request'
     );
     try {

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

@@ -10,15 +10,7 @@ import type { Context } from '@zlink-systems/zlink';
 export class ZLinkNodeMeshBackendAdapter implements ZLinkMeshBackendAdapter {
   createMeshNode(
     context: ZLinkBackendContext,
-    options: {
-      readonly meshName: string;
-      readonly routingId?: string;
-      readonly receiveTimeoutMs?: number;
-      readonly trustProfile?: string;
-      readonly applicationJobQueue: import('../../application-jobs/contracts').ApplicationJobQueuePort;
-      readonly applicationJobReceiveFlowFailureSink?: (error: unknown) => void;
-      readonly peerAdmissionSealed?: () => boolean;
-    }
+    options: Parameters<ZLinkMeshBackendAdapter['createMeshNode']>[1]
   ): ZLinkBackendMeshNode {
     if (options.trustProfile !== undefined) {
       throw new Error(
@@ -37,7 +29,8 @@ export class ZLinkNodeMeshBackendAdapter implements ZLinkMeshBackendAdapter {
       new ZLinkNodeRawBindingPort(bindingContext, options.receiveTimeoutMs),
       options.applicationJobQueue,
       options.applicationJobReceiveFlowFailureSink,
-      options.peerAdmissionSealed
+      options.peerAdmissionSealed,
+      options.infrastructureTaskRunner
     );
   }
 }

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

@@ -22,10 +22,12 @@ import {
 import {
   translateBindingResultError,
   bindingRequestReply,
-  submitBindingAsyncSend
+  submitBindingAsyncSend,
+  submitBindingSend
 } from './node-backend-adapter-support';
 import { isEndpointCloseIgnorableError } from './node-socket-backend-adapter';
 import { ZLinkNodeEventLoopPoller } from './node-event-loop-poller';
+import { ZLinkBufferMessage } from '../runtime-message';
 import type {
   ZLinkRawBindingPort,
   ZLinkRawDealerPort,
@@ -171,13 +173,6 @@ abstract class NodeRawSocketPort<TSocket extends Socket> implements ZLinkRawSock
     this.endpoints.delete(`connect\0${endpoint}`);
   }
 
-  setReceiveFlowState(state: 'running' | 'paused'): void {
-    this.requireOpen();
-    this.socket.setReceiveFlowState(
-      state === 'paused' ? ReceiveFlowState.PAUSED : ReceiveFlowState.RUNNING
-    );
-  }
-
   monitor(): ZLinkRawMonitorPort {
     this.requireOpen();
     const nativeMonitor = this.socket.monitorOpen();
@@ -232,13 +227,57 @@ abstract class NodeRawSocketPort<TSocket extends Socket> implements ZLinkRawSock
 
 class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLinkRawRouterPort {
   private nextIncomingRequestSequence = 1n;
+  private readonly routingIds = new Map<string, BindingRoutingId>();
+  private readonly nextRequestSequence = () => {
+    const current = this.nextIncomingRequestSequence;
+    this.nextIncomingRequestSequence =
+      current === BigInt(Number.MAX_SAFE_INTEGER) ? 1n : current + 1n;
+    return current;
+  };
+  private readonly replyParts = (
+    targetRid: string | Uint8Array,
+    replyToken: unknown,
+    parts: readonly Uint8Array[]
+  ) => {
+    appendReplyParts(
+      this.socket.reply(
+        this.preparedRoutingId(targetRid),
+        replyToken as Parameters<RouterSocket['reply']>[1]
+      ),
+      parts
+    ).submit();
+  };
+
+  private preparedRoutingId(routingId: string | Uint8Array): BindingRoutingId {
+    if (typeof routingId !== 'string') return bindingRoutingId(routingId);
+    let prepared = this.routingIds.get(routingId);
+    if (prepared === undefined)
+      this.routingIds.set(routingId, (prepared = bindingRoutingId(routingId)));
+    return prepared;
+  }
+
+  override close(): void {
+    try {
+      super.close();
+    } finally {
+      this.routingIds.clear();
+    }
+  }
+
+  setReceiveFlowState(state: 'running' | 'paused'): void {
+    this.requireOpen();
+    this.socket.setReceiveFlowState(
+      state === 'paused' ? ReceiveFlowState.PAUSED : ReceiveFlowState.RUNNING
+    );
+  }
+
   disconnectRid(routingId: string): void {
     this.requireOpen();
     (
       this.socket as RouterSocket & {
         disconnectRid(value: BindingRoutingId): void;
       }
-    ).disconnectRid(bindingRoutingId(routingId));
+    ).disconnectRid(this.preparedRoutingId(routingId));
   }
 
   constructor(socket: RouterSocket, receiveTimeoutMs?: number) {
@@ -258,39 +297,47 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
 
   setRoutingId(routingId: string): void {
     this.requireOpen();
-    this.socket.setRoutingId(bindingRoutingId(routingId));
+    this.socket.setRoutingId(this.preparedRoutingId(routingId));
   }
 
   connectToRoutingId(routingId: string, endpoint: string): void {
     this.requireOpen();
-    this.socket.options.setConnectRoutingId(bindingRoutingId(routingId));
+    this.socket.options.setConnectRoutingId(this.preparedRoutingId(routingId));
     this.connect(endpoint);
   }
 
   send(targetRid: string, parts: readonly Uint8Array[]): Promise<void> {
     this.requireOpen();
     requireParts(parts);
-    return submitBindingAsyncSend(this.socket.send(bindingRoutingId(targetRid)), parts);
+    return submitBindingAsyncSend(this.socket.send(this.preparedRoutingId(targetRid)), parts);
+  }
+
+  submitSend(targetRid: string, parts: readonly Uint8Array[]) {
+    this.requireOpen();
+    requireParts(parts);
+    return submitBindingSend(this.socket.send(this.preparedRoutingId(targetRid)), parts);
   }
 
   async request(
     targetRid: string,
     parts: readonly Uint8Array[],
-    timeoutMs: number
+    timeoutMs: number,
+    recordReceived?: () => void,
+    onAdmitted?: () => void
   ): Promise<readonly Buffer[]> {
     this.requireOpen();
     const deadlineMs = performance.now() + timeoutMs;
     let submission: ReturnType<RequestSubmitOperation['submit']>;
     try {
-      submission = appendRequestParts(this.socket.request(bindingRoutingId(targetRid)), parts)
+      submission = appendRequestParts(this.socket.request(this.preparedRoutingId(targetRid)), parts)
         .timeout(timeoutMs)
         .submit();
     } catch (error) {
       throw translateBindingResultError(error, 'submit');
     }
     try {
-      const replies = await bindingRequestReply(submission, deadlineMs);
-      return copyAndClose(replies);
+      const replies = await bindingRequestReply(submission, deadlineMs, recordReceived, onAdmitted);
+      return retainAndClose(replies);
     } catch (error) {
       throw translateBindingResultError(error, 'completion');
     }
@@ -306,22 +353,7 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
 
   receive(dontWait = false): ZLinkRawReceivedRecord | undefined {
     this.requireOpen();
-    return receiveRecord(
-      this.socket,
-      dontWait,
-      () => {
-        const current = this.nextIncomingRequestSequence;
-        this.nextIncomingRequestSequence =
-          current === BigInt(Number.MAX_SAFE_INTEGER) ? 1n : current + 1n;
-        return current;
-      },
-      (targetRid, replyToken, parts) => {
-        appendReplyParts(
-          this.socket.reply(bindingRoutingId(targetRid), replyToken),
-          parts
-        ).submit();
-      }
-    );
+    return receiveRecord(this.socket, dontWait, this.nextRequestSequence, this.replyParts);
   }
 }
 
@@ -341,7 +373,11 @@ class NodeRawDealerPort extends NodeRawSocketPort<DealerSocket> implements ZLink
     return submitBindingAsyncSend(this.socket.send(), parts);
   }
 
-  async request(parts: readonly Uint8Array[], timeoutMs: number): Promise<readonly Buffer[]> {
+  async request(
+    parts: readonly Uint8Array[],
+    timeoutMs: number,
+    onAdmitted?: () => void
+  ): Promise<readonly Buffer[]> {
     this.requireOpen();
     const deadlineMs = performance.now() + timeoutMs;
     let submission: ReturnType<RequestSubmitOperation['submit']>;
@@ -351,8 +387,8 @@ class NodeRawDealerPort extends NodeRawSocketPort<DealerSocket> implements ZLink
       throw translateBindingResultError(error, 'submit');
     }
     try {
-      const replies = await bindingRequestReply(submission, deadlineMs);
-      return copyAndClose(replies);
+      const replies = await bindingRequestReply(submission, deadlineMs, undefined, onAdmitted);
+      return retainAndClose(replies);
     } catch (error) {
       throw translateBindingResultError(error, 'completion');
     }
@@ -484,9 +520,9 @@ function receiveRecord(
   }
 }
 
-function copyAndClose(messages: readonly Message[]): readonly Buffer[] {
+function retainAndClose(messages: readonly Message[]): readonly Buffer[] {
   try {
-    return messages.map((message) => message.toBytes());
+    return messages.map((message) => ZLinkBufferMessage.retainPayload(message));
   } finally {
     for (const message of messages) message.close();
   }