@zlink-systems/framework 0.25.0 → 0.27.0

package/src/runtime/diagnostics/topology-runtime-projections.ts

@@ -21,21 +21,151 @@ import {
 } from './runtime-observation-queue';
 import {
   runtimeStateIsReady,
-  topologyRuntimeIsReady
+  topologyRuntimeIsReady,
+  topologyObservationIsTerminal
 } from '../foundation/runtime-state-projections';
+import type {
+  ClientServerDescriptor,
+  FanoutPublisherDescriptor
+} from '../foundation/service-discovery-registry';
 
 export { RuntimeEventQueue } from './runtime-observation-queue';
 
 type RuntimeAccessor = () => ZLinkChannelRuntimeManager | undefined;
 type HostStateAccessor = () => ZLinkFrameworkRuntimeState;
-interface HostObserver {
-  readonly changed: () => void;
-  readonly stop: () => void;
+type TopologyStatus = ZLinkClientServerStatus | ZLinkFanoutStatus;
+interface TopologySource<T extends TopologyStatus> {
+  lastSnapshot?: T;
+  readonly observers: Set<RuntimeEventQueue<T>>;
+  stop?: () => void;
+}
+
+class TopologyStatusSources<T extends TopologyStatus> {
+  private readonly sources = new Map<string, TopologySource<T>>();
+
+  constructor(
+    private readonly read: (channelName: string, sequence: bigint) => T,
+    private readonly subscribe: (channelName: string, changed: () => void) => () => void,
+    private readonly equivalent: (left: T, right: T) => boolean
+  ) {}
+
+  snapshot(channelName: string): T {
+    let source = this.sources.get(channelName);
+    const current = source?.lastSnapshot;
+    if (current !== undefined && topologyObservationIsTerminal(current.state)) return current;
+    const snapshot = this.read(channelName, current?.sequence ?? 0n);
+    if (source === undefined) {
+      source = { observers: new Set() };
+      this.sources.set(channelName, source);
+    }
+    const published = this.publish(channelName, source, snapshot);
+    if (source.stop === undefined && !topologyObservationIsTerminal(published.state)) {
+      source.stop = this.subscribe(channelName, () => this.snapshot(channelName));
+    }
+    return published;
+  }
+
+  observe(
+    channelName: string,
+    capacity: number,
+    signal?: AbortSignal
+  ): AsyncIterable<ZLinkObservedStatus<T>> {
+    const queue = new RuntimeEventQueue<T>(capacity, signal);
+    const snapshot = this.snapshot(channelName);
+    const current = this.sources.get(channelName)!;
+    current.observers.add(queue);
+    queue.onClose(() => {
+      current.observers.delete(queue);
+    });
+    this.deliver(queue, snapshot, channelName);
+    return queue;
+  }
+
+  hostStateChanged(): void {
+    for (const channelName of this.sources.keys()) this.snapshot(channelName);
+  }
+
+  stopObservers(): void {
+    for (const [channelName, source] of this.sources) {
+      if (
+        source.lastSnapshot === undefined ||
+        topologyObservationIsTerminal(source.lastSnapshot.state)
+      )
+        continue;
+      this.publish(channelName, source, {
+        ...source.lastSnapshot,
+        state: ZLinkTopologyState.Stopped,
+        isReady: false
+      });
+    }
+  }
+
+  private publish(channelName: string, source: TopologySource<T>, snapshot: T): T {
+    const previous = source.lastSnapshot;
+    if (previous !== undefined && this.equivalent(previous, snapshot)) return previous;
+    source.lastSnapshot = {
+      ...snapshot,
+      sequence: (previous?.sequence ?? 0n) + 1n,
+      observedAt: new Date()
+    };
+    for (const queue of source.observers) this.deliver(queue, source.lastSnapshot, channelName);
+    if (topologyObservationIsTerminal(source.lastSnapshot.state)) {
+      source.stop?.();
+      source.stop = undefined;
+    }
+    return source.lastSnapshot;
+  }
+
+  private deliver(queue: RuntimeEventQueue<T>, snapshot: T, channelName: string): void {
+    if (topologyObservationIsTerminal(snapshot.state)) queue.seal(snapshot, channelName);
+    else queue.push(snapshot, channelName);
+  }
+}
+
+function sameTopologyState(left: TopologyStatus, right: TopologyStatus): boolean {
+  return left.state === right.state && left.isReady === right.isReady;
+}
+
+function samePeer(left: ZLinkPeerStatus, right: ZLinkPeerStatus): boolean {
+  return (
+    left.nodeRid === right.nodeRid &&
+    left.state === right.state &&
+    left.unavailableReason === right.unavailableReason
+  );
+}
+
+function sameClientServerStatus(
+  left: ZLinkClientServerStatus,
+  right: ZLinkClientServerStatus
+): boolean {
+  return (
+    sameTopologyState(left, right) &&
+    left.localRole === right.localRole &&
+    left.readyTargetCount === right.readyTargetCount &&
+    left.targets.length === right.targets.length &&
+    left.targets.every(
+      (target, index) =>
+        samePeer(target, right.targets[index]!) && target.weight === right.targets[index]!.weight
+    )
+  );
+}
+
+function sameFanoutStatus(left: ZLinkFanoutStatus, right: ZLinkFanoutStatus): boolean {
+  return (
+    sameTopologyState(left, right) &&
+    left.readyPublisherCount === right.readyPublisherCount &&
+    left.publishers.length === right.publishers.length &&
+    left.publishers.every((publisher, index) => samePeer(publisher, right.publishers[index]!))
+  );
 }
 
 export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRuntime {
-  private sequence = 0n;
-  private readonly hostObservers = new Set<HostObserver>();
+  private readonly sources = new TopologyStatusSources<ZLinkClientServerStatus>(
+    (channelName, sequence) => this.snapshotCore(channelName, sequence),
+    (channelName, changed) =>
+      this.requireRuntime().observeClientServerTopology(channelName, changed),
+    sameClientServerStatus
+  );
 
   constructor(
     private readonly runtime: RuntimeAccessor,
@@ -43,34 +173,19 @@ export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRunt
   ) {}
 
   snapshot(channelName: string): ZLinkClientServerStatus {
-    return this.snapshotCore(channelName);
+    return this.sources.snapshot(channelName);
   }
 
-  private snapshotCore(channelName: string): ZLinkClientServerStatus {
+  private snapshotCore(channelName: string, sequence: bigint): ZLinkClientServerStatus {
     const topology = this.requireRuntime().clientServerTopology(channelName);
     if (topology.localRole === undefined) {
       throw new ZLinkConfigurationException(
         `ClientServer channel '${channelName}' is not registered.`
       );
     }
-    const targets = topology.descriptors.map((descriptor): ZLinkClientServerTargetStatus => ({
-      nodeRid: descriptor.serverRoutingId,
-      weight: descriptor.weight,
-      state:
-        descriptor.state === 'serving'
-          ? ZLinkPeerState.Ready
-          : descriptor.state === 'retiring'
-            ? ZLinkPeerState.Draining
-            : descriptor.state === 'preparing'
-              ? ZLinkPeerState.Connecting
-              : ZLinkPeerState.NotConnected,
-      unavailableReason:
-        descriptor.state === 'serving' && descriptor.weight > 0
-          ? undefined
-          : descriptor.state === 'retiring'
-            ? ZLinkTopologyReason.Draining
-            : ZLinkTopologyReason.NoReadyTarget
-    }));
+    const targets = topology.descriptors.map((descriptor) =>
+      peerStatusForAvailability(descriptor, ZLinkTopologyReason.NoReadyTarget)
+    );
     const readyTargetCount = targets.filter(
       (target) => target.state === ZLinkPeerState.Ready && target.weight > 0
     ).length;
@@ -83,7 +198,7 @@ export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRunt
       isReady,
       readyTargetCount,
       targets,
-      sequence: this.sequence,
+      sequence,
       observedAt: new Date()
     };
   }
@@ -93,72 +208,19 @@ export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRunt
     capacity = ZLINK_DEFAULT_TERMINAL_OBSERVATION_CAPACITY,
     signal?: AbortSignal
   ): AsyncIterable<ZLinkObservedStatus<ZLinkClientServerStatus>> {
-    const runtime = this.requireRuntime();
-    const queue = new RuntimeEventQueue<ZLinkClientServerStatus>(capacity, signal);
-    let lastSnapshot = this.snapshotCore(channelName);
-    const stop = runtime.observeClientServerTopology(channelName, () => {
-      this.sequence += 1n;
-      lastSnapshot = this.snapshotCore(channelName);
-      queue.push(lastSnapshot, channelName);
-    });
-    const hostObserver: HostObserver = {
-      changed: () => {
-        this.sequence += 1n;
-        lastSnapshot = this.snapshotCore(channelName);
-        queue.push(lastSnapshot, channelName);
-      },
-      stop: () => {
-        this.sequence += 1n;
-        let current = lastSnapshot;
-        try {
-          current = this.snapshotCore(channelName);
-          lastSnapshot = current;
-        } catch {
-          // The last complete projection remains valid after native teardown.
-        }
-        queue.seal(
-          {
-            ...current,
-            state: ZLinkTopologyState.Stopped,
-            isReady: false,
-            sequence: this.sequence,
-            observedAt: new Date()
-          },
-          channelName
-        );
-      }
-    };
-    this.hostObservers.add(hostObserver);
-    queue.onClose(() => {
-      stop();
-      this.hostObservers.delete(hostObserver);
-    });
-    return queue;
+    return this.sources.observe(channelName, capacity, signal);
   }
 
   hostStateChanged(): void {
-    for (const observer of this.hostObservers) {
-      try {
-        observer.changed();
-      } catch {
-        // Monitoring projection failures do not change host lifecycle results.
-      }
-    }
+    this.sources.hostStateChanged();
   }
 
   stopObservers(): void {
-    for (const observer of [...this.hostObservers]) {
-      try {
-        observer.stop();
-      } catch {
-        // The observer is still removed when its terminal snapshot fails.
-      }
-    }
-    this.hostObservers.clear();
+    this.sources.stopObservers();
   }
 
   isReady(channelName: string): boolean {
-    return this.snapshotCore(channelName).isReady;
+    return this.snapshot(channelName).isReady;
   }
 
   private requireRuntime(): ZLinkChannelRuntimeManager {
@@ -170,8 +232,11 @@ export class ZLinkClientServerRuntimeProjection implements ZLinkClientServerRunt
 }
 
 export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
-  private sequence = 0n;
-  private readonly hostObservers = new Set<HostObserver>();
+  private readonly sources = new TopologyStatusSources<ZLinkFanoutStatus>(
+    (channelName, sequence) => this.snapshotCore(channelName, sequence),
+    (channelName, changed) => this.requireRuntime().observeFanoutTopology(channelName, changed),
+    sameFanoutStatus
+  );
 
   constructor(
     private readonly runtime: RuntimeAccessor,
@@ -179,29 +244,15 @@ export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
   ) {}
 
   snapshot(channelName: string): ZLinkFanoutStatus {
-    return this.snapshotCore(channelName);
+    return this.sources.snapshot(channelName);
   }
 
-  private snapshotCore(channelName: string): ZLinkFanoutStatus {
+  private snapshotCore(channelName: string, sequence: bigint): ZLinkFanoutStatus {
     const publishers = this.requireRuntime()
       .fanoutTopology(channelName)
-      .descriptors.map((descriptor): ZLinkPeerStatus => ({
-        nodeRid: descriptor.publisherRoutingId,
-        state:
-          descriptor.state === 'serving'
-            ? ZLinkPeerState.Ready
-            : descriptor.state === 'retiring'
-              ? ZLinkPeerState.Draining
-              : descriptor.state === 'preparing'
-                ? ZLinkPeerState.Connecting
-                : ZLinkPeerState.NotConnected,
-        unavailableReason:
-          descriptor.state === 'serving'
-            ? undefined
-            : descriptor.state === 'retiring'
-              ? ZLinkTopologyReason.Draining
-              : ZLinkTopologyReason.NoReadyTarget
-      }));
+      .descriptors.map((descriptor) =>
+        peerStatusForAvailability(descriptor, ZLinkTopologyReason.NoReadyPeer)
+      );
     const readyPublisherCount = publishers.filter(
       (publisher) => publisher.state === ZLinkPeerState.Ready
     ).length;
@@ -217,7 +268,7 @@ export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
       isReady: topologyRuntimeIsReady(hostState, readyPublisherCount),
       readyPublisherCount,
       publishers,
-      sequence: this.sequence,
+      sequence,
       observedAt: new Date()
     };
   }
@@ -227,68 +278,15 @@ export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
     capacity = ZLINK_DEFAULT_TERMINAL_OBSERVATION_CAPACITY,
     signal?: AbortSignal
   ): AsyncIterable<ZLinkObservedStatus<ZLinkFanoutStatus>> {
-    const runtime = this.requireRuntime();
-    const queue = new RuntimeEventQueue<ZLinkFanoutStatus>(capacity, signal);
-    let lastSnapshot = this.snapshotCore(channelName);
-    const stop = runtime.observeFanoutTopology(channelName, () => {
-      this.sequence += 1n;
-      lastSnapshot = this.snapshotCore(channelName);
-      queue.push(lastSnapshot, channelName);
-    });
-    const hostObserver: HostObserver = {
-      changed: () => {
-        this.sequence += 1n;
-        lastSnapshot = this.snapshotCore(channelName);
-        queue.push(lastSnapshot, channelName);
-      },
-      stop: () => {
-        this.sequence += 1n;
-        let current = lastSnapshot;
-        try {
-          current = this.snapshotCore(channelName);
-          lastSnapshot = current;
-        } catch {
-          // The last complete projection remains valid after native teardown.
-        }
-        queue.seal(
-          {
-            ...current,
-            state: ZLinkTopologyState.Stopped,
-            isReady: false,
-            sequence: this.sequence,
-            observedAt: new Date()
-          },
-          channelName
-        );
-      }
-    };
-    this.hostObservers.add(hostObserver);
-    queue.onClose(() => {
-      stop();
-      this.hostObservers.delete(hostObserver);
-    });
-    return queue;
+    return this.sources.observe(channelName, capacity, signal);
   }
 
   hostStateChanged(): void {
-    for (const observer of this.hostObservers) {
-      try {
-        observer.changed();
-      } catch {
-        // Monitoring projection failures do not change host lifecycle results.
-      }
-    }
+    this.sources.hostStateChanged();
   }
 
   stopObservers(): void {
-    for (const observer of [...this.hostObservers]) {
-      try {
-        observer.stop();
-      } catch {
-        // The observer is still removed when its terminal snapshot fails.
-      }
-    }
-    this.hostObservers.clear();
+    this.sources.stopObservers();
   }
 
   private requireRuntime(): ZLinkChannelRuntimeManager {
@@ -299,6 +297,40 @@ export class ZLinkFanoutRuntimeProjection implements ZLinkFanoutRuntime {
   }
 }
 
