@zlink-systems/framework 0.10.0

package/dist/contracts/Configuration/RegistrationBuilders.js

@@ -0,0 +1,1181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultStreamCompressionBuilder = exports.DefaultLocationOptionsBuilder = exports.DefaultInboundDispatchOptionsBuilder = exports.DefaultDispatchOptionsBuilder = void 0;
+exports.createFrameworkOptions = createFrameworkOptions;
+const ObjectRoles_1 = require("./ObjectRoles");
+const Attributes_1 = require("../Handlers/Attributes");
+const Dispatch_1 = require("../Dispatch");
+const zlink_1 = require("@zlink-systems/zlink");
+const RuntimeEndpointConnections_1 = require("./RuntimeEndpointConnections");
+const ConfigurationException_1 = require("./ConfigurationException");
+const RegistrationCodecRegistry_1 = require("./RegistrationCodecRegistry");
+const RegistrationNormalizers_1 = require("./RegistrationNormalizers");
+const EndpointNotation_1 = require("./EndpointNotation");
+const InternalDefaults_1 = require("./InternalDefaults");
+const RegistrationBuilderPolicy_1 = require("./RegistrationBuilderPolicy");
+const DiagnosticsValidation_1 = require("./DiagnosticsValidation");
+function createFrameworkOptions(configure) {
+    const builder = new ZLinkFrameworkOptionsBuilder();
+    configure(builder);
+    return builder.build();
+}
+class ZLinkFrameworkOptionsBuilder {
+    spotMeshes = new Set();
+    options = {
+        network: { bindHost: '127.0.0.1' },
+        channels: {},
+        streamNodes: {},
+        spotNodes: {},
+        spotFactories: []
+    };
+    codecs() {
+        this.options.codecs ??= { serializers: [], streamCodecs: [] };
+        return new RegistrationCodecRegistry_1.RegistrationCodecRegistryBuilder(this.options.codecs);
+    }
+    configureNetwork() {
+        return this.options.network;
+    }
+    configureWorker(options) {
+        this.options.worker = { ...this.options.worker, ...options };
+        return this;
+    }
+    configureDispatch() {
+        this.options.dispatch ??= defaultDispatchOptions();
+        return new DefaultDispatchOptionsBuilder(this.options.dispatch);
+    }
+    configureInboundDispatch() {
+        return new DefaultInboundDispatchOptionsBuilder(this.options);
+    }
+    addLocationStore(store) {
+        this.options.locations ??= { options: {} };
+        this.options.locations.storeInstance = store;
+        return this;
+    }
+    addRelocationStore(store) {
+        this.options.locations ??= { options: {} };
+        this.options.locations.relocationStoreInstance = store;
+        return this;
+    }
+    setApplicationVersion(version) {
+        this.options.applicationVersion = version;
+        return this;
+    }
+    setMaintenanceWave(waveId) {
+        this.options.maintenanceWave = waveId;
+        return this;
+    }
+    setActorTransferTimeout(timeoutMs) {
+        this.options.actorTransferTimeoutMs = (0, RegistrationBuilderPolicy_1.validateActorTransferTimeout)(timeoutMs);
+        return this;
+    }
+    setMessageFollowDuration(timeoutMs) {
+        this.options.messageFollowDurationMs = (0, RegistrationBuilderPolicy_1.validateMessageFollowDuration)(timeoutMs);
+        return this;
+    }
+    setSessionReplacementCallbackTimeout(timeoutMs) {
+        this.options.sessionReplacementCallbackTimeoutMs = (0, RegistrationBuilderPolicy_1.validateSessionReplacementCallbackTimeout)(timeoutMs);
+        return this;
+    }
+    configureLocations() {
+        this.options.locations ??= { options: {} };
+        this.options.locations.options ??= {};
+        return new DefaultLocationOptionsBuilder(this.options.locations.options);
+    }
+    configureStreamCompression() {
+        this.options.streamCompression ??= {};
+        return new DefaultStreamCompressionBuilder(this.options.streamCompression);
+    }
+    addRouteMesh(meshName) {
+        requireRegistrationName(meshName, 'RouteMesh');
+        if (this.spotMeshes.has(meshName)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Duplicate RouteMesh '${meshName}'.`);
+        }
+        this.spotMeshes.add(meshName);
+        const node = this.spotNodeOptions(meshName);
+        node.router ??= { port: 0 };
+        return new DefaultMeshNodeBuilder(meshName, node);
+    }
+    addFanoutChannel(name) {
+        return new DefaultFanoutChannelBuilder(name, this.channel(name));
+    }
+    addClientServerChannel(name) {
+        return new DefaultClientServerChannelRoleBuilder(name, this.clientServerChannel(name));
+    }
+    addStreamNode(name) {
+        if (name.trim().length === 0 || name.trim() !== name) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('STREAM node name must not be empty or padded.');
+        }
+        if (Object.prototype.hasOwnProperty.call(this.options.streamNodes, name)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Duplicate STREAM node '${name}'.`);
+        }
+        const streamNode = {
+            maxMessageSize: InternalDefaults_1.DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE
+        };
+        this.options.streamNodes[name] = streamNode;
+        return new DefaultStreamNodeBuilder(streamNode);
+    }
+    build() {
+        return {
+            network: { ...this.options.network },
+            codecs: this.options.codecs,
+            applicationVersion: this.options.applicationVersion,
+            maintenanceWave: this.options.maintenanceWave,
+            channels: this.options.channels,
+            requestTimeoutMs: this.options.requestTimeoutMs,
+            streamNodes: this.options.streamNodes,
+            streamCompression: this.options.streamCompression,
+            spotNodes: this.options.spotNodes,
+            spotFactories: this.options.spotFactories,
+            actorTransferTimeoutMs: this.options.actorTransferTimeoutMs,
+            messageFollowDurationMs: this.options.messageFollowDurationMs,
+            sessionReplacementCallbackTimeoutMs: this.options.sessionReplacementCallbackTimeoutMs,
+            dispatch: this.options.dispatch,
+            worker: this.options.worker,
+            coreHwm: this.options.coreHwm,
+            applicationJobQueue: this.options.applicationJobQueue,
+            locations: this.options.locations
+        };
+    }
+    channel(name) {
+        if (name.trim().length === 0 || name.trim() !== name) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('Channel name must not be empty or padded.');
+        }
+        if (Object.prototype.hasOwnProperty.call(this.options.channels, name)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Duplicate channel '${name}'.`);
+        }
+        const channel = {};
+        this.options.channels[name] = channel;
+        return channel;
+    }
+    clientServerChannel(name) {
+        if (name.trim().length === 0 || name.trim() !== name) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('Channel name must not be empty or padded.');
+        }
+        if (!Object.prototype.hasOwnProperty.call(this.options.channels, name)) {
+            const channel = {};
+            this.options.channels[name] = channel;
+            return channel;
+        }
+        const current = this.options.channels[name];
+        if (current.publisher !== undefined || current.subscriber !== undefined) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Duplicate channel '${name}'.`);
+        }
+        return current;
+    }
+    spotNodeOptions(name) {
+        this.options.spotNodes[name] ??= {};
+        return this.options.spotNodes[name];
+    }
+}
+class DefaultDispatchOptionsBuilder {
+    dispatch;
+    constructor(dispatch) {
+        this.dispatch = dispatch;
+    }
+    messageFlow(mode) {
+        this.dispatch.diagnostics.messageFlow = (0, DiagnosticsValidation_1.requireMessageFlowLogMode)(mode);
+        return this;
+    }
+    traceSampleRate(rate) {
+        this.dispatch.diagnostics.sampleRate = (0, DiagnosticsValidation_1.requireTraceSampleRate)(rate);
+        return this;
+    }
+    includeMessageSizes(include) {
+        this.dispatch.diagnostics.includeMessageSizes = include;
+        return this;
+    }
+}
+exports.DefaultDispatchOptionsBuilder = DefaultDispatchOptionsBuilder;
+class DefaultInboundDispatchOptionsBuilder {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    coreHwmMemoryLimitBytes(value) {
+        this.options.coreHwm = { ...this.options.coreHwm, memoryLimitBytes: value };
+        return this;
+    }
+    coreHwmBudgetBytes(value) {
+        this.options.coreHwm = { ...this.options.coreHwm, budgetBytes: value };
+        return this;
+    }
+    coreHwmProfile(value) {
+        this.options.coreHwm = {
+            ...this.options.coreHwm,
+            profile: coreHwmProfileValue(value)
+        };
+        return this;
+    }
+    applicationJobQueueProfile(value) {
+        this.options.applicationJobQueue = {
+            ...this.options.applicationJobQueue,
+            profile: value
+        };
+        return this;
+    }
+    maxQueuedApplicationJobs(value) {
+        this.options.applicationJobQueue = {
+            ...this.options.applicationJobQueue,
+            maxQueuedApplicationJobs: value
+        };
+        return this;
+    }
+    applicationJobQueuePauseThresholdPercent(value) {
+        this.options.applicationJobQueue = {
+            ...this.options.applicationJobQueue,
+            pauseThresholdPercent: value
+        };
+        return this;
+    }
+    applicationJobQueueResumeThresholdPercent(value) {
+        this.options.applicationJobQueue = {
+            ...this.options.applicationJobQueue,
+            resumeThresholdPercent: value
+        };
+        return this;
+    }
+}
+exports.DefaultInboundDispatchOptionsBuilder = DefaultInboundDispatchOptionsBuilder;
+function coreHwmProfileValue(value) {
+    switch (value) {
+        case Dispatch_1.ZLinkCoreHwmProfile.Compact: return zlink_1.AutoHwmProfile.Compact;
+        case Dispatch_1.ZLinkCoreHwmProfile.LowLatency: return zlink_1.AutoHwmProfile.LowLatency;
+        case Dispatch_1.ZLinkCoreHwmProfile.Balanced: return zlink_1.AutoHwmProfile.Balanced;
+        case Dispatch_1.ZLinkCoreHwmProfile.Throughput: return zlink_1.AutoHwmProfile.Throughput;
+        default: throw new TypeError('coreHwmProfile must be a supported profile.');
+    }
+}
+class DefaultLocationOptionsBuilder {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    ownerLeaseRenewIntervalMs(value) {
+        this.options.ownerLeaseRenewIntervalMs = value;
+        return this;
+    }
+    ownerLeaseTtlMs(value) {
+        this.options.ownerLeaseTtlMs = value;
+        return this;
+    }
+    pollingIntervalMs(value) {
+        this.options.pollingIntervalMs = value;
+        return this;
+    }
+    storeFailureGraceMs(value) {
+        this.options.storeFailureGraceMs = value;
+        return this;
+    }
+    ownerLeaseFencingMarginMs(value) {
+        this.options.ownerLeaseFencingMarginMs = value;
+        return this;
+    }
+    ownerLeaseRenewTimeoutMs(value) {
+        this.options.ownerLeaseRenewTimeoutMs = value;
+        return this;
+    }
+    routeCacheMaxAgeMs(value) {
+        this.options.routeCacheMaxAgeMs = value;
+        return this;
+    }
+    messageFollowDurationMs(value) {
+        this.options.messageFollowDurationMs = value;
+        return this;
+    }
+    sessionRelocationSealTimeoutMs(value) {
+        this.options.sessionRelocationSealTimeoutMs = value;
+        return this;
+    }
+    relocationCutoverWaitTimeoutMs(value) {
+        this.options.relocationCutoverWaitTimeoutMs = value;
+        return this;
+    }
+    relocationPayloadChunkLimitBytes(value) {
+        this.options.relocationPayloadChunkLimitBytes = value;
+        return this;
+    }
+    relocationInFlightPayloadBudgetBytes(value) {
+        this.options.relocationInFlightPayloadBudgetBytes = value;
+        return this;
+    }
+    relocationNodeInFlightPayloadBudgetBytes(value) {
+        this.options.relocationNodeInFlightPayloadBudgetBytes = value;
+        return this;
+    }
+}
+exports.DefaultLocationOptionsBuilder = DefaultLocationOptionsBuilder;
+function defaultDispatchOptions() {
+    return {
+        unhandled: {
+            request: Dispatch_1.ZLinkUnhandledDispatchAction.ReplyError,
+            send: Dispatch_1.ZLinkUnhandledDispatchAction.LogAndDrop,
+            publish: Dispatch_1.ZLinkUnhandledDispatchAction.LogAndDrop
+        },
+        diagnostics: {
+            messageFlow: 'errors',
+            sampleRate: 1,
+            includeMessageSizes: false
+        }
+    };
+}
+class DefaultFanoutChannelBuilder {
+    name;
+    channel;
+    subscriberMode;
+    constructor(name, channel) {
+        this.name = name;
+        this.channel = channel;
+    }
+    enablePublisher(endpointOrPort = 0) {
+        this.channel.publisher ??= {};
+        if (typeof endpointOrPort === 'string') {
+            requireRegistrationName(endpointOrPort, `Fanout channel '${this.name}' publisher endpoint`);
+            this.channel.publisher.bind = endpointOrPort;
+            this.channel.publisher.port = undefined;
+            return this;
+        }
+        this.channel.publisher.port = requireListenerPort(endpointOrPort, `Fanout channel '${this.name}' publisher port`);
+        this.updateBind();
+        return this;
+    }
+    setBindHost(bindHost) {
+        requireRegistrationName(bindHost, `Fanout channel '${this.name}' bind host`);
+        this.channel.publisher ??= {};
+        this.channel.publisher.bindHost = bindHost;
+        if (this.channel.publisher.port !== undefined)
+            this.updateBind();
+        return this;
+    }
+    setAdvertiseHost(advertiseHost) {
+        requireRegistrationName(advertiseHost, `Fanout channel '${this.name}' advertise host`);
+        this.channel.publisher ??= {};
+        this.channel.publisher.advertiseHost = advertiseHost;
+        return this;
+    }
+    routingId(routingId) {
+        rejectGeneratedRoutingId(this.channel.routingIdPrefix, this.name);
+        this.channel.routingId = routingId;
+        return this;
+    }
+    setRoutingIdPrefix(prefix) {
+        rejectFixedRoutingId(this.channel.routingId, this.name);
+        this.channel.routingIdPrefix = (0, RegistrationBuilderPolicy_1.validateRoutingIdPrefix)(prefix);
+        return this;
+    }
+    enableSubscriber(endpoint) {
+        this.selectSubscriberMode(endpoint === undefined ? 'automatic' : 'manual');
+        this.channel.subscriber ??= { manualConnections: [] };
+        if (endpoint !== undefined) {
+            this.channel.subscriber.manualConnections ??= [];
+            if (!this.channel.subscriber.manualConnections.includes(endpoint)) {
+                this.channel.subscriber.manualConnections.push(endpoint);
+            }
+        }
+        return this;
+    }
+    connect(endpoint) {
+        requireRegistrationName(endpoint, `Fanout channel '${this.name}' subscriber endpoint`);
+        this.selectSubscriberMode('manual');
+        this.channel.subscriber ??= { manualConnections: [] };
+        this.channel.subscriber.manualConnections ??= [];
+        if (!this.channel.subscriber.manualConnections.includes(endpoint)) {
+            this.channel.subscriber.manualConnections.push(endpoint);
+        }
+        return this;
+    }
+    subscriberConnections() {
+        this.selectSubscriberMode('manual');
+        this.channel.subscriber ??= { manualConnections: [] };
+        this.channel.subscriber.manualConnections ??= [];
+        return (0, RuntimeEndpointConnections_1.endpointConnections)(this.channel.subscriber, this.channel.subscriber.manualConnections);
+    }
+    selectSubscriberMode(mode) {
+        if (this.subscriberMode !== undefined && this.subscriberMode !== mode) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Fanout channel '${this.name}' cannot combine automatic and manual subscriber sources.`);
+        }
+        this.subscriberMode = mode;
+    }
+    updateBind() {
+        const publisher = this.channel.publisher;
+        if (publisher?.port === undefined)
+            return;
+        publisher.bind = tcpEndpoint(publisher.bindHost ?? '127.0.0.1', publisher.port);
+    }
+}
+class DefaultClientServerChannelRoleBuilder {
+    name;
+    channel;
+    constructor(name, channel) {
+        this.name = name;
+        this.channel = channel;
+    }
+    client() {
+        if (this.channel.client !== undefined) {
+            throw this.duplicate('Client');
+        }
+        this.channel.client = { manualConnections: [] };
+        return new DefaultClientServerChannelClientBuilder(this.name, this.channel.client);
+    }
+    server() {
+        if (this.channel.server !== undefined) {
+            throw this.duplicate('Server');
+        }
+        this.channel.server = {};
+        return new DefaultClientServerChannelServerBuilder(this.name, this.channel);
+    }
+    duplicate(role) {
+        return new ConfigurationException_1.ZLinkConfigurationException(`ClientServer channel '${this.name}' ${role} role is already registered.`);
+    }
+}
+class DefaultClientServerChannelClientBuilder {
+    name;
+    client;
+    constructor(name, client) {
+        this.name = name;
+        this.client = client;
+    }
+    connect(endpoint) {
+        requireRegistrationName(endpoint, `ClientServer channel '${this.name}' endpoint`);
+        this.client.manualConnections ??= [];
+        if (!this.client.manualConnections.includes(endpoint)) {
+            this.client.manualConnections.push(endpoint);
+        }
+        return this;
+    }
+}
+class DefaultClientServerChannelServerBuilder {
+    name;
+    channel;
+    constructor(name, channel) {
+        this.name = name;
+        this.channel = channel;
+    }
+    listen(port = 0) {
+        if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`ClientServer channel '${this.name}' port must be between 0 and 65535.`);
+        }
+        this.server.port = port;
+        this.updateBind();
+        return this;
+    }
+    setBindHost(bindHost) {
+        requireRegistrationName(bindHost, `ClientServer channel '${this.name}' bind host`);
+        this.server.bindHost = bindHost;
+        if (this.server.port !== undefined)
+            this.updateBind();
+        return this;
+    }
+    setAdvertiseHost(advertiseHost) {
+        requireRegistrationName(advertiseHost, `ClientServer channel '${this.name}' advertise host`);
+        this.server.advertiseHost = advertiseHost;
+        return this;
+    }
+    setWeight(weight) {
+        this.server.weight = requirePublicWeight(weight, `ClientServer channel '${this.name}' weight`);
+        return this;
+    }
+    addHandlerGroup(groupName) {
+        requireRegistrationName(groupName, `ClientServer channel '${this.name}' handler group`);
+        this.channel.handlerGroups ??= [];
+        if (!this.channel.handlerGroups.includes(groupName))
+            this.channel.handlerGroups.push(groupName);
+        return this;
+    }
+    addSendHandler(handlerType) {
+        this.channel.sendHandlers ??= [];
+        this.channel.sendHandlers.push({ packetName: handlerPacketName(handlerType), handlerType });
+        return this;
+    }
+    addRequestHandler(handlerType) {
+        this.channel.requestHandlers ??= [];
+        this.channel.requestHandlers.push({ packetName: handlerPacketName(handlerType), handlerType });
+        return this;
+    }
+    get server() {
+        return this.channel.server;
+    }
+    updateBind() {
+        const host = this.server.bindHost ?? '127.0.0.1';
+        const endpointHost = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+        this.server.bind = `tcp://${endpointHost}:${this.server.port ?? 0}`;
+    }
+}
+class DefaultStreamNodeBuilder {
+    streamNode;
+    constructor(streamNode) {
+        this.streamNode = streamNode;
+    }
+    bind(endpointOrPort = 0) {
+        if (typeof endpointOrPort === 'string') {
+            requireRegistrationName(endpointOrPort, 'STREAM bind endpoint');
+            this.streamNode.bind = endpointOrPort;
+            this.streamNode.port = undefined;
+            return this;
+        }
+        this.streamNode.port = requireListenerPort(endpointOrPort, 'STREAM bind port');
+        this.updateBind();
+        return this;
+    }
+    setBindHost(bindHost) {
+        requireRegistrationName(bindHost, 'STREAM bind host');
+        this.streamNode.bindHost = bindHost;
+        if (this.streamNode.port !== undefined)
+            this.updateBind();
+        return this;
+    }
+    setAdvertiseHost(advertiseHost) {
+        requireRegistrationName(advertiseHost, 'STREAM advertise host');
+        this.streamNode.advertiseHost = advertiseHost;
+        return this;
+    }
+    configureSocket() {
+        return this.streamNode;
+    }
+    enableActorDispatch() {
+        if (this.streamNode.actorDispatchEnabled === true) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('STREAM node actor dispatch is already enabled.');
+        }
+        this.streamNode.actorDispatchEnabled = true;
+        return this;
+    }
+    setTlsServer(certificatePath, keyPath, requireClientCertificate = false) {
+        this.streamNode.tlsServer = {
+            certificatePath,
+            keyPath,
+            requireClientCertificate
+        };
+        return this;
+    }
+    registerSession(sessionType) {
+        if (this.streamNode.session !== undefined) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('STREAM node cannot register more than one header stream session.');
+        }
+        this.streamNode.session = sessionType;
+        return this;
+    }
+    updateBind() {
+        if (this.streamNode.port === undefined)
+            return;
+        this.streamNode.bind = tcpEndpoint(this.streamNode.bindHost ?? '127.0.0.1', this.streamNode.port);
+    }
+}
+class DefaultStreamCompressionBuilder {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    useDefault() {
+        this.options.disabled = false;
+        this.options.codec = undefined;
+        return this;
+    }
+    useLz4() {
+        return this.useDefault();
+    }
+    use(codec) {
+        if (!(0, RegistrationNormalizers_1.isStreamCompressionCodec)(codec)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('STREAM compression codec must provide compress and decompress functions.');
+        }
+        this.options.disabled = false;
+        this.options.codec = codec;
+        return this;
+    }
+    disable() {
+        this.options.disabled = true;
+        this.options.codec = undefined;
+        return this;
+    }
+}
+exports.DefaultStreamCompressionBuilder = DefaultStreamCompressionBuilder;
+class DefaultSpotNodeBuilder {
+    name;
+    spotNode;
+    constructor(name, spotNode) {
+        this.name = name;
+        this.spotNode = spotNode;
+    }
+    routingId(routingId) {
+        rejectGeneratedRoutingId(this.spotNode.routingIdPrefix, this.name);
+        this.spotNode.routingId = routingId;
+        if (this.spotNode.router !== undefined) {
+            this.spotNode.router.routingId = routingId;
+        }
+        if (this.spotNode.pubSub !== undefined) {
+            this.spotNode.pubSub.routingId = routingId;
+        }
+        return this;
+    }
+    setRoutingIdPrefix(prefix) {
+        rejectFixedRoutingId(this.spotNode.routingId, this.name);
+        this.spotNode.routingIdPrefix = (0, RegistrationBuilderPolicy_1.validateRoutingIdPrefix)(prefix);
+        return this;
+    }
+    enableRouter(endpoint, routingId, connect) {
+        this.spotNode.router = {
+            ...(this.spotNode.router ?? {}),
+            bind: endpoint,
+            routingId: routingId ?? this.spotNode.routingId,
+            manualConnections: connect === undefined ? this.spotNode.router?.manualConnections : endpointList(connect)
+        };
+        return this;
+    }
+    connectRouter(peerRidOrEndpoint, endpoint) {
+        this.spotNode.router ??= { manualConnections: [] };
+        if (endpoint === undefined) {
+            this.spotNode.router.manualConnections ??= [];
+            this.spotNode.router.manualConnections.push(peerRidOrEndpoint);
+            return this;
+        }
+        this.spotNode.router.manualPeerConnections ??= [];
+        this.spotNode.router.manualPeerConnections.push({
+            peerRid: peerRidOrEndpoint,
+            endpoint
+        });
+        return this;
+    }
+    enablePubSub(endpoint, routingId, connect) {
+        this.spotNode.pubSub = {
+            ...(this.spotNode.pubSub ?? {}),
+            bind: endpoint,
+            routingId: routingId ?? this.spotNode.routingId,
+            manualConnections: connect === undefined ? this.spotNode.pubSub?.manualConnections : endpointList(connect)
+        };
+        return this;
+    }
+    connectPeerPub(endpoint) {
+        this.spotNode.pubSub ??= { manualConnections: [] };
+        this.spotNode.pubSub.manualConnections ??= [];
+        this.spotNode.pubSub.manualConnections.push(endpoint);
+        return this;
+    }
+}
+class DefaultMeshNodeBuilder {
+    name;
+    node;
+    spot;
+    constructor(name, node) {
+        this.name = name;
+        this.node = node;
+        this.spot = new DefaultSpotNodeBuilder(name, node);
+    }
+    channel(channelName) {
+        requireRegistrationName(channelName, 'Mesh channel');
+        this.node.meshChannels ??= {};
+        if (Object.prototype.hasOwnProperty.call(this.node.meshChannels, channelName)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Duplicate channel '${channelName}' in RouteMesh '${this.name}'.`);
+        }
+        const channel = {};
+        this.node.meshChannels[channelName] = channel;
+        return new DefaultMeshChannelBuilder(channel);
+    }
+    listen(endpointOrPort = 0) {
+        this.node.router ??= {};
+        if (typeof endpointOrPort === 'string') {
+            requireRegistrationName(endpointOrPort, 'RouteMesh listen endpoint');
+            this.node.router.bind = endpointOrPort;
+            this.node.router.port = undefined;
+            return this;
+        }
+        if (!Number.isInteger(endpointOrPort) || endpointOrPort < 0 || endpointOrPort > 65_535) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`RouteMesh '${this.name}' port must be between 0 and 65535.`);
+        }
+        this.node.router.port = endpointOrPort;
+        this.updateBind();
+        return this;
+    }
+    setBindHost(bindHost) {
+        requireRegistrationName(bindHost, `RouteMesh '${this.name}' bind host`);
+        this.node.router ??= {};
+        this.node.router.bindHost = bindHost;
+        if (this.node.router.port !== undefined)
+            this.updateBind();
+        return this;
+    }
+    setAdvertiseHost(advertiseHost) {
+        requireRegistrationName(advertiseHost, `RouteMesh '${this.name}' advertise host`);
+        this.node.router ??= {};
+        this.node.router.advertiseHost = advertiseHost;
+        return this;
+    }
+    routingId(routingId) {
+        this.spot.routingId(routingId);
+        return this;
+    }
+    setRoutingIdPrefix(prefix) {
+        this.spot.setRoutingIdPrefix(prefix);
+        return this;
+    }
+    setPlacementWeight(weight) {
+        this.node.placementWeight = requirePublicWeight(weight, 'Placement weight');
+        return this;
+    }
+    setActorLimit(limit) {
+        this.node.actorLimit = requireCapacity(limit, 'Actor limit');
+        return this;
+    }
+    setSpotLimit(limit) {
+        this.node.spotLimit = requireCapacity(limit, 'Spot limit');
+        return this;
+    }
+    setActivationConcurrency(limit) {
+        this.node.activationConcurrencyLimit = requirePositiveCapacity(limit, 'Activation concurrency limit');
+        return this;
+    }
+    setInstanceSpotIdleTimeout(timeoutMs) {
+        this.node.instanceSpotIdleTimeoutMs = requireNonNegativeSafeInteger(timeoutMs, 'Instance Spot idle timeout');
+        return this;
+    }
+    configureRouterSocket() {
+        this.node.router ??= {};
+        return this.node.router;
+    }
+    configureSpotPublisher() {
+        this.node.publisherConfig ??= {};
+        return this.node.publisherConfig;
+    }
+    peerConnections() {
+        this.node.router ??= {};
+        return new DefaultMeshPeerConnections(this.node.router);
+    }
+    setDefaultRequestTimeout(timeoutMs) {
+        this.node.requestTimeoutMs = (0, RegistrationNormalizers_1.normalizeOptionalPositiveInteger)(timeoutMs, `RouteMesh '${this.name}' default request timeout`);
+        return this;
+    }
+    objects() {
+        return new DefaultMeshObjectRoleBuilder(this.name, this.node);
+    }
+    addRouteSendHandler(handlerType) {
+        this.node.routeSendHandlers ??= [];
+        this.node.routeSendHandlers.push({ packetName: handlerPacketName(handlerType), handlerType });
+        return this;
+    }
+    addRouteRequestHandler(handlerType) {
+        this.node.routeRequestHandlers ??= [];
+        this.node.routeRequestHandlers.push({ packetName: handlerPacketName(handlerType), handlerType });
+        return this;
+    }
+    updateBind() {
+        const router = this.node.router;
+        if (router?.port === undefined)
+            return;
+        const bindHost = router.bindHost ?? '127.0.0.1';
+        const host = bindHost.includes(':') && !bindHost.startsWith('[')
+            ? `[${bindHost}]`
+            : bindHost;
+        router.bind = `tcp://${host}:${router.port}`;
+    }
+}
+class DefaultMeshObjectRoleBuilder {
+    meshName;
+    node;
+    constructor(meshName, node) {
+        this.meshName = meshName;
+        this.node = node;
+    }
+    client() {
+        this.node.objectRole = 'client';
+        return {};
+    }
+    server() {
+        this.node.objectRole = 'server';
+        return new DefaultMeshObjectServerBuilder(this.meshName, this.node);
+    }
+}
+class DefaultFactoryBuilder {
+    relocation;
+    sealed = false;
+    disable() {
+        this.select({ kind: 'disabled' });
+    }
+    recreate() {
+        this.select({ kind: 'recreate' });
+    }
+    preserve(adapterType) {
+        if (typeof adapterType !== 'function') {
+            throw new ConfigurationException_1.ZLinkConfigurationException('PreserveStateWith relocation requires an adapter type.');
+        }
+        this.select({ kind: 'snapshot', adapterType });
+    }
+    relocationConfiguration() {
+        if (this.relocation === undefined) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('Factory configure callback must select exactly one relocation policy.');
+        }
+        return this.relocation;
+    }
+    seal() {
+        this.sealed = true;
+    }
+    assertMutable() {
+        if (this.sealed) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('Factory builder cannot be changed after the configure callback returns.');
+        }
+    }
+    select(relocation) {
+        this.assertMutable();
+        if (this.relocation !== undefined) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('Factory configure callback must select exactly one relocation policy.');
+        }
+        this.relocation = relocation;
+    }
+}
+class DefaultActorFactoryBuilder extends DefaultFactoryBuilder {
+    disableRelocation() {
+        this.disable();
+    }
+    recreateOnRelocation() {
+        this.recreate();
+    }
+    preserveStateWith(adapterType) {
+        this.preserve(adapterType);
+    }
+    build() {
+        return {
+            options: {},
+            relocation: this.relocationConfiguration()
+        };
+    }
+}
+class DefaultUserSpotFactoryBuilder extends DefaultFactoryBuilder {
+    stableTypeLimitValue;
+    executionModeValue = ObjectRoles_1.ZLinkUserSpotExecutionMode.SpotWide;
+    relocationCoordinationModeValue = ObjectRoles_1.ZLinkSpotRelocationCoordinationMode.FrameworkManaged;
+    stableTypeLimit(limit) {
+        this.assertMutable();
+        validateStableTypeLimit(limit);
+        this.stableTypeLimitValue = limit;
+        return this;
+    }
+    executionMode(mode) {
+        this.assertMutable();
+        this.executionModeValue = mode;
+        return this;
+    }
+    relocationCoordinationMode(mode) {
+        this.assertMutable();
+        this.relocationCoordinationModeValue = mode;
+        return this;
+    }
+    disableRelocation() {
+        this.disable();
+    }
+    recreateOnRelocation() {
+        this.recreate();
+    }
+    preserveStateWith(adapterType) {
+        this.preserve(adapterType);
+    }
+    build() {
+        const relocation = this.relocationConfiguration();
+        const options = {
+            stableTypeLimit: this.stableTypeLimitValue,
+            executionMode: this.executionModeValue,
+            relocationCoordinationMode: this.relocationCoordinationModeValue
+        };
+        validateUserSpotFactoryOptions(options);
+        if (options.executionMode === ObjectRoles_1.ZLinkUserSpotExecutionMode.PerActor
+            && relocation.kind !== 'recreate') {
+            throw new ConfigurationException_1.ZLinkConfigurationException('PerActor User Spots require RecreateOnRelocation.');
+        }
+        return { options, relocation };
+    }
+}
+class DefaultInstanceSpotFactoryBuilder extends DefaultFactoryBuilder {
+    stableTypeLimitValue;
+    stableTypeLimit(limit) {
+        this.assertMutable();
+        validateStableTypeLimit(limit);
+        this.stableTypeLimitValue = limit;
+        return this;
+    }
+    disableRelocation() {
+        this.disable();
+    }
+    recreateOnRelocation() {
+        this.recreate();
+    }
+    preserveStateWith(adapterType) {
+        this.preserve(adapterType);
+    }
+    build() {
+        return {
+            options: { stableTypeLimit: this.stableTypeLimitValue },
+            relocation: this.relocationConfiguration()
+        };
+    }
+}
+class DefaultMeshObjectServerBuilder {
+    meshName;
+    node;
+    constructor(meshName, node) {
+        this.meshName = meshName;
+        this.node = node;
+    }
+    addEntrySpot(entrySpotType) {
+        (0, RegistrationBuilderPolicy_1.registerEntrySpot)(this.node, entrySpotType);
+        return this;
+    }
+    addSpotFactory(spotType, implementation, configure) {
+        const stableType = requireStableObjectType(spotType, 'User Spot type');
+        requireFactoryConfigure(configure);
+        const factory = new DefaultUserSpotFactoryBuilder();
+        let built;
+        try {
+            configure(factory);
+            built = factory.build();
+        }
+        finally {
+            factory.seal();
+        }
+        const { options, relocation } = built;
+        validateUserSpotFactoryOptions(options);
+        this.node.spotFactoryRegistrations ??= {};
+        rejectDuplicateObjectType(this.node.spotFactoryRegistrations, stableType, this.meshName);
+        this.node.spotFactoryRegistrations[stableType] = {
+            implementation,
+            options: {
+                ...options,
+                executionMode: options.executionMode
+            },
+            relocation
+        };
+        (0, RegistrationBuilderPolicy_1.registerSpotFactory)(this.node, implementation);
+        return this;
+    }
+    addInstanceSpotFactory(instanceSpotType, implementation, configure) {
+        const stableType = requireStableObjectType(instanceSpotType, 'Instance Spot type');
+        requireFactoryConfigure(configure);
+        const factory = new DefaultInstanceSpotFactoryBuilder();
+        let built;
+        try {
+            configure(factory);
+            built = factory.build();
+        }
+        finally {
+            factory.seal();
+        }
+        const { options, relocation } = built;
+        validateStableTypeLimit(options.stableTypeLimit);
+        this.node.instanceSpotFactories ??= {};
+        if (Object.hasOwn(this.node.instanceSpotFactories, stableType)) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Duplicate Instance Spot factory '${stableType}' on RouteMesh '${this.meshName}'.`);
+        }
+        this.node.instanceSpotFactories[stableType] = implementation;
+        this.node.instanceSpotFactoryRegistrations ??= {};
+        this.node.instanceSpotFactoryRegistrations[stableType] = {
+            implementation,
+            options,
+            relocation
+        };
+        return this;
+    }
+    addActorFactory(actorType, implementation, configure) {
+        const stableType = requireStableObjectType(actorType, 'Actor type');
+        requireFactoryConfigure(configure);
+        const factory = new DefaultActorFactoryBuilder();
+        let built;
+        try {
+            configure(factory);
+            built = factory.build();
+        }
+        finally {
+            factory.seal();
+        }
+        const { options, relocation } = built;
+        this.node.actorFactories = (0, RegistrationNormalizers_1.typeMapToRecord)(this.node.actorFactories);
+        (0, RegistrationBuilderPolicy_1.registerActorFactory)(this.node, stableType, implementation);
+        this.node.actorFactoryRegistrations ??= {};
+        this.node.actorFactoryRegistrations[stableType] = {
+            implementation,
+            options,
+            relocation
+        };
+        return this;
+    }
+}
+class DefaultMeshChannelBuilder {
+    channel;
+    constructor(channel) {
+        this.channel = channel;
+    }
+    client() {
+        if (this.channel.client === true || this.channel.server === true) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('RouteMesh channel must register exactly one role; client() and server() cannot both be used or called twice.');
+        }
+        this.channel.client = true;
+        return new DefaultMeshChannelClientBuilder();
+    }
+    server() {
+        if (this.channel.client === true || this.channel.server === true) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('RouteMesh channel must register exactly one role; client() and server() cannot both be used or called twice.');
+        }
+        this.channel.server = true;
+        return new DefaultMeshChannelServerBuilder(this.channel);
+    }
+}
+class DefaultMeshChannelClientBuilder {
+}
+class DefaultMeshChannelServerBuilder {
+    channel;
+    constructor(channel) {
+        this.channel = channel;
+    }
+    setWeight(weight) {
+        this.channel.weight = requirePublicWeight(weight, 'Mesh channel weight');
+        return this;
+    }
+    addHandlerGroup(groupName) {
+        requireRegistrationName(groupName, 'Mesh channel handler group');
+        this.channel.handlerGroups ??= [];
+        if (!this.channel.handlerGroups.includes(groupName))
+            this.channel.handlerGroups.push(groupName);
+        return this;
+    }
+    addSendHandler(handlerType) {
+        this.channel.sendHandlers ??= [];
+        this.channel.sendHandlers.push({ packetName: handlerPacketName(handlerType), handlerType });
+        return this;
+    }
+    addRequestHandler(handlerType) {
+        this.channel.requestHandlers ??= [];
+        this.channel.requestHandlers.push({ packetName: handlerPacketName(handlerType), handlerType });
+        return this;
+    }
+}
+class DefaultMeshPeerConnections {
+    router;
+    constructor(router) {
+        this.router = router;
+    }
+    connect(expectedRoutingIdOrEndpoint, endpoint) {
+        if (endpoint === undefined) {
+            requireRegistrationName(expectedRoutingIdOrEndpoint, 'Mesh peer endpoint');
+            const normalizedEndpoint = (0, EndpointNotation_1.normalizeEndpoint)(expectedRoutingIdOrEndpoint);
+            this.router.manualConnections ??= [];
+            if (!this.router.manualConnections.includes(normalizedEndpoint)) {
+                this.router.manualConnections.push(normalizedEndpoint);
+            }
+            return;
+        }
+        requireRegistrationName(endpoint, 'Mesh peer endpoint');
+        const normalizedEndpoint = (0, EndpointNotation_1.normalizeEndpoint)(endpoint);
+        this.router.manualPeerConnections ??= [];
+        if (!this.router.manualPeerConnections.some((peer) => peer.endpoint === normalizedEndpoint && peer.peerRid === expectedRoutingIdOrEndpoint)) {
+            this.router.manualPeerConnections.push({ peerRid: expectedRoutingIdOrEndpoint, endpoint: normalizedEndpoint });
+        }
+    }
+    disconnect(endpoint) {
+        // The public connect/disconnect-by-endpoint API accepts any equivalent
+        // notation for an endpoint already connected under its canonical form
+        // (see connect() above); without normalizing here, disconnect() with a
+        // differently-cased or -formatted endpoint would silently no-op.
+        const normalizedEndpoint = (0, EndpointNotation_1.normalizeEndpoint)(endpoint);
+        this.router.manualConnections = this.router.manualConnections?.filter((value) => value !== normalizedEndpoint);
+        this.router.manualPeerConnections = this.router.manualPeerConnections?.filter((value) => value.endpoint !== normalizedEndpoint);
+    }
+    listConnections() {
+        return [
+            ...(this.router.manualConnections ?? []).map((endpoint) => ({ endpoint })),
+            ...(this.router.manualPeerConnections ?? []).map((peer) => ({
+                endpoint: peer.endpoint,
+                expectedRoutingId: peer.peerRid
+            }))
+        ];
+    }
+}
+function endpointList(endpoint) {
+    return typeof endpoint === 'string' ? [endpoint] : [...endpoint];
+}
+function requireStableObjectType(value, label) {
+    const byteLength = Buffer.byteLength(value, 'utf8');
+    if (byteLength < 1 || byteLength > 255 || value.includes('\0')) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must contain 1..255 UTF-8 bytes and no NUL.`);
+    }
+    return value;
+}
+function requirePositiveCapacity(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0 || value > 0x7fff_ffff) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must be an integer in 1..2147483647.`);
+    }
+    return value;
+}
+function requireCapacity(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 0x7fff_ffff) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must be an integer in 0..2147483647.`);
+    }
+    return value;
+}
+function requireNonNegativeSafeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must be a non-negative safe integer.`);
+    }
+    return value;
+}
+function requirePublicWeight(value, label) {
+    if (!Number.isInteger(value) || value < 0 || value > 10_000) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must be an integer in 0..10000.`);
+    }
+    return value;
+}
+function requireFactoryConfigure(configure) {
+    if (typeof configure !== 'function') {
+        throw new ConfigurationException_1.ZLinkConfigurationException('Object factory requires a configure callback.');
+    }
+}
+function validateUserSpotFactoryOptions(options) {
+    validateStableTypeLimit(options?.stableTypeLimit);
+    const executionMode = options?.executionMode;
+    if (executionMode !== undefined
+        && executionMode !== ObjectRoles_1.ZLinkUserSpotExecutionMode.SpotWide
+        && executionMode !== ObjectRoles_1.ZLinkUserSpotExecutionMode.PerActor) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('User Spot executionMode is invalid.');
+    }
+    if (options?.relocationCoordinationMode !== ObjectRoles_1.ZLinkSpotRelocationCoordinationMode.FrameworkManaged
+        && options?.relocationCoordinationMode !== ObjectRoles_1.ZLinkSpotRelocationCoordinationMode.ApplicationSignaled) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('User Spot relocationCoordinationMode is invalid.');
+    }
+    if (options.executionMode === ObjectRoles_1.ZLinkUserSpotExecutionMode.PerActor
+        && options.relocationCoordinationMode === ObjectRoles_1.ZLinkSpotRelocationCoordinationMode.ApplicationSignaled) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('ApplicationSignaled relocation coordination mode is valid only for SpotWide User Spots.');
+    }
+}
+function validateStableTypeLimit(value) {
+    if (value !== undefined
+        && (!Number.isInteger(value) || value < 0 || value > 2_147_483_647)) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('stableTypeLimit must be an integer from 0 through 2147483647.');
+    }
+}
+function rejectDuplicateObjectType(registrations, stableType, meshName) {
+    if (Object.hasOwn(registrations, stableType)) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`Duplicate object factory '${stableType}' on RouteMesh '${meshName}'.`);
+    }
+}
+function handlerPacketName(handlerType) {
+    return (0, Attributes_1.readZLinkDecoratorMetadata)(handlerType)
+        .find((metadata) => metadata.kind === 'packet' && metadata.packetName !== undefined)
+        ?.packetName ?? handlerType.name;
+}
+function requireRegistrationName(value, label) {
+    if (value.trim().length === 0 || value.trim() !== value) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must not be empty or padded.`);
+    }
+}
+function requireListenerPort(value, label) {
+    if (!Number.isInteger(value) || value < 0 || value > 65_535) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`${label} must be between 0 and 65535.`);
+    }
+    return value;
+}
+function tcpEndpoint(host, port) {
+    const endpointHost = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+    return `tcp://${endpointHost}:${port}`;
+}
+function rejectFixedRoutingId(routingId, memberName) {
+    if (routingId !== undefined) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`Mesh member '${memberName}' cannot combine a fixed routing id with a generated prefix.`);
+    }
+}
+function rejectGeneratedRoutingId(prefix, memberName) {
+    if (prefix !== undefined) {
+        throw new ConfigurationException_1.ZLinkConfigurationException(`Mesh member '${memberName}' cannot combine a generated routing-id prefix with a fixed id.`);
+    }
+}