@zlink-systems/framework 0.10.0

package/src/runtime/foundation/service-liveness-registry.ts

@@ -0,0 +1,144 @@
+export interface ServiceProbe {
+  readonly nodeRoutingId: string;
+  readonly connectionId: string;
+  readonly probeId: bigint;
+}
+
+export interface ServiceLivenessTick {
+  readonly probes: readonly ServiceProbe[];
+  readonly timedOutNodes: readonly string[];
+}
+
+interface PeerState {
+  readonly connectionId: string;
+  deadlineMs: number;
+  nextProbeMs: number;
+  outstandingProbe?: bigint;
+  ready: boolean;
+}
+
+export const DEFAULT_SERVICE_PROBE_INTERVAL_MS = 5_000;
+export const DEFAULT_SERVICE_PEER_TIMEOUT_MS = 15_000;
+
+/** Uses monotonic milliseconds and never treats application traffic as a probe ACK. */
+export class ServiceLivenessRegistry {
+  private readonly peers = new Map<string, PeerState>();
+  private nextProbeId = 1n;
+
+  constructor(
+    private readonly probeIntervalMs = DEFAULT_SERVICE_PROBE_INTERVAL_MS,
+    private readonly peerTimeoutMs = DEFAULT_SERVICE_PEER_TIMEOUT_MS
+  ) {
+    if (
+      !Number.isFinite(probeIntervalMs)
+      || probeIntervalMs <= 0
+      || !Number.isFinite(peerTimeoutMs)
+      || peerTimeoutMs <= probeIntervalMs
+    ) {
+      throw new RangeError('Liveness requires a positive probe interval and a larger timeout.');
+    }
+  }
+
+  admit(nodeRoutingId: string, connectionId: string, nowMs: number): void {
+    requireIdentity(nodeRoutingId, 'nodeRoutingId');
+    requireIdentity(connectionId, 'connectionId');
+    const current = this.peers.get(nodeRoutingId);
+    if (current?.connectionId === connectionId) return;
+    this.peers.set(nodeRoutingId, {
+      connectionId,
+      deadlineMs: nowMs + this.peerTimeoutMs,
+      nextProbeMs: nowMs + this.probeIntervalMs,
+      ready: false
+    });
+  }
+
+  requestProbe(nodeRoutingId: string, connectionId: string, nowMs: number): boolean {
+    const current = this.peers.get(nodeRoutingId);
+    if (
+      current === undefined
+      || current.connectionId !== connectionId
+      || current.ready
+      || current.outstandingProbe !== undefined
+    ) return false;
+    current.nextProbeMs = Math.min(current.nextProbeMs, nowMs);
+    return true;
+  }
+
+  disconnect(nodeRoutingId: string, connectionId: string): boolean {
+    const current = this.peers.get(nodeRoutingId);
+    if (current === undefined || current.connectionId !== connectionId) return false;
+    this.peers.delete(nodeRoutingId);
+    return true;
+  }
+
+  acknowledge(
+    nodeRoutingId: string,
+    connectionId: string,
+    probeId: bigint,
+    nowMs: number
+  ): boolean {
+    const current = this.peers.get(nodeRoutingId);
+    if (
+      current === undefined
+      || current.connectionId !== connectionId
+      || current.outstandingProbe !== probeId
+    ) {
+      return false;
+    }
+    current.outstandingProbe = undefined;
+    current.deadlineMs = nowMs + this.peerTimeoutMs;
+    current.ready = true;
+    return true;
+  }
+
+  acknowledgeProbe(
+    nodeRoutingId: string,
+    connectionId: string,
+    probeId: bigint
+  ): ServiceProbe | undefined {
+    const current = this.peers.get(nodeRoutingId);
+    if (probeId <= 0n || current === undefined || current.connectionId !== connectionId) {
+      return undefined;
+    }
+    return { nodeRoutingId, connectionId, probeId };
+  }
+
+  tick(nowMs: number): ServiceLivenessTick {
+    const probes: ServiceProbe[] = [];
+    const timedOutNodes: string[] = [];
+    for (const [nodeRoutingId, peer] of this.peers) {
+      if (peer.deadlineMs <= nowMs) {
+        timedOutNodes.push(nodeRoutingId);
+        this.peers.delete(nodeRoutingId);
+        continue;
+      }
+      if (peer.nextProbeMs > nowMs) continue;
+      peer.outstandingProbe ??= this.allocateProbeId();
+      probes.push({ nodeRoutingId, connectionId: peer.connectionId, probeId: peer.outstandingProbe });
+      do {
+        peer.nextProbeMs += this.probeIntervalMs;
+      } while (peer.nextProbeMs <= nowMs);
+    }
+    timedOutNodes.sort();
+    return { probes, timedOutNodes };
+  }
+
+  get size(): number {
+    return this.peers.size;
+  }
+
+  isReady(nodeRoutingId: string, connectionId: string): boolean {
+    const current = this.peers.get(nodeRoutingId);
+    return current?.connectionId === connectionId && current.ready;
+  }
+
+  private allocateProbeId(): bigint {
+    const result = this.nextProbeId++;
+    if (this.nextProbeId > 0xffff_ffff_ffff_ffffn) this.nextProbeId = 1n;
+    return result;
+  }
+}
+
+function requireIdentity(value: string, field: string): void {
+  if (value.length === 0) throw new TypeError(`${field} must be non-empty.`);
+}

