@zlink-systems/framework 0.13.0 → 0.15.0

package/src/contracts/Configuration/RegistrationBuilders.ts

@@ -100,6 +100,7 @@ import {
   validateSessionReplacementCallbackTimeout
 } from './RegistrationBuilderPolicy';
 import { requireMessageFlowLogMode, requireTraceSampleRate } from './DiagnosticsValidation';
+import { requirePublicFanoutTopic } from './FanoutTopic';
 
 export function createFrameworkOptions(
   configure: (options: ZLinkFrameworkOptions) => void
@@ -507,6 +508,11 @@ class DefaultFanoutChannelBuilder implements ZLinkFanoutChannelBuilder {
     return this;
   }
 
+  setNoDrop(noDrop = true): this {
+    this.channel.noDrop = noDrop;
+    return this;
+  }
+
   enableSubscriber(endpoint?: string): this {
     this.selectSubscriberMode(endpoint === undefined ? 'automatic' : 'manual');
     this.channel.subscriber ??= { manualConnections: [] };
@@ -519,6 +525,15 @@ class DefaultFanoutChannelBuilder implements ZLinkFanoutChannelBuilder {
     return this;
   }
 
+  subscribe(topic: string): this {
+    requirePublicFanoutTopic(topic);
+    this.channel.subscriptions ??= [];
+    if (!this.channel.subscriptions.includes(topic)) {
+      this.channel.subscriptions.push(topic);
+    }
+    return this;
+  }
+
   connect(endpoint: string): this {
     requireRegistrationName(endpoint, `Fanout channel '${this.name}' subscriber endpoint`);
     this.selectSubscriberMode('manual');
@@ -1528,8 +1543,10 @@ type MutableLocationOptionValues = {
 interface MutableChannelOptions {
   routingId?: string;
   routingIdPrefix?: string;
+  noDrop?: boolean;
   publisher?: MutablePublisherCapabilityOptions;
   publishHandlers?: ZLinkChannelPublishHandlerRegistration[];
+  subscriptions?: string[];
   subscriber?: MutableClientCapabilityOptions;
   client?: MutableClientCapabilityOptions;
   server?: MutableServerCapabilityOptions;

package/src/contracts/Configuration/RegistrationTypes.ts

@@ -170,11 +170,13 @@ export interface ZLinkFrameworkRegistrationOptions {
 export interface ZLinkChannelOptions {
   readonly routingId?: string;
   readonly routingIdPrefix?: string;
+  readonly noDrop?: boolean;
   readonly requestTimeoutMs?: number;
   readonly client?: ZLinkClientCapabilityOptions;
   readonly publisher?: ZLinkPublisherCapabilityOptions;
   readonly routeMesh?: ZLinkRouteMeshChannelOptions;
   readonly publishHandlers?: readonly ZLinkChannelPublishHandlerRegistration[];
+  readonly subscriptions?: readonly string[];
   readonly requestHandlers?: readonly ZLinkChannelRequestHandlerRegistration[];
   readonly sendHandlers?: readonly ZLinkChannelSendHandlerRegistration[];
   readonly server?: {

package/src/contracts/Configuration/RegistrationValidators.ts

@@ -20,6 +20,7 @@ import {
 import { validateTimerRegistration } from './TimerRegistrationValidator';
 import { zlinkDefaultLocationOptions } from '../Locations';
 import { requireValidSendTimeoutMs } from './SendTimeoutValidation';
+import { requirePublicFanoutTopic } from './FanoutTopic';
 
 export function validateFrameworkRegistration(
   registration: ZLinkFrameworkRegistration,
@@ -27,7 +28,6 @@ export function validateFrameworkRegistration(
 ): void {
   validateListenerNetworkIdentity(
     'process network',
-    undefined,
     registration.network.bindHost,
     registration.network.advertiseHost
   );
@@ -203,11 +203,28 @@ function validateChannelCapabilities(
   peerLocationConfigured: boolean
 ): void {
   for (const [channelName, channel] of Object.entries(channels ?? {})) {
+    for (const topic of channel.subscriptions ?? []) {
+      requirePublicFanoutTopic(topic);
+    }
+    if ((channel.subscriptions ?? []).length > 0 && channel.subscriber === undefined) {
+      throw new ZLinkConfigurationException(
+        `Channel '${channelName}' fanout subscriptions require a subscriber capability.`
+      );
+    }
+    if (channel.noDrop !== undefined && typeof channel.noDrop !== 'boolean') {
+      throw new ZLinkConfigurationException(
+        `Channel '${channelName}' NoDrop must be a boolean.`
+      );
+    }
+    if (channel.noDrop !== undefined && channel.publisher === undefined) {
+      throw new ZLinkConfigurationException(
+        `Channel '${channelName}' NoDrop requires a publisher role.`
+      );
+    }
     if (channel.server !== undefined) {
       requireEndpoint(`channel '${channelName}' server`, channel.server.bind);
       validateListenerNetworkIdentity(
         `channel '${channelName}' server`,
-        channel.server.bind,
         channel.server.bindHost,
         channel.server.advertiseHost
       );
@@ -221,7 +238,6 @@ function validateChannelCapabilities(
       requireEndpoint(`channel '${channelName}' publisher`, channel.publisher.bind);
       validateListenerNetworkIdentity(
         `channel '${channelName}' publisher`,
-        channel.publisher.bind,
         channel.publisher.bindHost,
         channel.publisher.advertiseHost
       );
@@ -307,7 +323,6 @@ function validateSpotNodes(registration: ZLinkFrameworkRegistration): void {
     if (spotNode.router !== undefined) {
       validateListenerNetworkIdentity(
         `SpotNode '${spotNodeName}' router`,
-        spotNode.router.bind,
         spotNode.router.bindHost,
         spotNode.router.advertiseHost
       );
@@ -418,11 +433,9 @@ function validateSpotNodeCapability(
 
 function validateListenerNetworkIdentity(
   capabilityName: string,
-  bindEndpoint: string | undefined,
   configuredBindHost: string | undefined,
   advertiseHost: string | undefined
 ): void {
-  const bindHost = configuredBindHost ?? tcpEndpointHost(bindEndpoint);
   if (configuredBindHost !== undefined) {
     requireName(`${capabilityName} bind host`, configuredBindHost);
   }
@@ -434,16 +447,6 @@ function validateListenerNetworkIdentity(
       );
     }
   }
-  if (bindHost !== undefined && isWildcardHost(bindHost) && advertiseHost === undefined) {
-    throw new ZLinkConfigurationException(
-      `${capabilityName} must define an advertise host when its bind host is a wildcard address.`
-    );
-  }
-}
-
-function tcpEndpointHost(endpoint: string | undefined): string | undefined {
-  const match = /^tcp:\/\/(\[[^\]]+\]|[^:]+):\d+$/.exec(endpoint ?? '');
-  return match?.[1];
 }
 
 function isWildcardHost(host: string): boolean {
@@ -550,7 +553,6 @@ function validateStreamNodes(registration: ZLinkFrameworkRegistration): void {
     requireEndpoint(`STREAM node '${streamNodeName}'`, streamNode.bind);
     validateListenerNetworkIdentity(
       `STREAM node '${streamNodeName}'`,
-      streamNode.bind,
       streamNode.bindHost,
       streamNode.advertiseHost
     );

package/src/runtime/backend/contracts/index.ts

@@ -568,6 +568,7 @@ export interface ZLinkBackendRouterSocket extends ZLinkBackendConnectableSocket
 
 export interface ZLinkBackendPublisherSocket extends ZLinkBackendSocket {
   sendHighWaterMark: number;
+  noDrop: boolean;
   publish(topic: string, message: Message | readonly Message[]): void;
 }
 

package/src/runtime/backend/node/node-backend-adapter-support.ts

@@ -1,5 +1,6 @@
 import { loadBinding } from '../node-backend-adapter';
-import { ZLinkBackendResultError } from '../runtime-values';
+import { SubmitResult, ZLinkBackendResultError } from '../runtime-values';
+import { requireOneWayCompletion, ZLinkSubmitStatus } from '../../messaging/submission-result';
 
 export type ZLinkBindingModule = typeof import('@zlink-systems/zlink');
 export const zlink = loadBinding() as ZLinkBindingModule;
@@ -80,7 +81,17 @@ export function submitBindingPublish(
     }
     current!.submit();
   } catch (error) {
-    throw translateBindingResultError(error);
+    const translated = translateBindingResultError(error);
+    if (translated instanceof ZLinkBackendResultError
+        && translated.operation === 'submit'
+        && (translated.result === SubmitResult.Backpressured
+          || translated.result === SubmitResult.NotAdmitted)) {
+      requireOneWayCompletion(
+        { status: ZLinkSubmitStatus.Backpressured },
+        'Classic fanout publish'
+      );
+    }
+    throw translated;
   }
 }
 

package/src/runtime/backend/node/node-socket-backend-adapter.ts

@@ -33,6 +33,7 @@ export function wrapSocket<T extends { close(): void }>(
       sendHwm?: number;
       recvHwm?: number;
       sendTimeout?: number;
+      noDrop?: boolean;
       maxMsgSize?: bigint;
       lastEndpoint?: string;
     };
@@ -116,6 +117,12 @@ export function wrapSocket<T extends { close(): void }>(
     set sendHighWaterMark(value: number) {
       requireSocketOptions(socket).sendHwm = value;
     },
+    get noDrop(): boolean {
+      return socket.options?.noDrop ?? false;
+    },
+    set noDrop(value: boolean) {
+      requireSocketOptions(socket).noDrop = value;
+    },
     get receiveHighWaterMark(): number {
       return Number(socket.options?.recvHwm ?? 0n);
     },

package/src/runtime/channels/channel-clients.ts

@@ -38,6 +38,7 @@ import {
   requireZLinkYieldTurn,
   type ZLinkSpotSerialTurn
 } from '../execution';
+import { requirePublicFanoutTopic } from './fanout-service-wire';
 import {
   requestToSpotHandle,
   sendToSpotHandle,
@@ -128,6 +129,7 @@ export class DefaultZLinkFanoutClient implements ZLinkFanoutClient {
     const topic = hasExplicitTopic
       ? topicOrEvent as string
       : resolveFrameworkPacketName(event, undefined, 'Fanout');
+    requirePublicFanoutTopic(topic);
     const packetName = resolveFrameworkPacketName(event, undefined, 'Fanout');
     return new DefaultZLinkFanoutPublishCall(
       () => this.requirePublisherChannel(channelName),

package/src/runtime/channels/channel-socket-registry.ts

@@ -4,6 +4,7 @@ import {
   type ZLinkClientServerServerDescriptor,
   type ZLinkFanoutPublisherDescriptor
 } from '../../contracts';
+import type { ZLinkChannelOptions } from '../../contracts/Configuration/RegistrationTypes';
 import { ZLinkSocketNativeEventType } from '../diagnostics/internal-event-contracts';
 import {
   buildAdvertisedEndpoint,
@@ -942,8 +943,7 @@ export class ZLinkChannelSocketRegistry {
     }
     const subscriber = this.adapter.createSubscriberSocket(this.context);
     subscriber.setChannelName(channelName);
-    subscriber.setSubscription('');
-    subscriber.setSubscription(FANOUT_LIVENESS_TOPIC);
+    setFanoutSubscriptions(subscriber, channel.subscriptions);
     const monitor = this.monitoringAdapter.openSocketMonitor(subscriber);
     const connection: FanoutPublisherConnection = {
       channelName,
@@ -1166,6 +1166,8 @@ export class ZLinkChannelSocketRegistry {
       const payload = RuntimeMessage.from(FANOUT_LIVENESS_PAYLOAD);
       try {
         publisher.publish(FANOUT_LIVENESS_TOPIC, payload);
+      } catch (error) {
+        this.oneWayFailureSink?.(error);
       } finally {
         payload.close();
       }
@@ -1566,6 +1568,7 @@ export class ZLinkChannelSocketRegistry {
 
     const publisher = this.adapter.createPublisherSocket(this.context);
     publisher.setChannelName(channelName);
+    applyFanoutPublisherSocketOptions(publisher, channel);
     publisher.bind(channel.publisher.bind);
     this.publishers.set(channelName, publisher);
     this.fanoutPublisherNextBeacon.set(
@@ -1780,6 +1783,16 @@ function closeMessages(parts: readonly Message[]): void {
   for (const part of parts) part.close();
 }
 
+function setFanoutSubscriptions(
+  subscriber: ZLinkBackendSubscriberSocket,
+  applicationTopics: readonly string[] | undefined
+): void {
+  const topics = new Set(applicationTopics);
+  if (topics.size === 0) topics.add('');
+  topics.add(FANOUT_LIVENESS_TOPIC);
+  for (const topic of topics) subscriber.setSubscription(topic);
+}
+
 function deriveRoutingId(baseRoutingId: string, suffix: string): string {
   const derived = `${baseRoutingId}\0${suffix}`;
   if (Buffer.byteLength(derived, 'utf8') > 255) {
@@ -1790,6 +1803,13 @@ function deriveRoutingId(baseRoutingId: string, suffix: string): string {
   return derived;
 }
 
+function applyFanoutPublisherSocketOptions(
+  publisher: ZLinkBackendPublisherSocket,
+  channel: ZLinkChannelOptions
+): void {
+  publisher.noDrop = channel.noDrop ?? false;
+}
+
 function fanoutDiscoveryConnectionId(connectionId: string): string {
   return `fanout:${connectionId.replaceAll('\0', '/')}`;
 }

package/src/runtime/channels/fanout-service-wire.ts

@@ -1,9 +1,12 @@
 import type { Message } from '../../contracts/Common/Message';
-import { ZLinkConfigurationException } from '../configuration';
+import {
+  FANOUT_LIVENESS_TOPIC,
+  requirePublicFanoutTopic
+} from '../../contracts/Configuration/FanoutTopic';
 import { tryDecodeChannelHeader } from './channel-envelope-inspection';
 import type { ZLinkChannelEnvelopeHeader } from './channel-envelope';
 
-export const FANOUT_LIVENESS_TOPIC = '\x01ZLF1';
+export { FANOUT_LIVENESS_TOPIC, requirePublicFanoutTopic };
 export const FANOUT_LIVENESS_PAYLOAD =
   Uint8Array.from([0x5a, 0x46, 0x01, 0x01]);
 
@@ -35,9 +38,3 @@ export function inspectFanoutInbound(
     ? { kind: 'beacon' }
     : { kind: 'protocolError' };
 }
-
-export function requirePublicFanoutTopic(topic: string): void {
-  if (topic === FANOUT_LIVENESS_TOPIC) {
-    throw new ZLinkConfigurationException('Fanout topic is reserved for framework liveness.');
-  }
-}

package/src/runtime/locations/in-memory-authority-store.ts

@@ -273,7 +273,15 @@ export class ZLinkInMemoryAuthorityStore {
       if (current.snapshot.allocation.state === 'active') {
         return { kind: 'alreadyExists', current: this.snapshot(current.snapshot) };
       }
-      return { kind: 'conflict', current: this.read(key) };
+      // An unfinished creation whose owner lease ended is cancellable.
+      // Reclaim it so the key does not stay blocked forever.
+      if (this.isOwnerLive(current.snapshot) || current.creation === undefined) {
+        return { kind: 'conflict', current: this.read(key) };
+      }
+      this.adjustCapacity(this.pendingCapacity, current.snapshot.allocation, -1);
+      this.rows.delete(key);
+      this.creationTerminals.set(current.creation.reservationId, 'aborted');
+      this.scanRevision++;
     }
     const target = creationTarget(request);
     if (!this.validation.isTargetLive(target.descriptor, target.lifecycleGeneration, target.owner)) {

package/src/runtime/locations/location-store-repository.ts

@@ -1082,9 +1082,62 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
         ) {
           return { kind: 'typeMismatch', current: snapshot };
         }
-        return snapshot.allocation.state === 'active'
-          ? { kind: 'alreadyExists', current: snapshot }
-          : { kind: 'conflict', current: snapshot };
+        if (snapshot.allocation.state === 'active') {
+          return { kind: 'alreadyExists', current: snapshot };
+        }
+        if (record.aggregate !== undefined
+          || isCanonicalAuthorityPayload(record.snapshot.payload)) {
+          // A relocation record carries its own recovery protocol. Reserve
+          // may reclaim only an unfinished plain creation.
+          return { kind: 'conflict', current: snapshot };
+        }
+        // The row is Reserved by another owner. An unfinished creation
+        // whose owner lease ended is cancellable, so reclaim it and retry
+        // instead of blocking the key forever.
+        const staleOwnerKey = ownerKey(snapshot.ownerId);
+        const staleCapacityKey = capacityKey(
+          snapshot.allocation.descriptor.meshName,
+          String(snapshot.allocation.descriptor.rid)
+        );
+        const [staleOwnerRead, staleCapacityRead] = await Promise.all([
+          this.provider.read(staleOwnerKey, signal),
+          this.provider.read(staleCapacityKey, signal)
+        ]);
+        if (staleOwnerRead.kind === 'found'
+          && staleOwnerRead.value.expiresAt === undefined) {
+          // A lease is always written with a positive TTL, so a missing
+          // expiry is a corrupt record. Reclaiming deletes authority state,
+          // so refuse rather than read the absence as expiry.
+          throw new Error('Location Store owner lease record is invalid.');
+        }
+        if (sameLiveOwner(staleOwnerRead, record.snapshot)) {
+          return { kind: 'conflict', current: snapshot };
+        }
+        const staleCapacity = staleCapacityRead.kind === 'missing'
+          ? emptyCapacityRecord()
+          : decodeJson<CapacityRecord>(staleCapacityRead.value.bytes);
+        await this.provider.write({
+          conditions: [
+            { kind: 'version', key: rowKey, expected: current.value.version },
+            versionCondition(staleOwnerKey, staleOwnerRead),
+            conditionFor(staleCapacityKey, staleCapacityRead)
+          ],
+          mutations: [
+            { kind: 'delete', key: rowKey },
+            {
+              kind: 'put',
+              key: staleCapacityKey,
+              bytes: encodeJson({
+                active: staleCapacity.active,
+                pending: subtractCapacity(
+                  staleCapacity.pending,
+                  record.snapshot.allocation.capacity
+                )
+              } satisfies CapacityRecord)
+            }
+          ]
+        }, signal);
+        continue;
       }
       const descriptor = liveTargetDescriptor(
         descriptorRead,
@@ -1291,6 +1344,12 @@ export class ZLinkLocationStoreRepository extends ZLinkInMemoryLocationStore {
         this.provider.read(leaseKey, signal),
         this.provider.read(capacityRowKey, signal)
       ]);
+      if (leaseRead.kind === 'found' && leaseRead.value.expiresAt === undefined) {
+        // A lease is always written with a positive TTL, so a missing expiry
+        // is a corrupt record. Abort deletes authority state, so refuse
+        // rather than read the absence as expiry.
+        throw new Error('Location Store owner lease record is invalid.');
+      }
       if (!sameLiveOwner(leaseRead, record.snapshot)) return { kind: 'stale' };
       const capacity = capacityRead.kind === 'missing'
         ? emptyCapacityRecord()
@@ -3879,6 +3938,17 @@ function sameCreationTarget(
     && snapshot.ownerLeaseGeneration === target.owner.leaseGeneration;
 }
 
+const CANONICAL_AUTHORITY_MAGIC = Buffer.from('ZLAU');
+
+function isCanonicalAuthorityPayload(payload: Uint8Array): boolean {
+  return payload.byteLength >= CANONICAL_AUTHORITY_MAGIC.byteLength
+    && Buffer.from(
+      payload.buffer,
+      payload.byteOffset,
+      CANONICAL_AUTHORITY_MAGIC.byteLength
+    ).equals(CANONICAL_AUTHORITY_MAGIC);
+}
+
 function sameLiveOwner(
   lease: ZLinkStoreReadResult,
   snapshot: StoredAuthoritySnapshot

package/src/runtime/streams/index.ts

@@ -16,7 +16,11 @@ import {
   ZLinkMessage
 } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
-import type { ZLinkFrameworkRegistration } from '../configuration';
+import {
+  buildAdvertisedEndpoint,
+  ZLinkConfigurationException,
+  type ZLinkFrameworkRegistration
+} from '../configuration';
 import { ZLinkDispatchErrorReporter } from '../channels';
 import type {
   ZLinkBackendAdapterFactory,
@@ -178,6 +182,7 @@ export interface ZLinkStreamRuntimeManagerOptions {
 
 interface ZLinkStartedStreamNode {
   readonly meshName?: string;
+  readonly advertisedEndpoint: string;
   readonly runtime: ZLinkStreamSessionNodeRuntimeCore;
   readonly socket: ZLinkBackendStreamSocket;
   readonly monitor: ZLinkBackendSocketMonitor;
@@ -220,6 +225,17 @@ export class ZLinkStreamRuntimeManager {
         );
       }
       socket.bind(streamNode.bind!);
+      const boundEndpoint = socket.lastEndpoint ?? streamNode.bind!;
+      const advertisedEndpoint = buildAdvertisedEndpoint(
+        boundEndpoint,
+        streamNode.advertiseHost,
+        'tcp'
+      );
+      if (advertisedEndpoint === undefined) {
+        throw new ZLinkConfigurationException(
+          `STREAM node '${nodeName}' advertised host requires a TCP endpoint, received '${boundEndpoint}'.`
+        );
+      }
       const readablePoller = streamAdapter.createReadablePoller(socket);
       const nativeSessionRoutes = new Map<string, {
         readonly service: StreamSessionService;
@@ -288,6 +304,7 @@ export class ZLinkStreamRuntimeManager {
       runtime.start();
       this.nodes.set(nodeName, {
         meshName: applicationMeshName,
+        advertisedEndpoint,
         runtime,
         socket,
         monitor,