@zlink-systems/framework 0.31.0 → 0.32.0

package/src/runtime/backend/node/node-raw-binding-port.ts

@@ -42,6 +42,13 @@ import type {
   ZLinkRawRouterRoute,
   ZLinkRawSocketPort
 } from '../raw-binding-port';
+
+interface ZLinkNodeRawRouterSocketOptions {
+  readonly sendHighWaterMark?: number;
+  readonly receiveHighWaterMark?: number;
+  readonly receiveTimeoutMs?: number;
+}
+
 export type {
   ZLinkRawBindingPort,
   ZLinkRawDealerPort,
@@ -57,14 +64,14 @@ export type {
 export class ZLinkNodeRawBindingPort implements ZLinkRawBindingPort {
   constructor(
     private readonly sharedContext?: Context,
-    private readonly routerReceiveTimeoutMs?: number
+    private readonly routerSocketOptions?: ZLinkNodeRawRouterSocketOptions
   ) {}
 
   createHost(): ZLinkRawHostPort {
     return new NodeRawHostPort(
       this.sharedContext ?? createContext(),
       this.sharedContext === undefined,
-      this.routerReceiveTimeoutMs
+      this.routerSocketOptions
     );
   }
 }
@@ -76,13 +83,13 @@ class NodeRawHostPort implements ZLinkRawHostPort {
   constructor(
     private readonly context: Context,
     private readonly ownsContext: boolean,
-    private readonly routerReceiveTimeoutMs?: number
+    private readonly routerSocketOptions?: ZLinkNodeRawRouterSocketOptions
   ) {}
 
   createRouter(): ZLinkRawRouterPort {
     this.requireOpen();
     return this.own(
-      new NodeRawRouterPort(createRouterSocket(this.context), this.routerReceiveTimeoutMs)
+      new NodeRawRouterPort(createRouterSocket(this.context), this.routerSocketOptions)
     );
   }
 
@@ -281,13 +288,19 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
     disconnectSocketPeer(this.socket, this.preparedRoutingId(routingId));
   }
 
-  constructor(socket: RouterSocket, receiveTimeoutMs?: number) {
+  constructor(socket: RouterSocket, options?: ZLinkNodeRawRouterSocketOptions) {
     super(socket, true);
     socket.options.handover = true;
     socket.options.mandatory = true;
     socket.options.probe = true;
-    if (receiveTimeoutMs !== undefined) {
-      socket.options.recvTimeout = receiveTimeoutMs;
+    if (options?.sendHighWaterMark !== undefined) {
+      socket.options.sendHwm = BigInt(options.sendHighWaterMark);
+    }
+    if (options?.receiveHighWaterMark !== undefined) {
+      socket.options.recvHwm = BigInt(options.receiveHighWaterMark);
+    }
+    if (options?.receiveTimeoutMs !== undefined) {
+      socket.options.recvTimeout = options.receiveTimeoutMs;
     }
   }
 

package/src/runtime/backend/node/node-raw-mesh-backend.ts

@@ -190,7 +190,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   private readonly lifecycleGeneration: bigint;
   private bindEndpoint?: string;
   private advertiseHost?: string;
-  private runtime?: RawServiceMeshRuntime;
+  runtime?: RawServiceMeshRuntime;
   private stateful?: ServiceStatefulRuntime;
   private readyHandler?: (domains: number) => number;
   private maintenanceTimer?: NodeJS.Timeout;
@@ -629,6 +629,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
       peer.securityIdentity,
       peer.lifecycleGeneration
     );
+    this.scheduleMaintenance();
   }
 
   removePeerConnection(intentId: bigint): void {
@@ -1690,7 +1691,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     this.requireStateful().clearSubscriptions(state.ref.spotId);
   }
 
-  private createDescriptor(): ServiceNodeDescriptor {
+  createDescriptor(): ServiceNodeDescriptor {
     const channels: ServiceChannelDescriptor[] = [...this.channels]
       .map(([name, weight]) => ({ name, weight }))
       .sort((left, right) => left.name.localeCompare(right.name));
@@ -2559,6 +2560,9 @@ function completionRecord(
     kindData: 'kindData' in result ? (result.kindData ?? null) : null,
     terminalResult: result.terminalResult,
     failureErrno: result.failureCode,
+    ...('failureMessage' in result && result.failureMessage !== undefined
+      ? { failureMessage: result.failureMessage }
+      : {}),
     parts:
       payload === undefined
         ? []
@@ -2808,9 +2812,9 @@ function decodeStatefulRecord(
       });
       return accepted ? SubmitResult.Ok : SubmitResult.InvalidState;
     },
-    replyFailure(terminalResult, failureCode) {
+    replyFailure(terminalResult, failureCode, tail) {
       if (stateful.reply === undefined) return SubmitResult.InvalidState;
-      return stateful.reply(terminalResult, failureCode)
+      return stateful.reply(terminalResult, failureCode, undefined, tail)
         ? SubmitResult.Ok
         : SubmitResult.InvalidState;
     }
@@ -2818,16 +2822,20 @@ function decodeStatefulRecord(
 }
 
 function receiveIngressLifecycle(record: ServiceMailboxRecord): {
+  readonly receivedAt?: Date;
   readonly applicationJobPermit?: import('../../application-jobs/contracts').ApplicationJobPermitPort;
   readonly releaseRetainedIngress?: () => void;
 } {
   const applicationJob = record.applicationJob;
-  return applicationJob === undefined
-    ? {}
-    : {
-        applicationJobPermit: applicationJob,
-        releaseRetainedIngress: () => applicationJob.close()
-      };
+  return {
+    ...(record.receivedAt === undefined ? {} : { receivedAt: record.receivedAt }),
+    ...(applicationJob === undefined
+      ? {}
+      : {
+          applicationJobPermit: applicationJob,
+          releaseRetainedIngress: () => applicationJob.close()
+        })
+  };
 }
 
 function prepareStatefulMailboxDispatch(

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

@@ -84,10 +84,10 @@ export interface ZLinkRequestDispatch<TContext extends ZLinkMessageContext> {
 }
 
 export class ZLinkChannelDispatchPipeline {
-  private readonly filters: readonly ZLinkHandlerFilter[];
+  readonly filters: readonly ZLinkHandlerFilter[];
   private readonly unhandled: ZLinkUnhandledDispatchOptions;
 
-  constructor(private readonly options: ZLinkChannelDispatchPipelineOptions) {
+  constructor(readonly options: ZLinkChannelDispatchPipelineOptions) {
     this.filters = options.filters ?? [];
     this.unhandled = options.unhandled ?? DEFAULT_UNHANDLED_DISPATCH;
   }
@@ -203,7 +203,7 @@ export class ZLinkChannelDispatchPipeline {
     }
   }
 
-  private invokeInFlow<TContext extends ZLinkMessageContext, TResult>(
+  invokeInFlow<TContext extends ZLinkMessageContext, TResult>(
     dispatch: ZLinkOneWayDispatch<TContext> | ZLinkRequestDispatch<TContext>,
     handler: ZLinkChannelDispatchHandler<TContext, TResult>
   ): unknown {
@@ -330,7 +330,7 @@ export class ZLinkChannelDispatchPipeline {
     });
   }
 
-  private invoke<TContext extends ZLinkMessageContext, TResult>(
+  invoke<TContext extends ZLinkMessageContext, TResult>(
     dispatch: ZLinkOneWayDispatch<TContext> | ZLinkRequestDispatch<TContext>,
     handler: ZLinkChannelDispatchHandler<TContext, TResult>
   ):
@@ -409,6 +409,7 @@ export class ZLinkChannelDispatchPipeline {
       contentType: context.contentType,
       metadata: context.metadata,
       correlationId: context.correlationId,
+      receivedAt: context.receivedAt,
       dispatchKind
     };
   }
@@ -456,7 +457,7 @@ export class ZLinkChannelDispatchPipeline {
     });
   }
 
-  private trace(outcome: ZLinkMessageFlowOutcome, fields: ZLinkChannelDispatchFields): void {
+  trace(outcome: ZLinkMessageFlowOutcome, fields: ZLinkChannelDispatchFields): void {
     if (fields.messageKind === ZLinkDispatchMessageKind.Publish) return;
     const flow = this.options.dispatchErrors.flow;
     const tracePoint = flow.begin(outcome, undefined, fields.flowId);

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

@@ -50,6 +50,7 @@ import {
 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.
@@ -124,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) {
@@ -185,7 +187,8 @@ export class ZLinkChannelRequestDispatcher {
         contentType: envelope.header.contentType,
         packetName,
         metadata: zlinkMessageMetadata(envelope.header.metadata),
-        correlationId
+        correlationId,
+        receivedAt
       };
       await this.pipeline.dispatchOneWay({
         fields,
@@ -221,7 +224,8 @@ export class ZLinkChannelRequestDispatcher {
       contentType: envelope.header.contentType,
       packetName,
       metadata: zlinkMessageMetadata(envelope.header.metadata),
-      correlationId
+      correlationId,
+      receivedAt
     };
     await this.pipeline.dispatchRequest({
       fields: requestFields,
@@ -301,7 +305,7 @@ export class ZLinkChannelRequestDispatcher {
           codecs: this.options.codecs,
           handler: handler?.handler,
           messageType: handler?.messageType,
-          context: this.createMeshContext(envelope, record.sourceNodeRid),
+          context: this.createMeshContext(envelope, record.sourceNodeRid, record.receivedAt),
           signal
         },
         admit
@@ -323,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',
@@ -346,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,
@@ -354,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;
@@ -424,6 +430,7 @@ 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<
@@ -455,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;
@@ -507,7 +515,8 @@ export class ZLinkChannelPublishDispatcher {
       topic: publishTopic,
       source: publishSource,
       metadata: zlinkMessageMetadata(envelope.header.metadata),
-      correlationId: publishCorr
+      correlationId: publishCorr,
+      receivedAt
     };
     await this.pipeline.dispatchOneWay({
       fields,
@@ -523,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[];
@@ -557,11 +567,13 @@ export class ZLinkRoutePacketDispatcher {
     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,
@@ -635,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());
@@ -699,7 +712,7 @@ export class ZLinkRoutePacketDispatcher {
         codecs: codecsForFrameworkPacket(packetName, this.codecs),
         handler: handler?.handler,
         messageType: handler?.messageType,
-        context: this.createRouteContext(envelope, received.routingId),
+        context: this.createRouteContext(envelope, received.routingId, receivedAt),
         signal
       });
       return;
@@ -738,7 +751,7 @@ export class ZLinkRoutePacketDispatcher {
       codecs,
       handler: handler?.handler,
       messageType: handler?.messageType,
-      context: this.createRouteContext(envelope, received.routingId),
+      context: this.createRouteContext(envelope, received.routingId, receivedAt),
       signal,
       missingHandlerMessage: `No routed request handler is registered for '${this.routerChannelId}:${packetName}'.`,
       writeReply: (reply) =>
@@ -801,7 +814,8 @@ export class ZLinkRoutePacketDispatcher {
         sourceNodeRid,
         record.sourceNodeRid,
         signal,
-        admit
+        admit,
+        record.receivedAt ?? this.receivedAtClock()
       );
     }
     if (envelope.header.kind !== ZLinkChannelMessageKind.Request) {
@@ -821,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',
@@ -836,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 {
@@ -864,7 +879,9 @@ export class ZLinkRoutePacketDispatcher {
       packetName,
       String(sourceNodeRid),
       sourceNodeRid,
-      signal
+      signal,
+      undefined,
+      receivedAt
     );
   }
 
@@ -874,7 +891,8 @@ 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(
@@ -891,7 +909,7 @@ export class ZLinkRoutePacketDispatcher {
         codecs: codecsForFrameworkPacket(packetName, this.codecs),
         handler: handler?.handler,
         messageType: handler?.messageType,
-        context: this.createRouteContext(envelope, sourceNodeRid),
+        context: this.createRouteContext(envelope, sourceNodeRid, receivedAt),
         signal
       },
       admit
@@ -907,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 {
@@ -916,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
     };
   }
 }