@zlink-systems/framework 0.30.0 → 0.30.2

package/dist/runtime/channels/channel-dispatch-services.js

@@ -48,6 +48,13 @@ class ZLinkChannelDispatchServices {
         return this.handlerFiltersValue;
     }
     channelRequestHandler(handlerType) {
+        const activate = this.registration.filterTypes.length === 0
+            ? (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType)
+            : undefined;
+        if (activate !== undefined)
+            return {
+                handle: (payload, context) => this.invokeScopeFreeHandler(activate, payload, context)
+            };
         return {
             handle: (payload, context) => this.withHandlerScope(context, async (scope) => {
                 const handler = await scope.resolve(handlerType);
@@ -56,6 +63,13 @@ class ZLinkChannelDispatchServices {
         };
     }
     channelSendHandler(handlerType) {
+        const activate = this.registration.filterTypes.length === 0
+            ? (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType)
+            : undefined;
+        if (activate !== undefined)
+            return {
+                handle: (payload, context) => this.invokeScopeFreeHandler(activate, payload, context)
+            };
         return {
             handle: (payload, context) => this.withHandlerScope(context, async (scope) => {
                 const handler = await scope.resolve(handlerType);
@@ -64,6 +78,13 @@ class ZLinkChannelDispatchServices {
         };
     }
     routeRequestHandler(handlerType) {
+        const activate = this.registration.filterTypes.length === 0
+            ? (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType)
+            : undefined;
+        if (activate !== undefined)
+            return {
+                handle: (payload, context) => this.invokeScopeFreeHandler(activate, payload, context)
+            };
         return {
             handle: (payload, context) => this.withHandlerScope(context, async (scope) => {
                 const handler = await scope.resolve(handlerType);
@@ -72,6 +93,13 @@ class ZLinkChannelDispatchServices {
         };
     }
     routeSendHandler(handlerType) {
+        const activate = this.registration.filterTypes.length === 0
+            ? (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType)
+            : undefined;
+        if (activate !== undefined)
+            return {
+                handle: (payload, context) => this.invokeScopeFreeHandler(activate, payload, context)
+            };
         return {
             handle: (payload, context) => this.withHandlerScope(context, async (scope) => {
                 const handler = await scope.resolve(handlerType);
@@ -79,6 +107,23 @@ class ZLinkChannelDispatchServices {
             })
         };
     }
+    invokeScopeFreeHandler(activate, payload, context) {
+        const handler = activate();
+        const cleanup = (0, handler_instance_scope_1.handlerInstanceCleanup)(handler);
+        if (cleanup === undefined)
+            return handler.handle(payload, context);
+        let result;
+        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));
+    }
     async invokeHandlerFilters(context, next, signal) {
         const scoped = (0, handler_filter_scope_1.handlerFilterScope)(this.providerResolver);
         if (scoped !== undefined) {

package/dist/runtime/channels/channel-dispatchers.d.ts

@@ -1,6 +1,7 @@
+import type { ZLinkMeshDispatchAdmission } from '../admission';
 import type { RoutingId, ZLinkMessageContext, ZLinkHandlerFilter, ZLinkPublishMessageContext, ZLinkRouteMessageContext, ZLinkUnhandledDispatchOptions } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
-import type { ReceiveRecord } from '../foundation/service-runtime-contracts';
+import { type ReceiveRecord } from '../foundation/service-runtime-contracts';
 import { type ZLinkRouteChannelOptions } from '../configuration';
 import type { ZLinkBackendSpotRouteBridge } from '../backend/contracts';
 import type { ZLinkRuntimeMetrics } from '../diagnostics';
@@ -54,7 +55,7 @@ export declare class ZLinkChannelRequestDispatcher {
     }, router: {
         reply(routingId: unknown, replyToken: unknown): ZLinkMultipartReplyOperation;
     }, signal?: AbortSignal, decodedHeader?: ZLinkChannelEnvelopeHeader): Promise<boolean | void>;
-    dispatchMesh(record: ReceiveRecord, signal?: AbortSignal): Promise<void>;
+    dispatchMesh(record: ReceiveRecord, signal?: AbortSignal, admit?: ZLinkMeshDispatchAdmission): void | Promise<void>;
     private submitReply;
     private createMeshContext;
 }
@@ -117,7 +118,7 @@ export declare class ZLinkRoutePacketDispatcher {
     }, router: {
         reply(routingId: unknown, replyToken: unknown): ZLinkMultipartReplyOperation;
     }, signal?: AbortSignal, decodedHeader?: ZLinkChannelEnvelopeHeader, infrastructureChecked?: boolean): Promise<boolean | void>;
-    dispatchMesh(record: ReceiveRecord, signal?: AbortSignal): Promise<void>;
+    dispatchMesh(record: ReceiveRecord, signal?: AbortSignal, admit?: ZLinkMeshDispatchAdmission): void | Promise<void>;
     dispatchLocalCommand(parts: readonly Message[], sourceNodeRid: RoutingId, signal?: AbortSignal): Promise<void>;
     private dispatchMeshCommand;
     private submitReply;

package/dist/runtime/channels/channel-dispatchers.js

@@ -5,12 +5,14 @@ exports.collectRouteChannelHandlers = collectRouteChannelHandlers;
 const contracts_1 = require("../../contracts");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const runtime_values_1 = require("../backend/runtime-values");
+const service_runtime_contracts_1 = require("../foundation/service-runtime-contracts");
 const configuration_1 = require("../configuration");
 const channel_envelope_1 = require("./channel-envelope");
 const channel_envelope_inspection_1 = require("./channel-envelope-inspection");
 const channel_multipart_1 = require("./channel-multipart");
 const channel_framework_packets_1 = require("./channel-framework-packets");
 const channel_dispatch_pipeline_1 = require("./channel-dispatch-pipeline");
+const completedChannelReply = Promise.resolve();
 class ZLinkChannelRequestDispatcher {
     options;
     pipeline;
@@ -49,7 +51,7 @@ class ZLinkChannelRequestDispatcher {
             await this.pipeline.dispatchMalformed({
                 info,
                 error,
-                transportRequest: replyToken !== null,
+                transportRequest: replyToken != null,
                 writeProtocolError: replyToken === null
                     ? undefined
                     : (protocolError) => this.submitReply((0, channel_multipart_1.appendParts)(router.reply(received.routingId, replyToken), (0, channel_envelope_1.encodeChannelErrorReplyParts)((0, channel_envelope_inspection_1.malformedProtocolErrorRequestHeader)(this.options.channelName, info), protocolError)), signal)
@@ -124,9 +126,9 @@ class ZLinkChannelRequestDispatcher {
             writeError: (error) => this.submitReply((0, channel_multipart_1.appendParts)(router.reply(received.routingId, replyToken), (0, channel_envelope_1.encodeChannelErrorReplyParts)(envelope.header, error)), signal)
         });
     }
-    async dispatchMesh(record, signal) {
+    dispatchMesh(record, signal, admit) {
         if (record.parts.length === 0 || record.parts[0].data().length === 0) {
-            return;
+            return completedChannelReply;
         }
         let envelope;
         try {
@@ -134,16 +136,15 @@ class ZLinkChannelRequestDispatcher {
         }
         catch (error) {
             const info = (0, channel_envelope_inspection_1.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(record.reply((0, channel_envelope_1.encodeChannelErrorReplyParts)((0, channel_envelope_inspection_1.malformedProtocolErrorRequestHeader)(this.options.channelName, info), protocolError)));
                 }
             });
-            return;
         }
         const packetName = envelope.packetName;
         if (packetName === undefined) {
@@ -151,7 +152,7 @@ class ZLinkChannelRequestDispatcher {
         }
         const correlationId = envelope.header.correlationId ?? undefined;
         if (envelope.header.kind === 3 /* ZLinkChannelMessageKind.Command */) {
-            await this.pipeline.dispatchOneWay({
+            return this.pipeline.dispatchOneWay({
                 fields: {
                     messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
                     packetName,
@@ -164,11 +165,10 @@ class ZLinkChannelRequestDispatcher {
                 handler: this.options.sendHandlers?.get(packetName),
                 context: this.createMeshContext(envelope, record.sourceNodeRid),
                 signal
-            });
-            return;
+            }, admit);
         }
         if (envelope.header.kind !== 1 /* ZLinkChannelMessageKind.Request */) {
-            return;
+            return completedChannelReply;
         }
         const fields = {
             messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request,
@@ -177,28 +177,14 @@ 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((0, channel_envelope_1.encodeChannelReplyParts)(envelope.header, reply, this.options.codecs)));
-            },
-            writeError: async (error) => {
-                requireMeshReplyAccepted(record.reply((0, channel_envelope_1.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);
     }
     submitReply(operation, signal) {
         void signal;
         if (operation.submit() === false) {
             throw new configuration_1.ZLinkConfigurationException('Channel reply was not accepted by Core.');
         }
-        return Promise.resolve();
+        return completedChannelReply;
     }
     createMeshContext(envelope, sourceNodeRid) {
         const base = {
@@ -220,6 +206,42 @@ class ZLinkChannelRequestDispatcher {
     }
 }
 exports.ZLinkChannelRequestDispatcher = 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 {
+    fields;
+    envelope;
+    codecs;
+    handler;
+    context;
+    signal;
+    record;
+    handlerSurface;
+    channelName;
+    constructor(fields, envelope, codecs, handler, context, signal, record, handlerSurface, channelName) {
+        this.fields = fields;
+        this.envelope = envelope;
+        this.codecs = codecs;
+        this.handler = handler;
+        this.context = context;
+        this.signal = signal;
+        this.record = record;
+        this.handlerSurface = handlerSurface;
+        this.channelName = channelName;
+    }
+    get missingHandlerMessage() {
+        return `No ${this.handlerSurface} request handler is registered for '${this.channelName}:${this.fields.packetName}'.`;
+    }
+    writeReply(reply) {
+        requireMeshReplyAccepted(this.record.reply((0, channel_envelope_1.encodeChannelReplyParts)(this.envelope.header, reply, this.codecs)));
+    }
+    writeError(error) {
+        requireMeshReplyAccepted(this.record.reply((0, channel_envelope_1.encodeChannelErrorReplyParts)(this.envelope.header, error)));
+    }
+}
 function requireMeshReplyAccepted(result) {
     if (result !== runtime_values_1.SubmitResult.Ok) {
         throw new configuration_1.ZLinkConfigurationException(`MeshNode channel reply was not accepted (submit result ${result}).`);
@@ -381,7 +403,7 @@ class ZLinkRoutePacketDispatcher {
             await this.pipeline.dispatchMalformed({
                 info,
                 error,
-                transportRequest: replyToken !== null,
+                transportRequest: replyToken != null,
                 sourceRid: String(received.routingId),
                 writeProtocolError: replyToken === null
                     ? undefined
@@ -452,9 +474,9 @@ class ZLinkRoutePacketDispatcher {
             writeError: (error) => this.submitReply((0, channel_multipart_1.appendParts)(router.reply(received.routingId, replyToken), (0, channel_envelope_1.encodeChannelErrorReplyParts)(envelope.header, error)))
         });
     }
-    async dispatchMesh(record, signal) {
+    dispatchMesh(record, signal, admit) {
         if (record.parts.length === 0 || record.parts[0].data().length === 0) {
-            return;
+            return completedChannelReply;
         }
         let envelope;
         try {
@@ -462,16 +484,15 @@ class ZLinkRoutePacketDispatcher {
         }
         catch (error) {
             const info = (0, channel_envelope_inspection_1.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(record.reply((0, channel_envelope_1.encodeChannelErrorReplyParts)((0, channel_envelope_inspection_1.malformedProtocolErrorRequestHeader)(this.routerChannelId, info), protocolError)));
                 }
             });
-            return;
         }
         const packetName = envelope.packetName;
         if (packetName === undefined) {
@@ -480,11 +501,10 @@ class ZLinkRoutePacketDispatcher {
         const sourceNodeRid = String(record.sourceNodeRid ?? '');
         const correlationId = envelope.header.correlationId ?? undefined;
         if (envelope.header.kind === 3 /* ZLinkChannelMessageKind.Command */) {
-            await this.dispatchMeshCommand(envelope, packetName, sourceNodeRid, record.sourceNodeRid, signal);
-            return;
+            return this.dispatchMeshCommand(envelope, packetName, sourceNodeRid, record.sourceNodeRid, signal, admit);
         }
         if (envelope.header.kind !== 1 /* ZLinkChannelMessageKind.Request */) {
-            return;
+            return completedChannelReply;
         }
         const fields = {
             messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request,
@@ -494,22 +514,7 @@ class ZLinkRoutePacketDispatcher {
             flowId: envelope.header.flowId,
             flowOrigin: envelope.header.flowOrigin
         };
-        const codecs = (0, channel_framework_packets_1.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((0, channel_envelope_1.encodeChannelReplyParts)(envelope.header, reply, codecs)));
-            },
-            writeError: async (error) => {
-                requireMeshReplyAccepted(record.reply((0, channel_envelope_1.encodeChannelErrorReplyParts)(envelope.header, error)));
-            }
-        });
+        return this.pipeline.dispatchRequest(new ZLinkMeshRequestDispatch(fields, envelope, (0, channel_framework_packets_1.codecsForFrameworkPacket)(packetName, this.codecs), this.requestHandlers.get(packetName), this.createRouteContext(envelope, record.sourceNodeRid), signal, record, 'routed', this.routerChannelId), admit);
     }
     async dispatchLocalCommand(parts, sourceNodeRid, signal) {
         if (parts.length === 0 || parts[0].data().length === 0)
@@ -537,7 +542,7 @@ class ZLinkRoutePacketDispatcher {
         }
         await this.dispatchMeshCommand(envelope, packetName, String(sourceNodeRid), sourceNodeRid, signal);
     }
-    dispatchMeshCommand(envelope, packetName, sourceRid, sourceNodeRid, signal) {
+    dispatchMeshCommand(envelope, packetName, sourceRid, sourceNodeRid, signal, admit) {
         return this.pipeline.dispatchOneWay({
             fields: {
                 messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
@@ -552,13 +557,13 @@ class ZLinkRoutePacketDispatcher {
             handler: this.sendHandlers.get(packetName),
             context: this.createRouteContext(envelope, sourceNodeRid),
             signal
-        });
+        }, admit);
     }
     submitReply(operation) {
         if (operation.submit() === false) {
             throw new configuration_1.ZLinkConfigurationException('Route reply was not accepted by Core.');
         }
-        return Promise.resolve();
+        return completedChannelReply;
     }
     createRouteContext(envelope, sourceRid) {
         const sourceNodeRid = String(sourceRid ?? '');
@@ -573,3 +578,6 @@ class ZLinkRoutePacketDispatcher {
     }
 }
 exports.ZLinkRoutePacketDispatcher = ZLinkRoutePacketDispatcher;
+function isMeshRequest(record) {
+    return record.kind === service_runtime_contracts_1.ReceiveKind.NodeRequest || record.kind === service_runtime_contracts_1.ReceiveKind.ChannelRequest;
+}

package/dist/runtime/channels/channel-envelope-inspection.d.ts

@@ -1,6 +1,6 @@
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkFlowOrigin } from '../../contracts';
-import { ZLinkChannelMessageKind, type ZLinkChannelEnvelopeHeader } from './channel-envelope';
+import { type ZLinkChannelEnvelopeHeader } from './channel-envelope';
 export declare function tryDecodeChannelHeader(parts: readonly Message[], flowEnabled?: boolean): ZLinkChannelEnvelopeHeader | undefined;
 /**
  * Identifiers salvaged from a malformed channel envelope. Spec 27 §7: a
@@ -9,7 +9,6 @@ export declare function tryDecodeChannelHeader(parts: readonly Message[], flowEn
  * present only when it is individually well-formed.
  */
 export interface ZLinkMalformedChannelHeaderInfo {
-    readonly kind?: ZLinkChannelMessageKind;
     readonly channelName?: string;
     readonly messageName?: string;
     readonly correlationId?: string;

package/dist/runtime/channels/channel-envelope-inspection.js

@@ -29,15 +29,12 @@ function inspectMalformedChannelHeader(parts, flowEnabled) {
     catch {
         return {};
     }
-    if (header.formatMarker !== channel_envelope_1.ZLINK_CHANNEL_FORMAT_MARKER)
-        return {};
     const flowId = typeof header.flowId === 'string' && CHANNEL_FLOW_ID_PATTERN.test(header.flowId)
         ? header.flowId
         : undefined;
     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),
@@ -66,23 +63,11 @@ function malformedProtocolErrorRequestHeader(channelName, info) {
     };
 }
 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) {
-    return value === 1 /* ZLinkChannelMessageKind.Request */ ||
-        value === 2 /* ZLinkChannelMessageKind.Response */ ||
-        value === 3 /* ZLinkChannelMessageKind.Command */ ||
-        value === 4 /* ZLinkChannelMessageKind.Publish */ ||
-        value === 5 /* ZLinkChannelMessageKind.Error */
-        ? value
-        : undefined;
-}
 function salvageString(value) {
     return typeof value === 'string' && value.length > 0 ? value : undefined;
 }
 function salvageCorrelationId(value) {
-    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' && (0, channel_envelope_1.isValidChannelCorrelationId)(value) ? value : undefined;
 }
 function salvageFlowOrigin(value) {
     switch (value) {

package/dist/runtime/channels/channel-envelope.d.ts

@@ -54,6 +54,7 @@ export declare function encodeChannelReplyParts(request: ZLinkChannelEnvelopeHea
  */
 export declare const ZLINK_FRAMEWORK_ORIGIN_METADATA_KEY = "zlink.origin";
 export declare const ZLINK_FRAMEWORK_ORIGIN_METADATA_VALUE = "framework";
+export declare function channelErrorKindFromCode(code: string): ZLinkFrameworkErrorKind | undefined;
 export declare function channelErrorCodeName(kind: ZLinkFrameworkErrorKind): string;
 /**
  * A channel error decoded from an Error reply envelope. `origin` carries the
@@ -71,3 +72,4 @@ export declare function decodeChannelEnvelope(parts: readonly Message[], decoded
 export declare function decodeChannelPayload(envelope: ZLinkChannelEnvelope, codecs?: ZLinkChannelEnvelopeCodecRegistry): unknown;
 export declare function closeMessages(parts: readonly MessageLike[]): void;
 export declare function decodeChannelHeader(parts: readonly Message[], flowEnabled?: boolean): ZLinkChannelEnvelopeHeader;
+export declare function isValidChannelCorrelationId(value: string): boolean;