@zlink-systems/framework 0.30.0 → 0.30.1

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,17 @@ export class DefaultZLinkFanoutClient implements ZLinkFanoutClient {
   }
 }
 
+interface PreparedNodeSend {
+  readonly validate: () => void;
+  readonly submit: (
+    packetName: string | undefined,
+    metadata: ReadonlyMap<string, string>,
+    message?: unknown
+  ) => ZLinkSubmitResult | Promise<ZLinkSubmitResult>;
+}
+
 export class DefaultZLinkRouteClient implements ZLinkRouteClient {
+  private readonly nodeSends = new Map<string, Map<string, PreparedNodeSend>>();
   constructor(
     private readonly registration: ZLinkFrameworkRegistration,
     private readonly transport?: ZLinkRouteClientTransport,
@@ -175,25 +188,28 @@ 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(
-            meshName,
-            targetNodeRid,
-            packetName,
-            message,
-            metadata
+    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 {
     return new DefaultZLinkRequestCall(
       () => this.requireMesh(meshName),
-      (packetName, timeoutMs, metadata, signal) =>
+      (packetName, timeoutMs, metadata, signal, onAdmitted) =>
         this.requireTransport().request(
           meshName,
           targetNodeRid,
@@ -201,7 +217,8 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
           request,
           timeoutMs,
           signal,
-          metadata
+          metadata,
+          onAdmitted
         ),
       this.defaultRequestTimeout(meshName)
     );
@@ -233,7 +250,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 +260,8 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
             request,
             timeoutMs,
             signal,
-            metadata
+            metadata,
+            onAdmitted
           );
         }
         return this.requireChannelTransport().request(
@@ -252,7 +270,8 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
           request,
           timeoutMs,
           signal,
-          metadata
+          metadata,
+          onAdmitted
         );
       },
       this.defaultRequestTimeoutForChannel(channelName)
@@ -279,11 +298,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 +436,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 +464,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,13 +489,24 @@ 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);
 }
 
 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();
 
   constructor(
@@ -471,7 +515,8 @@ class DefaultZLinkRequestCall implements ZLinkChannelRequestCall {
       packetName: string | undefined,
       timeoutMs: number | undefined,
       metadata: ReadonlyMap<string, string>,
-      signal?: AbortSignal
+      signal?: AbortSignal,
+      onAdmitted?: () => void
     ) => Promise<TReply>,
     private readonly defaultRequestTimeoutMs?: number
   ) {}
@@ -479,6 +524,7 @@ class DefaultZLinkRequestCall implements ZLinkChannelRequestCall {
   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 +540,18 @@ 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
+      );
+    });
   }
 
   async yield<TReply>(signal?: AbortSignal): Promise<TReply> {
@@ -512,7 +561,7 @@ class DefaultZLinkRequestCall implements ZLinkChannelRequestCall {
     const pending = this.submitter<TReply>(
       undefined,
       this.timeoutMs ?? this.defaultRequestTimeoutMs,
-      new Map(this.selectedMetadata),
+      this.selectedMetadata === undefined ? EMPTY_CALL_METADATA : new Map(this.selectedMetadata),
       signal
     );
     return turn.yieldPromise(pending);

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

@@ -26,7 +26,6 @@ import {
 import { invokeZLinkHandlerFilters } from '../handlers';
 import {
   decodeChannelPayload,
-  ZLinkChannelMessageKind,
   type ZLinkChannelEnvelope,
   type ZLinkChannelEnvelopeCodecRegistry
 } from './channel-envelope';
@@ -74,8 +73,8 @@ interface ZLinkRequestDispatch<TContext extends ZLinkMessageContext> {
   readonly context: TContext;
   readonly signal?: AbortSignal;
   readonly missingHandlerMessage: string;
-  readonly writeReply: (reply: unknown) => Promise<void>;
-  readonly writeError: (error: unknown) => Promise<void>;
+  readonly writeReply: (reply: unknown) => void | Promise<void>;
+  readonly writeError: (error: unknown) => void | Promise<void>;
 }
 
 export class ZLinkChannelDispatchPipeline {
@@ -113,17 +112,27 @@ export class ZLinkChannelDispatchPipeline {
         this.options.dispatchErrors.flow.flowCreationEnabled(),
         undefined
       );
-      const invocation = await runWithFlow(flow, () =>
-        this.invoke(
-          dispatch.envelope,
-          dispatch.codecs,
-          dispatch.handler!,
-          dispatch.context,
-          dispatch.fields,
-          dispatch.signal
-        )
-      );
-      if (invocation.handlerInvoked) {
+      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
+            )
+          ));
+
+      if (invocation !== HANDLER_FILTER_REJECTED) {
         this.trace(ZLinkMessageFlowOutcome.Completed, dispatch.fields);
       }
     } catch (error) {
@@ -165,23 +174,33 @@ export class ZLinkChannelDispatchPipeline {
         this.options.dispatchErrors.flow.flowCreationEnabled(),
         undefined
       );
-      const invocation = await runWithFlow(flow, () =>
-        this.invoke(
-          dispatch.envelope,
-          dispatch.codecs,
-          dispatch.handler!,
-          dispatch.context,
-          dispatch.fields,
-          dispatch.signal
-        )
-      );
-      if (!invocation.handlerInvoked) {
+      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
+            )
+          ));
+
+      if (invocation === HANDLER_FILTER_REJECTED) {
         throw createInternalFrameworkException(
           ZLinkFrameworkInternalErrorKind.RequestRejected,
           `A handler filter rejected '${this.options.channelName}:${dispatch.fields.packetName}'.`
         );
       }
