@zlink-systems/nestjs 0.10.0

package/dist/framework-integration-contracts.d.ts

@@ -0,0 +1,368 @@
+import type { RoutingId, Type, ZLinkActor, ZLinkActorFactory, ZLinkApplicationJobQueueOptions, ZLinkCoreHwmOptions, ZLinkDispatchOptions, ZLinkEntrySpot, ZLinkHandlerFilter, ZLinkLocationOptions, ZLinkLocationOptionValues, ZLinkLocationStore, ZLinkRelocationStore, ZLinkSpotRelocationCoordinationMode, ZLinkUserSpotExecutionMode, ZLinkInstanceSpot, ZLinkMessageSerializer, ZLinkMetricsOptions, ZLinkNetworkOptions, ZLinkMessageContext, ZLinkPublishMessageContext, ZLinkRouteMessageContext, ZLinkSpot, ZLinkStreamCompressionOptions, ZLinkTimerOptions } from '@zlink-systems/framework';
+/** Private composition bridge used only by the Nest companion package. */
+export interface ZLinkProviderResolver {
+    get?<T>(type: Type<T>): T | undefined;
+    create?<T>(type: Type<T>): T | Promise<T>;
+}
+export interface ZLinkWorkerOptions {
+    readonly minThreads: number;
+    readonly maxThreads: number;
+    readonly idleTimeoutMs: number;
+    readonly maxQueueLength: number;
+}
+export interface ZLinkNestIntegrationRuntimeHost extends Pick<import('@zlink-systems/framework').ZLinkFrameworkRuntime, 'shutdown'> {
+    readonly channelRuntimeOptions: unknown;
+    readonly routeMeshRuntimeOptions: import('@zlink-systems/framework').ZLinkRouteMeshRuntimeOptions;
+    readonly boundSessionFactory: unknown;
+    readonly locationRuntimeQuery?: unknown;
+    readonly routeMeshRuntime: import('@zlink-systems/framework').ZLinkRouteMeshRuntime;
+    readonly clientServerRuntime: import('@zlink-systems/framework').ZLinkClientServerRuntime;
+    readonly fanoutRuntime: import('@zlink-systems/framework').ZLinkFanoutRuntime;
+    createLocationHandleResolver(): unknown;
+    start(): Promise<void>;
+    onApplicationBootstrap?(): Promise<void> | void;
+    onApplicationShutdown?(): Promise<void> | void;
+}
+export interface ZLinkRouteChannelSendHandler {
+    handle(payload: unknown, context: ZLinkRouteMessageContext): Promise<void>;
+}
+export interface ZLinkRouteChannelRequestHandler {
+    handle(payload: unknown, context: ZLinkRouteMessageContext): Promise<unknown>;
+}
+export interface ZLinkFrameworkRegistration {
+    readonly network: ZLinkNetworkOptions;
+    readonly messageSerializers: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly codecs: ZLinkCodecRegistration;
+    readonly requestTimeoutMs?: number;
+    readonly actorFactories: ReadonlyMap<string, Type>;
+    readonly actorTransferTimeoutMs?: number;
+    readonly messageFollowDurationMs: number;
+    readonly sessionReplacementCallbackTimeoutMs: number;
+    readonly spotFactories: ReadonlySet<Type<ZLinkSpot>>;
+    readonly channels: ReadonlyMap<string, ZLinkChannelOptions>;
+    readonly channelClients: ReadonlySet<string>;
+    readonly fanoutPublishers: ReadonlySet<string>;
+    readonly routeChannels: ReadonlySet<string>;
+    readonly routeChannelOptions: ReadonlyMap<string, ZLinkRouteChannelOptions>;
+    readonly streamNodes: ReadonlyMap<string, ZLinkStreamNodeOptions>;
+    readonly streamCompression?: ZLinkStreamCompressionOptions;
+    readonly spotNodes: ReadonlyMap<string, ZLinkSpotNodeOptions>;
+    readonly spotPublisherClients: ReadonlySet<string>;
+    readonly filterTypes: readonly Type<ZLinkHandlerFilter>[];
+    readonly worker?: ZLinkWorkerOptions;
+    readonly coreHwm?: ZLinkCoreHwmOptions;
+    readonly applicationJobQueue?: ZLinkApplicationJobQueueOptions;
+    readonly dispatch?: ZLinkDispatchOptions;
+    readonly metrics?: ZLinkMetricsOptions;
+    readonly locations: ZLinkLocationRegistration;
+}
+export interface ZLinkLocationRegistration {
+    readonly useInMemoryStores: boolean;
+    readonly storeInstance?: ZLinkLocationStore;
+    readonly relocationStoreInstance?: ZLinkRelocationStore;
+    readonly options: ZLinkLocationOptions;
+}
+export interface ZLinkCodecSerializerRegistration {
+    readonly contentType: string;
+    readonly serializer: ZLinkMessageSerializer;
+}
+export interface ZLinkStreamCodecRegistration {
+    readonly contentType: string;
+    readonly codec: unknown;
+}
+export interface ZLinkCodecRegistration {
+    readonly serializers: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly streamCodecs: ReadonlyMap<string, unknown>;
+}
+export interface ZLinkCodecRegistryOptions {
+    readonly serializers?: readonly ZLinkCodecSerializerRegistration[];
+    readonly streamCodecs?: readonly ZLinkStreamCodecRegistration[];
+}
+export interface ZLinkFrameworkRegistrationOptions {
+    readonly network?: Partial<ZLinkNetworkOptions>;
+    readonly codecs?: ZLinkCodecRegistryOptions;
+    readonly applicationVersion?: bigint;
+    readonly maintenanceWave?: string;
+    readonly requestTimeoutMs?: number;
+    readonly spotFactories?: readonly Type<ZLinkSpot>[];
+    readonly actorTransferTimeoutMs?: number;
+    readonly messageFollowDurationMs?: number;
+    readonly sessionReplacementCallbackTimeoutMs?: number;
+    readonly channels?: Readonly<Record<string, ZLinkChannelOptions>>;
+    readonly routeChannels?: readonly (string | ZLinkRouteChannelOptions)[];
+    readonly streamNodes?: Readonly<Record<string, ZLinkStreamNodeOptions>>;
+    readonly streamCompression?: ZLinkStreamCompressionOptions;
+    readonly spotNodes?: readonly (string | ZLinkSpotNodeRegistrationOptions)[] | Readonly<Record<string, ZLinkSpotNodeOptions>>;
+    readonly spotPublisherClients?: readonly string[];
+    readonly filters?: readonly Type<ZLinkHandlerFilter>[];
+    readonly worker?: ZLinkWorkerOptions;
+    readonly coreHwm?: ZLinkCoreHwmOptions;
+    readonly applicationJobQueue?: ZLinkApplicationJobQueueOptions;
+    readonly dispatch?: ZLinkDispatchOptions;
+    readonly metrics?: ZLinkMetricsOptions;
+    readonly locations?: {
+        readonly useInMemoryStores?: boolean;
+        readonly storeInstance?: ZLinkLocationStore;
+        readonly relocationStoreInstance?: ZLinkRelocationStore;
+        readonly options?: Partial<ZLinkLocationOptionValues>;
+    };
+}
+export interface ZLinkChannelOptions {
+    readonly routingId?: string;
+    readonly routingIdPrefix?: string;
+    readonly requestTimeoutMs?: number;
+    readonly client?: ZLinkClientCapabilityOptions;
+    readonly publisher?: ZLinkPublisherCapabilityOptions;
+    readonly routeMesh?: ZLinkRouteMeshChannelOptions;
+    readonly publishHandlers?: readonly ZLinkChannelPublishHandlerRegistration[];
+    readonly requestHandlers?: readonly ZLinkChannelRequestHandlerRegistration[];
+    readonly sendHandlers?: readonly ZLinkChannelSendHandlerRegistration[];
+    readonly server?: {
+        readonly bind?: string;
+        readonly bindHost?: string;
+        readonly advertiseHost?: string;
+        readonly port?: number;
+        readonly routingId?: string;
+        readonly weight?: number;
+        readonly sendHighWaterMark?: number;
+        readonly receiveHighWaterMark?: number;
+        readonly sendTimeoutMs?: number;
+        readonly maxMessageSize?: number;
+    };
+    readonly subscriber?: ZLinkClientCapabilityOptions;
+}
+export interface ZLinkClientCapabilityOptions {
+    readonly manualConnections?: readonly string[];
+    readonly sendHighWaterMark?: number;
+    readonly receiveHighWaterMark?: number;
+    readonly sendTimeoutMs?: number;
+    readonly maxMessageSize?: number;
+}
+export interface ZLinkPublisherCapabilityOptions {
+    readonly bind?: string;
+    readonly bindHost?: string;
+    readonly advertiseHost?: string;
+    readonly port?: number;
+}
+export interface ZLinkRouteMeshChannelOptions {
+    readonly requestTimeoutMs?: number;
+    readonly bind?: string;
+    readonly manualConnections?: readonly string[];
+    readonly routingId?: string;
+    readonly routingIdPrefix?: string;
+    readonly weight?: number;
+    readonly sendHighWaterMark?: number;
+    readonly receiveHighWaterMark?: number;
+    readonly sendTimeoutMs?: number;
+    readonly sendHandlers?: readonly ZLinkRouteChannelSendHandlerRegistration[];
+    readonly requestHandlers?: readonly ZLinkRouteChannelRequestHandlerRegistration[];
+    readonly handlers?: readonly ZLinkRouteChannelHandlerOptions[];
+}
+export interface ZLinkRouteChannelOptions extends ZLinkRouteMeshChannelOptions {
+    readonly routerChannelId: string;
+}
+export interface ZLinkStreamNodeOptions {
+    readonly bind?: string;
+    readonly bindHost?: string;
+    readonly advertiseHost?: string;
+    readonly port?: number;
+    readonly actorDispatchEnabled?: boolean;
+    readonly tlsServer?: {
+        readonly certificatePath: string;
+        readonly keyPath: string;
+        readonly requireClientCertificate?: boolean;
+    };
+    readonly session?: Type;
+}
+export interface ZLinkSpotNodeRegistrationOptions extends ZLinkSpotNodeOptions {
+    readonly name: string;
+}
+export interface ZLinkSpotNodeOptions {
+    readonly objectRole?: 'client' | 'server';
+    readonly placementWeight?: number;
+    readonly actorLimit?: number;
+    readonly spotLimit?: number;
+    readonly activationConcurrencyLimit?: number;
+    readonly instanceSpotIdleTimeoutMs?: number;
+    readonly routingId?: string;
+    readonly routingIdPrefix?: string;
+    readonly router?: ZLinkSpotRouterCapabilityOptions;
+    readonly pubSub?: ZLinkSpotPubSubCapabilityOptions;
+    readonly entrySpotType?: Type<ZLinkEntrySpot>;
+    readonly spotFactories?: readonly Type<ZLinkSpot>[];
+    readonly spotFactoryRegistrations?: Readonly<Record<string, ZLinkObjectFactoryRegistration<ZLinkSpot, ZLinkSpot, ZLinkUserSpotFactoryConfiguration>>>;
+    readonly instanceSpotFactories?: Readonly<Record<string, Type<ZLinkInstanceSpot>>>;
+    readonly instanceSpotFactoryRegistrations?: Readonly<Record<string, ZLinkObjectFactoryRegistration<ZLinkInstanceSpot, ZLinkInstanceSpot, ZLinkInstanceSpotFactoryConfiguration>>>;
+    readonly actorFactories?: Readonly<Record<string, Type> | Map<string, Type>>;
+    readonly actorFactoryRegistrations?: Readonly<Record<string, ZLinkObjectFactoryRegistration<ZLinkActor, ZLinkActorFactory, ZLinkActorFactoryConfiguration>>>;
+    readonly meshChannels?: Readonly<Record<string, ZLinkMeshChannelOptions>>;
+    readonly routeSendHandlers?: readonly ZLinkRouteMeshSendHandlerRegistration[];
+    readonly routeRequestHandlers?: readonly ZLinkRouteMeshRequestHandlerRegistration[];
+    readonly requestTimeoutMs?: number;
+    readonly publisherConfig?: {
+        readonly sendHighWaterMark?: number;
+        readonly sendTimeoutMs?: number;
+        readonly lingerMs?: number;
+    };
+    readonly entrySpotTimerHandlers?: readonly ZLinkEntrySpotTimerHandlerRegistration[];
+    readonly entrySpotPacketHandlers?: readonly ZLinkEntrySpotPacketHandlerRegistration[];
+    readonly entrySpotSubscriptionHandlers?: readonly ZLinkEntrySpotSubscriptionHandlerRegistration[];
+    readonly entrySpotActorSendHandlers?: readonly ZLinkEntrySpotActorSendHandlerRegistration[];
+    readonly entrySpotActorRequestHandlers?: readonly ZLinkEntrySpotActorRequestHandlerRegistration[];
+    readonly spotTimerHandlers?: readonly ZLinkSpotTimerHandlerRegistration[];
+    readonly spotPacketHandlers?: readonly ZLinkSpotPacketHandlerRegistration[];
+    readonly spotSubscriptionHandlers?: readonly ZLinkSpotSubscriptionHandlerRegistration[];
+    readonly spotActorSendHandlers?: readonly ZLinkSpotActorSendHandlerRegistration[];
+    readonly spotActorRequestHandlers?: readonly ZLinkSpotActorRequestHandlerRegistration[];
+}
+interface ZLinkObjectFactoryRegistration<T, TImplementation = T, TOptions = unknown> {
+    readonly implementation: Type<TImplementation>;
+    readonly options?: TOptions;
+    readonly relocation: ZLinkRelocationConfiguration<T>;
+}
+declare const zlinkRelocationConfigurationBrand: unique symbol;
+export type ZLinkRelocationConfiguration<T> = ({
+    readonly kind: 'disabled';
+} | {
+    readonly kind: 'recreate';
+} | {
+    readonly kind: 'snapshot';
+    readonly adapterType: Type;
+}) & {
+    readonly [zlinkRelocationConfigurationBrand]?: T;
+};
+export interface ZLinkActorFactoryConfiguration {
+}
+export interface ZLinkUserSpotFactoryConfiguration {
+    readonly stableTypeLimit?: number;
+    readonly executionMode: ZLinkUserSpotExecutionMode;
+    readonly relocationCoordinationMode: ZLinkSpotRelocationCoordinationMode;
+}
+export interface ZLinkInstanceSpotFactoryConfiguration {
+    readonly stableTypeLimit?: number;
+}
+export interface ZLinkMeshChannelOptions {
+    readonly client?: boolean;
+    readonly server?: boolean;
+    readonly weight?: number;
+    readonly handlerGroups?: readonly string[];
+    readonly sendHandlers?: readonly ZLinkMeshSendHandlerRegistration[];
+    readonly requestHandlers?: readonly ZLinkMeshRequestHandlerRegistration[];
+}
+export interface ZLinkMeshSendHandlerRegistration {
+    readonly packetName: string;
+    readonly handlerType: Type;
+}
+export interface ZLinkMeshRequestHandlerRegistration {
+    readonly packetName: string;
+    readonly handlerType: Type;
+}
+export interface ZLinkRouteMeshSendHandlerRegistration {
+    readonly packetName: string;
+    readonly handlerType: Type;
+}
+export interface ZLinkRouteMeshRequestHandlerRegistration {
+    readonly packetName: string;
+    readonly handlerType: Type;
+}
+export interface ZLinkSpotRouterCapabilityOptions {
+    readonly bind?: string;
+    readonly bindHost?: string;
+    readonly advertiseHost?: string;
+    readonly port?: number;
+    readonly manualConnections?: readonly string[];
+    readonly manualPeerConnections?: readonly {
+        readonly peerRid: RoutingId;
+        readonly endpoint: string;
+    }[];
+    readonly routingId?: string;
+}
+export interface ZLinkSpotPubSubCapabilityOptions {
+    readonly bind?: string;
+    readonly manualConnections?: readonly string[];
+    readonly routingId?: string;
+}
+export interface ZLinkRouteChannelHandlerOptions {
+    readonly kind: 'send' | 'request';
+    readonly packetName: string;
+    readonly handler: ZLinkRouteChannelSendHandler | ZLinkRouteChannelRequestHandler;
+}
+export interface ZLinkRouteChannelSendHandlerRegistration {
+    readonly packetName: string;
+    readonly handler: ZLinkRouteChannelSendHandler;
+}
+export interface ZLinkRouteChannelRequestHandlerRegistration {
+    readonly packetName: string;
+    readonly handler: ZLinkRouteChannelRequestHandler;
+}
+export interface ZLinkChannelPublishHandlerRegistration {
+    readonly packetName: string;
+    readonly handler: {
+        handle(payload: unknown, context: ZLinkPublishMessageContext): Promise<void>;
+    };
+}
+export interface ZLinkChannelRequestHandlerRegistration {
+    readonly packetName: string;
+    readonly handler: {
+        handle(payload: unknown, context: ZLinkMessageContext): Promise<unknown>;
+    };
+}
+export interface ZLinkChannelSendHandlerRegistration {
+    readonly packetName: string;
+    readonly handler: {
+        handle(payload: unknown, context: ZLinkMessageContext): Promise<void>;
+    };
+}
+export interface ZLinkEntrySpotTimerHandlerRegistration {
+    readonly entrySpotType: Type<ZLinkEntrySpot>;
+    readonly handlerType: Type;
+    readonly name: string;
+    readonly periodMs: number;
+    readonly options?: ZLinkTimerOptions;
+}
+export interface ZLinkEntrySpotPacketHandlerRegistration {
+    readonly entrySpotType: Type<ZLinkEntrySpot>;
+    readonly handlerType: Type;
+    readonly packetName?: string;
+}
+export interface ZLinkEntrySpotSubscriptionHandlerRegistration {
+    readonly entrySpotType: Type<ZLinkEntrySpot>;
+    readonly handlerType: Type;
+    readonly channelName: string;
+    readonly topic: string;
+}
+export interface ZLinkEntrySpotActorSendHandlerRegistration {
+    readonly entrySpotType: Type<ZLinkEntrySpot>;
+    readonly actorType: Type<ZLinkActor>;
+    readonly handlerType: Type;
+    readonly packetName: string;
+}
+export interface ZLinkEntrySpotActorRequestHandlerRegistration extends ZLinkEntrySpotActorSendHandlerRegistration {
+}
+export interface ZLinkSpotTimerHandlerRegistration {
+    readonly spotType: Type<ZLinkSpot>;
+    readonly handlerType: Type;
+    readonly name: string;
+    readonly periodMs: number;
+    readonly options?: ZLinkTimerOptions;
+}
+export interface ZLinkSpotPacketHandlerRegistration {
+    readonly spotType: Type<ZLinkSpot>;
+    readonly handlerType: Type;
+    readonly packetName?: string;
+}
+export interface ZLinkSpotSubscriptionHandlerRegistration {
+    readonly spotType: Type<ZLinkSpot>;
+    readonly handlerType: Type;
+    readonly channelName: string;
+    readonly topic: string;
+}
+export interface ZLinkSpotActorSendHandlerRegistration {
+    readonly spotType: Type<ZLinkSpot>;
+    readonly actorType: Type<ZLinkActor>;
+    readonly handlerType: Type;
+    readonly packetName: string;
+}
+export interface ZLinkSpotActorRequestHandlerRegistration extends ZLinkSpotActorSendHandlerRegistration {
+}
+export {};

