@zlink-systems/framework 0.10.0

package/src/runtime/locations/auto-connect-loop.ts

@@ -0,0 +1,131 @@
+import {
+  zlinkRuntimeDefaultLocationOptions,
+  type ZLinkLocationOptionOverrides
+} from '../../contracts/Locations/Options';
+import type { ZLinkDomainLocationStore as ZLinkLocationStore } from './domain-store-contract';
+import type { ZLinkOwnerLeaseTracker } from './lease-tracker';
+import type { ZLinkAutoConnectLocal } from './auto-connect-types';
+import type { ZLinkAutoConnectReconciler } from './auto-connect-reconciler';
+import { ZLinkStateLane } from '../execution/state-lane';
+
+export interface ZLinkAutoConnectLoopOptions {
+  readonly reconciler: ZLinkAutoConnectReconciler;
+  readonly local: ZLinkAutoConnectLocal;
+  readonly options?: ZLinkLocationOptionOverrides;
+  readonly changeStampStore?: Pick<ZLinkLocationStore, 'getMeshNodeChangeStamp'>;
+  readonly leaseTracker?: ZLinkOwnerLeaseTracker;
+  readonly setTimer?: (callback: () => void, delayMs: number) => unknown;
+  readonly clearTimer?: (handle: unknown) => void;
+}
+
+export class ZLinkAutoConnectLoop {
+  private readonly lane = new ZLinkStateLane();
+  private readonly reconciler: ZLinkAutoConnectReconciler;
+  private readonly options: Required<ZLinkLocationOptionOverrides>;
+  private readonly meshName: string;
+  private readonly changeStampStore?: Pick<ZLinkLocationStore, 'getMeshNodeChangeStamp'>;
+  private readonly leaseTracker?: ZLinkOwnerLeaseTracker;
+  private readonly setTimer: (callback: () => void, delayMs: number) => unknown;
+  private readonly clearTimer: (handle: unknown) => void;
+  private controller?: AbortController;
+  private timer?: unknown;
+  private lastStamp?: bigint;
+  private lastLiveOwnerSetVersion?: number;
+  private lastTickFailed = false;
+
+  constructor(options: ZLinkAutoConnectLoopOptions) {
+    this.reconciler = options.reconciler;
+    this.options = { ...zlinkRuntimeDefaultLocationOptions, ...options.options };
+    this.meshName = options.local.meshName;
+    this.changeStampStore = options.changeStampStore;
+    this.leaseTracker = options.leaseTracker;
+    this.setTimer = options.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+    this.clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle as NodeJS.Timeout));
+  }
+
+  async start(signal?: AbortSignal): Promise<void> {
+    if (await this.lane.run(() => this.controller !== undefined)) return;
+    await this.tick(signal);
+    const started = await this.lane.run(() => {
+      if (this.controller !== undefined) return false;
+      this.controller = new AbortController();
+      return true;
+    });
+    if (!started) return;
+    this.scheduleNext();
+  }
+
+  async stop(signal?: AbortSignal): Promise<void> {
+    await this.prepareTransportShutdown();
+    await this.finishTransportShutdown(signal);
+  }
+
+  async prepareTransportShutdown(): Promise<void> {
+    const controller = this.controller;
+    this.controller = undefined;
+    if (controller !== undefined) {
+      controller.abort();
+    }
+    if (this.timer !== undefined) {
+      this.clearTimer(this.timer);
+      this.timer = undefined;
+    }
+    this.reconciler.disconnectPeers();
+  }
+
+  async finishTransportShutdown(signal?: AbortSignal): Promise<void> {
+    await this.reconciler.unpublishLocal(signal);
+  }
+
+  async tick(signal?: AbortSignal): Promise<void> {
+    const lastTickFailed = await this.lane.run(() => this.lastTickFailed);
+    if (this.changeStampStore?.getMeshNodeChangeStamp !== undefined && !lastTickFailed) {
+      try {
+        const stamp = await this.changeStampStore.getMeshNodeChangeStamp(this.meshName, signal);
+        const liveOwners = this.leaseTracker === undefined
+          ? 0
+          : await this.leaseTracker.getLiveOwnerSetVersion(signal);
+        if (this.lastStamp === stamp
+          && this.lastLiveOwnerSetVersion === liveOwners
+          && this.reconciler.localPublicationReady) {
+          return;
+        }
+        const tickFailed = await this.runReconcile(signal);
+        if (!tickFailed) await this.lane.run(() => {
+          this.lastStamp = stamp;
+          this.lastLiveOwnerSetVersion = liveOwners;
+        });
+        return;
+      } catch {
+        // A failed stamp read degrades to a full reconcile tick.
+      }
+    }
+
+    await this.runReconcile(signal);
+    await this.lane.run(() => {
+      this.lastStamp = undefined;
+      this.lastLiveOwnerSetVersion = undefined;
+    });
+  }
+
+  private async runReconcile(signal?: AbortSignal): Promise<boolean> {
+    await this.reconciler.tick(signal);
+    return await this.lane.run(() => {
+      this.lastTickFailed = this.reconciler.storeFailed;
+      return this.lastTickFailed;
+    });
+  }
+
+  private scheduleNext(): void {
+    if (this.controller === undefined || this.controller.signal.aborted) {
+      return;
+    }
+    this.timer = this.setTimer(() => {
+      this.timer = undefined;
+      void this.tick(this.controller?.signal)
+        .catch(() => undefined)
+        .finally(() => this.scheduleNext());
+    }, this.options.pollingIntervalMs);
+  }
+
+}

