@zlink-systems/framework 0.10.0

package/dist/contracts/Configuration/RegistrationCodecRegistry.d.ts

@@ -0,0 +1,19 @@
+import type { ZLinkCodecExtension, ZLinkCodecRegistrar, ZLinkCodecRegistryBuilder, ZLinkMessageTypeSelector, ZLinkMessageSerializer } from '../Codecs';
+import type { ZLinkCodecRegistration, ZLinkCodecRegistryOptions, ZLinkCodecSerializerRegistration, ZLinkStreamCodecRegistration } from './RegistrationTypes';
+export interface MutableCodecRegistryOptions {
+    serializers: ZLinkCodecSerializerRegistration[];
+    streamCodecs: ZLinkStreamCodecRegistration[];
+}
+export declare function createCodecRegistry(options: ZLinkCodecRegistryOptions | undefined): RegistrationCodecRegistryBuilder;
+export declare class RegistrationCodecRegistryBuilder implements ZLinkCodecRegistryBuilder, ZLinkCodecRegistrar {
+    private readonly options;
+    constructor(options?: MutableCodecRegistryOptions);
+    get registeredSerializers(): ReadonlyMap<string, ZLinkMessageSerializer>;
+    get registeredStreamCodecs(): ReadonlyMap<string, unknown>;
+    get registration(): ZLinkCodecRegistration;
+    get registeredCodecs(): readonly string[];
+    use(extension: ZLinkCodecExtension): this;
+    addSerializer(contentType: string, serializer: ZLinkMessageSerializer): this;
+    addSerializer(contentType: string, serializer: ZLinkMessageSerializer, canSerialize: ZLinkMessageTypeSelector): this;
+    addStreamCodec(contentType: string, codec: unknown): this;
+}

package/dist/contracts/Configuration/RegistrationCodecRegistry.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegistrationCodecRegistryBuilder = void 0;
+exports.createCodecRegistry = createCodecRegistry;
+const CodecContentType_1 = require("./CodecContentType");
+const CodecSerializerSelection_1 = require("./CodecSerializerSelection");
+function createCodecRegistry(options) {
+    return new RegistrationCodecRegistryBuilder({
+        serializers: [...(options?.serializers ?? [])],
+        streamCodecs: [...(options?.streamCodecs ?? [])]
+    });
+}
+class RegistrationCodecRegistryBuilder {
+    options;
+    constructor(options = { serializers: [], streamCodecs: [] }) {
+        this.options = options;
+        const serializers = [...options.serializers];
+        const streamCodecs = [...options.streamCodecs];
+        options.serializers.length = 0;
+        options.streamCodecs.length = 0;
+        for (const entry of serializers) {
+            if (entry.canSerialize === undefined) {
+                this.addSerializer(entry.contentType, entry.serializer);
+            }
+            else {
+                this.addSerializer(entry.contentType, entry.serializer, entry.canSerialize);
+            }
+        }
+        for (const entry of streamCodecs) {
+            this.addStreamCodec(entry.contentType, entry.codec);
+        }
+    }
+    get registeredSerializers() {
+        const serializers = new Map(this.options.serializers.map((entry) => [entry.contentType, entry.serializer]));
+        const selections = new Map(this.options.serializers.map((entry) => [
+            entry.contentType,
+            {
+                selector: entry.canSerialize ?? CodecSerializerSelection_1.matchEveryDeclaredMessageType,
+                fallback: entry.canSerialize === undefined
+            }
+        ]));
+        return (0, CodecSerializerSelection_1.rememberCodecSerializerSelections)(serializers, selections);
+    }
+    get registeredStreamCodecs() {
+        return new Map(this.options.streamCodecs.map((entry) => [entry.contentType, entry.codec]));
+    }
+    get registration() {
+        return {
+            serializers: this.registeredSerializers,
+            streamCodecs: this.registeredStreamCodecs
+        };
+    }
+    get registeredCodecs() {
+        return this.options.serializers.map((entry) => entry.contentType);
+    }
+    use(extension) {
+        extension.register(this);
+        return this;
+    }
+    addSerializer(contentType, serializer, canSerialize) {
+        const normalized = (0, CodecContentType_1.normalizeCodecContentType)(contentType);
+        const existing = this.options.serializers.findIndex((entry) => entry.contentType === normalized);
+        const registration = { contentType: normalized, serializer, canSerialize };
+        if (existing >= 0)
+            this.options.serializers.splice(existing, 1);
+        this.options.serializers.push(registration);
+        return this;
+    }
+    addStreamCodec(contentType, codec) {
+        const normalized = (0, CodecContentType_1.normalizeCodecContentType)(contentType);
+        const existing = this.options.streamCodecs.findIndex((entry) => entry.contentType === normalized);
+        const registration = { contentType: normalized, codec };
+        if (existing >= 0)
+            this.options.streamCodecs.splice(existing, 1);
+        this.options.streamCodecs.push(registration);
+        return this;
+    }
+}
+exports.RegistrationCodecRegistryBuilder = RegistrationCodecRegistryBuilder;