-      reply = invocation.value;
+      reply = invocation;
     } catch (error) {
       try {
         await dispatch.writeError(error);
@@ -206,7 +225,8 @@ export class ZLinkChannelDispatchPipeline {
     }
 
     try {
-      await dispatch.writeReply(reply);
+      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
@@ -240,9 +260,7 @@ export class ZLinkChannelDispatchPipeline {
     readonly writeProtocolError?: (error: ZLinkFrameworkException) => Promise<void>;
   }): Promise<void> {
     const { info } = input;
-    const isRequest =
-      info.kind === ZLinkChannelMessageKind.Request ||
-      (info.kind === undefined && input.transportRequest);
+    const isRequest = input.transportRequest;
     let replied = false;
     if (isRequest && input.writeProtocolError !== undefined && info.correlationId !== undefined) {
       const protocolError = new ZLinkFrameworkException(
@@ -271,22 +289,37 @@ export class ZLinkChannelDispatchPipeline {
     });
   }
 
-  private async invoke<TContext extends ZLinkMessageContext, TResult>(
+  private invoke<TContext extends ZLinkMessageContext, TResult>(
     envelope: ZLinkChannelEnvelope,
     codecs: ZLinkChannelEnvelopeCodecRegistry | undefined,
     handler: ZLinkChannelDispatchHandler<TContext, TResult>,
     context: TContext,
     fields: ZLinkChannelDispatchFields,
     signal?: AbortSignal
-  ): Promise<{ readonly handlerInvoked: boolean; readonly value?: TResult }> {
+  ):
+    | TResult
+    | undefined
+    | typeof HANDLER_FILTER_REJECTED
+    | Promise<TResult | undefined | typeof HANDLER_FILTER_REJECTED> {
     releaseApplicationJobPermitBeforeHandler();
     if (this.filters.length === 0) {
       //  Fast path for the dominant unfiltered dispatch: skip the filter
       //  context object and chain machinery entirely.
       const payload = decodeChannelPayload(envelope, codecs);
       this.trace(ZLinkMessageFlowOutcome.Dispatched, fields);
-      return { handlerInvoked: true, value: await handler.handle(payload, context) };
+      return handler.handle(payload, context);
     }
+    return this.invokeFiltered(envelope, codecs, handler, context, fields, signal);
+  }
+
+  private async invokeFiltered<TContext extends ZLinkMessageContext, TResult>(
+    envelope: ZLinkChannelEnvelope,
+    codecs: ZLinkChannelEnvelopeCodecRegistry | undefined,
+    handler: ZLinkChannelDispatchHandler<TContext, TResult>,
+    context: TContext,
+    fields: ZLinkChannelDispatchFields,
+    signal?: AbortSignal
+  ): Promise<TResult | undefined | typeof HANDLER_FILTER_REJECTED> {
     let value: TResult | undefined;
     const handlerInvoked = await invokeZLinkHandlerFilters(
       this.filters,
@@ -300,7 +333,7 @@ export class ZLinkChannelDispatchPipeline {
       },
       signal
     );
-    return { handlerInvoked, value };
+    return handlerInvoked ? value : HANDLER_FILTER_REJECTED;
   }
 
   private createFilterContext(
@@ -401,6 +434,8 @@ export class ZLinkChannelDispatchPipeline {
   }
 }
 
+const HANDLER_FILTER_REJECTED = Symbol('handler-filter-rejected');
+
 const DEFAULT_UNHANDLED_DISPATCH: ZLinkUnhandledDispatchOptions = {
   request: ZLinkUnhandledDispatchAction.ReplyError,
   send: ZLinkUnhandledDispatchAction.LogAndDrop,

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

@@ -26,7 +26,11 @@ import {
 import type { ZLinkRuntimeTaskErrorSink } from '../execution';
 import { ZLinkDispatchErrorReporter } from './dispatch-error-reporter';
 import { invokeZLinkHandlerFilters } from '../handlers';
-import { runInHandlerInstanceScope } from '../handlers/handler-instance-scope';
+import {
+  runInHandlerInstanceScope,
+  prepareHandlerInstance,
+  handlerInstanceCleanup
+} from '../handlers/handler-instance-scope';
 import { handlerFilterScope } from './handler-filter-scope';
 import type {
   ZLinkChannelRequestHandler,
@@ -109,6 +113,17 @@ export class ZLinkChannelDispatchServices {
   }
 
   channelRequestHandler(handlerType: Type): ZLinkChannelRequestHandler {
+    const activate =
+      this.registration.filterTypes.length === 0
+        ? prepareHandlerInstance(
+            this.providerResolver,
+            handlerType as Type<ZLinkChannelRequestHandler>
+          )
+        : undefined;
+    if (activate !== undefined)
+      return {
+        handle: (payload, context) => this.invokeScopeFreeHandler(activate, payload, context)
+      };
     return {
       handle: (payload, context) =>
         this.withHandlerScope(context, async (scope) => {
@@ -119,6 +134,17 @@ export class ZLinkChannelDispatchServices {
   }
 
   channelSendHandler(handlerType: Type): ZLinkChannelSendHandler {
+    const activate =
+      this.registration.filterTypes.length === 0
+        ? prepareHandlerInstance(
+            this.providerResolver,
+            handlerType as Type<ZLinkChannelSendHandler>
+          )
+        : undefined;
+    if (activate !== undefined)
+      return {
+        handle: (payload, context) => this.invokeScopeFreeHandler(activate, payload, context)
+      };
     return {
       handle: (payload, context) =>
         this.withHandlerScope(context, async (scope) => {
@@ -129,6 +155,17 @@ export class ZLinkChannelDispatchServices {
   }
 
   routeRequestHandler(handlerType: Type): ZLinkRouteRuntimeRequestHandler {
+    const activate =
+      this.registration.filterTypes.length === 0
+        ? prepareHandlerInstance(
+            this.providerResolver,
+            handlerType as Type<ZLinkRouteRuntimeRequestHandler>
+          )
+        : undefined;
+    if (activate !== undefined)
+      return {
+        handle: (payload, context) => this.invokeScopeFreeHandler(activate, payload, context)
+      };
     return {
       handle: (payload, context) =>
         this.withHandlerScope(context, async (scope) => {
@@ -139,6 +176,17 @@ export class ZLinkChannelDispatchServices {
   }
 
   routeSendHandler(handlerType: Type): ZLinkRouteRuntimeSendHandler {
+    const activate =
+      this.registration.filterTypes.length === 0
+        ? prepareHandlerInstance(
+            this.providerResolver,
+            handlerType as Type<ZLinkRouteRuntimeSendHandler>
+          )
+        : undefined;
+    if (activate !== undefined)
+      return {
+        handle: (payload, context) => this.invokeScopeFreeHandler(activate, payload, context)
+      };
     return {
       handle: (payload, context) =>
         this.withHandlerScope(context, async (scope) => {
@@ -148,6 +196,26 @@ export class ZLinkChannelDispatchServices {
     };
   }
 
+  private invokeScopeFreeHandler<TContext extends ZLinkMessageContext, TResult>(
+    activate: () => { handle(payload: unknown, context: TContext): TResult | Promise<TResult> },
+    payload: unknown,
+    context: TContext
+  ): TResult | Promise<TResult> {
+    const handler = activate();
+    const cleanup = handlerInstanceCleanup(handler);
+    if (cleanup === undefined) return handler.handle(payload, context);
+    let result: TResult | Promise<TResult>;
+    try {
+      result = handler.handle(payload, context);
+    } catch (error) {
+      const disposed = cleanup.call(handler);
+      return Promise.resolve(disposed).then(() => {
+        throw error;
+      });
+    }
+    return Promise.resolve(result).finally(() => cleanup.call(handler));
+  }
+
   private async invokeHandlerFilters(
     context: ZLinkHandlerFilterContext,
     next: () => Promise<void>,