@zlink-systems/framework 0.30.0 → 0.30.2

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

@@ -1,3 +1,5 @@
+import { decodeRoutingId } from '../routing-id';
+import { decodeBoundSessionCloseCommand } from '../protocol/service_wire_codec.generated';
 import { UINT64_MAX, ZlinkStreamContentType } from '@zlink-systems/stream-wire';
 import { RELOCATION_STATE_CHUNK_DATA_MAX_BYTES } from '../../contracts/Configuration/InternalDefaults';
 import { isCanonicalWireReplyTerminal } from '../framework-errors-internal';
@@ -177,6 +179,7 @@ interface ServiceWireRelocationBase {
 
 export interface ServiceMaintenanceRelocationPrepare extends ServiceWireRelocationBase {
   readonly kind: 'prepare';
+  readonly deadlineUnixMs: bigint;
   readonly target: ServiceWireRelocationTarget;
   readonly initiatorRole: ServiceWireRelocationRole;
   readonly object: ServiceWireRelocationObject;
@@ -189,11 +192,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 {
@@ -329,6 +327,8 @@ export interface ServiceSessionRelocationOwnerFence {
 }
 
 export interface ServiceSessionRelocationSeal {
+  readonly targetNodeRid: string;
+  readonly targetNodeGeneration: bigint;
   readonly relocation: ServiceWireOperationId;
   readonly coordinator: ServiceWireRelocationCoordinatorFence;
   readonly senderRole: 'source' | 'coordinator';
@@ -337,6 +337,7 @@ export interface ServiceSessionRelocationSeal {
 }
 
 export interface ServiceSessionRelocationSealed {
+  readonly sealResult: 'sealed' | 'bindingAbsent';
   readonly relocation: ServiceWireOperationId;
   readonly coordinator: ServiceWireRelocationCoordinatorFence;
   readonly actor: ServiceBoundSessionActorAuthority;
@@ -376,17 +377,13 @@ export function serviceSessionRelocationIdentityKey(
     ServiceSessionRelocationSeal | ServiceSessionRelocationSealed | ServiceSessionRelocationRoute
 ): string {
   const actor = 'targetNodeGeneration' in value.actor ? value.actor.actor : value.actor;
-  //  Session owner가 seal을 대조할 때 쓰는 값만 넣는다 — Session과 Actor binding
-  //  §8.1 "Session owner는 다음 값만 검증한다". coordinator identity는 transport가
-  //  검증하는 wire fence이므로 여기서 다시 대조하지 않는다.
-  return [
+  // Session–Actor binding §8.3: all original fields are checked against the
+  // recorded request; only relocation identity and ActorId select the record.
+  return JSON.stringify([
     value.relocation.high.toString(),
     value.relocation.low.toString(),
-    actor.actorId,
-    actor.generation.toString(),
-    value.session.sessionRid,
-    value.session.bindingGeneration.toString()
-  ].join(':');
+    actor.actorId
+  ]);
 }
 
 function toGeneratedRoutingId(value: string, field: string): Uint8Array {
@@ -668,6 +665,8 @@ function toGeneratedSessionRelocationSeal(
   value: ServiceSessionRelocationSeal
 ): GeneratedSessionRelocationSeal42 {
   return {
+    targetNodeRid: toGeneratedRoutingId(value.targetNodeRid, 'targetNodeRid'),
+    targetNodeGeneration: value.targetNodeGeneration,
     relocation: value.relocation,
     coordinator: toGeneratedCoordinatorFence(value.coordinator),
     senderRole: value.senderRole,
@@ -680,6 +679,8 @@ function fromGeneratedSessionRelocationSeal(
   value: GeneratedSessionRelocationSeal42
 ): ServiceSessionRelocationSeal {
   return {
+    targetNodeRid: fromGeneratedRoutingId(value.targetNodeRid, 'targetNodeRid'),
+    targetNodeGeneration: value.targetNodeGeneration,
     relocation: value.relocation,
     coordinator: fromGeneratedCoordinatorFence(value.coordinator),
     senderRole: value.senderRole as ServiceSessionRelocationSeal['senderRole'],
@@ -695,7 +696,8 @@ function toGeneratedSessionRelocationSealed(
     relocation: value.relocation,
     coordinator: toGeneratedCoordinatorFence(value.coordinator),
     actor: toGeneratedRouteFence(value.actor),
-    ...toGeneratedSessionOwnerFence(value.session)
+    ...toGeneratedSessionOwnerFence(value.session),
+    sealResult: value.sealResult
   };
 }
 
@@ -703,6 +705,7 @@ function fromGeneratedSessionRelocationSealed(
   value: GeneratedSessionRelocationSealed43
 ): ServiceSessionRelocationSealed {
   return {
+    sealResult: value.sealResult,
     relocation: value.relocation,
     coordinator: fromGeneratedCoordinatorFence(value.coordinator),
     actor: fromGeneratedRouteFence(value.actor),
@@ -783,6 +786,7 @@ function fromGeneratedRelocationPrepare(
 ): ServiceMaintenanceRelocationPrepare {
   return {
     kind: 'prepare',
+    deadlineUnixMs: value.deadlineUnixMs,
     ...fromGeneratedRelocationBase(value),
     target: fromGeneratedTargetFence(value.target),
     initiatorRole: value.initiatorRole,
@@ -1088,6 +1092,12 @@ export type ServiceStatefulWireRecord =
       readonly sessionRid: string;
       readonly binding: ServiceBoundSessionTransition;
     }
+  | {
+      readonly kind: 'boundSessionClose';
+      readonly correlation: bigint;
+      readonly actor: { readonly actorId: string; readonly generation: bigint };
+      readonly session: ServiceRetiredBoundSessionRouteFence;
+    }
   | {
       readonly kind: 'boundSessionReplaced';
       readonly actorAuthority: ServiceBoundSessionActorAuthority;
@@ -1719,6 +1729,25 @@ export function decodeStatefulHeader(
             : { state: 'tombstone', retiredGeneration: generation }
       };
     }
+    case M6bServiceWireCommand.boundSessionClose: {
+      const decoded = decodeBoundSessionCloseCommand([frame], {});
+      return {
+        kind: 'boundSessionClose',
+        correlation: decoded.correlation,
+        actor: { actorId: decoded.actor.actorId, generation: decoded.actor.objectGeneration },
+        session: {
+          ...decoded.session,
+          sessionOwnerNodeRid: decodeRoutingId(
+            Buffer.from(decoded.session.sessionOwnerNodeRid).toString('utf8'),
+            Buffer.from(decoded.session.sessionOwnerNodeRid).toString('hex')
+          ),
+          sessionRid: decodeRoutingId(
+            Buffer.from(decoded.session.sessionRid).toString('utf8'),
+            Buffer.from(decoded.session.sessionRid).toString('hex')
+          )
+        }
+      };
+    }
     case M6bServiceWireCommand.boundSessionReplaced: {
       requireFlags(command.flags, 0);
       const actor = reader.actorRef('actorAuthority.actor');
@@ -1887,7 +1916,8 @@ export function encodeMaintenanceRelocationControl(
           payloadTotalLength: value.payloadTotalLength,
           payloadChunkCount: value.payloadChunkCount,
           payloadChecksumCrc32c: value.payloadChecksumCrc32c,
-          applicationVersion: value.applicationVersion
+          applicationVersion: value.applicationVersion,
+          deadlineUnixMs: value.deadlineUnixMs
         })
       );
     case 'ready':
@@ -2015,6 +2045,7 @@ export function decodeStatefulReply(
     | 'actorJoin'
     | 'streamBind'
     | 'streamUnbind'
+    | 'boundSessionClose'
     | 'instanceSpotRequest'
     | 'userSpotCreate'
     | 'userSpotClose'
@@ -2029,6 +2060,8 @@ export function decodeStatefulReply(
   const terminalResult = reader.u32('terminalResult');
   const failureCode = reader.u32('failureCode');
   validateReplyTerminal(terminalResult, failureCode, hasPayload);
+  if (operationKind === 'boundSessionClose' && hasPayload)
+    fail('A bound Session close reply cannot carry application payload.');
   let tail: ServiceStatefulReplyTail | undefined;
   if (terminalResult === 0) {
     if (operationKind === 'actorLookup') {

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

@@ -8,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';
@@ -40,8 +43,14 @@ 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 | bigint;
@@ -69,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>();
 
@@ -96,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);
       }
     }
@@ -107,7 +116,9 @@ export class ServiceTopologyRegistry {
     descriptor: ServiceNodeDescriptor,
     connectionId: string | bigint,
     expected?: ServicePeerAdmissionExpectation,
-    admitLiveness?: () => ServiceLivenessConnection
+    admitLiveness?: () => ServiceLivenessConnection,
+    command: number = ServiceWireCommand.hello,
+    descriptorBytes?: Uint8Array
   ): PeerAdmissionResult {
     try {
       validateDescriptor(descriptor);
@@ -127,37 +138,53 @@ 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),
+      ...admission,
       connectionId,
       liveness: admitLiveness?.() ?? current?.liveness
     });
@@ -175,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();
   }
@@ -193,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 (
@@ -206,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();
   }
@@ -222,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(

package/src/runtime/foundation/service-wire-binary-primitives.ts

@@ -7,38 +7,61 @@ export const SERVICE_WIRE_PREFIX_SIZE = SERVICE_WIRE_FLAGS_OFFSET + 1;
 
 export const SERVICE_WIRE_TEXT8_MAX_BYTES = 255;
 
+// Fatal decoding accepts exactly the canonical UTF-8 encodings; a leading
+// U+FEFF stays part of the value.
+const CANONICAL_UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
+
 export type ServiceWireInvalid = (message: string) => never;
 
-/** Encodes text without silently replacing an unpaired UTF-16 surrogate. */
-export function encodeCanonicalServiceWireText(
+/** String.prototype.isWellFormed (ES2024) exists on every supported Node (20 and later). */
+type ServiceWireText = string & { isWellFormed(): boolean };
+
+/**
+ * Validates text for the service wire and returns its UTF-8 byte length. An
+ * unpaired UTF-16 surrogate is rejected instead of being replaced.
+ */
+export function canonicalServiceWireTextLength(
   value: string,
   field: string,
   maximumBytes: number,
   invalid: ServiceWireInvalid
-): Buffer {
-  const bytes = Buffer.from(value, 'utf8');
+): number {
+  const length = Buffer.byteLength(value, 'utf8');
   if (
-    bytes.byteLength < 1 ||
-    bytes.byteLength > maximumBytes ||
+    length < 1 ||
+    length > maximumBytes ||
     value.includes('\0') ||
-    bytes.toString('utf8') !== value
+    !(value as ServiceWireText).isWellFormed()
   ) {
     invalid(`${field} must be 1..${maximumBytes} canonical UTF-8 bytes without NUL.`);
   }
-  return bytes;
+  return length;
 }
 
-/** Decodes schema text and rejects Node's replacement-character fallback. */
+/** Encodes text without silently replacing an unpaired UTF-16 surrogate. */
+export function encodeCanonicalServiceWireText(
+  value: string,
+  field: string,
+  maximumBytes: number,
+  invalid: ServiceWireInvalid
+): Buffer {
+  canonicalServiceWireTextLength(value, field, maximumBytes, invalid);
+  return Buffer.from(value, 'utf8');
+}
+
+/** Decodes schema text in place and rejects non-canonical UTF-8 and NUL. */
 export function decodeCanonicalServiceWireText(
   bytes: Uint8Array,
   field: string,
   invalid: ServiceWireInvalid
 ): string {
-  const encoded = Buffer.from(bytes);
-  const value = encoded.toString('utf8');
-  if (value.includes('\0') || !Buffer.from(value, 'utf8').equals(encoded)) {
+  let value: string;
+  try {
+    value = CANONICAL_UTF8.decode(bytes);
+  } catch {
     invalid(`${field} is not canonical UTF-8 without NUL.`);
   }
+  if (value.includes('\0')) invalid(`${field} is not canonical UTF-8 without NUL.`);
   return value;
 }
 

package/src/runtime/foundation/service-wire-constants.generated.ts

@@ -46,6 +46,7 @@ export const ServiceWireCommand = {
   boundSessionReplaced: 51,
   relocationState: 52,
   relocationFailed: 53,
+  boundSessionClose: 54,
 } as const;
 export const ServiceWireFlag = {
   metadata: 1,