@zlink-systems/framework 0.10.0

package/dist/runtime/channels/client-server-service-wire.js

@@ -0,0 +1,306 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkClientServerServiceWireError = void 0;
+exports.encodeClientServerHello = encodeClientServerHello;
+exports.encodeClientServerAdmit = encodeClientServerAdmit;
+exports.encodeClientServerUpdate = encodeClientServerUpdate;
+exports.encodeClientServerReject = encodeClientServerReject;
+exports.encodeClientServerLivenessProbe = encodeClientServerLivenessProbe;
+exports.encodeClientServerLivenessAck = encodeClientServerLivenessAck;
+exports.isClientServerControlFrame = isClientServerControlFrame;
+exports.decodeClientServerControl = decodeClientServerControl;
+const Locations_1 = require("../../contracts/Locations");
+const service_wire_binary_primitives_1 = require("../foundation/service-wire-binary-primitives");
+const EndpointNotation_1 = require("../../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 = 0x7fffffffffffffffn;
+class ZLinkClientServerServiceWireError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ZLinkClientServerServiceWireError';
+    }
+}
+exports.ZLinkClientServerServiceWireError = ZLinkClientServerServiceWireError;
+function encodeClientServerHello(value) {
+    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);
+}
+function encodeClientServerAdmit(descriptor, normalizedEffectiveMaxMessageBytes) {
+    return encodeServerAdmission(COMMAND_ADMIT, descriptor, normalizedEffectiveMaxMessageBytes);
+}
+function encodeClientServerUpdate(descriptor, normalizedEffectiveMaxMessageBytes) {
+    return encodeServerAdmission(COMMAND_UPDATE, descriptor, normalizedEffectiveMaxMessageBytes);
+}
+function encodeClientServerReject(reason) {
+    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));
+}
+function encodeClientServerLivenessProbe(probeId) {
+    return encodeLiveness(COMMAND_LIVENESS_PROBE, probeId);
+}
+function encodeClientServerLivenessAck(probeId) {
+    return encodeLiveness(COMMAND_LIVENESS_ACK, probeId);
+}
+function isClientServerControlFrame(frame) {
+    return frame.byteLength >= 5
+        && frame[0] === MAGIC_0
+        && frame[1] === MAGIC_1
+        && frame[2] === WIRE_MAJOR;
+}
+function decodeClientServerControl(frame) {
+    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, probeId) {
+    return concat(prefix(command), encodeNonZeroU64(probeId, 'probeId'));
+}
+function encodeServerAdmission(command, descriptor, normalizedEffectiveMaxMessageBytes) {
+    const serverRid = (0, service_wire_binary_primitives_1.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, role, roleBody) {
+    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) {
+    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) {
+    const channelName = reader.text8('channelName');
+    if (reader.u8('direction') !== DIRECTION_CLIENT_TO_SERVER) {
+        fail('ClientServer direction is invalid.');
+    }
+    const serverRid = (0, service_wire_binary_primitives_1.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: (0, EndpointNotation_1.normalizeEndpoint)(reader.text16('advertisedEndpoint'))
+    };
+}
+function prefix(command) {
+    return Buffer.from([MAGIC_0, MAGIC_1, WIRE_MAJOR, command, 0]);
+}
+function encodeU16(value) {
+    const result = Buffer.alloc(2);
+    result.writeUInt16BE(value);
+    return result;
+}
+function encodeU32(value) {
+    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, field) {
+    if (!Number.isInteger(value) || value < 1 || value > MAX_U32) {
+        fail(`${field} must be a non-zero u32.`);
+    }
+    return encodeU32(value);
+}
+function encodeNonZeroU64(value, field) {
+    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, field) {
+    const bytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(value, field, 0xff, fail);
+    return concat(Buffer.of(bytes.byteLength), bytes);
+}
+function encodeText16(value, field) {
+    const bytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(value, field, 4096, fail);
+    return concat(encodeU16(bytes.byteLength), bytes);
+}
+function runtimeStateToWire(value) {
+    switch (value) {
+        case Locations_1.ZLinkFrameworkRuntimeState.Preparing: return 0;
+        case Locations_1.ZLinkFrameworkRuntimeState.Serving: return 1;
+        case Locations_1.ZLinkFrameworkRuntimeState.Relocating:
+        case Locations_1.ZLinkFrameworkRuntimeState.Relocated:
+        case Locations_1.ZLinkFrameworkRuntimeState.Draining: return 2;
+        case Locations_1.ZLinkFrameworkRuntimeState.Stopped: return 3;
+        case Locations_1.ZLinkFrameworkRuntimeState.Error: return 4;
+        default: fail('ClientServer runtime state is invalid.');
+    }
+}
+function runtimeStateFromWire(value) {
+    switch (value) {
+        case 0: return Locations_1.ZLinkFrameworkRuntimeState.Preparing;
+        case 1: return Locations_1.ZLinkFrameworkRuntimeState.Serving;
+        case 2: return Locations_1.ZLinkFrameworkRuntimeState.Draining;
+        case 3: return Locations_1.ZLinkFrameworkRuntimeState.Stopped;
+        case 4: return Locations_1.ZLinkFrameworkRuntimeState.Error;
+        default: fail('ClientServer runtime state is invalid.');
+    }
+}
+function concat(...parts) {
+    return Buffer.concat(parts);
+}
+function fail(message) {
+    throw new ZLinkClientServerServiceWireError(message);
+}
+class Reader {
+    buffer;
+    offset = 0;
+    constructor(value) {
+        this.buffer = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+    }
+    get remaining() {
+        return this.buffer.byteLength - this.offset;
+    }
+    u8(field) {
+        this.require(1, field);
+        return this.buffer[this.offset++];
+    }
+    u16(field) {
+        this.require(2, field);
+        const value = this.buffer.readUInt16BE(this.offset);
+        this.offset += 2;
+        return value;
+    }
+    u32(field) {
+        this.require(4, field);
+        const value = this.buffer.readUInt32BE(this.offset);
+        this.offset += 4;
+        return value;
+    }
+    nonZeroU32(field) {
+        const value = this.u32(field);
+        if (value === 0)
+            fail(`${field} must be non-zero.`);
+        return value;
+    }
+    nonZeroU64(field) {
+        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, field) {
+        this.require(length, field);
+        const value = this.buffer.subarray(this.offset, this.offset + length);
+        this.offset += length;
+        return value;
+    }
+    bytes8(field) {
+        const length = this.u8(`${field}.length`);
+        if (length === 0)
+            fail(`${field} must be non-empty.`);
+        return this.bytes(length, field);
+    }
+    text8(field) {
+        return decodeText(this.bytes8(field), field);
+    }
+    text16(field) {
+        const length = this.u16(`${field}.length`);
+        if (length < 1 || length > 4096)
+            fail(`${field} length is invalid.`);
+        return decodeText(this.bytes(length, field), field);
+    }
+    end() {
+        if (this.remaining !== 0)
+            fail('ClientServer control record has trailing bytes.');
+    }
+    require(length, field) {
+        if (length < 0 || length > this.remaining)
+            fail(`${field} is truncated.`);
+    }
+}
+function decodeText(bytes, field) {
+    return (0, service_wire_binary_primitives_1.decodeCanonicalServiceWireText)(bytes, field, fail);
+}

package/dist/runtime/channels/dispatch-error-reporter.d.ts

@@ -0,0 +1,22 @@
+import { type ZLinkDispatchFailure } from '../../contracts/Dispatch/ZLinkDispatchOptions';
+import type { ZLinkRuntimeMetrics } from '../diagnostics';
+import { ZLinkMessageFlowTracer, 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 declare class ZLinkDispatchErrorReporter {
+    private readonly metrics?;
+    private reportedEvents;
+    /**
+     * 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, metrics?: ZLinkRuntimeMetrics | undefined);
+    report(event: ZLinkRuntimeDispatchFailure): void;
+    get reportedCount(): number;
+    get providerFailureCount(): number;
+}

package/dist/runtime/channels/dispatch-error-reporter.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkDispatchErrorReporter = void 0;
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const diagnostics_1 = require("../diagnostics");
+class ZLinkDispatchErrorReporter {
+    metrics;
+    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.
+     */
+    flow;
+    constructor(_observerType, _providerResolver, errorSink, ctx, metrics) {
+        this.metrics = metrics;
+        const flowCtx = ctx ?? {
+            diagnostics: diagnostics_1.DEFAULT_ZLINK_DIAGNOSTICS,
+            liveMode: { mode: 'errors' },
+            sourceMeshGeneration: 0n
+        };
+        this.flow = new diagnostics_1.ZLinkMessageFlowTracer(flowCtx, errorSink);
+    }
+    report(event) {
+        const normalized = normalizeDispatchFailure(event);
+        const tracePoint = this.flow.begin(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.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: ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.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() {
+        return this.reportedEvents;
+    }
+    get providerFailureCount() {
+        return this.flow.providerFailureCount;
+    }
+}
+exports.ZLinkDispatchErrorReporter = ZLinkDispatchErrorReporter;
+function normalizeDispatchFailure(event) {
+    if (event.messageKind !== 'publish')
+        return event;
+    return {
+        ...event,
+        surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.ClassicFanout,
+        messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+        channelRouteKind: undefined
+    };
+}
+function channelDropReason(event) {
+    if (event.action !== ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop
+        || (event.surface !== ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.Channel
+            && event.surface !== ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.RouteMeshChannel))
+        return undefined;
+    switch (event.reason) {
+        case ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerMissing:
+            return 'no_handler';
+        case ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.PayloadDecodeFailed:
+        case ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.InvalidFrame:
+            return 'decode_error';
+        default:
+            return undefined;
+    }
+}
+function dispatchErrorInfo(event) {
+    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) {
+    let current = error;
+    const seen = new Set();
+    while (current instanceof Error && current.cause !== undefined && !seen.has(current)) {
+        seen.add(current);
+        current = current.cause;
+    }
+    return current;
+}

package/dist/runtime/channels/fanout-location-runtime.d.ts

@@ -0,0 +1,38 @@
+import { type ZLinkFanoutPublisherDescriptor } from '../../contracts/Locations';
+import { type ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkLocationRuntime, ZLinkLocationRuntimeStores } from '../locations';
+import type { ZLinkBackendSubscriberSocket } from '../backend/contracts';
+import { ZLinkChannelSocketRegistry } from './channel-socket-registry';
+export declare class ZLinkFanoutLocationRuntime {
+    private readonly registration;
+    private readonly sockets;
+    private readonly locationRuntime;
+    private readonly stores;
+    private readonly onSubscriberOpened;
+    private readonly lane;
+    private readonly options;
+    private readonly store;
+    private readonly localDescriptors;
+    private readonly publisherIdentities;
+    private readonly connections;
+    private controller?;
+    private timer?;
+    constructor(registration: ZLinkFrameworkRegistration, sockets: ZLinkChannelSocketRegistry, locationRuntime: ZLinkLocationRuntime, stores: ZLinkLocationRuntimeStores, options: ZLinkLocationOptionOverrides, onSubscriberOpened: (channelName: string, connectionId: string, subscriber: ZLinkBackendSubscriberSocket) => () => Promise<void>);
+    start(signal?: AbortSignal): Promise<void>;
+    tick(signal?: AbortSignal): Promise<void>;
+    private tickCore;
+    stop(signal?: AbortSignal): Promise<void>;
+    activeTargets(channelName: string): readonly ZLinkFanoutPublisherDescriptor[];
+    reclaimOwnerRows(signal?: AbortSignal): Promise<void>;
+    private publishLocalPublishers;
+    private reconcileSubscribers;
+    private openConnection;
+    private closeConnection;
+    private replaceConnection;
+    private listLivePublishers;
+    private storeOwnerLease;
+    private removeLocalPublishers;
+    private requireOwnerToken;
+    private schedule;
+}