@zlink-systems/framework 0.10.0

package/dist/contracts/Configuration/RegistrationValidators.js

@@ -0,0 +1,461 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateFrameworkRegistration = validateFrameworkRegistration;
+const ConfigurationException_1 = require("./ConfigurationException");
+const RegistrationNormalizers_1 = require("./RegistrationNormalizers");
+const RouteChannelInternalState_1 = require("./RouteChannelInternalState");
+const TimerRegistrationValidator_1 = require("./TimerRegistrationValidator");
+const Locations_1 = require("../Locations");
+const SendTimeoutValidation_1 = require("./SendTimeoutValidation");
+function validateFrameworkRegistration(registration, _options = {}) {
+    validateListenerNetworkIdentity('process network', undefined, registration.network.bindHost, registration.network.advertiseHost);
+    const actorCapableSpotNodes = [...registration.spotNodes.values()]
+        .filter((spotNode) => toActorFactoryCount(spotNode.actorFactories) > 0);
+    if (actorCapableSpotNodes.length > 1) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('Actor factory registration is ambiguous because more than one SpotNode owns actor factories.');
+    }
+    const peerLocationConfigured = hasLocationStores(registration);
+    validateChannelCapabilities(Object.fromEntries(registration.channels), peerLocationConfigured);
+    validateChannelTopologyNames(registration);
+    validateSpotNodes(registration);
+    validateRouteChannels(registration, peerLocationConfigured);
+    validateStreamNodes(registration);
+    validateWorkerOptions(registration.worker);
+    validateLocationRegistration(registration);
+}
+function validateChannelTopologyNames(registration) {
+    const declaredChannelNames = new Set([...registration.channels]
+        .filter(([, channel]) => channel.client !== undefined
+        || channel.server !== undefined
+        || channel.publisher !== undefined
+        || channel.subscriber !== undefined)
+        .map(([channelName]) => channelName));
+    if (declaredChannelNames.size === 0)
+        return;
+    const routeMeshChannels = new Set(registration.routeChannels);
+    for (const spotNode of registration.spotNodes.values()) {
+        for (const channelName of Object.keys(spotNode.meshChannels ?? {})) {
+            routeMeshChannels.add(channelName);
+        }
+    }
+    for (const channelName of declaredChannelNames) {
+        if (routeMeshChannels.has(channelName)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`ChannelName '${channelName}' is registered on both RouteMesh and ClientServer physical paths.`);
+        }
+    }
+}
+function toActorFactoryCount(value) {
+    if (value === undefined) {
+        return 0;
+    }
+    return value instanceof Map ? value.size : Object.keys(value).length;
+}
+function hasLocationStores(registration) {
+    return registration.locations.useInMemoryStores
+        || registration.locations.storeInstance !== undefined;
+}
+function validateWorkerOptions(worker) {
+    if (worker === undefined) {
+        return;
+    }
+    requireNonNegativeInteger('Worker minThreads', worker.minThreads);
+    (0, RegistrationNormalizers_1.requirePositiveInteger)('Worker maxThreads', worker.maxThreads);
+    requireNonNegativeInteger('Worker idleTimeoutMs', worker.idleTimeoutMs);
+    (0, RegistrationNormalizers_1.requirePositiveInteger)('Worker maxQueueLength', worker.maxQueueLength);
+    if (worker.maxThreads < worker.minThreads) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('Worker maxThreads must be greater than or equal to minThreads.');
+    }
+}
+function validateLocationRegistration(registration) {
+    const locations = registration.locations;
+    if (locations.useInMemoryStores && locations.storeInstance !== undefined) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('In-memory location stores cannot be combined with explicit location store registrations.');
+    }
+    const store = locations.storeInstance;
+    if (store !== undefined
+        && (typeof store.read !== 'function'
+            || typeof store.write !== 'function'
+            || typeof store.scan !== 'function')) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('Location Store must implement read, write, and scan.');
+    }
+    const options = { ...Locations_1.zlinkDefaultLocationOptions, ...locations.options };
+    for (const [name, value] of Object.entries({
+        ownerLeaseRenewIntervalMs: options.ownerLeaseRenewIntervalMs,
+        ownerLeaseTtlMs: options.ownerLeaseTtlMs,
+        ownerLeaseFencingMarginMs: options.ownerLeaseFencingMarginMs,
+        ownerLeaseRenewTimeoutMs: options.ownerLeaseRenewTimeoutMs,
+        sessionRelocationSealTimeoutMs: options.sessionRelocationSealTimeoutMs
+    })) {
+        if (!Number.isFinite(value) || value <= 0) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`${name} must be a finite positive number.`);
+        }
+    }
+    if (options.ownerLeaseRenewIntervalMs + options.ownerLeaseRenewTimeoutMs
+        >= options.ownerLeaseTtlMs - options.ownerLeaseFencingMarginMs) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('ownerLeaseRenewIntervalMs + ownerLeaseRenewTimeoutMs must be less than ownerLeaseTtlMs - ownerLeaseFencingMarginMs.');
+    }
+    for (const [name, value] of Object.entries({
+        relocationCutoverWaitTimeoutMs: options.relocationCutoverWaitTimeoutMs,
+        relocationPayloadChunkLimitBytes: options.relocationPayloadChunkLimitBytes
+    })) {
+        if (!Number.isInteger(value) || value <= 0) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`${name} must be a positive integer.`);
+        }
+    }
+    if (options.relocationPayloadChunkLimitBytes > 67_108_864) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('relocationPayloadChunkLimitBytes must not exceed the 64 MiB wire chunk bound.');
+    }
+    for (const [name, value] of Object.entries({
+        relocationInFlightPayloadBudgetBytes: options.relocationInFlightPayloadBudgetBytes,
+        relocationNodeInFlightPayloadBudgetBytes: options.relocationNodeInFlightPayloadBudgetBytes
+    })) {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`${name} must be a non-negative safe integer (0 disables the budget).`);
+        }
+    }
+    for (const [name, value] of Object.entries({
+        routeCacheMaxAgeMs: options.routeCacheMaxAgeMs,
+        messageFollowDurationMs: options.messageFollowDurationMs
+    })) {
+        if (!Number.isFinite(value) || value < 0) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`${name} must be a finite non-negative number.`);
+        }
+    }
+    if (options.routeCacheMaxAgeMs > 0
+        && options.messageFollowDurationMs > 0
+        && options.routeCacheMaxAgeMs > options.messageFollowDurationMs - 5000) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('routeCacheMaxAgeMs must be at least 5000 ms shorter than messageFollowDurationMs.');
+    }
+}
+function requireNonNegativeInteger(label, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isInteger(value) || value < 0) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must be a non-negative integer.`);
+    }
+}
+function requireNonNegativeSafeInteger(label, value) {
+    if (value === undefined)
+        return;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must be a non-negative safe integer.`);
+    }
+}
+function validateChannelCapabilities(channels, peerLocationConfigured) {
+    for (const [channelName, channel] of Object.entries(channels ?? {})) {
+        if (channel.server !== undefined) {
+            requireEndpoint(`channel '${channelName}' server`, channel.server.bind);
+            validateListenerNetworkIdentity(`channel '${channelName}' server`, channel.server.bind, channel.server.bindHost, channel.server.advertiseHost);
+            if (channel.server.routingId !== undefined) {
+                requireName(`channel '${channelName}' server routingId`, channel.server.routingId);
+            }
+            requirePeerWeight(`channel '${channelName}' server weight`, channel.server.weight);
+            requireSocketOptions(`channel '${channelName}' server`, channel.server);
+        }
+        if (channel.publisher !== undefined) {
+            requireEndpoint(`channel '${channelName}' publisher`, channel.publisher.bind);
+            validateListenerNetworkIdentity(`channel '${channelName}' publisher`, channel.publisher.bind, channel.publisher.bindHost, channel.publisher.advertiseHost);
+            validateFanoutPublisherIdentity(channelName, channel.routingId, channel.routingIdPrefix, peerLocationConfigured);
+        }
+        if (channel.client !== undefined) {
+            requirePeerSource(`channel '${channelName}' client`, channel.client.manualConnections, peerLocationConfigured || channel.server !== undefined);
+            requireSocketOptions(`channel '${channelName}' client`, channel.client);
+        }
+        if (channel.subscriber !== undefined) {
+            requirePeerSource(`channel '${channelName}' subscriber`, channel.subscriber.manualConnections, peerLocationConfigured);
+        }
+        if ((channel.publishHandlers ?? []).length > 0 && channel.subscriber === undefined) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Channel '${channelName}' publish handlers require a subscriber capability.`);
+        }
+        if (channel.subscriber !== undefined && (channel.publishHandlers ?? []).length === 0) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Channel '${channelName}' subscriber must register at least one publish handler.`);
+        }
+        if (((channel.requestHandlers ?? []).length > 0 || (channel.sendHandlers ?? []).length > 0) && channel.server === undefined) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Channel '${channelName}' request/send handlers require a server capability.`);
+        }
+        if (channel.server !== undefined
+            && (channel.requestHandlers ?? []).length + (channel.sendHandlers ?? []).length === 0) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Channel '${channelName}' server must register at least one request or send handler.`);
+        }
+        validateDuplicatePacketNames(`channel '${channelName}' request handler`, channel.requestHandlers?.map((handler) => handler.packetName));
+        validateDuplicatePacketNames(`channel '${channelName}' send handler`, channel.sendHandlers?.map((handler) => handler.packetName));
+        validateDuplicatePacketNames(`channel '${channelName}' publish handler`, channel.publishHandlers?.map((handler) => handler.packetName));
+        if (channel.routeMesh !== undefined) {
+            validateRouteMeshCapability(`channel '${channelName}' route mesh`, channel.routeMesh, peerLocationConfigured);
+        }
+    }
+}
+function validateSpotNodes(registration) {
+    for (const [spotNodeName, spotNode] of registration.spotNodes.entries()) {
+        if (spotNodeName.trim().length === 0 || spotNodeName.trim() !== spotNodeName) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('SpotNode name must not be empty or padded.');
+        }
+        if (spotNode.router === undefined && spotNode.pubSub === undefined) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`SpotNode '${spotNodeName}' must enable router or pubSub capability.`);
+        }
+        if (toActorFactoryCount(spotNode.actorFactories) > 0 && spotNode.router === undefined) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`SpotNode '${spotNodeName}' must enable router capability when actor factories are registered.`);
+        }
+        validateSpotNodeCapability(`SpotNode '${spotNodeName}' router`, spotNode.router);
+        validateMeshChannels(spotNodeName, spotNode.meshChannels);
+        if (spotNode.router !== undefined) {
+            validateListenerNetworkIdentity(`SpotNode '${spotNodeName}' router`, spotNode.router.bind, spotNode.router.bindHost, spotNode.router.advertiseHost);
+        }
+        validateSpotNodeCapability(`SpotNode '${spotNodeName}' pubSub`, spotNode.pubSub);
+        requireNonNegativeSafeInteger(`SpotNode '${spotNodeName}' instanceSpotIdleTimeoutMs`, spotNode.instanceSpotIdleTimeoutMs);
+        (0, SendTimeoutValidation_1.requireValidSendTimeoutMs)(`SpotNode '${spotNodeName}' publisher sendTimeoutMs`, spotNode.publisherConfig?.sendTimeoutMs);
+        validateSpotNodeFactories(spotNodeName, spotNode);
+        validateSpotNodeTimers(spotNode);
+        if (spotNode.objectRole === 'client'
+            && ((spotNode.routeSendHandlers?.length ?? 0) > 0
+                || (spotNode.routeRequestHandlers?.length ?? 0) > 0)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Object Client RouteMesh '${spotNodeName}' cannot register Node-direct handlers.`);
+        }
+        if (spotNode.router?.routingId !== undefined &&
+            spotNode.pubSub?.routingId !== undefined &&
+            spotNode.router.routingId !== spotNode.pubSub.routingId) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`SpotNode '${spotNodeName}' router and pubSub routingId must match.`);
+        }
+    }
+}
+function validateMeshChannels(spotNodeName, meshChannels) {
+    for (const [channelName, channel] of Object.entries(meshChannels ?? {})) {
+        requireName(`RouteMesh '${spotNodeName}' channel`, channelName);
+        const handlerCount = (channel.requestHandlers?.length ?? 0)
+            + (channel.sendHandlers?.length ?? 0);
+        if (channel.client === true && channel.server === true) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`RouteMesh '${spotNodeName}' channel '${channelName}' must register exactly one role.`);
+        }
+        if (channel.server !== true && handlerCount > 0) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`RouteMesh '${spotNodeName}' channel '${channelName}' handlers require a server role.`);
+        }
+        if (channel.client !== true && channel.server !== true) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`RouteMesh '${spotNodeName}' channel '${channelName}' must register a client or server role.`);
+        }
+        validateDuplicatePacketNames(`RouteMesh '${spotNodeName}' channel '${channelName}' request handler`, channel.requestHandlers?.map((handler) => handler.packetName));
+        validateDuplicatePacketNames(`RouteMesh '${spotNodeName}' channel '${channelName}' send handler`, channel.sendHandlers?.map((handler) => handler.packetName));
+    }
+}
+function validateSpotNodeTimers(spotNode) {
+    for (const timer of spotNode.entrySpotTimerHandlers ?? []) {
+        (0, TimerRegistrationValidator_1.validateTimerRegistration)(timer.name, timer.periodMs, timer.options);
+    }
+    for (const timer of spotNode.spotTimerHandlers ?? []) {
+        (0, TimerRegistrationValidator_1.validateTimerRegistration)(timer.name, timer.periodMs, timer.options);
+    }
+}
+function validateSpotNodeFactories(spotNodeName, spotNode) {
+    const seen = new Set();
+    for (const factory of spotNode.spotFactories ?? []) {
+        if (seen.has(factory)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Duplicate SPOT factory registration on SpotNode '${spotNodeName}'.`);
+        }
+        seen.add(factory);
+    }
+}
+function validateSpotNodeCapability(capabilityName, capability) {
+    if (capability === undefined) {
+        return;
+    }
+    validateManualConnections(capabilityName, capability.manualConnections);
+    validateRouterPeerConnections(capabilityName, 'manualPeerConnections' in capability ? capability.manualPeerConnections : undefined);
+    requireEndpoint(capabilityName, capability.bind);
+    if (capability.routingId !== undefined && (capability.routingId.trim().length === 0 || capability.routingId.trim() !== capability.routingId)) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${capabilityName} routingId must not be empty or padded.`);
+    }
+}
+function validateListenerNetworkIdentity(capabilityName, bindEndpoint, configuredBindHost, advertiseHost) {
+    const bindHost = configuredBindHost ?? tcpEndpointHost(bindEndpoint);
+    if (configuredBindHost !== undefined) {
+        requireName(`${capabilityName} bind host`, configuredBindHost);
+    }
+    if (advertiseHost !== undefined) {
+        requireName(`${capabilityName} advertise host`, advertiseHost);
+        if (isWildcardHost(advertiseHost)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`${capabilityName} advertise host must identify a connectable host, not a wildcard address.`);
+        }
+    }
+    if (bindHost !== undefined && isWildcardHost(bindHost) && advertiseHost === undefined) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${capabilityName} must define an advertise host when its bind host is a wildcard address.`);
+    }
+}
+function tcpEndpointHost(endpoint) {
+    const match = /^tcp:\/\/(\[[^\]]+\]|[^:]+):\d+$/.exec(endpoint ?? '');
+    return match?.[1];
+}
+function isWildcardHost(host) {
+    const normalized = host.startsWith('[') && host.endsWith(']')
+        ? host.slice(1, -1)
+        : host;
+    return normalized === '0.0.0.0' || normalized === '::';
+}
+function validateManualConnections(capabilityName, manualConnections) {
+    if ((manualConnections ?? []).some((endpoint) => endpoint.trim().length === 0)) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${capabilityName} manual connection endpoint must not be empty.`);
+    }
+}
+function validateRouterPeerConnections(capabilityName, manualPeerConnections) {
+    const seenPeerRids = new Set();
+    for (const connection of manualPeerConnections ?? []) {
+        const peerRid = String(connection.peerRid);
+        if (peerRid.trim().length === 0) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`${capabilityName} manual peer routing id must not be empty.`);
+        }
+        if (seenPeerRids.has(peerRid)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`${capabilityName} manual peer routing id must be unique.`);
+        }
+        seenPeerRids.add(peerRid);
+        if (connection.endpoint.trim().length === 0) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`${capabilityName} manual peer connection endpoint must not be empty.`);
+        }
+    }
+}
+function validateDuplicatePacketNames(label, packetNames) {
+    const seen = new Set();
+    for (const packetName of packetNames ?? []) {
+        requireName(label, packetName);
+        if (seen.has(packetName)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Duplicate ${label} packet '${packetName}'.`);
+        }
+        seen.add(packetName);
+    }
+}
+function requireName(label, value) {
+    if (value.trim().length === 0 || value.trim() !== value) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must not be empty or padded.`);
+    }
+}
+function requirePeerSource(capabilityName, manualConnections, peerLocationConfigured) {
+    validateManualConnections(capabilityName, manualConnections);
+    if ((manualConnections ?? []).length > 0 || peerLocationConfigured) {
+        return;
+    }
+    throw new ConfigurationException_1.ZLinkConfigurationException(`${capabilityName} requires location stores or manual connections.`);
+}
+function validateFanoutPublisherIdentity(channelName, routingId, routingIdPrefix, peerLocationConfigured) {
+    if (!peerLocationConfigured)
+        return;
+    if (routingId !== undefined && routingIdPrefix !== undefined) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`channel '${channelName}' publisher cannot combine a fixed routing id with an automatic routing id prefix.`);
+    }
+    if (routingId === undefined && routingIdPrefix === undefined) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`channel '${channelName}' publisher must select a fixed routing id or an automatic routing id prefix.`);
+    }
+    if (routingId !== undefined)
+        requireName(`channel '${channelName}' publisher routingId`, routingId);
+}
+function requireEndpoint(capabilityName, endpoint) {
+    if (endpoint === undefined || endpoint.trim().length === 0) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${capabilityName} must define a bind endpoint.`);
+    }
+}
+function requireFilePath(label, value) {
+    if (value === undefined || value.trim().length === 0) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must define a file path.`);
+    }
+}
+function validateStreamNodes(registration) {
+    const sessionTypes = new Map();
+    for (const [streamNodeName, streamNode] of registration.streamNodes.entries()) {
+        requireNonNegativeInteger(`STREAM node '${streamNodeName}' maxMessageSize`, streamNode.maxMessageSize);
+        requireEndpoint(`STREAM node '${streamNodeName}'`, streamNode.bind);
+        validateListenerNetworkIdentity(`STREAM node '${streamNodeName}'`, streamNode.bind, streamNode.bindHost, streamNode.advertiseHost);
+        if (streamNode.tlsServer !== undefined) {
+            requireFilePath(`STREAM node '${streamNodeName}' TLS certificate`, streamNode.tlsServer.certificatePath);
+            requireFilePath(`STREAM node '${streamNodeName}' TLS key`, streamNode.tlsServer.keyPath);
+        }
+        if (streamNode.session === undefined) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`STREAM node '${streamNodeName}' must register a header stream session.`);
+        }
+        const sessionTypeName = streamNode.session.name;
+        const registeredNodeName = sessionTypes.get(sessionTypeName);
+        if (registeredNodeName !== undefined) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`STREAM session type '${sessionTypeName}' is registered on both '${registeredNodeName}' and '${streamNodeName}'.`);
+        }
+        sessionTypes.set(sessionTypeName, streamNodeName);
+        if (streamNode.actorDispatchEnabled === true) {
+            if (!hasLocationStores(registration)) {
+                throw new ConfigurationException_1.ZLinkConfigurationException(`STREAM node '${streamNodeName}' enables Actor dispatch but no Location Store is registered.`);
+            }
+            if (![...registration.spotNodes.values()].some((spotNode) => spotNode.objectRole !== undefined)) {
+                throw new ConfigurationException_1.ZLinkConfigurationException(`STREAM node '${streamNodeName}' requires at least one local Object Client or Server MeshNode.`);
+            }
+        }
+    }
+}
+function validateRouteChannels(registration, peerLocationConfigured) {
+    for (const routeChannel of registration.routeChannelOptions.values()) {
+        if (!(0, RouteChannelInternalState_1.isRouteTransportDeclared)(routeChannel) && !isRouteTransportConfigured(routeChannel)) {
+            continue;
+        }
+        if (!isRoutePacketCapabilityConfigured(routeChannel) &&
+            isAcceptedSpotRouteChannel(registration, routeChannel)) {
+            continue;
+        }
+        validateRouteMeshCapability(`route channel '${routeChannel.routerChannelId}'`, routeChannel, peerLocationConfigured);
+        if (routeChannelHandlerCount(routeChannel) > 0 && !hasBind(routeChannel.bind)) {
+            requireEndpoint(`route channel '${routeChannel.routerChannelId}' router`, routeChannel.bind);
+        }
+    }
+}
+function isRouteTransportConfigured(routeChannel) {
+    return isRoutePacketCapabilityConfigured(routeChannel);
+}
+function isRoutePacketCapabilityConfigured(routeChannel) {
+    return hasBind(routeChannel.bind)
+        || (0, RouteChannelInternalState_1.isRouteClientEnabled)(routeChannel)
+        || (routeChannel.manualConnections ?? []).length > 0
+        || routeChannelHandlerCount(routeChannel) > 0;
+}
+function isAcceptedSpotRouteChannel(registration, routeChannel) {
+    if (!(0, RouteChannelInternalState_1.isRouteTransportDeclared)(routeChannel)) {
+        return false;
+    }
+    if (registration.spotNodes.get(routeChannel.routerChannelId)?.router !== undefined) {
+        return true;
+    }
+    if (routeChannel.routingId !== undefined) {
+        return [...registration.spotNodes.values()].some((spotNode) => spotNode.router?.routingId === routeChannel.routingId);
+    }
+    return [...registration.spotNodes.values()].filter((spotNode) => spotNode.router !== undefined).length === 1;
+}
+function validateRouteMeshCapability(capabilityName, routeChannel, peerLocationConfigured = false) {
+    const clientEnabled = (0, RouteChannelInternalState_1.isRouteClientEnabled)(routeChannel)
+        || (routeChannel.manualConnections ?? []).length > 0;
+    if (!hasBind(routeChannel.bind) && !clientEnabled) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${capabilityName} must enable server or client capability.`);
+    }
+    if (clientEnabled) {
+        requirePeerSource(capabilityName, routeChannel.manualConnections, peerLocationConfigured);
+    }
+    requirePeerWeight(`${capabilityName} weight`, routeChannel.weight);
+    requireRouteMeshSocketOptions(capabilityName, routeChannel);
+}
+function routeChannelHandlerCount(routeChannel) {
+    return (routeChannel.handlers ?? []).length +
+        (routeChannel.sendHandlers ?? []).length +
+        (routeChannel.requestHandlers ?? []).length;
+}
+function hasBind(endpoint) {
+    return endpoint !== undefined && endpoint.trim().length > 0;
+}
+function requirePeerWeight(label, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isInteger(value) || value < 0 || value > 10_000) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must be an integer in 0..10000.`);
+    }
+}
+function requireSocketOptions(label, options) {
+    requireNonNegativeInteger(`${label} sendHighWaterMark`, options.sendHighWaterMark);
+    requireNonNegativeInteger(`${label} receiveHighWaterMark`, options.receiveHighWaterMark);
+    requireNonNegativeInteger(`${label} maxMessageSize`, options.maxMessageSize);
+    (0, SendTimeoutValidation_1.requireValidSendTimeoutMs)(`${label} sendTimeoutMs`, options.sendTimeoutMs);
+}
+function requireRouteMeshSocketOptions(label, options) {
+    requireNonNegativeInteger(`${label} sendHighWaterMark`, options.sendHighWaterMark);
+    requireNonNegativeInteger(`${label} receiveHighWaterMark`, options.receiveHighWaterMark);
+    (0, SendTimeoutValidation_1.requireValidSendTimeoutMs)(`${label} sendTimeoutMs`, options.sendTimeoutMs);
+}

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

@@ -0,0 +1,10 @@
+import type { ZLinkRouteChannelOptions, ZLinkRouteMeshChannelOptions } from './RegistrationTypes';
+export interface RouteChannelInternalState {
+    readonly transportDeclared?: boolean;
+    readonly clientEnabled?: boolean;
+}
+export declare function markRouteTransportDeclared(routeChannel: object): void;
+export declare function markRouteClientEnabled(routeChannel: object): void;
+export declare function copyRouteInternalState(source: object, target: object): void;
+export declare function isRouteTransportDeclared(routeChannel: ZLinkRouteChannelOptions): boolean;
+export declare function isRouteClientEnabled(routeChannel: ZLinkRouteChannelOptions | ZLinkRouteMeshChannelOptions): boolean;

package/dist/contracts/Configuration/RouteChannelInternalState.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.markRouteTransportDeclared = markRouteTransportDeclared;
+exports.markRouteClientEnabled = markRouteClientEnabled;
+exports.copyRouteInternalState = copyRouteInternalState;
+exports.isRouteTransportDeclared = isRouteTransportDeclared;
+exports.isRouteClientEnabled = isRouteClientEnabled;
+function markRouteTransportDeclared(routeChannel) {
+    defineRouteInternalFlag(routeChannel, 'transportDeclared');
+}
+function markRouteClientEnabled(routeChannel) {
+    defineRouteInternalFlag(routeChannel, 'clientEnabled');
+}
+function copyRouteInternalState(source, target) {
+    const state = routeInternalState(source);
+    if (state.transportDeclared === true) {
+        markRouteTransportDeclared(target);
+    }
+    if (state.clientEnabled === true) {
+        markRouteClientEnabled(target);
+    }
+}
+function isRouteTransportDeclared(routeChannel) {
+    return routeInternalState(routeChannel).transportDeclared === true;
+}
+function isRouteClientEnabled(routeChannel) {
+    return routeInternalState(routeChannel).clientEnabled === true;
+}
+function routeInternalState(routeChannel) {
+    return routeChannel;
+}
+function defineRouteInternalFlag(routeChannel, key) {
+    Object.defineProperty(routeChannel, key, {
+        value: true,
+        configurable: true,
+        enumerable: false,
+        writable: true
+    });
+}

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

@@ -0,0 +1,9 @@
+import type { ZLinkEndpointConnections } from './Connections';
+interface ConnectableEndpointSocket {
+    connect(endpoint: string): void;
+    disconnect(endpoint: string): void;
+}
+export declare function endpointConnections(owner: object, endpoints: readonly string[]): ZLinkEndpointConnections;
+export declare function attachEndpointConnections(owner: object, socket: ConnectableEndpointSocket): void;
+export declare function detachEndpointConnections(owner: object): void;
+export {};

package/dist/contracts/Configuration/RuntimeEndpointConnections.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.endpointConnections = endpointConnections;
+exports.attachEndpointConnections = attachEndpointConnections;
+exports.detachEndpointConnections = detachEndpointConnections;
+const EndpointNotation_1 = require("./EndpointNotation");
+const controllers = new WeakMap();
+class RuntimeEndpointConnections {
+    socket;
+    endpoints;
+    constructor(endpoints) {
+        if (Array.isArray(endpoints) && Object.isExtensible(endpoints)) {
+            // Builder registration and the public handle must observe one mutable
+            // endpoint set. A frozen, sealed or external readonly array uses a
+            // private snapshot because it cannot safely be updated in place.
+            this.endpoints = endpoints;
+            // Normalize in place -- callers (and the builder that shares this
+            // array) must keep observing the same array identity.
+            for (let index = 0; index < this.endpoints.length; index += 1) {
+                this.endpoints[index] = (0, EndpointNotation_1.normalizeEndpoint)(this.endpoints[index]);
+            }
+            for (let index = this.endpoints.length - 1; index >= 0; index -= 1) {
+                if (this.endpoints.indexOf(this.endpoints[index]) !== index) {
+                    this.endpoints.splice(index, 1);
+                }
+            }
+        }
+        else {
+            this.endpoints = [];
+            for (const endpoint of endpoints) {
+                const normalizedEndpoint = (0, EndpointNotation_1.normalizeEndpoint)(endpoint);
+                if (!this.endpoints.includes(normalizedEndpoint)) {
+                    this.endpoints.push(normalizedEndpoint);
+                }
+            }
+        }
+    }
+    connect(endpoint) {
+        const normalizedEndpoint = (0, EndpointNotation_1.normalizeEndpoint)(endpoint);
+        if (!this.endpoints.includes(normalizedEndpoint)) {
+            this.endpoints.push(normalizedEndpoint);
+            this.socket?.connect(normalizedEndpoint);
+        }
+    }
+    disconnect(endpoint) {
+        // Normalize so a caller using a different (but equivalent) notation than
+        // the one recorded at connect() time still matches -- otherwise this is
+        // a silent no-op from the caller's perspective.
+        const normalizedEndpoint = (0, EndpointNotation_1.normalizeEndpoint)(endpoint);
+        const index = this.endpoints.indexOf(normalizedEndpoint);
+        if (index >= 0) {
+            this.endpoints.splice(index, 1);
+            this.socket?.disconnect(normalizedEndpoint);
+        }
+    }
+    listConnections() {
+        return Object.freeze([...this.endpoints]);
+    }
+    attach(socket) {
+        this.socket = socket;
+    }
+    detach() {
+        this.socket = undefined;
+    }
+}
+function endpointConnections(owner, endpoints) {
+    let controller = controllers.get(owner);
+    if (controller === undefined) {
+        controller = new RuntimeEndpointConnections(endpoints);
+        controllers.set(owner, controller);
+    }
+    return controller;
+}
+function attachEndpointConnections(owner, socket) {
+    const controller = controllers.get(owner);
+    controller?.attach(socket);
+}
+function detachEndpointConnections(owner) {
+    controllers.get(owner)?.detach();
+}

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

@@ -0,0 +1,2 @@
+export declare const ZLINK_MAX_SEND_TIMEOUT_MS = 2147483647;
+export declare function requireValidSendTimeoutMs(label: string, value: number | undefined): void;

package/dist/contracts/Configuration/SendTimeoutValidation.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLINK_MAX_SEND_TIMEOUT_MS = void 0;
+exports.requireValidSendTimeoutMs = requireValidSendTimeoutMs;
+const ConfigurationException_1 = require("./ConfigurationException");
+exports.ZLINK_MAX_SEND_TIMEOUT_MS = 2_147_483_647;
+function requireValidSendTimeoutMs(label, value) {
+    if (value === undefined)
+        return;
+    if (!Number.isFinite(value)
+        || !Number.isInteger(value)
+        || value < 1
+        || value > exports.ZLINK_MAX_SEND_TIMEOUT_MS) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must be an integer between 1 and ${exports.ZLINK_MAX_SEND_TIMEOUT_MS} milliseconds.`);
+    }
+}

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

