@forgeax/engine-net 0.0.0-dev.8d955ade1c79

package/src/replication/codec.ts

@@ -0,0 +1,323 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { REPLICATION_PROTOCOL_PREFIX, REPLICATION_PROTOCOL_VERSION } from './constants';
+import { NetError } from './errors';
+import type { ReplicationLimits } from './profile';
+import type { ReplicationDataPacket, ReplicationEntityRecord, ReplicationPacket } from './protocol';
+
+export type { ReplicationComponentRecord, ReplicationEntityRecord } from './protocol';
+
+type PortableTypedArray =
+  | Float32Array
+  | Float64Array
+  | Int8Array
+  | Int16Array
+  | Int32Array
+  | Uint8Array
+  | Uint8ClampedArray
+  | Uint16Array
+  | Uint32Array;
+
+const TYPED_ARRAYS = {
+  Float32Array,
+  Float64Array,
+  Int8Array,
+  Int16Array,
+  Int32Array,
+  Uint8Array,
+  Uint8ClampedArray,
+  Uint16Array,
+  Uint32Array,
+} as const;
+
+type TypedArrayName = keyof typeof TYPED_ARRAYS;
+
+const PACKET_KINDS = [
+  'session-open',
+  'session-resume',
+  'baseline',
+  'delta',
+  'ack',
+  'rejection',
+] as const satisfies readonly ReplicationPacket['kind'][];
+
+const REPLICATION_ENTITY_KINDS = [
+  'upsert',
+  'despawn',
+] as const satisfies readonly ReplicationEntityRecord['kind'][];
+
+function isPacketKind(value: unknown): value is ReplicationPacket['kind'] {
+  return PACKET_KINDS.some((kind) => kind === value);
+}
+
+function isReplicationEntityKind(value: unknown): value is ReplicationEntityRecord['kind'] {
+  return REPLICATION_ENTITY_KINDS.some((kind) => kind === value);
+}
+
+function isSafeNonNegativeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isSessionId(value: unknown): boolean {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+}
+
+function typedArrayName(value: unknown): TypedArrayName | undefined {
+  for (const [name, typedArrayConstructor] of Object.entries(TYPED_ARRAYS) as [
+    TypedArrayName,
+    (typeof TYPED_ARRAYS)[TypedArrayName],
+  ][]) {
+    if (value instanceof typedArrayConstructor) return name;
+  }
+  return undefined;
+}
+
+function canonicalize(value: unknown): unknown {
+  const name = typedArrayName(value);
+  if (name !== undefined)
+    return { $typedArray: name, values: Array.from(value as PortableTypedArray) };
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value !== null && typeof value === 'object')
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, canonicalize((value as Record<string, unknown>)[key])]),
+    );
+  return value;
+}
+
+function reviveTypedArrays(
+  value: unknown,
+): { readonly value: unknown } | { readonly reason: string } {
+  if (Array.isArray(value)) {
+    const values: unknown[] = [];
+    for (const item of value) {
+      const revived = reviveTypedArrays(item);
+      if ('reason' in revived) return revived;
+      values.push(revived.value);
+    }
+    return { value: values };
+  }
+  if (value === null || typeof value !== 'object') return { value };
+  const record = value as Record<string, unknown>;
+  if ('$typedArray' in record) {
+    if (
+      Object.keys(record).length !== 2 ||
+      typeof record.$typedArray !== 'string' ||
+      !Array.isArray(record.values)
+    )
+      return { reason: 'typed-array tag must contain only an allowlisted name and values array' };
+    const typedArrayConstructor = TYPED_ARRAYS[record.$typedArray as TypedArrayName];
+    if (
+      typedArrayConstructor === undefined ||
+      record.values.some((item) => typeof item !== 'number')
+    )
+      return { reason: 'typed-array tag contains an unsupported type or non-numeric value' };
+    return { value: new typedArrayConstructor(record.values) };
+  }
+  const revived: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(record)) {
+    const nested = reviveTypedArrays(item);
+    if ('reason' in nested) return nested;
+    revived[key] = nested.value;
+  }
+  return { value: revived };
+}
+
+function limitError(limit: string, actual: number, maximum: number): NetError {
+  return new NetError({
+    code: 'decode-limit-exceeded',
+    expected: `${limit} must not exceed ${maximum}`,
+    hint: 'reduce the replicated payload or configure matching declared limits',
+    detail: { limit, actual, maximum },
+  });
+}
+
+function invalid(reason: string): NetError {
+  return new NetError({
+    code: 'decode-invalid-payload',
+    expected: `a version ${REPLICATION_PROTOCOL_VERSION} ${REPLICATION_PROTOCOL_PREFIX} packet`,
+    hint: 'send bytes produced by the protocol-v2 replication codec',
+    detail: { reason },
+  });
+}
+
+function validateEntities(entities: readonly ReplicationEntityRecord[]): string | undefined {
+  const ids = new Set<number>();
+  for (const [entityIndex, entity] of entities.entries()) {
+    if (
+      entity === null ||
+      typeof entity !== 'object' ||
+      !isSafeNonNegativeInteger(entity.id) ||
+      !isReplicationEntityKind(entity.kind) ||
+      !Array.isArray(entity.components) ||
+      ids.has(entity.id)
+    )
+      return `entity record ${entityIndex} has an invalid or duplicate identity`;
+    ids.add(entity.id);
+    for (const [componentIndex, component] of entity.components.entries()) {
+      if (
+        component === null ||
+        typeof component !== 'object' ||
+        typeof component.name !== 'string' ||
+        component.name.length === 0 ||
+        (component.operation !== undefined &&
+          component.operation !== 'replace' &&
+          component.operation !== 'remove') ||
+        component.data === null ||
+        typeof component.data !== 'object' ||
+        Array.isArray(component.data) ||
+        (component.operation === 'remove' && Object.keys(component.data).length !== 0)
+      )
+        return `component record ${entityIndex}:${componentIndex} has invalid fields`;
+    }
+  }
+  return undefined;
+}
+
+function validatePacket(packet: ReplicationPacket): string | undefined {
+  if (packet.version !== REPLICATION_PROTOCOL_VERSION)
+    return 'packet protocol version is unsupported';
+  if (!isPacketKind(packet.kind)) return 'packet kind is unsupported';
+  if (!isSessionId(packet.sessionId)) return 'sessionId must be a positive safe integer';
+  if (!isSafeNonNegativeInteger(packet.epoch)) return 'epoch must be a non-negative safe integer';
+  if (packet.kind === 'session-open' || packet.kind === 'session-resume')
+    return packet.sequence === 0 ? undefined : 'session control sequence must be zero';
+  if (packet.kind === 'ack')
+    return isSafeNonNegativeInteger(packet.acknowledgedSequence)
+      ? undefined
+      : 'acknowledgedSequence must be a non-negative safe integer';
+  if (!isSafeNonNegativeInteger(packet.sequence) || packet.sequence === 0)
+    return 'sequence must be a positive safe integer';
+  if (packet.kind === 'baseline' && packet.sequence !== 1) return 'baseline sequence must be one';
+  if (packet.kind === 'rejection') {
+    if (!isPacketKind(packet.rejectedKind) || typeof packet.reason !== 'string')
+      return 'rejection details are invalid';
+    return undefined;
+  }
+  if (packet.kind !== 'baseline' && packet.kind !== 'delta')
+    return 'packet kind does not carry a data payload';
+  if (typeof packet.tick !== 'number' || !Number.isSafeInteger(packet.tick))
+    return 'tick must be a safe integer';
+  if (typeof packet.fingerprint !== 'string') return 'fingerprint must be a string';
+  return validateEntities(packet.entities);
+}
+
+function validateLimits(
+  packet: ReplicationDataPacket,
+  bytes: Uint8Array | undefined,
+  limits: ReplicationLimits,
+): NetError | null {
+  if (bytes !== undefined && bytes.byteLength > limits.maxMessageBytes)
+    return limitError('maxMessageBytes', bytes.byteLength, limits.maxMessageBytes);
+  if (packet.entities.length > limits.maxEntities)
+    return limitError('maxEntities', packet.entities.length, limits.maxEntities);
+  let operations = 0;
+  const visit = (value: unknown): NetError | null => {
+    if (
+      typeof value === 'string' &&
+      new TextEncoder().encode(value).byteLength > limits.maxStringBytes
+    )
+      return limitError(
+        'maxStringBytes',
+        new TextEncoder().encode(value).byteLength,
+        limits.maxStringBytes,
+      );
+    const typedArray = typedArrayName(value);
+    if (typedArray !== undefined) {
+      const contents = value as PortableTypedArray;
+      if (contents.byteLength > limits.maxBufferBytes)
+        return limitError('maxBufferBytes', contents.byteLength, limits.maxBufferBytes);
+      if (contents.length > limits.maxArrayElements)
+        return limitError('maxArrayElements', contents.length, limits.maxArrayElements);
+      return null;
+    }
+    if (Array.isArray(value)) {
+      if (value.length > limits.maxArrayElements)
+        return limitError('maxArrayElements', value.length, limits.maxArrayElements);
+      for (const item of value) {
+        const problem = visit(item);
+        if (problem) return problem;
+      }
+    }
+    if (value !== null && typeof value === 'object' && !(value instanceof Uint8Array))
+      for (const item of Object.values(value as Record<string, unknown>)) {
+        const problem = visit(item);
+        if (problem) return problem;
+      }
+    return null;
+  };
+  for (const entity of packet.entities) {
+    operations += entity.components.length;
+    for (const component of entity.components) {
+      const problem = visit(component.data);
+      if (problem) return problem;
+    }
+  }
+  return operations > limits.maxComponentOperations
+    ? limitError('maxComponentOperations', operations, limits.maxComponentOperations)
+    : null;
+}
+
+function parse(
+  bytes: Uint8Array,
+): { readonly packet: ReplicationPacket } | { readonly error: NetError } {
+  const text = new TextDecoder().decode(bytes);
+  const separator = text.indexOf('\n');
+  if (separator < 0 || text.slice(0, separator) !== REPLICATION_PROTOCOL_PREFIX)
+    return { error: invalid('packet prefix does not match protocol-v2') };
+  try {
+    const decoded: unknown = JSON.parse(text.slice(separator + 1));
+    const revived = reviveTypedArrays(decoded);
+    if ('reason' in revived) return { error: invalid(revived.reason) };
+    if (revived.value === null || typeof revived.value !== 'object')
+      return { error: invalid('packet must be an object') };
+    const packet = revived.value as ReplicationPacket;
+    const reason = validatePacket(packet);
+    if (reason !== undefined) {
+      if (typeof packet.version === 'number' && packet.version !== REPLICATION_PROTOCOL_VERSION)
+        return {
+          error: new NetError({
+            code: 'protocol-unsupported-version',
+            expected: `protocol version ${REPLICATION_PROTOCOL_VERSION}`,
+            hint: 'upgrade the peer before sending replicated bytes',
+            detail: {
+              receivedVersion: packet.version,
+              supportedVersion: REPLICATION_PROTOCOL_VERSION,
+            },
+          }),
+        };
+      return { error: invalid(reason) };
+    }
+    return { packet };
+  } catch {
+    return { error: invalid('payload is not valid JSON') };
+  }
+}
+
+function isDataPacket(packet: ReplicationPacket): packet is ReplicationDataPacket {
+  return packet.kind === 'baseline' || packet.kind === 'delta';
+}
+
+export function encodeReplicationPacket(
+  packet: ReplicationPacket,
+  limits: ReplicationLimits,
+): Result<Uint8Array, NetError> {
+  const reason = validatePacket(packet);
+  if (reason !== undefined) return err(invalid(reason));
+  const body = JSON.stringify(canonicalize(packet));
+  const bytes = new TextEncoder().encode(`${REPLICATION_PROTOCOL_PREFIX}\n${body}`);
+  const failure = isDataPacket(packet) ? validateLimits(packet, bytes, limits) : null;
+  return failure ? err(failure) : ok(bytes);
+}
+
+export function decodeReplicationPacket(
+  bytes: Uint8Array,
+  limits: ReplicationLimits,
+): Result<ReplicationPacket, NetError> {
+  if (bytes.byteLength > limits.maxMessageBytes)
+    return err(limitError('maxMessageBytes', bytes.byteLength, limits.maxMessageBytes));
+  const parsed = parse(bytes);
+  if ('error' in parsed) return err(parsed.error);
+  const failure = isDataPacket(parsed.packet) ? validateLimits(parsed.packet, bytes, limits) : null;
+  return failure ? err(failure) : ok(parsed.packet);
+}

