@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/messaging/framework-json-v1.ts

@@ -1,326 +1,6 @@
-import type { ZLinkJsonSchema } from '../../contracts/Handlers/JsonContract';
+import * as profile from '@zlink-systems/stream-wire/internal/json';
 
-export const FRAMEWORK_JSON_V1_PROFILE = 'framework-json-v1';
-
-const SIGNED_64_MIN = -(1n << 63n);
-const UNSIGNED_64_MAX = (1n << 64n) - 1n;
-
-export interface FrameworkJsonParseOptions {
-  readonly rejectPropertyName?: (name: string) => boolean;
-}
-
-export function stringifyFrameworkJsonV1(value: unknown, schema?: ZLinkJsonSchema): string {
-  if (value === undefined || typeof value === 'function' || typeof value === 'symbol') {
-    throw new TypeError('framework-json-v1 payload is not a JSON value.');
-  }
-  const encoded = JSON.stringify(value, frameworkJsonV1Replacer);
-  if (schema !== undefined) {
-    validateFrameworkJsonV1Value(JSON.parse(encoded), schema, '$', false);
-  }
-  return encoded;
-}
-
-//  Module-level so JSON.stringify does not allocate a fresh closure per
-//  encoded message. On the root call `this` is the {'': value} wrapper, so
-//  this[key] resolves the raw (pre-toJSON) source for every key including ''.
-function frameworkJsonV1Replacer(
-  this: Record<string, unknown>,
-  key: string,
-  item: unknown
-): unknown {
-  const source = this[key];
-  if (typeof source === 'number' && !Number.isFinite(source)) {
-    throw new TypeError('framework-json-v1 only accepts finite JSON numbers.');
-  }
-  if (typeof source === 'bigint') {
-    if (source < SIGNED_64_MIN || source > UNSIGNED_64_MAX) {
-      throw new RangeError('framework-json-v1 64-bit integer is outside the supported range.');
-    }
-    return source.toString(10);
-  }
-  if (source instanceof Uint8Array) {
-    return Buffer.from(source.buffer, source.byteOffset, source.byteLength).toString('base64');
-  }
-  if (source instanceof Date) {
-    throw new TypeError('framework-json-v1 does not implicitly encode Date values.');
-  }
-  if (
-    typeof source === 'object' &&
-    source !== null &&
-    typeof (source as { readonly toJSON?: unknown }).toJSON === 'function'
-  ) {
-    throw new TypeError('framework-json-v1 does not implicitly invoke custom toJSON methods.');
-  }
-  return item;
-}
-
-export function parseFrameworkJsonV1(
-  text: string,
-  options: FrameworkJsonParseOptions = {},
-  schema?: ZLinkJsonSchema
-): unknown {
-  if (text.charCodeAt(0) === 0xfeff) {
-    throw new SyntaxError('framework-json-v1 does not allow a UTF-8 BOM.');
-  }
-  new JsonPropertyScanner(text, options).scan();
-  const parsed = JSON.parse(text);
-  return schema === undefined ? parsed : validateFrameworkJsonV1Value(parsed, schema, '$', true);
-}
-
-//  Sticky pattern shared across scans; matching happens synchronously so the
-//  mutable lastIndex never crosses calls.
-const NUMBER_TOKEN_PATTERN = /-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/uy;
-
-const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
-const INT32_MIN = -2_147_483_648;
-const INT32_MAX = 2_147_483_647;
-const UINT32_MAX = 4_294_967_295;
-
-function validateFrameworkJsonV1Value(
-  value: unknown,
-  schema: ZLinkJsonSchema,
-  path: string,
-  decode: boolean
-): unknown {
-  switch (schema.type) {
-    case 'boolean':
-      if (typeof value !== 'boolean') schemaFailure(path, 'a boolean');
-      return value;
-    case 'string':
-      if (typeof value !== 'string') schemaFailure(path, 'a string');
-      return value;
-    case 'number':
-      if (typeof value !== 'number' || !Number.isFinite(value))
-        schemaFailure(path, 'a finite number');
-      return value;
-    case 'int32':
-      if (
-        !Number.isInteger(value) ||
-        (value as number) < INT32_MIN ||
-        (value as number) > INT32_MAX
-      ) {
-        schemaFailure(path, 'an int32 JSON number');
-      }
-      return value;
-    case 'uint32':
-      if (!Number.isInteger(value) || (value as number) < 0 || (value as number) > UINT32_MAX) {
-        schemaFailure(path, 'a uint32 JSON number');
-      }
-      return value;
-    case 'int64':
-      return validateDecimalInteger(value, path, true, decode);
-    case 'uint64':
-      return validateDecimalInteger(value, path, false, decode);
-    case 'bytes': {
-      if (typeof value !== 'string' || !BASE64_PATTERN.test(value)) {
-        schemaFailure(path, 'padded RFC 4648 base64');
-      }
-      const bytes = Buffer.from(value as string, 'base64');
-      if (bytes.toString('base64') !== value)
-        schemaFailure(path, 'canonical padded RFC 4648 base64');
-      return decode ? Uint8Array.from(bytes) : value;
-    }
-    case 'enum':
-      if (typeof value !== 'string' || !schema.names.includes(value)) {
-        schemaFailure(path, `one of ${schema.names.join(', ')}`);
-      }
-      return value;
-    case 'nullable':
-      return value === null
-        ? null
-        : validateFrameworkJsonV1Value(value, schema.value, path, decode);
-    case 'array':
-      if (!Array.isArray(value)) schemaFailure(path, 'an array');
-      return (value as unknown[]).map((item, index) =>
-        validateFrameworkJsonV1Value(item, schema.items, `${path}[${index}]`, decode)
-      );
-    case 'record': {
-      if (!isJsonObject(value)) schemaFailure(path, 'an object');
-      const result: Record<string, unknown> = {};
-      for (const [name, item] of Object.entries(value as Record<string, unknown>)) {
-        result[name] = validateFrameworkJsonV1Value(item, schema.values, `${path}.${name}`, decode);
-      }
-      return decode ? result : value;
-    }
-    case 'object': {
-      if (!isJsonObject(value)) schemaFailure(path, 'an object');
-      const input = value as Record<string, unknown>;
-      for (const name of schema.required) {
-        if (!Object.prototype.hasOwnProperty.call(input, name)) {
-          throw new TypeError(`framework-json-v1 required property '${path}.${name}' is missing.`);
-        }
-      }
-      const result: Record<string, unknown> = {};
-      for (const [name, item] of Object.entries(input)) {
-        const propertySchema: unknown = schema.properties[name];
-        if (propertySchema === undefined) {
-          if (schema.additionalProperties === false) {
-            throw new TypeError(`framework-json-v1 property '${path}.${name}' is not allowed.`);
-          }
-          continue;
-        }
-        result[name] = validateFrameworkJsonV1Value(
-          item,
-          propertySchema as ZLinkJsonSchema,
-          `${path}.${name}`,
-          decode
-        );
-      }
-      return decode ? result : value;
-    }
-  }
-}
-
-function validateDecimalInteger(
-  value: unknown,
-  path: string,
-  signed: boolean,
-  decode: boolean
-): unknown {
-  if (typeof value !== 'string' || !/^(?:0|[1-9][0-9]*|-[1-9][0-9]*)$/u.test(value)) {
-    schemaFailure(
-      path,
-      signed ? 'a canonical int64 decimal string' : 'a canonical uint64 decimal string'
-    );
-  }
-  const parsed = BigInt(value as string);
-  const minimum = signed ? SIGNED_64_MIN : 0n;
-  const maximum = signed ? (1n << 63n) - 1n : UNSIGNED_64_MAX;
-  if (parsed < minimum || parsed > maximum)
-    schemaFailure(path, signed ? 'an int64 value' : 'a uint64 value');
-  return decode ? parsed : value;
-}
-
-function isJsonObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function schemaFailure(path: string, expected: string): never {
-  throw new TypeError(`framework-json-v1 value '${path}' must be ${expected}.`);
-}
-
-class JsonPropertyScanner {
-  private index = 0;
-
-  constructor(
-    private readonly text: string,
-    private readonly options: FrameworkJsonParseOptions
-  ) {}
-
-  scan(): void {
-    this.skipWhitespace();
-    this.scanValue();
-    this.skipWhitespace();
-    if (this.index !== this.text.length) this.fail('trailing data');
-  }
-
-  private scanValue(): void {
-    this.skipWhitespace();
-    const token = this.text[this.index];
-    if (token === '{') return this.scanObject();
-    if (token === '[') return this.scanArray();
-    if (token === '"') {
-      this.scanString();
-      return;
-    }
-    if (token === 't') return this.scanLiteral('true');
-    if (token === 'f') return this.scanLiteral('false');
-    if (token === 'n') return this.scanLiteral('null');
-    this.scanNumber();
-  }
-
-  private scanObject(): void {
-    this.index++;
-    this.skipWhitespace();
-    if (this.text[this.index] === '}') {
-      this.index++;
-      return;
-    }
-    const properties = new Set<string>();
-    for (;;) {
-      this.skipWhitespace();
-      if (this.text[this.index] !== '"') this.fail('object property name');
-      const property = this.scanString();
-      if (properties.has(property)) {
-        throw new SyntaxError(`framework-json-v1 duplicate property '${property}'.`);
-      }
-      properties.add(property);
-      if (this.options.rejectPropertyName?.(property) === true) {
-        throw new SyntaxError(`framework-json-v1 property '${property}' is not allowed.`);
-      }
-      this.skipWhitespace();
-      if (this.text[this.index] !== ':') this.fail("':' after object property");
-      this.index++;
-      this.scanValue();
-      this.skipWhitespace();
-      const delimiter = this.text[this.index++];
-      if (delimiter === '}') return;
-      if (delimiter !== ',') this.fail("',' or '}' after object property");
-    }
-  }
-
-  private scanArray(): void {
-    this.index++;
-    this.skipWhitespace();
-    if (this.text[this.index] === ']') {
-      this.index++;
-      return;
-    }
-    for (;;) {
-      this.scanValue();
-      this.skipWhitespace();
-      const delimiter = this.text[this.index++];
-      if (delimiter === ']') return;
-      if (delimiter !== ',') this.fail("',' or ']' after array item");
-    }
-  }
-
-  private scanString(): string {
-    const start = this.index++;
-    let sawEscape = false;
-    for (;;) {
-      if (this.index >= this.text.length) this.fail('unterminated string');
-      const character = this.text[this.index++]!;
-      if (character === '"') {
-        //  Without escapes the token content is verbatim; the outer
-        //  JSON.parse pass still rejects any raw control characters.
-        return sawEscape
-          ? (JSON.parse(this.text.slice(start, this.index)) as string)
-          : this.text.slice(start + 1, this.index - 1);
-      }
-      if (character === '\\') {
-        sawEscape = true;
-        if (this.index >= this.text.length) this.fail('unterminated escape');
-        const escaped = this.text[this.index++]!;
-        if (escaped === 'u') this.index += 4;
-      }
-    }
-  }
-
-  private scanLiteral(value: 'true' | 'false' | 'null'): void {
-    if (!this.text.startsWith(value, this.index)) this.fail(value);
-    this.index += value.length;
-  }
-
-  private scanNumber(): void {
-    NUMBER_TOKEN_PATTERN.lastIndex = this.index;
-    const match = NUMBER_TOKEN_PATTERN.exec(this.text);
-    if (match === null) this.fail('JSON value');
-    this.index += match[0].length;
-  }
-
-  private skipWhitespace(): void {
-    for (;;) {
-      const code = this.text.charCodeAt(this.index);
-      if (code === 0x20 || code === 0x09 || code === 0x0a || code === 0x0d) {
-        this.index += 1;
-        continue;
-      }
-      return;
-    }
-  }
-
-  private fail(expected: string): never {
-    throw new SyntaxError(`framework-json-v1 expected ${expected} at offset ${this.index}.`);
-  }
-}
+export const FRAMEWORK_JSON_V1_PROFILE = profile.FRAMEWORK_JSON_V1_PROFILE;
+export const stringifyFrameworkJsonV1 = profile.stringifyFrameworkJsonV1;
+export const parseFrameworkJsonV1 = profile.parseFrameworkJsonV1;
+export type { FrameworkJsonParseOptions } from '@zlink-systems/stream-wire/internal/json';

