@zlink-systems/framework 0.10.0

package/dist/nest-integration.d.ts

@@ -0,0 +1,49 @@
+export { ZLinkConfigurationException, createFrameworkRegistration, hasActorManager, hasSpotNode, hasSpotPublisherClient } from './contracts/Configuration/Registration';
+export type * from './contracts/Configuration/RegistrationTypes';
+export type * from './contracts';
+export { registerActorFactory, validateRoutingIdPrefix, registerEntrySpot, registerSpotFactory, validateActorTransferTimeout, validateMessageFollowDuration, validateSessionReplacementCallbackTimeout } from './contracts/Configuration/RegistrationBuilderPolicy';
+import type { ZLinkLocationRuntimeQuery, ZLinkActorClient, ZLinkActorManager, ZLinkChannelClient, ZLinkClientServerRuntime, ZLinkCodecRegistryBuilder, ZLinkCodecRegistrar, ZLinkDispatchOptions, ZLinkDispatchOptionsBuilder, ZLinkFanoutClient, ZLinkFanoutRuntime, ZLinkRouteClient, ZLinkRouteMeshRuntime, ZLinkRouteMeshRuntimeOptions, ZLinkSpotManager, ZLinkSpotOutbound, ZLinkSpotPublisherClient, ZLinkStreamCompressionBuilder, ZLinkStreamCompressionCodec } from './contracts';
+import type { ZLinkProviderResolver } from './contracts/Common/ZLinkProviderResolver';
+import type { ZLinkSpotHandleResolver } from './runtime/spots/spot-handle';
+import type { ZLinkBoundSessionFactory } from './runtime/streams/session-context';
+import type { ZLinkFrameworkRegistration } from './contracts/Configuration/Registration';
+import type { ZLinkCodecSerializerRegistration, ZLinkFrameworkRegistrationOptions, ZLinkStreamCodecRegistration } from './contracts/Configuration/RegistrationTypes';
+import { captureZLinkExecutionTurn } from './runtime/execution';
+export { registerHandlerFilterScope as registerIntegrationHandlerFilterScope, type ZLinkHandlerFilterScopeRunner } from './runtime/channels/handler-filter-scope';
+export interface ZLinkNestIntegrationRuntimeHost extends Pick<import('./contracts').ZLinkFrameworkRuntime, 'shutdown'> {
+    readonly channelRuntimeOptions: unknown;
+    readonly routeMeshRuntimeOptions: ZLinkRouteMeshRuntimeOptions;
+    readonly boundSessionFactory: ZLinkBoundSessionFactory;
+    readonly locationRuntimeQuery?: ZLinkLocationRuntimeQuery;
+    readonly routeMeshRuntime: ZLinkRouteMeshRuntime;
+    readonly clientServerRuntime: ZLinkClientServerRuntime;
+    readonly fanoutRuntime: ZLinkFanoutRuntime;
+    createLocationHandleResolver(): ZLinkSpotHandleResolver | undefined;
+    start(): Promise<void>;
+    onApplicationBootstrap?(): Promise<void> | void;
+    onApplicationShutdown?(): Promise<void> | void;
+}
+export declare function createIntegrationDispatchOptionsBuilder(dispatch: ZLinkDispatchOptions): ZLinkDispatchOptionsBuilder;
+export declare function createIntegrationInboundDispatchOptionsBuilder(options: Pick<ZLinkFrameworkRegistrationOptions, 'coreHwm' | 'applicationJobQueue'>): import('./contracts').ZLinkInboundDispatchOptions;
+export declare function createIntegrationLocationOptionsBuilder(options: Partial<import('./contracts').ZLinkLocationOptionValues>): import('./contracts').ZLinkLocationOptions;
+export declare function createIntegrationStreamCompressionBuilder(options: {
+    disabled?: boolean;
+    codec?: ZLinkStreamCompressionCodec;
+}): ZLinkStreamCompressionBuilder;
+export declare function createIntegrationCodecRegistryBuilder(options: {
+    serializers: ZLinkCodecSerializerRegistration[];
+    streamCodecs: ZLinkStreamCodecRegistration[];
+}): ZLinkCodecRegistryBuilder & ZLinkCodecRegistrar;
+export declare function createIntegrationRuntimeHost(registration: ZLinkFrameworkRegistration, providerResolver?: ZLinkProviderResolver): ZLinkNestIntegrationRuntimeHost;
+export declare function createIntegrationChannelClient(registration: ZLinkFrameworkRegistration, runtime: ZLinkNestIntegrationRuntimeHost): ZLinkChannelClient;
+export declare function createIntegrationFanoutClient(registration: ZLinkFrameworkRegistration, runtime: ZLinkNestIntegrationRuntimeHost): ZLinkFanoutClient;
+export declare function createIntegrationRouteClient(registration: ZLinkFrameworkRegistration, runtime: ZLinkNestIntegrationRuntimeHost): ZLinkRouteClient;
+export declare function createIntegrationSpotPublisherClient(registration: ZLinkFrameworkRegistration, runtime: ZLinkNestIntegrationRuntimeHost): ZLinkSpotPublisherClient;
+export declare function createIntegrationActorClient(runtime: ZLinkNestIntegrationRuntimeHost): ZLinkActorClient;
+export declare function createIntegrationActorManager(registration: ZLinkFrameworkRegistration, runtime: ZLinkNestIntegrationRuntimeHost, providerResolver?: ZLinkProviderResolver): ZLinkActorManager;
+export declare function createIntegrationSpotManager(registration: ZLinkFrameworkRegistration, runtime: ZLinkNestIntegrationRuntimeHost, providerResolver?: ZLinkProviderResolver): ZLinkSpotManager;
+export declare function createIntegrationSpotOutbound(runtime: ZLinkNestIntegrationRuntimeHost): ZLinkSpotOutbound;
+export declare function createIntegrationHttpExecutionScheduler(runtime: ZLinkNestIntegrationRuntimeHost): {
+    capture: typeof captureZLinkExecutionTurn;
+    reportError(error: unknown): void;
+};

