@zlink-systems/framework 0.30.0 → 0.30.2

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

@@ -25,8 +25,10 @@ import {
   submitBindingAsyncSend,
   submitBindingSend
 } from './node-backend-adapter-support';
-import { isEndpointCloseIgnorableError } from './node-socket-backend-adapter';
+import { disconnectSocketPeer, isEndpointCloseIgnorableError } from './node-socket-backend-adapter';
+import { SubmitResult } from '../runtime-values';
 import { ZLinkNodeEventLoopPoller } from './node-event-loop-poller';
+import { ZLinkBufferMessage } from '../runtime-message';
 import type {
   ZLinkRawBindingPort,
   ZLinkRawDealerPort,
@@ -226,6 +228,38 @@ 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: BindingRoutingId,
+    replyToken: ReplyToken,
+    parts: readonly Uint8Array[]
+  ) => {
+    // The receive record keeps the binding RoutingId it was delivered with,
+    // so the reply addresses that route without rebuilding the identity.
+    appendReplyParts(this.socket.reply(targetRid, replyToken), 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();
@@ -236,11 +270,7 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
 
   disconnectRid(routingId: string): void {
     this.requireOpen();
-    (
-      this.socket as RouterSocket & {
-        disconnectRid(value: BindingRoutingId): void;
-      }
-    ).disconnectRid(bindingRoutingId(routingId));
+    disconnectSocketPeer(this.socket, this.preparedRoutingId(routingId));
   }
 
   constructor(socket: RouterSocket, receiveTimeoutMs?: number) {
@@ -260,49 +290,45 @@ 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(bindingRoutingId(targetRid)), parts);
+    return submitBindingSend(this.socket.send(this.preparedRoutingId(targetRid)), parts);
   }
 
-  async request(
+  request(
     targetRid: string,
     parts: readonly Uint8Array[],
     timeoutMs: number,
-    recordReceived?: () => void
+    recordReceived?: () => void,
+    onAdmitted?: () => void
   ): Promise<readonly Buffer[]> {
-    this.requireOpen();
-    const deadlineMs = performance.now() + timeoutMs;
     let submission: ReturnType<RequestSubmitOperation['submit']>;
+    const deadlineMs = performance.now() + timeoutMs;
     try {
-      submission = appendRequestParts(this.socket.request(bindingRoutingId(targetRid)), parts)
+      this.requireOpen();
+      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, recordReceived);
-      return copyAndClose(replies);
-    } catch (error) {
-      throw translateBindingResultError(error, 'completion');
+      return Promise.reject(translateBindingResultError(error, 'submit'));
     }
+    return requestReply(submission, deadlineMs, recordReceived, onAdmitted);
   }
 
   routesSnapshot(): readonly ZLinkRawRouterRoute[] {
@@ -315,22 +341,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);
   }
 }
 
@@ -350,21 +361,20 @@ class NodeRawDealerPort extends NodeRawSocketPort<DealerSocket> implements ZLink
     return submitBindingAsyncSend(this.socket.send(), parts);
   }
 
