@zlink-systems/framework 0.29.1 → 0.30.1

package/src/runtime/foundation/service-stateful-wire-codec.ts

@@ -14,6 +14,7 @@ import {
   encodeInstanceRouteV1,
   encodeSpotRequestCommand,
   encodeSpotSendCommand,
+  type InstanceRouteV1,
   type ServiceWireDecoderContext
 } from '../protocol/service_wire_codec.generated';
 import {
@@ -82,8 +83,6 @@ import {
 import { APPLICATION_PAYLOAD_VERSION, ServiceWireProtocolError } from './service-wire-m6a-codec';
 const MESSAGE_FOLLOW_MAX_BODY_BYTES = 16 * 1024 * 1024;
 const MESSAGE_FOLLOW_VERSION = 1;
-const INSTANCE_ROUTE_VERSION = 1;
-const INSTANCE_ACTIVATION_VERSION = 2;
 
 const PREFIX_SIZE = SERVICE_WIRE_PREFIX_SIZE;
 const MAGIC_0 = SERVICE_WIRE_MAGIC[0];
@@ -190,11 +189,6 @@ export interface ServiceMaintenanceRelocationPrepare extends ServiceWireRelocati
   /** CRC-32C (Castagnoli) over the fully assembled payload bytes. */
   readonly payloadChecksumCrc32c: number;
   readonly applicationVersion: bigint;
-  /** NODE-INTERNAL; serialized as extra frames after canonical command 40. */
-  readonly nodeInternalBoundSessions?: readonly {
-    readonly participantKey: string;
-    readonly payload: Uint8Array;
-  }[];
 }
 
 export interface ServiceMaintenanceRelocationReady extends ServiceWireRelocationBase {
@@ -946,6 +940,10 @@ export interface ServiceInstanceActivationTarget {
   readonly descriptorVersion: string;
 }
 
+export interface ServiceInstanceColdActivationTarget extends ServiceInstanceActivationTarget {
+  readonly targetMeshName: string;
+}
+
 export interface ServiceUserSpotReservationFence {
   readonly reservationId: string;
   readonly expectedStoreVersion: string;
@@ -1105,7 +1103,7 @@ export type ServiceStatefulWireRecord =
   | {
       readonly kind: 'instanceSpot';
       readonly activation: 'missing';
-      readonly target: ServiceInstanceActivationTarget;
+      readonly target: ServiceInstanceColdActivationTarget;
       readonly sourceNodeGeneration: bigint;
       readonly sourceNodeRid: string;
       readonly sourceSpotId?: string;
@@ -1435,7 +1433,7 @@ export function encodeInstanceSpotHeader(
 }
 
 export function encodeInstanceSpotActivationHeader(
-  target: ServiceInstanceActivationTarget,
+  target: ServiceInstanceColdActivationTarget,
   sourceNodeGeneration: bigint,
   sourceNodeRid: string,
   sourceSpotId: string | undefined,
@@ -1454,25 +1452,28 @@ export function encodeInstanceSpotActivationHeader(
   if (operationKind === 'send' && replyRouteId !== undefined) {
     throw new RangeError('Instance Spot send must not carry a reply route.');
   }
-  const targetBody = concat(
-    rid(target.targetNodeRid, 'targetNodeRid'),
-    u64(target.targetNodeGeneration),
-    rid(target.targetSpotId, 'targetSpotId'),
-    text16(target.stableType, 'stableType'),
-    text16(target.descriptorVersion, 'descriptorVersion')
+  const encodedRoute = encodeInstanceRouteV1(
+    {
+      routeKind: 'coldActivation',
+      targetNodeRid: toGeneratedRoutingId(target.targetNodeRid, 'targetNodeRid'),
+      targetNodeGeneration: target.targetNodeGeneration,
+      targetSpotId: target.targetSpotId,
+      targetMeshName: target.targetMeshName,
+      stableType: target.stableType,
+      targetDescriptorVersion: target.descriptorVersion,
+      deadlineUnixMs
+    },
+    STATEFUL_MESSAGE_CONTEXT
   );
   return concat(
     prefix(M6bServiceWireCommand.instanceSpot, hasMetadata ? M6bServiceWireFlag.metadata : 0),
-    Buffer.of(INSTANCE_ACTIVATION_VERSION),
-    u16(targetBody.byteLength),
-    targetBody,
+    encodedRoute,
     u64Any(sourceNodeGeneration),
     rid(sourceNodeRid, 'sourceNodeRid'),
     optionalRid(sourceSpotId),
     Buffer.of(operationKind === 'send' ? 1 : 2),
     u64Any(operation.high),
     u64Any(operation.low),
-    u64(deadlineUnixMs),
     ...(operationKind === 'request' ? [u64(requirePositive(replyRouteId, 'replyRouteId'))] : [])
   );
 }
@@ -1741,53 +1742,31 @@ export function decodeStatefulHeader(
         fail(`Invalid command flags '${command.flags}'.`);
       }
       const routeStart = reader.offset;
-      const version = reader.u8('instanceRoute.version');
-      if (version !== INSTANCE_ROUTE_VERSION && version !== INSTANCE_ACTIVATION_VERSION)
-        fail('Unsupported Instance route version.');
+      reader.u8('instanceRoute.kind');
       const routeLength = reader.u16('instanceRoute.length');
       const routeEnd = reader.offset + routeLength;
-      const generatedReadyRoute =
-        version === INSTANCE_ROUTE_VERSION
-          ? decodeInstanceRouteV1(
-              reader.bytes.subarray(routeStart, routeEnd),
-              STATEFUL_MESSAGE_CONTEXT
-            )
-          : undefined;
-      if (generatedReadyRoute !== undefined && generatedReadyRoute.routeKind !== 'ready') {
-        fail('Invalid Ready Instance route kind.');
-      }
-      const commonTarget =
-        generatedReadyRoute?.routeKind === 'ready'
-          ? {
-              targetNodeRid: fromGeneratedRoutingId(
-                generatedReadyRoute.targetNodeRid,
-                'targetNodeRid'
-              ),
-              targetNodeGeneration: generatedReadyRoute.targetNodeGeneration,
-              targetSpotId: generatedReadyRoute.targetSpotId
-            }
-          : {
-              targetNodeRid: reader.rid('targetNodeRid'),
-              targetNodeGeneration: reader.nonZeroU64('targetNodeGeneration'),
-              targetSpotId: reader.rid('targetSpotId')
-            };
-      const route: ServiceInstanceRouteFence | undefined =
-        generatedReadyRoute?.routeKind === 'ready'
-          ? {
-              ...commonTarget,
-              ...generatedReadyRoute.authority
-            }
+      const generatedRoute = decodeCanonicalInstanceRoute(
+        reader.bytes.subarray(routeStart, routeEnd)
+      );
+      const commonTarget = {
+        targetNodeRid: fromGeneratedRoutingId(generatedRoute.targetNodeRid, 'targetNodeRid'),
+        targetNodeGeneration: generatedRoute.targetNodeGeneration,
+        targetSpotId: generatedRoute.targetSpotId
+      };
+      const route =
+        generatedRoute.routeKind === 'ready'
+          ? { ...commonTarget, ...generatedRoute.authority }
           : undefined;
-      const target: ServiceInstanceActivationTarget | undefined =
-        version === INSTANCE_ACTIVATION_VERSION
+      const target =
+        generatedRoute.routeKind === 'coldActivation'
           ? {
               ...commonTarget,
-              stableType: reader.text16('stableType'),
-              descriptorVersion: reader.text16('descriptorVersion')
+              targetMeshName: generatedRoute.targetMeshName,
+              stableType: generatedRoute.stableType,
+              descriptorVersion: generatedRoute.targetDescriptorVersion
             }
           : undefined;
-      if (generatedReadyRoute !== undefined) reader.offset = routeEnd;
-      if (reader.offset !== routeEnd) fail('Invalid Instance route body length.');
+      reader.offset = routeEnd;
       const sourceNodeGeneration = reader.nonZeroU64('sourceNodeGeneration');
       const sourceNodeRid = reader.rid('sourceNodeRid');
       const sourceSpotId = reader.optionalRid('sourceSpotId');
@@ -1799,21 +1778,21 @@ export function decodeStatefulHeader(
       };
       const operationKind = operationValue === 1 ? ('send' as const) : ('request' as const);
       if (
-        version === INSTANCE_ROUTE_VERSION &&
+        generatedRoute.routeKind === 'ready' &&
         ((operationKind === 'send' && (operation.high !== 0n || operation.low !== 0n)) ||
           (operationKind === 'request' && operation.high === 0n && operation.low === 0n))
       ) {
         fail('Invalid Instance operation identity.');
       }
       if (
-        version === INSTANCE_ACTIVATION_VERSION &&
+        generatedRoute.routeKind === 'coldActivation' &&
         operation.high === 0n &&
         operation.low === 0n
       ) {
         fail('Instance activation requires a non-zero operation identity.');
       }
       const deadlineUnixMs =
-        version === INSTANCE_ACTIVATION_VERSION ? reader.nonZeroU64('deadlineUnixMs') : undefined;
+        generatedRoute.routeKind === 'coldActivation' ? generatedRoute.deadlineUnixMs : undefined;
       const replyRouteId =
         operationKind === 'request' ? reader.nonZeroU64('replyRouteId') : undefined;
       reader.end();
@@ -1826,12 +1805,12 @@ export function decodeStatefulHeader(
         operation,
         ...(replyRouteId === undefined ? {} : { replyRouteId })
       };
-      return version === INSTANCE_ROUTE_VERSION
+      return generatedRoute.routeKind === 'ready'
         ? {
             ...common,
             activation: 'ready',
             route: route!,
-            instanceIntent: generatedReadyRoute!.instanceIntent === 'true'
+            instanceIntent: generatedRoute.instanceIntent === 'true'
           }
         : {
             ...common,
@@ -2387,11 +2366,6 @@ function text8(value: string, name: string): Buffer {
   return sized8(value, name);
 }
 
-function text16(value: string, name: string): Buffer {
-  const bytes = encodeCanonicalServiceWireText(value, name, 0xffff, outOfRange);
-  return concat(u16(bytes.byteLength), bytes);
-}
-
 function optionalRid(value: string | undefined): Buffer {
   return value === undefined ? Buffer.of(0) : rid(value, 'sourceSpotId');
 }
@@ -2448,6 +2422,15 @@ function concat(...parts: readonly Uint8Array[]): Buffer {
   return Buffer.concat(parts.map((part) => Buffer.from(part)));
 }
 
+function decodeCanonicalInstanceRoute(bytes: Uint8Array): InstanceRouteV1 {
+  try {
+    return decodeInstanceRouteV1(bytes, STATEFUL_MESSAGE_CONTEXT);
+  } catch (error) {
+    if (error instanceof RangeError) throw new ServiceWireProtocolError(error.message);
+    throw error;
+  }
+}
+
 function fail(message: string): never {
   throw new ServiceWireProtocolError(message);
 }
@@ -3093,21 +3076,9 @@ class FrozenReader {
 
   private instanceRoute(): void {
     const start = this.offset;
-    const kind = this.u8('instanceRouteKind');
-    if (kind < 1 || kind > 2) fail('Invalid Instance route kind.');
-    const body = this.body16('Instance route');
-    if (kind === INSTANCE_ROUTE_VERSION) {
-      decodeInstanceRouteV1(this.bytes.subarray(start, this.offset), STATEFUL_MESSAGE_CONTEXT);
-      return;
-    }
-    body.rid8('targetNodeRid');
-    body.nonZeroU64('targetNodeGeneration');
-    body.text8('targetSpotId');
-    body.text8('targetMeshName');
-    body.text8('stableType');
-    body.text8('targetDescriptorVersion');
-    body.nonZeroU64('deadlineUnixMs');
-    body.end('Instance route');
+    this.u8('instanceRouteKind');
+    this.body16('Instance route');
+    decodeCanonicalInstanceRoute(this.bytes.subarray(start, this.offset));
   }
 
   private relocationObject(): void {

package/src/runtime/foundation/service-topology-registry.ts

@@ -1,4 +1,5 @@
 import { ZLINK_MAX_IDENTITY_TEXT_BYTES } from '../../contracts/Common/CoreTypes';
+import type { ServiceLivenessConnection } from './service-liveness-registry';
 import {
   ZLINK_MAX_PUBLIC_WEIGHT,
   isValidCapacity,
@@ -7,7 +8,10 @@ import {
 } from '../../contracts/Configuration/RegistrationBuilderPolicy';
 import { descriptorConnectionNotRequired } from './route-mesh-connection-policy';
 import { SmoothWeightedSelection } from './service-weighted-selection';
-import { SERVICE_WIRE_REQUIRED_CAPABILITY } from './service-wire-constants.generated';
+import {
+  SERVICE_WIRE_REQUIRED_CAPABILITY,
+  ServiceWireCommand
+} from './service-wire-constants.generated';
 
 export type ServiceNodeState =
   'preparing' | 'serving' | 'retiring' | 'draining' | 'stopped' | 'error';
@@ -39,11 +43,18 @@ export interface ServiceNodeDescriptor {
   readonly pendingCapacityUsed: number;
 }
 
-export interface AdmittedServicePeer {
+interface ServiceRouteAdmission {
   readonly descriptor: ServiceNodeDescriptor;
+  readonly descriptorBytes?: Uint8Array;
+  readonly connectionId?: string | bigint;
+  readonly remoteAdmitReceived?: boolean;
+}
+
+export interface AdmittedServicePeer extends ServiceRouteAdmission {
   // The Core selected-route generation this admission belongs to (Core ROUTER
   // §10.1), as an opaque token compared only for equality.
-  readonly connectionId: string;
+  readonly connectionId: string | bigint;
+  readonly liveness?: ServiceLivenessConnection;
 }
 
 export interface ServicePeerAdmissionExpectation {
@@ -67,7 +78,7 @@ interface ServiceSelectionCacheEntry {
 export class ServiceTopologyRegistry {
   private local: ServiceNodeDescriptor;
   private readonly peersByRid = new Map<string, AdmittedServicePeer>();
-  private readonly notRequiredByRid = new Map<string, ServiceNodeDescriptor>();
+  private readonly notRequiredByRid = new Map<string, ServiceRouteAdmission>();
   private readonly knownByRid = new Map<string, ServiceNodeDescriptor>();
   private readonly selections = new Map<string, ServiceSelectionCacheEntry>();
 
@@ -94,7 +105,7 @@ export class ServiceTopologyRegistry {
     }
     this.local = cloneDescriptor(descriptor);
     for (const [nodeRoutingId, remote] of this.notRequiredByRid) {
-      if (!descriptorConnectionNotRequired(this.local, remote)) {
+      if (!descriptorConnectionNotRequired(this.local, remote.descriptor)) {
         this.notRequiredByRid.delete(nodeRoutingId);
       }
     }
@@ -103,12 +114,16 @@ export class ServiceTopologyRegistry {
 
   admit(
     descriptor: ServiceNodeDescriptor,
-    connectionId: string,
-    expected?: ServicePeerAdmissionExpectation
+    connectionId: string | bigint,
+    expected?: ServicePeerAdmissionExpectation,
+    admitLiveness?: () => ServiceLivenessConnection,
+    command: number = ServiceWireCommand.hello,
+    descriptorBytes?: Uint8Array
   ): PeerAdmissionResult {
     try {
       validateDescriptor(descriptor);
-      requireText(connectionId, 'connectionId');
+      if (typeof connectionId === 'string') requireText(connectionId, 'connectionId');
+      else if (connectionId === 0n) throw new TypeError('connectionId must be nonzero.');
     } catch (error) {
       return 'invalidDescriptor';
     }
@@ -123,45 +138,62 @@ export class ServiceTopologyRegistry {
     ) {
       return 'invalidDescriptor';
     }
+    const current = this.peersByRid.get(descriptor.nodeRoutingId);
+    const previous = current ?? this.notRequiredByRid.get(descriptor.nodeRoutingId);
+    const receivedAdmit =
+      command === ServiceWireCommand.admit ||
+      (previous?.connectionId === connectionId && previous.remoteAdmitReceived === true);
+    if (
+      previous !== undefined &&
+      previous.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration
+    ) {
+      const existing = previous.descriptor;
+      if (
+        descriptor.descriptorRevision < existing.descriptorRevision ||
+        (descriptor.descriptorRevision === existing.descriptorRevision &&
+          !(previous.descriptorBytes !== undefined && descriptorBytes !== undefined
+            ? Buffer.compare(previous.descriptorBytes, descriptorBytes) === 0
+            : sameServiceNodeDescriptor(existing, descriptor))) ||
+        (descriptor.descriptorRevision > existing.descriptorRevision &&
+          command !== ServiceWireCommand.update)
+      )
+        return 'staleDescriptor';
+      if (
+        descriptor.descriptorRevision > existing.descriptorRevision &&
+        !sameImmutableDescriptor(existing, descriptor)
+      )
+        return 'invalidDescriptor';
+    } else if (command === ServiceWireCommand.update) {
+      return 'staleDescriptor';
+    }
+    const admission: ServiceRouteAdmission = {
+      descriptor: cloneDescriptor(descriptor),
+      ...(descriptorBytes === undefined ? {} : { descriptorBytes: Buffer.from(descriptorBytes) }),
+      connectionId,
+      remoteAdmitReceived: receivedAdmit
+    };
     if (descriptorConnectionNotRequired(this.local, descriptor)) {
       this.peersByRid.delete(descriptor.nodeRoutingId);
       this.remember(descriptor);
-      this.notRequiredByRid.set(descriptor.nodeRoutingId, cloneDescriptor(descriptor));
+      this.notRequiredByRid.set(descriptor.nodeRoutingId, admission);
       this.rebuildSelections();
       return 'notRequired';
     }
     this.notRequiredByRid.delete(descriptor.nodeRoutingId);
 
-    const current = this.peersByRid.get(descriptor.nodeRoutingId);
-    if (
-      current !== undefined &&
-      current.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration &&
-      descriptor.descriptorRevision > current.descriptor.descriptorRevision &&
-      !sameImmutableDescriptor(current.descriptor, descriptor)
-    ) {
-      return 'invalidDescriptor';
-    }
-    if (
-      current !== undefined &&
-      current.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration &&
-      (current.descriptor.descriptorRevision > descriptor.descriptorRevision ||
-        (current.descriptor.descriptorRevision === descriptor.descriptorRevision &&
-          !sameServiceNodeDescriptor(current.descriptor, descriptor)))
-    ) {
-      return 'staleDescriptor';
-    }
     // Core selects the one route per RID (Core ROUTER §10.1); an admission on
     // that route replaces the admission of a route it replaced.
     this.peersByRid.set(descriptor.nodeRoutingId, {
-      descriptor: cloneDescriptor(descriptor),
-      connectionId
+      ...admission,
+      connectionId,
+      liveness: admitLiveness?.() ?? current?.liveness
     });
     this.remember(descriptor);
     this.rebuildSelections();
     return 'admitted';
   }
 
-  disconnect(nodeRoutingId: string, connectionId: string): boolean {
+  disconnect(nodeRoutingId: string, connectionId: string | bigint): boolean {
     const current = this.peersByRid.get(nodeRoutingId);
     if (current === undefined || current.connectionId !== connectionId) return false;
     this.peersByRid.delete(nodeRoutingId);
@@ -170,10 +202,18 @@ export class ServiceTopologyRegistry {
   }
 
   peer(nodeRoutingId: string): AdmittedServicePeer | undefined {
-    const peer = this.peersByRid.get(nodeRoutingId);
+    const peer = this.admittedPeer(nodeRoutingId);
     return peer === undefined ? undefined : clonePeer(peer);
   }
 
+  routeAdmission(nodeRoutingId: string): ServiceRouteAdmission | undefined {
+    return this.peersByRid.get(nodeRoutingId) ?? this.notRequiredByRid.get(nodeRoutingId);
+  }
+
+  admittedPeer(nodeRoutingId: string): AdmittedServicePeer | undefined {
+    return this.peersByRid.get(nodeRoutingId);
+  }
+
   peers(): readonly AdmittedServicePeer[] {
     return this.peersCore();
   }
@@ -188,12 +228,14 @@ export class ServiceTopologyRegistry {
 
   notRequiredPeers(): readonly ServiceNodeDescriptor[] {
     return [...this.notRequiredByRid.values()]
-      .sort((left, right) => compareOrdinal(left.nodeRoutingId, right.nodeRoutingId))
-      .map(cloneDescriptor);
+      .sort((left, right) =>
+        compareOrdinal(left.descriptor.nodeRoutingId, right.descriptor.nodeRoutingId)
+      )
+      .map((peer) => cloneDescriptor(peer.descriptor));
   }
 
   replaceDiscoveredNotRequired(descriptors: readonly ServiceNodeDescriptor[]): void {
-    const next = new Map<string, ServiceNodeDescriptor>();
+    const next = new Map<string, ServiceRouteAdmission>();
     for (const descriptor of descriptors) {
       validateDescriptor(descriptor);
       if (
@@ -201,13 +243,16 @@ export class ServiceTopologyRegistry {
         descriptor.nodeRoutingId !== this.local.nodeRoutingId &&
         descriptorConnectionNotRequired(this.local, descriptor)
       ) {
-        next.set(descriptor.nodeRoutingId, cloneDescriptor(descriptor));
+        next.set(descriptor.nodeRoutingId, {
+          ...this.notRequiredByRid.get(descriptor.nodeRoutingId),
+          descriptor: cloneDescriptor(descriptor)
+        });
       }
     }
     this.notRequiredByRid.clear();
-    for (const [nodeRoutingId, descriptor] of next) {
-      this.notRequiredByRid.set(nodeRoutingId, descriptor);
-      this.remember(descriptor);
+    for (const [nodeRoutingId, admission] of next) {
+      this.notRequiredByRid.set(nodeRoutingId, admission);
+      this.remember(admission.descriptor);
     }
     this.rebuildSelections();
   }
@@ -217,12 +262,27 @@ export class ServiceTopologyRegistry {
   }
 
   knownDescriptor(nodeRoutingId: string): ServiceNodeDescriptor | undefined {
-    const admitted = this.peersByRid.get(nodeRoutingId)?.descriptor;
-    const descriptor =
-      admitted ?? this.notRequiredByRid.get(nodeRoutingId) ?? this.knownByRid.get(nodeRoutingId);
+    const descriptor = this.knownPeerDescriptor(nodeRoutingId);
     return descriptor === undefined ? undefined : cloneDescriptor(descriptor);
   }
 
+  isObjectClientNodeDirectTarget(nodeRoutingId: string): boolean {
+    const descriptor =
+      nodeRoutingId === this.local.nodeRoutingId
+        ? this.local
+        : this.knownPeerDescriptor(nodeRoutingId);
+    return descriptor?.objectRole === 'client';
+  }
+
+  private knownPeerDescriptor(nodeRoutingId: string): ServiceNodeDescriptor | undefined {
+    const admitted = this.peersByRid.get(nodeRoutingId)?.descriptor;
+    return (
+      admitted ??
+      this.notRequiredByRid.get(nodeRoutingId)?.descriptor ??
+      this.knownByRid.get(nodeRoutingId)
+    );
+  }
+
   hasKnownChannelTarget(channelName: string): boolean {
     requireText(channelName, 'channelName');
     return [...this.knownByRid.values()].some(
@@ -525,7 +585,8 @@ function cloneDescriptor(descriptor: ServiceNodeDescriptor): ServiceNodeDescript
 function clonePeer(peer: AdmittedServicePeer): AdmittedServicePeer {
   return {
     descriptor: cloneDescriptor(peer.descriptor),
-    connectionId: peer.connectionId
+    connectionId: peer.connectionId,
+    liveness: peer.liveness
   };
 }