@@ -0,0 +1,2 @@
+import { type ZLinkTimerOptions } from '../Timers';
+export declare function validateTimerRegistration(name: string, periodMs: number, options: ZLinkTimerOptions | undefined): void;

package/dist/contracts/Configuration/TimerRegistrationValidator.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateTimerRegistration = validateTimerRegistration;
+const Timers_1 = require("../Timers");
+const ConfigurationException_1 = require("./ConfigurationException");
+function validateTimerRegistration(name, periodMs, options) {
+    if (name.trim().length === 0) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('SPOT timer name must not be empty.');
+    }
+    if (!Number.isFinite(periodMs) || periodMs <= 0) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('SPOT timer period must be greater than zero.');
+    }
+    if (options?.overrunPolicy !== undefined
+        && !Object.values(Timers_1.ZLinkTimerOverrunPolicy).includes(options.overrunPolicy)) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('SPOT timer overrun policy is not supported.');
+    }
+    if (options?.overrunPolicy === Timers_1.ZLinkTimerOverrunPolicy.CatchUpBounded
+        && (options.maxCatchUpTicks === undefined
+            || !Number.isInteger(options.maxCatchUpTicks)
+            || options.maxCatchUpTicks < 1
+            || options.maxCatchUpTicks > 2_147_483_647)) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('SPOT timer MaxCatchUpTicks must be an integer from 1 through 2,147,483,647.');
+    }
+}

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