package/src/runtime/foundation/service-mailbox.ts

@@ -0,0 +1,369 @@
+import type {
+  ApplicationJobRecordLease
+} from '../application-jobs/application-ingress-record-owner';
+
+export type ServiceMailboxDomain = 'application' | 'infrastructure';
+
+export interface ServiceMailboxRecord {
+  readonly owner: string;
+  readonly domain: ServiceMailboxDomain;
+  parts: readonly Uint8Array[];
+  readonly sourceRoutingId?: string;
+  readonly sourceRoute?: Uint8Array;
+  readonly requestSequence?: bigint;
+  readonly reply?: (parts: readonly Uint8Array[]) => void;
+  readonly correlation?: bigint;
+  readonly localReply?: (
+    terminalResult: number,
+    failureCode: number,
+    payload?: {
+      readonly packetName: string;
+      readonly contentType: string;
+      readonly payload: Uint8Array;
+    }
+  ) => void;
+  readonly stateful?: unknown;
+  /** Host queue permit plus its ordinary Framework-owned ingress record. */
+  readonly applicationJob?: ApplicationJobRecordLease;
+}
+
+export interface ServiceMailboxClaim {
+  readonly owner: string;
+  readonly domain: ServiceMailboxDomain;
+  readonly serial: bigint;
+  readonly records: readonly ServiceMailboxRecord[];
+}
+
+export interface ServiceMailboxRelocationSeal {
+  readonly owner: string;
+  readonly serial: bigint;
+  readonly captured: readonly ServiceMailboxRecord[];
+}
+
+interface OwnerQueue {
+  readonly records: MailboxQueue<ServiceMailboxRecord>;
+  bytes: number;
+  claimed: boolean;
+  claimSerial: bigint;
+}
+
+interface DomainState {
+  readonly owners: Map<string, OwnerQueue>;
+  readonly ready: MailboxQueue<string>;
+  readonly indexed: Set<string>;
+  messages: number;
+  bytes: number;
+}
+
+export interface ServiceMailboxLimits {
+  readonly applicationMessages: number;
+  readonly applicationBytes: number;
+  readonly infrastructureMessages: number;
+  readonly infrastructureBytes: number;
+}
+
+
+/** Level-triggered queues with one active application claim per owner. */
+export class ServiceMailbox {
+  private readonly application: DomainState;
+  private readonly infrastructure: DomainState;
+  private readonly relocationSeals = new Map<string, {
+    readonly serial: bigint;
+    readonly captured: ServiceMailboxRecord[];
+    readonly held: ServiceMailboxRecord[];
+    heldBytes: number;
+  }>();
+  private readonly relocatedOwners = new Set<string>();
+  private nextClaimSerial = 1n;
+  private nextRelocationSerial = 1n;
+  private closed = false;
+
+  constructor(
+    _legacyLimits?: ServiceMailboxLimits,
+    private readonly onReady?: (domain: ServiceMailboxDomain) => void
+  ) {
+    // Host ApplicationJobQueue permits own ordinary-record admission. The
+    // Framework-owned payload lifetime does not retain Core HWM credit. A
+    // second mailbox cap would reject already-admitted work before the shared
+    // queue can apply cancellable FIFO backpressure.
+    this.application = createDomain();
+    this.infrastructure = createDomain();
+  }
+
+  releaseClaimedPayload(record: ServiceMailboxRecord): void {
+    record.parts = [];
+  }
+
+  tryEnqueue(record: ServiceMailboxRecord): boolean {
+    if (record.owner.length === 0 || record.parts.length === 0) {
+      throw new TypeError('Mailbox records require an owner and retained payload.');
+    }
+    const target = this.domain(record.domain);
+    const bytes = retainedBytes(record);
+    if (this.closed) return false;
+    if (record.domain === 'application') {
+      if (this.relocatedOwners.has(record.owner)) return false;
+      const relocation = this.relocationSeals.get(record.owner);
+      if (relocation !== undefined) {
+        relocation.held.push(retainRecord(record));
+        relocation.heldBytes += bytes;
+        target.messages++;
+        target.bytes += bytes;
+        return true;
+      }
+    }
+    let queue = target.owners.get(record.owner);
+    if (queue === undefined) {
+      queue = { records: new MailboxQueue(), bytes: 0, claimed: false, claimSerial: 0n };
+      target.owners.set(record.owner, queue);
+    }
+    const retained = retainRecord(record);
+    queue.records.push(retained);
+    queue.bytes += bytes;
+    target.messages++;
+    target.bytes += bytes;
+    if (!queue.claimed && !target.indexed.has(record.owner)) {
+      target.indexed.add(record.owner);
+      target.ready.push(record.owner);
+    }
+    this.onReady?.(record.domain);
+    return true;
+  }
+
+  tryClaim(
+    domain: ServiceMailboxDomain,
+    messageBudget: number,
+    byteBudget: number
+  ): ServiceMailboxClaim | undefined {
+    requirePositive(messageBudget, 'messageBudget');
+    requirePositive(byteBudget, 'byteBudget');
+    const source = this.domain(domain);
+    for (;;) {
+      const owner = source.ready.shift();
+      if (owner === undefined) return undefined;
+      source.indexed.delete(owner);
+      const queue = source.owners.get(owner);
+      if (queue === undefined || queue.claimed || queue.records.length === 0) continue;
+
+      queue.claimed = true;
+      const serial = this.nextClaimSerial++;
+      queue.claimSerial = serial;
+      const records: ServiceMailboxRecord[] = [];
+      let bytes = 0;
+      while (queue.records.length > 0 && records.length < messageBudget) {
+        const next = queue.records.peek()!;
+        const nextBytes = retainedBytes(next);
+        if (records.length > 0 && nextBytes > byteBudget - bytes) break;
+        queue.records.shift();
+        queue.bytes -= nextBytes;
+        source.messages--;
+        source.bytes -= nextBytes;
+        bytes += nextBytes;
+        records.push(next);
+      }
+      return { owner, domain, serial, records };
+    }
+  }
+
+  release(
+    claim: ServiceMailboxClaim,
+    remaining: readonly ServiceMailboxRecord[] = []
+  ): boolean {
+    const target = this.domain(claim.domain);
+    const queue = target.owners.get(claim.owner);
+    if (queue === undefined || !queue.claimed || queue.claimSerial !== claim.serial) return false;
+    if (remaining.length > 0) {
+      const bytes = remaining.reduce((sum, record) => sum + retainedBytes(record), 0);
+      queue.records.prepend(remaining);
+      queue.bytes += bytes;
+      target.messages += remaining.length;
+      target.bytes += bytes;
+    }
+    queue.claimed = false;
+    queue.claimSerial = 0n;
+    if (queue.records.length === 0) {
+      target.owners.delete(claim.owner);
+    } else if (!target.indexed.has(claim.owner)) {
+      target.indexed.add(claim.owner);
+      target.ready.push(claim.owner);
+    }
+    return true;
+  }
+
+  trySealApplicationOwner(owner: string): ServiceMailboxRelocationSeal | undefined {
+    if (owner.length === 0 || this.closed || this.relocatedOwners.has(owner)) return undefined;
+    if (this.relocationSeals.has(owner)) return undefined;
+    const queue = this.application.owners.get(owner);
+    if (queue?.claimed === true) return undefined;
+    const captured = queue?.records.drain() ?? [];
+    if (queue !== undefined) {
+      queue.bytes = 0;
+      this.application.owners.delete(owner);
+      this.application.indexed.delete(owner);
+    }
+    const serial = this.nextRelocationSerial++;
+    this.relocationSeals.set(owner, { serial, captured, held: [], heldBytes: 0 });
+    return { owner, serial, captured };
+  }
+
+  abortRelocation(seal: ServiceMailboxRelocationSeal): boolean {
+    const current = this.relocationSeals.get(seal.owner);
+    if (current === undefined || current.serial !== seal.serial) return false;
+    this.relocationSeals.delete(seal.owner);
+    const records = [...current.captured, ...current.held];
+    if (records.length === 0) return true;
+    const bytes = records.reduce((sum, record) => sum + retainedBytes(record), 0);
+    this.application.owners.set(seal.owner, {
+      records: new MailboxQueue(records),
+      bytes,
+      claimed: false,
+      claimSerial: 0n
+    });
+    if (!this.application.indexed.has(seal.owner)) {
+      this.application.indexed.add(seal.owner);
+      this.application.ready.push(seal.owner);
+    }
+    this.onReady?.('application');
+    return true;
+  }
+
+  commitRelocation(seal: ServiceMailboxRelocationSeal): readonly ServiceMailboxRecord[] | undefined {
+    const current = this.relocationSeals.get(seal.owner);
+    if (current === undefined || current.serial !== seal.serial) return undefined;
+    this.relocationSeals.delete(seal.owner);
+    this.relocatedOwners.add(seal.owner);
+    const released = [...current.captured, ...current.held];
+    this.application.messages -= released.length;
+    this.application.bytes -= released.reduce((sum, record) => sum + retainedBytes(record), 0);
+    return current.held;
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    clearDomain(this.application);
+    clearDomain(this.infrastructure);
+    for (const relocation of this.relocationSeals.values()) {
+      closeRecords(relocation.captured);
+      closeRecords(relocation.held);
+    }
+    this.relocationSeals.clear();
+    this.relocatedOwners.clear();
+  }
+
+  pendingMessages(domain: ServiceMailboxDomain): number {
+    return this.domain(domain).messages;
+  }
+
+  pendingBytes(domain: ServiceMailboxDomain): number {
+    return this.domain(domain).bytes;
+  }
+
+  private domain(domain: ServiceMailboxDomain): DomainState {
+    return domain === 'application' ? this.application : this.infrastructure;
+  }
+}
+
+function createDomain(): DomainState {
+  return {
+    owners: new Map(),
+    ready: new MailboxQueue(),
+    indexed: new Set(),
+    messages: 0,
+    bytes: 0
+  };
+}
+
+function clearDomain(domain: DomainState): void {
+  for (const owner of domain.owners.values()) {
+    closeRecords(owner.records.drain());
+  }
+  domain.owners.clear();
+  domain.ready.clear();
+  domain.indexed.clear();
+  domain.messages = 0;
+  domain.bytes = 0;
+}
+
+function closeRecords(records: readonly ServiceMailboxRecord[]): void {
+  for (const record of records) record.applicationJob?.close();
+}
+
+/**
+ * Internal FIFO used by the mailbox hot path. Two stacks keep dequeue and
+ * prepend operations amortized O(1), avoiding array reindexing from shift and
+ * unshift while retaining the queue's existing ordering semantics.
+ */
+class MailboxQueue<T> {
+  private readonly front: T[] = [];
+  private readonly back: T[] = [];
+
+  constructor(initial?: readonly T[]) {
+    if (initial !== undefined) {
+      for (const value of initial) this.back.push(value);
+    }
+  }
+
+  get length(): number {
+    return this.front.length + this.back.length;
+  }
+
+  push(value: T): void {
+    this.back.push(value);
+  }
+
+  peek(): T | undefined {
+    this.moveBackToFront();
+    return this.front.at(-1);
+  }
+
+  shift(): T | undefined {
+    this.moveBackToFront();
+    return this.front.pop();
+  }
+
+  prepend(values: readonly T[]): void {
+    for (let index = values.length - 1; index >= 0; index -= 1) {
+      this.front.push(values[index]!);
+    }
+  }
+
+  drain(): T[] {
+    this.moveBackToFront();
+    const drained: T[] = [];
+    while (this.front.length > 0) {
+      drained.push(this.front.pop()!);
+    }
+    return drained;
+  }
+
+  clear(): void {
+    this.front.length = 0;
+    this.back.length = 0;
+  }
+
+  private moveBackToFront(): void {
+    if (this.front.length > 0 || this.back.length === 0) return;
+    for (let index = this.back.length - 1; index >= 0; index -= 1) {
+      this.front.push(this.back[index]!);
+    }
+    this.back.length = 0;
+  }
+}
+
+function retainRecord(record: ServiceMailboxRecord): ServiceMailboxRecord {
+  // Raw binding ingress already transfers owned Buffer values to the
+  // framework. Moving the record between mailbox queues must not create a
+  // second representation of the same payload.
+  return record;
+}
+
+function retainedBytes(record: ServiceMailboxRecord): number {
+  return record.parts.reduce((sum, part) => sum + part.byteLength, 0);
+}
+
+function requirePositive(value: number, field: string): void {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new RangeError(`${field} must be a positive safe integer.`);
+  }
+}