package/dist/nest-integration.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerIntegrationHandlerFilterScope = exports.validateSessionReplacementCallbackTimeout = exports.validateMessageFollowDuration = exports.validateActorTransferTimeout = exports.registerSpotFactory = exports.registerEntrySpot = exports.validateRoutingIdPrefix = exports.registerActorFactory = exports.hasSpotPublisherClient = exports.hasSpotNode = exports.hasActorManager = exports.createFrameworkRegistration = exports.ZLinkConfigurationException = void 0;
+exports.createIntegrationDispatchOptionsBuilder = createIntegrationDispatchOptionsBuilder;
+exports.createIntegrationInboundDispatchOptionsBuilder = createIntegrationInboundDispatchOptionsBuilder;
+exports.createIntegrationLocationOptionsBuilder = createIntegrationLocationOptionsBuilder;
+exports.createIntegrationStreamCompressionBuilder = createIntegrationStreamCompressionBuilder;
+exports.createIntegrationCodecRegistryBuilder = createIntegrationCodecRegistryBuilder;
+exports.createIntegrationRuntimeHost = createIntegrationRuntimeHost;
+exports.createIntegrationChannelClient = createIntegrationChannelClient;
+exports.createIntegrationFanoutClient = createIntegrationFanoutClient;
+exports.createIntegrationRouteClient = createIntegrationRouteClient;
+exports.createIntegrationSpotPublisherClient = createIntegrationSpotPublisherClient;
+exports.createIntegrationActorClient = createIntegrationActorClient;
+exports.createIntegrationActorManager = createIntegrationActorManager;
+exports.createIntegrationSpotManager = createIntegrationSpotManager;
+exports.createIntegrationSpotOutbound = createIntegrationSpotOutbound;
+exports.createIntegrationHttpExecutionScheduler = createIntegrationHttpExecutionScheduler;
+var Registration_1 = require("./contracts/Configuration/Registration");
+Object.defineProperty(exports, "ZLinkConfigurationException", { enumerable: true, get: function () { return Registration_1.ZLinkConfigurationException; } });
+Object.defineProperty(exports, "createFrameworkRegistration", { enumerable: true, get: function () { return Registration_1.createFrameworkRegistration; } });
+Object.defineProperty(exports, "hasActorManager", { enumerable: true, get: function () { return Registration_1.hasActorManager; } });
+Object.defineProperty(exports, "hasSpotNode", { enumerable: true, get: function () { return Registration_1.hasSpotNode; } });
+Object.defineProperty(exports, "hasSpotPublisherClient", { enumerable: true, get: function () { return Registration_1.hasSpotPublisherClient; } });
+var RegistrationBuilderPolicy_1 = require("./contracts/Configuration/RegistrationBuilderPolicy");
+Object.defineProperty(exports, "registerActorFactory", { enumerable: true, get: function () { return RegistrationBuilderPolicy_1.registerActorFactory; } });
+Object.defineProperty(exports, "validateRoutingIdPrefix", { enumerable: true, get: function () { return RegistrationBuilderPolicy_1.validateRoutingIdPrefix; } });
+Object.defineProperty(exports, "registerEntrySpot", { enumerable: true, get: function () { return RegistrationBuilderPolicy_1.registerEntrySpot; } });
+Object.defineProperty(exports, "registerSpotFactory", { enumerable: true, get: function () { return RegistrationBuilderPolicy_1.registerSpotFactory; } });
+Object.defineProperty(exports, "validateActorTransferTimeout", { enumerable: true, get: function () { return RegistrationBuilderPolicy_1.validateActorTransferTimeout; } });
+Object.defineProperty(exports, "validateMessageFollowDuration", { enumerable: true, get: function () { return RegistrationBuilderPolicy_1.validateMessageFollowDuration; } });
+Object.defineProperty(exports, "validateSessionReplacementCallbackTimeout", { enumerable: true, get: function () { return RegistrationBuilderPolicy_1.validateSessionReplacementCallbackTimeout; } });
+const RegistrationBuilders_1 = require("./contracts/Configuration/RegistrationBuilders");
+const RegistrationCodecRegistry_1 = require("./contracts/Configuration/RegistrationCodecRegistry");
+const channels_1 = require("./runtime/channels");
+const actors_1 = require("./runtime/actors");
+const host_1 = require("./runtime/host");
+const spots_1 = require("./runtime/spots");
+const workers_1 = require("./runtime/workers");
+const execution_1 = require("./runtime/execution");
+var handler_filter_scope_1 = require("./runtime/channels/handler-filter-scope");
+Object.defineProperty(exports, "registerIntegrationHandlerFilterScope", { enumerable: true, get: function () { return handler_filter_scope_1.registerHandlerFilterScope; } });
+function createIntegrationDispatchOptionsBuilder(dispatch) {
+    return new RegistrationBuilders_1.DefaultDispatchOptionsBuilder(dispatch);
+}
+function createIntegrationInboundDispatchOptionsBuilder(options) {
+    return new RegistrationBuilders_1.DefaultInboundDispatchOptionsBuilder(options);
+}
+function createIntegrationLocationOptionsBuilder(options) {
+    return new RegistrationBuilders_1.DefaultLocationOptionsBuilder(options);
+}
+function createIntegrationStreamCompressionBuilder(options) {
+    return new RegistrationBuilders_1.DefaultStreamCompressionBuilder(options);
+}
+function createIntegrationCodecRegistryBuilder(options) {
+    return new RegistrationCodecRegistry_1.RegistrationCodecRegistryBuilder(options);
+}
+function createIntegrationRuntimeHost(registration, providerResolver) {
+    return new host_1.ZLinkFrameworkRuntimeHost({ registration, providerResolver });
+}
+function createIntegrationChannelClient(registration, runtime) {
+    return new channels_1.DefaultZLinkChannelClient(registration, runtimeHost(runtime).channelTransport);
+}
+function createIntegrationFanoutClient(registration, runtime) {
+    return new channels_1.DefaultZLinkFanoutClient(registration, runtimeHost(runtime).channelTransport);
+}
+function createIntegrationRouteClient(registration, runtime) {
+    const host = runtimeHost(runtime);
+    return new channels_1.DefaultZLinkRouteClient(registration, host.routeTransport, host.spotRouterChannelIdForMesh);
+}
+function createIntegrationSpotPublisherClient(registration, runtime) {
+    return new channels_1.DefaultZLinkSpotPublisherClient(registration, runtimeHost(runtime).spotPublisherTransport);
+}
+function createIntegrationActorClient(runtime) {
+    const host = runtimeHost(runtime);
+    return new actors_1.DefaultZLinkActorClient(host.createActorClientOptions());
+}
+function createIntegrationActorManager(registration, runtime, providerResolver) {
+    const host = runtimeHost(runtime);
+    const runtimeOptions = host.createActorManagerOptions();
+    const manager = new actors_1.DefaultZLinkActorManager({
+        actorFactories: registration.actorFactories,
+        ...runtimeOptions,
+        boundSessionFactory: runtimeOptions.boundSessionFactory ?? host.boundSessionFactory.create.bind(host.boundSessionFactory),
+        providerResolver
+    });
+    host.setActorManager(manager);
+    return manager;
+}
+function createIntegrationSpotManager(registration, runtime, providerResolver) {
+    const host = runtimeHost(runtime);
+    const runtimeOptions = host.createSpotManagerOptions();
+    const manager = new spots_1.DefaultZLinkSpotManager({
+        spotFactories: [...registration.spotFactories],
+        instanceSpotFactories: new Map([...registration.spotNodes].map(([meshName, spotNode]) => [
+            meshName,
+            new Map(Object.entries(spotNode.instanceSpotFactories ?? {}))
+        ])),
+        instanceSpotIdleTimeoutMs: new Map([...registration.spotNodes].map(([meshName, spotNode]) => [
+            meshName,
+            spotNode.instanceSpotIdleTimeoutMs ?? 0
+        ])),
+        spotTimerHandlers: [...registration.spotNodes.values()]
+            .flatMap((spotNode) => [...(spotNode.spotTimerHandlers ?? [])]),
+        spotPacketHandlers: [...registration.spotNodes.values()]
+            .flatMap((spotNode) => [...(spotNode.spotPacketHandlers ?? [])]),
+        spotSubscriptionHandlers: [...registration.spotNodes.values()]
+            .flatMap((spotNode) => [...(spotNode.spotSubscriptionHandlers ?? [])]),
+        spotActorSendHandlers: [...registration.spotNodes.values()]
+            .flatMap((spotNode) => [...(spotNode.spotActorSendHandlers ?? [])]),
+        spotActorRequestHandlers: [...registration.spotNodes.values()]
+            .flatMap((spotNode) => [...(spotNode.spotActorRequestHandlers ?? [])]),
+        ...runtimeOptions,
+        spotRouteResolver: runtimeOptions.spotRouteResolver,
+        routedTransport: host.routeTransport,
+        providerResolver,
+        workerRuntime: new workers_1.ZLinkWorkerRuntime(registration.worker)
+    });
+    host.setSpotManager(manager);
+    return host.createPublicSpotManager(manager);
+}
+function createIntegrationSpotOutbound(runtime) {
+    const host = runtimeHost(runtime);
+    const runtimeOptions = host.createSpotManagerOptions();
+    return new spots_1.DefaultZLinkSpotOutbound({
+        serial: new spots_1.ZLinkSpotSerialTurnExecutor(),
+        routedTransport: host.routeTransport,
+        spotRouterChannelIdForMesh: runtimeOptions.spotRouterChannelIdForMesh,
+        addressTransport: host.spotAddressTransport
+    });
+}
+function createIntegrationHttpExecutionScheduler(runtime) {
+    return {
+        capture: execution_1.captureZLinkExecutionTurn,
+        reportError(error) {
+            const host = runtimeHost(runtime);
+            host.errorSink?.reportRuntimeTaskException('http client submit', error);
+        }
+    };
+}
+function runtimeHost(runtime) {
+    return runtime;
+}