package/src/runtime/locations/auto-connect-planner.ts

@@ -0,0 +1,178 @@
+import {
+  ZLinkLocationAutoConnectType,
+  ZLinkLocationRole,
+  type ZLinkPeerLocation
+} from './internal-location-contracts';
+import { zlinkLocationRoleName } from './canonical-codec';
+import { ZLinkLocationKeyCodec } from './key-codec';
+import { routingIdsEqual } from '../routing-id';
+import type {
+  ZLinkAutoConnectLocal,
+  ZLinkAutoConnectTarget
+} from './auto-connect-types';
+import { routeMeshConnectionNotRequired } from '../foundation/route-mesh-connection-policy';
+
+const encodeRoutingIdHex = ZLinkLocationKeyCodec.encodeRoutingIdHex;
+
+export const ZLinkAutoConnectPlanner = Object.freeze({
+  isRoleAllowed(type: ZLinkLocationAutoConnectType, role: ZLinkLocationRole): boolean {
+    switch (type) {
+      case ZLinkLocationAutoConnectType.RouteMesh:
+        return role === ZLinkLocationRole.Router;
+      case ZLinkLocationAutoConnectType.Fanout:
+        return role === ZLinkLocationRole.Pub || role === ZLinkLocationRole.Sub;
+      default:
+        return false;
+    }
+  },
+
+  computeDesired(
+    local: ZLinkAutoConnectLocal,
+    peers: readonly ZLinkPeerLocation[],
+    includeDraining = false
+  ): ReadonlyMap<string, ZLinkAutoConnectTarget> {
+    const desired = new Map<string, ZLinkAutoConnectTarget>();
+    for (const peer of peers) {
+      if (!isCandidate(local, peer, includeDraining)) {
+        continue;
+      }
+
+      if (!shouldDialAutoConnectPeer(local, peer)) continue;
+
+      const target = targetOf(peer);
+      desired.set(target.targetKey, target);
+    }
+    return desired;
+  },
+
+  computeCandidates(
+    local: ZLinkAutoConnectLocal,
+    peers: readonly ZLinkPeerLocation[]
+  ): ReadonlyMap<string, ZLinkAutoConnectTarget> {
+    const candidates = new Map<string, ZLinkAutoConnectTarget>();
+    for (const peer of peers) {
+      if (!isCandidate(local, peer, true)) continue;
+      const target = targetOf(peer);
+      candidates.set(target.targetKey, target);
+    }
+    return candidates;
+  },
+
+  targetKeyOf(peer: ZLinkPeerLocation): string {
+    return autoConnectTargetKeyOf(peer);
+  },
+
+  computeNotRequired(
+    local: ZLinkAutoConnectLocal,
+    peers: readonly ZLinkPeerLocation[]
+  ): readonly ZLinkAutoConnectTarget[] {
+    if (local.autoConnectType !== ZLinkLocationAutoConnectType.RouteMesh) {
+      return [];
+    }
+    return peers
+      .filter(peer =>
+        peer.autoConnectType === local.autoConnectType
+        && peer.meshName === local.meshName
+        && peer.endpoint.length > 0
+        && !isAutoConnectSelf(local, peer)
+        && routeMeshConnectionNotRequired(
+          local.objectRole ?? 'none',
+          local.hasRouteMeshServerChannel ?? false,
+          peer.metadata?.objectRole === 'client'
+            ? 'client'
+            : peer.metadata?.objectRole === 'server' ? 'server' : 'none',
+          peer.metadata?.hasRouteMeshServerChannel === 'true'
+        ))
+      .map(peer => ({
+        targetKey: autoConnectTargetKeyOf(peer),
+        nodeRid: peer.nodeRid,
+        lifecycleGeneration: peer.generation,
+        role: peer.role,
+        endpoint: peer.endpoint,
+        metadata: peer.metadata,
+        ownerId: peer.ownerId,
+        descriptorRevision: parseDescriptorRevision(peer.metadata?.descriptorRevision)
+      }));
+  }
+});
+
+function autoConnectTargetKeyOf(peer: ZLinkPeerLocation): string {
+  const identity = peer.nodeRid === undefined ? peer.endpoint : encodeRoutingIdHex(peer.nodeRid);
+  return `${zlinkLocationRoleName(peer.role)}|${identity}|${peer.generation}`;
+}
+
+function isCandidate(
+  local: ZLinkAutoConnectLocal,
+  peer: ZLinkPeerLocation,
+  includeDraining: boolean
+): boolean {
+  return peer.autoConnectType === local.autoConnectType
+    && peer.meshName === local.meshName
+    && (includeDraining || !peer.draining)
+    && ZLinkAutoConnectPlanner.isRoleAllowed(peer.autoConnectType, peer.role)
+    && peer.endpoint.length > 0
+    && !isAutoConnectSelf(local, peer);
+}
+
+function targetOf(peer: ZLinkPeerLocation): ZLinkAutoConnectTarget {
+  return {
+    targetKey: autoConnectTargetKeyOf(peer),
+    nodeRid: peer.nodeRid,
+    lifecycleGeneration: peer.generation,
+    role: peer.role,
+    endpoint: peer.endpoint,
+    metadata: peer.metadata,
+    ownerId: peer.ownerId
+  };
+}
+
+function isAutoConnectSelf(local: ZLinkAutoConnectLocal, peer: ZLinkPeerLocation): boolean {
+  if (local.nodeRid !== undefined && peer.nodeRid !== undefined && routingIdsEqual(local.nodeRid, peer.nodeRid)) {
+    return true;
+  }
+  return peer.endpoint === local.endpoint;
+}
+
+function shouldDialAutoConnectPeer(local: ZLinkAutoConnectLocal, peer: ZLinkPeerLocation): boolean {
+  switch (local.autoConnectType) {
+    case ZLinkLocationAutoConnectType.RouteMesh:
+      return local.role === ZLinkLocationRole.Router
+        && peer.role === ZLinkLocationRole.Router
+        && !routeMeshConnectionNotRequired(
+          local.objectRole ?? 'none',
+          local.hasRouteMeshServerChannel ?? false,
+          peer.metadata?.objectRole === 'client'
+            ? 'client'
+            : peer.metadata?.objectRole === 'server' ? 'server' : 'none',
+          peer.metadata?.hasRouteMeshServerChannel === 'true'
+        )
+        && localIsPairwiseInitiator(local, peer);
+    case ZLinkLocationAutoConnectType.Fanout:
+      return local.role === ZLinkLocationRole.Sub && peer.role === ZLinkLocationRole.Pub;
+    default:
+      return false;
+  }
+}
+
+function parseDescriptorRevision(value: string | undefined): bigint | undefined {
+  if (value === undefined) return undefined;
+  try {
+    const revision = BigInt(value);
+    return revision > 0n ? revision : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function localIsPairwiseInitiator(local: ZLinkAutoConnectLocal, peer: ZLinkPeerLocation): boolean {
+  if (local.endpoint.length === 0) {
+    return true;
+  }
+  if (local.nodeRid !== undefined && peer.nodeRid !== undefined) {
+    const byRid = encodeRoutingIdHex(local.nodeRid).localeCompare(encodeRoutingIdHex(peer.nodeRid));
+    if (byRid !== 0) {
+      return byRid < 0;
+    }
+  }
+  return local.endpoint.localeCompare(peer.endpoint) < 0;
+}