@zlink-systems/framework 0.10.0

package/dist/runtime/spots/spot-node-autoconnect.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSpotNodeLocationAutoConnectContext = createSpotNodeLocationAutoConnectContext;
+exports.spotNodeAutoConnectCapability = spotNodeAutoConnectCapability;
+const Values_1 = require("../../contracts/Locations/Values");
+const contracts_1 = require("../../contracts");
+const node_async_hooks_1 = require("node:async_hooks");
+const state_lane_1 = require("../execution/state-lane");
+const routing_id_1 = require("../routing-id");
+const locations_1 = require("../locations");
+function createSpotNodeLocationAutoConnectContext(runtime, stores, options, events) {
+    const leaseTracker = new locations_1.ZLinkOwnerLeaseTracker({
+        store: stores.ownerLeaseStore,
+        options
+    });
+    return {
+        runtime,
+        stores,
+        options,
+        leaseTracker,
+        resolver: meshDescriptorPeerResolver(runtime),
+        events,
+        // The opaque provider has no cross-process change notification primitive.
+        // A process-local inherited stamp would hide descriptors written by peers,
+        // so RouteMesh discovery polls the authoritative descriptor scan.
+        changeStampStore: undefined
+    };
+}
+function spotNodeAutoConnectCapability(spotNodeName, spotNode, node) {
+    if (spotNode.router === undefined) {
+        return undefined;
+    }
+    // The node has already started when this capability is built. Publishing
+    // the configured bind string would advertise port 0 for wildcard binds,
+    // so peers must receive the concrete endpoint resolved by Core.
+    const status = node.status();
+    const endpoint = status.localEndpoint;
+    const local = {
+        autoConnectType: Values_1.ZLinkLocationAutoConnectType.RouteMesh,
+        meshName: spotNodeName,
+        role: contracts_1.ZLinkLocationRole.Router,
+        nodeRid: String(status.routingId),
+        endpoint,
+        objectRole: spotNode.objectRole ?? 'none',
+        hasRouteMeshServerChannel: Object.values(spotNode.meshChannels ?? {})
+            .some((channel) => channel.server === true)
+    };
+    const manualConnections = hasManualRouterConnections(spotNode);
+    return {
+        local,
+        executor: new ZLinkSpotNodeAutoConnectExecutor(node, manualConnections)
+    };
+}
+function meshDescriptorPeerResolver(runtime) {
+    return {
+        async listLivePeers(filter, signal) {
+            if (filter.meshName === undefined
+                || (filter.autoConnectType !== undefined
+                    && filter.autoConnectType !== Values_1.ZLinkLocationAutoConnectType.RouteMesh)
+                || (filter.role !== undefined
+                    && filter.role !== contracts_1.ZLinkLocationRole.Router)) {
+                return [];
+            }
+            const descriptors = await runtime.listLiveMeshNodes(filter.meshName, signal);
+            return descriptors
+                .map((descriptor) => ({
+                autoConnectType: Values_1.ZLinkLocationAutoConnectType.RouteMesh,
+                meshName: descriptor.meshName,
+                nodeRid: descriptor.rid,
+                role: contracts_1.ZLinkLocationRole.Router,
+                endpoint: descriptor.endpoint,
+                weight: 100,
+                draining: descriptor.state !== contracts_1.ZLinkFrameworkRuntimeState.Serving,
+                value: descriptor.descriptorRevision,
+                ownerId: descriptor.ownerId,
+                generation: descriptor.lifecycleGeneration,
+                updatedAt: descriptor.updatedAt,
+                metadata: {
+                    objectRole: descriptor.objectRole,
+                    hasRouteMeshServerChannel: String(Object.keys(descriptor.channelWeights).length > 0),
+                    descriptorRevision: descriptor.descriptorRevision.toString(),
+                    securityIdentity: descriptor.securityIdentity
+                }
+            }))
+                .filter(peer => (filter.nodeRid === undefined || String(peer.nodeRid) === String(filter.nodeRid))
+                && (filter.endpoint === undefined || peer.endpoint === filter.endpoint));
+        }
+    };
+}
+function hasManualRouterConnections(spotNode) {
+    return (spotNode.router?.manualConnections?.length ?? 0) > 0
+        || (spotNode.router?.manualPeerConnections?.length ?? 0) > 0;
+}
+const detachedSpotNodeAutoConnectResource = new node_async_hooks_1.AsyncResource('zlink:spot-node-autoconnect');
+class ZLinkSpotNodeAutoConnectExecutor {
+    node;
+    manualConnections;
+    lane = new state_lane_1.ZLinkStateLane();
+    connectionIntents = new Map();
+    constructor(node, manualConnections) {
+        this.node = node;
+        this.manualConnections = manualConnections;
+    }
+    onDisconnected(handler) {
+        this.node.onPeerDisconnected?.(handler);
+    }
+    async connect(target) {
+        if (this.manualConnections)
+            return false;
+        const key = connectionKey(target);
+        const intent = await this.lane.run(() => this.prepareConnectCore(key));
+        if (intent === undefined)
+            return true;
+        return await runDetachedSpotNodeAutoConnect(() => this.connectPeer(target, key, intent));
+    }
+    disconnect(target) {
+        if (this.manualConnections)
+            return;
+        this.disconnectPeer(target);
+    }
+    disconnectStalePeers(targets) {
+        if (this.manualConnections)
+            return;
+        const current = new Map(targets
+            .filter((target) => target.nodeRid !== undefined)
+            .map((target) => [String(target.nodeRid), target]));
+        const peers = this.node.peers();
+        for (const peer of peers) {
+            if (peer.routingId === null)
+                continue;
+            const target = current.get(String(peer.routingId));
+            if (target !== undefined
+                && peer.endpoint === target.endpoint) {
+                continue;
+            }
+            this.node.disconnectPeer(peer.routingId, peer.lifecycleGeneration);
+        }
+    }
+    isDisconnected(target) {
+        // A connect intent still owns transport state even when its peer has not
+        // reached the admitted table yet. Shutdown must remove that intent before
+        // it can treat the automatic route as disconnected.
+        if (this.connectionIntents.has(connectionKey(target)))
+            return false;
+        return !this.node.peers().some((peer) => peer.routingId !== null &&
+            peer.endpoint === target.endpoint &&
+            (target.nodeRid === undefined || String(peer.routingId) === String(target.nodeRid)) &&
+            peer.lifecycleGeneration === target.lifecycleGeneration &&
+            peer.state === 3);
+    }
+    replaceNotRequired(targets) {
+        this.node.replaceDiscoveredNotRequiredPeers?.(targets
+            .filter((target) => target.nodeRid !== undefined)
+            .map(target => ({
+            nodeRoutingId: String(target.nodeRid),
+            lifecycleGeneration: target.lifecycleGeneration,
+            descriptorRevision: target.descriptorRevision ?? 1n,
+            endpoint: target.endpoint
+        })));
+    }
+    expectPeers(targets) {
+        for (const target of targets) {
+            if (target.nodeRid === undefined)
+                continue;
+            this.node.expectPeer?.({
+                nodeRoutingId: String(target.nodeRid),
+                endpoint: target.endpoint,
+                securityIdentity: toAdmissionSecurityIdentity(target.metadata?.securityIdentity),
+                lifecycleGeneration: target.lifecycleGeneration
+            });
+        }
+    }
+    prepareConnectCore(key) {
+        if (this.connectionIntents.has(key))
+            return undefined;
+        const intent = {};
+        this.connectionIntents.set(key, intent);
+        return intent;
+    }
+    async connectPeer(target, key, intent) {
+        try {
+            const connectionIntentId = await this.node.connectPeer({
+                endpoint: target.endpoint,
+                expectedRid: target.nodeRid === undefined
+                    ? undefined
+                    : (0, routing_id_1.toBackendRoutingId)(target.nodeRid),
+                expectedSecurityIdentity: toAdmissionSecurityIdentity(target.metadata?.securityIdentity),
+                expectedLifecycleGeneration: target.lifecycleGeneration
+            });
+            const accepted = await this.lane.run(() => {
+                if (this.connectionIntents.get(key) !== intent)
+                    return false;
+                intent.connectionIntentId = connectionIntentId;
+                return true;
+            });
+            if (!accepted)
+                this.node.removePeerConnection(connectionIntentId);
+            return accepted;
+        }
+        catch {
+            // A discovered endpoint can become unavailable between the store read and
+            // the socket connect. Leave the target inactive so the next reconciliation
+            // can retry without terminating the host's background runtime.
+            await this.lane.run(() => {
+                if (this.connectionIntents.get(key) === intent)
+                    this.connectionIntents.delete(key);
+            });
+            return false;
+        }
+    }
+    disconnectPeer(target) {
+        const key = connectionKey(target);
+        const intent = this.connectionIntents.get(key);
+        if (intent !== undefined) {
+            this.connectionIntents.delete(key);
+            if (intent.connectionIntentId !== undefined) {
+                this.node.removePeerConnection(intent.connectionIntentId);
+            }
+        }
+        for (const peer of this.node.peers()) {
+            if (peer.routingId === null) {
+                continue;
+            }
+            if (peer.endpoint !== target.endpoint) {
+                continue;
+            }
+            if (target.nodeRid !== undefined && String(peer.routingId) !== String(target.nodeRid)) {
+                continue;
+            }
+            this.node.disconnectPeer(peer.routingId, peer.lifecycleGeneration);
+        }
+    }
+}
+function runDetachedSpotNodeAutoConnect(work) {
+    return detachedSpotNodeAutoConnectResource.runInAsyncScope(work);
+}
+function connectionKey(target) {
+    return `${target.nodeRid ?? ''}\0${target.lifecycleGeneration}\0${target.endpoint}`;
+}
+// Location descriptors identify an unauthenticated transport as "plaintext";
+// RouteMesh admission carries its canonical wire identity, "default". The
+// expectation must use the wire value while authenticated identities remain
+// exact descriptor fences.
+function toAdmissionSecurityIdentity(identity) {
+    return identity === 'plaintext' ? 'default' : identity;
+}

