@zlink-systems/framework 0.30.3 → 0.32.0

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

@@ -1,3 +1,4 @@
+import type { ZLinkHandlerMessageType } from '../../contracts/Common/HandlerMessageType';
 import type { ZLinkMeshDispatchAdmission } from '../admission';
 import type {
   RoutingId,
@@ -42,12 +43,14 @@ import { codecsForFrameworkPacket } from './channel-framework-packets';
 import {
   ZLinkChannelDispatchPipeline,
   type ZLinkChannelDispatchFields,
+  type ZLinkOneWayDispatch,
   type ZLinkRequestDispatch
 } from './channel-dispatch-pipeline';
 
 export interface ZLinkChannelRequestDispatcherOptions {
   readonly meshName?: string;
   readonly channelName: string;
+  readonly receivedAtClock?: () => Date;
   /**
    * Mesh channels use the routed message context so a handler can associate
    * a report with the node that sent it.
@@ -55,8 +58,14 @@ export interface ZLinkChannelRequestDispatcherOptions {
   readonly routeMesh?: boolean;
   readonly codecs?: ZLinkChannelEnvelopeCodecRegistry;
   readonly dispatchErrors: ZLinkDispatchErrorReporter;
-  readonly handlers: ReadonlyMap<string, ZLinkChannelRequestHandler>;
-  readonly sendHandlers?: ReadonlyMap<string, ZLinkChannelSendHandler>;
+  readonly handlers: ReadonlyMap<
+    string,
+    Pick<ZLinkRequestDispatch<ZLinkMessageContext>, 'handler' | 'messageType'>
+  >;
+  readonly sendHandlers?: ReadonlyMap<
+    string,
+    Pick<ZLinkOneWayDispatch<ZLinkMessageContext>, 'handler' | 'messageType'>
+  >;
   readonly filters?: readonly ZLinkHandlerFilter[];
   readonly unhandled?: ZLinkUnhandledDispatchOptions;
 }
@@ -72,6 +81,7 @@ export interface ZLinkChannelSendHandler {
 }
 
 export interface ZLinkRouteHandlerRegistration {
+  readonly messageType?: ZLinkHandlerMessageType;
   readonly kind: 'send' | 'request';
   readonly packetName: string;
   readonly handler: ZLinkRouteRuntimeSendHandler | ZLinkRouteRuntimeRequestHandler;
@@ -115,7 +125,8 @@ export class ZLinkChannelRequestDispatcher {
       reply(routingId: unknown, replyToken: unknown): ZLinkMultipartReplyOperation;
     },
     signal?: AbortSignal,
-    decodedHeader?: ZLinkChannelEnvelopeHeader
+    decodedHeader?: ZLinkChannelEnvelopeHeader,
+    receivedAt: Date = this.options.receivedAtClock?.() ?? new Date()
   ): Promise<boolean | void> {
     if (received.spotId !== null && received.spotId !== undefined) {
       if (received.send === undefined) {
@@ -176,13 +187,15 @@ export class ZLinkChannelRequestDispatcher {
         contentType: envelope.header.contentType,
         packetName,
         metadata: zlinkMessageMetadata(envelope.header.metadata),
-        correlationId
+        correlationId,
+        receivedAt
       };
       await this.pipeline.dispatchOneWay({
         fields,
         envelope,
         codecs: this.options.codecs,
-        handler,
+        handler: handler?.handler,
+        messageType: handler?.messageType,
         context,
         signal
       });
@@ -211,13 +224,15 @@ export class ZLinkChannelRequestDispatcher {
       contentType: envelope.header.contentType,
       packetName,
       metadata: zlinkMessageMetadata(envelope.header.metadata),
-      correlationId
+      correlationId,
+      receivedAt
     };
     await this.pipeline.dispatchRequest({
       fields: requestFields,
       envelope,
       codecs: this.options.codecs,
-      handler,
+      handler: handler?.handler,
+      messageType: handler?.messageType,
       context,
       signal,
       missingHandlerMessage: `No channel request handler is registered for '${this.options.channelName}:${packetName}'.`,
@@ -276,6 +291,7 @@ export class ZLinkChannelRequestDispatcher {
     }
     const correlationId = envelope.header.correlationId ?? undefined;
     if (envelope.header.kind === ZLinkChannelMessageKind.Command) {
+      const handler = this.options.sendHandlers?.get(packetName);
       return this.pipeline.dispatchOneWay(
         {
           fields: {
@@ -287,8 +303,9 @@ export class ZLinkChannelRequestDispatcher {
           },
           envelope,
           codecs: this.options.codecs,
-          handler: this.options.sendHandlers?.get(packetName),
-          context: this.createMeshContext(envelope, record.sourceNodeRid),
+          handler: handler?.handler,
+          messageType: handler?.messageType,
+          context: this.createMeshContext(envelope, record.sourceNodeRid, record.receivedAt),
           signal
         },
         admit
@@ -310,7 +327,7 @@ export class ZLinkChannelRequestDispatcher {
         envelope,
         this.options.codecs,
         this.options.handlers.get(packetName),
-        this.createMeshContext(envelope, record.sourceNodeRid),
+        this.createMeshContext(envelope, record.sourceNodeRid, record.receivedAt),
         signal,
         record,
         'channel',
@@ -333,7 +350,8 @@ export class ZLinkChannelRequestDispatcher {
 
   private createMeshContext(
     envelope: ReturnType<typeof decodeChannelEnvelope>,
-    sourceNodeRid: unknown
+    sourceNodeRid: unknown,
+    receivedAt?: Date
   ): ZLinkMessageContext {
     const base = {
       meshName: this.options.meshName,
@@ -341,7 +359,8 @@ export class ZLinkChannelRequestDispatcher {
       contentType: envelope.header.contentType,
       packetName: envelope.packetName!,
       metadata: zlinkMessageMetadata(envelope.header.metadata),
-      correlationId: envelope.header.correlationId ?? undefined
+      correlationId: envelope.header.correlationId ?? undefined,
+      receivedAt: receivedAt ?? this.options.receivedAtClock?.() ?? new Date()
     };
     if (this.options.routeMesh !== true) {
       return base;
@@ -366,7 +385,8 @@ class ZLinkMeshRequestDispatch<
     readonly fields: ZLinkChannelDispatchFields,
     readonly envelope: ReturnType<typeof decodeChannelEnvelope>,
     readonly codecs: ZLinkChannelEnvelopeCodecRegistry | undefined,
-    readonly handler: ZLinkRequestDispatch<TContext>['handler'],
+    private readonly registration:
+      Pick<ZLinkRequestDispatch<TContext>, 'handler' | 'messageType'> | undefined,
     readonly context: TContext,
     readonly signal: AbortSignal | undefined,
     private readonly record: ReceiveRecord,
@@ -374,6 +394,14 @@ class ZLinkMeshRequestDispatch<
     private readonly channelName: string
   ) {}
 
+  get handler(): ZLinkRequestDispatch<TContext>['handler'] {
+    return this.registration?.handler;
+  }
+
+  get messageType(): ZLinkHandlerMessageType | undefined {
+    return this.registration?.messageType;
+  }
+
   get missingHandlerMessage(): string {
     return `No ${this.handlerSurface} request handler is registered for '${this.channelName}:${this.fields.packetName}'.`;
   }
@@ -402,9 +430,13 @@ function requireMeshReplyAccepted(result: number): void {
 export interface ZLinkChannelPublishDispatcherOptions {
   readonly meshName?: string;
   readonly channelName: string;
+  readonly receivedAtClock?: () => Date;
   readonly codecs?: ZLinkChannelEnvelopeCodecRegistry;
   readonly dispatchErrors: ZLinkDispatchErrorReporter;
-  readonly handlers: ReadonlyMap<string, ZLinkRuntimePublishHandler>;
+  readonly handlers: ReadonlyMap<
+    string,
+    Pick<ZLinkOneWayDispatch<ZLinkPublishMessageContext>, 'handler' | 'messageType'>
+  >;
   readonly filters?: readonly ZLinkHandlerFilter[];
   readonly unhandled?: ZLinkUnhandledDispatchOptions;
   readonly metrics?: ZLinkRuntimeMetrics;
@@ -430,7 +462,8 @@ export class ZLinkChannelPublishDispatcher {
   async dispatch(
     topicMessage: { readonly topic: string; readonly parts: readonly Message[] },
     signal?: AbortSignal,
-    decodedHeader?: ZLinkChannelEnvelopeHeader
+    decodedHeader?: ZLinkChannelEnvelopeHeader,
+    receivedAt: Date = this.options.receivedAtClock?.() ?? new Date()
   ): Promise<void> {
     if (topicMessage.parts.length === 0 || topicMessage.parts[0].data().length === 0) {
       return;
@@ -482,13 +515,15 @@ export class ZLinkChannelPublishDispatcher {
       topic: publishTopic,
       source: publishSource,
       metadata: zlinkMessageMetadata(envelope.header.metadata),
-      correlationId: publishCorr
+      correlationId: publishCorr,
+      receivedAt
     };
     await this.pipeline.dispatchOneWay({
       fields,
       envelope,
       codecs: this.options.codecs,
-      handler,
+      handler: handler?.handler,
+      messageType: handler?.messageType,
       context,
       signal
     });
@@ -497,6 +532,7 @@ export class ZLinkChannelPublishDispatcher {
 
 export interface ZLinkRoutePacketDispatcherOptions {
   readonly routerChannelId: string;
+  readonly receivedAtClock?: () => Date;
   readonly codecs?: ZLinkChannelEnvelopeCodecRegistry;
   readonly dispatchErrors: ZLinkDispatchErrorReporter;
   readonly handlers: readonly ZLinkRouteHandlerRegistration[];
@@ -510,28 +546,34 @@ export function collectRouteChannelHandlers(
 ): ZLinkRouteHandlerRegistration[] {
   return [
     ...(routeChannel.handlers ?? []),
-    ...(routeChannel.sendHandlers ?? []).map((handler): ZLinkRouteHandlerRegistration => ({
+    ...(routeChannel.sendHandlers ?? []).map((registration): ZLinkRouteHandlerRegistration => ({
       kind: 'send',
-      packetName: handler.packetName,
-      handler: handler.handler
+      ...registration
     })),
-    ...(routeChannel.requestHandlers ?? []).map((handler): ZLinkRouteHandlerRegistration => ({
+    ...(routeChannel.requestHandlers ?? []).map((registration): ZLinkRouteHandlerRegistration => ({
       kind: 'request',
-      packetName: handler.packetName,
-      handler: handler.handler
+      ...registration
     }))
   ];
 }
 
 export class ZLinkRoutePacketDispatcher {
-  private readonly sendHandlers = new Map<string, ZLinkRouteRuntimeSendHandler>();
-  private readonly requestHandlers = new Map<string, ZLinkRouteRuntimeRequestHandler>();
+  private readonly sendHandlers = new Map<
+    string,
+    Pick<ZLinkOneWayDispatch<ZLinkRouteMessageContext>, 'handler' | 'messageType'>
+  >();
+  private readonly requestHandlers = new Map<
+    string,
+    Pick<ZLinkRequestDispatch<ZLinkRouteMessageContext>, 'handler' | 'messageType'>
+  >();
   private readonly codecs?: ZLinkChannelEnvelopeCodecRegistry;
+  private readonly receivedAtClock: () => Date;
   private readonly pipeline: ZLinkChannelDispatchPipeline;
 
   constructor(options: ZLinkRoutePacketDispatcherOptions) {
     this.routerChannelId = options.routerChannelId;
     this.codecs = options.codecs;
+    this.receivedAtClock = options.receivedAtClock ?? (() => new Date());
     this.dispatchErrors = options.dispatchErrors;
     this.pipeline = new ZLinkChannelDispatchPipeline({
       dispatchErrors: options.dispatchErrors,
@@ -548,7 +590,7 @@ export class ZLinkRoutePacketDispatcher {
           `Duplicate routed handler '${options.routerChannelId}:${handler.kind}:${handler.packetName}'.`
         );
       }
-      target.set(handler.packetName, handler.handler as never);
+      target.set(handler.packetName, handler as never);
     }
   }
 
@@ -605,7 +647,8 @@ export class ZLinkRoutePacketDispatcher {
     },
     signal?: AbortSignal,
     decodedHeader?: ZLinkChannelEnvelopeHeader,
-    infrastructureChecked = false
+    infrastructureChecked = false,
+    receivedAt: Date = this.receivedAtClock()
   ): Promise<boolean | void> {
     const channelHeader =
       decodedHeader ?? tryDecodeChannelHeader(received.parts, this.flowEnabled());
@@ -667,8 +710,9 @@ export class ZLinkRoutePacketDispatcher {
         fields,
         envelope,
         codecs: codecsForFrameworkPacket(packetName, this.codecs),
-        handler,
-        context: this.createRouteContext(envelope, received.routingId),
+        handler: handler?.handler,
+        messageType: handler?.messageType,
+        context: this.createRouteContext(envelope, received.routingId, receivedAt),
         signal
       });
       return;
@@ -705,8 +749,9 @@ export class ZLinkRoutePacketDispatcher {
       fields: requestFields,
       envelope,
       codecs,
-      handler,
-      context: this.createRouteContext(envelope, received.routingId),
+      handler: handler?.handler,
+      messageType: handler?.messageType,
+      context: this.createRouteContext(envelope, received.routingId, receivedAt),
       signal,
       missingHandlerMessage: `No routed request handler is registered for '${this.routerChannelId}:${packetName}'.`,
       writeReply: (reply) =>
@@ -769,7 +814,8 @@ export class ZLinkRoutePacketDispatcher {
         sourceNodeRid,
         record.sourceNodeRid,
         signal,
-        admit
+        admit,
+        record.receivedAt ?? this.receivedAtClock()
       );
     }
     if (envelope.header.kind !== ZLinkChannelMessageKind.Request) {
@@ -789,7 +835,7 @@ export class ZLinkRoutePacketDispatcher {
         envelope,
         codecsForFrameworkPacket(packetName, this.codecs),
         this.requestHandlers.get(packetName),
-        this.createRouteContext(envelope, record.sourceNodeRid),
+        this.createRouteContext(envelope, record.sourceNodeRid, record.receivedAt),
         signal,
         record,
         'routed',
@@ -804,6 +850,7 @@ export class ZLinkRoutePacketDispatcher {
     sourceNodeRid: RoutingId,
     signal?: AbortSignal
   ): Promise<void> {
+    const receivedAt = this.receivedAtClock();
     if (parts.length === 0 || parts[0].data().length === 0) return;
     let envelope: ReturnType<typeof decodeChannelEnvelope>;
     try {
@@ -832,7 +879,9 @@ export class ZLinkRoutePacketDispatcher {
       packetName,
       String(sourceNodeRid),
       sourceNodeRid,
-      signal
+      signal,
+      undefined,
+      receivedAt
     );
   }
 
@@ -842,8 +891,10 @@ export class ZLinkRoutePacketDispatcher {
     sourceRid: string,
     sourceNodeRid: unknown,
     signal?: AbortSignal,
-    admit?: ZLinkMeshDispatchAdmission
+    admit?: ZLinkMeshDispatchAdmission,
+    receivedAt: Date = this.receivedAtClock()
   ): void | Promise<void> {
+    const handler = this.sendHandlers.get(packetName);
     return this.pipeline.dispatchOneWay(
       {
         fields: {
@@ -856,8 +907,9 @@ export class ZLinkRoutePacketDispatcher {
         },
         envelope,
         codecs: codecsForFrameworkPacket(packetName, this.codecs),
-        handler: this.sendHandlers.get(packetName),
-        context: this.createRouteContext(envelope, sourceNodeRid),
+        handler: handler?.handler,
+        messageType: handler?.messageType,
+        context: this.createRouteContext(envelope, sourceNodeRid, receivedAt),
         signal
       },
       admit
@@ -873,7 +925,8 @@ export class ZLinkRoutePacketDispatcher {
 
   private createRouteContext(
     envelope: ReturnType<typeof decodeChannelEnvelope>,
-    sourceRid: unknown
+    sourceRid: unknown,
+    receivedAt: Date = this.receivedAtClock()
   ): ZLinkRouteMessageContext {
     const sourceNodeRid = String(sourceRid ?? '');
     return {
@@ -882,7 +935,8 @@ export class ZLinkRoutePacketDispatcher {
       contentType: envelope.header.contentType,
       sourceNodeRid,
       metadata: zlinkMessageMetadata(envelope.header.metadata),
-      correlationId: envelope.header.correlationId ?? undefined
+      correlationId: envelope.header.correlationId ?? undefined,
+      receivedAt
     };
   }
 }