@zlink-systems/framework 0.30.3 → 0.32.0

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

@@ -58,20 +58,24 @@ export async function submitRequestOperation(
   try {
     return await operation.submit();
   } catch (error) {
-    //  Spec 32-framework-error-model:81-92 — classify the backend request
-    //  terminal rather than collapsing every failure to Unavailable.
-    if (isZLinkBackendResultError(error) && error.operation === 'request') {
-      throw new ZLinkFrameworkException(
-        requestResultToPublicErrorKind(error.result),
-        `${label} failed with result ${error.result}.`,
-        error
-      );
-    }
-    throw createInternalFrameworkException(
-      ZLinkFrameworkInternalErrorKind.RouteNotConnected,
-      `${label} failed before a reply was received.`,
-      true,
+    throw mapRequestFailure(error, label);
+  }
+}
+
+export function mapRequestFailure(error: unknown, label: string): unknown {
+  //  Spec 32-framework-error-model:81-92 — classify the backend request
+  //  terminal rather than collapsing every failure to Unavailable.
+  if (isZLinkBackendResultError(error) && error.operation === 'request') {
+    return new ZLinkFrameworkException(
+      requestResultToPublicErrorKind(error.result),
+      `${label} failed with result ${error.result}.`,
       error
     );
   }
+  return createInternalFrameworkException(
+    ZLinkFrameworkInternalErrorKind.RouteNotConnected,
+    `${label} failed before a reply was received.`,
+    true,
+    error
+  );
 }

package/src/runtime/channels/channel-outbound-operations.ts

@@ -1,3 +1,5 @@
+import { RequestRuntime } from '../foundation/request-runtime';
+import type { PendingOperation } from '../foundation/operation-registry';
 import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException,
@@ -18,7 +20,7 @@ import {
   ZLinkDispatchErrorSurface,
   ZLinkDispatchMessageKind
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
-import { awaitWithAbort, throwIfAborted } from '../abort';
+import { throwIfAborted } from '../abort';
 import {
   closeMessages,
   decodeChannelReply,
@@ -36,10 +38,6 @@ import { ZLinkFrameworkErrorKind, ZLinkFrameworkException } from '../../contract
 import { ZLinkRouteDisconnectedError } from './route-disconnected-error';
 import { runWithOutboundFlow } from '../diagnostics/flow-context';
 
-const CHANNEL_REQUEST_LOOP_KEEPALIVE_MS = 0x7fff_ffff;
-
-//  Shared default for the dominant no-metadata call; avoids a Map allocation
-//  per outbound operation.
 const EMPTY_OUTBOUND_METADATA: ReadonlyMap<string, string> = new Map();
 
 export class ZLinkChannelOutboundOperations {
@@ -47,7 +45,8 @@ export class ZLinkChannelOutboundOperations {
   constructor(
     private readonly sockets: ZLinkChannelSocketRegistry,
     private readonly codecs: ZLinkChannelEnvelopeCodecRegistry,
-    private readonly dispatchServices: ZLinkChannelDispatchServices
+    private readonly dispatchServices: ZLinkChannelDispatchServices,
+    private readonly requests = new RequestRuntime()
   ) {}
 
   pendingRequestCount(channelName: string): number {
@@ -129,40 +128,36 @@ export class ZLinkChannelOutboundOperations {
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>
   ): Promise<TReply> {
-    return keepChannelRequestAlive(
-      runWithOutboundFlow(this.dispatchServices.flowCreationEnabled(), () =>
-        this.requestScoped<TReply>(
-          channelName,
-          packetName,
-          request,
-          timeoutMs,
-          signal,
-          metadata,
-          onAdmitted
-        )
+    return runWithOutboundFlow(this.dispatchServices.flowCreationEnabled(), () =>
+      this.requestScoped<TReply>(
+        channelName,
+        packetName,
+        request,
+        timeoutMs,
+        signal,
+        metadata,
+        onAdmitted,
+        requestOperation
       )
     );
   }
 
-  private async requestScoped<TReply>(
+  private requestScoped<TReply>(
     channelName: string,
     packetName: string | undefined,
     request: unknown,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    existing?: PendingOperation<unknown>
   ): Promise<TReply> {
-    const deadlineMs = timeoutMs === undefined ? undefined : performance.now() + timeoutMs;
-    const deadlineUnixMs = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
     let correlationId: string | undefined;
     let selectedServerRid: string | undefined;
-    let terminalRecorded = false;
     const traceTerminal = (result: ZLinkRuntimeMessageFlowResult): void => {
-      if (terminalRecorded) return;
-      terminalRecorded = true;
       this.dispatchServices.beginOutbound(ZLinkMessageFlowOutcome.ReplyReceived, result)?.trace({
         surface: ZLinkDispatchErrorSurface.Channel,
         messageKind: ZLinkDispatchMessageKind.Request,
@@ -175,88 +170,106 @@ export class ZLinkChannelOutboundOperations {
       });
     };
     try {
-      throwIfAborted(signal);
-      const readyWait = new AbortController();
-      const readySignal =
-        signal === undefined ? readyWait.signal : AbortSignal.any([signal, readyWait.signal]);
-      const dealer = await waitRequestReply(
-        this.sockets.awaitClientDealerForOutbound(channelName, readySignal),
-        `Channel request '${channelName}'`,
-        deadlineMs,
-        signal,
-        () => readyWait.abort()
-      );
-      if (dealer === undefined) {
-        throw createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
-          `Channel '${channelName}' has no ready ClientServer server before its admission deadline.`
-        );
-      }
-      const serverRid = this.sockets.selectedClientServerRid(channelName, dealer);
-      selectedServerRid = serverRid;
-      correlationId = newChannelCorrelationId();
-      const parts = encodeChannelEnvelopePartsAtDeadline(
-        ZLinkChannelMessageKind.Request,
-        channelName,
-        packetName,
-        request,
-        deadlineUnixMs,
-        undefined,
-        this.codecs,
-        correlationId,
-        this.dispatchServices.flowCreationEnabled(),
-        metadata
-      ) as readonly Message[];
-      this.dispatchServices.beginOutbound(ZLinkMessageFlowOutcome.Sent)?.trace({
-        surface: ZLinkDispatchErrorSurface.Channel,
-        messageKind: ZLinkDispatchMessageKind.Request,
-        channelName,
-        channelRouteKind: 'client_server',
-        serverRid,
-        packetName,
-        correlationId
-      });
-      const reply = await this.measureRequest(channelName, async () => {
-        let replyParts: readonly Message[] = [];
-        try {
-          try {
-            replyParts = await awaitWithAbort(
-              dealer.request(
-                parts,
-                remainingRequestTimeout(`Channel request '${channelName}'`, deadlineMs),
-                onAdmitted
-              ),
-              signal
+      signal?.throwIfAborted();
+      const operation = this.requests.begin(timeoutMs, signal, existing);
+      const reply = this.requests.run<TReply>(
+        operation,
+        (receiver) => {
+          this.measureRequest(channelName, operation);
+          operation.mapCaller(
+            (value) => {
+              traceTerminal('succeeded');
+              return value;
+            },
+            (error) => {
+              if (!isRemoteChannelErrorReply(error))
+                traceTerminal(requestTerminalResult(error, signal));
+              throw error;
+            }
+          );
+
+          void (async () => {
+            const requestOperation = operation;
+            const deadlineMs = requestOperation.deadlineMs;
+            const deadlineUnixMs = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
+            const readyWait = new AbortController();
+            const readySignal =
+              signal === undefined ? readyWait.signal : AbortSignal.any([signal, readyWait.signal]);
+            const dealer = await waitRequestReply(
+              this.sockets.awaitClientDealerForOutbound(channelName, readySignal),
+              `Channel request '${channelName}'`,
+              requestOperation,
+              () => readyWait.abort()
             );
-          } catch (error) {
-            if (signal?.aborted === true) throw error;
-            //  Spec 32-framework-error-model:81-92 — classify the backend request
-            //  terminal (deadline -> DeadlineExceeded, lost route -> Unavailable,
-            //  etc.) instead of collapsing every failure to Unavailable.
-            if (isZLinkBackendResultError(error) && error.operation === 'request') {
-              throw new ZLinkFrameworkException(
-                requestResultToPublicErrorKind(error.result),
-                `Channel '${channelName}' request failed with result ${error.result}.`,
-                error
+            if (dealer === undefined) {
+              throw createInternalFrameworkException(
+                ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
+                `Channel '${channelName}' has no ready ClientServer server before its admission deadline.`
               );
             }
-            throw error;
+            const serverRid = this.sockets.selectedClientServerRid(channelName, dealer);
+            selectedServerRid = serverRid;
+            correlationId = newChannelCorrelationId();
+            const parts = encodeChannelEnvelopePartsAtDeadline(
+              ZLinkChannelMessageKind.Request,
+              channelName,
+              packetName,
+              request,
+              deadlineUnixMs,
+              undefined,
+              this.codecs,
+              correlationId,
+              this.dispatchServices.flowCreationEnabled(),
+              metadata
+            ) as readonly Message[];
+            this.dispatchServices.beginOutbound(ZLinkMessageFlowOutcome.Sent)?.trace({
+              surface: ZLinkDispatchErrorSurface.Channel,
+              messageKind: ZLinkDispatchMessageKind.Request,
+              channelName,
+              channelRouteKind: 'client_server',
+              serverRid,
+              packetName,
+              correlationId
+            });
+            dealer.request(
+              parts,
+              remainingRequestTimeout(`Channel request '${channelName}'`, deadlineMs),
+              onAdmitted,
+              requestOperation,
+              receiver
+            );
+          })().catch((error) => receiver.operationFailed(operation.id, error, undefined));
+        },
+        (raw) => {
+          const replyParts = raw as readonly Message[];
+          try {
+            return decodeChannelReply<TReply>(replyParts, this.codecs);
+          } finally {
+            closeMessages(replyParts);
+          }
+        },
+        (error) => {
+          if (
+            signal?.aborted !== true &&
+            isZLinkBackendResultError(error) &&
+            error.operation === 'request'
+          ) {
+            return new ZLinkFrameworkException(
+              requestResultToPublicErrorKind(error.result),
+              `Channel '${channelName}' request failed with result ${error.result}.`,
+              error
+            );
           }
-          return decodeChannelReply<TReply>(replyParts, this.codecs);
-        } finally {
-          closeMessages(replyParts);
+          return error;
         }
-      });
-      traceTerminal('succeeded');
+      );
       return reply;
     } catch (error) {
       // A framework peer has already made the terminal dispatch error record
       // before it sends an Error reply.  Do not turn that same remote dispatch
       // failure into a second local `reply_received` terminal at Errors level.
-      if (!isRemoteChannelErrorReply(error)) {
-        traceTerminal(requestTerminalResult(error, signal));
-      }
-      throw error;
+      if (!isRemoteChannelErrorReply(error)) traceTerminal(requestTerminalResult(error, signal));
+      return Promise.reject(error);
     }
   }
 
@@ -409,7 +422,8 @@ export class ZLinkChannelOutboundOperations {
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>
   ): Promise<TReply> {
     return runWithOutboundFlow(this.dispatchServices.flowCreationEnabled(), () =>
       this.routeRequestScoped<TReply>(
@@ -420,12 +434,13 @@ export class ZLinkChannelOutboundOperations {
         timeoutMs,
         signal,
         metadata,
-        onAdmitted
+        onAdmitted,
+        requestOperation
       )
     );
   }
 
-  private async routeRequestScoped<TReply>(
+  private routeRequestScoped<TReply>(
     routerChannelId: string,
     targetNodeRid: string,
     packetName: string | undefined,
@@ -433,14 +448,11 @@ export class ZLinkChannelOutboundOperations {
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    existing?: PendingOperation<unknown>
   ): Promise<TReply> {
     let correlationId: string | undefined;
-    let router: ReturnType<ZLinkChannelSocketRegistry['routeRouter']> | undefined;
-    let terminalRecorded = false;
     const traceTerminal = (result: ZLinkRuntimeMessageFlowResult): void => {
-      if (terminalRecorded) return;
-      terminalRecorded = true;
       this.dispatchServices.beginOutbound(ZLinkMessageFlowOutcome.ReplyReceived, result)?.trace({
         surface: ZLinkDispatchErrorSurface.RouteMeshChannel,
         messageKind: ZLinkDispatchMessageKind.Request,
@@ -453,92 +465,106 @@ export class ZLinkChannelOutboundOperations {
       });
     };
     try {
-      throwIfAborted(signal);
-      router = this.sockets.routeRouter(routerChannelId);
-      if (this.sockets.routeMemberStatus(routerChannelId, targetNodeRid) === 'missing') {
-        throw createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
-          `Route channel '${routerChannelId}' has no member '${targetNodeRid}'.`
-        );
-      }
-      correlationId = newChannelCorrelationId();
-      const parts = encodeChannelEnvelopeParts(
-        ZLinkChannelMessageKind.Request,
-        routerChannelId,
-        packetName,
-        request,
-        timeoutMs,
-        undefined,
-        codecsForFrameworkPacket(packetName, this.codecs),
-        correlationId,
-        this.dispatchServices.flowCreationEnabled(),
-        metadata
-      ) as readonly Message[];
-      this.dispatchServices.beginOutbound(ZLinkMessageFlowOutcome.Sent)?.trace({
-        surface: ZLinkDispatchErrorSurface.RouteMeshChannel,
-        messageKind: ZLinkDispatchMessageKind.Request,
-        channelName: routerChannelId,
-        channelRouteKind: 'route_mesh',
-        packetName,
-        correlationId,
-        targetRid: targetNodeRid
-      });
-      const reply = await this.measureRequest(routerChannelId, async () => {
-        const replyParts = await awaitWithAbort(
-          router!.request(targetNodeRid, parts, timeoutMs, onAdmitted),
-          signal
-        );
-        try {
-          return decodeChannelReply<TReply>(replyParts, this.codecs);
-        } finally {
-          closeMessages(replyParts);
+      signal?.throwIfAborted();
+      const operation = this.requests.begin(timeoutMs, signal, existing);
+      const reply = this.requests.run<TReply>(
+        operation,
+        (receiver) => {
+          this.measureRequest(routerChannelId, operation);
+          operation.mapCaller(
+            (value) => {
+              traceTerminal('succeeded');
+              return value;
+            },
+            (error) => {
+              if (!isRemoteChannelErrorReply(error))
+                traceTerminal(requestTerminalResult(error, signal));
+              throw error;
+            }
+          );
+
+          const requestOperation = operation;
+          const router = this.sockets.routeRouter(routerChannelId);
+          if (this.sockets.routeMemberStatus(routerChannelId, targetNodeRid) === 'missing') {
+            throw createInternalFrameworkException(
+              ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
+              `Route channel '${routerChannelId}' has no member '${targetNodeRid}'.`
+            );
+          }
+          correlationId = newChannelCorrelationId();
+          const parts = encodeChannelEnvelopeParts(
+            ZLinkChannelMessageKind.Request,
+            routerChannelId,
+            packetName,
+            request,
+            timeoutMs,
+            undefined,
+            codecsForFrameworkPacket(packetName, this.codecs),
+            correlationId,
+            this.dispatchServices.flowCreationEnabled(),
+            metadata
+          ) as readonly Message[];
+          this.dispatchServices.beginOutbound(ZLinkMessageFlowOutcome.Sent)?.trace({
+            surface: ZLinkDispatchErrorSurface.RouteMeshChannel,
+            messageKind: ZLinkDispatchMessageKind.Request,
+            channelName: routerChannelId,
+            channelRouteKind: 'route_mesh',
+            packetName,
+            correlationId,
+            targetRid: targetNodeRid
+          });
+          router.request(targetNodeRid, parts, timeoutMs, onAdmitted, requestOperation, receiver);
+        },
+        (raw) => {
+          const replyParts = raw as readonly Message[];
+          try {
+            return decodeChannelReply<TReply>(replyParts, this.codecs);
+          } finally {
+            closeMessages(replyParts);
+          }
+        },
+        (error) => {
+          if (
+            this.sockets.routeMemberStatus(routerChannelId, targetNodeRid) === 'disconnected' &&
+            (isSubmitDeadline(error) || error instanceof ZLinkRouteDisconnectedError)
+          ) {
+            return createInternalFrameworkException(
+              ZLinkFrameworkInternalErrorKind.RouteNotConnected,
+              `Route channel '${routerChannelId}' member '${targetNodeRid}' is not connected.`,
+              true,
+              error
+            );
+          }
+          return error;
         }
-      });
-      traceTerminal('succeeded');
+      );
       return reply;
     } catch (error) {
-      // See the ClientServer request path: the remote dispatch error owns this
-      // terminal record when the reply itself is an Error envelope.
-      if (!isRemoteChannelErrorReply(error)) {
-        traceTerminal(requestTerminalResult(error, signal));
-      }
-      if (
-        this.sockets.routeMemberStatus(routerChannelId, targetNodeRid) === 'disconnected' &&
-        (isSubmitDeadline(error) || error instanceof ZLinkRouteDisconnectedError)
-      ) {
-        throw createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.RouteNotConnected,
-          `Route channel '${routerChannelId}' member '${targetNodeRid}' is not connected.`,
-          true,
-          error
-        );
-      }
-      throw error;
+      if (!isRemoteChannelErrorReply(error)) traceTerminal(requestTerminalResult(error, signal));
+      return Promise.reject(error);
     }
   }
 
-  private async measureRequest<T>(channel: string, operation: () => Promise<T>): Promise<T> {
+  private measureRequest(channel: string, operation: PendingOperation<unknown>): void {
     this.pendingRequests.set(channel, this.pendingRequestCount(channel) + 1);
-    try {
-      return await operation();
-    } finally {
+    const complete = (): void => {
       const remaining = this.pendingRequestCount(channel) - 1;
       if (remaining === 0) this.pendingRequests.delete(channel);
       else this.pendingRequests.set(channel, remaining);
-    }
+    };
+    operation.mapCaller(
+      (value) => {
+        complete();
+        return value;
+      },
+      (error) => {
+        complete();
+        throw error;
+      }
+    );
   }
 }
 
-/**
- * A ClientServer DEALER's request progress poller is intentionally unref'ed.
- * The public request promise is live work, however, so it needs its own
- * ref'ed handle until reply, cancellation, timeout, or failure settles it.
- */
-export function keepChannelRequestAlive<T>(request: Promise<T>): Promise<T> {
-  const keepalive = setTimeout(() => {}, CHANNEL_REQUEST_LOOP_KEEPALIVE_MS);
-  return request.finally(() => clearTimeout(keepalive));
-}
-
 function isSubmitDeadline(error: unknown): boolean {
   return (
     error instanceof ZLinkFrameworkException &&