@zlink-systems/framework 0.21.0 → 0.22.0

package/src/runtime/channels/client-server-location-runtime.ts

@@ -24,9 +24,7 @@ import {
 } from './client-server-service-wire';
 import { discoveryAvailabilityForRuntimeState } from '../foundation/runtime-state-projections';
 import { ZLinkStateLane } from '../execution/state-lane';
-import {
-  isBackendRequestTimeoutError
-} from '../backend/runtime-values';
+import { isBackendRequestTimeoutError } from '../backend/runtime-values';
 
 interface ActiveClientServerTarget {
   descriptor: ZLinkClientServerServerDescriptor;
@@ -102,7 +100,7 @@ export class ZLinkClientServerLocationRuntime {
 
   activeTargets(channelName: string): readonly ZLinkClientServerServerDescriptor[] {
     return [...this.connections.values()]
-      .filter(target => target.state === 'ready')
+      .filter((target) => target.state === 'ready')
       .map((target) => target.descriptor)
       .filter((descriptor) => descriptor.channelName === channelName);
   }
@@ -111,8 +109,7 @@ export class ZLinkClientServerLocationRuntime {
     const owner = this.requireOwnerToken();
     const descriptors = await this.lane.run(() => [...this.localDescriptors]);
     for (const [channelName, current] of descriptors) {
-      if (current.ownerId === owner.ownerId
-        && current.leaseGeneration === owner.leaseGeneration) {
+      if (current.ownerId === owner.ownerId && current.leaseGeneration === owner.leaseGeneration) {
         continue;
       }
       const candidate = {
@@ -143,13 +140,14 @@ export class ZLinkClientServerLocationRuntime {
       const current = await this.lane.run(() => this.localDescriptors.get(channelName));
       if (current !== undefined) {
         const runtimeWeight = this.sockets.clientServerServerWeight(channelName);
-        const candidate = runtimeWeight === current.weight
-          ? current
-          : {
-              ...current,
-              descriptorRevision: current.descriptorRevision + 1n,
-              weight: runtimeWeight
-            };
+        const candidate =
+          runtimeWeight === current.weight
+            ? current
+            : {
+                ...current,
+                descriptorRevision: current.descriptorRevision + 1n,
+                weight: runtimeWeight
+              };
         const result = await this.store.updateClientServer(
           candidate,
           ZLinkLocationWriteIntent.Renew,
@@ -201,10 +199,9 @@ export class ZLinkClientServerLocationRuntime {
         continue;
       }
       const rows = await this.listLiveServers(channelName, signal);
-      const desired = new Map(rows.map((descriptor) => [
-        clientServerConnectionId(descriptor),
-        descriptor
-      ]));
+      const desired = new Map(
+        rows.map((descriptor) => [clientServerConnectionId(descriptor), descriptor])
+      );
       const desiredStableKeys = new Set(rows.map(clientServerStableKey));
       for (const [connectionId, descriptor] of desired) {
         const current = await this.lane.run(() => this.connections.get(connectionId));
@@ -233,8 +230,10 @@ export class ZLinkClientServerLocationRuntime {
       const connections = await this.lane.run(() => [...this.connections]);
       for (const [connectionId, current] of connections) {
         if (current.descriptor.channelName !== channelName || desired.has(connectionId)) continue;
-        if (desiredStableKeys.has(clientServerStableKey(current.descriptor))
-          && current.state === 'ready') {
+        if (
+          desiredStableKeys.has(clientServerStableKey(current.descriptor)) &&
+          current.state === 'ready'
+        ) {
           continue;
         }
         await this.closeConnection(connectionId);
@@ -260,17 +259,18 @@ export class ZLinkClientServerLocationRuntime {
 
     const live: ZLinkClientServerServerDescriptor[] = [];
     for (const descriptor of rows) {
-      if (descriptor.state === ZLinkFrameworkRuntimeState.Stopped
-        || descriptor.state === ZLinkFrameworkRuntimeState.Error) {
+      if (
+        descriptor.state === ZLinkFrameworkRuntimeState.Stopped ||
+        descriptor.state === ZLinkFrameworkRuntimeState.Error
+      ) {
         continue;
       }
-      const lease = await this.stores.ownerLeaseStore.readOwnerLease(
-        descriptor.ownerId,
-        signal
-      );
-      if (lease.kind === 'found'
-        && lease.token.leaseGeneration === descriptor.leaseGeneration
-        && lease.leaseExpiresAt.getTime() > lease.storeNow.getTime()) {
+      const lease = await this.stores.ownerLeaseStore.readOwnerLease(descriptor.ownerId, signal);
+      if (
+        lease.kind === 'found' &&
+        lease.token.leaseGeneration === descriptor.leaseGeneration &&
+        lease.leaseExpiresAt.getTime() > lease.storeNow.getTime()
+      ) {
         live.push(descriptor);
       }
     }
@@ -280,7 +280,7 @@ export class ZLinkClientServerLocationRuntime {
   private async disconnectClients(): Promise<void> {
     const connectionIds = await this.lane.run(() => [...this.connections.keys()]);
     await Promise.allSettled(
-      connectionIds.map(connectionId => this.closeConnection(connectionId))
+      connectionIds.map((connectionId) => this.closeConnection(connectionId))
     );
   }
 
@@ -302,8 +302,9 @@ export class ZLinkClientServerLocationRuntime {
         descriptor.endpoint,
         {
           onTransportReady: (routingId, endpoint) => {
-            void this.handleTransportReady(connectionId, routingId, endpoint)
-              .catch(error => this.locationRuntime.reportDiscoveryFailure(error));
+            void this.handleTransportReady(connectionId, routingId, endpoint).catch((error) =>
+              this.locationRuntime.reportDiscoveryFailure(error)
+            );
           },
           onTerminated: () => {
             void this.handleConnectionTerminated(connectionId);
@@ -325,7 +326,8 @@ export class ZLinkClientServerLocationRuntime {
   ): Promise<void> {
     const current = await this.lane.run(() => {
       const target = this.connections.get(connectionId);
-      if (target === undefined || target.state === 'ready' || target.handshakeInFlight) return undefined;
+      if (target === undefined || target.state === 'ready' || target.handshakeInFlight)
+        return undefined;
       const dealer = target.dealer;
       if (dealer === undefined) return undefined;
       target.handshakeInFlight = true;
@@ -354,10 +356,12 @@ export class ZLinkClientServerLocationRuntime {
         return descriptor;
       });
       if (admittedDescriptor === undefined) return;
-      if (!this.sockets.admitClientServerConnection(
-        toDiscoveryDescriptor(admittedDescriptor, admission.normalizedEffectiveMaxMessageBytes),
-        connectionId
-      )) {
+      if (
+        !this.sockets.admitClientServerConnection(
+          toDiscoveryDescriptor(admittedDescriptor, admission.normalizedEffectiveMaxMessageBytes),
+          connectionId
+        )
+      ) {
         throw new ZLinkConfigurationException(
           `ClientServer '${current.target.descriptor.channelName}' admission was stale.`
         );
@@ -367,8 +371,9 @@ export class ZLinkClientServerLocationRuntime {
       });
       await this.removeSupersededConnections(current.target);
     } catch (error) {
-      const isCurrent = await this.lane.run(() =>
-        this.connections.get(connectionId) === current.target);
+      const isCurrent = await this.lane.run(
+        () => this.connections.get(connectionId) === current.target
+      );
       if (!isCurrent) return;
       if (error instanceof ZLinkConfigurationException) {
         current.target.dealer = undefined;
@@ -386,22 +391,23 @@ export class ZLinkClientServerLocationRuntime {
         return retryAdmission;
       });
       if (shouldRetry) {
-        void this.handleTransportReady(connectionId, _routingId, _endpoint)
-          .catch(error => this.locationRuntime.reportDiscoveryFailure(error));
+        void this.handleTransportReady(connectionId, _routingId, _endpoint).catch((error) =>
+          this.locationRuntime.reportDiscoveryFailure(error)
+        );
       }
     }
   }
 
-  private async removeSupersededConnections(
-    admitted: ActiveClientServerTarget
-  ): Promise<void> {
+  private async removeSupersededConnections(admitted: ActiveClientServerTarget): Promise<void> {
     const stableKey = clientServerStableKey(admitted.descriptor);
     const connections = await this.lane.run(() => [...this.connections.values()]);
     const superseded = connections
-      .filter(current =>
-        current.connectionId !== admitted.connectionId
-        && clientServerStableKey(current.descriptor) === stableKey)
-      .map(current => current.connectionId);
+      .filter(
+        (current) =>
+          current.connectionId !== admitted.connectionId &&
+          clientServerStableKey(current.descriptor) === stableKey
+      )
+      .map((current) => current.connectionId);
     for (const connectionId of superseded) {
       await this.closeConnection(connectionId);
     }
@@ -447,10 +453,14 @@ export class ZLinkClientServerLocationRuntime {
       );
       if (result.status === ZLinkLocationWriteStatus.Stored) {
         this.sockets.setClientServerServerDescriptor(draining, channelName);
-        await this.store.removeClientServer({
-          channelName,
-          serverRid: descriptor.serverRid
-        }, owner, signal);
+        await this.store.removeClientServer(
+          {
+            channelName,
+            serverRid: descriptor.serverRid
+          },
+          owner,
+          signal
+        );
       }
       this.sockets.setClientServerServerDescriptor(undefined, channelName);
     }
@@ -494,16 +504,17 @@ function sameDescriptor(
   left: ZLinkClientServerServerDescriptor,
   right: ZLinkClientServerServerDescriptor
 ): boolean {
-  return left.lifecycleGeneration === right.lifecycleGeneration
-    && left.descriptorRevision === right.descriptorRevision
-    && left.endpoint === right.endpoint
-    && left.weight === right.weight
-    && left.state === right.state
-    && left.ownerId === right.ownerId
-    && left.leaseGeneration === right.leaseGeneration;
+  return (
+    left.lifecycleGeneration === right.lifecycleGeneration &&
+    left.descriptorRevision === right.descriptorRevision &&
+    left.endpoint === right.endpoint &&
+    left.weight === right.weight &&
+    left.state === right.state &&
+    left.ownerId === right.ownerId &&
+    left.leaseGeneration === right.leaseGeneration
+  );
 }
 
-
 function toDiscoveryDescriptor(
   descriptor: ZLinkClientServerServerDescriptor,
   effectiveMaxMessageBytes = 0x7fff_ffff
@@ -526,53 +537,60 @@ function requestAdmission(
   descriptor: ZLinkClientServerServerDescriptor,
   timeoutMs: number
 ): Promise<ZLinkClientServerAdmission> {
-  const message = RuntimeMessage.from(encodeClientServerHello({
-    channelName: descriptor.channelName,
-    securityIdentity: descriptor.securityIdentity,
-    normalizedEffectiveMaxMessageBytes: normalizedMessageLimit(dealer.maxMessageSize)
-  }));
-  return dealer.request(message, timeoutMs).then((parts) => {
-    try {
-      if (parts.length !== 1) {
-        throw new ZLinkConfigurationException(
-          `ClientServer '${descriptor.channelName}' admission reply must contain exactly one part.`
-        );
+  const message = RuntimeMessage.from(
+    encodeClientServerHello({
+      channelName: descriptor.channelName,
+      securityIdentity: descriptor.securityIdentity,
+      normalizedEffectiveMaxMessageBytes: normalizedMessageLimit(dealer.maxMessageSize)
+    })
+  );
+  return dealer.request(message, timeoutMs).then(
+    (parts) => {
+      try {
+        if (parts.length !== 1) {
+          throw new ZLinkConfigurationException(
+            `ClientServer '${descriptor.channelName}' admission reply must contain exactly one part.`
+          );
+        }
+        const first = parts[0]!;
+        const record = decodeClientServerControl(first.data());
+        if (record.kind === 'reject') {
+          throw new ZLinkConfigurationException(
+            `ClientServer '${descriptor.channelName}' admission was rejected (${record.reason}).`
+          );
+        }
+        if (record.kind !== 'admit') {
+          throw new ZLinkConfigurationException(
+            `ClientServer '${descriptor.channelName}' admission reply has an invalid command.`
+          );
+        }
+        return record.admission;
+      } finally {
+        message.close();
+        closeMessages(parts);
       }
-            const first = parts[0]!;
-            const record = decodeClientServerControl(first.data());
-            if (record.kind === 'reject') {
-        throw new ZLinkConfigurationException(
-                `ClientServer '${descriptor.channelName}' admission was rejected (${record.reason}).`
-        );
-            }
-            if (record.kind !== 'admit') {
-        throw new ZLinkConfigurationException(
-                `ClientServer '${descriptor.channelName}' admission reply has an invalid command.`
-        );
-            }
-      return record.admission;
-    } finally {
+    },
+    (error) => {
       message.close();
-      closeMessages(parts);
+      throw error;
     }
-  }, (error) => {
-      message.close();
-    throw error;
-  });
+  );
 }
 
 function requireMatchingAdmission(
   expected: ZLinkClientServerServerDescriptor,
   actual: ZLinkClientServerAdmission
 ): void {
-  if (actual.channelName !== expected.channelName
-    || actual.serverRid !== String(expected.serverRid)
-    || actual.lifecycleGeneration !== expected.lifecycleGeneration
-    || actual.descriptorRevision !== expected.descriptorRevision
-    || actual.weight !== expected.weight
-    || actual.state !== expected.state
-    || actual.securityIdentity !== expected.securityIdentity
-    || actual.advertisedEndpoint !== expected.endpoint) {
+  if (
+    actual.channelName !== expected.channelName ||
+    actual.serverRid !== String(expected.serverRid) ||
+    actual.lifecycleGeneration !== expected.lifecycleGeneration ||
+    actual.descriptorRevision !== expected.descriptorRevision ||
+    actual.weight !== expected.weight ||
+    actual.state !== expected.state ||
+    actual.securityIdentity !== expected.securityIdentity ||
+    actual.advertisedEndpoint !== expected.endpoint
+  ) {
     throw new ZLinkConfigurationException(
       `ClientServer '${expected.channelName}' admission does not match its descriptor.`
     );
@@ -584,7 +602,5 @@ function closeMessages(parts: readonly Message[]): void {
 }
 
 function normalizedMessageLimit(value: number): number {
-  return Number.isSafeInteger(value) && value > 0
-    ? Math.min(value, 0xffff_ffff)
-    : 0x7fff_ffff;
+  return Number.isSafeInteger(value) && value > 0 ? Math.min(value, 0xffff_ffff) : 0x7fff_ffff;
 }

package/src/runtime/channels/client-server-service-wire.ts

@@ -63,10 +63,7 @@ export function encodeClientServerHello(value: ZLinkClientServerHello): Buffer {
     encodeText8(value.channelName, 'channelName'),
     Buffer.of(DIRECTION_CLIENT_TO_SERVER),
     encodeText8(value.securityIdentity, 'securityIdentity'),
-    encodeNonZeroU32(
-      value.normalizedEffectiveMaxMessageBytes,
-      'normalizedEffectiveMaxMessageBytes'
-    )
+    encodeNonZeroU32(value.normalizedEffectiveMaxMessageBytes, 'normalizedEffectiveMaxMessageBytes')
   );
   return encodeAdmission(COMMAND_HELLO, ROLE_CLIENT, roleBody);
 }
@@ -101,18 +98,19 @@ export function encodeClientServerLivenessAck(probeId: bigint): Buffer {
 }
 
 export function isClientServerControlFrame(frame: Uint8Array): boolean {
-  return frame.byteLength >= 5
-    && frame[0] === MAGIC_0
-    && frame[1] === MAGIC_1
-    && frame[2] === WIRE_MAJOR;
+  return (
+    frame.byteLength >= 5 && frame[0] === MAGIC_0 && frame[1] === MAGIC_1 && frame[2] === WIRE_MAJOR
+  );
 }
 
 export function decodeClientServerControl(frame: Uint8Array): ZLinkClientServerControlRecord {
   if (frame.byteLength > MAX_DESCRIPTOR_BYTES) fail('ClientServer control record is oversized.');
   const reader = new Reader(frame);
-  if (reader.u8('magic[0]') !== MAGIC_0
-    || reader.u8('magic[1]') !== MAGIC_1
-    || reader.u8('wireMajor') !== WIRE_MAJOR) {
+  if (
+    reader.u8('magic[0]') !== MAGIC_0 ||
+    reader.u8('magic[1]') !== MAGIC_1 ||
+    reader.u8('wireMajor') !== WIRE_MAJOR
+  ) {
     fail('ClientServer control record prefix is invalid.');
   }
   const command = reader.u8('command');
@@ -150,9 +148,7 @@ export function decodeClientServerControl(frame: Uint8Array): ZLinkClientServerC
   if (role !== ROLE_SERVER) fail('ClientServer server admission role is invalid.');
   const admission = decodeServerAdmission(reader);
   reader.end();
-  return command === COMMAND_ADMIT
-    ? { kind: 'admit', admission }
-    : { kind: 'update', admission };
+  return command === COMMAND_ADMIT ? { kind: 'admit', admission } : { kind: 'update', admission };
 }
 
 function encodeLiveness(command: number, probeId: bigint): Buffer {
@@ -174,10 +170,7 @@ function encodeServerAdmission(
     encodeU32(descriptor.weight),
     Buffer.of(runtimeStateToWire(descriptor.state)),
     encodeText8(descriptor.securityIdentity, 'securityIdentity'),
-    encodeNonZeroU32(
-      normalizedEffectiveMaxMessageBytes,
-      'normalizedEffectiveMaxMessageBytes'
-    ),
+    encodeNonZeroU32(normalizedEffectiveMaxMessageBytes, 'normalizedEffectiveMaxMessageBytes'),
     encodeText16(descriptor.endpoint, 'advertisedEndpoint')
   );
   return encodeAdmission(command, ROLE_SERVER, roleBody);
@@ -204,9 +197,7 @@ function decodeClientHello(reader: Reader): ZLinkClientServerHello {
   return {
     channelName,
     securityIdentity: reader.text8('securityIdentity'),
-    normalizedEffectiveMaxMessageBytes: reader.nonZeroU32(
-      'normalizedEffectiveMaxMessageBytes'
-    )
+    normalizedEffectiveMaxMessageBytes: reader.nonZeroU32('normalizedEffectiveMaxMessageBytes')
   };
 }
 
@@ -228,9 +219,7 @@ function decodeServerAdmission(reader: Reader): ZLinkClientServerAdmission {
     weight,
     state: runtimeStateFromWire(reader.u8('runtimeState')),
     securityIdentity: reader.text8('securityIdentity'),
-    normalizedEffectiveMaxMessageBytes: reader.nonZeroU32(
-      'normalizedEffectiveMaxMessageBytes'
-    ),
+    normalizedEffectiveMaxMessageBytes: reader.nonZeroU32('normalizedEffectiveMaxMessageBytes'),
     advertisedEndpoint: normalizeEndpoint(reader.text16('advertisedEndpoint'))
   };
 }
@@ -278,25 +267,37 @@ function encodeText16(value: string, field: string): Buffer {
 
 function runtimeStateToWire(value: ZLinkFrameworkRuntimeState): number {
   switch (value) {
-    case ZLinkFrameworkRuntimeState.Preparing: return 0;
-    case ZLinkFrameworkRuntimeState.Serving: return 1;
+    case ZLinkFrameworkRuntimeState.Preparing:
+      return 0;
+    case ZLinkFrameworkRuntimeState.Serving:
+      return 1;
     case ZLinkFrameworkRuntimeState.Relocating:
     case ZLinkFrameworkRuntimeState.Relocated:
-    case ZLinkFrameworkRuntimeState.Draining: return 2;
-    case ZLinkFrameworkRuntimeState.Stopped: return 3;
-    case ZLinkFrameworkRuntimeState.Error: return 4;
-    default: fail('ClientServer runtime state is invalid.');
+    case ZLinkFrameworkRuntimeState.Draining:
+      return 2;
+    case ZLinkFrameworkRuntimeState.Stopped:
+      return 3;
+    case ZLinkFrameworkRuntimeState.Error:
+      return 4;
+    default:
+      fail('ClientServer runtime state is invalid.');
   }
 }
 
 function runtimeStateFromWire(value: number): ZLinkFrameworkRuntimeState {
   switch (value) {
-    case 0: return ZLinkFrameworkRuntimeState.Preparing;
-    case 1: return ZLinkFrameworkRuntimeState.Serving;
-    case 2: return ZLinkFrameworkRuntimeState.Draining;
-    case 3: return ZLinkFrameworkRuntimeState.Stopped;
-    case 4: return ZLinkFrameworkRuntimeState.Error;
-    default: fail('ClientServer runtime state is invalid.');
+    case 0:
+      return ZLinkFrameworkRuntimeState.Preparing;
+    case 1:
+      return ZLinkFrameworkRuntimeState.Serving;
+    case 2:
+      return ZLinkFrameworkRuntimeState.Draining;
+    case 3:
+      return ZLinkFrameworkRuntimeState.Stopped;
+    case 4:
+      return ZLinkFrameworkRuntimeState.Error;
+    default:
+      fail('ClientServer runtime state is invalid.');
   }
 }
 

package/src/runtime/channels/dispatch-error-reporter.ts

@@ -108,10 +108,11 @@ function normalizeDispatchFailure(event: ZLinkRuntimeDispatchFailure): ZLinkRunt
 
 function channelDropReason(event: ZLinkRuntimeDispatchFailure): string | undefined {
   if (
-    event.action !== ZLinkDispatchErrorAction.Drop
-    || (event.surface !== ZLinkDispatchErrorSurface.Channel
-      && event.surface !== ZLinkDispatchErrorSurface.RouteMeshChannel)
-  ) return undefined;
+    event.action !== ZLinkDispatchErrorAction.Drop ||
+    (event.surface !== ZLinkDispatchErrorSurface.Channel &&
+      event.surface !== ZLinkDispatchErrorSurface.RouteMeshChannel)
+  )
+    return undefined;
   switch (event.reason) {
     case ZLinkDispatchErrorReason.HandlerMissing:
       return 'no_handler';
@@ -145,10 +146,12 @@ function dispatchErrorInfo(event: ZLinkRuntimeDispatchFailure): {
     return {
       errorType: event.error.name,
       errorMessage: event.error.message,
-      ...(cause === event.error ? {} : {
-        errorCauseType: cause instanceof Error ? cause.name : typeof cause,
-        errorCauseMessage: cause instanceof Error ? cause.message : String(cause)
-      })
+      ...(cause === event.error
+        ? {}
+        : {
+            errorCauseType: cause instanceof Error ? cause.name : typeof cause,
+            errorCauseMessage: cause instanceof Error ? cause.message : String(cause)
+          })
     };
   }
   return { errorType: typeof event.error, errorMessage: String(event.error) };