@zlink-systems/framework 0.27.0 → 0.29.0

package/src/runtime/streams/stream-session-runtime.ts

@@ -61,12 +61,10 @@ import {
 import { createSessionDispatchContext, DefaultZLinkSessionContext } from './session-context';
 import { ZLinkSessionSerialExecutor } from './session-serial-executor';
 import { ownedMessage } from './stream-message-utils';
+import { normalizeStreamLiveness } from '../../contracts/Configuration/RegistrationNormalizers';
 
 const ZLINK_SEND_DONT_WAIT = 1;
 const ZLINK_RECV_DONT_WAIT = 1;
-const ZLINK_STREAM_HEARTBEAT_INTERVAL_MS = 1_000;
-const ZLINK_STREAM_HEARTBEAT_TIMEOUT_MS = 5_000;
-const ZLINK_STREAM_APPLICATION_IDLE_TIMEOUT_MS = 30_000;
 const ZLINK_STREAM_RECEIVE_FRAME_BATCH_LIMIT = 64;
 const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CLOSE_DELAY_MS = 100;
 const ZLINK_STREAM_MONITOR_IDLE_MIN_DELAY_MS = 1;
@@ -89,9 +87,11 @@ interface ZLinkStreamLivenessOptions {
   readonly claimApplicationWork?: () => ZLinkApplicationWorkClaim;
 }
 
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
 const systemLivenessClock: ZLinkStreamLivenessClock = {
   now: () => performance.now(),
-  setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+  setTimer: (callback, delayMs) => setTimeout(callback, Math.min(delayMs, MAX_TIMER_DELAY_MS)),
   clearTimer: (timer) => clearTimeout(timer as ReturnType<typeof setTimeout>)
 };
 
@@ -127,6 +127,9 @@ export interface ZLinkStreamSessionContextFactory {
 }
 
 export interface ZLinkStreamSessionRuntimeOptions {
+  readonly heartbeatIntervalMs?: number;
+  readonly heartbeatTimeoutMs?: number;
+  readonly idleTimeoutMs?: number;
   readonly socket: ZLinkBackendStreamSocket;
   readonly nativeSessionService?: StreamSessionService;
   readonly meshCompletions?: ZLinkMeshCompletionTable;
@@ -165,8 +168,10 @@ export class ZLinkStreamSessionRuntime {
   private closeReason = 'client_close';
   private metricsClosed = false;
   private readonly livenessClock: ZLinkStreamLivenessClock;
+  private readonly liveness: ReturnType<typeof normalizeStreamLiveness>;
   private lastApplicationActivityAt = 0;
   private lastInboundFrameAt = 0;
+  private lastHeartbeatPingAt = 0;
   private livenessTimer: unknown;
 
   constructor(
@@ -177,6 +182,7 @@ export class ZLinkStreamSessionRuntime {
       session: ZLinkStreamSessionRuntime
     ) => void = () => {}
   ) {
+    this.liveness = normalizeStreamLiveness(options);
     this.livenessClock = options.livenessClock ?? systemLivenessClock;
     this.stream = new ZLinkManagedStream(
       options.socket,
@@ -238,7 +244,7 @@ export class ZLinkStreamSessionRuntime {
   }
 
   enqueueConnected(localAddr?: string, remoteAddr?: string): void {
-    this.serial.executeInfrastructure(async () => this.markConnected(localAddr, remoteAddr));
+    this.serial.executeControl(async () => this.markConnected(localAddr, remoteAddr));
   }
 
   enqueuePacket(
@@ -255,46 +261,22 @@ export class ZLinkStreamSessionRuntime {
       terminalOwner?.close();
     };
     if (decodedHeader.kind === ZLinkStreamMessageKind.Control) {
-      if (
-        messageToBytes(payload).length === 0 &&
-        (decodedHeader.name === ZLINK_STREAM_HEARTBEAT_PONG ||
-          decodedHeader.name === ZLINK_STREAM_HEARTBEAT_PING)
-      ) {
-        void this.handleControl(decodedHeader, payload)
-          .catch((error) => {
-            this.options.onError?.(error);
-          })
-          .finally(() => {
-            applicationJobPermit?.releaseAfterInternalProcessing();
-            payload.close();
-            releaseTerminal();
-          });
-        return;
-      }
-      this.enqueueControl(
-        async () => {
-          try {
-            const dispatch = () => this.dispatchPacket(payload, decodedHeader);
-            if (applicationJobPermit === undefined) await dispatch();
-            else await runWithApplicationJobPermit(applicationJobPermit, dispatch);
-          } finally {
-            releaseTerminal();
-          }
-        },
-        () => {
+      void this.handleControl(decodedHeader, payload)
+        .catch((error) => {
+          this.options.onError?.(error);
+        })
+        .finally(() => {
           applicationJobPermit?.releaseAfterInternalProcessing();
           payload.close();
           releaseTerminal();
-        },
-        () => this.traceShutdownDrop(decodedHeader)
-      );
+        });
       return;
     }
     if (
       decodedHeader.kind === ZLinkStreamMessageKind.Response ||
       decodedHeader.kind === ZLinkStreamMessageKind.Error
     ) {
-      this.enqueueInfrastructure(
+      this.enqueueControl(
         async () => {
           try {
             await this.dispatchPacket(payload, decodedHeader);
@@ -340,8 +322,7 @@ export class ZLinkStreamSessionRuntime {
   }
 
   /**
-   * Starts the callback on the session lane and observes its terminal result
-   * without retaining that lane while application code awaits unrelated work.
+   * Retains the session turn through the callback's terminal result.
    */
   enqueueActorBindingReplaced(
     actor: ServiceActorRef,
@@ -352,7 +333,6 @@ export class ZLinkStreamSessionRuntime {
       if (!this.context.beginActorBindingReplacement(actor, retiredSession)) return;
       const session = await this.requireSession();
       let callbackDeadlineTimer: unknown;
-      let callbackTerminal = false;
       let forcedClose = false;
       const scheduleClose = (): void => {
         if (forcedClose) return;
@@ -367,23 +347,6 @@ export class ZLinkStreamSessionRuntime {
           void this.close().catch((error) => this.options.onError?.(error));
         }, ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CLOSE_DELAY_MS);
       };
-      const completeCallback = (): void => {
-        if (callbackTerminal) return;
-        callbackTerminal = true;
-        if (callbackDeadlineTimer !== undefined) {
-          this.livenessClock.clearTimer(callbackDeadlineTimer);
-          callbackDeadlineTimer = undefined;
-        }
-        scheduleClose();
-      };
-      const reportCallbackFailure = (error: unknown): void => {
-        try {
-          this.options.onError?.(error);
-        } catch {
-          // Diagnostics must not prevent the lifecycle terminal transition.
-        }
-        completeCallback();
-      };
       callbackDeadlineTimer = this.livenessClock.setTimer(() => {
         if (
           this.disposed ||
@@ -396,18 +359,15 @@ export class ZLinkStreamSessionRuntime {
         void this.close().catch((error) => this.options.onError?.(error));
       }, this.options.replacementCallbackTimeoutMs ?? DEFAULT_SESSION_REPLACEMENT_CALLBACK_TIMEOUT_MS);
 
-      const callback = session.onActorBindingReplaced;
-      if (callback === undefined) {
-        completeCallback();
-        return;
-      }
       try {
-        // Start the callback on this lifecycle turn, but do not retain the
-        // serial lane while application code awaits an unrelated operation.
-        const result = callback.call(session, this.context, actor.actorId);
-        void Promise.resolve(result).then(() => completeCallback(), reportCallbackFailure);
+        await session.onActorBindingReplaced?.(this.context, actor.actorId);
       } catch (error) {
-        reportCallbackFailure(error);
+        this.options.onError?.(error);
+      } finally {
+        if (callbackDeadlineTimer !== undefined) {
+          this.livenessClock.clearTimer(callbackDeadlineTimer);
+        }
+        scheduleClose();
       }
     });
   }
@@ -460,6 +420,7 @@ export class ZLinkStreamSessionRuntime {
     this.connected = true;
     const connectedAt = this.livenessClock.now();
     this.lastApplicationActivityAt = connectedAt;
+    this.lastHeartbeatPingAt = connectedAt;
     this.lastInboundFrameAt = Math.max(this.lastInboundFrameAt, connectedAt);
     this.scheduleLivenessCheck();
     this.options.metrics?.change(METRIC_NAMES.StreamConnectionsActive, 1, { transport: 'tcp' });
@@ -475,15 +436,8 @@ export class ZLinkStreamSessionRuntime {
     let dispatchPayload = payload;
     let enteredDispatch = false;
     try {
-      if (decodedHeader.kind === ZLinkStreamMessageKind.Control) {
-        await this.handleControl(decodedHeader, payload);
-        return;
-      }
       this.lastApplicationActivityAt = this.livenessClock.now();
       dispatchPayload = this.context.payloadForHeader(decodedHeader, payload);
-      if (this.context.tryCompleteResponse(decodedHeader, dispatchPayload)) {
-        return;
-      }
       const dispatchActor = this.context.actorForSlot(decodedHeader.actorSlot);
       if (decodedHeader.actorSlot !== undefined && dispatchActor === undefined) {
         const staleFlowEnabled = this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true;
@@ -674,14 +628,21 @@ export class ZLinkStreamSessionRuntime {
     if (this.disposed || this.disconnected || this.livenessTimer !== undefined) {
       return;
     }
-    this.livenessTimer = this.livenessClock.setTimer(() => {
-      this.livenessTimer = undefined;
-      this.serial.executeInfrastructure(
-        async () => this.runLivenessCheck(),
-        {},
-        (error) => this.options.onError?.(error)
-      );
-    }, ZLINK_STREAM_HEARTBEAT_INTERVAL_MS);
+    const now = this.livenessClock.now();
+    const due = Math.min(
+      this.lastHeartbeatPingAt + this.liveness.heartbeatIntervalMs,
+      this.lastInboundFrameAt + this.liveness.heartbeatTimeoutMs,
+      this.liveness.idleTimeoutMs > 0
+        ? this.lastApplicationActivityAt + this.liveness.idleTimeoutMs
+        : Infinity
+    );
+    this.livenessTimer = this.livenessClock.setTimer(
+      () => {
+        this.livenessTimer = undefined;
+        void this.runLivenessCheck().catch((error) => this.options.onError?.(error));
+      },
+      Math.max(0, due - now)
+    );
   }
 
   private async runLivenessCheck(): Promise<void> {
@@ -689,7 +650,10 @@ export class ZLinkStreamSessionRuntime {
       return;
     }
     const now = this.livenessClock.now();
-    if (now - this.lastApplicationActivityAt >= ZLINK_STREAM_APPLICATION_IDLE_TIMEOUT_MS) {
+    if (
+      this.liveness.idleTimeoutMs > 0 &&
+      now - this.lastApplicationActivityAt >= this.liveness.idleTimeoutMs
+    ) {
       await this.closeForLiveness(
         ZLinkStreamCloseReasonCode.IdleTimeout,
         'idle_timeout',
@@ -697,7 +661,7 @@ export class ZLinkStreamSessionRuntime {
       );
       return;
     }
-    if (now - this.lastInboundFrameAt >= ZLINK_STREAM_HEARTBEAT_TIMEOUT_MS) {
+    if (now - this.lastInboundFrameAt >= this.liveness.heartbeatTimeoutMs) {
       await this.closeForLiveness(
         ZLinkStreamCloseReasonCode.HeartbeatTimeout,
         'heartbeat_timeout',
@@ -705,7 +669,10 @@ export class ZLinkStreamSessionRuntime {
       );
       return;
     }
-    await this.stream.writeControl(ZLINK_STREAM_HEARTBEAT_PING);
+    if (now - this.lastHeartbeatPingAt >= this.liveness.heartbeatIntervalMs) {
+      this.lastHeartbeatPingAt = now;
+      await this.stream.writeControl(ZLINK_STREAM_HEARTBEAT_PING);
+    }
     this.scheduleLivenessCheck();
   }
 
@@ -722,7 +689,9 @@ export class ZLinkStreamSessionRuntime {
     this.closeReason = closeReason;
     this.stopLivenessChecks();
     await this.stream.closeForReason(reason, diagnostic);
-    await this.complete(undefined, true);
+    void this.serial
+      .executeFinal(async () => this.complete(undefined, true))
+      .catch((error) => this.options.onError?.(error));
   }
 
   private stopLivenessChecks(): void {
@@ -853,18 +822,6 @@ export class ZLinkStreamSessionRuntime {
     }
   }
 
-  private enqueueInfrastructure(
-    work: () => Promise<void>,
-    onRejected?: () => void,
-    onShutdownRejected?: () => void
-  ): void {
-    if (!this.serial.executeInfrastructure(work, {}, onRejected)) {
-      // The serial lane only refuses new work after dispose() closed it.
-      onShutdownRejected?.();
-      onRejected?.();
-    }
-  }
-
   private enqueueApplication(
     work: () => Promise<void>,
     onRejected?: (error?: unknown) => void,

package/dist/runtime/streams/session-requests.d.ts

@@ -1,25 +0,0 @@
-import type { Message } from '../../contracts/Common/Message';
-export declare class ZLinkPendingSessionRequest {
-    private readonly tracker;
-    readonly requestSeq: bigint;
-    private completed;
-    private readonly timeout;
-    private resolvePromise;
-    private rejectPromise;
-    readonly promise: Promise<Message>;
-    constructor(tracker: ZLinkSessionRequestTracker, requestSeq: bigint, timeoutMs: number | undefined);
-    complete(payload: Message): void;
-    fail(error: unknown): void;
-    cancel(): void;
-    dispose(): void;
-    private clearTimeout;
-}
-export declare class ZLinkSessionRequestTracker {
-    private readonly pending;
-    private nextRequestSeq;
-    start(timeoutMs?: number): ZLinkPendingSessionRequest;
-    complete(requestSeq: bigint, payload: Message): boolean;
-    fail(requestSeq: bigint, error: unknown): boolean;
-    remove(requestSeq: bigint): void;
-    private next;
-}

package/dist/runtime/streams/session-requests.js

@@ -1,101 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkSessionRequestTracker = exports.ZLinkPendingSessionRequest = void 0;
-const stream_wire_1 = require("@zlink-systems/stream-wire");
-const stream_message_utils_1 = require("./stream-message-utils");
-class ZLinkPendingSessionRequest {
-    tracker;
-    requestSeq;
-    completed = false;
-    timeout;
-    resolvePromise;
-    rejectPromise;
-    promise;
-    constructor(tracker, requestSeq, timeoutMs) {
-        this.tracker = tracker;
-        this.requestSeq = requestSeq;
-        this.promise = new Promise((resolve, reject) => {
-            this.resolvePromise = resolve;
-            this.rejectPromise = reject;
-        });
-        if (timeoutMs !== undefined) {
-            this.timeout = setTimeout(() => this.cancel(), timeoutMs);
-        }
-    }
-    complete(payload) {
-        if (this.completed) {
-            return;
-        }
-        this.completed = true;
-        this.clearTimeout();
-        this.resolvePromise((0, stream_message_utils_1.copyMessage)(payload));
-    }
-    fail(error) {
-        if (this.completed) {
-            return;
-        }
-        this.completed = true;
-        this.clearTimeout();
-        this.rejectPromise(error);
-    }
-    cancel() {
-        if (this.completed) {
-            return;
-        }
-        this.completed = true;
-        this.clearTimeout();
-        this.tracker.remove(this.requestSeq);
-        this.rejectPromise(new Error('Client stream request timed out.'));
-    }
-    dispose() {
-        this.clearTimeout();
-        this.tracker.remove(this.requestSeq);
-    }
-    clearTimeout() {
-        if (this.timeout !== undefined) {
-            clearTimeout(this.timeout);
-        }
-    }
-}
-exports.ZLinkPendingSessionRequest = ZLinkPendingSessionRequest;
-class ZLinkSessionRequestTracker {
-    pending = new Map();
-    nextRequestSeq = 0n;
-    start(timeoutMs) {
-        const requestSeq = this.next();
-        const pending = new ZLinkPendingSessionRequest(this, requestSeq, timeoutMs);
-        if (this.pending.has(requestSeq)) {
-            throw new Error('Duplicate stream request sequence.');
-        }
-        this.pending.set(requestSeq, pending);
-        return pending;
-    }
-    complete(requestSeq, payload) {
-        const pending = this.pending.get(requestSeq);
-        if (pending === undefined) {
-            return false;
-        }
-        this.pending.delete(requestSeq);
-        pending.complete(payload);
-        return true;
-    }
-    fail(requestSeq, error) {
-        const pending = this.pending.get(requestSeq);
-        if (pending === undefined) {
-            return false;
-        }
-        this.pending.delete(requestSeq);
-        pending.fail(error);
-        return true;
-    }
-    remove(requestSeq) {
-        this.pending.delete(requestSeq);
-    }
-    next() {
-        do {
-            this.nextRequestSeq = (this.nextRequestSeq + 1n) & stream_wire_1.UINT64_MAX;
-        } while (this.nextRequestSeq === 0n);
-        return this.nextRequestSeq;
-    }
-}
-exports.ZLinkSessionRequestTracker = ZLinkSessionRequestTracker;

package/src/runtime/streams/session-requests.ts

@@ -1,110 +0,0 @@
-import { UINT64_MAX } from '@zlink-systems/stream-wire';
-import type { Message } from '../../contracts/Common/Message';
-import { copyMessage } from './stream-message-utils';
-
-export class ZLinkPendingSessionRequest {
-  private completed = false;
-  private readonly timeout: ReturnType<typeof setTimeout> | undefined;
-  private resolvePromise!: (message: Message) => void;
-  private rejectPromise!: (error: unknown) => void;
-  readonly promise: Promise<Message>;
-
-  constructor(
-    private readonly tracker: ZLinkSessionRequestTracker,
-    readonly requestSeq: bigint,
-    timeoutMs: number | undefined
-  ) {
-    this.promise = new Promise<Message>((resolve, reject) => {
-      this.resolvePromise = resolve;
-      this.rejectPromise = reject;
-    });
-    if (timeoutMs !== undefined) {
-      this.timeout = setTimeout(() => this.cancel(), timeoutMs);
-    }
-  }
-
-  complete(payload: Message): void {
-    if (this.completed) {
-      return;
-    }
-    this.completed = true;
-    this.clearTimeout();
-    this.resolvePromise(copyMessage(payload));
-  }
-
-  fail(error: unknown): void {
-    if (this.completed) {
-      return;
-    }
-    this.completed = true;
-    this.clearTimeout();
-    this.rejectPromise(error);
-  }
-
-  cancel(): void {
-    if (this.completed) {
-      return;
-    }
-    this.completed = true;
-    this.clearTimeout();
-    this.tracker.remove(this.requestSeq);
-    this.rejectPromise(new Error('Client stream request timed out.'));
-  }
-
-  dispose(): void {
-    this.clearTimeout();
-    this.tracker.remove(this.requestSeq);
-  }
-
-  private clearTimeout(): void {
-    if (this.timeout !== undefined) {
-      clearTimeout(this.timeout);
-    }
-  }
-}
-
-export class ZLinkSessionRequestTracker {
-  private readonly pending = new Map<bigint, ZLinkPendingSessionRequest>();
-  private nextRequestSeq = 0n;
-
-  start(timeoutMs?: number): ZLinkPendingSessionRequest {
-    const requestSeq = this.next();
-    const pending = new ZLinkPendingSessionRequest(this, requestSeq, timeoutMs);
-    if (this.pending.has(requestSeq)) {
-      throw new Error('Duplicate stream request sequence.');
-    }
-    this.pending.set(requestSeq, pending);
-    return pending;
-  }
-
-  complete(requestSeq: bigint, payload: Message): boolean {
-    const pending = this.pending.get(requestSeq);
-    if (pending === undefined) {
-      return false;
-    }
-    this.pending.delete(requestSeq);
-    pending.complete(payload);
-    return true;
-  }
-
-  fail(requestSeq: bigint, error: unknown): boolean {
-    const pending = this.pending.get(requestSeq);
-    if (pending === undefined) {
-      return false;
-    }
-    this.pending.delete(requestSeq);
-    pending.fail(error);
-    return true;
-  }
-
-  remove(requestSeq: bigint): void {
-    this.pending.delete(requestSeq);
-  }
-
-  private next(): bigint {
-    do {
-      this.nextRequestSeq = (this.nextRequestSeq + 1n) & UINT64_MAX;
-    } while (this.nextRequestSeq === 0n);
-    return this.nextRequestSeq;
-  }
-}