package/dist/contracts/Configuration/RegistrationNormalizers.d.ts

@@ -0,0 +1,23 @@
+import type { Type, ZLinkSpot, ZLinkStreamCompressionOptions, ZLinkStreamCompressionCodec } from '../../contracts';
+import type { ZLinkChannelOptions, ZLinkFrameworkRegistration, ZLinkFrameworkRegistrationOptions, ZLinkLocationRegistration, ZLinkRouteChannelOptions, ZLinkSpotNodeOptions, ZLinkStreamNodeOptions, ZLinkWorkerOptions } from './RegistrationTypes';
+import type { ZLinkNetworkOptions } from './Builders';
+export declare function normalizeWorkerOptions(value: ZLinkFrameworkRegistrationOptions['worker']): ZLinkWorkerOptions | undefined;
+export declare function normalizeNetworkOptions(value: ZLinkFrameworkRegistrationOptions['network']): ZLinkNetworkOptions;
+export declare function toChannelMap(channels: ZLinkFrameworkRegistrationOptions['channels'], network: ZLinkNetworkOptions): Map<string, ZLinkChannelOptions>;
+export declare function toStreamNodeMap(streamNodes: ZLinkFrameworkRegistrationOptions['streamNodes'], network: ZLinkNetworkOptions): Map<string, ZLinkStreamNodeOptions>;
+export declare function toRouteChannelOptions(options: ZLinkFrameworkRegistrationOptions): Map<string, ZLinkRouteChannelOptions>;
+export declare function requirePositiveInteger(label: string, value: number | undefined): void;
+export declare function normalizeOptionalPositiveInteger(value: number | undefined, label: string): number | undefined;
+export declare function hasSpotNode(registration: ZLinkFrameworkRegistration): boolean;
+export declare function hasActorManager(registration: ZLinkFrameworkRegistration): boolean;
+export declare function hasSpotPublisherClient(registration: ZLinkFrameworkRegistration): boolean;
+export declare function toTypeMap(value: ZLinkSpotNodeOptions['actorFactories']): Map<string, Type>;
+export declare function typeMapToRecord(value: ZLinkSpotNodeOptions['actorFactories']): Record<string, Type>;
+export declare function actorFactoriesFromSpotNodes(spotNodes: ReadonlyMap<string, ZLinkSpotNodeOptions>): Map<string, Type>;
+export declare function toSpotNodeMap(value: ZLinkFrameworkRegistrationOptions['spotNodes'], network: ZLinkNetworkOptions): Map<string, ZLinkSpotNodeOptions>;
+export declare function toSpotFactorySet(rootFactories: readonly Type<ZLinkSpot>[] | undefined, spotNodes: ReadonlyMap<string, ZLinkSpotNodeOptions>): Set<Type<ZLinkSpot>>;
+export declare function toSpotPublisherClientSet(explicitClients: readonly string[] | undefined, spotNodes: ReadonlyMap<string, ZLinkSpotNodeOptions>): Set<string>;
+export declare function channelNamesWith(channels: ZLinkFrameworkRegistrationOptions['channels'], predicate: (channel: ZLinkChannelOptions) => boolean): Set<string>;
+export declare function normalizeStreamCompression(value: ZLinkFrameworkRegistrationOptions['streamCompression']): ZLinkStreamCompressionOptions | undefined;
+export declare function isStreamCompressionCodec(value: unknown): value is ZLinkStreamCompressionCodec;
+export declare function normalizeLocationRegistration(value: ZLinkFrameworkRegistrationOptions['locations']): ZLinkLocationRegistration;

package/dist/contracts/Configuration/RegistrationNormalizers.js

