@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,109 @@
+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) & 0xffffffffffffffffn;
+    } while (this.nextRequestSeq === 0n);
+    return this.nextRequestSeq;
+  }
+}

package/src/runtime/streams/session-serial-executor.ts

@@ -0,0 +1,97 @@
+import {
+  ZLinkSerialExecutionQueue,
+  type ZLinkSerialWorkLane,
+  type ZLinkSerialWorkOptions,
+  type ZLinkSerialWorkRecord
+} from '../execution/serial-execution-queue';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
+import {
+  bindApplicationJobPermit,
+  hasApplicationJobPermit
+} from '../application-jobs/application-job-queue-scope';
+
+export class ZLinkSessionSerialExecutor {
+  private readonly scheduler = new ZLinkSerialExecutionQueue(
+    async (record) => this.execute(record),
+    {
+      capacityError: (lane) => createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.WorkerQueueFull,
+        `Stream Session ${lane} execution capacity is full.`,
+        true
+      )
+    }
+  );
+  private closed = false;
+
+  executeApplication(
+    work: () => Promise<void>,
+    options: Omit<ZLinkSerialWorkOptions, 'lane'> = {},
+    onRejected?: (error?: unknown) => void
+  ): boolean {
+    return this.submit(work, 'application', options, onRejected);
+  }
+
+  executeControl(
+    work: () => Promise<void>,
+    options: Omit<ZLinkSerialWorkOptions, 'lane'> = {},
+    onRejected?: (error?: unknown) => void
+  ): boolean {
+    return this.submit(work, 'lifecycle', options, onRejected);
+  }
+
+  executeInfrastructure(
+    work: () => Promise<void>,
+    options: Omit<ZLinkSerialWorkOptions, 'lane'> = {},
+    onRejected?: (error?: unknown) => void
+  ): boolean {
+    return this.submit(work, 'lifecycle', options, onRejected);
+  }
+
+  executeFinal(work: () => Promise<void>): Promise<void> {
+    if (this.closed) {
+      return Promise.reject(createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.RuntimeShutdown,
+        'Session execution queue is closed.'
+      ));
+    }
+    const boundWork = bindApplicationJobPermit(work);
+    return hasApplicationJobPermit()
+      ? this.scheduler.submitPreAdmitted(boundWork, { lane: 'lifecycle' })
+      : this.scheduler.submit(boundWork, { lane: 'lifecycle' });
+  }
+
+  private submit(
+    work: () => Promise<void>,
+    lane: ZLinkSerialWorkLane,
+    options: Omit<ZLinkSerialWorkOptions, 'lane'> = {},
+    onRejected?: (error?: unknown) => void
+  ): boolean {
+    if (this.closed) return false;
+    const serialOptions = { ...options, lane };
+    const boundWork = bindApplicationJobPermit(work);
+    const submitted = hasApplicationJobPermit()
+      ? this.scheduler.submitPreAdmitted(boundWork, serialOptions)
+      : this.scheduler.submit(boundWork, serialOptions);
+    void submitted
+      .catch(error => onRejected?.(error));
+    return true;
+  }
+
+  async dispose(): Promise<void> {
+    this.closed = true;
+    await this.scheduler.whenIdle();
+  }
+
+  private async execute(record: ZLinkSerialWorkRecord<unknown>): Promise<void> {
+    try {
+      record.resolve(await record.operation());
+    } catch (error) {
+      record.reject(error);
+    } finally {
+      record.release();
+    }
+  }
+}

package/src/runtime/streams/stream-binding-runtime-ports.ts

