@zlink-systems/framework 0.30.0 → 0.30.2

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

@@ -208,22 +208,34 @@ export function wrapSocket<T extends { close(): void }>(
     },
     request(...args: unknown[]): unknown {
       if (hasRoutedPeer) {
-        const [routingId, payload, timeoutMs] = args as [unknown, unknown, number | undefined];
+        const [routingId, payload, timeoutMs, onAdmitted] = args as [
+          unknown,
+          unknown,
+          number | undefined,
+          (() => void) | undefined
+        ];
         return submitBindingRequest(
           (
             nativeInstance as T & { request(routingId: unknown): ZLinkBindingRequestOperation }
           ).request(toNativeRoutingId(routingId)),
           payload,
-          timeoutMs
+          timeoutMs,
+          undefined,
+          onAdmitted
         );
       }
       if (hasRequest) {
-        const [payload, timeoutMs] = args as [unknown, number | undefined];
+        const [payload, timeoutMs, onAdmitted] = args as [
+          unknown,
+          number | undefined,
+          (() => void) | undefined
+        ];
         return submitBindingRequest(
           (nativeInstance as T & { request(): ZLinkBindingRequestOperation }).request(),
           payload,
           timeoutMs,
-          adapter.receiveAdmission?.recordReceived
+          adapter.receiveAdmission?.recordReceived,
+          onAdmitted
         );
       }
       throw new TypeError('Backend request requires a DEALER or ROUTER socket.');
@@ -302,7 +314,8 @@ export function wrapSocket<T extends { close(): void }>(
       targetRid: unknown,
       targetSpot: unknown,
       payload: unknown,
-      timeoutMs?: number
+      timeoutMs?: number,
+      onAdmitted?: () => void
     ): Promise<readonly unknown[]> {
       return submitBindingRequest(
         (
@@ -311,13 +324,15 @@ export function wrapSocket<T extends { close(): void }>(
           }
         ).requestToSpot(toNativeRoutingId(targetRid), toNativeRoutingId(targetSpot)),
         payload,
-        timeoutMs
+        timeoutMs,
+        undefined,
+        onAdmitted
       );
     },
     disconnectPeer(routingId: unknown): void {
-      disconnectStreamPeer(
+      disconnectSocketPeer(
         nativeInstance as T & { disconnectRid(value: unknown): void },
-        routingId
+        toNativeRoutingId(routingId)
       );
     },
     async bindActor(
@@ -361,15 +376,15 @@ export function nodeEventLoopPollerOf(socket: object): ZLinkNodeEventLoopPoller
   return poller;
 }
 
-export function disconnectStreamPeer(
+export function disconnectSocketPeer(
   socket: { disconnectRid(routingId: unknown): void },
   routingId: unknown
 ): void {
   try {
-    socket.disconnectRid(toNativeRoutingId(routingId));
+    socket.disconnectRid(routingId);
   } catch (error) {
     // An absent RID has already completed the physical close. The existing
-    // session lifecycle still owns local cleanup and unbind.
+    // logical lifecycle still owns local cleanup and unbind.
     if (!isBindingNotFound(error)) throw error;
   }
 }

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

@@ -67,7 +67,8 @@ export interface ZLinkRawRouterPort extends ZLinkRawSocketPort {
     targetRid: string,
     parts: readonly Uint8Array[],
     timeoutMs: number,
-    recordReceived?: () => void
+    recordReceived?: () => void,
+    onAdmitted?: () => void
   ): Promise<readonly Buffer[]>;
   receive(dontWait?: boolean): ZLinkRawReceivedRecord | undefined;
   /** The selected route of every RID. The socket's one route observer calls it. */
@@ -77,7 +78,11 @@ export interface ZLinkRawRouterPort extends ZLinkRawSocketPort {
 export interface ZLinkRawDealerPort extends ZLinkRawSocketPort {
   setRoutingId(routingId: string): void;
   send(parts: readonly Uint8Array[]): Promise<void>;
-  request(parts: readonly Uint8Array[], timeoutMs: number): Promise<readonly Buffer[]>;
+  request(
+    parts: readonly Uint8Array[],
+    timeoutMs: number,
+    onAdmitted?: () => void
+  ): Promise<readonly Buffer[]>;
   receive(dontWait?: boolean): ZLinkRawReceivedRecord | undefined;
 }
 

package/src/runtime/backend/runtime-message.ts

@@ -17,6 +17,12 @@ export class ZLinkBufferMessage implements Message {
     return new ZLinkBufferMessage(bytes);
   }
 
+  static retainPayload(message: Message): Buffer {
+    // Binding data() Buffers retain their storage after the message handle closes.
+    // Preserve that ownership at runtime boundaries without copying the payload.
+    return message.data();
+  }
+
   data(): Buffer {
     return this.bytes;
   }

package/src/runtime/backend/runtime-values.ts

@@ -39,6 +39,7 @@ export type SubmitResult = (typeof SubmitResult)[keyof typeof SubmitResult];
 export type ZLinkBackendSendFlags = number;
 export type ZLinkBackendRecvFlags = number;
 export const ZLINK_BACKEND_SEND_NONE: ZLinkBackendSendFlags = 0;
+export const ZLINK_BACKEND_SEND_DONT_WAIT: ZLinkBackendSendFlags = 1;
 export const ZLINK_BACKEND_RECV_DONT_WAIT: ZLinkBackendRecvFlags = 1;
 
 export class ZLinkBackendResultError extends Error {

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

@@ -1,4 +1,6 @@
 import { DEFAULT_REQUEST_TIMEOUT_MS } from '../../contracts/Configuration/Registration';
+import { createZLinkRequest } from '../messaging/request-result';
+import type { ZLinkRequest } from '../../contracts/Handlers/Attributes';
 import type {
   ZLinkChannelClient,
   ZLinkChannelRequestCall,
@@ -23,6 +25,7 @@ import {
   requireClassicFanoutCompletion,
   throwAlreadySubmitted,
   ZLinkSubmitStatus,
+  submittedResult,
   type ZLinkSubmitResult
 } from '../messaging/submission-result';
 import type {
@@ -165,7 +168,23 @@ export class DefaultZLinkFanoutClient implements ZLinkFanoutClient {
   }
 }
 
+interface PreparedNodeSend {
+  readonly validate: () => void;
+  readonly submit: (
+    packetName: string | undefined,
+    metadata: ReadonlyMap<string, string>,
+    message?: unknown
+  ) => ZLinkSubmitResult | Promise<ZLinkSubmitResult>;
+}
+
+interface PreparedNodeRequest {
+  readonly validate: () => void;
+  readonly submit: ZLinkRequestSubmitter;
+}
+
 export class DefaultZLinkRouteClient implements ZLinkRouteClient {
+  private readonly nodeSends = new Map<string, Map<string, PreparedNodeSend>>();
+  private readonly nodeRequests = new Map<string, Map<string, PreparedNodeRequest>>();
   constructor(
     private readonly registration: ZLinkFrameworkRegistration,
     private readonly transport?: ZLinkRouteClientTransport,
@@ -175,35 +194,50 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
   ) {}
 
   sendToNode(meshName: string, targetNodeRid: string, message: unknown): ZLinkSendCall {
-    return new DefaultZLinkSendCall(
-      () => this.requireMesh(meshName),
-      async (packetName, metadata) =>
-        normalizeSubmitResult(
-          await this.requireTransport().submit(
+    let targets = this.nodeSends.get(meshName);
+    if (targets === undefined) this.nodeSends.set(meshName, (targets = new Map()));
+    let prepared = targets.get(targetNodeRid);
+    if (prepared === undefined) {
+      prepared = {
+        validate: () => {
+          this.requireMesh(meshName);
+        },
+        submit: (packetName, metadata, payload) =>
+          normalizeSubmitResult(
+            this.requireTransport().submit(meshName, targetNodeRid, packetName, payload, metadata)
+          )
+      };
+      targets.set(targetNodeRid, prepared);
+    }
+    return new DefaultZLinkSendCall(prepared.validate, prepared.submit, message);
+  }
+
+  requestToNode(meshName: string, targetNodeRid: string, request: unknown): ZLinkRequestCall {
+    let targets = this.nodeRequests.get(meshName);
+    if (targets === undefined) this.nodeRequests.set(meshName, (targets = new Map()));
+    let prepared = targets.get(targetNodeRid);
+    if (prepared === undefined) {
+      prepared = {
+        validate: () => this.requireMesh(meshName),
+        submit: (packetName, timeoutMs, metadata, signal, onAdmitted, message) =>
+          this.requireTransport().request(
             meshName,
             targetNodeRid,
             packetName,
             message,
-            metadata
+            timeoutMs,
+            signal,
+            metadata,
+            onAdmitted
           )
-        )
-    );
-  }
-
-  requestToNode(meshName: string, targetNodeRid: string, request: unknown): ZLinkRequestCall {
+      };
+      targets.set(targetNodeRid, prepared);
+    }
     return new DefaultZLinkRequestCall(
-      () => this.requireMesh(meshName),
-      (packetName, timeoutMs, metadata, signal) =>
-        this.requireTransport().request(
-          meshName,
-          targetNodeRid,
-          packetName,
-          request,
-          timeoutMs,
-          signal,
-          metadata
-        ),
-      this.defaultRequestTimeout(meshName)
+      prepared.validate,
+      prepared.submit,
+      this.defaultRequestTimeout(meshName),
+      request
     );
   }
 
@@ -233,7 +267,7 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
   requestToChannel(channelName: string, request: unknown): ZLinkChannelRequestCall {
     return new DefaultZLinkRequestCall(
       () => this.requireChannelRoute(channelName),
-      (packetName, timeoutMs, metadata, signal) => {
+      (packetName, timeoutMs, metadata, signal, onAdmitted) => {
         const route = this.requireChannelRoute(channelName);
         if (route.kind === 'route-mesh') {
           return this.requireTransport().requestToChannel(
@@ -243,7 +277,8 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
             request,
             timeoutMs,
             signal,
-            metadata
+            metadata,
+            onAdmitted
           );
         }
         return this.requireChannelTransport().request(
@@ -252,7 +287,8 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
           request,
           timeoutMs,
           signal,
-          metadata
+          metadata,
+          onAdmitted
         );
       },
       this.defaultRequestTimeoutForChannel(channelName)
@@ -279,11 +315,12 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
       () => {
         this.requireSpotTransport();
       },
-      (_packetName, timeoutMs, metadata, signal) =>
+      (_packetName, timeoutMs, metadata, signal, onAdmitted) =>
         requestToSpotHandle(this.requireSpotTransport(), spot, request, {
           timeoutMs,
           signal,
           metadata,
+          onAdmitted,
           spotRouterChannelIdForMesh: this.spotRouterChannelIdForMesh
         }),
       this.registration.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
@@ -416,21 +453,24 @@ export class DefaultZLinkSpotPublisherClient implements ZLinkSpotPublisherClient
 }
 
 class DefaultZLinkSendCall implements ZLinkSendCall {
-  private readonly selectedMetadata = new Map<string, string>();
+  private selectedMetadata?: Map<string, string>;
   private executed = false;
 
   constructor(
     private readonly validate: () => void,
     private readonly submitter: (
       packetName: string | undefined,
-      metadata: ReadonlyMap<string, string>
-    ) => Promise<ZLinkSubmitResult>
+      metadata: ReadonlyMap<string, string>,
+      message?: unknown
+    ) => ZLinkSubmitResult | Promise<ZLinkSubmitResult>,
+    private readonly message?: unknown
   ) {}
 
   metadata(key: string, value: string): this;
   metadata(metadata: ZLinkMessageMetadata): this;
   metadata(keyOrMetadata: string | ZLinkMessageMetadata, value?: string): this {
     ensureNotExecuted(this.executed);
+    this.selectedMetadata ??= new Map<string, string>();
     if (typeof keyOrMetadata === 'string') {
       this.selectedMetadata.set(keyOrMetadata, value!);
     } else {
@@ -441,12 +481,22 @@ class DefaultZLinkSendCall implements ZLinkSendCall {
     return this;
   }
 
-  async submit(): Promise<void> {
-    ensureNotExecuted(this.executed);
-    this.validate();
-    this.executed = true;
-    const result = await this.submitter(undefined, new Map(this.selectedMetadata));
-    requireOneWayCompletion(result, 'One-way send');
+  submit(): Promise<void> {
+    try {
+      ensureNotExecuted(this.executed);
+      this.validate();
+      this.executed = true;
+      const result = this.submitter(
+        undefined,
+        this.selectedMetadata ?? EMPTY_CALL_METADATA,
+        this.message
+      );
+      if (result instanceof Promise) return result.then(completeOneWaySend);
+      completeOneWaySend(result);
+      return completedOneWaySend;
+    } catch (error) {
+      return Promise.reject(error);
+    }
   }
 }
 
@@ -456,29 +506,47 @@ function ensureNotExecuted(executed: boolean): void {
   }
 }
 
-function normalizeSubmitResult(result: void | ZLinkSubmitResult): ZLinkSubmitResult {
-  return result ?? { status: ZLinkSubmitStatus.Submitted };
+const EMPTY_CALL_METADATA: ReadonlyMap<string, string> = new Map();
+const completedOneWaySend = Promise.resolve();
+
+function completeOneWaySend(result: ZLinkSubmitResult): void {
+  requireOneWayCompletion(result, 'One-way send');
+}
+
+function normalizeSubmitResult(
+  result: void | ZLinkSubmitResult | Promise<void | ZLinkSubmitResult>
+): ZLinkSubmitResult | Promise<ZLinkSubmitResult> {
+  return result instanceof Promise
+    ? result.then((value) => value ?? submittedResult)
+    : (result ?? submittedResult);
 }
 
+type ZLinkRequestSubmitter = <TReply>(
+  packetName: string | undefined,
+  timeoutMs: number | undefined,
+  metadata: ReadonlyMap<string, string>,
+  signal?: AbortSignal,
+  onAdmitted?: () => void,
+  message?: unknown
+) => Promise<TReply>;
+
 class DefaultZLinkRequestCall implements ZLinkChannelRequestCall {
   private timeoutMs?: number;
-  private readonly selectedMetadata = new Map<string, string>();
+  private selectedMetadata?: Map<string, string>;
   private readonly turn: ZLinkSpotSerialTurn | undefined = captureZLinkSpotSerialTurn();
 
+  /** `message` is the request payload a prepared submitter receives per call. */
   constructor(
     private readonly validate: () => void,
-    private readonly submitter: <TReply>(
-      packetName: string | undefined,
-      timeoutMs: number | undefined,
-      metadata: ReadonlyMap<string, string>,
-      signal?: AbortSignal
-    ) => Promise<TReply>,
-    private readonly defaultRequestTimeoutMs?: number
+    private readonly submitter: ZLinkRequestSubmitter,
+    private readonly defaultRequestTimeoutMs?: number,
+    private readonly message?: unknown
   ) {}
 
   metadata(key: string, value: string): this;
   metadata(metadata: ZLinkMessageMetadata): this;
   metadata(keyOrMetadata: string | ZLinkMessageMetadata, value?: string): this {
+    this.selectedMetadata ??= new Map<string, string>();
     if (typeof keyOrMetadata === 'string') {
       this.selectedMetadata.set(keyOrMetadata, value!);
     } else {
@@ -494,15 +562,19 @@ class DefaultZLinkRequestCall implements ZLinkChannelRequestCall {
     return this;
   }
 
-  async submit<TReply>(signal?: AbortSignal): Promise<TReply> {
-    throwIfAborted(signal);
-    this.validate();
-    return this.submitter<TReply>(
-      undefined,
-      this.timeoutMs ?? this.defaultRequestTimeoutMs,
-      new Map(this.selectedMetadata),
-      signal
-    );
+  submit<TReply>(signal?: AbortSignal): ZLinkRequest<TReply> {
+    return createZLinkRequest((onAdmitted) => {
+      throwIfAborted(signal);
+      this.validate();
+      return this.submitter<TReply>(
+        undefined,
+        this.timeoutMs ?? this.defaultRequestTimeoutMs,
+        this.selectedMetadata === undefined ? EMPTY_CALL_METADATA : new Map(this.selectedMetadata),
+        signal,
+        onAdmitted,
+        this.message
+      );
+    });
   }
 
   async yield<TReply>(signal?: AbortSignal): Promise<TReply> {
@@ -512,10 +584,12 @@ class DefaultZLinkRequestCall implements ZLinkChannelRequestCall {
     const pending = this.submitter<TReply>(
       undefined,
       this.timeoutMs ?? this.defaultRequestTimeoutMs,
-      new Map(this.selectedMetadata),
-      signal
+      this.selectedMetadata === undefined ? EMPTY_CALL_METADATA : new Map(this.selectedMetadata),
+      signal,
+      undefined,
+      this.message
     );
-    return turn.yieldPromise(pending);
+    return turn.yieldFrameworkPromise(pending);
   }
 }