+function peerStatusForAvailability(
+  descriptor: Pick<ClientServerDescriptor, 'serverRoutingId' | 'weight' | 'state'>,
+  unavailableReason: ZLinkTopologyReason.NoReadyTarget
+): ZLinkClientServerTargetStatus;
+function peerStatusForAvailability(
+  descriptor: Pick<FanoutPublisherDescriptor, 'publisherRoutingId' | 'state'>,
+  unavailableReason: ZLinkTopologyReason.NoReadyPeer
+): ZLinkPeerStatus;
+function peerStatusForAvailability(
+  descriptor:
+    | Pick<ClientServerDescriptor, 'serverRoutingId' | 'weight' | 'state'>
+    | Pick<FanoutPublisherDescriptor, 'publisherRoutingId' | 'state'>,
+  noReadyReason: ZLinkTopologyReason.NoReadyTarget | ZLinkTopologyReason.NoReadyPeer
+): ZLinkClientServerTargetStatus | ZLinkPeerStatus {
+  let state = ZLinkPeerState.NotConnected;
+  let unavailableReason: ZLinkTopologyReason | undefined = noReadyReason;
+  switch (descriptor.state) {
+    case 'retiring':
+      state = ZLinkPeerState.Draining;
+      unavailableReason = ZLinkTopologyReason.Draining;
+      break;
+    case 'serving':
+      state = ZLinkPeerState.Ready;
+      unavailableReason = undefined;
+      break;
+    case 'preparing':
+      state = ZLinkPeerState.Connecting;
+      break;
+  }
+  return 'serverRoutingId' in descriptor
+    ? { nodeRid: descriptor.serverRoutingId, weight: descriptor.weight, state, unavailableReason }
+    : { nodeRid: descriptor.publisherRoutingId, state, unavailableReason };
+}
+
 function topologyStateForHost(state: ZLinkFrameworkRuntimeState): ZLinkTopologyState {
   switch (state) {
     case ZLinkFrameworkRuntimeState.Preparing:

package/src/runtime/disposal.ts

@@ -0,0 +1,19 @@
+export class RuntimeDisposal {
+  private task?: Promise<void> | null;
+
+  get started(): boolean {
+    return this.task !== undefined;
+  }
+
+  run(close: () => Promise<void>): Promise<void> {
+    if (this.task != null) return this.task;
+    const task = Promise.resolve()
+      .then(close)
+      .catch((error: unknown) => {
+        this.task = null;
+        throw error;
+      });
+    this.task = task;
+    return task;
+  }
+}