@naylence/runtime 0.3.4 → 0.3.5-test.0

package/dist/esm/src/naylence/fame/sentinel/sentinel.js

@@ -0,0 +1,972 @@
+import { DeliveryOriginType, FameAddress, FameResponseType, FlowFlags, parseAddress, formatAddress, generateId, localDeliveryContext, withFabric,
+// type NodeAttachAckFrame,
+ } from '@naylence/core';
+import { currentTraceId } from '../util/envelope-context.js';
+import { FameNode } from '../node/node.js';
+import { createPersistentRouteStore, getDefaultRouteStore, } from './store/route-store.js';
+import { RouteManager, } from './route-manager.js';
+import { CompositeRoutingPolicy } from './composite-routing-policy.js';
+import { CapabilityAwareRoutingPolicy } from './capability-aware-routing-policy.js';
+import { HybridPathRoutingPolicy } from './hybrid-path-routing-policy.js';
+import { NodeAttachFrameHandler } from './node-attach-frame-handler.js';
+import { AddressBindFrameHandler } from './address-bind-frame-handler.js';
+import { NodeHeartbeatFrameHandler } from './node-heartbeat-frame-handler.js';
+import { CapabilityFrameHandler } from './capability-frame-handler.js';
+import { CreditUpdateFrameHandler } from './credit-update-frame-handler.js';
+import { LogLevel, basicConfig, getLogger, summarizeEnvelope, } from '../util/logging.js';
+// import { TaskSpawner } from "../util/task-spawner.js";
+import { delay } from '../util/task-utils.js';
+import { AsyncEvent } from '../util/async-event.js';
+import { AsyncLock } from '../util/lock.js';
+import { createResource } from '../connector/connector-factory.js';
+import { UpstreamSessionManager } from '../node/upstream-session-manager.js';
+import { emitDeliveryNack, RouterState } from './router.js';
+const logger = getLogger('naylence.fame.sentinel.sentinel');
+const ALLOWED_BEFORE_ATTACH = new Set(['NodeAttach']);
+const SYSTEM_INBOX = '__sys__';
+const RESERVED_UPSTREAM_ADDRESS_NAMES = new Set(['__sys__', '__rpc__']);
+const DEFAULT_BINDING_ACK_TIMEOUT_MS = 20000;
+const DEFAULT_ATTACH_TIMEOUT_SEC = 5;
+const DEFAULT_CONNECTOR_CLEANUP_DELAY_MS = 200;
+function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+function computePhysicalSegments(path) {
+    return path.replace(/^\/+/u, '').split('/').filter(Boolean);
+}
+function normalizeSentinelOptions(rawOptions) {
+    const normalized = {
+        ...(rawOptions ?? {}),
+    };
+    const assignAlias = (targetKey, aliasKeys) => {
+        if (normalized[targetKey] === undefined) {
+            for (const alias of aliasKeys) {
+                if (alias in normalized) {
+                    normalized[targetKey] = normalized[alias];
+                    break;
+                }
+            }
+        }
+        for (const alias of aliasKeys) {
+            if (alias in normalized) {
+                delete normalized[alias];
+            }
+        }
+    };
+    assignAlias('routeStore', ['route_store']);
+    assignAlias('routingPolicy', ['routing_policy']);
+    assignAlias('attachTimeoutSec', ['attach_timeout_sec']);
+    assignAlias('maxAttachTtlSec', ['max_attach_ttl_sec']);
+    assignAlias('bindingAckTimeoutMs', ['binding_ack_timeout_ms']);
+    assignAlias('attachmentKeyValidator', ['attachment_key_validator']);
+    assignAlias('stickinessManager', ['stickiness_manager']);
+    assignAlias('requestedLogicals', ['requested_logicals']);
+    assignAlias('attachClient', ['attach_client']);
+    assignAlias('cleanupDelayMs', ['cleanup_delay_ms']);
+    assignAlias('rebindOnAttach', ['rebind_on_attach']);
+    return normalized;
+}
+function normalizeOriginConnectorOptions(rawOptions) {
+    const normalized = { ...rawOptions };
+    const assignAlias = (targetKey, aliasKeys) => {
+        if (normalized[targetKey] === undefined) {
+            for (const alias of aliasKeys) {
+                if (alias in normalized) {
+                    normalized[targetKey] = normalized[alias];
+                    break;
+                }
+            }
+        }
+        for (const alias of aliasKeys) {
+            if (alias in normalized) {
+                delete normalized[alias];
+            }
+        }
+    };
+    assignAlias('originType', ['origin_type']);
+    assignAlias('systemId', ['system_id']);
+    assignAlias('connectorConfig', ['connector_config']);
+    assignAlias('authorization', ['authorization_context']);
+    return normalized;
+}
+export class Sentinel extends FameNode {
+    constructor(options = {}) {
+        const normalizedOptions = normalizeSentinelOptions(options);
+        super(normalizedOptions);
+        this.pendingBinds = new Map();
+        this.pendingLock = new AsyncLock();
+        this.peerSessionManagers = new Map();
+        this.upstreamConnectorRef = null;
+        this.routingEpochValue = generateId();
+        this.isPreparedToStop = false;
+        const opts = normalizedOptions;
+        let routeStore;
+        if (opts.routeStore) {
+            routeStore = opts.routeStore;
+        }
+        else {
+            try {
+                routeStore = createPersistentRouteStore(this.storageProvider);
+            }
+            catch (error) {
+                logger.warning('persistent_route_store_unavailable', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                routeStore = getDefaultRouteStore();
+            }
+        }
+        const cleanupDelayMs = Number.isFinite(opts.cleanupDelayMs ?? NaN)
+            ? Math.max(0, Number(opts.cleanupDelayMs))
+            : DEFAULT_CONNECTOR_CLEANUP_DELAY_MS;
+        this.cleanupDelayMs = cleanupDelayMs;
+        const attachTimeoutSec = opts.attachTimeoutSec ?? DEFAULT_ATTACH_TIMEOUT_SEC;
+        this.attachTimeoutMs =
+            typeof attachTimeoutSec === 'number' && Number.isFinite(attachTimeoutSec)
+                ? Math.max(0, attachTimeoutSec * 1000)
+                : null;
+        const rebindOnAttach = opts.rebindOnAttach ?? false;
+        this.routeManager = new RouteManager({
+            deliver: (envelope, context) => this.deliver(envelope, context),
+            routeStore,
+            getId: () => this.id,
+            cleanupDelayMs: this.cleanupDelayMs,
+        });
+        this.rebindOnAttach = rebindOnAttach;
+        this._route_manager =
+            this.routeManager;
+        this.routingPolicy =
+            opts.routingPolicy ??
+                new CompositeRoutingPolicy([
+                    new CapabilityAwareRoutingPolicy(),
+                    new HybridPathRoutingPolicy(),
+                ]);
+        this.attachmentKeyValidator = opts.attachmentKeyValidator ?? null;
+        this.stickinessManager = opts.stickinessManager ?? null;
+        this.peers = opts.peers ?? [];
+        this.ackTimeoutMs =
+            opts.bindingAckTimeoutMs ?? DEFAULT_BINDING_ACK_TIMEOUT_MS;
+        this.maxAttachTtlSec = opts.maxAttachTtlSec ?? null;
+        this.requestedLogicals = opts.requestedLogicals ?? [];
+        this.attachClient = opts.attachClient ?? null;
+        this.nodeAttachFrameHandler = new NodeAttachFrameHandler({
+            routingNode: this,
+            routeManager: this.routeManager,
+            attachmentKeyValidator: this.attachmentKeyValidator,
+            stickinessManager: this.stickinessManager,
+            maxTtlSec: this.maxAttachTtlSec,
+        });
+        this.nodeHeartbeatFrameHandler = new NodeHeartbeatFrameHandler({
+            routingNode: this,
+        });
+        this.addressBindFrameHandler = new AddressBindFrameHandler({
+            routingNode: this,
+            routeManager: this.routeManager,
+            upstreamConnector: () => this.upstreamConnector,
+        });
+        this.capabilityFrameHandler = new CapabilityFrameHandler({
+            routingNode: this,
+            routeManager: this.routeManager,
+            upstreamConnector: () => this.upstreamConnector,
+        });
+        this.creditUpdateFrameHandler = new CreditUpdateFrameHandler({
+            routeManager: this.routeManager,
+        });
+        const authorizer = this.securityManager?.authorizer ?? null;
+        if (!authorizer) {
+            throw new Error('Sentinel nodes require a security manager with an authorizer');
+        }
+        if (this.rebindOnAttach) {
+            this.addEventListener({
+                priority: 500,
+                onNodeAttachToUpstream: async () => {
+                    await this.propagateAddressBindingsUpstream();
+                },
+            });
+        }
+    }
+    get routingEpoch() {
+        return this.routingEpochValue;
+    }
+    bumpRoutingEpoch() {
+        const previousEpoch = this.routingEpochValue;
+        this.routingEpochValue = generateId();
+        logger.debug('routing_epoch_bumped', {
+            previous_epoch: previousEpoch,
+            new_epoch: this.routingEpochValue,
+        });
+    }
+    get upstreamConnector() {
+        if (this.upstreamConnectorRef) {
+            return this.upstreamConnectorRef;
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(FameNode.prototype, 'upstreamConnector');
+        const baseGetter = descriptor?.get;
+        return baseGetter ? baseGetter.call(this) : null;
+    }
+    setUpstreamConnector(connector) {
+        this.upstreamConnectorRef = connector;
+    }
+    async start() {
+        this.isPreparedToStop = false;
+        await super.start();
+        await this.routeManager.start();
+        await this.connectToPeers();
+    }
+    async prepareToStop() {
+        if (this.isPreparedToStop) {
+            return;
+        }
+        super.prepareToStop();
+        this.isPreparedToStop = true;
+    }
+    async stop() {
+        await this.prepareToStop();
+        // await this.lifecycleTasks.shutdownTasks({ cancelHanging: true }).catch(() => undefined);
+        for (const manager of this.peerSessionManagers.values()) {
+            await manager.stop().catch(() => undefined);
+        }
+        this.peerSessionManagers.clear();
+        await super.stop();
+        await this.routeManager.stop();
+    }
+    async deliver(envelope, context) {
+        const processedEnvelope = await this.dispatchEnvelopeEvent('onDeliver', this, envelope, context);
+        if (!processedEnvelope) {
+            return;
+        }
+        const frameType = processedEnvelope.frame?.type ?? null;
+        if (frameType &&
+            [
+                'AddressBindAck',
+                'AddressUnbindAck',
+                'CapabilityAdvertiseAck',
+                'CapabilityWithdrawAck',
+            ].includes(frameType)) {
+            await this.deliveryTracker.onEnvelopeDelivered(SYSTEM_INBOX, processedEnvelope, context);
+            if (frameType === 'AddressBindAck') {
+                const frame = processedEnvelope.frame;
+                await this.resolvePendingBind(processedEnvelope, frame?.ok ?? true, frame?.reason ?? null);
+            }
+            return;
+        }
+        if (!context || context.originType !== DeliveryOriginType.LOCAL) {
+            if (frameType === 'NodeAttach') {
+                await this.nodeAttachFrameHandler.acceptNodeAttach(processedEnvelope, context);
+            }
+            else if (frameType === 'AddressBind') {
+                await this.addressBindFrameHandler.acceptAddressBind(processedEnvelope, context);
+            }
+            else if (frameType === 'AddressUnbind') {
+                await this.addressBindFrameHandler.acceptAddressUnbind(processedEnvelope, context);
+            }
+            else if (frameType === 'CapabilityAdvertise') {
+                await this.capabilityFrameHandler.acceptCapabilityAdvertise(processedEnvelope, context);
+            }
+            else if (frameType === 'CapabilityWithdraw') {
+                await this.capabilityFrameHandler.acceptCapabilityWithdraw(processedEnvelope, context);
+            }
+            else if (frameType === 'CreditUpdate') {
+                await this.creditUpdateFrameHandler.acceptCreditUpdate(processedEnvelope, context);
+            }
+            else if (frameType === 'NodeHeartbeat') {
+                await this.nodeHeartbeatFrameHandler.acceptNodeHeartbeat(processedEnvelope, context);
+            }
+        }
+        const state = this.buildRouterState();
+        const action = await this.routingPolicy.decide(processedEnvelope, state, context);
+        await action.execute(processedEnvelope, this, state, context);
+    }
+    async forwardToRoute(nextSegment, envelope, context) {
+        if (this.originMatches(context, nextSegment, DeliveryOriginType.DOWNSTREAM)) {
+            logger.debug('downstream_loop_detected', {
+                envp_id: envelope.id,
+                segment: nextSegment,
+            });
+        }
+        let processed = null;
+        try {
+            processed = await this.dispatchEnvelopeEvent('onForwardToRoute', this, nextSegment, envelope, context);
+            if (!processed) {
+                return;
+            }
+            const connector = this.routeManager.downstreamRoutes.get(nextSegment);
+            if (!connector) {
+                logger.warning('no_route_for_child_segment', { segment: nextSegment });
+                await this.emitDeliveryNack(processed, {
+                    code: 'CHILD_UNREACHABLE',
+                    context: context ?? null,
+                });
+                return;
+            }
+            logger.debug('forwarding_downstream', {
+                ...summarizeEnvelope(processed, ''),
+                route: nextSegment,
+            });
+            await connector.send(processed);
+            this.trackFlowRoute(processed, connector);
+            this.maybeForgetFlow(processed);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            await this.dispatchEnvelopeEvent('onForwardToRouteComplete', this, nextSegment, processed ?? envelope, undefined, err, context).catch(() => undefined);
+            throw err;
+        }
+        await this.dispatchEnvelopeEvent('onForwardToRouteComplete', this, nextSegment, processed ?? envelope, undefined, undefined, context).catch(() => undefined);
+    }
+    async forwardToPeer(peerSegment, envelope, context) {
+        if (this.originMatches(context, peerSegment, DeliveryOriginType.PEER)) {
+            logger.debug('peer_loop_detected', {
+                envp_id: envelope.id,
+                segment: peerSegment,
+            });
+        }
+        const processed = await this.dispatchEnvelopeEvent('onForwardToPeer', this, peerSegment, envelope, context);
+        if (!processed) {
+            return;
+        }
+        const connector = this.routeManager._peer_routes.get(peerSegment);
+        if (!connector) {
+            logger.warning('no_route_for_peer_segment', {
+                peer_segment: peerSegment,
+            });
+            await this.emitDeliveryNack(processed, {
+                code: 'PEER_UNREACHABLE',
+                context: context ?? null,
+            });
+            return;
+        }
+        await connector.send(processed);
+        await this.dispatchEnvelopeEvent('onForwardToPeerComplete', this, peerSegment, processed, undefined, undefined, context).catch(() => undefined);
+        this.trackFlowRoute(processed, connector);
+        this.maybeForgetFlow(processed);
+    }
+    async forwardToPeers(envelope, peers, excludePeers, context) {
+        const processed = await this.dispatchEnvelopeEvent('onForwardToPeers', this, envelope, peers ?? undefined, excludePeers ?? undefined, context);
+        if (!processed) {
+            return;
+        }
+        const availablePeers = new Set(peers ?? Array.from(this.routeManager._peer_routes.keys()));
+        if (excludePeers) {
+            for (const peer of excludePeers) {
+                availablePeers.delete(peer);
+            }
+        }
+        for (const peerId of availablePeers) {
+            const connector = this.routeManager._peer_routes.get(peerId);
+            if (!connector) {
+                throw new Error(`No route for peer segment '${peerId}'`);
+            }
+            const forwarded = await this.dispatchEnvelopeEvent('onForwardToPeer', this, peerId, envelope, context);
+            if (!forwarded) {
+                continue;
+            }
+            await connector.send(forwarded);
+            await this.dispatchEnvelopeEvent('onForwardToPeerComplete', this, peerId, forwarded, undefined, undefined, context).catch(() => undefined);
+            this.trackFlowRoute(forwarded, connector);
+            this.maybeForgetFlow(forwarded);
+        }
+        await this.dispatchEnvelopeEvent('onForwardToPeersComplete', this, processed, peers ?? undefined, excludePeers ?? undefined, undefined, undefined, context).catch(() => undefined);
+    }
+    async forwardUpstream(envelope, context) {
+        if (context?.originType === DeliveryOriginType.UPSTREAM) {
+            logger.debug('skipping_forward_upstream', {
+                envp_id: envelope.id,
+                origin_type: context.originType,
+            });
+            return;
+        }
+        let processed = null;
+        try {
+            processed = await this.dispatchEnvelopeEvent('onForwardUpstream', this, envelope, context);
+            if (!processed) {
+                return;
+            }
+            const connector = this.upstreamConnector;
+            const sessionManager = this._sessionManager;
+            const upstreamManager = sessionManager &&
+                typeof sessionManager.send === 'function'
+                ? sessionManager
+                : null;
+            if (!connector || !upstreamManager) {
+                await this.dispatchEnvelopeEvent('onForwardUpstreamComplete', this, processed, undefined, undefined, context).catch(() => undefined);
+                return;
+            }
+            await upstreamManager.send(processed);
+            this.trackFlowRoute(processed, connector);
+            this.maybeForgetFlow(processed);
+            await this.dispatchEnvelopeEvent('onForwardUpstreamComplete', this, processed, undefined, undefined, context).catch(() => undefined);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            await this.dispatchEnvelopeEvent('onForwardUpstreamComplete', this, processed ?? envelope, undefined, err, context).catch(() => undefined);
+            throw err;
+        }
+    }
+    async createOriginConnector(options) {
+        const normalizedOptions = normalizeOriginConnectorOptions(options);
+        const { connectorConfig, originType, systemId, authorization: authorizationOption, ...factoryArgs } = normalizedOptions;
+        const connector = await createResource(connectorConfig, factoryArgs);
+        const attachedEvent = new AsyncEvent();
+        const buffer = [];
+        const authorization = (authorizationOption ??
+            null);
+        const buildContext = (ctx) => {
+            const baseSecurity = ctx?.security
+                ? { ...ctx.security }
+                : undefined;
+            const security = baseSecurity || authorization !== null
+                ? { ...(baseSecurity ?? {}), authorization }
+                : undefined;
+            return {
+                fromConnector: connector,
+                fromSystemId: systemId,
+                originType,
+                expectedResponseType: ctx?.expectedResponseType ?? FameResponseType.NONE,
+                security,
+                meta: ctx?.meta,
+                stickinessRequired: ctx?.stickinessRequired,
+                stickySid: ctx?.stickySid,
+            };
+        };
+        const gatedHandler = async (env, ctx) => {
+            if (ctx?.fromConnector && ctx.fromConnector !== connector) {
+                throw new Error('Context connector mismatch for origin connector');
+            }
+            if (ctx?.fromSystemId && ctx.fromSystemId !== systemId) {
+                throw new Error('Context system id mismatch for origin connector');
+            }
+            if (ctx?.originType && ctx.originType !== originType) {
+                throw new Error('Context origin type mismatch for origin connector');
+            }
+            const effectiveContext = buildContext(ctx);
+            await this.dispatchEnvelopeEvent('onEnvelopeReceived', this, env, ctx);
+            if (!attachedEvent.isSet()) {
+                const frameType = env.frame?.type ?? '';
+                if (ALLOWED_BEFORE_ATTACH.has(frameType)) {
+                    await this.deliver(env, effectiveContext);
+                }
+                else {
+                    buffer.push(env);
+                }
+                return null;
+            }
+            while (buffer.length) {
+                const pending = buffer.shift();
+                if (pending) {
+                    await this.deliver(pending, effectiveContext);
+                }
+            }
+            await this.deliver(env, effectiveContext);
+            return null;
+        };
+        await connector.start(gatedHandler);
+        const pendingEntry = {
+            connector,
+            attached: {
+                set: () => attachedEvent.set(),
+                wait: (options) => attachedEvent.wait(options),
+            },
+            buffer,
+        };
+        const timeoutMs = this.attachTimeoutMs;
+        if (timeoutMs !== null && timeoutMs > 0) {
+            const timeoutController = new AbortController();
+            pendingEntry.cancelAttachTimeout = () => timeoutController.abort();
+            this.spawn(async (taskSignal) => {
+                const combined = new AbortController();
+                const abortHandler = () => combined.abort();
+                timeoutController.signal.addEventListener('abort', abortHandler);
+                if (taskSignal) {
+                    if (taskSignal.aborted) {
+                        combined.abort();
+                    }
+                    else {
+                        taskSignal.addEventListener('abort', abortHandler);
+                    }
+                }
+                try {
+                    await delay(timeoutMs, combined.signal);
+                }
+                catch (error) {
+                    if (!combined.signal.aborted) {
+                        logger.debug('attach_timeout_delay_failed', {
+                            system_id: systemId,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                    }
+                    return;
+                }
+                finally {
+                    timeoutController.signal.removeEventListener('abort', abortHandler);
+                    taskSignal?.removeEventListener('abort', abortHandler);
+                }
+                let removed = false;
+                await this.routeManager.routesLock.runExclusive(async () => {
+                    const current = this.routeManager._pending_routes.get(systemId);
+                    if (current === pendingEntry) {
+                        this.routeManager._pending_routes.delete(systemId);
+                        this.routeManager._pending_route_metadata.delete(systemId);
+                        removed = true;
+                    }
+                });
+                if (!removed) {
+                    return;
+                }
+                try {
+                    await connector.stop();
+                }
+                catch (error) {
+                    logger.debug('attach_timeout_stop_failed', {
+                        system_id: systemId,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                logger.warning('attach_timeout_expired', {
+                    system_id: systemId,
+                    timeout_ms: timeoutMs,
+                });
+            }, { name: `attach-timeout-${systemId}` });
+        }
+        this.routeManager._pending_routes.set(systemId, pendingEntry);
+        this.routeManager._pending_route_metadata.set(systemId, connectorConfig);
+        return connector;
+    }
+    childFor(address) {
+        const entry = this.routeManager._downstream_addresses_routes.get(address.toString());
+        return entry?.segment ?? null;
+    }
+    buildRouterState() {
+        const downstream = new Map();
+        for (const [addr, info,] of this.routeManager._downstream_addresses_routes.entries()) {
+            if (info?.segment) {
+                downstream.set(addr, info.segment);
+            }
+        }
+        return new RouterState({
+            nodeId: this.id,
+            local: this.bindingManager.getAddresses(),
+            downstreamAddressRoutes: downstream,
+            peerAddressRoutes: this.routeManager._peer_addresses_routes,
+            childSegments: this.routeManager.downstreamRoutes.keys(),
+            peerSegments: this.routeManager._peer_routes.keys(),
+            hasParent: this.hasParent,
+            physicalSegments: computePhysicalSegments(this.physicalPath),
+            pools: this.getPoolsForRouter(),
+            capabilities: this.capabilityFrameHandler.capRoutes,
+            resolveAddressByCapability: this.resolveAddressByCapability.bind(this),
+            envelopeFactory: this.envelopeFactory,
+        });
+    }
+    getPoolsForRouter() {
+        const result = new Map();
+        for (const [poolKey, segments,] of this.addressBindFrameHandler.pools.entries()) {
+            result.set([poolKey.name, poolKey.pattern], new Set(segments));
+        }
+        return result;
+    }
+    async resolveAddressByCapability(capabilities) {
+        for (const capability of capabilities) {
+            const routes = this.capabilityFrameHandler.capRoutes[capability];
+            if (!routes) {
+                continue;
+            }
+            for (const addressKey of Object.keys(routes)) {
+                try {
+                    return new FameAddress(addressKey);
+                }
+                catch (error) {
+                    logger.debug('invalid_capability_address', {
+                        capability,
+                        address: addressKey,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+        return null;
+    }
+    async emitDeliveryNack(envelope, options) {
+        const state = this.buildRouterState();
+        await emitDeliveryNack(envelope, this, state, options.code, options.context ?? undefined);
+    }
+    async removeDownstreamRoute(segment, options = {}) {
+        const { stop = true, delayMs, reason, meta, captureStack } = options;
+        await this.routeManager.unregisterDownstreamRoute(segment, {
+            stop,
+            delayMs,
+            reason: reason ?? 'sentinel.removeDownstreamRoute',
+            meta: {
+                ...(meta ?? {}),
+                requested_stop: stop,
+                caller: 'Sentinel.removeDownstreamRoute',
+            },
+            captureStack,
+        });
+    }
+    async removePeerRoute(segment, options = {}) {
+        const { stop = true, delayMs, reason, meta, captureStack } = options;
+        await this.routeManager.unregisterPeerRoute(segment, {
+            stop,
+            delayMs,
+            reason: reason ?? 'sentinel.removePeerRoute',
+            meta: {
+                ...(meta ?? {}),
+                requested_stop: stop,
+                caller: 'Sentinel.removePeerRoute',
+            },
+            captureStack,
+        });
+    }
+    async resolveEncryptionKeyForAddress(_targetAddress) {
+        return null;
+    }
+    async onDeliveryNack(frame, envelope, context) {
+        await super.onDeliveryNack(frame, envelope, context);
+        const corrId = envelope.corrId;
+        if (!corrId || !this.pendingBinds.has(corrId)) {
+            return;
+        }
+        await this.resolvePendingBind(envelope, false, frame.reason ?? null);
+    }
+    get deliveryTracker() {
+        return this
+            ._deliveryTracker;
+    }
+    originMatches(context, segment, originType) {
+        return Boolean(context &&
+            context.originType === originType &&
+            context.fromSystemId === segment);
+    }
+    trackFlowRoute(envelope, connector) {
+        const flowId = envelope.flowId;
+        if (!flowId || this.routeManager.getFlowRoute(flowId)) {
+            return;
+        }
+        this.routeManager.trackFlowRoute(flowId, connector);
+    }
+    maybeForgetFlow(envelope) {
+        const flowId = envelope.flowId;
+        if (!flowId) {
+            return;
+        }
+        if (envelope.flowFlags && envelope.flowFlags & FlowFlags.RESET) {
+            this.routeManager.clearFlowRoute(flowId);
+        }
+    }
+    async resolvePendingBind(envelope, ok, reason) {
+        const corrId = envelope.corrId;
+        if (!corrId) {
+            return;
+        }
+        await this.pendingLock.runExclusive(async () => {
+            const pending = this.pendingBinds.get(corrId);
+            if (!pending) {
+                return;
+            }
+            this.pendingBinds.delete(corrId);
+            if (ok) {
+                pending.resolve(true);
+            }
+            else {
+                pending.reject(new Error(reason ?? 'Bind rejected'));
+            }
+        });
+    }
+    async connectToPeers() {
+        if (!this.peers.length) {
+            return;
+        }
+        const tasks = this.peers.map((peer) => this.connectToPeer(peer));
+        await Promise.all(tasks);
+    }
+    async connectToPeer(peer) {
+        if (!this.attachClient) {
+            throw new Error('Missing attach client');
+        }
+        if (!peer.admissionClient) {
+            throw new Error('Missing admission client');
+        }
+        const sessionManager = new UpstreamSessionManager({
+            node: this,
+            outboundOriginType: DeliveryOriginType.PEER,
+            inboundOriginType: DeliveryOriginType.PEER,
+            admissionClient: peer.admissionClient,
+            attachClient: this.attachClient,
+            requestedLogicals: this.requestedLogicals,
+            inboundHandler: (env, ctx) => this.handleInboundFromPeer(env, ctx),
+            onAttach: (info, connector) => this.onNodeAttachToPeer(info, connector),
+            onEpochChange: (epoch) => this.onEpochChange(epoch),
+            onWelcome: async () => undefined,
+        });
+        await sessionManager.start();
+        const systemId = sessionManager.systemId;
+        if (!systemId) {
+            throw new Error('Peer session manager missing system id');
+        }
+        this.peerSessionManagers.set(systemId, sessionManager);
+        await this.routeManager.registerPeerRoute(systemId, sessionManager);
+    }
+    async handleInboundFromPeer(envelope, context) {
+        const deliveryContext = {
+            expectedResponseType: context?.expectedResponseType ?? FameResponseType.NONE,
+            fromConnector: context?.fromConnector,
+            fromSystemId: context?.fromSystemId,
+            originType: DeliveryOriginType.PEER,
+            security: context?.security,
+            meta: context?.meta,
+            stickinessRequired: context?.stickinessRequired,
+            stickySid: context?.stickySid,
+        };
+        await this.deliver(envelope, deliveryContext);
+        return null;
+    }
+    async onNodeAttachToPeer(info, connector) {
+        await this.dispatchEvent('onNodeAttachToPeer', this, info, connector).catch(() => undefined);
+    }
+    async onEpochChange(epoch) {
+        this.routingEpochValue = epoch;
+        await this.dispatchEvent('onEpochChange', this, epoch).catch(() => undefined);
+        await this.propagateAddressBindingsUpstream();
+    }
+    async propagateAddressBindingsUpstream() {
+        if (!this.hasParent) {
+            logger.warning('No upstream defined to rebind addresses');
+            return;
+        }
+        const entries = Array.from(this.routeManager._downstream_addresses_routes.entries());
+        for (const [address, info] of entries) {
+            if (!info) {
+                continue;
+            }
+            let name = null;
+            try {
+                const [parsedName] = parseAddress(address);
+                name = parsedName;
+            }
+            catch {
+                name = null;
+            }
+            if (name && RESERVED_UPSTREAM_ADDRESS_NAMES.has(name.toLowerCase())) {
+                continue;
+            }
+            try {
+                await this.bindAddressUpstream(new FameAddress(address), info);
+            }
+            catch (error) {
+                logger.error('rebind_failed', {
+                    address,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    async bindAddressUpstream(address, info) {
+        if (!this.hasParent) {
+            return;
+        }
+        const corrId = generateId();
+        const deferred = createDeferred();
+        await this.pendingLock.runExclusive(async () => {
+            this.pendingBinds.set(corrId, deferred);
+        });
+        const frame = {
+            type: 'AddressBind',
+            address: address.toString(),
+        };
+        if (info.physicalPath) {
+            frame.physicalPath = info.physicalPath;
+        }
+        if (info.encryptionKeyId) {
+            frame.encryptionKeyId = info.encryptionKeyId;
+        }
+        const replyTo = formatAddress(SYSTEM_INBOX, this.physicalPath);
+        const envelopeOptions = {
+            frame,
+            corrId,
+            replyTo,
+        };
+        const traceId = currentTraceId();
+        if (traceId) {
+            envelopeOptions.traceId = traceId;
+        }
+        const envelope = this.envelopeFactory.createEnvelope(envelopeOptions);
+        await this.forwardUpstream(envelope, localDeliveryContext(this.id));
+        let timeoutId = null;
+        const timeoutPromise = new Promise((_resolve, reject) => {
+            timeoutId = setTimeout(() => {
+                reject(new Error(`Timeout waiting for bind ack for ${address.toString()}`));
+            }, this.ackTimeoutMs);
+            if (typeof timeoutId?.unref === 'function') {
+                timeoutId.unref();
+            }
+        });
+        try {
+            const result = await Promise.race([deferred.promise, timeoutPromise]);
+            if (!result) {
+                throw new Error(`Bind to ${address.toString()} was rejected`);
+            }
+        }
+        finally {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+                timeoutId = null;
+            }
+            await this.pendingLock.runExclusive(async () => {
+                const pending = this.pendingBinds.get(corrId);
+                if (pending === deferred) {
+                    this.pendingBinds.delete(corrId);
+                }
+            });
+        }
+    }
+    static async aserve(options = {}) {
+        const { logLevel, rootConfig, config, node = null, fabric: providedFabric = null, signals = ['SIGINT', 'SIGTERM'], signal, ...fabricOptions } = options;
+        const resolvedLevel = normalizeServeLogLevel(logLevel) ?? LogLevel.INFO;
+        basicConfig({ level: resolvedLevel });
+        const processRef = typeof globalThis !== 'undefined' &&
+            typeof globalThis.process !== 'undefined'
+            ? globalThis.process
+            : undefined;
+        if (!processRef ||
+            typeof processRef.once !== 'function' ||
+            typeof processRef.removeListener !== 'function') {
+            throw new Error('Sentinel.aserve requires a Node.js runtime with signal support');
+        }
+        const abortSignal = signal ?? null;
+        if (abortSignal?.aborted) {
+            logger.info('shutdown_signal_received', { signal: 'abort' });
+            return;
+        }
+        // Build fabric options, preferring rootConfig if provided
+        const fabricCreateOptions = {
+            ...fabricOptions,
+        };
+        if (rootConfig !== undefined) {
+            fabricCreateOptions.rootConfig = rootConfig;
+        }
+        else if (config !== null && config !== undefined) {
+            fabricCreateOptions.rootConfig = config;
+        }
+        if (node !== null) {
+            fabricCreateOptions.node = node;
+        }
+        logger.debug('fabric_create_options', {
+            hasRootConfig: 'rootConfig' in fabricCreateOptions,
+            hasNode: 'node' in fabricCreateOptions,
+            rootConfigKeys: fabricCreateOptions.rootConfig
+                ? Object.keys(fabricCreateOptions.rootConfig).join(',')
+                : 'none',
+            allKeys: Object.keys(fabricCreateOptions).join(','),
+        });
+        let stopResolve;
+        let stopResolved = false;
+        const stopPromise = new Promise((resolve) => {
+            stopResolve = () => {
+                if (!stopResolved) {
+                    stopResolved = true;
+                    resolve();
+                }
+            };
+        });
+        const listeners = [];
+        let abortListener = null;
+        const cleanupListeners = () => {
+            while (listeners.length) {
+                const { signal: registeredSignal, listener } = listeners.pop();
+                processRef.removeListener(registeredSignal, listener);
+            }
+            if (abortSignal && abortListener) {
+                abortSignal.removeEventListener('abort', abortListener);
+                abortListener = null;
+            }
+        };
+        const registerSignalListeners = () => {
+            for (const sig of signals) {
+                const listener = () => {
+                    logger.info('shutdown_signal_received', { signal: sig });
+                    cleanupListeners();
+                    stopResolve();
+                };
+                listeners.push({ signal: sig, listener });
+                processRef.once(sig, listener);
+            }
+            if (abortSignal) {
+                abortListener = () => {
+                    logger.info('shutdown_signal_received', { signal: 'abort' });
+                    cleanupListeners();
+                    stopResolve();
+                };
+                abortSignal.addEventListener('abort', abortListener, { once: true });
+            }
+        };
+        // Use provided fabric or withFabric pattern for lifecycle management
+        if (providedFabric) {
+            // If a fabric is provided, use it directly without lifecycle management
+            await providedFabric.enter();
+            try {
+                registerSignalListeners();
+                logger.info('sentinel_live', {
+                    message: 'Node is live! Press Ctrl+C to stop.',
+                });
+                try {
+                    await stopPromise;
+                    logger.info('sentinel_shutdown_begin');
+                }
+                finally {
+                    cleanupListeners();
+                }
+            }
+            finally {
+                await providedFabric.exit();
+            }
+        }
+        else {
+            // Use withFabric pattern for automatic lifecycle management
+            await withFabric(fabricCreateOptions, async () => {
+                registerSignalListeners();
+                logger.info('sentinel_live', {
+                    message: 'Node is live! Press Ctrl+C to stop.',
+                });
+                try {
+                    await stopPromise;
+                    logger.info('sentinel_shutdown_begin');
+                }
+                finally {
+                    cleanupListeners();
+                }
+            });
+        }
+        logger.info('sentinel_shutdown_complete');
+    }
+}
+function normalizeServeLogLevel(level) {
+    if (level === null || level === undefined) {
+        return undefined;
+    }
+    if (typeof level === 'number' && Number.isFinite(level)) {
+        return level;
+    }
+    if (typeof level === 'string') {
+        const trimmed = level.trim();
+        if (!trimmed) {
+            return undefined;
+        }
+        const numeric = Number(trimmed);
+        if (!Number.isNaN(numeric)) {
+            return numeric;
+        }
+        const key = trimmed.toUpperCase();
+        const value = LogLevel[key];
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            return value;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=sentinel.js.map