package/src/runtime/messaging/packet-name.ts

@@ -1,3 +1,7 @@
+import {
+  readFrameworkPacketJsonContract,
+  normalizePacketName
+} from '@zlink-systems/stream-wire/internal/json';
 import { readZLinkDecoratorMetadata } from '../../contracts/Handlers/Attributes';
 import type { ZLinkPacketJsonContract } from '../../contracts/Handlers/JsonContract';
 import { ZLinkConfigurationException } from '../configuration';
@@ -42,23 +46,7 @@ export function resolveFrameworkPacketJsonContract(
   return readFrameworkPacketJsonContract(constructor, explicitPacketName);
 }
 
-export function readFrameworkPacketJsonContract(
-  type: object,
-  explicitPacketName?: string
-): ZLinkPacketJsonContract | undefined {
-  const expectedPacketName = normalizePacketName(explicitPacketName);
-  for (const metadata of readZLinkDecoratorMetadata(type)) {
-    if (
-      metadata.kind === 'packet' &&
-      metadata.jsonContract !== undefined &&
-      (expectedPacketName === undefined ||
-        normalizePacketName(metadata.packetName) === expectedPacketName)
-    ) {
-      return metadata.jsonContract;
-    }
-  }
-  return undefined;
-}
+export { readFrameworkPacketJsonContract } from '@zlink-systems/stream-wire/internal/json';
 
 function tryDecoratorPacketName(payload: unknown): string | undefined {
   if (typeof payload !== 'object' || payload === null) {
@@ -86,11 +74,3 @@ function tryConstructorPacketName(payload: unknown): string | undefined {
   }
   return normalizePacketName(name);
 }
-
-function normalizePacketName(value: unknown): string | undefined {
-  if (typeof value !== 'string') {
-    return undefined;
-  }
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-}

package/src/runtime/messaging/payload-codec.ts

@@ -17,10 +17,7 @@ import {
   materializeZLinkMessageValue,
   readZLinkMessageDeclaredType
 } from '../../contracts/Common/ZLinkMessage';
-import {
-  adoptEncodedPayload,
-  borrowEncodedPayload
-} from '../../contracts/Common/encoded-payload-storage';
+import { borrowEncodedPayload } from '../../contracts/Common/encoded-payload-storage';
 import { ZLinkConfigurationException } from '../configuration';
 import { parseFrameworkJsonV1, stringifyFrameworkJsonV1 } from './framework-json-v1';
 import type { ZLinkJsonSchema } from '../../contracts/Handlers/JsonContract';
@@ -434,13 +431,13 @@ function toRuntimeMessage(payload: ZLinkEncodedPayload): Message {
     : RuntimeMessage.fromOwned(owned);
 }
 
-function encodedPayloadFromOwned(bytes: Uint8Array): ZLinkEncodedPayload {
-  if (!Buffer.isBuffer(bytes)) {
-    return ZLinkEncodedPayload.from(bytes);
-  }
-  const payload = ZLinkEncodedPayload.from(Buffer.alloc(0));
-  adoptEncodedPayload(payload, bytes);
-  return payload;
+/**
+ * Wraps received bytes for a serializer without copying them. Binding receive
+ * Buffers keep their storage after the message closes and nothing writes to
+ * them, so the payload may adopt them; the public from() and data() still copy.
+ */
+export function encodedPayloadFromOwned(bytes: Uint8Array): ZLinkEncodedPayload {
+  return ZLinkEncodedPayload.fromOwned(bytes);
 }
 
 function rememberContentType(message: Message, contentType: string): Message {

package/src/runtime/messaging/request-result.ts

@@ -0,0 +1,62 @@
+import type { ZLinkRequest } from '../../contracts/Handlers/Attributes';
+
+const completedAdmission = Promise.resolve();
+const ignoreAdmissionFailure = (): void => {};
+
+class RequestAdmission {
+  private admitted: Promise<void> | undefined;
+  private resolveAdmission: (() => void) | undefined;
+  private rejectAdmission: ((error: unknown) => void) | undefined;
+  confirm(): void {
+    this.admitted ??= completedAdmission;
+    this.resolveAdmission?.();
+  }
+  fail(error: unknown): void {
+    if (this.admitted === undefined) {
+      this.admitted = Promise.reject(error);
+      // Existing callers may observe only the reply Promise. Observing the
+      // rejection here leaves the public admission Promise rejected.
+      void this.admitted.catch(ignoreAdmissionFailure);
+    } else {
+      this.rejectAdmission?.(error);
+    }
+  }
+  observe(): Promise<void> {
+    if (this.admitted === undefined) {
+      this.admitted = new Promise<void>((resolve, reject) => {
+        this.resolveAdmission = resolve;
+        this.rejectAdmission = reject;
+      });
+      void this.admitted.catch(ignoreAdmissionFailure);
+    }
+    return this.admitted;
+  }
+}
+
+export function createZLinkRequest<TReply>(
+  start: (onAdmitted: () => void) => Promise<TReply>,
+  deliverReply?: (reply: Promise<TReply>) => Promise<TReply>
+): ZLinkRequest<TReply> {
+  const admission = new RequestAdmission();
+  let pending: Promise<TReply>;
+  try {
+    pending = start(() => admission.confirm());
+  } catch (error) {
+    pending = Promise.reject(error);
+  }
+  const observed = pending.then(
+    (value) => {
+      // A successful reply proves admission even without an observation callback.
+      admission.confirm();
+      return value;
+    },
+    (error: unknown) => {
+      admission.fail(error);
+      throw error;
+    }
+  );
+  const reply = deliverReply?.(observed) ?? observed;
+  return Object.defineProperty(reply, 'admitted', {
+    get: () => admission.observe()
+  }) as ZLinkRequest<TReply>;
+}

package/src/runtime/messaging/submission-result.ts

@@ -18,6 +18,10 @@ export interface ZLinkSubmitResult {
   readonly status: ZLinkSubmitStatus;
 }
 
+export const submittedResult: ZLinkSubmitResult = Object.freeze({
+  status: ZLinkSubmitStatus.Submitted
+});
+
 /** Projects typed submit failure; capacity refusal has no admission wait token. */
 export function submitToRequestResult(result: number, phase: 'submit' | 'completion'): number {
   switch (result) {
@@ -54,7 +58,7 @@ export function classifySubmitResult(
   const terminal = submitToRequestResult(result, phase);
   switch (terminal) {
     case RequestResult.Ok:
-      return { status: ZLinkSubmitStatus.Submitted };
+      return submittedResult;
     case RequestResult.TimedOut:
       return { status: ZLinkSubmitStatus.TimedOut };
     case RequestResult.NotFound: