@zlink-systems/framework 0.10.0

package/src/runtime/channels/client-server-service-wire.ts

@@ -0,0 +1,390 @@
+import type { ZLinkClientServerServerDescriptor } from '../../contracts/Locations';
+import { ZLinkFrameworkRuntimeState } from '../../contracts/Locations';
+import {
+  decodeCanonicalServiceWireText,
+  decodeServiceWireRoutingId,
+  encodeCanonicalServiceWireText,
+  encodeServiceWireRoutingId
+} from '../foundation/service-wire-binary-primitives';
+import { normalizeEndpoint } from '../../contracts/Configuration/EndpointNotation';
+
+const MAGIC_0 = 0x5a;
+const MAGIC_1 = 0x4d;
+const WIRE_MAJOR = 1;
+const TOPOLOGY_CLIENT_SERVER = 2;
+const ROLE_CLIENT = 1;
+const ROLE_SERVER = 2;
+const DIRECTION_CLIENT_TO_SERVER = 1;
+const COMMAND_HELLO = 1;
+const COMMAND_ADMIT = 2;
+const COMMAND_REJECT = 3;
+const COMMAND_UPDATE = 4;
+const COMMAND_LIVENESS_PROBE = 5;
+const COMMAND_LIVENESS_ACK = 6;
+const MAX_DESCRIPTOR_BYTES = 1024 * 1024;
+const MAX_U32 = 0xffff_ffff;
+const MAX_GENERATION = 0x7fff_ffff_ffff_ffffn;
+
+export interface ZLinkClientServerHello {
+  readonly channelName: string;
+  readonly securityIdentity: string;
+  readonly normalizedEffectiveMaxMessageBytes: number;
+}
+
+export interface ZLinkClientServerAdmission {
+  readonly channelName: string;
+  readonly serverRid: string;
+  readonly lifecycleGeneration: bigint;
+  readonly descriptorRevision: bigint;
+  readonly weight: number;
+  readonly state: ZLinkFrameworkRuntimeState;
+  readonly securityIdentity: string;
+  readonly normalizedEffectiveMaxMessageBytes: number;
+  readonly advertisedEndpoint: string;
+}
+
+export type ZLinkClientServerControlRecord =
+  | { readonly kind: 'hello'; readonly hello: ZLinkClientServerHello }
+  | { readonly kind: 'admit'; readonly admission: ZLinkClientServerAdmission }
+  | { readonly kind: 'update'; readonly admission: ZLinkClientServerAdmission }
+  | { readonly kind: 'reject'; readonly reason: number }
+  | { readonly kind: 'livenessProbe'; readonly probeId: bigint }
+  | { readonly kind: 'livenessAck'; readonly probeId: bigint };
+
+export class ZLinkClientServerServiceWireError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ZLinkClientServerServiceWireError';
+  }
+}
+
+export function encodeClientServerHello(value: ZLinkClientServerHello): Buffer {
+  const roleBody = concat(
+    encodeText8(value.channelName, 'channelName'),
+    Buffer.of(DIRECTION_CLIENT_TO_SERVER),
+    encodeText8(value.securityIdentity, 'securityIdentity'),
+    encodeNonZeroU32(
+      value.normalizedEffectiveMaxMessageBytes,
+      'normalizedEffectiveMaxMessageBytes'
+    )
+  );
+  return encodeAdmission(COMMAND_HELLO, ROLE_CLIENT, roleBody);
+}
+
+export function encodeClientServerAdmit(
+  descriptor: ZLinkClientServerServerDescriptor,
+  normalizedEffectiveMaxMessageBytes: number
+): Buffer {
+  return encodeServerAdmission(COMMAND_ADMIT, descriptor, normalizedEffectiveMaxMessageBytes);
+}
+
+export function encodeClientServerUpdate(
+  descriptor: ZLinkClientServerServerDescriptor,
+  normalizedEffectiveMaxMessageBytes: number
+): Buffer {
+  return encodeServerAdmission(COMMAND_UPDATE, descriptor, normalizedEffectiveMaxMessageBytes);
+}
+
+export function encodeClientServerReject(reason: number): Buffer {
+  if (!Number.isInteger(reason) || reason < 1 || reason > 12) {
+    fail('ClientServer reject reason must be between 1 and 12.');
+  }
+  return concat(prefix(COMMAND_REJECT), encodeU32(reason));
+}
+
+export function encodeClientServerLivenessProbe(probeId: bigint): Buffer {
+  return encodeLiveness(COMMAND_LIVENESS_PROBE, probeId);
+}
+
+export function encodeClientServerLivenessAck(probeId: bigint): Buffer {
+  return encodeLiveness(COMMAND_LIVENESS_ACK, probeId);
+}
+
+export function isClientServerControlFrame(frame: Uint8Array): boolean {
+  return frame.byteLength >= 5
+    && frame[0] === MAGIC_0
+    && frame[1] === MAGIC_1
+    && frame[2] === WIRE_MAJOR;
+}
+
+export function decodeClientServerControl(frame: Uint8Array): ZLinkClientServerControlRecord {
+  if (frame.byteLength > MAX_DESCRIPTOR_BYTES) fail('ClientServer control record is oversized.');
+  const reader = new Reader(frame);
+  if (reader.u8('magic[0]') !== MAGIC_0
+    || reader.u8('magic[1]') !== MAGIC_1
+    || reader.u8('wireMajor') !== WIRE_MAJOR) {
+    fail('ClientServer control record prefix is invalid.');
+  }
+  const command = reader.u8('command');
+  if (reader.u8('flags') !== 0) fail('ClientServer control flags are invalid.');
+  if (command === COMMAND_REJECT) {
+    const reason = reader.u32('reason');
+    reader.end();
+    if (reason < 1 || reason > 12) fail('ClientServer reject reason is invalid.');
+    return { kind: 'reject', reason };
+  }
+  if (command === COMMAND_LIVENESS_PROBE || command === COMMAND_LIVENESS_ACK) {
+    const probeId = reader.nonZeroU64('probeId');
+    reader.end();
+    return command === COMMAND_LIVENESS_PROBE
+      ? { kind: 'livenessProbe', probeId }
+      : { kind: 'livenessAck', probeId };
+  }
+  if (command !== COMMAND_HELLO && command !== COMMAND_ADMIT && command !== COMMAND_UPDATE) {
+    fail('ClientServer control command is invalid.');
+  }
+  if (reader.u8('topologyKind') !== TOPOLOGY_CLIENT_SERVER) {
+    fail('Control record is not ClientServer topology.');
+  }
+  const admissionLength = reader.u32('admissionLength');
+  if (admissionLength !== reader.remaining) fail('ClientServer admission length is invalid.');
+  const role = reader.u8('role');
+  const roleLength = reader.u16('roleLength');
+  if (roleLength !== reader.remaining) fail('ClientServer role body length is invalid.');
+  if (command === COMMAND_HELLO) {
+    if (role !== ROLE_CLIENT) fail('ClientServer hello role is invalid.');
+    const hello = decodeClientHello(reader);
+    reader.end();
+    return { kind: 'hello', hello };
+  }
+  if (role !== ROLE_SERVER) fail('ClientServer server admission role is invalid.');
+  const admission = decodeServerAdmission(reader);
+  reader.end();
+  return command === COMMAND_ADMIT
+    ? { kind: 'admit', admission }
+    : { kind: 'update', admission };
+}
+
+function encodeLiveness(command: number, probeId: bigint): Buffer {
+  return concat(prefix(command), encodeNonZeroU64(probeId, 'probeId'));
+}
+
+function encodeServerAdmission(
+  command: number,
+  descriptor: ZLinkClientServerServerDescriptor,
+  normalizedEffectiveMaxMessageBytes: number
+): Buffer {
+  const serverRid = encodeServiceWireRoutingId(descriptor.serverRid, 'serverRid', 0xff, fail);
+  const roleBody = concat(
+    encodeText8(descriptor.channelName, 'channelName'),
+    Buffer.of(DIRECTION_CLIENT_TO_SERVER),
+    concat(Buffer.of(serverRid.byteLength), serverRid),
+    encodeNonZeroU64(descriptor.lifecycleGeneration, 'lifecycleGeneration'),
+    encodeNonZeroU64(descriptor.descriptorRevision, 'descriptorRevision'),
+    encodeU32(descriptor.weight),
+    Buffer.of(runtimeStateToWire(descriptor.state)),
+    encodeText8(descriptor.securityIdentity, 'securityIdentity'),
+    encodeNonZeroU32(
+      normalizedEffectiveMaxMessageBytes,
+      'normalizedEffectiveMaxMessageBytes'
+    ),
+    encodeText16(descriptor.endpoint, 'advertisedEndpoint')
+  );
+  return encodeAdmission(command, ROLE_SERVER, roleBody);
+}
+
+function encodeAdmission(command: number, role: number, roleBody: Buffer): Buffer {
+  if (roleBody.byteLength > 0xffff) fail('ClientServer role body is oversized.');
+  const admission = concat(Buffer.of(role), encodeU16(roleBody.byteLength), roleBody);
+  const result = concat(
+    prefix(command),
+    Buffer.of(TOPOLOGY_CLIENT_SERVER),
+    encodeU32(admission.byteLength),
+    admission
+  );
+  if (result.byteLength > MAX_DESCRIPTOR_BYTES) fail('ClientServer admission is oversized.');
+  return result;
+}
+
+function decodeClientHello(reader: Reader): ZLinkClientServerHello {
+  const channelName = reader.text8('channelName');
+  if (reader.u8('direction') !== DIRECTION_CLIENT_TO_SERVER) {
+    fail('ClientServer direction is invalid.');
+  }
+  return {
+    channelName,
+    securityIdentity: reader.text8('securityIdentity'),
+    normalizedEffectiveMaxMessageBytes: reader.nonZeroU32(
+      'normalizedEffectiveMaxMessageBytes'
+    )
+  };
+}
+
+function decodeServerAdmission(reader: Reader): ZLinkClientServerAdmission {
+  const channelName = reader.text8('channelName');
+  if (reader.u8('direction') !== DIRECTION_CLIENT_TO_SERVER) {
+    fail('ClientServer direction is invalid.');
+  }
+  const serverRid = decodeServiceWireRoutingId(reader.bytes8('serverRid'), 'serverRid', 0xff, fail);
+  const lifecycleGeneration = reader.nonZeroU64('lifecycleGeneration');
+  const descriptorRevision = reader.nonZeroU64('descriptorRevision');
+  const weight = reader.u32('weight');
+  if (weight > 10_000) fail('ClientServer weight is invalid.');
+  return {
+    channelName,
+    serverRid,
+    lifecycleGeneration,
+    descriptorRevision,
+    weight,
+    state: runtimeStateFromWire(reader.u8('runtimeState')),
+    securityIdentity: reader.text8('securityIdentity'),
+    normalizedEffectiveMaxMessageBytes: reader.nonZeroU32(
+      'normalizedEffectiveMaxMessageBytes'
+    ),
+    advertisedEndpoint: normalizeEndpoint(reader.text16('advertisedEndpoint'))
+  };
+}
+
+function prefix(command: number): Buffer {
+  return Buffer.from([MAGIC_0, MAGIC_1, WIRE_MAJOR, command, 0]);
+}
+
+function encodeU16(value: number): Buffer {
+  const result = Buffer.alloc(2);
+  result.writeUInt16BE(value);
+  return result;
+}
+
+function encodeU32(value: number): Buffer {
+  if (!Number.isInteger(value) || value < 0 || value > MAX_U32) fail('Value exceeds u32.');
+  const result = Buffer.alloc(4);
+  result.writeUInt32BE(value);
+  return result;
+}
+
+function encodeNonZeroU32(value: number, field: string): Buffer {
+  if (!Number.isInteger(value) || value < 1 || value > MAX_U32) {
+    fail(`${field} must be a non-zero u32.`);
+  }
+  return encodeU32(value);
+}
+
+function encodeNonZeroU64(value: bigint, field: string): Buffer {
+  if (value < 1n || value > MAX_GENERATION) fail(`${field} must be a non-zero i63.`);
+  const result = Buffer.alloc(8);
+  result.writeBigUInt64BE(value);
+  return result;
+}
+
+function encodeText8(value: string, field: string): Buffer {
+  const bytes = encodeCanonicalServiceWireText(value, field, 0xff, fail);
+  return concat(Buffer.of(bytes.byteLength), bytes);
+}
+
+function encodeText16(value: string, field: string): Buffer {
+  const bytes = encodeCanonicalServiceWireText(value, field, 4096, fail);
+  return concat(encodeU16(bytes.byteLength), bytes);
+}
+
+function runtimeStateToWire(value: ZLinkFrameworkRuntimeState): number {
+  switch (value) {
+    case ZLinkFrameworkRuntimeState.Preparing: return 0;
+    case ZLinkFrameworkRuntimeState.Serving: return 1;
+    case ZLinkFrameworkRuntimeState.Relocating:
+    case ZLinkFrameworkRuntimeState.Relocated:
+    case ZLinkFrameworkRuntimeState.Draining: return 2;
+    case ZLinkFrameworkRuntimeState.Stopped: return 3;
+    case ZLinkFrameworkRuntimeState.Error: return 4;
+    default: fail('ClientServer runtime state is invalid.');
+  }
+}
+
+function runtimeStateFromWire(value: number): ZLinkFrameworkRuntimeState {
+  switch (value) {
+    case 0: return ZLinkFrameworkRuntimeState.Preparing;
+    case 1: return ZLinkFrameworkRuntimeState.Serving;
+    case 2: return ZLinkFrameworkRuntimeState.Draining;
+    case 3: return ZLinkFrameworkRuntimeState.Stopped;
+    case 4: return ZLinkFrameworkRuntimeState.Error;
+    default: fail('ClientServer runtime state is invalid.');
+  }
+}
+
+function concat(...parts: readonly Uint8Array[]): Buffer {
+  return Buffer.concat(parts);
+}
+
+function fail(message: string): never {
+  throw new ZLinkClientServerServiceWireError(message);
+}
+
+class Reader {
+  private readonly buffer: Buffer;
+  private offset = 0;
+
+  constructor(value: Uint8Array) {
+    this.buffer = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  }
+
+  get remaining(): number {
+    return this.buffer.byteLength - this.offset;
+  }
+
+  u8(field: string): number {
+    this.require(1, field);
+    return this.buffer[this.offset++]!;
+  }
+
+  u16(field: string): number {
+    this.require(2, field);
+    const value = this.buffer.readUInt16BE(this.offset);
+    this.offset += 2;
+    return value;
+  }
+
+  u32(field: string): number {
+    this.require(4, field);
+    const value = this.buffer.readUInt32BE(this.offset);
+    this.offset += 4;
+    return value;
+  }
+
+  nonZeroU32(field: string): number {
+    const value = this.u32(field);
+    if (value === 0) fail(`${field} must be non-zero.`);
+    return value;
+  }
+
+  nonZeroU64(field: string): bigint {
+    this.require(8, field);
+    const value = this.buffer.readBigUInt64BE(this.offset);
+    this.offset += 8;
+    if (value < 1n || value > MAX_GENERATION) fail(`${field} is invalid.`);
+    return value;
+  }
+
+  bytes(length: number, field: string): Buffer {
+    this.require(length, field);
+    const value = this.buffer.subarray(this.offset, this.offset + length);
+    this.offset += length;
+    return value;
+  }
+
+  bytes8(field: string): Buffer {
+    const length = this.u8(`${field}.length`);
+    if (length === 0) fail(`${field} must be non-empty.`);
+    return this.bytes(length, field);
+  }
+
+  text8(field: string): string {
+    return decodeText(this.bytes8(field), field);
+  }
+
+  text16(field: string): string {
+    const length = this.u16(`${field}.length`);
+    if (length < 1 || length > 4096) fail(`${field} length is invalid.`);
+    return decodeText(this.bytes(length, field), field);
+  }
+
+  end(): void {
+    if (this.remaining !== 0) fail('ClientServer control record has trailing bytes.');
+  }
+
+  private require(length: number, field: string): void {
+    if (length < 0 || length > this.remaining) fail(`${field} is truncated.`);
+  }
+}
+
+function decodeText(bytes: Buffer, field: string): string {
+  return decodeCanonicalServiceWireText(bytes, field, fail);
+}

package/src/runtime/channels/dispatch-error-reporter.ts

@@ -0,0 +1,165 @@
+import {
+  ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome,
+  ZLinkRuntimeDispatchErrorAction as ZLinkDispatchErrorAction,
+  ZLinkRuntimeDispatchErrorReason as ZLinkDispatchErrorReason,
+  ZLinkDispatchErrorSurface,
+  ZLinkDispatchMessageKind,
+  type ZLinkDispatchFailure
+} from '../../contracts/Dispatch/ZLinkDispatchOptions';
+import type { ZLinkRuntimeMetrics } from '../diagnostics';
+import {
+  ZLinkMessageFlowTracer,
+  DEFAULT_ZLINK_DIAGNOSTICS,
+  type ZLinkDiagnosticsContext
+} from '../diagnostics';
+import type { ZLinkDispatchErrorSink } from '../diagnostics/dispatch-error-port';
+
+export type { ZLinkDispatchErrorSink } from '../diagnostics/dispatch-error-port';
+
+type ZLinkRuntimeDispatchFailure = ZLinkDispatchFailure & {
+  readonly error?: unknown;
+};
+
+export class ZLinkDispatchErrorReporter {
+  private reportedEvents = 0;
+  /**
+   * Success-path tracer companion: every surface already receives a reporter, so
+   * exposing the flow tracer here wires all dispatch sites without threading a new
+   * parameter. Shares the same diagnostics context (live mode) and error sink.
+   */
+  readonly flow: ZLinkMessageFlowTracer;
+
+  constructor(
+    _observerType: undefined,
+    _providerResolver: unknown,
+    errorSink: ZLinkDispatchErrorSink,
+    ctx?: ZLinkDiagnosticsContext,
+    private readonly metrics?: ZLinkRuntimeMetrics
+  ) {
+    const flowCtx: ZLinkDiagnosticsContext = ctx ?? {
+      diagnostics: DEFAULT_ZLINK_DIAGNOSTICS,
+      liveMode: { mode: 'errors' },
+      sourceMeshGeneration: 0n
+    };
+    this.flow = new ZLinkMessageFlowTracer(flowCtx, errorSink);
+  }
+
+  report(event: ZLinkRuntimeDispatchFailure): void {
+    const normalized = normalizeDispatchFailure(event);
+    const tracePoint = this.flow.begin(ZLinkMessageFlowOutcome.Error);
+    const dropReason = channelDropReason(normalized);
+    if (dropReason !== undefined) {
+      this.metrics?.count('zlink.mesh_node.messages.dropped', 1, {
+        surface: normalized.surface,
+        message_kind: normalized.messageKind,
+        reason: dropReason
+      });
+    }
+    if (tracePoint === undefined) return;
+    const errorInfo = dispatchErrorInfo(normalized);
+    this.reportedEvents += 1;
+    tracePoint.trace({
+      outcome: ZLinkMessageFlowOutcome.Error,
+      surface: normalized.surface,
+      messageKind: normalized.messageKind,
+      packetName: normalized.packetName,
+      channelName: normalized.channelName,
+      channelRouteKind: normalized.channelRouteKind,
+      meshName: normalized.meshName,
+      topic: normalized.topic,
+      correlationId: normalized.correlationId,
+      flowId: normalized.flowId,
+      flowOrigin: normalized.flowOrigin,
+      sourceRid: normalized.sourceRid,
+      targetRid: normalized.targetRid,
+      serverRid: normalized.serverRid,
+      spotId: normalized.spotId,
+      instanceSpotType: normalized.instanceSpotType,
+      activationState: normalized.activationState,
+      actorId: normalized.actorId,
+      commandId: normalized.commandId,
+      errorReason: normalized.reason,
+      errorAction: normalized.action,
+      errorType: errorInfo.errorType,
+      errorMessage: errorInfo.errorMessage,
+      errorCauseType: errorInfo.errorCauseType,
+      errorCauseMessage: errorInfo.errorCauseMessage
+    });
+  }
+
+  get reportedCount(): number {
+    return this.reportedEvents;
+  }
+
+  get providerFailureCount(): number {
+    return this.flow.providerFailureCount;
+  }
+}
+
+function normalizeDispatchFailure(event: ZLinkRuntimeDispatchFailure): ZLinkRuntimeDispatchFailure {
+  if (event.messageKind !== 'publish') return event;
+  return {
+    ...event,
+    surface: ZLinkDispatchErrorSurface.ClassicFanout,
+    messageKind: ZLinkDispatchMessageKind.Send,
+    channelRouteKind: undefined
+  };
+}
+
+function channelDropReason(event: ZLinkRuntimeDispatchFailure): string | undefined {
+  if (
+    event.action !== ZLinkDispatchErrorAction.Drop
+    || (event.surface !== ZLinkDispatchErrorSurface.Channel
+      && event.surface !== ZLinkDispatchErrorSurface.RouteMeshChannel)
+  ) return undefined;
+  switch (event.reason) {
+    case ZLinkDispatchErrorReason.HandlerMissing:
+      return 'no_handler';
+    case ZLinkDispatchErrorReason.PayloadDecodeFailed:
+    case ZLinkDispatchErrorReason.InvalidFrame:
+      return 'decode_error';
+    default:
+      return undefined;
+  }
+}
+
+function dispatchErrorInfo(event: ZLinkRuntimeDispatchFailure): {
+  readonly errorType?: string;
+  readonly errorMessage?: string;
+  readonly errorCauseType?: string;
+  readonly errorCauseMessage?: string;
+} {
+  if (event.errorType !== undefined || event.errorMessage !== undefined) {
+    return {
+      errorType: event.errorType,
+      errorMessage: event.errorMessage,
+      errorCauseType: event.errorCauseType,
+      errorCauseMessage: event.errorCauseMessage
+    };
+  }
+  if (event.error === undefined) {
+    return {};
+  }
+  if (event.error instanceof Error) {
+    const cause = deepestErrorCause(event.error);
+    return {
+      errorType: event.error.name,
+      errorMessage: event.error.message,
+      ...(cause === event.error ? {} : {
+        errorCauseType: cause instanceof Error ? cause.name : typeof cause,
+        errorCauseMessage: cause instanceof Error ? cause.message : String(cause)
+      })
+    };
+  }
+  return { errorType: typeof event.error, errorMessage: String(event.error) };
+}
+
+function deepestErrorCause(error: Error): unknown {
+  let current: unknown = error;
+  const seen = new Set<unknown>();
+  while (current instanceof Error && current.cause !== undefined && !seen.has(current)) {
+    seen.add(current);
+    current = current.cause;
+  }
+  return current;
+}