@zlink-systems/framework 0.30.0 → 0.30.2

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,
@@ -26,7 +28,6 @@ import {
 import { invokeZLinkHandlerFilters } from '../handlers';
 import {
   decodeChannelPayload,
-  ZLinkChannelMessageKind,
   type ZLinkChannelEnvelope,
   type ZLinkChannelEnvelopeCodecRegistry
 } from './channel-envelope';
@@ -66,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;
@@ -74,8 +75,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 {
@@ -87,137 +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 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);
+  }
+
+  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)
       );
-      if (invocation.handlerInvoked) {
-        this.trace(ZLinkMessageFlowOutcome.Completed, dispatch.fields);
-      }
+    }
+    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 runWithFlow(flow, () =>
-        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,
-          dispatch.handler!,
+          handler,
           dispatch.context,
           dispatch.fields,
           dispatch.signal
         )
-      );
-      if (!invocation.handlerInvoked) {
-        throw createInternalFrameworkException(
+      : runWithFlow(flow, () =>
+          this.invoke(
+            dispatch.envelope,
+            dispatch.codecs,
+            handler,
+            dispatch.context,
+            dispatch.fields,
+            dispatch.signal
+          )
+        );
+  }
+
+  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.value;
-    } 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 {
-      await dispatch.writeReply(reply);
-      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 {
@@ -240,9 +309,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 +338,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 +382,7 @@ export class ZLinkChannelDispatchPipeline {
       },
       signal
     );
-    return { handlerInvoked, value };
+    return handlerInvoked ? value : HANDLER_FILTER_REJECTED;
   }
 
   private createFilterContext(
@@ -401,6 +483,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>,