@zlink-systems/framework 0.10.0

package/src/contracts/Configuration/RegistrationCodecRegistry.ts

@@ -0,0 +1,118 @@
+import type {
+  ZLinkCodecExtension,
+  ZLinkCodecRegistrar,
+  ZLinkCodecRegistryBuilder,
+  ZLinkMessageTypeSelector,
+  ZLinkMessageSerializer
+} from '../Codecs';
+import type {
+  ZLinkCodecRegistration,
+  ZLinkCodecRegistryOptions,
+  ZLinkCodecSerializerRegistration,
+  ZLinkStreamCodecRegistration
+} from './RegistrationTypes';
+import { normalizeCodecContentType } from './CodecContentType';
+import {
+  matchEveryDeclaredMessageType,
+  rememberCodecSerializerSelections
+} from './CodecSerializerSelection';
+
+export interface MutableCodecRegistryOptions {
+  serializers: ZLinkCodecSerializerRegistration[];
+  streamCodecs: ZLinkStreamCodecRegistration[];
+}
+
+export function createCodecRegistry(
+  options: ZLinkCodecRegistryOptions | undefined
+): RegistrationCodecRegistryBuilder {
+  return new RegistrationCodecRegistryBuilder({
+    serializers: [...(options?.serializers ?? [])],
+    streamCodecs: [...(options?.streamCodecs ?? [])]
+  });
+}
+
+export class RegistrationCodecRegistryBuilder implements ZLinkCodecRegistryBuilder, ZLinkCodecRegistrar {
+  private readonly options: MutableCodecRegistryOptions;
+
+  constructor(options: MutableCodecRegistryOptions = { serializers: [], streamCodecs: [] }) {
+    this.options = options;
+    const serializers = [...options.serializers];
+    const streamCodecs = [...options.streamCodecs];
+    options.serializers.length = 0;
+    options.streamCodecs.length = 0;
+    for (const entry of serializers) {
+      if (entry.canSerialize === undefined) {
+        this.addSerializer(entry.contentType, entry.serializer);
+      } else {
+        this.addSerializer(entry.contentType, entry.serializer, entry.canSerialize);
+      }
+    }
+    for (const entry of streamCodecs) {
+      this.addStreamCodec(entry.contentType, entry.codec);
+    }
+  }
+
+  get registeredSerializers(): ReadonlyMap<string, ZLinkMessageSerializer> {
+    const serializers = new Map(
+      this.options.serializers.map((entry) => [entry.contentType, entry.serializer])
+    );
+    const selections = new Map(
+      this.options.serializers.map((entry) => [
+        entry.contentType,
+        {
+          selector: entry.canSerialize ?? matchEveryDeclaredMessageType,
+          fallback: entry.canSerialize === undefined
+        }
+      ])
+    );
+    return rememberCodecSerializerSelections(serializers, selections);
+  }
+
+  get registeredStreamCodecs(): ReadonlyMap<string, unknown> {
+    return new Map(this.options.streamCodecs.map((entry) => [entry.contentType, entry.codec]));
+  }
+
+  get registration(): ZLinkCodecRegistration {
+    return {
+      serializers: this.registeredSerializers,
+      streamCodecs: this.registeredStreamCodecs
+    };
+  }
+
+  get registeredCodecs(): readonly string[] {
+    return this.options.serializers.map((entry) => entry.contentType);
+  }
+
+  use(extension: ZLinkCodecExtension): this {
+    extension.register(this);
+    return this;
+  }
+
+  addSerializer(contentType: string, serializer: ZLinkMessageSerializer): this;
+  addSerializer(
+    contentType: string,
+    serializer: ZLinkMessageSerializer,
+    canSerialize: ZLinkMessageTypeSelector
+  ): this;
+  addSerializer(
+    contentType: string,
+    serializer: ZLinkMessageSerializer,
+    canSerialize?: ZLinkMessageTypeSelector
+  ): this {
+    const normalized = normalizeCodecContentType(contentType);
+    const existing = this.options.serializers.findIndex((entry) => entry.contentType === normalized);
+    const registration = { contentType: normalized, serializer, canSerialize };
+    if (existing >= 0) this.options.serializers.splice(existing, 1);
+    this.options.serializers.push(registration);
+    return this;
+  }
+
+  addStreamCodec(contentType: string, codec: unknown): this {
+    const normalized = normalizeCodecContentType(contentType);
+    const existing = this.options.streamCodecs.findIndex((entry) => entry.contentType === normalized);
+    const registration = { contentType: normalized, codec };
+    if (existing >= 0) this.options.streamCodecs.splice(existing, 1);
+    this.options.streamCodecs.push(registration);
+    return this;
+  }
+}