package/dist/framework-integration-contracts.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/framework-loader.d.ts

@@ -0,0 +1,50 @@
+import type { Type, ZLinkActorClient, ZLinkActorManager, ZLinkChannelClient, ZLinkCodecRegistrar, ZLinkCodecRegistryBuilder, ZLinkDispatchOptions, ZLinkDispatchOptionsBuilder, ZLinkInboundDispatchOptions, ZLinkLocationOptionValues, ZLinkLocationOptions, ZLinkEntrySpot, ZLinkFanoutClient, ZLinkHandlerFilterContext, ZLinkRouteClient, ZLinkSpot, ZLinkSpotManager, ZLinkSpotOutbound, ZLinkSpotPublisherClient, ZLinkStreamCompressionBuilder, ZLinkStreamCompressionCodec } from '@zlink-systems/framework';
+import type { ZLinkHttpExecutionScheduler } from '@zlink-systems/http-client';
+import type { ZLinkCodecSerializerRegistration, ZLinkFrameworkRegistration, ZLinkFrameworkRegistrationOptions, ZLinkNestIntegrationRuntimeHost, ZLinkProviderResolver, ZLinkStreamCodecRegistration } from './framework-integration-contracts';
+export type FrameworkRuntimeHost = ZLinkNestIntegrationRuntimeHost;
+interface FrameworkIntegrationModule {
+    readonly ZLinkConfigurationException: new (message: string) => Error;
+    createFrameworkRegistration(options: ZLinkFrameworkRegistrationOptions): ZLinkFrameworkRegistration;
+    hasActorManager(registration: ZLinkFrameworkRegistration): boolean;
+    hasSpotNode(registration: ZLinkFrameworkRegistration): boolean;
+    hasSpotPublisherClient(registration: ZLinkFrameworkRegistration): boolean;
+    createIntegrationDispatchOptionsBuilder(dispatch: ZLinkDispatchOptions): ZLinkDispatchOptionsBuilder;
+    createIntegrationInboundDispatchOptionsBuilder(options: Pick<ZLinkFrameworkRegistrationOptions, 'coreHwm' | 'applicationJobQueue'>): ZLinkInboundDispatchOptions;
+    createIntegrationLocationOptionsBuilder(options: Partial<ZLinkLocationOptionValues>): ZLinkLocationOptions;
+    createIntegrationStreamCompressionBuilder(options: {
+        disabled?: boolean;
+        codec?: ZLinkStreamCompressionCodec;
+    }): ZLinkStreamCompressionBuilder;
+    createIntegrationCodecRegistryBuilder(options: {
+        serializers: ZLinkCodecSerializerRegistration[];
+        streamCodecs: ZLinkStreamCodecRegistration[];
+    }): ZLinkCodecRegistryBuilder & ZLinkCodecRegistrar;
+    createIntegrationRuntimeHost(registration: ZLinkFrameworkRegistration, providerResolver?: ZLinkProviderResolver): ZLinkNestIntegrationRuntimeHost;
+    createIntegrationChannelClient(registration: ZLinkFrameworkRegistration, runtime: ZLinkNestIntegrationRuntimeHost): ZLinkChannelClient;
+    createIntegrationFanoutClient(registration: ZLinkFrameworkRegistration, runtime: ZLinkNestIntegrationRuntimeHost): ZLinkFanoutClient;
+    createIntegrationRouteClient(registration: ZLinkFrameworkRegistration, runtime: ZLinkNestIntegrationRuntimeHost): ZLinkRouteClient;
+    createIntegrationSpotPublisherClient(registration: ZLinkFrameworkRegistration, runtime: ZLinkNestIntegrationRuntimeHost): ZLinkSpotPublisherClient;
+    createIntegrationActorClient(runtime: ZLinkNestIntegrationRuntimeHost): ZLinkActorClient;
+    createIntegrationActorManager(registration: ZLinkFrameworkRegistration, runtime: ZLinkNestIntegrationRuntimeHost, providerResolver?: ZLinkProviderResolver): ZLinkActorManager;
+    createIntegrationSpotManager(registration: ZLinkFrameworkRegistration, runtime: ZLinkNestIntegrationRuntimeHost, providerResolver?: ZLinkProviderResolver): ZLinkSpotManager;
+    createIntegrationSpotOutbound(runtime: ZLinkNestIntegrationRuntimeHost): ZLinkSpotOutbound;
+    createIntegrationHttpExecutionScheduler(runtime: ZLinkNestIntegrationRuntimeHost): ZLinkHttpExecutionScheduler;
+    validateActorTransferTimeout(timeoutMs: number): number;
+    validateMessageFollowDuration(timeoutMs: number): number;
+    validateSessionReplacementCallbackTimeout(timeoutMs: number): number;
+    validateRoutingIdPrefix(prefix: string): string;
+    registerEntrySpot(options: {
+        entrySpotType?: Type<ZLinkEntrySpot>;
+    }, entrySpotType: Type<ZLinkEntrySpot>): void;
+    registerSpotFactory(options: {
+        spotFactories?: Type<ZLinkSpot>[];
+    }, spotType: Type<ZLinkSpot>): void;
+    registerActorFactory(options: {
+        actorFactories?: Record<string, Type>;
+    }, actorType: string, factoryType: Type): void;
+    registerIntegrationHandlerFilterScope(resolver: ZLinkProviderResolver, runner: (context: ZLinkHandlerFilterContext, callback: (scope: {
+        resolve<T>(type: Type<T>): Promise<T>;
+    }) => Promise<unknown>) => Promise<unknown>): void;
+}
+export declare const framework: FrameworkIntegrationModule;
+export {};

