@naylence/runtime 0.3.3 → 0.3.5-test.0

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

@@ -0,0 +1,926 @@
+import { DEFAULT_INVOKE_TIMEOUT_MILLIS, DeliveryOriginType, FameResponseType, createChannelMessage, formatAddress, localDeliveryContext, parseAddress, } from '@naylence/core';
+import { generateId } from '@naylence/core';
+import { secureDigest } from '../util/util.js';
+import { InMemoryStorageProvider } from '../storage/in-memory-storage.js';
+import { NodeEnvelopeFactory } from './node-envelope-factory.js';
+import { BindingManager } from './binding-manager.js';
+import { EnvelopeListenerManager } from './envelope-listener-manager.js';
+import { DefaultDeliveryTracker } from '../delivery/default-delivery-tracker.js';
+import { TaskSpawner } from '../util/task-spawner.js';
+import { pushNode } from './node-context-stack.js';
+import { getLogger } from '../util/logging.js';
+import { RootSessionManager } from './root-session-manager.js';
+import { UpstreamSessionManager } from './upstream-session-manager.js';
+import { NoopAdmissionClient } from './admission/noop-admission-client.js';
+import { NodeMetaRecord, NODE_META_NAMESPACE } from './node-meta.js';
+import { DefaultServiceManager } from '../service/default-service-manager.js';
+const SYSTEM_INBOX = '__sys__';
+const logger = getLogger('naylence.fame.node.node');
+function isSnakeCase(name) {
+    return name.includes('_');
+}
+function camelToSnake(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/([A-Z])([A-Z][a-z])/g, '$1_$2')
+        .toLowerCase();
+}
+function snakeToCamel(name) {
+    return name.replace(/_([a-z])/g, (_match, char) => char.toUpperCase());
+}
+function getCandidateNames(eventName) {
+    const candidates = new Set();
+    candidates.add(eventName);
+    if (isSnakeCase(eventName)) {
+        candidates.add(snakeToCamel(eventName));
+    }
+    else {
+        candidates.add(camelToSnake(eventName));
+    }
+    return Array.from(candidates);
+}
+function resolveListenerMethod(listener, eventName) {
+    for (const candidate of getCandidateNames(eventName)) {
+        const handler = listener[candidate];
+        if (typeof handler === 'function') {
+            return handler.bind(listener);
+        }
+    }
+    return undefined;
+}
+class DefaultRetryHandler {
+    constructor(deliveryFn) {
+        this.deliveryFn = deliveryFn;
+    }
+    async onRetryNeeded(envelope, _attempt, _nextDelayMs, context) {
+        await this.deliveryFn(envelope, context);
+    }
+}
+function resolveOption(options, primary, ...aliases) {
+    const primaryValue = options[primary];
+    if (primaryValue !== undefined) {
+        return primaryValue;
+    }
+    for (const alias of aliases) {
+        if (alias in options) {
+            const aliasValue = options[alias];
+            if (aliasValue !== undefined) {
+                return aliasValue;
+            }
+        }
+    }
+    return undefined;
+}
+function resolveBooleanOption(options, primary, ...aliases) {
+    const value = resolveOption(options, primary, ...aliases);
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    return undefined;
+}
+function resolveStringOption(options, primary, ...aliases) {
+    const value = resolveOption(options, primary, ...aliases);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null || typeof value === 'string') {
+        return value;
+    }
+    return undefined;
+}
+function resolveNumberOption(options, primary, ...aliases) {
+    const value = resolveOption(options, primary, ...aliases);
+    if (value === undefined || value === null) {
+        return value;
+    }
+    if (typeof value === 'number') {
+        return value;
+    }
+    return undefined;
+}
+function resolveArrayOption(options, primary, ...aliases) {
+    const value = resolveOption(options, primary, ...aliases);
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        return value;
+    }
+    return undefined;
+}
+function resolveStringArrayOption(options, primary, ...aliases) {
+    const value = resolveArrayOption(options, primary, ...aliases);
+    if (!value) {
+        return undefined;
+    }
+    return value.filter((item) => typeof item === 'string');
+}
+function sortListeners(listeners) {
+    return [...listeners].sort((a, b) => a.priority - b.priority);
+}
+export class FameNode extends TaskSpawner {
+    constructor(options = {}) {
+        super();
+        this._sessionManager = null;
+        this._upstreamConnector = null;
+        this._isStarted = false;
+        this._releaseNodeContext = null;
+        this._lastHeartbeatAt = null;
+        const systemIdOption = resolveStringOption(options, 'systemId', 'system_id');
+        this._id = systemIdOption ?? generateId();
+        const physicalPathOption = resolveStringOption(options, 'physicalPath', 'physical_path');
+        this._physicalPath = physicalPathOption ?? `/${this._id}`;
+        const hasParentOption = resolveBooleanOption(options, 'hasParent', 'has_parent');
+        this._hasParent = hasParentOption ?? false;
+        const storageProviderOption = resolveOption(options, 'storageProvider', 'storage_provider');
+        this._storageProvider =
+            storageProviderOption ?? new InMemoryStorageProvider();
+        const acceptedLogicalsOption = resolveStringArrayOption(options, 'acceptedLogicals', 'accepted_logicals') ?? [];
+        this._acceptedLogicals = new Set(acceptedLogicalsOption);
+        const deliveryPolicyOption = resolveOption(options, 'deliveryPolicy', 'delivery_policy');
+        this._deliveryPolicy = deliveryPolicyOption ?? null;
+        const admissionClientOption = resolveOption(options, 'admissionClient', 'admission_client');
+        this._admissionClient = admissionClientOption ?? null;
+        const attachClientOption = resolveOption(options, 'attachClient', 'attach_client');
+        this._attachClient = attachClientOption ?? null;
+        const requestedLogicalsOption = resolveStringArrayOption(options, 'requestedLogicals', 'requested_logicals') ?? [];
+        this._requestedLogicals = [...requestedLogicalsOption];
+        const securityManagerOption = resolveOption(options, 'securityManager', 'security_manager');
+        this._securityManager = securityManagerOption ?? null;
+        const publicUrlOption = resolveStringOption(options, 'publicUrl', 'public_url');
+        this._publicUrl = publicUrlOption ?? null;
+        const cryptoProviderOption = resolveOption(options, 'cryptoProvider', 'crypto_provider');
+        const fallbackCryptoProvider = {};
+        this._cryptoProvider = cryptoProviderOption ?? fallbackCryptoProvider;
+        const envelopeFactoryOption = resolveOption(options, 'envelopeFactory', 'envelope_factory');
+        const envelopeFactory = envelopeFactoryOption ?? new NodeEnvelopeFactory(() => this.sid ?? '');
+        this._envelopeFactory = envelopeFactory;
+        const deliveryTrackerOption = resolveOption(options, 'deliveryTracker', 'delivery_tracker');
+        const tracker = deliveryTrackerOption ??
+            new DefaultDeliveryTracker(this._storageProvider);
+        this._deliveryTracker = tracker;
+        const nodeMetaStoreOption = resolveOption(options, 'nodeMetaStore', 'node_meta_store');
+        this._nodeMetaStorePromise = nodeMetaStoreOption
+            ? Promise.resolve(nodeMetaStoreOption)
+            : this._storageProvider.getKeyValueStore(NodeMetaRecord, NODE_META_NAMESPACE);
+        const transportListenersResolved = resolveArrayOption(options, 'transportListeners', 'transport_listeners') ?? [];
+        const transportListeners = [...transportListenersResolved];
+        this._transportListeners = transportListeners;
+        const listenersResolved = resolveArrayOption(options, 'eventListeners', 'event_listeners') ?? [];
+        const listeners = [...listenersResolved];
+        if (this._securityManager && !listeners.includes(this._securityManager)) {
+            listeners.push(this._securityManager);
+        }
+        for (const listener of transportListeners) {
+            if (!listeners.includes(listener)) {
+                listeners.push(listener);
+            }
+        }
+        if (!listeners.includes(tracker)) {
+            listeners.push(tracker);
+        }
+        this._eventListeners = sortListeners(listeners);
+        const bindingStoreOption = resolveOption(options, 'bindingStore', 'binding_store');
+        const bindingManagerOptions = {
+            hasUpstream: this._hasParent,
+            getId: () => this._id,
+            getPhysicalPath: () => this._physicalPath,
+            getAcceptedLogicals: () => this._acceptedLogicals,
+            forwardUpstream: (envelope, context) => this.forwardUpstream(envelope, context),
+            envelopeFactory: this._envelopeFactory,
+            deliveryTracker: this._deliveryTracker,
+            getEncryptionKeyId: () => this._securityManager?.getEncryptionKeyId() ?? null,
+            ...(bindingStoreOption ? { bindingStore: bindingStoreOption } : {}),
+        };
+        this._bindingManager = new BindingManager(bindingManagerOptions);
+        this._binding_manager = this._bindingManager;
+        this._envelopeListenerManager = new EnvelopeListenerManager({
+            bindingManager: this._bindingManager,
+            nodeLike: this,
+            envelopeFactory: this._envelopeFactory,
+            deliveryTracker: this._deliveryTracker,
+        });
+        const serviceManagerOption = resolveOption(options, 'serviceManager', 'service_manager');
+        const defaultServiceConfigs = resolveArrayOption(options, 'defaultServiceConfigs', 'default_service_configs', 'service_configs') ?? [];
+        const serviceCapabilityMapOption = resolveOption(options, 'serviceCapabilityMap', 'service_capability_map');
+        const servicePollTimeoutOption = resolveNumberOption(options, 'servicePollTimeoutMs', 'service_poll_timeout_ms');
+        const serviceManager = serviceManagerOption ??
+            new DefaultServiceManager({
+                invoke: (targetAddr, method, params, timeoutMs) => this.invoke(targetAddr, method, params, timeoutMs ?? DEFAULT_INVOKE_TIMEOUT_MILLIS),
+                serve: (serviceName, handler, serveOptions) => this._envelopeListenerManager.listen(serviceName, handler, serveOptions ?? {}),
+                serveRpc: (serviceName, handler, serveOptions) => this._envelopeListenerManager.listenRpc(serviceName, handler, serveOptions ?? {}),
+                capabilityMap: serviceCapabilityMapOption ?? undefined,
+                pollTimeoutMs: servicePollTimeoutOption ?? null,
+                defaultServiceConfigs,
+            });
+        this._serviceManager = serviceManager;
+        this._defaultBindingPath = this._physicalPath;
+        const physicalPathProvided = options.physicalPath !== undefined ||
+            options['physical_path'] !== undefined;
+        this._sid =
+            this._hasParent && !physicalPathProvided
+                ? null
+                : this.computeSid(this._physicalPath);
+        this._handshakeCompleted = !this._hasParent;
+        this._welcomeExpiresAt = null;
+        this._attachExpiresAt = null;
+    }
+    async initializeSessionManager() {
+        if (this._sessionManager) {
+            return;
+        }
+        if (this._hasParent) {
+            await this.initializeUpstreamSessionManager();
+        }
+        else {
+            await this.initializeRootSessionManager();
+        }
+    }
+    async initializeRootSessionManager() {
+        const admissionClient = this._admissionClient ?? new NoopAdmissionClient({ systemId: this._id });
+        const manager = new RootSessionManager({
+            node: this,
+            admissionClient,
+            requestedLogicals: [...this._requestedLogicals],
+            onWelcome: (frame) => this.handleWelcome(frame),
+            onEpochChange: (epoch) => this.handleEpochChange(epoch),
+        });
+        this._sessionManager = manager;
+        await manager.start();
+    }
+    async initializeUpstreamSessionManager() {
+        if (!this._attachClient) {
+            throw new Error('Attach client is required for upstream nodes');
+        }
+        if (!this._admissionClient) {
+            throw new Error('Admission client is required for upstream nodes');
+        }
+        const manager = new UpstreamSessionManager({
+            node: this,
+            attachClient: this._attachClient,
+            requestedLogicals: [...this._requestedLogicals],
+            outboundOriginType: DeliveryOriginType.DOWNSTREAM,
+            inboundOriginType: DeliveryOriginType.UPSTREAM,
+            inboundHandler: (envelope, context) => this.handleInboundFromUpstream(envelope, context),
+            onWelcome: (frame) => this.handleWelcome(frame),
+            onAttach: (info, connector) => this.handleAttach(info, connector),
+            onEpochChange: (epoch) => this.handleEpochChange(epoch),
+            admissionClient: this._admissionClient,
+        });
+        this._sessionManager = manager;
+        await manager.start();
+    }
+    async handleInboundFromUpstream(envelope, context) {
+        await this.deliver(envelope, context);
+        return null;
+    }
+    async handleWelcome(welcome) {
+        if (welcome.systemId) {
+            this._id = welcome.systemId;
+        }
+        if (welcome.acceptedLogicals) {
+            this._acceptedLogicals = new Set(welcome.acceptedLogicals);
+        }
+        this._welcomeExpiresAt = welcome.expiresAt ?? null;
+        if (!this._hasParent) {
+            if (welcome.assignedPath) {
+                this._physicalPath = welcome.assignedPath;
+            }
+            else if (welcome.systemId) {
+                this._physicalPath = `/${welcome.systemId}`;
+            }
+            this._defaultBindingPath = this._physicalPath;
+            this._sid = this.computeSid(this._physicalPath);
+            this._upstreamConnector = null;
+            this._handshakeCompleted = true;
+        }
+        await this.dispatchEvent('onWelcome', welcome);
+    }
+    async handleAttach(info, connector) {
+        this._id = info.systemId;
+        this._physicalPath =
+            info.assignedPath ?? info.targetPhysicalPath ?? this._physicalPath;
+        this._upstreamConnector = connector;
+        if (info.acceptedLogicals) {
+            this._acceptedLogicals = new Set(info.acceptedLogicals);
+        }
+        this._attachExpiresAt = info.attachExpiresAt ?? null;
+        this._handshakeCompleted = true;
+        if (this._physicalPath) {
+            this._defaultBindingPath = this._physicalPath;
+            this._sid = this.computeSid(this._physicalPath);
+        }
+        await this.dispatchEvent('onNodeAttachToUpstream', this, info);
+    }
+    async handleEpochChange(epoch) {
+        await this._bindingManager.rebindAddressesUpstream();
+        await this._bindingManager.readvertiseCapabilitiesUpstream();
+        await this.dispatchEvent('onEpochChange', this, epoch);
+    }
+    async stopSessionManager() {
+        const manager = this._sessionManager;
+        if (!manager) {
+            return;
+        }
+        try {
+            await manager.stop();
+        }
+        finally {
+            this._sessionManager = null;
+            this._upstreamConnector = null;
+        }
+    }
+    async handleSystemFrame(envelope, context) {
+        const frameType = envelope.frame?.type;
+        if (!frameType) {
+            return;
+        }
+        if (frameType === 'NodeHeartbeat') {
+            logger.debug('received_heartbeat_frame', {
+                envelopeId: envelope.id,
+                corrId: envelope.corrId ?? null,
+            });
+            this._lastHeartbeatAt = Date.now();
+            await this.dispatchEvent('onHeartbeatReceived', envelope);
+            return;
+        }
+        if (frameType === 'DeliveryAck') {
+            await this.handleDeliveryAck(envelope, context);
+            return;
+        }
+        logger.debug('unhandled_system_frame', {
+            envelopeId: envelope.id,
+            frameType,
+        });
+    }
+    async handleDeliveryAck(envelope, context) {
+        const frame = envelope.frame;
+        if (!frame || frame.type !== 'DeliveryAck') {
+            return;
+        }
+        await this._deliveryTracker.onEnvelopeDelivered(SYSTEM_INBOX, envelope, context);
+        if (frame.ok !== false) {
+            logger.debug('delivery_ack_received', {
+                envelopeId: envelope.id,
+                corrId: envelope.corrId ?? null,
+            });
+            return;
+        }
+        logger.warning('delivery_nack_received', {
+            envelopeId: envelope.id,
+            corrId: envelope.corrId ?? null,
+            code: frame.code ?? null,
+            reason: frame.reason ?? null,
+            fromSystemId: context?.fromSystemId ?? null,
+        });
+        await this.onDeliveryNack(frame, envelope, context);
+    }
+    async onDeliveryNack(frame, envelope, _context) {
+        logger.debug('delivery_nack_processed', {
+            envelopeId: envelope.id,
+            code: frame.code ?? null,
+            reason: frame.reason ?? null,
+        });
+    }
+    get id() {
+        return this._id;
+    }
+    get sid() {
+        return this._sid;
+    }
+    get physicalPath() {
+        return this._physicalPath;
+    }
+    get acceptedLogicals() {
+        return this._acceptedLogicals;
+    }
+    get envelopeFactory() {
+        return this._envelopeFactory;
+    }
+    get deliveryPolicy() {
+        return this._deliveryPolicy;
+    }
+    get bindingManager() {
+        return this._bindingManager;
+    }
+    get defaultBindingPath() {
+        return this._defaultBindingPath;
+    }
+    get hasParent() {
+        return this._hasParent;
+    }
+    get securityManager() {
+        return this._securityManager;
+    }
+    get admissionClient() {
+        return this._admissionClient;
+    }
+    get eventListeners() {
+        return this._eventListeners;
+    }
+    get upstreamConnector() {
+        const manager = this._sessionManager;
+        if (manager instanceof UpstreamSessionManager) {
+            const activeConnector = manager.getActiveConnector();
+            if (activeConnector) {
+                return activeConnector;
+            }
+        }
+        return this._upstreamConnector;
+    }
+    get publicUrl() {
+        return this._publicUrl;
+    }
+    get storageProvider() {
+        return this._storageProvider;
+    }
+    get cryptoProvider() {
+        return this._cryptoProvider;
+    }
+    get lastHeartbeatAt() {
+        return this._lastHeartbeatAt;
+    }
+    get serviceManager() {
+        return this._serviceManager;
+    }
+    get handshakeCompleted() {
+        return this._handshakeCompleted;
+    }
+    get welcomeExpiresAt() {
+        return this._welcomeExpiresAt;
+    }
+    get attachExpiresAt() {
+        return this._attachExpiresAt;
+    }
+    addEventListener(listener) {
+        if (this._eventListeners.includes(listener)) {
+            return;
+        }
+        this._eventListeners.push(listener);
+        this._eventListeners.sort((a, b) => a.priority - b.priority);
+    }
+    removeEventListener(listener) {
+        const index = this._eventListeners.indexOf(listener);
+        if (index >= 0) {
+            this._eventListeners.splice(index, 1);
+        }
+    }
+    async start() {
+        if (this._isStarted) {
+            throw new Error('Node already started');
+        }
+        const release = pushNode(this);
+        try {
+            await this.dispatchEvent('onNodeInitialized', this);
+            await this.initializeSessionManager();
+            if (!this._sid && this._physicalPath) {
+                this._sid = this.computeSid(this._physicalPath);
+            }
+            await this.persistNodeMeta();
+            await this.listen(SYSTEM_INBOX, async (env, ctx) => {
+                await this.handleSystemFrame(env, ctx);
+                return null;
+            });
+            await this._serviceManager.start();
+            await this.dispatchEvent('onNodeStarted', this);
+            await this._bindingManager.restore();
+            await this._envelopeListenerManager.start();
+            this._releaseNodeContext = release;
+            this._isStarted = true;
+            logger.debug('node_started', {
+                node_id: this.id,
+                sid: this.sid,
+                path: this.physicalPath,
+                logicals: this.acceptedLogicals,
+            });
+        }
+        catch (error) {
+            release();
+            try {
+                await this._serviceManager.stop();
+            }
+            catch {
+                // Best-effort cleanup
+            }
+            await this.stopSessionManager();
+            throw error;
+        }
+    }
+    async prepareToStop() {
+        await this.dispatchEvent('onNodePreparingToStop', this);
+    }
+    async stop() {
+        if (!this._isStarted) {
+            return;
+        }
+        await this.prepareToStop();
+        await this.shutdownTasks({ gracePeriod: 100, joinTimeout: 100 });
+        await this._envelopeListenerManager.stop();
+        await this.stopSessionManager();
+        await this._serviceManager.stop();
+        await this.dispatchEvent('onNodeStopped', this);
+        this._isStarted = false;
+        if (this._releaseNodeContext) {
+            this._releaseNodeContext();
+            this._releaseNodeContext = null;
+        }
+        logger.debug('node_stopped', {
+            node_id: this.id,
+        });
+    }
+    async bind(participant) {
+        return this._bindingManager.bind(participant);
+    }
+    async unbind(participant) {
+        await this._bindingManager.unbind(participant);
+    }
+    async listen(recipient, handler, pollTimeoutMs) {
+        return this._envelopeListenerManager.listen(recipient, handler, {
+            pollTimeoutMs: pollTimeoutMs ?? null,
+        });
+    }
+    async listenRpc(serviceName, handler, pollTimeoutMs) {
+        return this._envelopeListenerManager.listenRpc(serviceName, handler, {
+            pollTimeoutMs: pollTimeoutMs ?? null,
+        });
+    }
+    async invoke(targetAddr, method, params, timeoutMs) {
+        return this._envelopeListenerManager.invoke({
+            targetAddr,
+            method,
+            params,
+            timeoutMs,
+        });
+    }
+    async invokeByCapability(capabilities, method, params, timeoutMs) {
+        return this._envelopeListenerManager.invoke({
+            capabilities,
+            method,
+            params,
+            timeoutMs,
+        });
+    }
+    async *invokeStream(targetAddr, method, params, timeoutMs) {
+        const stream = await this._envelopeListenerManager.invokeStream({
+            targetAddr,
+            method,
+            params,
+            timeoutMs,
+        });
+        for await (const item of stream) {
+            yield item;
+        }
+    }
+    async *invokeByCapabilityStream(capabilities, method, params, timeoutMs) {
+        const stream = await this._envelopeListenerManager.invokeStream({
+            capabilities,
+            method,
+            params,
+            timeoutMs,
+        });
+        for await (const item of stream) {
+            yield item;
+        }
+    }
+    async send(envelope, context, _deliveryPolicy, deliveryFn, timeoutMs) {
+        let effectiveContext;
+        if (!context) {
+            effectiveContext = localDeliveryContext(this.id);
+        }
+        else {
+            if (context.originType &&
+                context.originType !== DeliveryOriginType.LOCAL) {
+                throw new Error('Can only send with LOCAL origin context');
+            }
+            if (context.fromConnector) {
+                throw new Error('fromConnector must be null in LOCAL context');
+            }
+            effectiveContext = {
+                ...context,
+                originType: DeliveryOriginType.LOCAL,
+                fromConnector: null,
+            };
+        }
+        const deliveryPolicy = _deliveryPolicy ?? this._deliveryPolicy ?? null;
+        const deliverFn = deliveryFn ??
+            ((env, ctx) => this.deliver(env, ctx));
+        const ackRequired = Boolean(deliveryPolicy?.isAckRequired(envelope));
+        if (ackRequired) {
+            envelope.rtype = envelope.rtype
+                ? envelope.rtype | FameResponseType.ACK
+                : FameResponseType.ACK;
+        }
+        const replyRequired = Boolean(envelope.rtype &&
+            ((envelope.rtype & FameResponseType.REPLY) !== 0 ||
+                (envelope.rtype & FameResponseType.STREAM) !== 0));
+        if (!envelope.traceId) {
+            envelope.traceId = generateId();
+        }
+        if (!ackRequired && !replyRequired) {
+            await deliverFn(envelope, effectiveContext);
+            return null;
+        }
+        const retryPolicy = deliveryPolicy?.senderRetryPolicy;
+        if (!envelope.corrId) {
+            envelope.corrId = generateId();
+        }
+        if (!envelope.replyTo) {
+            envelope.replyTo = formatAddress(SYSTEM_INBOX, this._physicalPath ?? '');
+        }
+        const retryHandler = retryPolicy
+            ? new DefaultRetryHandler(deliverFn)
+            : null;
+        const effectiveTimeout = timeoutMs ?? DEFAULT_INVOKE_TIMEOUT_MILLIS;
+        const expectedResponseType = envelope.rtype ?? FameResponseType.ACK;
+        await this._deliveryTracker.track(envelope, {
+            timeoutMs: effectiveTimeout,
+            expectedResponseType,
+            retryPolicy: retryPolicy ?? null,
+            retryHandler,
+        });
+        await deliverFn(envelope, effectiveContext);
+        if (!ackRequired) {
+            return null;
+        }
+        const ackEnvelope = await this._deliveryTracker.awaitAck(envelope.id, effectiveTimeout);
+        const ackFrame = ackEnvelope.frame;
+        if (!ackFrame || ackFrame.type !== 'DeliveryAck') {
+            throw new Error('Expected DeliveryAck frame in acknowledgement');
+        }
+        return ackFrame;
+    }
+    async deliver(envelope, context) {
+        const processedEnvelope = await this.runEnvelopeListeners('onDeliver', 1, [
+            this,
+            envelope,
+            context,
+        ]);
+        if (!processedEnvelope) {
+            return;
+        }
+        const frameType = processedEnvelope.frame?.type ?? null;
+        if (frameType &&
+            [
+                'AddressBind',
+                'AddressUnbind',
+                'CapabilityAdvertise',
+                'CapabilityWithdraw',
+                'NodeHeartbeat',
+            ].includes(frameType)) {
+            await this.forwardUpstream(processedEnvelope, context);
+            return;
+        }
+        if (frameType &&
+            [
+                'AddressBindAck',
+                'AddressUnbindAck',
+                'CapabilityAdvertiseAck',
+                'CapabilityWithdrawAck',
+            ].includes(frameType)) {
+            await this._deliveryTracker.onEnvelopeDelivered(SYSTEM_INBOX, processedEnvelope, context);
+            return;
+        }
+        // if (frameType === 'DeliveryAck') {
+        //   if (!context || context.originType !== DeliveryOriginType.LOCAL) {
+        //     await this._deliveryTracker.onEnvelopeDelivered(SYSTEM_INBOX, processedEnvelope, context);
+        //     return;
+        //   }
+        // }
+        if (frameType &&
+            [
+                'Data',
+                'DeliveryAck',
+                'SecureOpen',
+                'SecureAccept',
+                'SecureClose',
+            ].includes(frameType)) {
+            if (processedEnvelope.to && this.hasLocal(processedEnvelope.to)) {
+                await this.deliverLocal(processedEnvelope.to, processedEnvelope, context);
+                return;
+            }
+            if (processedEnvelope.capabilities &&
+                processedEnvelope.capabilities.length > 0) {
+                const resolved = await this._serviceManager.resolveAddressByCapability(processedEnvelope.capabilities);
+                if (resolved) {
+                    await this.deliverLocal(resolved, processedEnvelope, context);
+                    return;
+                }
+            }
+        }
+        if (this._upstreamConnector &&
+            context?.originType === DeliveryOriginType.LOCAL) {
+            if (!context.fromConnector ||
+                context.fromConnector !== this._upstreamConnector) {
+                await this.forwardUpstream(processedEnvelope, context);
+            }
+            else {
+                logger.error('attempted_upstream_loop', {
+                    envelopeId: processedEnvelope.id,
+                });
+            }
+            return;
+        }
+        if (!processedEnvelope.to) {
+            logger.error('dropping_envelope_without_destination', {
+                envelopeId: processedEnvelope.id,
+                capabilities: processedEnvelope.capabilities ?? [],
+            });
+            return;
+        }
+        logger.warning('no_local_handler_for_address', {
+            address: processedEnvelope.to.toString?.() ?? String(processedEnvelope.to),
+            originType: context?.originType ?? null,
+        });
+    }
+    async deliverLocal(address, envelope, context) {
+        const processedEnvelope = await this.runEnvelopeListeners('onDeliverLocal', 2, [this, address, envelope, context]);
+        if (!processedEnvelope) {
+            return;
+        }
+        const binding = this._bindingManager.getBinding(address);
+        if (!binding) {
+            throw new Error(`No local binding for address: ${address.toString()}`);
+        }
+        const channelMessage = createChannelMessage(processedEnvelope, context);
+        await binding.channel.send(channelMessage);
+        await this.runEnvelopeListeners('onDeliverLocalComplete', 2, [
+            this,
+            address,
+            processedEnvelope,
+            context,
+        ]);
+    }
+    async forwardUpstream(envelope, context) {
+        if (context?.originType === DeliveryOriginType.UPSTREAM) {
+            return;
+        }
+        let processedEnvelope = null;
+        try {
+            processedEnvelope = await this.runEnvelopeListeners('onForwardUpstream', 1, [this, envelope, context]);
+            if (!processedEnvelope) {
+                return;
+            }
+            if (!this._upstreamConnector) {
+                await this.runEnvelopeListeners('onForwardUpstreamComplete', 1, [
+                    this,
+                    processedEnvelope,
+                    undefined,
+                    undefined,
+                    context,
+                ]);
+                return;
+            }
+            const manager = this._sessionManager;
+            if (!manager || !(manager instanceof UpstreamSessionManager)) {
+                await this.runEnvelopeListeners('onForwardUpstreamComplete', 1, [
+                    this,
+                    processedEnvelope,
+                    undefined,
+                    undefined,
+                    context,
+                ]);
+                return;
+            }
+            await manager.send(processedEnvelope);
+            await this.runEnvelopeListeners('onForwardUpstreamComplete', 1, [
+                this,
+                processedEnvelope,
+                undefined,
+                undefined,
+                context,
+            ]);
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            await this.runEnvelopeListeners('onForwardUpstreamComplete', 1, [
+                this,
+                processedEnvelope ?? envelope,
+                undefined,
+                err,
+                context,
+            ]);
+            throw err;
+        }
+    }
+    hasLocal(address) {
+        if (this._bindingManager.hasBinding(address)) {
+            return true;
+        }
+        try {
+            const [, location] = parseAddress(address.toString());
+            return location === this._physicalPath;
+        }
+        catch {
+            return false;
+        }
+    }
+    gatherSupportedCallbackGrants() {
+        const grants = [];
+        const seen = new Set();
+        const addGrant = (grant) => {
+            let signature = null;
+            try {
+                signature = JSON.stringify(grant);
+            }
+            catch {
+                // Non-serializable grant; allow duplicates to ensure availability
+            }
+            if (signature !== null) {
+                if (seen.has(signature)) {
+                    return;
+                }
+                seen.add(signature);
+            }
+            grants.push(grant);
+        };
+        const processCandidate = (candidate) => {
+            if (!candidate || typeof candidate !== 'object') {
+                return;
+            }
+            try {
+                const asAny = candidate;
+                let grant;
+                if (typeof asAny.asCallbackGrant === 'function') {
+                    grant = asAny.asCallbackGrant();
+                }
+                else if (typeof asAny.getCallbackGrant === 'function') {
+                    grant = asAny.getCallbackGrant();
+                }
+                if (grant) {
+                    addGrant(grant);
+                }
+            }
+            catch (error) {
+                logger.warning('callback_grant_collection_failed', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        };
+        for (const listener of this._transportListeners) {
+            processCandidate(listener);
+        }
+        for (const listener of this._eventListeners) {
+            if (this._transportListeners.includes(listener)) {
+                continue;
+            }
+            processCandidate(listener);
+        }
+        return grants;
+    }
+    async dispatchEvent(eventName, ...args) {
+        for (const listener of this._eventListeners) {
+            const handler = resolveListenerMethod(listener, eventName);
+            if (handler) {
+                await handler(...args);
+            }
+        }
+    }
+    async dispatchEnvelopeEvent(eventName, ...args) {
+        const argsWithNode = args.length > 0 && args[0] === this ? args : [this, ...args];
+        const envelopeIndex = argsWithNode.findIndex((value) => value && typeof value === 'object' && 'frame' in value);
+        if (envelopeIndex === -1) {
+            throw new Error(`dispatchEnvelopeEvent(${eventName}) requires an envelope argument`);
+        }
+        return this.runEnvelopeListeners(eventName, envelopeIndex, argsWithNode);
+    }
+    computeSid(physicalPath) {
+        return secureDigest(physicalPath);
+    }
+    async runEnvelopeListeners(eventName, envelopeIndex, args) {
+        let currentEnvelope = args[envelopeIndex] ?? null;
+        for (const listener of this._eventListeners) {
+            const handler = resolveListenerMethod(listener, eventName);
+            if (!handler) {
+                continue;
+            }
+            const result = await handler(...args);
+            if (result === null) {
+                return null;
+            }
+            if (result !== undefined) {
+                currentEnvelope = result;
+                args[envelopeIndex] = currentEnvelope;
+            }
+        }
+        return currentEnvelope;
+    }
+    async persistNodeMeta() {
+        try {
+            const store = await this._nodeMetaStorePromise;
+            const existing = await store.get('self');
+            const record = existing
+                ? Object.assign(existing, { id: this._id })
+                : new NodeMetaRecord(this._id);
+            await store.set('self', record);
+        }
+        catch (error) {
+            logger.warning('node_meta_persist_failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}
+//# sourceMappingURL=node.js.map