@@ -0,0 +1,5 @@
+export type { ZLinkClientServerChannelClientBuilder, ZLinkClientServerChannelRoleBuilder, ZLinkClientServerChannelServerBuilder, ZLinkFanoutChannelBuilder, ZLinkFrameworkOptions, ZLinkMeshChannelBuilder, ZLinkMeshChannelClientBuilder, ZLinkMeshChannelServerBuilder, ZLinkMeshObjectClientBuilder, ZLinkMeshObjectRoleBuilder, ZLinkMeshObjectServerBuilder, ZLinkMeshNodeBuilder, ZLinkMeshNodeSocketConfig, ZLinkMeshPeerConnection, ZLinkMeshPeerConnections, ZLinkNetworkOptions, ZLinkMetadataPolicyBuilder, ZLinkStreamCompressionBuilder, ZLinkStreamSocketConfig, ZLinkStreamNodeBuilder } from './Builders';
+export type { ZLinkOutboundRouteConfig, ZLinkRouteConfig, ZLinkSocketConfig, ZLinkSpotPublisherConfig } from './Configs';
+export * from './Connections';
+export * from './ObjectRoles';
+export type { ZLinkApplicationJobQueueOptions, ZLinkCoreHwmOptions, ZLinkWorkerOptions } from './RegistrationTypes';