@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -1,3 +1,10 @@
+import { ZLINK_MAX_IDENTITY_TEXT_BYTES } from '../../contracts/Common/CoreTypes';
+import {
+  ZLINK_MAX_PUBLIC_WEIGHT,
+  isValidCapacity,
+  isValidPositiveCapacity,
+  isValidPublicWeight
+} 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';
@@ -34,8 +41,9 @@ export interface ServiceNodeDescriptor {
 
 export interface AdmittedServicePeer {
   readonly descriptor: ServiceNodeDescriptor;
+  // 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 connectionDiscriminator: string;
 }
 
 export interface ServicePeerAdmissionExpectation {
@@ -50,8 +58,6 @@ export type PeerAdmissionResult =
 export type ServiceObjectPlacementStatus = 'available' | 'unsupported' | 'capacity' | 'unavailable';
 
 const REQUIRED_CAPABILITY = SERVICE_WIRE_REQUIRED_CAPABILITY;
-const MAX_CAPACITY = 0x7fff_ffff;
-const MAX_PUBLIC_WEIGHT = 10_000;
 
 interface ServiceSelectionCacheEntry {
   readonly selection: SmoothWeightedSelection<unknown>;
@@ -98,13 +104,11 @@ export class ServiceTopologyRegistry {
   admit(
     descriptor: ServiceNodeDescriptor,
     connectionId: string,
-    expected?: ServicePeerAdmissionExpectation,
-    connectionDiscriminator = connectionId
+    expected?: ServicePeerAdmissionExpectation
   ): PeerAdmissionResult {
     try {
       validateDescriptor(descriptor);
       requireText(connectionId, 'connectionId');
-      requireText(connectionDiscriminator, 'connectionDiscriminator');
     } catch (error) {
       return 'invalidDescriptor';
     }
@@ -146,34 +150,11 @@ export class ServiceTopologyRegistry {
     ) {
       return 'staleDescriptor';
     }
-    if (
-      current !== undefined &&
-      current.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration &&
-      current.descriptor.descriptorRevision === descriptor.descriptorRevision &&
-      sameServiceNodeDescriptor(current.descriptor, descriptor) &&
-      current.connectionId !== connectionId &&
-      // A fallback candidate is only a logical placeholder. Once the
-      // monitor reports the physical connection, its evidence supersedes
-      // candidate ordering so the request path uses the native route.
-      !(
-        isUnmonitoredConnectionId(current.connectionId) && !isUnmonitoredConnectionId(connectionId)
-      ) &&
-      compareConnectionCandidate(
-        current.connectionDiscriminator,
-        current.connectionId,
-        connectionDiscriminator,
-        connectionId
-      ) <= 0
-    ) {
-      // Both manual directions can reach admission. The same comparison on
-      // every retry keeps one physical candidate instead of replacing it in
-      // arrival order.
-      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,
-      connectionDiscriminator
+      connectionId
     });
     this.remember(descriptor);
     this.rebuildSelections();
@@ -231,21 +212,6 @@ export class ServiceTopologyRegistry {
     this.rebuildSelections();
   }
 
-  markNotRequired(descriptor: ServiceNodeDescriptor): void {
-    validateDescriptor(descriptor);
-    if (
-      descriptor.meshName !== this.local.meshName ||
-      descriptor.nodeRoutingId === this.local.nodeRoutingId ||
-      !descriptorConnectionNotRequired(this.local, descriptor)
-    ) {
-      return;
-    }
-    this.peersByRid.delete(descriptor.nodeRoutingId);
-    this.remember(descriptor);
-    this.notRequiredByRid.set(descriptor.nodeRoutingId, cloneDescriptor(descriptor));
-    this.rebuildSelections();
-  }
-
   forgetNotRequired(nodeRoutingId: string): void {
     if (this.notRequiredByRid.delete(nodeRoutingId)) this.rebuildSelections();
   }
@@ -259,8 +225,12 @@ export class ServiceTopologyRegistry {
 
   hasKnownChannelTarget(channelName: string): boolean {
     requireText(channelName, 'channelName');
-    return [this.local, ...this.knownByRid.values()].some(
-      (descriptor) => selectableChannel(descriptor, channelName) !== undefined
+    return [...this.knownByRid.values()].some(
+      (descriptor) =>
+        (descriptor.state === 'serving' ||
+          descriptor.state === 'retiring' ||
+          descriptor.state === 'draining') &&
+        findChannel(descriptor, channelName) !== undefined
     );
   }
 
@@ -283,13 +253,8 @@ export class ServiceTopologyRegistry {
     requireText(channelName, 'channelName');
     return this.selectWeightedCycle(
       `channel:${channelName}`,
-      () => {
-        const local: AdmittedServicePeer = {
-          descriptor: cloneDescriptor(this.local),
-          connectionId: 'local',
-          connectionDiscriminator: 'local'
-        };
-        return [local, ...this.peersByRid.values()]
+      () =>
+        [...this.peersByRid.values()]
           .map((peer) => ({
             peer: clonePeer(peer),
             channel: selectableChannel(peer.descriptor, channelName)
@@ -301,8 +266,7 @@ export class ServiceTopologyRegistry {
               peer: AdmittedServicePeer;
               channel: ServiceChannelDescriptor;
             } => value.channel !== undefined
-          );
-      },
+          ),
       (value) => value.channel.weight,
       (value) => value.peer.descriptor.nodeRoutingId,
       (left, right) =>
@@ -452,8 +416,10 @@ export function validateDescriptor(descriptor: ServiceNodeDescriptor): void {
   }
   if (descriptor.maintenanceWave !== undefined) {
     requireText(descriptor.maintenanceWave, 'maintenanceWave');
-    if (Buffer.byteLength(descriptor.maintenanceWave, 'utf8') > 255) {
-      throw new RangeError('maintenanceWave must not exceed 255 UTF-8 bytes.');
+    if (Buffer.byteLength(descriptor.maintenanceWave, 'utf8') > ZLINK_MAX_IDENTITY_TEXT_BYTES) {
+      throw new RangeError(
+        `maintenanceWave must not exceed ${ZLINK_MAX_IDENTITY_TEXT_BYTES} UTF-8 bytes.`
+      );
     }
   }
   validatePublicWeight(descriptor.placementWeight, 'placementWeight');
@@ -490,14 +456,14 @@ export function validateDescriptor(descriptor: ServiceNodeDescriptor): void {
 }
 
 function validateCapacity(value: number, allowZero: boolean, field: string): void {
-  if (!Number.isInteger(value) || value < (allowZero ? 0 : 1) || value > MAX_CAPACITY) {
+  if (!(allowZero ? isValidCapacity(value) : isValidPositiveCapacity(value))) {
     throw new RangeError(`${field} is outside its supported range.`);
   }
 }
 
 function validatePublicWeight(value: number, field: string): void {
-  if (!Number.isInteger(value) || value < 0 || value > MAX_PUBLIC_WEIGHT) {
-    throw new RangeError(`${field} must be an integer in 0..10000.`);
+  if (!isValidPublicWeight(value)) {
+    throw new RangeError(`${field} must be an integer in 0..${ZLINK_MAX_PUBLIC_WEIGHT}.`);
   }
 }
 
@@ -549,8 +515,7 @@ function cloneDescriptor(descriptor: ServiceNodeDescriptor): ServiceNodeDescript
 function clonePeer(peer: AdmittedServicePeer): AdmittedServicePeer {
   return {
     descriptor: cloneDescriptor(peer.descriptor),
-    connectionId: peer.connectionId,
-    connectionDiscriminator: peer.connectionDiscriminator
+    connectionId: peer.connectionId
   };
 }
 
@@ -582,20 +547,6 @@ function arraysEqual(left: readonly string[], right: readonly string[]): boolean
   return left.length === right.length && left.every((value, index) => value === right[index]);
 }
 
-function isUnmonitoredConnectionId(connectionId: string): boolean {
-  return connectionId.startsWith('unmonitored:');
-}
-
-function compareConnectionCandidate(
-  leftDiscriminator: string,
-  leftId: string,
-  rightDiscriminator: string,
-  rightId: string
-): number {
-  const discriminator = compareOrdinal(leftDiscriminator, rightDiscriminator);
-  return discriminator === 0 ? compareOrdinal(leftId, rightId) : discriminator;
-}
-
 function compareOrdinal(left: string, right: string): number {
   return left < right ? -1 : left > right ? 1 : 0;
 }

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

@@ -1,5 +1,11 @@
 import type { RoutingId } from '../../contracts';
 import { decodeRoutingId, encodeRoutingIdStorageHex } from '../routing-id';
+export const SERVICE_WIRE_MAJOR_OFFSET = 2;
+export const SERVICE_WIRE_COMMAND_OFFSET = SERVICE_WIRE_MAJOR_OFFSET + 1;
+export const SERVICE_WIRE_FLAGS_OFFSET = SERVICE_WIRE_COMMAND_OFFSET + 1;
+export const SERVICE_WIRE_PREFIX_SIZE = SERVICE_WIRE_FLAGS_OFFSET + 1;
+
+export const SERVICE_WIRE_TEXT8_MAX_BYTES = 255;
 
 export type ServiceWireInvalid = (message: string) => never;
 

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

@@ -1,4 +1,11 @@
-const PREFIX_SIZE = 5;
+import { UINT64_MAX } from '@zlink-systems/stream-wire';
+import {
+  SERVICE_WIRE_COMMAND_OFFSET,
+  SERVICE_WIRE_FLAGS_OFFSET,
+  SERVICE_WIRE_MAJOR_OFFSET,
+  SERVICE_WIRE_PREFIX_SIZE
+} from './service-wire-binary-primitives';
+const PREFIX_SIZE = SERVICE_WIRE_PREFIX_SIZE;
 const LIVENESS_FRAME_SIZE = PREFIX_SIZE + 8;
 
 export interface ServiceWireDefinition {
@@ -46,16 +53,16 @@ export function createServiceWireCodec(definition: ServiceWireDefinition): Servi
       ) {
         throw new RangeError('command must be a liveness command.');
       }
-      if (record.probeId <= 0n || record.probeId > 0xffff_ffff_ffff_ffffn) {
+      if (record.probeId <= 0n || record.probeId > UINT64_MAX) {
         throw new RangeError('probeId must be a non-zero unsigned 64-bit integer.');
       }
 
       const frame = Buffer.allocUnsafe(LIVENESS_FRAME_SIZE);
       frame[0] = definition.magic[0];
       frame[1] = definition.magic[1];
-      frame[2] = definition.major;
-      frame[3] = record.command;
-      frame[4] = 0;
+      frame[SERVICE_WIRE_MAJOR_OFFSET] = definition.major;
+      frame[SERVICE_WIRE_COMMAND_OFFSET] = record.command;
+      frame[SERVICE_WIRE_FLAGS_OFFSET] = 0;
       frame.writeBigUInt64BE(record.probeId, PREFIX_SIZE);
       return frame;
     },
@@ -64,9 +71,9 @@ export function createServiceWireCodec(definition: ServiceWireDefinition): Servi
       if (frame[0] !== definition.magic[0] || frame[1] !== definition.magic[1]) {
         fail('invalid-magic');
       }
-      if (frame[2] !== definition.major) fail('unsupported-major');
+      if (frame[SERVICE_WIRE_MAJOR_OFFSET] !== definition.major) fail('unsupported-major');
 
-      const command = frame[3];
+      const command = frame[SERVICE_WIRE_COMMAND_OFFSET];
       if (!knownCommands.has(command)) fail('unknown-command');
       if (
         command !== definition.commands.livenessProbe &&
@@ -74,7 +81,7 @@ export function createServiceWireCodec(definition: ServiceWireDefinition): Servi
       ) {
         fail('unknown-command');
       }
-      if (frame[4] !== 0) fail('forbidden-flag');
+      if (frame[SERVICE_WIRE_FLAGS_OFFSET] !== 0) fail('forbidden-flag');
       if (frame.byteLength < LIVENESS_FRAME_SIZE) fail('truncated-field');
       if (frame.byteLength > LIVENESS_FRAME_SIZE) fail('trailing-byte');
 

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

@@ -1,6 +1,7 @@
 // Generated from service-wire-v1.schema.json. Do not edit.
 export const SERVICE_WIRE_MAGIC = [90, 77] as const;
 export const SERVICE_WIRE_MAJOR = 1 as const;
+export const SERVICE_WIRE_METADATA_BYTES = 1024 as const;
 export const SERVICE_WIRE_REQUIRED_CAPABILITY = "framework-service-v13" as const;
 export const SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME = "ZLinkFrameworkMultipart" as const;
 export const SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE = "application/x-zlink-multipart" as const;

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

@@ -1,10 +1,16 @@
+import { UINT32_MAX, UINT64_MAX } from '@zlink-systems/stream-wire';
+import { normalizeEndpoint } from '../../contracts/Configuration/EndpointNotation';
 import {
   validateDescriptor,
   type ServiceNodeDescriptor,
   type ServiceNodeState,
   type ServiceObjectRole
 } from './service-topology-registry';
-import { normalizeEndpoint } from '../../contracts/Configuration/EndpointNotation';
+import {
+  SERVICE_WIRE_PREFIX_SIZE,
+  decodeCanonicalServiceWireText,
+  encodeCanonicalServiceWireText
+} from './service-wire-binary-primitives';
 import {
   SERVICE_WIRE_MAGIC,
   SERVICE_WIRE_MAJOR,
@@ -12,14 +18,20 @@ import {
   ServiceWireCommand,
   isValidServiceWireTerminalFailure
 } from './service-wire-constants.generated';
-import {
-  decodeCanonicalServiceWireText,
-  encodeCanonicalServiceWireText
-} from './service-wire-binary-primitives';
 
-const PREFIX_SIZE = 5;
-const MAX_U32 = 0xffff_ffff;
-const MAX_U64 = 0xffff_ffff_ffff_ffffn;
+const PREFIX_SIZE = SERVICE_WIRE_PREFIX_SIZE;
+const REPLY_HEADER_MIN_BYTES = PREFIX_SIZE + 16;
+const SERVICE_ROUTE_TEXT_MAX_BYTES = 4096;
+export const APPLICATION_PAYLOAD_VERSION = 1;
+const APPLICATION_PAYLOAD_LENGTH_FIELD_BYTES = 4;
+const APPLICATION_PAYLOAD_TEXT_LENGTH_FIELD_BYTES = 1;
+export const APPLICATION_PAYLOAD_MINIMUM_FIELD_BYTES =
+  1 +
+  APPLICATION_PAYLOAD_LENGTH_FIELD_BYTES +
+  2 * APPLICATION_PAYLOAD_TEXT_LENGTH_FIELD_BYTES +
+  APPLICATION_PAYLOAD_LENGTH_FIELD_BYTES;
+const MAX_U32 = UINT32_MAX;
+const MAX_U64 = UINT64_MAX;
 export const M6A_SERVICE_WIRE_MAGIC = SERVICE_WIRE_MAGIC;
 export const M6A_SERVICE_WIRE_MAJOR = SERVICE_WIRE_MAJOR;
 export const M6A_SERVICE_WIRE_REQUIRED_CAPABILITY = SERVICE_WIRE_REQUIRED_CAPABILITY;
@@ -134,7 +146,7 @@ export function decodeReplyHeader(frame: Uint8Array): ServiceReplyHeader {
   if (
     header.command !== M6aServiceWireCommand.reply ||
     header.flags !== 0 ||
-    frame.byteLength < 21
+    frame.byteLength < REPLY_HEADER_MIN_BYTES
   ) {
     fail('Invalid reply header.');
   }
@@ -160,7 +172,7 @@ export function encodeApplicationPayload(payload: ServiceApplicationPayload): Bu
     packetName.byteLength + contentType.byteLength + 4 + payload.payload.byteLength;
   if (bodyLength > MAX_U32) fail('Application payload body exceeds u32.');
   const result = Buffer.alloc(5 + bodyLength);
-  result[0] = 1;
+  result[0] = APPLICATION_PAYLOAD_VERSION;
   result.writeUInt32BE(bodyLength, 1);
   let offset = 5;
   offset += packetName.copy(result, offset);
@@ -197,7 +209,7 @@ export function encodeMultipartApplicationPayload(
   const bodyLength = packetNameBytes.byteLength + contentTypeBytes.byteLength + 4 + multipartLength;
   if (bodyLength > MAX_U32) fail('Application payload body exceeds u32.');
   const result = Buffer.alloc(5 + bodyLength);
-  result[0] = 1;
+  result[0] = APPLICATION_PAYLOAD_VERSION;
   result.writeUInt32BE(bodyLength, 1);
   let offset = 5;
   offset += packetNameBytes.copy(result, offset);
@@ -230,7 +242,8 @@ export function decodeApplicationPayload(frame: Uint8Array): ServiceApplicationP
  */
 export function decodeApplicationPayloadView(frame: Uint8Array): ServiceApplicationPayload {
   const reader = new Reader(frame);
-  if (reader.u8('version') !== 1) fail('Invalid application payload version.');
+  if (reader.u8('version') !== APPLICATION_PAYLOAD_VERSION)
+    fail('Invalid application payload version.');
   const bodyLength = reader.u32('bodyLength');
   if (bodyLength !== reader.remaining) fail('Application payload body length mismatch.');
   const packetName = reader.text8('packetName');
@@ -250,7 +263,8 @@ export function decodeApplicationPayloadView(frame: Uint8Array): ServiceApplicat
  */
 export function validateApplicationPayloadFrame(frame: Uint8Array): void {
   const reader = new Reader(frame);
-  if (reader.u8('version') !== 1) fail('Invalid application payload version.');
+  if (reader.u8('version') !== APPLICATION_PAYLOAD_VERSION)
+    fail('Invalid application payload version.');
   const bodyLength = reader.u32('bodyLength');
   if (bodyLength !== reader.remaining) fail('Application payload body length mismatch.');
   reader.text8('packetName');
@@ -478,7 +492,7 @@ function encodeText8(value: string, field: string): Buffer {
 }
 
 function encodeText16(value: string, field: string): Buffer {
-  const bytes = encodeCanonicalServiceWireText(value, field, 4096, fail);
+  const bytes = encodeCanonicalServiceWireText(value, field, SERVICE_ROUTE_TEXT_MAX_BYTES, fail);
   return concat(encodeU16(bytes.byteLength), bytes);
 }
 
@@ -624,7 +638,7 @@ class Reader {
 
   text16(field: string): string {
     const length = this.u16(`${field}.length`);
-    if (length === 0 || length > 4096) fail(`${field} has invalid length.`);
+    if (length === 0 || length > SERVICE_ROUTE_TEXT_MAX_BYTES) fail(`${field} has invalid length.`);
     return decodeText(this.bytes(length, field), field);
   }