-  async request(parts: readonly Uint8Array[], timeoutMs: number): Promise<readonly Buffer[]> {
-    this.requireOpen();
-    const deadlineMs = performance.now() + timeoutMs;
+  request(
+    parts: readonly Uint8Array[],
+    timeoutMs: number,
+    onAdmitted?: () => void
+  ): Promise<readonly Buffer[]> {
     let submission: ReturnType<RequestSubmitOperation['submit']>;
+    const deadlineMs = performance.now() + timeoutMs;
     try {
+      this.requireOpen();
       submission = appendRequestParts(this.socket.request(), parts).timeout(timeoutMs).submit();
     } catch (error) {
-      throw translateBindingResultError(error, 'submit');
-    }
-    try {
-      const replies = await bindingRequestReply(submission, deadlineMs);
-      return copyAndClose(replies);
-    } catch (error) {
-      throw translateBindingResultError(error, 'completion');
+      return Promise.reject(translateBindingResultError(error, 'submit'));
     }
+    return requestReply(submission, deadlineMs, undefined, onAdmitted);
   }
 
   receive(dontWait = false): ZLinkRawReceivedRecord | undefined {
@@ -436,11 +446,61 @@ function requireParts(parts: readonly Uint8Array[]): [Uint8Array, ...Uint8Array[
 }
 
 type RawReceivedReply = (
-  targetRid: Uint8Array,
+  targetRid: BindingRoutingId,
   replyToken: ReplyToken,
   parts: readonly Uint8Array[]
 ) => void;
 
+const EMPTY_SOURCE_ROUTE = Buffer.alloc(0);
+
+/**
+ * One received binding record. The payload Buffers are the binding's own
+ * `data()` storage, retained under the runtime payload policy instead of a
+ * second Framework copy; closing the record releases the binding handles.
+ */
+class NodeRawReceivedRecord implements ZLinkRawReceivedRecord {
+  readonly sourceRid: string;
+  readonly sourceRoute: Uint8Array;
+  readonly routeGeneration: bigint;
+  readonly requestSeq?: bigint;
+  readonly reply?: (parts: readonly Uint8Array[]) => void;
+  readonly parts: readonly Buffer[];
+  private closed = false;
+
+  constructor(
+    private readonly received: Received,
+    nextRequestSequence: (() => bigint) | undefined,
+    reply: RawReceivedReply | undefined
+  ) {
+    const routingId = received.routingId;
+    this.sourceRid = routingId?.toString() ?? '';
+    this.sourceRoute = routingId?.toBytes() ?? EMPTY_SOURCE_ROUTE;
+    this.routeGeneration = received.routeGeneration;
+    const replyToken = received.replyToken;
+    if (replyToken !== null) {
+      this.requestSeq = nextRequestSequence?.();
+      if (reply === undefined) {
+        const operation = received.reply();
+        this.reply = (parts) => appendReplyParts(operation, parts).submit();
+      } else {
+        const target = routingId ?? bindingRoutingId(EMPTY_SOURCE_ROUTE);
+        this.reply = (parts) => reply(target, replyToken, parts);
+      }
+    }
+    const parts = received.parts;
+    const retained = new Array<Buffer>(parts.length);
+    for (let index = 0; index < parts.length; index++)
+      retained[index] = ZLinkBufferMessage.retainPayload(parts[index]!);
+    this.parts = retained;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.received.close();
+  }
+}
+
 function receiveRecord(
   socket: Pick<RouterSocket | DealerSocket, 'recv'>,
   dontWait: boolean,
@@ -452,50 +512,53 @@ function receiveRecord(
     received.close();
     return undefined;
   }
-  let closed = false;
   try {
-    const sourceRid = received.routingId?.toString() ?? '';
-    const sourceRoute = received.routingId?.toBytes() ?? Buffer.alloc(0);
-    const requestSeq = received.replyToken === null ? undefined : nextRequestSequence?.();
-    const replyToken = received.replyToken;
-    const receivedReply =
-      replyToken === null
-        ? undefined
-        : reply === undefined
-          ? received.reply()
-          : (parts: readonly Uint8Array[]) => reply(sourceRoute, replyToken, parts);
-    return {
-      sourceRid,
-      sourceRoute,
-      routeGeneration: received.routeGeneration,
-      ...(requestSeq === undefined ? {} : { requestSeq }),
-      ...(receivedReply === undefined
-        ? {}
-        : {
-            reply: (parts: readonly Uint8Array[]) => {
-              if (typeof receivedReply === 'function') {
-                receivedReply(parts);
-                return;
-              }
-              appendReplyParts(receivedReply, parts).submit();
-            }
-          }),
-      parts: received.parts.map((part) => part.toBytes()),
-      close: () => {
-        if (closed) return;
-        closed = true;
-        received.close();
-      }
-    };
+    return new NodeRawReceivedRecord(received, nextRequestSequence, reply);
   } catch (error) {
     received.close();
     throw error;
   }
 }
 
-function copyAndClose(messages: readonly Message[]): readonly Buffer[] {
+/**
+ * Continues once on the binding reply. Admission that completed at submit is
+ * confirmed in this turn; a backpressured submission keeps the admission
+ * wait that bounds it by the request deadline.
+ */
+function requestReply(
+  submission: ReturnType<RequestSubmitOperation['submit']>,
+  deadlineMs: number,
+  recordReceived: (() => void) | undefined,
+  onAdmitted: (() => void) | undefined
+): Promise<readonly Buffer[]> {
+  if (submission.result === SubmitResult.Backpressured) {
+    return bindingRequestReply(submission, deadlineMs, recordReceived, onAdmitted).then(
+      retainAndClose,
+      rejectCompletion
+    );
+  }
+  try {
+    onAdmitted?.();
+  } catch (error) {
+    return Promise.reject(translateBindingResultError(error, 'completion'));
+  }
+  return submission.reply.then((replies) => {
+    try {
+      recordReceived?.();
+      return retainAndClose(replies);
+    } catch (error) {
+      throw translateBindingResultError(error, 'completion');
+    }
+  }, rejectCompletion);
+}
+
+function rejectCompletion(error: unknown): never {
+  throw translateBindingResultError(error, 'completion');
+}
+
+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();
   }