package/src/contracts/Configuration/RegistrationNormalizers.ts

@@ -0,0 +1,404 @@
+import type {
+  Type,
+  ZLinkSpot,
+  ZLinkStreamCompressionOptions,
+  ZLinkStreamCompressionCodec
+} from '../../contracts';
+import { ZLinkConfigurationException } from './ConfigurationException';
+import {
+  copyRouteInternalState,
+  markRouteTransportDeclared
+} from './RouteChannelInternalState';
+import type {
+  ZLinkChannelOptions,
+  ZLinkFrameworkRegistration,
+  ZLinkFrameworkRegistrationOptions,
+  ZLinkLocationRegistration,
+  ZLinkRouteChannelOptions,
+  ZLinkSpotNodeOptions,
+  ZLinkStreamNodeOptions,
+  ZLinkWorkerOptions
+} from './RegistrationTypes';
+import type { ZLinkNetworkOptions } from './Builders';
+import { normalizeEndpoint, parseEndpointHostPort } from './EndpointNotation';
+import {
+  defaultWorkerMaxThreads,
+  DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE,
+  DEFAULT_WORKER_IDLE_TIMEOUT_MS,
+  DEFAULT_WORKER_MIN_THREADS,
+  DEFAULT_WORKER_QUEUE_LENGTH
+} from './InternalDefaults';
+
+export function normalizeWorkerOptions(
+  value: ZLinkFrameworkRegistrationOptions['worker']
+): ZLinkWorkerOptions | undefined {
+  if (value === undefined) return undefined;
+  const partial = value as Partial<ZLinkWorkerOptions>;
+  return {
+    minThreads: partial.minThreads ?? DEFAULT_WORKER_MIN_THREADS,
+    maxThreads: partial.maxThreads ?? defaultWorkerMaxThreads(),
+    idleTimeoutMs: partial.idleTimeoutMs ?? DEFAULT_WORKER_IDLE_TIMEOUT_MS,
+    maxQueueLength: partial.maxQueueLength ?? DEFAULT_WORKER_QUEUE_LENGTH
+  };
+}
+
+export function normalizeNetworkOptions(
+  value: ZLinkFrameworkRegistrationOptions['network']
+): ZLinkNetworkOptions {
+  return {
+    bindHost: value?.bindHost ?? '127.0.0.1',
+    ...(value?.advertiseHost === undefined ? {} : { advertiseHost: value.advertiseHost })
+  };
+}
+
+export function toChannelMap(
+  channels: ZLinkFrameworkRegistrationOptions['channels'],
+  network: ZLinkNetworkOptions
+): Map<string, ZLinkChannelOptions> {
+  return new Map(Object.entries(channels ?? {}).map(([name, channel]) => {
+    const server = channel.server === undefined
+      ? undefined
+      : normalizeListener(channel.server, network);
+    const publisher = channel.publisher === undefined
+      ? undefined
+      : normalizeListener(channel.publisher, network);
+    // In-place: channel.client/subscriber.manualConnections can be the same
+    // array a live RuntimeEndpointConnections handle mutates, so this must
+    // not replace the array or the containing client/subscriber object.
+    normalizeEndpointList(channel.client?.manualConnections);
+    normalizeEndpointList(channel.subscriber?.manualConnections);
+    return [name, {
+      ...channel,
+      ...(server === undefined ? {} : { server }),
+      ...(publisher === undefined ? {} : { publisher }),
+      requestTimeoutMs: normalizeOptionalPositiveInteger(channel.requestTimeoutMs, `${name}.requestTimeoutMs`)
+    }];
+  }));
+}
+
+export function toStreamNodeMap(
+  streamNodes: ZLinkFrameworkRegistrationOptions['streamNodes'],
+  network: ZLinkNetworkOptions
+): Map<string, ZLinkStreamNodeOptions> {
+  return new Map(Object.entries(streamNodes ?? {}).map(([name, streamNode]) => {
+    const normalized = normalizeListener(streamNode, network);
+    return [name, {
+      ...normalized,
+      maxMessageSize: streamNode.maxMessageSize ?? DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE
+    }];
+  }));
+}
+
+export function toRouteChannelOptions(
+  options: ZLinkFrameworkRegistrationOptions
+): Map<string, ZLinkRouteChannelOptions> {
+  const routeOptions = new Map<string, ZLinkRouteChannelOptions>();
+  for (const routeChannel of options.routeChannels ?? []) {
+    if (typeof routeChannel === 'string') {
+      routeOptions.set(routeChannel, { routerChannelId: routeChannel });
+      continue;
+    }
+    const normalized = {
+      ...routeChannel,
+      manualConnections: normalizeEndpointList(routeChannel.manualConnections),
+      requestTimeoutMs: normalizeOptionalPositiveInteger(
+        routeChannel.requestTimeoutMs,
+        `${routeChannel.routerChannelId}.requestTimeoutMs`
+      )
+    } as ZLinkRouteChannelOptions;
+    copyRouteInternalState(routeChannel, normalized);
+    routeOptions.set(routeChannel.routerChannelId, normalized);
+  }
+  for (const [channelName, channel] of Object.entries(options.channels ?? {})) {
+    if (channel.routeMesh === undefined) {
+      continue;
+    }
+    if (routeOptions.has(channelName)) {
+      throw new ZLinkConfigurationException(`Route mesh channel '${channelName}' is already registered.`);
+    }
+    const routeChannel = {
+      routerChannelId: channelName,
+      ...channel.routeMesh,
+      manualConnections: normalizeEndpointList(channel.routeMesh.manualConnections),
+      requestTimeoutMs: normalizeOptionalPositiveInteger(
+        channel.routeMesh.requestTimeoutMs,
+        `${channelName}.routeMesh.requestTimeoutMs`
+      )
+    } as ZLinkRouteChannelOptions;
+    markRouteTransportDeclared(routeChannel);
+    copyRouteInternalState(channel.routeMesh, routeChannel);
+    routeOptions.set(channelName, routeChannel);
+  }
+  return routeOptions;
+}
+
+export function requirePositiveInteger(label: string, value: number | undefined): void {
+  if (value === undefined) {
+    return;
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new ZLinkConfigurationException(`${label} must be a positive integer.`);
+  }
+}
+
+export function normalizeOptionalPositiveInteger(value: number | undefined, label: string): number | undefined {
+  requirePositiveInteger(label, value);
+  return value;
+}
+
+export function hasSpotNode(registration: ZLinkFrameworkRegistration): boolean {
+  return registration.spotNodes.size > 0;
+}
+
+export function hasActorManager(registration: ZLinkFrameworkRegistration): boolean {
+  const hasObjectCapability = [...registration.spotNodes.values()].some(node =>
+    node.objectRole === 'client'
+    || node.objectRole === 'server'
+    || (
+      node.actorFactories instanceof Map
+        ? node.actorFactories.size > 0
+        : Object.keys(node.actorFactories ?? {}).length > 0
+    )
+    || Object.keys(node.actorFactoryRegistrations ?? {}).length > 0
+  );
+  return hasObjectCapability && (
+    registration.locations.useInMemoryStores
+    || registration.locations.storeInstance !== undefined
+  );
+}
+
+export function hasSpotPublisherClient(registration: ZLinkFrameworkRegistration): boolean {
+  return registration.spotPublisherClients.size > 0;
+}
+
+export function toTypeMap(value: ZLinkSpotNodeOptions['actorFactories']): Map<string, Type> {
+  if (value === undefined) {
+    return new Map();
+  }
+  if (value instanceof Map) {
+    return new Map(value);
+  }
+  return new Map(Object.entries(value));
+}
+
+export function typeMapToRecord(value: ZLinkSpotNodeOptions['actorFactories']): Record<string, Type> {
+  if (value === undefined) {
+    return {};
+  }
+  if (isTypeMap(value)) {
+    return Object.fromEntries(value) as Record<string, Type>;
+  }
+  return { ...(value as Readonly<Record<string, Type>>) };
+}
+
+function isTypeMap(value: ZLinkSpotNodeOptions['actorFactories']): value is Map<string, Type> {
+  return value instanceof Map;
+}
+
+export function actorFactoriesFromSpotNodes(spotNodes: ReadonlyMap<string, ZLinkSpotNodeOptions>): Map<string, Type> {
+  const actorCapableNodes = [...spotNodes.values()].filter((spotNode) => toTypeMap(spotNode.actorFactories).size > 0);
+  if (actorCapableNodes.length === 0) {
+    return new Map();
+  }
+  return toTypeMap(actorCapableNodes[0].actorFactories);
+}
+
+export function toSpotNodeMap(
+  value: ZLinkFrameworkRegistrationOptions['spotNodes'],
+  network: ZLinkNetworkOptions
+): Map<string, ZLinkSpotNodeOptions> {
+  if (value === undefined) {
+    return new Map();
+  }
+  if (!Array.isArray(value)) {
+    return new Map(Object.entries(value).map(([name, spotNode]) => [
+      name,
+      normalizeSpotNodeOptions(spotNode, network)
+    ]));
+  }
+  return new Map(value.map((spotNode) => {
+    if (typeof spotNode === 'string') {
+      return [spotNode, normalizeSpotNodeOptions({}, network)];
+    }
+    const { name, ...options } = spotNode;
+    return [name, normalizeSpotNodeOptions(options, network)];
+  }));
+}
+
+function normalizeSpotNodeOptions(
+  spotNode: ZLinkSpotNodeOptions,
+  network: ZLinkNetworkOptions
+): ZLinkSpotNodeOptions {
+  const router = spotNode.router === undefined
+    ? undefined
+    : normalizeListener(spotNode.router, network);
+  return {
+    ...spotNode,
+    router: router === undefined
+      ? undefined
+      : {
+          ...router,
+          routingId: router.routingId ?? spotNode.routingId,
+          manualConnections: normalizeEndpointList(router.manualConnections),
+          manualPeerConnections: normalizeManualPeerConnections(router.manualPeerConnections)
+        },
+    pubSub: spotNode.pubSub === undefined
+      ? undefined
+      : {
+          ...spotNode.pubSub,
+          routingId: spotNode.pubSub.routingId ?? spotNode.routingId,
+          manualConnections: normalizeEndpointList(spotNode.pubSub.manualConnections)
+        }
+  };
+}
+
+function normalizeListener<
+  T extends {
+    readonly bind?: string;
+    readonly bindHost?: string;
+    readonly advertiseHost?: string;
+    readonly port?: number;
+  }
+>(listener: T, network: ZLinkNetworkOptions): T & {
+  readonly bind: string;
+  readonly bindHost?: string;
+  readonly port: number;
+} {
+  const usesConfiguredEndpoint = listener.bind !== undefined && listener.port === undefined;
+  const port = listener.port ?? (usesConfiguredEndpoint ? endpointPort(listener.bind!) : 0);
+  const bindHost = listener.bindHost
+    ?? (usesConfiguredEndpoint ? endpointHost(listener.bind!) : network.bindHost);
+  const bind = usesConfiguredEndpoint
+    ? normalizeEndpoint(listener.bind!)
+    : tcpEndpoint(bindHost ?? network.bindHost, port);
+  return {
+    ...listener,
+    bind,
+    bindHost,
+    port,
+    ...(listener.advertiseHost !== undefined
+      ? { advertiseHost: listener.advertiseHost }
+      : network.advertiseHost === undefined
+        ? {}
+        : { advertiseHost: network.advertiseHost })
+  };
+}
+
+/**
+ * Normalizes a declaratively-configured list of manual-connection endpoints
+ * (e.g. `channel.client.manualConnections`, `routeChannel.manualConnections`,
+ * `spotNode.router.manualConnections`) at the point the application hands
+ * them to the framework, so every later comparison/dedup can use plain
+ * string equality.
+ *
+ * Normalizes in place and preserves array identity when possible: this
+ * array can be the very array `RuntimeEndpointConnections`/builder handles
+ * mutate at runtime (see its constructor comment), so returning a copy
+ * would silently detach live `connect()`/`disconnect()` calls from the
+ * registered configuration. Only builds a new array when the input isn't a
+ * plain extensible array (frozen/sealed/external readonly).
+ */
+function normalizeEndpointList<T extends readonly string[] | undefined>(endpoints: T): T {
+  if (endpoints === undefined) return endpoints;
+  if (Array.isArray(endpoints) && Object.isExtensible(endpoints)) {
+    const mutable = endpoints as string[];
+    for (let index = 0; index < mutable.length; index += 1) {
+      mutable[index] = normalizeEndpoint(mutable[index]);
+    }
+    return endpoints;
+  }
+  return endpoints.map(normalizeEndpoint) as unknown as T;
+}
+
+function normalizeManualPeerConnections<T extends { readonly endpoint: string }>(
+  peers: readonly T[] | undefined
+): readonly T[] | undefined {
+  if (peers === undefined) return undefined;
+  return peers.map((peer) => ({ ...peer, endpoint: normalizeEndpoint(peer.endpoint) }));
+}
+
+function tcpEndpoint(host: string, port: number): string {
+  const endpointHost = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+  return normalizeEndpoint(`tcp://${endpointHost}:${port}`);
+}
+
+function endpointHost(endpoint: string): string | undefined {
+  return parseEndpointHostPort(endpoint, 'tcp')?.host;
+}
+
+function endpointPort(endpoint: string): number {
+  return parseEndpointHostPort(endpoint, 'tcp')?.port ?? 0;
+}
+
+export function toSpotFactorySet(
+  rootFactories: readonly Type<ZLinkSpot>[] | undefined,
+  spotNodes: ReadonlyMap<string, ZLinkSpotNodeOptions>
+): Set<Type<ZLinkSpot>> {
+  const factories = new Set(rootFactories ?? []);
+  for (const spotNode of spotNodes.values()) {
+    for (const spotFactory of spotNode.spotFactories ?? []) {
+      factories.add(spotFactory);
+    }
+  }
+  return factories;
+}
+
+export function toSpotPublisherClientSet(
+  explicitClients: readonly string[] | undefined,
+  spotNodes: ReadonlyMap<string, ZLinkSpotNodeOptions>
+): Set<string> {
+  const clients = new Set(explicitClients ?? []);
+  for (const spotNodeName of spotNodes.keys()) {
+    clients.add(spotNodeName);
+  }
+  return clients;
+}
+
+export function channelNamesWith(
+  channels: ZLinkFrameworkRegistrationOptions['channels'],
+  predicate: (channel: ZLinkChannelOptions) => boolean
+): Set<string> {
+  const names = new Set<string>();
+  for (const [name, channel] of Object.entries(channels ?? {})) {
+    if (predicate(channel)) {
+      names.add(name);
+    }
+  }
+  return names;
+}
+
+export function normalizeStreamCompression(
+  value: ZLinkFrameworkRegistrationOptions['streamCompression']
+): ZLinkStreamCompressionOptions | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value.disabled === true && value.codec !== undefined) {
+    throw new ZLinkConfigurationException('STREAM compression codec cannot be set when compression is disabled.');
+  }
+  if (value.codec !== undefined && !isStreamCompressionCodec(value.codec)) {
+    throw new ZLinkConfigurationException('STREAM compression codec must provide compress and decompress functions.');
+  }
+  return {
+    disabled: value.disabled,
+    codec: value.codec
+  };
+}
+
+export function isStreamCompressionCodec(value: unknown): value is ZLinkStreamCompressionCodec {
+  return typeof value === 'object'
+    && value !== null
+    && typeof (value as { compress?: unknown }).compress === 'function'
+    && typeof (value as { decompress?: unknown }).decompress === 'function';
+}
+
+export function normalizeLocationRegistration(
+  value: ZLinkFrameworkRegistrationOptions['locations']
+): ZLinkLocationRegistration {
+  return {
+    useInMemoryStores: value?.useInMemoryStores === true,
+    storeInstance: value?.storeInstance,
+    relocationStoreInstance: value?.relocationStoreInstance,
+    options: value?.options === undefined ? {} : { ...value.options }
+  };
+}