package/dist/framework-loader.js

@@ -0,0 +1,16 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.framework = void 0;
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+function loadFramework() {
+    const requireFramework = (0, node_module_1.createRequire)(__filename);
+    const frameworkEntry = requireFramework.resolve('@zlink-systems/framework');
+    return requireFramework(node_path_1.default.join(node_path_1.default.dirname(frameworkEntry), 'nest-integration'));
+}
+// The Nest package is a workspace adapter. It loads the framework's private
+// composition bridge without turning that bridge into a package subpath.
+exports.framework = loadFramework();

package/dist/handler-adapters.d.ts

@@ -0,0 +1,13 @@
+import { ModuleRef } from '@nestjs/core';
+import type { ZLinkChannelOptions } from './framework-integration-contracts';
+import type { ZLinkNestManualHandlerOptions } from './contracts';
+import type { DiscoveredNestProvider } from './provider-discovery';
+export declare function createDiscoveredRequestHandlers(providerRefs: readonly DiscoveredNestProvider[], handlerGroups: readonly string[] | undefined, moduleRef: ModuleRef): NonNullable<ZLinkChannelOptions['requestHandlers']>;
+export declare function createDiscoveredSendHandlers(providerRefs: readonly DiscoveredNestProvider[], handlerGroups: readonly string[] | undefined, moduleRef: ModuleRef): NonNullable<NonNullable<ZLinkChannelOptions['routeMesh']>['sendHandlers']>;
+export declare function createDiscoveredChannelSendHandlers(providerRefs: readonly DiscoveredNestProvider[], handlerGroups: readonly string[] | undefined, moduleRef: ModuleRef): NonNullable<ZLinkChannelOptions['sendHandlers']>;
+export declare function createDiscoveredPublishHandlers(providerRefs: readonly DiscoveredNestProvider[], handlerGroups: readonly string[] | undefined, moduleRef: ModuleRef): NonNullable<ZLinkChannelOptions['publishHandlers']>;
+export declare function createManualRequestHandlers(handlerTypes: readonly ZLinkNestManualHandlerOptions[] | undefined, moduleRef: ModuleRef): NonNullable<ZLinkChannelOptions['requestHandlers']>;
+export declare function createManualPublishHandlers(handlerTypes: readonly ZLinkNestManualHandlerOptions[] | undefined, moduleRef: ModuleRef): NonNullable<ZLinkChannelOptions['publishHandlers']>;
+export declare function createManualSendHandlers(handlerTypes: readonly ZLinkNestManualHandlerOptions[] | undefined, moduleRef: ModuleRef): NonNullable<ZLinkChannelOptions['sendHandlers']>;
+export declare function createManualRouteSendHandlers(handlerTypes: readonly ZLinkNestManualHandlerOptions[] | undefined, moduleRef: ModuleRef): NonNullable<NonNullable<ZLinkChannelOptions['routeMesh']>['sendHandlers']>;
+export declare function createManualRouteRequestHandlers(handlerTypes: readonly ZLinkNestManualHandlerOptions[] | undefined, moduleRef: ModuleRef): NonNullable<NonNullable<ZLinkChannelOptions['routeMesh']>['requestHandlers']>;

