@zlink-systems/framework 0.30.3 → 0.32.0

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

@@ -1,3 +1,6 @@
+import { requireOneWayCompletion } from '../messaging/submission-result';
+import { logs, SeverityNumber } from '@opentelemetry/api-logs';
+import { ZlinkStreamControlPacket } from '@zlink-systems/stream-wire';
 import type { RoutingId, ZLinkMessageSerializer, ZLinkSession } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
@@ -30,6 +33,7 @@ import type {
 import type { ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
 import { ZLinkDispatchErrorReporter, ZLinkRouteDisconnectedError } from '../channels';
 import { type ZLinkRuntimeMetrics, flowIfEnabled } from '../diagnostics';
+import { TELEMETRY_INSTRUMENTATION_NAME } from '../diagnostics/message-flow-record';
 
 import { createInboundFlow, runWithFlow } from '../diagnostics/flow-context';
 import { ZLinkSocketNativeEventType } from '../diagnostics/internal-event-contracts';
@@ -63,7 +67,6 @@ 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_RECEIVE_FRAME_BATCH_LIMIT = 64;
 const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CLOSE_DELAY_MS = 100;
@@ -88,6 +91,7 @@ interface ZLinkStreamLivenessOptions {
 }
 
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const STREAM_RUNTIME_LOGGER = logs.getLogger(TELEMETRY_INSTRUMENTATION_NAME);
 
 const systemLivenessClock: ZLinkStreamLivenessClock = {
   now: () => performance.now(),
@@ -504,7 +508,6 @@ export class ZLinkStreamSessionRuntime {
                 this.context.routingId === undefined ? undefined : String(this.context.routingId)
             }
           );
-          releaseApplicationJobPermitBeforeHandler();
           flowIfEnabled(
             this.options.dispatchErrors?.flow,
             ZLinkMessageFlowOutcome.Dispatched
@@ -517,15 +520,20 @@ export class ZLinkStreamSessionRuntime {
             sourceRid:
               this.context.routingId === undefined ? undefined : String(this.context.routingId)
           });
-          await session.onDispatch?.(
-            createSessionDispatchContext(inboundHeader, dispatchActor),
-            wrapFrameworkPayloadMessage(
+          if (session.onDispatch !== undefined) {
+            const sessionDispatchContext = createSessionDispatchContext(
+              inboundHeader,
+              dispatchActor
+            );
+            const frameworkPayload = wrapFrameworkPayloadMessage(
               dispatchPayload,
               this.options.messageSerializers,
               streamCodecContentType(inboundHeader.codec),
               inboundHeader.name
-            )
-          );
+            );
+            releaseApplicationJobPermitBeforeHandler();
+            await session.onDispatch(sessionDispatchContext, frameworkPayload);
+          }
           if (streamKind === ZLinkDispatchMessageKind.Send) {
             flowIfEnabled(
               this.options.dispatchErrors?.flow,
@@ -579,19 +587,33 @@ export class ZLinkStreamSessionRuntime {
   }
 
   private async handleControl(header: ZLinkStreamFrameHeader, payload: Message): Promise<void> {
-    if (messageToBytes(payload).length !== 0) {
+    const payloadBytes = messageToBytes(payload);
+    if (header.name === ZLINK_STREAM_HEARTBEAT_PING) {
+      if (payloadBytes.length !== 0) {
+        this.logIgnoredControl(header.name, payloadBytes.length);
+      }
+      await this.stream.writeControl(ZLINK_STREAM_HEARTBEAT_PONG);
+      return;
+    }
+    if (header.name === ZLINK_STREAM_HEARTBEAT_PONG) {
+      if (payloadBytes.length !== 0) {
+        this.logIgnoredControl(header.name, payloadBytes.length);
+      }
+      return;
+    }
+    if (
+      header.name === ZlinkStreamControlPacket.ActorBound ||
+      header.name === ZlinkStreamControlPacket.ActorUnbound
+    ) {
       await this.closeForLiveness(
         ZLinkStreamCloseReasonCode.ProtocolError,
         'protocol_error',
-        'Control heartbeat payload must be empty.'
+        `Unexpected stream actor control frame: ${header.name}`
       );
       return;
     }
-    if (header.name === ZLINK_STREAM_HEARTBEAT_PONG) {
-      return;
-    }
-    if (header.name === ZLINK_STREAM_HEARTBEAT_PING) {
-      await this.stream.writeControl(ZLINK_STREAM_HEARTBEAT_PONG);
+    if (header.name.startsWith('$zlink.')) {
+      this.logIgnoredControl(header.name, payloadBytes.length);
       return;
     }
     await this.closeForLiveness(
@@ -601,6 +623,21 @@ export class ZLinkStreamSessionRuntime {
     );
   }
 
+  private logIgnoredControl(name: string, payloadLength: number): void {
+    STREAM_RUNTIME_LOGGER.emit({
+      eventName: 'zlink.stream.control_ignored',
+      timestamp: new Date(),
+      severityNumber: SeverityNumber.DEBUG,
+      severityText: 'DEBUG',
+      body: `Ignored STREAM control name=${name} payloadBytes=${payloadLength} peerSessionRid=${this.stream.sessionId}`,
+      attributes: {
+        control_name: name,
+        payload_bytes: payloadLength,
+        peer_session_rid: this.stream.sessionId
+      }
+    });
+  }
+
   private scheduleLivenessCheck(): void {
     if (this.disposed || this.disconnected || this.livenessTimer !== undefined) {
       return;
@@ -666,9 +703,11 @@ export class ZLinkStreamSessionRuntime {
     this.closeReason = closeReason;
     this.stopLivenessChecks();
     await this.stream.closeForReason(reason, diagnostic);
-    void this.serial
-      .executeFinal(async () => this.complete(undefined, true))
-      .catch((error) => this.options.onError?.(error));
+    const bindingsCleanup = this.context.cleanupBindings();
+    void Promise.all([
+      bindingsCleanup,
+      this.serial.executeFinal(async () => this.complete(undefined, true, bindingsCleanup))
+    ]).catch((error) => this.options.onError?.(error));
   }
 
   private stopLivenessChecks(): void {
@@ -688,22 +727,18 @@ export class ZLinkStreamSessionRuntime {
       // record (spec 26 §2.2) and confuse the peer's reply matching.
       return;
     }
-    const message = this.context.createJsonReplyFrameMessage(
-      header,
-      ZLinkStreamMessageKind.Error,
-      new Map(),
-      false,
-      boundSessionErrorPayload(error)
-    );
     try {
-      if (!this.context.stream.writeRaw(message, ZLINK_SEND_DONT_WAIT)) {
-        throw new Error('Client stream error reply send failed.');
-      }
+      const result = await this.context.submitReply(
+        header,
+        ZLinkStreamMessageKind.Error,
+        new Map(),
+        false,
+        boundSessionErrorPayload(error)
+      );
+      requireOneWayCompletion(result, 'Client stream error reply');
       this.traceFrameWritten(ZLinkStreamMessageKind.Error, header.name, header.correlationId);
     } catch (replyError) {
       this.options.onError?.(replyError);
-    } finally {
-      message.close();
     }
   }
 
@@ -736,7 +771,11 @@ export class ZLinkStreamSessionRuntime {
     });
   }
 
-  private async complete(error: unknown, notifyDisconnected: boolean): Promise<void> {
+  private async complete(
+    error: unknown,
+    notifyDisconnected: boolean,
+    bindingsCleanup?: Promise<void>
+  ): Promise<void> {
     try {
       if (error !== undefined && this.closeReason !== 'server_drain') {
         this.closeReason = 'transport_error';
@@ -753,7 +792,7 @@ export class ZLinkStreamSessionRuntime {
         await session.onDisconnected?.(this.context);
       }
     } finally {
-      await this.cleanup();
+      await this.cleanup(bindingsCleanup);
     }
   }
 
@@ -761,20 +800,20 @@ export class ZLinkStreamSessionRuntime {
     if (this.disconnected || this.disconnectQueued) return;
     this.disconnectQueued = true;
     this.stopLivenessChecks();
-    void this.serial
-      .executeFinal(async () => {
+    this.stream.markTransportClosed();
+    const bindingsCleanup = this.context.cleanupBindings();
+    void Promise.all([
+      bindingsCleanup,
+      this.serial.executeFinal(async () => {
         this.disconnectQueued = false;
         if (this.disconnected) return;
-        this.stream.markTransportClosed();
         this.disconnected = true;
-        await this.complete(error, true);
+        await this.complete(error, true, bindingsCleanup);
       })
-      .catch(() => {
-        this.disconnectQueued = false;
-      });
+    ]).catch((failure) => this.options.onError?.(failure));
   }
 
-  private async cleanup(): Promise<void> {
+  private async cleanup(bindingsCleanup?: Promise<void>): Promise<void> {
     if (this.connected && !this.metricsClosed) {
       this.metricsClosed = true;
       this.options.metrics?.change(METRIC_NAMES.StreamConnectionsActive, -1, { transport: 'tcp' });
@@ -783,7 +822,7 @@ export class ZLinkStreamSessionRuntime {
         close_reason: normalizeStreamCloseReason(this.closeReason)
       });
     }
-    await this.context.cleanupBindings();
+    await (bindingsCleanup ?? this.context.cleanupBindings());
     this.removeSession(this.stream.sessionId, this);
   }
 

package/dist/runtime/spots/spot-lifecycle-metrics.d.ts

@@ -1,8 +0,0 @@
-import type { ZLinkRuntimeMetrics } from '../diagnostics';
-export type ZLinkSpotMetricKind = 'entry' | 'user';
-export declare class ZLinkSpotLifecycleMetrics {
-    private readonly metrics?;
-    constructor(metrics?: ZLinkRuntimeMetrics | undefined);
-    opened(kind: ZLinkSpotMetricKind): void;
-    closed(kind: ZLinkSpotMetricKind): void;
-}

package/dist/runtime/spots/spot-lifecycle-metrics.js

@@ -1,17 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkSpotLifecycleMetrics = void 0;
-const runtime_metrics_1 = require("../diagnostics/runtime-metrics");
-class ZLinkSpotLifecycleMetrics {
-    metrics;
-    constructor(metrics) {
-        this.metrics = metrics;
-    }
-    opened(kind) {
-        this.metrics?.change(runtime_metrics_1.METRIC_NAMES.SpotCount, 1, { kind });
-    }
-    closed(kind) {
-        this.metrics?.change(runtime_metrics_1.METRIC_NAMES.SpotCount, -1, { kind });
-    }
-}
-exports.ZLinkSpotLifecycleMetrics = ZLinkSpotLifecycleMetrics;

package/src/runtime/spots/spot-lifecycle-metrics.ts

@@ -1,16 +0,0 @@
-import { METRIC_NAMES } from '../diagnostics/runtime-metrics';
-import type { ZLinkRuntimeMetrics } from '../diagnostics';
-
-export type ZLinkSpotMetricKind = 'entry' | 'user';
-
-export class ZLinkSpotLifecycleMetrics {
-  constructor(private readonly metrics?: ZLinkRuntimeMetrics) {}
-
-  opened(kind: ZLinkSpotMetricKind): void {
-    this.metrics?.change(METRIC_NAMES.SpotCount, 1, { kind });
-  }
-
-  closed(kind: ZLinkSpotMetricKind): void {
-    this.metrics?.change(METRIC_NAMES.SpotCount, -1, { kind });
-  }
-}