package/dist/runtime/abort.d.ts

@@ -0,0 +1,13 @@
+/** The typed cancellation error produced by Framework admission helpers. */
+export declare class ZLinkAbortError extends Error {
+    constructor(message?: string);
+}
+export declare class ZLinkDeadlineExceededError extends Error {
+    constructor(message?: string);
+}
+export declare function createAbortError(): ZLinkAbortError;
+export declare function isAbortError(error: unknown): boolean;
+export declare function createDeadlineExceededError(message?: string): ZLinkDeadlineExceededError;
+export declare function isDeadlineExceededError(error: unknown): boolean;
+export declare function throwIfAborted(signal: AbortSignal | undefined): void;
+export declare function awaitWithAbort<T>(operation: Promise<T>, signal: AbortSignal | undefined, abortOperation?: () => void): Promise<T>;

package/dist/runtime/abort.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkDeadlineExceededError = exports.ZLinkAbortError = void 0;
+exports.createAbortError = createAbortError;
+exports.isAbortError = isAbortError;
+exports.createDeadlineExceededError = createDeadlineExceededError;
+exports.isDeadlineExceededError = isDeadlineExceededError;
+exports.throwIfAborted = throwIfAborted;
+exports.awaitWithAbort = awaitWithAbort;
+/** The typed cancellation error produced by Framework admission helpers. */
+class ZLinkAbortError extends Error {
+    constructor(message = 'The operation was aborted.') {
+        super(message);
+        this.name = 'AbortError';
+    }
+}
+exports.ZLinkAbortError = ZLinkAbortError;
+class ZLinkDeadlineExceededError extends Error {
+    constructor(message = 'The operation deadline was exceeded.') {
+        super(message);
+        this.name = 'DeadlineExceededError';
+    }
+}
+exports.ZLinkDeadlineExceededError = ZLinkDeadlineExceededError;
+function createAbortError() {
+    return new ZLinkAbortError();
+}
+function isAbortError(error) {
+    return error instanceof ZLinkAbortError
+        || (error instanceof DOMException && error.name === 'AbortError');
+}
+function createDeadlineExceededError(message) {
+    return new ZLinkDeadlineExceededError(message);
+}
+function isDeadlineExceededError(error) {
+    return error instanceof ZLinkDeadlineExceededError;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted === true) {
+        throw createAbortError();
+    }
+}
+function awaitWithAbort(operation, signal, abortOperation) {
+    if (signal?.aborted === true) {
+        abortOperation?.();
+        throw createAbortError();
+    }
+    if (signal === undefined) {
+        return operation;
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return false;
+            settled = true;
+            signal.removeEventListener('abort', abort);
+            return true;
+        };
+        const abort = () => {
+            if (!settle())
+                return;
+            abortOperation?.();
+            reject(createAbortError());
+        };
+        signal.addEventListener('abort', abort, { once: true });
+        operation.then((value) => { if (settle())
+            resolve(value); }, (error) => { if (settle())
+            reject(error); });
+    });
+}

package/dist/runtime/actors/actor-authority-payload-codec.d.ts

@@ -0,0 +1,33 @@
+import type { RoutingId } from '../../contracts';
+import { ZLinkSpotKind } from '../../contracts';
+export type ZLinkActorAuthorityState = 'creating' | 'ready';
+export interface ZLinkActorAuthorityPayload {
+    readonly state: ZLinkActorAuthorityState;
+    readonly stableType: string;
+    readonly actorId: string;
+    readonly currentSpotId: string;
+    readonly currentSpotGeneration: bigint;
+    readonly currentSpotKind: ZLinkSpotKind.Entry | ZLinkSpotKind.User;
+    readonly ownerId: string;
+    readonly ownerLeaseGeneration: bigint;
+    readonly meshName: string;
+    readonly nodeRid: RoutingId;
+    readonly nodeGeneration: bigint;
+}
+export interface ZLinkCanonicalAuthorityPayload {
+    readonly body: Buffer;
+}
+/** Encodes the durable authority-payload-v1 envelope around one schema body. */
+export declare function encodeCanonicalAuthorityPayload(value: ZLinkCanonicalAuthorityPayload): Buffer;
+/** Decodes and checksum-validates the durable authority-payload-v1 envelope. */
+export declare function decodeCanonicalAuthorityPayload(payload: Uint8Array): ZLinkCanonicalAuthorityPayload | undefined;
+/** Byte-exact Node counterpart of .NET ZLinkActorAuthorityPayloadCodec.Encode. */
+export declare function encodeActorAuthorityPayload(value: ZLinkActorAuthorityPayload): Buffer;
+/** Byte-exact Node counterpart of .NET ZLinkActorAuthorityPayloadCodec.TryDecodeDirect. */
+export declare function decodeActorAuthorityPayload(payload: Uint8Array): ZLinkActorAuthorityPayload | undefined;
+/** Returns the ZLAU payload only when a .NET-compatible ZLAP is Steady. */
+export declare function actorRelocationAuthorityApplicationPayload(payload: Uint8Array): Buffer | undefined;
+/** Returns the ZLAU payload from every valid .NET-compatible ZLAP phase. */
+export declare function relocatingActorAuthorityApplicationPayload(payload: Uint8Array): Buffer;
+/** Replaces only the application payload of a valid ZLAP phase envelope. */
+export declare function replaceActorRelocationAuthorityApplicationPayload(payload: Uint8Array, applicationPayload: Uint8Array): Buffer;