@zlink-systems/framework 0.30.0 → 0.30.2

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

@@ -1,3 +1,4 @@
+import type { ZLinkMeshDispatchAdmission } from '../admission';
 import type {
   RoutingId,
   ZLinkMessageContext,
@@ -13,7 +14,7 @@ import {
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
 import type { Message } from '../../contracts/Common/Message';
 import { SubmitResult } from '../backend/runtime-values';
-import type { ReceiveRecord } from '../foundation/service-runtime-contracts';
+import { ReceiveKind, type ReceiveRecord } from '../foundation/service-runtime-contracts';
 import { ZLinkConfigurationException, type ZLinkRouteChannelOptions } from '../configuration';
 import type { ZLinkBackendSpotRouteBridge } from '../backend/contracts';
 import type { ZLinkRuntimeMetrics } from '../diagnostics';
@@ -40,7 +41,8 @@ import {
 import { codecsForFrameworkPacket } from './channel-framework-packets';
 import {
   ZLinkChannelDispatchPipeline,
-  type ZLinkChannelDispatchFields
+  type ZLinkChannelDispatchFields,
+  type ZLinkRequestDispatch
 } from './channel-dispatch-pipeline';
 
 export interface ZLinkChannelRequestDispatcherOptions {
@@ -59,6 +61,8 @@ export interface ZLinkChannelRequestDispatcherOptions {
   readonly unhandled?: ZLinkUnhandledDispatchOptions;
 }
 
+const completedChannelReply = Promise.resolve();
+
 export interface ZLinkChannelRequestHandler {
   handle(payload: unknown, context: ZLinkMessageContext): Promise<unknown> | unknown;
 }
@@ -134,7 +138,7 @@ export class ZLinkChannelRequestDispatcher {
       await this.pipeline.dispatchMalformed({
         info,
         error,
-        transportRequest: replyToken !== null,
+        transportRequest: replyToken != null,
         writeProtocolError:
           replyToken === null
             ? undefined
@@ -236,19 +240,23 @@ export class ZLinkChannelRequestDispatcher {
     });
   }
 
-  async dispatchMesh(record: ReceiveRecord, signal?: AbortSignal): Promise<void> {
+  dispatchMesh(
+    record: ReceiveRecord,
+    signal?: AbortSignal,
+    admit?: ZLinkMeshDispatchAdmission
+  ): void | Promise<void> {
     if (record.parts.length === 0 || record.parts[0].data().length === 0) {
-      return;
+      return completedChannelReply;
     }
     let envelope: ReturnType<typeof decodeChannelEnvelope>;
     try {
       envelope = decodeChannelEnvelope(record.parts, undefined, this.flowEnabled());
     } catch (error) {
       const info = inspectMalformedChannelHeader(record.parts, this.flowEnabled());
-      await this.pipeline.dispatchMalformed({
+      return this.pipeline.dispatchMalformed({
         info,
         error,
-        transportRequest: false,
+        transportRequest: isMeshRequest(record),
         sourceRid: record.sourceNodeRid == null ? undefined : String(record.sourceNodeRid),
         writeProtocolError: async (protocolError) => {
           requireMeshReplyAccepted(
@@ -261,7 +269,6 @@ export class ZLinkChannelRequestDispatcher {
           );
         }
       });
-      return;
     }
     const packetName = envelope.packetName;
     if (packetName === undefined) {
@@ -269,24 +276,26 @@ export class ZLinkChannelRequestDispatcher {
     }
     const correlationId = envelope.header.correlationId ?? undefined;
     if (envelope.header.kind === ZLinkChannelMessageKind.Command) {
-      await this.pipeline.dispatchOneWay({
-        fields: {
-          messageKind: ZLinkDispatchMessageKind.Send,
-          packetName,
-          correlationId,
-          flowId: envelope.header.flowId,
-          flowOrigin: envelope.header.flowOrigin
+      return this.pipeline.dispatchOneWay(
+        {
+          fields: {
+            messageKind: ZLinkDispatchMessageKind.Send,
+            packetName,
+            correlationId,
+            flowId: envelope.header.flowId,
+            flowOrigin: envelope.header.flowOrigin
+          },
+          envelope,
+          codecs: this.options.codecs,
+          handler: this.options.sendHandlers?.get(packetName),
+          context: this.createMeshContext(envelope, record.sourceNodeRid),
+          signal
         },
-        envelope,
-        codecs: this.options.codecs,
-        handler: this.options.sendHandlers?.get(packetName),
-        context: this.createMeshContext(envelope, record.sourceNodeRid),
-        signal
-      });
-      return;
+        admit
+      );
     }
     if (envelope.header.kind !== ZLinkChannelMessageKind.Request) {
-      return;
+      return completedChannelReply;
     }
     const fields: ZLinkChannelDispatchFields = {
       messageKind: ZLinkDispatchMessageKind.Request,
@@ -295,25 +304,20 @@ export class ZLinkChannelRequestDispatcher {
       flowId: envelope.header.flowId,
       flowOrigin: envelope.header.flowOrigin
     };
-    await this.pipeline.dispatchRequest({
-      fields,
-      envelope,
-      codecs: this.options.codecs,
-      handler: this.options.handlers.get(packetName),
-      context: this.createMeshContext(envelope, record.sourceNodeRid),
-      signal,
-      missingHandlerMessage: `No channel request handler is registered for '${this.options.channelName}:${packetName}'.`,
-      writeReply: async (reply) => {
-        requireMeshReplyAccepted(
-          record.reply(encodeChannelReplyParts(envelope.header, reply, this.options.codecs))
-        );
-      },
-      writeError: async (error) => {
-        requireMeshReplyAccepted(
-          record.reply(encodeChannelErrorReplyParts(envelope.header, error))
-        );
-      }
-    });
+    return this.pipeline.dispatchRequest(
+      new ZLinkMeshRequestDispatch(
+        fields,
+        envelope,
+        this.options.codecs,
+        this.options.handlers.get(packetName),
+        this.createMeshContext(envelope, record.sourceNodeRid),
+        signal,
+        record,
+        'channel',
+        this.options.channelName
+      ),
+      admit
+    );
   }
 
   private submitReply(
@@ -324,7 +328,7 @@ export class ZLinkChannelRequestDispatcher {
     if (operation.submit() === false) {
       throw new ZLinkConfigurationException('Channel reply was not accepted by Core.');
     }
-    return Promise.resolve();
+    return completedChannelReply;
   }
 
   private createMeshContext(
@@ -350,6 +354,43 @@ export class ZLinkChannelRequestDispatcher {
   }
 }
 
+/**
+ * One mesh request handed to the dispatch pipeline. The reply writers are
+ * methods over the received record instead of per-message closures, and the
+ * missing-handler text is built only when no handler exists.
+ */
+class ZLinkMeshRequestDispatch<
+  TContext extends ZLinkMessageContext
+> implements ZLinkRequestDispatch<TContext> {
+  constructor(
+    readonly fields: ZLinkChannelDispatchFields,
+    readonly envelope: ReturnType<typeof decodeChannelEnvelope>,
+    readonly codecs: ZLinkChannelEnvelopeCodecRegistry | undefined,
+    readonly handler: ZLinkRequestDispatch<TContext>['handler'],
+    readonly context: TContext,
+    readonly signal: AbortSignal | undefined,
+    private readonly record: ReceiveRecord,
+    private readonly handlerSurface: 'channel' | 'routed',
+    private readonly channelName: string
+  ) {}
+
+  get missingHandlerMessage(): string {
+    return `No ${this.handlerSurface} request handler is registered for '${this.channelName}:${this.fields.packetName}'.`;
+  }
+
+  writeReply(reply: unknown): void {
+    requireMeshReplyAccepted(
+      this.record.reply(encodeChannelReplyParts(this.envelope.header, reply, this.codecs))
+    );
+  }
+
+  writeError(error: unknown): void {
+    requireMeshReplyAccepted(
+      this.record.reply(encodeChannelErrorReplyParts(this.envelope.header, error))
+    );
+  }
+}
+
 function requireMeshReplyAccepted(result: number): void {
   if (result !== SubmitResult.Ok) {
     throw new ZLinkConfigurationException(
@@ -587,7 +628,7 @@ export class ZLinkRoutePacketDispatcher {
       await this.pipeline.dispatchMalformed({
         info,
         error,
-        transportRequest: replyToken !== null,
+        transportRequest: replyToken != null,
         sourceRid: String(received.routingId),
         writeProtocolError:
           replyToken === null
@@ -685,19 +726,23 @@ export class ZLinkRoutePacketDispatcher {
     });
   }
 
-  async dispatchMesh(record: ReceiveRecord, signal?: AbortSignal): Promise<void> {
+  dispatchMesh(
+    record: ReceiveRecord,
+    signal?: AbortSignal,
+    admit?: ZLinkMeshDispatchAdmission
+  ): void | Promise<void> {
     if (record.parts.length === 0 || record.parts[0].data().length === 0) {
-      return;
+      return completedChannelReply;
     }
     let envelope: ReturnType<typeof decodeChannelEnvelope>;
     try {
       envelope = decodeChannelEnvelope(record.parts, undefined, this.flowEnabled());
     } catch (error) {
       const info = inspectMalformedChannelHeader(record.parts, this.flowEnabled());
-      await this.pipeline.dispatchMalformed({
+      return this.pipeline.dispatchMalformed({
         info,
         error,
-        transportRequest: false,
+        transportRequest: isMeshRequest(record),
         sourceRid: record.sourceNodeRid == null ? undefined : String(record.sourceNodeRid),
         writeProtocolError: async (protocolError) => {
           requireMeshReplyAccepted(
@@ -710,7 +755,6 @@ export class ZLinkRoutePacketDispatcher {
           );
         }
       });
-      return;
     }
     const packetName = envelope.packetName;
     if (packetName === undefined) {
@@ -719,17 +763,17 @@ export class ZLinkRoutePacketDispatcher {
     const sourceNodeRid = String(record.sourceNodeRid ?? '');
     const correlationId = envelope.header.correlationId ?? undefined;
     if (envelope.header.kind === ZLinkChannelMessageKind.Command) {
-      await this.dispatchMeshCommand(
+      return this.dispatchMeshCommand(
         envelope,
         packetName,
         sourceNodeRid,
         record.sourceNodeRid,
-        signal
+        signal,
+        admit
       );
-      return;
     }
     if (envelope.header.kind !== ZLinkChannelMessageKind.Request) {
-      return;
+      return completedChannelReply;
     }
     const fields: ZLinkChannelDispatchFields = {
       messageKind: ZLinkDispatchMessageKind.Request,
@@ -739,26 +783,20 @@ export class ZLinkRoutePacketDispatcher {
       flowId: envelope.header.flowId,
       flowOrigin: envelope.header.flowOrigin
     };
-    const codecs = codecsForFrameworkPacket(packetName, this.codecs);
-    await this.pipeline.dispatchRequest({
-      fields,
-      envelope,
-      codecs,
-      handler: this.requestHandlers.get(packetName),
-      context: this.createRouteContext(envelope, record.sourceNodeRid),
-      signal,
-      missingHandlerMessage: `No routed request handler is registered for '${this.routerChannelId}:${packetName}'.`,
-      writeReply: async (reply) => {
-        requireMeshReplyAccepted(
-          record.reply(encodeChannelReplyParts(envelope.header, reply, codecs))
-        );
-      },
-      writeError: async (error) => {
-        requireMeshReplyAccepted(
-          record.reply(encodeChannelErrorReplyParts(envelope.header, error))
-        );
-      }
-    });
+    return this.pipeline.dispatchRequest(
+      new ZLinkMeshRequestDispatch(
+        fields,
+        envelope,
+        codecsForFrameworkPacket(packetName, this.codecs),
+        this.requestHandlers.get(packetName),
+        this.createRouteContext(envelope, record.sourceNodeRid),
+        signal,
+        record,
+        'routed',
+        this.routerChannelId
+      ),
+      admit
+    );
   }
 
   async dispatchLocalCommand(
@@ -803,30 +841,34 @@ export class ZLinkRoutePacketDispatcher {
     packetName: string,
     sourceRid: string,
     sourceNodeRid: unknown,
-    signal?: AbortSignal
-  ): Promise<void> {
-    return this.pipeline.dispatchOneWay({
-      fields: {
-        messageKind: ZLinkDispatchMessageKind.Send,
-        packetName,
-        sourceRid,
-        correlationId: envelope.header.correlationId ?? undefined,
-        flowId: envelope.header.flowId,
-        flowOrigin: envelope.header.flowOrigin
+    signal?: AbortSignal,
+    admit?: ZLinkMeshDispatchAdmission
+  ): void | Promise<void> {
+    return this.pipeline.dispatchOneWay(
+      {
+        fields: {
+          messageKind: ZLinkDispatchMessageKind.Send,
+          packetName,
+          sourceRid,
+          correlationId: envelope.header.correlationId ?? undefined,
+          flowId: envelope.header.flowId,
+          flowOrigin: envelope.header.flowOrigin
+        },
+        envelope,
+        codecs: codecsForFrameworkPacket(packetName, this.codecs),
+        handler: this.sendHandlers.get(packetName),
+        context: this.createRouteContext(envelope, sourceNodeRid),
+        signal
       },
-      envelope,
-      codecs: codecsForFrameworkPacket(packetName, this.codecs),
-      handler: this.sendHandlers.get(packetName),
-      context: this.createRouteContext(envelope, sourceNodeRid),
-      signal
-    });
+      admit
+    );
   }
 
   private submitReply(operation: ZLinkMultipartReplyOperation): Promise<void> {
     if (operation.submit() === false) {
       throw new ZLinkConfigurationException('Route reply was not accepted by Core.');
     }
-    return Promise.resolve();
+    return completedChannelReply;
   }
 
   private createRouteContext(
@@ -844,3 +886,7 @@ export class ZLinkRoutePacketDispatcher {
     };
   }
 }
+
+function isMeshRequest(record: ReceiveRecord): boolean {
+  return record.kind === ReceiveKind.NodeRequest || record.kind === ReceiveKind.ChannelRequest;
+}

package/src/runtime/channels/channel-envelope-inspection.ts

@@ -3,6 +3,7 @@ import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkFlowOrigin } from '../../contracts';
 import {
   decodeChannelHeader,
+  isValidChannelCorrelationId,
   ZLINK_CHANNEL_FORMAT_MARKER,
   ZLinkChannelMessageKind,
   type ZLinkChannelEnvelopeHeader
@@ -29,7 +30,6 @@ export function tryDecodeChannelHeader(
  * present only when it is individually well-formed.
  */
 export interface ZLinkMalformedChannelHeaderInfo {
-  readonly kind?: ZLinkChannelMessageKind;
   readonly channelName?: string;
   readonly messageName?: string;
   readonly correlationId?: string;
@@ -50,7 +50,6 @@ export function inspectMalformedChannelHeader(
   } catch {
     return {};
   }
-  if (header.formatMarker !== ZLINK_CHANNEL_FORMAT_MARKER) return {};
   const flowId =
     typeof header.flowId === 'string' && CHANNEL_FLOW_ID_PATTERN.test(header.flowId)
       ? header.flowId
@@ -58,7 +57,6 @@ export function inspectMalformedChannelHeader(
   const flowOrigin = salvageFlowOrigin(header.flowOrigin);
   const flowPairValid = flowEnabled && flowId !== undefined && flowOrigin !== undefined;
   return {
-    kind: salvageChannelKind(header.kind),
     channelName: salvageString(header.channelName),
     messageName: salvageString(header.messageName),
     correlationId: salvageCorrelationId(header.correlationId),
@@ -94,24 +92,12 @@ export function malformedProtocolErrorRequestHeader(
 const CHANNEL_FLOW_ID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 
-function salvageChannelKind(value: unknown): ZLinkChannelMessageKind | undefined {
-  return value === ZLinkChannelMessageKind.Request ||
-    value === ZLinkChannelMessageKind.Response ||
-    value === ZLinkChannelMessageKind.Command ||
-    value === ZLinkChannelMessageKind.Publish ||
-    value === ZLinkChannelMessageKind.Error
-    ? value
-    : undefined;
-}
-
 function salvageString(value: unknown): string | undefined {
   return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
 
 function salvageCorrelationId(value: unknown): string | undefined {
-  if (typeof value !== 'string') return undefined;
-  const byteLength = Buffer.byteLength(value, 'utf8');
-  return byteLength >= 1 && byteLength <= 64 && /^[\x00-\x7f]*$/.test(value) ? value : undefined;
+  return typeof value === 'string' && isValidChannelCorrelationId(value) ? value : undefined;
 }
 
 function salvageFlowOrigin(value: unknown): ZLinkFlowOrigin | undefined {