@zlink-systems/framework 0.31.0 → 0.32.1

package/src/runtime/streams/index.ts

@@ -60,6 +60,9 @@ import { ZLinkBoundSessionService, type ZLinkBoundSessionTransport } from './bou
 import { ZLinkManagedStream } from './managed-stream';
 import {
   messageToBytes,
+  decodeStreamFrame,
+  decodeStreamHeader,
+  encodeStreamFrame,
   ZLinkStreamCodec,
   ZLinkStreamMessageKind,
   type ZLinkStreamFrameHeader,
@@ -417,7 +420,7 @@ export class ZLinkStreamSessionNodeRuntime extends ZLinkStreamSessionNodeRuntime
 }
 
 export class ZLinkStreamBindingRuntime {
-  private readonly routes: ZLinkActorSessionBindingRegistry<
+  readonly routes: ZLinkActorSessionBindingRegistry<
     DefaultZLinkSessionContext,
     DefaultZLinkSessionActor
   >;
@@ -808,19 +811,42 @@ export class ZLinkStreamBindingRuntime {
     );
   }
 
-  createJsonReplyFrameMessage(
+  async submitReply(
+    context: DefaultZLinkSessionContext,
     requestHeader: ZLinkStreamFrameHeader,
     kind: ZLinkStreamReplyMessageKind,
     metadata: ReadonlyMap<string, string>,
     compressed: boolean,
     payload: unknown
-  ): Message {
-    return this.frameMessages.createJsonReplyFrameMessage(
+  ): Promise<ZLinkSubmitResult> {
+    const frame = this.frameMessages.createJsonReplyFrameMessage(
       requestHeader,
       kind,
       metadata,
       compressed,
       payload
     );
+    try {
+      return await this.routes.submitReply(context, requestHeader, async (header) => {
+        if (header === requestHeader) return await context.stream.submitRaw(frame);
+        const encoded = decodeStreamFrame(messageToBytes(frame));
+        const normalized = this.createBinaryMessage(
+          encodeStreamFrame(
+            {
+              ...decodeStreamHeader(encoded.header),
+              actorSlot: header.actorSlot
+            },
+            encoded.payload
+          )
+        );
+        try {
+          return await context.stream.submitRaw(normalized);
+        } finally {
+          normalized.close();
+        }
+      });
+    } finally {
+      frame.close();
+    }
   }
 }

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

@@ -478,7 +478,8 @@ export class ZLinkManagedStream implements ZLinkStream {
         throw wireReplyFailureException(
           completion.terminalResult,
           completion.failureErrno,
-          `${operationName} failed with result ${completion.terminalResult} (errno ${completion.failureErrno}).`
+          completion.failureMessage ??
+            `${operationName} failed with result ${completion.terminalResult} (errno ${completion.failureErrno}).`
         );
       }
     } finally {

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

@@ -39,13 +39,13 @@ export interface ZLinkSessionCallContext {
     payload: unknown,
     correlationId?: string
   ): Message;
-  createJsonReplyFrameMessage(
+  submitReply(
     requestHeader: ZLinkStreamFrameHeader,
     kind: ZLinkStreamReplyMessageKind,
     metadata: ReadonlyMap<string, string>,
     compressed: boolean,
     payload: unknown
-  ): Message;
+  ): Promise<ZLinkSubmitResult>;
   claimReply(requestHeader: ZLinkStreamFrameHeader): void;
   /**
    * Spec 26 §2.2: the STREAM surface records session-connected sends and the
@@ -168,23 +168,18 @@ export class DefaultZLinkSessionReplyCall implements ZLinkSessionReplyCall {
       throw new Error('Reply is only available while handling a request packet.');
     }
     this.context.claimReply(requestHeader);
-    const message = this.context.createJsonReplyFrameMessage(
+    const result = await this.context.submitReply(
       requestHeader,
       ZLinkStreamMessageKind.Response,
       new Map<string, string>(),
       this.compressionEnabled,
       this.message
     );
-    try {
-      const result = await this.context.stream.submitRaw(message);
-      requireOneWayCompletion(result, 'STREAM session reply');
-      this.context.traceFrameWritten?.(
-        ZLinkStreamMessageKind.Response,
-        requestHeader.name,
-        requestHeader.correlationId
-      );
-    } finally {
-      message.close();
-    }
+    requireOneWayCompletion(result, 'STREAM session reply');
+    this.context.traceFrameWritten?.(
+      ZLinkStreamMessageKind.Response,
+      requestHeader.name,
+      requestHeader.correlationId
+    );
   }
 }

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

@@ -65,13 +65,14 @@ interface ZLinkSessionContextRuntime {
     payload: unknown,
     correlationId?: string
   ): Message;
-  createJsonReplyFrameMessage(
+  submitReply(
+    context: DefaultZLinkSessionContext,
     requestHeader: ZLinkStreamFrameHeader,
     kind: ZLinkStreamReplyMessageKind,
     metadata: ReadonlyMap<string, string>,
     compressed: boolean,
     payload: unknown
-  ): Message;
+  ): Promise<ZLinkSubmitResult>;
   decompressPayload(payload: Message): Message;
   bind(
     context: DefaultZLinkSessionContext,
@@ -267,20 +268,14 @@ export class DefaultZLinkSessionContext implements ZLinkSessionContext {
     );
   }
 
-  createJsonReplyFrameMessage(
+  submitReply(
     requestHeader: ZLinkStreamFrameHeader,
     kind: ZLinkStreamReplyMessageKind,
     metadata: ReadonlyMap<string, string>,
     compressed: boolean,
     payload: unknown
-  ): Message {
-    return this.runtime.createJsonReplyFrameMessage(
-      requestHeader,
-      kind,
-      metadata,
-      compressed,
-      payload
-    );
+  ): Promise<ZLinkSubmitResult> {
+    return this.runtime.submitReply(this, requestHeader, kind, metadata, compressed, payload);
   }
 
   enterDispatch(header: ZLinkStreamFrameHeader): void {

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(),
@@ -583,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(
@@ -605,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;
@@ -694,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();
     }
   }