package/dist/runtime/spots/spot-node-runtime-manager.d.ts

@@ -0,0 +1,137 @@
+import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
+import type { ActorRef, RoutingId, ZLinkActor, ZLinkChannelClient, ZLinkFanoutClient, ZLinkMessage, ZLinkMeshNodeDescriptor, ZLinkMessageSerializer, ZLinkSpotPublisherClient } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
+import { ZLinkFrameworkRuntimeState } from '../../contracts';
+import { type ZLinkSubmitResult } from '../messaging/submission-result';
+import { type ReadyRecord, type ReceiveRecord } from '../foundation/service-runtime-contracts';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
+import { type ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkBackendAdapterFactory, ZLinkBackendContext, ZLinkBackendMeshNode } from '../backend/contracts';
+import { ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
+import type { ZLinkDispatchErrorReporter } from '../channels';
+import { ZLinkLocationRuntime, type ZLinkLocationEventSink, type ZLinkLocationRuntimeStores } from '../locations';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkActorHandoffPacket } from '../actors/actor-handoff';
+import type { ZLinkDetachedTaskRunner } from './spot-actor-join-dispatch';
+import type { ZLinkSpotRoutedTransport } from './spot-outbound';
+import type { ZLinkSpotRouteResolver } from './spot-routing-internal';
+import type { ZLinkEntryActorRuntime, ZLinkSpotActorTransferRuntime, ZLinkSpotActorHandoffRuntime, ZLinkSpotBoundSessionRuntime } from './spot-runtime-ports';
+import type { ServiceMessageFollowRecord } from '../foundation/service-stateful-wire-codec';
+import { ApplicationJobQueue } from '../host/application-job-queue';
+export interface ZLinkSpotNodeRuntimeManagerOptions {
+    readonly registration: ZLinkFrameworkRegistration;
+    readonly primaryMeshName?: string;
+    readonly backendAdapterFactory: ZLinkBackendAdapterFactory;
+    readonly context: ZLinkBackendContext;
+    readonly channelClient?: ZLinkChannelClient;
+    readonly fanoutClient?: ZLinkFanoutClient;
+    readonly spotPublisherClient?: ZLinkSpotPublisherClient;
+    readonly spotRouteResolver?: ZLinkSpotRouteResolver;
+    readonly routedTransport?: ZLinkSpotRoutedTransport;
+    readonly spotRouterChannelIdForMesh?: (meshName: string) => string;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
+    readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
+    readonly metrics?: import('../diagnostics').ZLinkRuntimeMetrics;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly entryActorRuntime?: ZLinkEntryActorRuntime;
+    readonly actorTransferRuntime?: ZLinkSpotActorTransferRuntime;
+    readonly boundSessionRuntime?: ZLinkSpotBoundSessionRuntime;
+    readonly actorHandoffRuntime?: ZLinkSpotActorHandoffRuntime;
+    readonly detachedTaskRunner?: ZLinkDetachedTaskRunner;
+    readonly applicationJobQueue?: ApplicationJobQueue;
+    readonly applicationJobReceiveFlowFailureSink?: (error: unknown) => void;
+    readonly peerAdmissionSealed?: (meshName: string) => boolean;
+    readonly meshRecordDispatcher?: (meshName: string, owner: ReadyRecord, record: ReceiveRecord) => void | Promise<void>;
+    readonly messageFollowReceiver?: (record: ServiceMessageFollowRecord) => void;
+    readonly instanceActivationConcurrencyProvider?: (meshName: string) => {
+        readonly active: number;
+        readonly limit: number;
+    };
+}
+export declare class ZLinkSpotNodeRuntimeManager {
+    private readonly options;
+    private readonly meshNodes;
+    private readonly meshPumps;
+    private readonly meshCompletions;
+    private readonly entryActivations;
+    private readonly entryActivationStarts;
+    private readonly publishers;
+    private readonly activePublishes;
+    private readonly publishSlotWaiters;
+    private disposed;
+    private readonly autoConnectLoops;
+    private readonly publishedMeshNodeDescriptors;
+    private readonly descriptorRevisionByMesh;
+    private publishedOwnerToken?;
+    private readonly runtimePlacementWeights;
+    private readonly runtimeChannelWeights;
+    private readonly entrySpotIds;
+    private runtimeWeightPublication;
+    private statePublication;
+    private locationAutoConnect?;
+    private readonly applicationJobQueue;
+    constructor(options: ZLinkSpotNodeRuntimeManagerOptions);
+    createReceived(): import("../backend/runtime-values").ZLinkBackendReceived;
+    createTopicMessage(): import("../backend/runtime-values").ZLinkBackendTopicMessage;
+    configureLocationAutoConnect(runtime: ZLinkLocationRuntime, stores: ZLinkLocationRuntimeStores, options: ZLinkLocationOptionOverrides, events?: ZLinkLocationEventSink): void;
+    startLocationAutoConnect(signal?: AbortSignal): Promise<void>;
+    /**
+     * Fences transport connections that were created under an owner token which
+     * is no longer valid. The loops are discarded so a later owner renewal can
+     * build them again with the current lifecycle descriptor.
+     */
+    fenceLocationAutoConnect(): Promise<void>;
+    start(): Promise<void>;
+    publishMeshNodeState(state: ZLinkFrameworkRuntimeState, signal?: AbortSignal, selectedMeshName?: string): Promise<void>;
+    private publishMeshNodeStateCore;
+    reconcileAndPublishMeshNodeState(state: ZLinkFrameworkRuntimeState, meshName: string, signal?: AbortSignal): Promise<void>;
+    private entrySpotId;
+    get meshNodesByName(): ReadonlyMap<string, ZLinkBackendMeshNode>;
+    meshNode(meshName: string): ZLinkBackendMeshNode | undefined;
+    sendMessageFollowNotification(sourceNodeRid: RoutingId, targetNodeRid: RoutingId, record: Omit<ServiceMessageFollowRecord, 'kind'>): Promise<boolean>;
+    entrySpotIdForMesh(meshName: string): string | undefined;
+    meshNodeDescriptor(meshName: string): ZLinkMeshNodeDescriptor | undefined;
+    placementWeight(meshName: string): number;
+    channelWeight(channelName: string): number;
+    setRuntimePlacementWeight(meshName: string, weight: number): void;
+    setRuntimeChannelWeight(channelName: string, weight: number): void;
+    waitForRuntimeWeightPublication(): Promise<void>;
+    meshCompletionTable(meshName: string): ZLinkMeshCompletionTable | undefined;
+    get primaryMeshNode(): ZLinkBackendMeshNode | undefined;
+    private effectiveChannelWeight;
+    private resolveChannel;
+    private scheduleRuntimeWeightPublication;
+    get primaryMeshCompletions(): ZLinkMeshCompletionTable | undefined;
+    notifyEntrySpotActorCreated(nodeRid: RoutingId, actor: ZLinkActor, createRequest: ZLinkMessage, signal?: AbortSignal): Promise<import('../../contracts').ZLinkActorCreateResponse | undefined>;
+    notifyPrimaryEntrySpotActorJoined(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
+    notifyPrimaryEntrySpotActorLeft(actor: ZLinkActor, signal?: AbortSignal, actorRef?: ActorRef, membershipEpoch?: bigint): Promise<void>;
+    notifyPrimaryEntrySpotActorDisconnected(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
+    notifyEntrySpotActorDisconnected(meshName: string, actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
+    serverChannels(meshName: string): [string, import("../configuration").ZLinkMeshChannelOptions][];
+    dispose(signal?: AbortSignal, deadline?: Date): Promise<void>;
+    private dispatchMeshRecord;
+    dispatchEntrySpotRecord(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<boolean>;
+    private ensureEntryActivation;
+    private initializeEntrySpot;
+    private primaryEntryActivation;
+    dispatchEntryActorPacket(actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
+    dispatchEntryActorJoin(meshName: string, actor: ZLinkActor, handoffBacklog?: readonly ZLinkActorHandoffPacket[]): Promise<void>;
+    publish(meshName: string, channelName: string, topic: string, packetName: string | undefined, event: Message, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
+    private executePublish;
+    tryPublish(meshName: string, channelName: string, topic: string, packetName: string | undefined, event: Message, metadata?: ReadonlyMap<string, string>): ZLinkSubmitResult;
+    private publishWithFlags;
+    private acquirePublishSlot;
+    private publishTimedOut;
+    private releasePublishSlot;
+    private settlePublishSlotWaiter;
+    private rejectPublishSlotWaiter;
+    private removePublishSlotWaiter;
+    private cleanupPublishSlotWaiter;
+    private rejectPublishSlotWaiters;
+    private takePublishSlotWaiter;
+    private compactPublishSlotWaiters;
+}
+export declare function createFrameworkEntrySpotId(prefix: string): string;