@@ -0,0 +1,106 @@
+import type { ActorRef, ZLinkSessionActor } from '../../contracts';
+import type { ZLinkBackendActorSessionNode } from '../backend';
+import type { ZLinkSubmitResult } from '../messaging/submission-result';
+import type { DefaultZLinkSessionActor } from './session-context';
+import type { ZLinkBoundSessionResponseTarget } from './bound-session-response-target';
+
+export interface ZLinkStreamActorLookupPort {
+  find(actorId: string): Promise<DefaultZLinkSessionActor | undefined>;
+  authorityFence(actorId: string): Promise<{
+    readonly authorityOwnerGeneration: bigint;
+    readonly ownerLeaseGeneration: bigint;
+  } | undefined>;
+  sessionRouteFence(actorId: string): Promise<{
+    readonly actor: ActorRef;
+    readonly sessionRid: ActorRef['nodeRid'];
+    readonly bindingGeneration: bigint;
+  } | undefined>;
+}
+
+export interface ZLinkStreamActorLifecyclePort {
+  rebindActor(actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+  refreshActor(actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+  commitActorRoute(
+    actorRef: ActorRef,
+    signal?: AbortSignal,
+    options?: ZLinkActorRouteCommitOptions
+  ): Promise<void>;
+  abortActorRouteSeal(actorId: string, sealId: string): Promise<boolean>;
+  validateActorRouteSeal(actorId: string, sealId: string): Promise<boolean>;
+  unbindActor(actorId: string): Promise<void>;
+}
+
+export interface ZLinkActorRouteCommitOptions {
+  /**
+   * Relocation already carries the binding identity to the target actor. The
+   * follow-up confirmation can use a one-way route submission because a
+   * request/ACK would create a nested route request while the Session
+   * ownership command is being dispatched.
+   */
+  readonly confirmRemoteSessionBinding?: boolean | 'send';
+  /**
+   * Command 44 keeps ingress sealed while the native route is prepared, then
+   * publishes the new route and releases this exact seal in one owner turn.
+   */
+  readonly releaseSeal?: {
+    readonly sealId: string;
+  };
+}
+
+export interface ZLinkBoundSessionResponsePort {
+  captureBoundSessionResponseTarget(actor: ZLinkSessionActor): Promise<ZLinkBoundSessionResponseTarget | undefined>;
+  sendLocalBoundSessionResponse(
+    actorId: string, packetName: string, requestSeq: bigint, message: unknown,
+    metadata: ReadonlyMap<string, string>, compressPayload: boolean
+  ): Promise<boolean>;
+  sendLocalBoundSessionError(
+    actorId: string, packetName: string, requestSeq: bigint, error: unknown,
+    metadata: ReadonlyMap<string, string>
+  ): Promise<boolean>;
+}
+
+export interface ZLinkRemoteBoundSessionPort extends ZLinkStreamActorLifecyclePort {
+  disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void>;
+  sendLocalBoundSession(
+    actorId: string, message: unknown, packetName: string | undefined,
+    metadata: ReadonlyMap<string, string>
+  ): Promise<boolean>;
+  sendLocalBoundSessionResponse(
+    actorId: string, packetName: string, requestSeq: bigint, message: unknown,
+    metadata: ReadonlyMap<string, string>, compressPayload: boolean
+  ): Promise<boolean>;
+  sendLocalBoundSessionError(
+    actorId: string, packetName: string, requestSeq: bigint, error: unknown,
+    metadata: ReadonlyMap<string, string>
+  ): Promise<boolean>;
+  sendNativeBoundSessionResponse(
+    node: ZLinkBackendActorSessionNode, actorRef: ActorRef, packetName: string, requestSeq: bigint,
+    message: unknown, metadata: ReadonlyMap<string, string>, compressPayload: boolean,
+    signal?: AbortSignal
+  ): Promise<void>;
+  sendNativeBoundSessionError(
+    node: ZLinkBackendActorSessionNode, actorRef: ActorRef, packetName: string, requestSeq: bigint,
+    error: unknown, metadata: ReadonlyMap<string, string>, signal?: AbortSignal
+  ): Promise<void>;
+}
+
+export interface ZLinkNativeFallbackBoundSessionPort {
+  disconnectNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+  disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void>;
+  sendLocalBoundSession(
+    actorId: string, message: unknown, packetName: string | undefined,
+    metadata: ReadonlyMap<string, string>
+  ): Promise<boolean>;
+  submitLocalBoundSession(
+    actorId: string, message: unknown, packetName: string | undefined,
+    metadata: ReadonlyMap<string, string>, signal?: AbortSignal
+  ): Promise<ZLinkSubmitResult>;
+  sendNativeBoundSession(
+    node: ZLinkBackendActorSessionNode, actorRef: ActorRef, message: unknown, packetName: string | undefined,
+    metadata: ReadonlyMap<string, string>, signal?: AbortSignal
+  ): Promise<ZLinkSubmitResult>;
+  sendBoundSession(
+    actorId: string, message: unknown, packetName: string | undefined,
+    metadata: ReadonlyMap<string, string>, signal?: AbortSignal
+  ): Promise<ZLinkSubmitResult>;
+}

package/src/runtime/streams/stream-frame-factory.ts

@@ -0,0 +1,255 @@
+import type {
+  ZLinkStreamCompressionCodec,
+  ZLinkStreamCompressionOptions
+} from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import { ZLinkBufferMessage as ZLinkBindingMessage } from '../backend/runtime-message';
+import { currentOrCreateFlow } from '../diagnostics/flow-context';
+import { stringifyFrameworkJsonV1 } from '../messaging/framework-json-v1';
+import { readZLinkPacketJsonContract } from '../../contracts/Handlers/Attributes';
+import {
+  createStreamReplyHeader,
+  encodeStreamFrame,
+  lz4Pickle,
+  lz4Unpickle,
+  utf8Decode,
+  utf8Encode,
+  ZLinkStreamCodec,
+  type ZLinkStreamFrameHeader,
+  ZLinkStreamHeaderFlags,
+  ZLinkStreamMessageKind,
+  type ZLinkStreamReplyMessageKind
+} from './protocol';
+
+const DEFAULT_MAX_DECOMPRESSED_STREAM_PAYLOAD_SIZE = 64 * 1024;
+
+export interface ZLinkStreamFramePayloadCodec {
+  encode(payload: unknown, context?: {
+    readonly messageType?: Function;
+    readonly packetName?: string;
+    readonly direction: 'Request' | 'Response' | 'Error' | 'Send';
+  } | Function): {
+    readonly codec: ZLinkStreamCodec;
+    readonly payload: Uint8Array;
+  };
+}
+
+export interface ZLinkStreamFrameMessageFactoryOptions {
+  readonly messageFactory?: ZLinkStreamFrameMessageFactorySource;
+  readonly streamPayloadCodec?: ZLinkStreamFramePayloadCodec;
+  readonly streamCompression?: ZLinkStreamCompressionOptions;
+  readonly flowCreationEnabled?: () => boolean;
+}
+
+export interface ZLinkStreamFrameMessageFactorySource {
+  createTextMessage(payload: string): Message;
+  createBinaryMessage?(payload: Uint8Array): Message;
+}
+
+export class ZLinkStreamFrameMessageFactory {
+  private readonly compressionCodec: ZLinkStreamCompressionCodec | undefined;
+
+  constructor(private readonly options: ZLinkStreamFrameMessageFactoryOptions) {
+    this.compressionCodec = resolveStreamCompressionCodec(options.streamCompression);
+  }
+
+  createTextMessage(payload: string): Message {
+    return this.requireMessageFactory().createTextMessage(payload);
+  }
+
+  createBinaryMessage(payload: Uint8Array): Message {
+    const factory = this.requireMessageFactory();
+    if (factory.createBinaryMessage !== undefined) {
+      return factory.createBinaryMessage(payload);
+    }
+    return factory.createTextMessage(utf8Decode(payload));
+  }
+
+  createJsonFrameMessage(
+    kind: ZLinkStreamMessageKind,
+    packetName: string,
+    metadata: ReadonlyMap<string, string>,
+    compressed: boolean,
+    requestSeq: bigint | undefined,
+    payload: unknown,
+    correlationId?: string
+  ): Message {
+    const flow = (this.options.flowCreationEnabled?.() ?? true)
+      ? currentOrCreateFlow('Application')
+      : undefined;
+    return this.createJsonFrameMessageWithHeader(
+      payload,
+      compressed,
+      packetName,
+      streamDirection(kind),
+      (codec, flags) => ({
+        kind,
+        codec,
+        flags,
+        requestSeq,
+        name: kind === ZLinkStreamMessageKind.Response || kind === ZLinkStreamMessageKind.Error
+          ? ''
+          : packetName,
+        metadata,
+        correlationId,
+        flowId: flow?.flowId,
+        flowOrigin: flow?.flowOrigin
+      })
+    );
+  }
+
+  createJsonReplyFrameMessage(
+    requestHeader: ZLinkStreamFrameHeader,
+    kind: ZLinkStreamReplyMessageKind,
+    metadata: ReadonlyMap<string, string>,
+    compressed: boolean,
+    payload: unknown
+  ): Message {
+    return this.createJsonFrameMessageWithHeader(
+      payload,
+      compressed,
+      requestHeader.name,
+      streamDirection(kind),
+      (codec, flags) => createStreamReplyHeader(
+        requestHeader,
+        kind,
+        codec,
+        flags,
+        metadata,
+        this.options.flowCreationEnabled?.() ?? true
+      )
+    );
+  }
+
+  private createJsonFrameMessageWithHeader(
+    payload: unknown,
+    compressed: boolean,
+    packetName: string,
+    direction: 'Request' | 'Response' | 'Error' | 'Send',
+    createHeader: (codec: ZLinkStreamCodec, flags: ZLinkStreamHeaderFlags) => ZLinkStreamFrameHeader
+  ): Message {
+    const encoded = this.encodePayload(payload, packetName, direction);
+    let body = encoded.payload;
+    if (compressed) {
+      body = compressStreamPayload(body, this.compressionCodec);
+    }
+    const flags = compressed ? ZLinkStreamHeaderFlags.PayloadCompressed : ZLinkStreamHeaderFlags.None;
+    const frame = encodeStreamFrame(createHeader(encoded.codec, flags), body);
+    return this.createOwnedFrameMessage(frame);
+  }
+
+  /**
+   * Wraps a freshly encoded, unaliased frame. `createBinaryMessage` must copy
+   * because callers may pass live buffers, but the frames built here are
+   * never retained by the encoder, so the default path skips that copy.
+   */
+  private createOwnedFrameMessage(frame: Uint8Array): Message {
+    const factory = this.options.messageFactory;
+    if (factory !== undefined) {
+      return factory.createBinaryMessage !== undefined
+        ? factory.createBinaryMessage(frame)
+        : factory.createTextMessage(utf8Decode(frame));
+    }
+    return ZLinkBindingMessage.fromOwned(
+      Buffer.from(frame.buffer, frame.byteOffset, frame.byteLength)
+    );
+  }
+
+  private encodePayload(
+    payload: unknown,
+    packetName: string,
+    direction: 'Request' | 'Response' | 'Error' | 'Send'
+  ): { codec: ZLinkStreamCodec; payload: Uint8Array } {
+    const codec = this.options.streamPayloadCodec;
+    if (codec !== undefined) {
+      if (direction !== 'Error') {
+        return codec.encode(payload, { packetName, direction });
+      }
+    }
+    return {
+      codec: ZLinkStreamCodec.Json,
+      payload: utf8Encode(stringifyFrameworkJsonV1(
+        payload,
+        direction === 'Error'
+          ? undefined
+          : readZLinkPacketJsonContract(packetName)?.[
+              direction === 'Response' ? 'reply' : 'payload'
+            ]
+      ))
+    };
+  }
+
+  private requireMessageFactory(): ZLinkStreamFrameMessageFactorySource {
+    return this.options.messageFactory ?? defaultStreamMessageFactory;
+  }
+}
+
+function streamDirection(kind: ZLinkStreamMessageKind): 'Request' | 'Response' | 'Error' | 'Send' {
+  switch (kind) {
+    case ZLinkStreamMessageKind.Request: return 'Request';
+    case ZLinkStreamMessageKind.Response: return 'Response';
+    case ZLinkStreamMessageKind.Error: return 'Error';
+    default: return 'Send';
+  }
+}
+
+export const zlinkStreamLz4CompressionCodec: ZLinkStreamCompressionCodec = {
+  compress(payload: Uint8Array): Uint8Array {
+    return lz4Pickle(payload);
+  },
+  decompress(payload: Uint8Array, maxDecompressedSize: number): Uint8Array {
+    return lz4Unpickle(payload, maxDecompressedSize);
+  }
+};
+
+export function resolveStreamCompressionCodec(
+  options: ZLinkStreamCompressionOptions | undefined
+): ZLinkStreamCompressionCodec | undefined {
+  if (options?.disabled === true) {
+    return undefined;
+  }
+  return options?.codec ?? zlinkStreamLz4CompressionCodec;
+}
+
+function compressStreamPayload(
+  payload: Uint8Array,
+  codec: ZLinkStreamCompressionCodec | undefined
+): Uint8Array {
+  if (codec === undefined) {
+    throw new Error('Compression codec is not configured.');
+  }
+  try {
+    return codec.compress(payload);
+  } catch (error) {
+    throw new Error(`Compression failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+export function decompressStreamPayload(
+  payload: Uint8Array,
+  codec: ZLinkStreamCompressionCodec | undefined,
+  maxDecompressedSize = DEFAULT_MAX_DECOMPRESSED_STREAM_PAYLOAD_SIZE
+): Uint8Array {
+  if (codec === undefined) {
+    throw new Error('Compression codec is not configured.');
+  }
+  let decompressed: Uint8Array;
+  try {
+    decompressed = codec.decompress(payload, maxDecompressedSize);
+  } catch (error) {
+    throw new Error(`Decompression failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (decompressed.length > maxDecompressedSize) {
+    throw new Error('Decompressed stream payload exceeds maximum stream payload size.');
+  }
+  return decompressed;
+}
+
+const defaultStreamMessageFactory: ZLinkStreamFrameMessageFactorySource = {
+  createTextMessage(payload: string): Message {
+    return ZLinkBindingMessage.fromOwned(Buffer.from(payload));
+  },
+  createBinaryMessage(payload: Uint8Array): Message {
+    return ZLinkBindingMessage.fromOwned(Buffer.from(payload));
+  }
+};

package/src/runtime/streams/stream-message-utils.ts

@@ -0,0 +1,89 @@
+import type { Message } from '../../contracts/Common/Message';
+import { parseFrameworkJsonV1 } from '../messaging/framework-json-v1';
+import { utf8Decode, utf8Encode } from './protocol';
+
+const EMPTY_MESSAGE_BYTES = new Uint8Array(0);
+
+export function copyMessage(message: Message): Message {
+  const value = message as unknown as {
+    copy?: () => Message;
+    toBytes?: () => Uint8Array;
+    data?: () => Uint8Array;
+    bytes?: Uint8Array;
+    getString?: () => string;
+  };
+  if (value.copy !== undefined) {
+    return value.copy();
+  }
+  if (value.toBytes !== undefined) {
+    return simpleMessage(value.toBytes()) as Message;
+  }
+  if (value.data !== undefined) {
+    return simpleMessage(value.data()) as Message;
+  }
+  if (value.bytes !== undefined) {
+    return simpleMessage(value.bytes) as Message;
+  }
+  if (value.getString !== undefined) {
+    return simpleMessage(utf8Encode(value.getString())) as Message;
+  }
+  throw new Error('Stream response payload cannot be copied.');
+}
+
+export function simpleMessage(bytes: Uint8Array): unknown {
+  return createSimpleMessage(new Uint8Array(bytes), false);
+}
+
+/** Create the structural Message used by the internal receive assembler. */
+export function ownedMessage(bytes: Uint8Array): Message {
+  return createSimpleMessage(bytes, true) as Message;
+}
+
+function createSimpleMessage(initial: Uint8Array, releaseOnClose: boolean): unknown {
+  return new ZLinkSimpleMessage(initial, releaseOnClose);
+}
+
+class ZLinkSimpleMessage {
+  constructor(
+    private current: Uint8Array,
+    private readonly releaseOnClose: boolean
+  ) {}
+
+  get bytes(): Uint8Array {
+    return this.current;
+  }
+
+  toBytes(): Uint8Array {
+    return new Uint8Array(this.current);
+  }
+
+  data(): Uint8Array {
+    return this.current;
+  }
+
+  size(): number {
+    return this.current.byteLength;
+  }
+
+  isEmpty(): boolean {
+    return this.current.byteLength === 0;
+  }
+
+  copy(): unknown {
+    return createSimpleMessage(new Uint8Array(this.current), true);
+  }
+
+  getString(): string {
+    return utf8Decode(this.current);
+  }
+
+  value(): unknown {
+    return parseFrameworkJsonV1(utf8Decode(this.current));
+  }
+
+  close(): void {
+    if (this.releaseOnClose) {
+      this.current = EMPTY_MESSAGE_BYTES;
+    }
+  }
+}