@@ -0,0 +1,319 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeWorkerOptions = normalizeWorkerOptions;
+exports.normalizeNetworkOptions = normalizeNetworkOptions;
+exports.toChannelMap = toChannelMap;
+exports.toStreamNodeMap = toStreamNodeMap;
+exports.toRouteChannelOptions = toRouteChannelOptions;
+exports.requirePositiveInteger = requirePositiveInteger;
+exports.normalizeOptionalPositiveInteger = normalizeOptionalPositiveInteger;
+exports.hasSpotNode = hasSpotNode;
+exports.hasActorManager = hasActorManager;
+exports.hasSpotPublisherClient = hasSpotPublisherClient;
+exports.toTypeMap = toTypeMap;
+exports.typeMapToRecord = typeMapToRecord;
+exports.actorFactoriesFromSpotNodes = actorFactoriesFromSpotNodes;
+exports.toSpotNodeMap = toSpotNodeMap;
+exports.toSpotFactorySet = toSpotFactorySet;
+exports.toSpotPublisherClientSet = toSpotPublisherClientSet;
+exports.channelNamesWith = channelNamesWith;
+exports.normalizeStreamCompression = normalizeStreamCompression;
+exports.isStreamCompressionCodec = isStreamCompressionCodec;
+exports.normalizeLocationRegistration = normalizeLocationRegistration;
+const ConfigurationException_1 = require("./ConfigurationException");
+const RouteChannelInternalState_1 = require("./RouteChannelInternalState");
+const EndpointNotation_1 = require("./EndpointNotation");
+const InternalDefaults_1 = require("./InternalDefaults");
+function normalizeWorkerOptions(value) {
+    if (value === undefined)
+        return undefined;
+    const partial = value;
+    return {
+        minThreads: partial.minThreads ?? InternalDefaults_1.DEFAULT_WORKER_MIN_THREADS,
+        maxThreads: partial.maxThreads ?? (0, InternalDefaults_1.defaultWorkerMaxThreads)(),
+        idleTimeoutMs: partial.idleTimeoutMs ?? InternalDefaults_1.DEFAULT_WORKER_IDLE_TIMEOUT_MS,
+        maxQueueLength: partial.maxQueueLength ?? InternalDefaults_1.DEFAULT_WORKER_QUEUE_LENGTH
+    };
+}
+function normalizeNetworkOptions(value) {
+    return {
+        bindHost: value?.bindHost ?? '127.0.0.1',
+        ...(value?.advertiseHost === undefined ? {} : { advertiseHost: value.advertiseHost })
+    };
+}
+function toChannelMap(channels, network) {
+    return new Map(Object.entries(channels ?? {}).map(([name, channel]) => {
+        const server = channel.server === undefined
+            ? undefined
+            : normalizeListener(channel.server, network);
+        const publisher = channel.publisher === undefined
+            ? undefined
+            : normalizeListener(channel.publisher, network);
+        // In-place: channel.client/subscriber.manualConnections can be the same
+        // array a live RuntimeEndpointConnections handle mutates, so this must
+        // not replace the array or the containing client/subscriber object.
+        normalizeEndpointList(channel.client?.manualConnections);
+        normalizeEndpointList(channel.subscriber?.manualConnections);
+        return [name, {
+                ...channel,
+                ...(server === undefined ? {} : { server }),
+                ...(publisher === undefined ? {} : { publisher }),
+                requestTimeoutMs: normalizeOptionalPositiveInteger(channel.requestTimeoutMs, `${name}.requestTimeoutMs`)
+            }];
+    }));
+}
+function toStreamNodeMap(streamNodes, network) {
+    return new Map(Object.entries(streamNodes ?? {}).map(([name, streamNode]) => {
+        const normalized = normalizeListener(streamNode, network);
+        return [name, {
+                ...normalized,
+                maxMessageSize: streamNode.maxMessageSize ?? InternalDefaults_1.DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE
+            }];
+    }));
+}
+function toRouteChannelOptions(options) {
+    const routeOptions = new Map();
+    for (const routeChannel of options.routeChannels ?? []) {
+        if (typeof routeChannel === 'string') {
+            routeOptions.set(routeChannel, { routerChannelId: routeChannel });
+            continue;
+        }
+        const normalized = {
+            ...routeChannel,
+            manualConnections: normalizeEndpointList(routeChannel.manualConnections),
+            requestTimeoutMs: normalizeOptionalPositiveInteger(routeChannel.requestTimeoutMs, `${routeChannel.routerChannelId}.requestTimeoutMs`)
+        };
+        (0, RouteChannelInternalState_1.copyRouteInternalState)(routeChannel, normalized);
+        routeOptions.set(routeChannel.routerChannelId, normalized);
+    }
+    for (const [channelName, channel] of Object.entries(options.channels ?? {})) {
+        if (channel.routeMesh === undefined) {
+            continue;
+        }
+        if (routeOptions.has(channelName)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Route mesh channel '${channelName}' is already registered.`);
+        }
+        const routeChannel = {
+            routerChannelId: channelName,
+            ...channel.routeMesh,
+            manualConnections: normalizeEndpointList(channel.routeMesh.manualConnections),
+            requestTimeoutMs: normalizeOptionalPositiveInteger(channel.routeMesh.requestTimeoutMs, `${channelName}.routeMesh.requestTimeoutMs`)
+        };
+        (0, RouteChannelInternalState_1.markRouteTransportDeclared)(routeChannel);
+        (0, RouteChannelInternalState_1.copyRouteInternalState)(channel.routeMesh, routeChannel);
+        routeOptions.set(channelName, routeChannel);
+    }
+    return routeOptions;
+}
+function requirePositiveInteger(label, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must be a positive integer.`);
+    }
+}
+function normalizeOptionalPositiveInteger(value, label) {
+    requirePositiveInteger(label, value);
+    return value;
+}
+function hasSpotNode(registration) {
+    return registration.spotNodes.size > 0;
+}
+function hasActorManager(registration) {
+    const hasObjectCapability = [...registration.spotNodes.values()].some(node => node.objectRole === 'client'
+        || node.objectRole === 'server'
+        || (node.actorFactories instanceof Map
+            ? node.actorFactories.size > 0
+            : Object.keys(node.actorFactories ?? {}).length > 0)
+        || Object.keys(node.actorFactoryRegistrations ?? {}).length > 0);
+    return hasObjectCapability && (registration.locations.useInMemoryStores
+        || registration.locations.storeInstance !== undefined);
+}
+function hasSpotPublisherClient(registration) {
+    return registration.spotPublisherClients.size > 0;
+}
+function toTypeMap(value) {
+    if (value === undefined) {
+        return new Map();
+    }
+    if (value instanceof Map) {
+        return new Map(value);
+    }
+    return new Map(Object.entries(value));
+}
+function typeMapToRecord(value) {
+    if (value === undefined) {
+        return {};
+    }
+    if (isTypeMap(value)) {
+        return Object.fromEntries(value);
+    }
+    return { ...value };
+}
+function isTypeMap(value) {
+    return value instanceof Map;
+}
+function actorFactoriesFromSpotNodes(spotNodes) {
+    const actorCapableNodes = [...spotNodes.values()].filter((spotNode) => toTypeMap(spotNode.actorFactories).size > 0);
+    if (actorCapableNodes.length === 0) {
+        return new Map();
+    }
+    return toTypeMap(actorCapableNodes[0].actorFactories);
+}
+function toSpotNodeMap(value, network) {
+    if (value === undefined) {
+        return new Map();
+    }
+    if (!Array.isArray(value)) {
+        return new Map(Object.entries(value).map(([name, spotNode]) => [
+            name,
+            normalizeSpotNodeOptions(spotNode, network)
+        ]));
+    }
+    return new Map(value.map((spotNode) => {
+        if (typeof spotNode === 'string') {
+            return [spotNode, normalizeSpotNodeOptions({}, network)];
+        }
+        const { name, ...options } = spotNode;
+        return [name, normalizeSpotNodeOptions(options, network)];
+    }));
+}
+function normalizeSpotNodeOptions(spotNode, network) {
+    const router = spotNode.router === undefined
+        ? undefined
+        : normalizeListener(spotNode.router, network);
+    return {
+        ...spotNode,
+        router: router === undefined
+            ? undefined
+            : {
+                ...router,
+                routingId: router.routingId ?? spotNode.routingId,
+                manualConnections: normalizeEndpointList(router.manualConnections),
+                manualPeerConnections: normalizeManualPeerConnections(router.manualPeerConnections)
+            },
+        pubSub: spotNode.pubSub === undefined
+            ? undefined
+            : {
+                ...spotNode.pubSub,
+                routingId: spotNode.pubSub.routingId ?? spotNode.routingId,
+                manualConnections: normalizeEndpointList(spotNode.pubSub.manualConnections)
+            }
+    };
+}
+function normalizeListener(listener, network) {
+    const usesConfiguredEndpoint = listener.bind !== undefined && listener.port === undefined;
+    const port = listener.port ?? (usesConfiguredEndpoint ? endpointPort(listener.bind) : 0);
+    const bindHost = listener.bindHost
+        ?? (usesConfiguredEndpoint ? endpointHost(listener.bind) : network.bindHost);
+    const bind = usesConfiguredEndpoint
+        ? (0, EndpointNotation_1.normalizeEndpoint)(listener.bind)
+        : tcpEndpoint(bindHost ?? network.bindHost, port);
+    return {
+        ...listener,
+        bind,
+        bindHost,
+        port,
+        ...(listener.advertiseHost !== undefined
+            ? { advertiseHost: listener.advertiseHost }
+            : network.advertiseHost === undefined
+                ? {}
+                : { advertiseHost: network.advertiseHost })
+    };
+}
+/**
+ * Normalizes a declaratively-configured list of manual-connection endpoints
+ * (e.g. `channel.client.manualConnections`, `routeChannel.manualConnections`,
+ * `spotNode.router.manualConnections`) at the point the application hands
+ * them to the framework, so every later comparison/dedup can use plain
+ * string equality.
+ *
+ * Normalizes in place and preserves array identity when possible: this
+ * array can be the very array `RuntimeEndpointConnections`/builder handles
+ * mutate at runtime (see its constructor comment), so returning a copy
+ * would silently detach live `connect()`/`disconnect()` calls from the
+ * registered configuration. Only builds a new array when the input isn't a
+ * plain extensible array (frozen/sealed/external readonly).
+ */
+function normalizeEndpointList(endpoints) {
+    if (endpoints === undefined)
+        return endpoints;
+    if (Array.isArray(endpoints) && Object.isExtensible(endpoints)) {
+        const mutable = endpoints;
+        for (let index = 0; index < mutable.length; index += 1) {
+            mutable[index] = (0, EndpointNotation_1.normalizeEndpoint)(mutable[index]);
+        }
+        return endpoints;
+    }
+    return endpoints.map(EndpointNotation_1.normalizeEndpoint);
+}
+function normalizeManualPeerConnections(peers) {
+    if (peers === undefined)
+        return undefined;
+    return peers.map((peer) => ({ ...peer, endpoint: (0, EndpointNotation_1.normalizeEndpoint)(peer.endpoint) }));
+}
+function tcpEndpoint(host, port) {
+    const endpointHost = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+    return (0, EndpointNotation_1.normalizeEndpoint)(`tcp://${endpointHost}:${port}`);
+}
+function endpointHost(endpoint) {
+    return (0, EndpointNotation_1.parseEndpointHostPort)(endpoint, 'tcp')?.host;
+}
+function endpointPort(endpoint) {
+    return (0, EndpointNotation_1.parseEndpointHostPort)(endpoint, 'tcp')?.port ?? 0;
+}
+function toSpotFactorySet(rootFactories, spotNodes) {
+    const factories = new Set(rootFactories ?? []);
+    for (const spotNode of spotNodes.values()) {
+        for (const spotFactory of spotNode.spotFactories ?? []) {
+            factories.add(spotFactory);
+        }
+    }
+    return factories;
+}
+function toSpotPublisherClientSet(explicitClients, spotNodes) {
+    const clients = new Set(explicitClients ?? []);
+    for (const spotNodeName of spotNodes.keys()) {
+        clients.add(spotNodeName);
+    }
+    return clients;
+}
+function channelNamesWith(channels, predicate) {
+    const names = new Set();
+    for (const [name, channel] of Object.entries(channels ?? {})) {
+        if (predicate(channel)) {
+            names.add(name);
+        }
+    }
+    return names;
+}
+function normalizeStreamCompression(value) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value.disabled === true && value.codec !== undefined) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('STREAM compression codec cannot be set when compression is disabled.');
+    }
+    if (value.codec !== undefined && !isStreamCompressionCodec(value.codec)) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('STREAM compression codec must provide compress and decompress functions.');
+    }
+    return {
+        disabled: value.disabled,
+        codec: value.codec
+    };
+}
+function isStreamCompressionCodec(value) {
+    return typeof value === 'object'
+        && value !== null
+        && typeof value.compress === 'function'
+        && typeof value.decompress === 'function';
+}
+function normalizeLocationRegistration(value) {
+    return {
+        useInMemoryStores: value?.useInMemoryStores === true,
+        storeInstance: value?.storeInstance,
+        relocationStoreInstance: value?.relocationStoreInstance,
+        options: value?.options === undefined ? {} : { ...value.options }
+    };
+}