@zlink-systems/framework 0.30.1 → 0.30.2

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

@@ -330,9 +330,9 @@ export function wrapSocket<T extends { close(): void }>(
       );
     },
     disconnectPeer(routingId: unknown): void {
-      disconnectStreamPeer(
+      disconnectSocketPeer(
         nativeInstance as T & { disconnectRid(value: unknown): void },
-        routingId
+        toNativeRoutingId(routingId)
       );
     },
     async bindActor(
@@ -376,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/channels/channel-clients.ts

@@ -177,8 +177,14 @@ interface PreparedNodeSend {
   ) => 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,
@@ -207,20 +213,31 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
   }
 
   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,
+            timeoutMs,
+            signal,
+            metadata,
+            onAdmitted
+          )
+      };
+      targets.set(targetNodeRid, prepared);
+    }
     return new DefaultZLinkRequestCall(
-      () => this.requireMesh(meshName),
-      (packetName, timeoutMs, metadata, signal, onAdmitted) =>
-        this.requireTransport().request(
-          meshName,
-          targetNodeRid,
-          packetName,
-          request,
-          timeoutMs,
-          signal,
-          metadata,
-          onAdmitted
-        ),
-      this.defaultRequestTimeout(meshName)
+      prepared.validate,
+      prepared.submit,
+      this.defaultRequestTimeout(meshName),
+      request
     );
   }
 
@@ -504,21 +521,26 @@ function normalizeSubmitResult(
     : (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 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,
-      onAdmitted?: () => void
-    ) => Promise<TReply>,
-    private readonly defaultRequestTimeoutMs?: number
+    private readonly submitter: ZLinkRequestSubmitter,
+    private readonly defaultRequestTimeoutMs?: number,
+    private readonly message?: unknown
   ) {}
 
   metadata(key: string, value: string): this;
@@ -549,7 +571,8 @@ class DefaultZLinkRequestCall implements ZLinkChannelRequestCall {
         this.timeoutMs ?? this.defaultRequestTimeoutMs,
         this.selectedMetadata === undefined ? EMPTY_CALL_METADATA : new Map(this.selectedMetadata),
         signal,
-        onAdmitted
+        onAdmitted,
+        this.message
       );
     });
   }
@@ -562,9 +585,11 @@ class DefaultZLinkRequestCall implements ZLinkChannelRequestCall {
       undefined,
       this.timeoutMs ?? this.defaultRequestTimeoutMs,
       this.selectedMetadata === undefined ? EMPTY_CALL_METADATA : new Map(this.selectedMetadata),
-      signal
+      signal,
+      undefined,
+      this.message
     );
-    return turn.yieldPromise(pending);
+    return turn.yieldFrameworkPromise(pending);
   }
 }
 

package/src/runtime/channels/channel-dispatch-pipeline.ts

@@ -1,8 +1,10 @@
+import type { ZLinkMeshDispatchAdmission } from '../admission';
 import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException,
   internalFrameworkErrorKind
 } from '../framework-errors-internal';