package/src/replication/constants.ts

@@ -0,0 +1,5 @@
+/** The sole application replication protocol version published by net. */
+export const REPLICATION_PROTOCOL_VERSION = 2;
+
+/** Fixed wire prefix used to reject non-v2 replication bytes before dispatch. */
+export const REPLICATION_PROTOCOL_PREFIX = 'FXRP2';

package/src/replication/errors.ts

@@ -0,0 +1,78 @@
+export type NetErrorDetailByCode = {
+  'handshake-profile-mismatch': {
+    readonly localFingerprint: string;
+    readonly remoteFingerprint: string;
+  };
+  'decode-invalid-payload': { readonly reason: string };
+  'decode-limit-exceeded': {
+    readonly limit: string;
+    readonly actual: number;
+    readonly maximum: number;
+  };
+  'ordering-invalid-tick': { readonly receivedTick: number; readonly lastTick: number };
+  'identity-invalid': { readonly id: number; readonly reason: string };
+  'schema-invalid': { readonly component: string; readonly reason: string };
+  'remap-unresolved-reference': { readonly id: number; readonly referencedId: number };
+  'apply-invariant-failed': { readonly reason: string };
+  'protocol-unsupported-version': {
+    readonly receivedVersion: number;
+    readonly supportedVersion: number;
+  };
+  'session-illegal-transition': {
+    readonly from: string;
+    readonly to: string;
+  };
+  'recovery-policy-invalid': {
+    readonly field: string;
+    readonly reason: string;
+  };
+  'recovery-rejected': { readonly reason: string };
+  'recovery-exhausted': {
+    readonly attempts: number;
+    readonly maxAttempts: number;
+  };
+};
+
+export type NetErrorCode = keyof NetErrorDetailByCode;
+export type NetErrorDetailFor<C extends NetErrorCode> = NetErrorDetailByCode[C];
+export type NetErrorDetail = NetErrorDetailFor<NetErrorCode>;
+
+class NetErrorClass extends Error {
+  readonly code: NetErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: NetErrorDetail;
+  constructor(args: {
+    code: NetErrorCode;
+    expected: string;
+    hint: string;
+    detail: NetErrorDetail;
+  }) {
+    super(`[NetError ${args.code}] expected: ${args.expected}; hint: ${args.hint}`);
+    this.name = 'NetError';
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+}
+
+type Variant<C extends NetErrorCode> = NetErrorClass & {
+  readonly code: C;
+  readonly detail: NetErrorDetailFor<C>;
+};
+
+export type NetError = {
+  [C in NetErrorCode]: Variant<C>;
+}[NetErrorCode];
+
+interface NetErrorConstructor {
+  new <C extends NetErrorCode>(args: {
+    code: C;
+    expected: string;
+    hint: string;
+    detail: NetErrorDetailFor<C>;
+  }): Variant<C>;
+  readonly prototype: NetErrorClass;
+}
+export const NetError: NetErrorConstructor = NetErrorClass as unknown as NetErrorConstructor;

package/src/replication/handshake.ts

@@ -0,0 +1,18 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { NetError } from './errors';
+import type { ReplicationProfile } from './profile';
+export function validateHandshake(
+  local: ReplicationProfile,
+  remote: ReplicationProfile,
+): Result<void, NetError> {
+  if (local.fingerprint !== remote.fingerprint)
+    return err(
+      new NetError({
+        code: 'handshake-profile-mismatch',
+        expected: 'matching protocol, profile, and declared limits',
+        hint: 'use identical ordered replication components and limits on both peers',
+        detail: { localFingerprint: local.fingerprint, remoteFingerprint: remote.fingerprint },
+      }),
+    );
+  return ok(undefined);
+}

package/src/replication/profile.ts

@@ -0,0 +1,111 @@
+import type { Component } from '@forgeax/engine-ecs';
+import { validateProfileComponents } from '@forgeax/engine-ecs/externalization';
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { err, ok, type Result } from '@forgeax/engine-types';
+export interface ReplicationLimits {
+  readonly maxMessageBytes: number;
+  readonly maxEntities: number;
+  readonly maxComponentOperations: number;
+  readonly maxStringBytes: number;
+  readonly maxBufferBytes: number;
+  readonly maxArrayElements: number;
+}
+export const DEFAULT_REPLICATION_LIMITS: ReplicationLimits = {
+  maxMessageBytes: 64 * 1024,
+  maxEntities: 1024,
+  maxComponentOperations: 4096,
+  maxStringBytes: 4096,
+  maxBufferBytes: 16 * 1024,
+  maxArrayElements: 1024,
+};
+
+import { NetError } from './errors';
+
+export interface ReplicationProfile {
+  readonly name: string;
+  readonly entities: ReplicationEntityFilter;
+  readonly components: readonly Component[];
+  readonly limits: ReplicationLimits;
+  readonly fingerprint: string;
+}
+export interface ReplicationEntityFilter {
+  readonly with: readonly Component[];
+  readonly without?: readonly Component[];
+}
+export interface DefineReplicationOptions {
+  readonly name: string;
+  readonly entities: ReplicationEntityFilter;
+  readonly components: readonly Component[];
+  readonly limits?: Partial<ReplicationLimits>;
+}
+function hash(text: string): string {
+  let value = 2166136261;
+  for (const char of text) {
+    value ^= char.charCodeAt(0);
+    value = Math.imul(value, 16777619);
+  }
+  return (value >>> 0).toString(16).padStart(8, '0');
+}
+
+function immutableProfile(
+  options: DefineReplicationOptions,
+  limits: ReplicationLimits,
+  fingerprint: string,
+): ReplicationProfile {
+  const entities: ReplicationEntityFilter = Object.freeze({
+    with: Object.freeze([...options.entities.with]),
+    ...(options.entities.without === undefined
+      ? {}
+      : { without: Object.freeze([...options.entities.without]) }),
+  });
+  return Object.freeze({
+    name: options.name,
+    entities,
+    components: Object.freeze([...options.components]),
+    limits: Object.freeze({ ...limits }),
+    fingerprint,
+  });
+}
+
+export function defineReplication(
+  options: DefineReplicationOptions,
+): Result<ReplicationProfile, NetError> {
+  const portable = validateProfileComponents(options.components);
+  if (!portable.valid) {
+    const first = portable.errors[0];
+    if (first === undefined) {
+      return err(
+        new NetError({
+          code: 'schema-invalid',
+          expected: 'portable replication components',
+          hint: 'select only components accepted by the ECS externalization kernel',
+          detail: { component: '', reason: 'portable validation failed without a diagnostic' },
+        }),
+      );
+    }
+    return err(
+      new NetError({
+        code: 'schema-invalid',
+        expected: first.expected,
+        hint: first.hint,
+        detail: { component: first.component, reason: first.code },
+      }),
+    );
+  }
+  const limits: ReplicationLimits = { ...DEFAULT_REPLICATION_LIMITS, ...options.limits };
+  const signature = JSON.stringify({
+    name: options.name,
+    query: {
+      with: options.entities.with.map((component) => component.name),
+      ...(options.entities.without === undefined
+        ? {}
+        : { without: options.entities.without.map((component) => component.name) }),
+    },
+    components: options.components.map((component) => ({
+      name: component.name,
+      schema: componentSchema(component),
+    })),
+    limits,
+  });
+  return ok(immutableProfile(options, limits, hash(signature)));
+}

package/src/replication/protocol.ts

@@ -0,0 +1,86 @@
+import type { SessionId } from '../session/recovery';
+
+/** Replicated ECS entity operations owned by the protocol manifest. */
+export type ReplicationEntityKind = 'upsert' | 'despawn';
+
+export interface ReplicationComponentRecord {
+  readonly name: string;
+  readonly operation?: 'replace' | 'remove';
+  readonly data: Record<string, unknown>;
+}
+
+export interface ReplicationEntityRecord {
+  readonly id: number;
+  readonly kind: ReplicationEntityKind;
+  readonly components: readonly ReplicationComponentRecord[];
+}
+
+export type ReplicationPacketKind =
+  | 'session-open'
+  | 'session-resume'
+  | 'baseline'
+  | 'delta'
+  | 'ack'
+  | 'rejection';
+
+/** Control packet that opens or resumes one application session. */
+export interface ReplicationSessionPacket {
+  readonly version: 2;
+  readonly kind: 'session-open' | 'session-resume';
+  readonly sessionId: SessionId;
+  readonly epoch: number;
+  readonly sequence: 0;
+}
+
+/** Shared fields for baseline and delta data packets. */
+export interface ReplicationDataPacketBase {
+  readonly version: 2;
+  readonly kind: 'baseline' | 'delta';
+  readonly sessionId: SessionId;
+  readonly epoch: number;
+  readonly sequence: number;
+  readonly tick: number;
+  readonly fingerprint: string;
+  readonly entities: readonly ReplicationEntityRecord[];
+}
+
+/** Complete authoritative baseline; sequence one is required for every epoch. */
+export interface ReplicationBaselinePacket extends ReplicationDataPacketBase {
+  readonly kind: 'baseline';
+  readonly sequence: 1;
+}
+
+/** Ordered authoritative delta after the accepted baseline. */
+export interface ReplicationDeltaPacket extends ReplicationDataPacketBase {
+  readonly kind: 'delta';
+  readonly sequence: number;
+}
+
+export type ReplicationDataPacket = ReplicationBaselinePacket | ReplicationDeltaPacket;
+
+export interface ReplicationAckPacket {
+  readonly version: 2;
+  readonly kind: 'ack';
+  readonly sessionId: SessionId;
+  readonly epoch: number;
+  readonly acknowledgedSequence: number;
+}
+
+export interface ReplicationRejectionPacket {
+  readonly version: 2;
+  readonly kind: 'rejection';
+  readonly sessionId: SessionId;
+  readonly epoch: number;
+  readonly sequence: number;
+  readonly rejectedKind: ReplicationPacketKind;
+  readonly reason: string;
+}
+
+export type ReplicationPacket =
+  | ReplicationSessionPacket
+  | ReplicationBaselinePacket
+  | ReplicationDeltaPacket
+  | ReplicationAckPacket
+  | ReplicationRejectionPacket;
+
+export type ReplicationDataPacketKind = ReplicationDataPacket['kind'];