package/dist/handler-adapters.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDiscoveredRequestHandlers = createDiscoveredRequestHandlers;
+exports.createDiscoveredSendHandlers = createDiscoveredSendHandlers;
+exports.createDiscoveredChannelSendHandlers = createDiscoveredChannelSendHandlers;
+exports.createDiscoveredPublishHandlers = createDiscoveredPublishHandlers;
+exports.createManualRequestHandlers = createManualRequestHandlers;
+exports.createManualPublishHandlers = createManualPublishHandlers;
+exports.createManualSendHandlers = createManualSendHandlers;
+exports.createManualRouteSendHandlers = createManualRouteSendHandlers;
+exports.createManualRouteRequestHandlers = createManualRouteRequestHandlers;
+const core_1 = require("@nestjs/core");
+const framework_loader_1 = require("./framework-loader");
+const dispatch_scope_1 = require("./dispatch-scope");
+const providers_1 = require("./providers");
+function createDiscoveredRequestHandlers(providerRefs, handlerGroups, moduleRef) {
+    return createDiscoveredHandlerRegistrations(providerRefs, handlerGroups, 'request', (ref, metadata) => ({
+        async handle(payload, context) {
+            const result = await invokeDiscoveredHandler(moduleRef, ref, metadata, payload, context);
+            return metadata.encodeResult === undefined ? result : metadata.encodeResult(result, context);
+        }
+    }));
+}
+function createDiscoveredSendHandlers(providerRefs, handlerGroups, moduleRef) {
+    return createDiscoveredHandlerRegistrations(providerRefs, handlerGroups, 'send', (ref, metadata) => ({
+        async handle(payload, context) {
+            await invokeDiscoveredHandler(moduleRef, ref, metadata, payload, context);
+        }
+    }));
+}
+function createDiscoveredChannelSendHandlers(providerRefs, handlerGroups, moduleRef) {
+    return createDiscoveredHandlerRegistrations(providerRefs, handlerGroups, 'send', (ref, metadata) => ({
+        async handle(payload, context) {
+            await invokeDiscoveredHandler(moduleRef, ref, metadata, payload, context);
+        }
+    }));
+}
+function createDiscoveredPublishHandlers(providerRefs, handlerGroups, moduleRef) {
+    return createDiscoveredHandlerRegistrations(providerRefs, handlerGroups, 'publish', (ref, metadata) => ({
+        async handle(payload, context) {
+            await invokeDiscoveredHandler(moduleRef, ref, metadata, payload, context);
+        }
+    }));
+}
+function createManualRequestHandlers(handlerTypes, moduleRef) {
+    return createManualHandlerRegistrations(handlerTypes, moduleRef, (result) => result);
+}
+function createManualPublishHandlers(handlerTypes, moduleRef) {
+    return createManualHandlerRegistrations(handlerTypes, moduleRef, () => undefined);
+}
+function createManualSendHandlers(handlerTypes, moduleRef) {
+    return createManualHandlerRegistrations(handlerTypes, moduleRef, () => undefined);
+}
+function createManualRouteSendHandlers(handlerTypes, moduleRef) {
+    return createManualHandlerRegistrations(handlerTypes, moduleRef, () => undefined);
+}
+function createManualRouteRequestHandlers(handlerTypes, moduleRef) {
+    return createManualHandlerRegistrations(handlerTypes, moduleRef, (result) => result);
+}
+function createManualHandlerRegistrations(handlerTypes, moduleRef, result) {
+    return (handlerTypes ?? []).map((registration) => ({
+        packetName: registration.packetName,
+        handler: {
+            async handle(payload, context) {
+                return result(await invokeManualHandler(moduleRef, registration.handlerType, payload, context));
+            }
+        }
+    }));
+}
+function createDiscoveredHandlerRegistrations(providerRefs, handlerGroups, kind, createHandler) {
+    const descriptors = createDiscoveredHandlerDescriptors(providerRefs, handlerGroups, kind);
+    return descriptors.map(({ ref, metadata }) => ({
+        packetName: metadata.packetName,
+        handler: createHandler(ref, metadata)
+    }));
+}
+function createDiscoveredHandlerDescriptors(providerRefs, handlerGroups, kind) {
+    if ((handlerGroups ?? []).length === 0) {
+        return [];
+    }
+    const groups = new Set(handlerGroups);
+    const seen = new Map();
+    const selected = [];
+    for (const ref of providerRefs) {
+        const metadata = ref.metadata;
+        if (metadata.kind !== kind || !groups.has(metadata.groupName)) {
+            continue;
+        }
+        const key = `${metadata.kind}:${metadata.packetName}`;
+        const previousType = seen.get(key);
+        if (previousType === ref.handlerKey) {
+            continue;
+        }
+        if (previousType !== undefined) {
+            throw new framework_loader_1.framework.ZLinkConfigurationException(`Duplicate handler '${metadata.groupName}:${metadata.kind}:${metadata.packetName}'.`);
+        }
+        seen.set(key, ref.handlerKey);
+        selected.push({ ref, metadata });
+    }
+    return selected;
+}
+async function invokeDiscoveredHandler(moduleRef, ref, metadata, payload, context) {
+    const instance = await resolveHandlerInstance(moduleRef, ref.handlerKey, context);
+    try {
+        const method = instance[metadata.methodName];
+        if (typeof method !== 'function') {
+            throw new framework_loader_1.framework.ZLinkConfigurationException(`Discovered handler ${ref.handlerName}.${metadata.methodName} is not callable.`);
+        }
+        return await method.call(instance, decodePayload(metadata, payload, context), context);
+    }
+    finally {
+        await (0, providers_1.disposeNestOwnedHandler)(instance);
+    }
+}
+async function invokeManualHandler(moduleRef, handlerType, payload, context) {
+    const instance = await resolveHandlerInstance(moduleRef, handlerType, context);
+    try {
+        const method = instance.handle;
+        if (typeof method !== 'function') {
+            throw new framework_loader_1.framework.ZLinkConfigurationException(`Manual handler ${handlerType.name}.handle is not callable.`);
+        }
+        return await method.call(instance, decodePayload(undefined, payload, context), context);
+    }
+    finally {
+        await (0, providers_1.disposeNestOwnedHandler)(instance);
+    }
+}
+async function resolveHandlerInstance(moduleRef, handlerType, context) {
+    const currentContextId = (0, dispatch_scope_1.currentNestDispatchContext)();
+    const contextId = currentContextId ?? core_1.ContextIdFactory.create();
+    if (currentContextId === undefined) {
+        moduleRef.registerRequestByContextId({ zlinkContext: context }, contextId);
+    }
+    return await (0, providers_1.createNestHandlerInstance)(moduleRef, contextId, new Map(), handlerType);
+}
+function decodePayload(metadata, payload, context) {
+    if (Buffer.isBuffer(payload) || payload instanceof Uint8Array) {
+        if (metadata?.decodePayload !== undefined) {
+            return metadata.decodePayload(Buffer.from(payload), context);
+        }
+        if (context.contentType !== undefined && context.contentType !== 'application/json') {
+            return Buffer.from(payload);
+        }
+        return parseWireJson(Buffer.from(payload).toString());
+    }
+    return typeof payload === 'string' ? parseWireJson(payload) : payload;
+}
+function parseWireJson(payload) {
+    return JSON.parse(payload, (key, value) => {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+            throw new framework_loader_1.framework.ZLinkConfigurationException(`NestJS handler JSON key '${key}' is not allowed.`);
+        }
+        return value;
+    });
+}

package/dist/handler-metadata.d.ts

@@ -0,0 +1,55 @@
+import type { InjectionToken } from '@nestjs/common';
+import type { Type, ZLinkActor, ZLinkEntrySpot, ZLinkInstanceSpot, ZLinkMessageContext, ZLinkPublishMessageContext, ZLinkRouteMessageContext, ZLinkSpot, ZLinkTimerOptions } from '@zlink-systems/framework';
+export type ZLinkNestHandlerKind = 'request' | 'send' | 'publish';
+type ZLinkNestTypeResolver<T> = Type<T> | (() => Type<T>);
+export interface ZLinkNestHandlerMetadata {
+    readonly groupName: string;
+    readonly kind: ZLinkNestHandlerKind;
+    readonly packetName: string;
+    readonly methodName: string;
+    readonly decodePayload?: (payload: Buffer, context: ZLinkMessageContext | ZLinkRouteMessageContext | ZLinkPublishMessageContext) => unknown;
+    readonly encodeResult?: (result: unknown, context: ZLinkMessageContext | ZLinkRouteMessageContext) => unknown;
+}
+export type ZLinkNestSpotActorHandlerKind = 'spotActorSend' | 'spotActorRequest' | 'entrySpotActorSend' | 'entrySpotActorRequest';
+export interface ZLinkNestSpotActorHandlerMetadata {
+    readonly kind: ZLinkNestSpotActorHandlerKind;
+    readonly packetName: string;
+    readonly methodName: string;
+    readonly handlerType: Type;
+    readonly actor: ZLinkNestTypeResolver<ZLinkActor>;
+    readonly spot?: ZLinkNestTypeResolver<ZLinkSpot>;
+    readonly entrySpot?: ZLinkNestTypeResolver<ZLinkEntrySpot>;
+}
+export type ZLinkNestSpotHandlerKind = 'spotPacket' | 'spotSubscription' | 'entrySpotPacket' | 'entrySpotSubscription';
+export interface ZLinkNestSpotHandlerMetadata {
+    readonly kind: ZLinkNestSpotHandlerKind;
+    readonly handlerType: Type;
+    readonly packetName?: string;
+    readonly channelName?: string;
+    readonly topic?: string;
+    readonly spot?: ZLinkNestTypeResolver<ZLinkSpot | ZLinkInstanceSpot>;
+    readonly entrySpot?: ZLinkNestTypeResolver<ZLinkEntrySpot>;
+}
+export interface ZLinkNestSpotTimerHandlerMetadata {
+    readonly handlerType: Type;
+    readonly name: string;
+    readonly periodMs: number;
+    readonly options?: ZLinkTimerOptions;
+    readonly spot?: ZLinkNestTypeResolver<ZLinkSpot>;
+    readonly entrySpot?: ZLinkNestTypeResolver<ZLinkEntrySpot>;
+}
+export declare function appendNestHandlerMetadata(handlerToken: InjectionToken, metadata: ZLinkNestHandlerMetadata): void;
+export declare function readNestHandlerMetadata(handlerToken: InjectionToken | undefined): readonly ZLinkNestHandlerMetadata[];
+export declare function appendNestSpotActorHandlerMetadata(handlerToken: InjectionToken, metadata: ZLinkNestSpotActorHandlerMetadata): void;
+export declare function readNestSpotActorHandlerMetadata(handlerToken: InjectionToken | undefined): readonly ZLinkNestSpotActorHandlerMetadata[];
+export declare function appendNestSpotHandlerMetadata(handlerToken: InjectionToken, metadata: ZLinkNestSpotHandlerMetadata): void;
+export declare function readNestSpotHandlerMetadata(handlerToken: InjectionToken | undefined): readonly ZLinkNestSpotHandlerMetadata[];
+export declare function markNestSpotTimerHandler(handlerToken: InjectionToken): void;
+export declare function appendNestSpotTimerHandlerMetadata(handlerToken: InjectionToken, metadata: ZLinkNestSpotTimerHandlerMetadata): void;
+export declare function readNestSpotTimerHandlerMetadata(handlerToken: InjectionToken | undefined): readonly ZLinkNestSpotTimerHandlerMetadata[];
+export declare function hasNestSpotTimerHandlerMetadata(handlerToken: InjectionToken | undefined): boolean;
+export declare function nestHandlerMetadataEntries(): [InjectionToken, readonly ZLinkNestHandlerMetadata[]][];
+export declare function nestSpotActorHandlerMetadataEntries(): [InjectionToken, readonly ZLinkNestSpotActorHandlerMetadata[]][];
+export declare function nestSpotHandlerMetadataEntries(): [InjectionToken, readonly ZLinkNestSpotHandlerMetadata[]][];
+export declare function nestSpotTimerHandlerMetadataEntries(): [InjectionToken, readonly ZLinkNestSpotTimerHandlerMetadata[]][];
+export {};