+import { isPromiseLike } from '../abort';
 import type {
   ZLinkMessageContext,
   ZLinkHandlerFilter,
@@ -65,7 +67,7 @@ interface ZLinkOneWayDispatch<TContext extends ZLinkMessageContext> {
   readonly signal?: AbortSignal;
 }
 
-interface ZLinkRequestDispatch<TContext extends ZLinkMessageContext> {
+export interface ZLinkRequestDispatch<TContext extends ZLinkMessageContext> {
   readonly fields: ZLinkChannelDispatchFields;
   readonly envelope: ZLinkChannelEnvelope;
   readonly codecs?: ZLinkChannelEnvelopeCodecRegistry;
@@ -86,158 +88,205 @@ export class ZLinkChannelDispatchPipeline {
     this.unhandled = options.unhandled ?? DEFAULT_UNHANDLED_DISPATCH;
   }
 
-  async dispatchOneWay<TContext extends ZLinkMessageContext>(
-    dispatch: ZLinkOneWayDispatch<TContext>
-  ): Promise<void> {
+  /**
+   * Runs the handler in the caller's execution turn. A synchronous handler
+   * completes here; an asynchronous handler adds exactly one continuation
+   * for its terminal trace or error record.
+   */
+  dispatchOneWay<TContext extends ZLinkMessageContext>(
+    dispatch: ZLinkOneWayDispatch<TContext>,
+    admit?: ZLinkMeshDispatchAdmission
+  ): void | Promise<void> {
+    if (admit !== undefined) {
+      const pipeline = this;
+      const record = dispatch;
+      return admit(
+        () => pipeline.dispatchOneWay(record),
+        (error) => pipeline.failOneWay(record.fields, error)
+      );
+    }
     this.trace(ZLinkMessageFlowOutcome.Received, dispatch.fields);
     this.trace(ZLinkMessageFlowOutcome.Admitted, dispatch.fields);
-    if (dispatch.handler === undefined) {
-      const action =
-        dispatch.fields.messageKind === ZLinkDispatchMessageKind.Publish
-          ? this.unhandled.publish
-          : this.unhandled.send;
-      this.report(
-        dispatch.fields,
-        ZLinkDispatchErrorReason.HandlerMissing,
-        ZLinkDispatchErrorAction.Drop
-      );
-      this.applyOneWayUnhandled(action, dispatch.fields);
+    if (dispatch.handler === undefined) return this.dispatchMissingOneWay(dispatch.fields);
+    let invocation: unknown;
+    try {
+      invocation = this.invokeInFlow(dispatch, dispatch.handler);
+    } catch (error) {
+      this.failOneWay(dispatch.fields, error);
+      return;
+    }
+    if (!isPromiseLike(invocation)) {
+      this.completeOneWay(dispatch.fields, invocation);
       return;
     }
+    return Promise.resolve(invocation).then(
+      (value) => this.completeOneWay(dispatch.fields, value),
+      (error: unknown) => this.failOneWay(dispatch.fields, error)
+    );
+  }
 
-    try {
-      const flow = createInboundFlow(
-        dispatch.fields.flowId,
-        dispatch.fields.flowOrigin,
-        this.options.dispatchErrors.flow.flowCreationEnabled(),
-        undefined
-      );
-      const invocation = await (flow === undefined
-        ? this.invoke(
-            dispatch.envelope,
-            dispatch.codecs,
-            dispatch.handler,
-            dispatch.context,
-            dispatch.fields,
-            dispatch.signal
-          )
-        : runWithFlow(flow, () =>
-            this.invoke(
-              dispatch.envelope,
-              dispatch.codecs,
-              dispatch.handler!,
-              dispatch.context,
-              dispatch.fields,
-              dispatch.signal
-            )
-          ));
+  private async dispatchMissingOneWay(fields: ZLinkChannelDispatchFields): Promise<void> {
+    const action =
+      fields.messageKind === ZLinkDispatchMessageKind.Publish
+        ? this.unhandled.publish
+        : this.unhandled.send;
+    this.report(fields, ZLinkDispatchErrorReason.HandlerMissing, ZLinkDispatchErrorAction.Drop);
+    this.applyOneWayUnhandled(action, fields);
+  }
 
-      if (invocation !== HANDLER_FILTER_REJECTED) {
-        this.trace(ZLinkMessageFlowOutcome.Completed, dispatch.fields);
-      }
+  private completeOneWay(fields: ZLinkChannelDispatchFields, invocation: unknown): void {
+    if (invocation !== HANDLER_FILTER_REJECTED) {
+      this.trace(ZLinkMessageFlowOutcome.Completed, fields);
+    }
+  }
+
+  private failOneWay(fields: ZLinkChannelDispatchFields, error: unknown): void {
+    this.report(fields, this.failureReason(error), ZLinkDispatchErrorAction.Drop, error);
+  }
+
+  /**
+   * Runs the handler in the caller's execution turn and writes its reply in
+   * the same turn when the handler completes synchronously. An asynchronous
+   * handler adds exactly one continuation that writes the reply.
+   */
+  dispatchRequest<TContext extends ZLinkMessageContext>(
+    dispatch: ZLinkRequestDispatch<TContext>,
+    admit?: ZLinkMeshDispatchAdmission
+  ): void | Promise<void> {
+    if (admit !== undefined) {
+      const pipeline = this;
+      const record = dispatch;
+      return admit(
+        () => pipeline.dispatchRequest(record),
+        (error) => pipeline.failRequest(record, error)
+      );
+    }
+    this.trace(ZLinkMessageFlowOutcome.Received, dispatch.fields);
+    this.trace(ZLinkMessageFlowOutcome.Admitted, dispatch.fields);
+    if (dispatch.handler === undefined) return this.dispatchMissingRequest(dispatch);
+    let invocation: unknown;
+    try {
+      invocation = this.invokeInFlow(dispatch, dispatch.handler);
     } catch (error) {
-      this.report(dispatch.fields, this.failureReason(error), ZLinkDispatchErrorAction.Drop, error);
+      return this.failRequest(dispatch, error);
     }
+    if (!isPromiseLike(invocation)) return this.completeRequest(dispatch, invocation);
+    return Promise.resolve(invocation).then(
+      (value) => this.completeRequest(dispatch, value),
+      (error: unknown) => this.failRequest(dispatch, error)
+    );
   }
 
-  async dispatchRequest<TContext extends ZLinkMessageContext>(
+  private async dispatchMissingRequest<TContext extends ZLinkMessageContext>(
     dispatch: ZLinkRequestDispatch<TContext>
   ): Promise<void> {
-    this.trace(ZLinkMessageFlowOutcome.Received, dispatch.fields);
-    this.trace(ZLinkMessageFlowOutcome.Admitted, dispatch.fields);
-    if (dispatch.handler === undefined) {
-      const missing = createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.HandlerNotFound,
-        dispatch.missingHandlerMessage
-      );
-      if (this.unhandled.request === ZLinkUnhandledDispatchAction.ReplyError) {
-        await dispatch.writeError(missing);
-      }
-      this.report(
-        dispatch.fields,
-        ZLinkDispatchErrorReason.HandlerMissing,
-        this.unhandled.request === ZLinkUnhandledDispatchAction.ReplyError
-          ? ZLinkDispatchErrorAction.ReplyError
-          : ZLinkDispatchErrorAction.Drop
-      );
-      if (this.unhandled.request === ZLinkUnhandledDispatchAction.Throw) {
-        throw missing;
-      }
-      return;
+    const missing = createInternalFrameworkException(
+      ZLinkFrameworkInternalErrorKind.HandlerNotFound,
+      dispatch.missingHandlerMessage
+    );
+    if (this.unhandled.request === ZLinkUnhandledDispatchAction.ReplyError) {
+      await dispatch.writeError(missing);
+    }
+    this.report(
+      dispatch.fields,
+      ZLinkDispatchErrorReason.HandlerMissing,
+      this.unhandled.request === ZLinkUnhandledDispatchAction.ReplyError
+        ? ZLinkDispatchErrorAction.ReplyError
+        : ZLinkDispatchErrorAction.Drop
+    );
+    if (this.unhandled.request === ZLinkUnhandledDispatchAction.Throw) {
+      throw missing;
     }
+  }
 
-    let reply: unknown;
-    try {
-      const flow = createInboundFlow(
-        dispatch.fields.flowId,
-        dispatch.fields.flowOrigin,
-        this.options.dispatchErrors.flow.flowCreationEnabled(),
-        undefined
-      );
-      const invocation = await (flow === undefined
-        ? this.invoke(
+  private invokeInFlow<TContext extends ZLinkMessageContext, TResult>(
+    dispatch: ZLinkOneWayDispatch<TContext> | ZLinkRequestDispatch<TContext>,
+    handler: ZLinkChannelDispatchHandler<TContext, TResult>
+  ): unknown {
+    const flow = createInboundFlow(
+      dispatch.fields.flowId,
+      dispatch.fields.flowOrigin,
+      this.options.dispatchErrors.flow.flowCreationEnabled(),
+      undefined
+    );
+    return flow === undefined
+      ? this.invoke(
+          dispatch.envelope,
+          dispatch.codecs,
+          handler,
+          dispatch.context,
+          dispatch.fields,
+          dispatch.signal
+        )
+      : runWithFlow(flow, () =>
+          this.invoke(
             dispatch.envelope,
             dispatch.codecs,
-            dispatch.handler,
+            handler,
             dispatch.context,
             dispatch.fields,
             dispatch.signal
           )
-        : runWithFlow(flow, () =>
-            this.invoke(
-              dispatch.envelope,
-              dispatch.codecs,
-              dispatch.handler!,
-              dispatch.context,
-              dispatch.fields,
-              dispatch.signal
-            )
-          ));
+        );
+  }
 
-      if (invocation === HANDLER_FILTER_REJECTED) {
-        throw createInternalFrameworkException(
+  private completeRequest<TContext extends ZLinkMessageContext>(
+    dispatch: ZLinkRequestDispatch<TContext>,
+    invocation: unknown
+  ): void | Promise<void> {
+    if (invocation === HANDLER_FILTER_REJECTED) {
+      return this.failRequest(
+        dispatch,
+        createInternalFrameworkException(
           ZLinkFrameworkInternalErrorKind.RequestRejected,
           `A handler filter rejected '${this.options.channelName}:${dispatch.fields.packetName}'.`
-        );
-      }
-      reply = invocation;
-    } catch (error) {
-      try {
-        await dispatch.writeError(error);
-      } catch (replyError) {
-        // Spec 26 §3.1: a failed reply write means the reply delivery path is
-        // gone; `unexpected_reply` names a surplus/late reply instead.
-        this.report(
-          dispatch.fields,
-          ZLinkDispatchErrorReason.ReplyPathMissing,
-          ZLinkDispatchErrorAction.Drop,
-          replyError
-        );
-        return;
-      }
-      this.report(
-        dispatch.fields,
-        this.failureReason(error),
-        ZLinkDispatchErrorAction.ReplyError,
-        error
+        )
       );
+    }
+    let written: void | Promise<void>;
+    try {
+      written = dispatch.writeReply(invocation);
+    } catch (error) {
+      this.replyPathMissing(dispatch.fields, error);
+      return;
+    }
+    if (written === undefined) {
+      this.trace(ZLinkMessageFlowOutcome.Replied, dispatch.fields);
       return;
     }
+    return written.then(
+      () => this.trace(ZLinkMessageFlowOutcome.Replied, dispatch.fields),
+      (error: unknown) => this.replyPathMissing(dispatch.fields, error)
+    );
+  }
 
+  private replyPathMissing(fields: ZLinkChannelDispatchFields, error: unknown): void {
+    // Spec 26 §3.1: a failed reply write means the reply delivery path is
+    // gone; `unexpected_reply` names a surplus/late reply instead.
+    this.report(
+      fields,
+      ZLinkDispatchErrorReason.ReplyPathMissing,
+      ZLinkDispatchErrorAction.Drop,
+      error
+    );
+  }
+
+  private async failRequest<TContext extends ZLinkMessageContext>(
+    dispatch: ZLinkRequestDispatch<TContext>,
+    error: unknown
+  ): Promise<void> {
     try {
-      const written = dispatch.writeReply(reply);
-      if (written !== undefined) await written;
-      this.trace(ZLinkMessageFlowOutcome.Replied, dispatch.fields);
-    } catch (error) {
-      // Spec 26 §3.1: a failed reply write means the reply delivery path is
-      // gone; `unexpected_reply` names a surplus/late reply instead.
-      this.report(
-        dispatch.fields,
-        ZLinkDispatchErrorReason.ReplyPathMissing,
-        ZLinkDispatchErrorAction.Drop,
-        error
-      );
+      await dispatch.writeError(error);
+    } catch (replyError) {
+      this.replyPathMissing(dispatch.fields, replyError);
+      return;
     }
+    this.report(
+      dispatch.fields,
+      this.failureReason(error),
+      ZLinkDispatchErrorAction.ReplyError,
+      error
+    );
   }
 
   dropMissingReplyPath(fields: ZLinkChannelDispatchFields): void {