@forgeax/engine-net 0.1.2

package/src/endpoint/errors.ts

@@ -0,0 +1,164 @@
+// @forgeax/engine-net -- endpoint structured errors.
+//
+// Closed union of transport-level failures. Each variant carries .code, .expected,
+// .hint, and per-code .detail. AI users exhaustively switch on .code without a
+// default branch (requirements AC-13).
+
+import type { PeerId } from './endpoint';
+
+// ---------------------------------------------------------------------------
+// EndpointErrorCode -- closed 5-member union derived from endpointErrorPolicy
+// ---------------------------------------------------------------------------
+
+/** Transport-level endpoint error codes (requirements AC-02, AC-13). */
+export type EndpointErrorCode = keyof typeof endpointErrorPolicy;
+
+// ---------------------------------------------------------------------------
+// Per-code detail payloads
+// ---------------------------------------------------------------------------
+
+export interface EndpointDetailPeerNotFound {
+  readonly peerId: PeerId;
+}
+
+export interface EndpointDetailConnectionClosed {
+  readonly peerId: PeerId;
+}
+
+export interface EndpointDetailSendFailed {
+  readonly peerId: PeerId;
+  readonly cause: string;
+}
+
+export interface EndpointDetailAlreadyClosed {
+  readonly cause: string;
+}
+
+export interface EndpointDetailConnectionFailed {
+  readonly address: string;
+  readonly cause: string;
+}
+
+// ---------------------------------------------------------------------------
+// Conditional resolver
+// ---------------------------------------------------------------------------
+
+export type EndpointErrorDetailFor<C extends EndpointErrorCode> = C extends 'peer-not-found'
+  ? EndpointDetailPeerNotFound
+  : C extends 'connection-closed'
+    ? EndpointDetailConnectionClosed
+    : C extends 'send-failed'
+      ? EndpointDetailSendFailed
+      : C extends 'already-closed'
+        ? EndpointDetailAlreadyClosed
+        : C extends 'connection-failed'
+          ? EndpointDetailConnectionFailed
+          : never;
+
+/** Tagged union of all endpoint error detail variants. */
+export type EndpointErrorDetail = EndpointErrorDetailFor<EndpointErrorCode>;
+
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+
+class EndpointErrorClass extends Error {
+  readonly code: EndpointErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: EndpointErrorDetail;
+
+  constructor(args: {
+    code: EndpointErrorCode;
+    expected: string;
+    hint: string;
+    detail: EndpointErrorDetail;
+  }) {
+    let suffix = '';
+    if (args.code === 'peer-not-found') {
+      const d = args.detail as EndpointDetailPeerNotFound;
+      suffix = ` (peerId=${d.peerId})`;
+    } else if (args.code === 'connection-closed') {
+      const d = args.detail as EndpointDetailConnectionClosed;
+      suffix = ` (peerId=${d.peerId})`;
+    } else if (args.code === 'send-failed') {
+      const d = args.detail as EndpointDetailSendFailed;
+      suffix = ` (peerId=${d.peerId}, cause=${d.cause})`;
+    } else if (args.code === 'already-closed') {
+      const d = args.detail as EndpointDetailAlreadyClosed;
+      suffix = ` (cause=${d.cause})`;
+    } else if (args.code === 'connection-failed') {
+      const d = args.detail as EndpointDetailConnectionFailed;
+      suffix = ` (address=${d.address}, cause=${d.cause})`;
+    }
+    super(`[EndpointError ${args.code}] expected: ${args.expected}; hint: ${args.hint}${suffix}`);
+    this.name = 'EndpointError';
+    this.code = args.code;
+    this.expected = args.expected;
+    this.hint = args.hint;
+    this.detail = args.detail;
+  }
+}
+
+type EndpointErrorVariant<C extends EndpointErrorCode> = EndpointErrorClass & {
+  readonly code: C;
+  readonly detail: EndpointErrorDetailFor<C>;
+};
+
+export type EndpointError = {
+  [C in EndpointErrorCode]: EndpointErrorVariant<C>;
+}[EndpointErrorCode];
+
+interface EndpointErrorConstructor {
+  new <C extends EndpointErrorCode>(args: {
+    code: C;
+    expected: string;
+    hint: string;
+    detail: EndpointErrorDetailFor<C>;
+  }): EndpointErrorVariant<C>;
+  readonly prototype: EndpointErrorClass;
+}
+
+export const EndpointError: EndpointErrorConstructor =
+  EndpointErrorClass as unknown as EndpointErrorConstructor;
+
+type EndpointErrorPolicy = { readonly expected: string; readonly hint: string };
+
+const endpointErrorPolicy = {
+  'peer-not-found': {
+    expected: 'the target peer must exist in the current connection set',
+    hint: 'verify the PeerId is from a connect event; check that the peer has not disconnected',
+  },
+  'connection-closed': {
+    expected: 'the peer connection must be alive for the operation',
+    hint: 'the peer disconnected; poll for a disconnect event and handle the lifecycle',
+  },
+  'send-failed': {
+    expected: 'message bytes must be delivered to the target peer or the connection must fail',
+    hint: 'the memory connection is broken; the peer may have disconnected or the buffer is full',
+  },
+  'already-closed': {
+    expected: 'the endpoint must be open for any operation',
+    hint: 'the endpoint is closed; create a new endpoint pair for further communication',
+  },
+  'connection-failed': {
+    expected:
+      'the endpoint factory must successfully establish a connection or bind to the listen address',
+    hint: 'the initial connection or bind failed; verify the address is reachable and the port is not in use, then retry',
+  },
+} satisfies Record<string, EndpointErrorPolicy>;
+
+/** Expected-invariant table per error code. */
+export const ENDPOINT_EXPECTED: Readonly<Record<EndpointErrorCode, string>> = Object.fromEntries(
+  Object.entries(endpointErrorPolicy).map(([code, policy]) => [code, policy.expected]),
+) as Readonly<Record<EndpointErrorCode, string>>;
+
+/** Actionable hint table per error code. */
+export const ENDPOINT_ERROR_HINTS: Readonly<Record<EndpointErrorCode, string>> = Object.fromEntries(
+  Object.entries(endpointErrorPolicy).map(([code, policy]) => [code, policy.hint]),
+) as Readonly<Record<EndpointErrorCode, string>>;
+
+/** Type guard for narrowing unknown to EndpointError. */
+export function isEndpointError(err: unknown): err is EndpointError {
+  return err instanceof EndpointErrorClass;
+}

package/src/endpoint/memory.ts

@@ -0,0 +1,172 @@
+// @forgeax/engine-net -- memory endpoint implementation.
+// Deterministic memory backend for the NetEndpoint contract.
+// (requirements AC-03, plan-strategy D-3)
+
+import type { Result } from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+import type { EndpointEvent, NetEndpoint, PeerId } from './endpoint';
+import type { EndpointError as EndpointErrorType } from './errors';
+import { ENDPOINT_ERROR_HINTS, ENDPOINT_EXPECTED, EndpointError } from './errors';
+
+interface InternalState {
+  delayNext: boolean;
+  duplicateNext: boolean;
+  malformNext: boolean;
+}
+
+class MemoryEndpoint implements NetEndpoint {
+  readonly _peerId: PeerId;
+  _remote: MemoryEndpoint | null = null;
+  _closed = false;
+  _remoteConnected = false;
+  _incoming: EndpointEvent[] = [];
+  _delayed: EndpointEvent[] = [];
+  _state: InternalState = { delayNext: false, duplicateNext: false, malformNext: false };
+
+  constructor(peerId: PeerId) {
+    this._peerId = peerId;
+  }
+
+  poll(): EndpointEvent[] {
+    if (this._closed) return [];
+    const events = this._incoming.splice(0);
+    this._incoming = this._delayed.splice(0);
+    return events;
+  }
+
+  send(peerId: PeerId, data: Uint8Array): Result<void, EndpointErrorType> {
+    if (this._closed) {
+      return err(
+        new EndpointError({
+          code: 'already-closed',
+          expected: ENDPOINT_EXPECTED['already-closed'],
+          hint: ENDPOINT_ERROR_HINTS['already-closed'],
+          detail: { cause: 'endpoint is closed' },
+        }),
+      );
+    }
+    if (!this._remote || this._remote._peerId !== peerId) {
+      return err(
+        new EndpointError({
+          code: 'peer-not-found',
+          expected: ENDPOINT_EXPECTED['peer-not-found'],
+          hint: ENDPOINT_ERROR_HINTS['peer-not-found'],
+          detail: { peerId },
+        }),
+      );
+    }
+    if (!this._remoteConnected) {
+      return err(
+        new EndpointError({
+          code: 'connection-closed',
+          expected: ENDPOINT_EXPECTED['connection-closed'],
+          hint: ENDPOINT_ERROR_HINTS['connection-closed'],
+          detail: { peerId },
+        }),
+      );
+    }
+
+    const deliver = (bytes: Uint8Array) => {
+      if (this._state.delayNext) {
+        this._remote?._delayed.push({ kind: 'message', peerId: this._peerId, data: bytes });
+        this._state.delayNext = false;
+      } else {
+        this._remote?._incoming.push({ kind: 'message', peerId: this._peerId, data: bytes });
+      }
+    };
+
+    if (this._state.malformNext) {
+      const corrupted = new Uint8Array(data);
+      if (corrupted.length > 0) {
+        const firstByte = corrupted[0];
+        if (firstByte !== undefined) corrupted[0] = firstByte ^ 0xff;
+      }
+      deliver(corrupted);
+      this._state.malformNext = false;
+    } else {
+      deliver(data);
+      if (this._state.duplicateNext) {
+        this._state.duplicateNext = false;
+        if (this._state.delayNext) {
+          this._remote?._delayed.push({ kind: 'message', peerId: this._peerId, data });
+          this._state.delayNext = false;
+        } else {
+          this._remote?._incoming.push({ kind: 'message', peerId: this._peerId, data });
+        }
+      }
+    }
+
+    return ok(undefined);
+  }
+
+  close(): Result<void, EndpointErrorType> {
+    if (this._closed) {
+      return err(
+        new EndpointError({
+          code: 'already-closed',
+          expected: ENDPOINT_EXPECTED['already-closed'],
+          hint: ENDPOINT_ERROR_HINTS['already-closed'],
+          detail: { cause: 'endpoint is already closed' },
+        }),
+      );
+    }
+    this._closed = true;
+    this._remoteConnected = false;
+    if (this._remote && !this._remote._closed) {
+      this._remote._remoteConnected = false;
+      this._remote._incoming.push({ kind: 'peer-disconnected', peerId: this._peerId });
+    }
+    return ok(undefined);
+  }
+
+  _forceDisconnect(): void {
+    if (this._remote && !this._remote._closed) {
+      this._remote._remoteConnected = false;
+      this._remote._incoming.push({ kind: 'peer-disconnected', peerId: this._peerId });
+    }
+    this._remoteConnected = false;
+  }
+}
+
+export function createMemoryEndpointPair(): [NetEndpoint, NetEndpoint] {
+  const epA = new MemoryEndpoint(1 as PeerId);
+  const epB = new MemoryEndpoint(2 as PeerId);
+  epA._remote = epB;
+  epB._remote = epA;
+  epA._remoteConnected = true;
+  epB._remoteConnected = true;
+  epA._incoming.push({ kind: 'peer-connected', peerId: 2 as PeerId });
+  epB._incoming.push({ kind: 'peer-connected', peerId: 1 as PeerId });
+  return [epA, epB];
+}
+
+export interface MemoryFaultController {
+  delayNextDelivery(ms: number): void;
+  duplicateNextDelivery(): void;
+  malformNextDelivery(): void;
+  disconnectPeer(endpoint: NetEndpoint): void;
+}
+
+export function createMemoryEndpointPairWithController(): {
+  readonly endpoints: [NetEndpoint, NetEndpoint];
+  readonly controller: MemoryFaultController;
+} {
+  const [epA, epB] = createMemoryEndpointPair();
+
+  const controller: MemoryFaultController = {
+    delayNextDelivery(_ms: number): void {
+      (epA as MemoryEndpoint)._state.delayNext = true;
+    },
+    duplicateNextDelivery(): void {
+      (epA as MemoryEndpoint)._state.duplicateNext = true;
+    },
+    malformNextDelivery(): void {
+      (epA as MemoryEndpoint)._state.malformNext = true;
+    },
+    disconnectPeer(endpoint: NetEndpoint): void {
+      (endpoint as MemoryEndpoint)._forceDisconnect();
+    },
+  };
+
+  return { endpoints: [epA, epB], controller };
+}

package/src/index.ts

@@ -0,0 +1,46 @@
+// @forgeax/engine-net -- memory transport, replication session, and profile-driven ECS sync.
+//
+// Depends on @forgeax/engine-ecs (World, schedule), @forgeax/engine-plugin (Plugin),
+// and @forgeax/engine-types (Result, errors). No WebSocket, browser, app, or runtime dependency.
+
+// Endpoint contract (requirements AC-02, AC-13)
+export type { EndpointEvent, NetEndpoint, PeerId } from './endpoint/endpoint';
+export type { EndpointErrorCode, EndpointErrorDetail } from './endpoint/errors';
+export {
+  ENDPOINT_ERROR_HINTS,
+  ENDPOINT_EXPECTED,
+  EndpointError,
+  isEndpointError,
+} from './endpoint/errors';
+export type { MemoryFaultController } from './endpoint/memory';
+// Memory endpoint (requirements AC-03)
+export {
+  createMemoryEndpointPair,
+  createMemoryEndpointPairWithController,
+} from './endpoint/memory';
+export { AuthorityCoordinator, createAuthorityCoordinator } from './replication/authority';
+export type {
+  NetEntityId,
+  ReplicationBatch,
+  ReplicationComponentRecord,
+  ReplicationEntityRecord,
+} from './replication/codec';
+export { NetError, type NetErrorCode, type NetErrorDetail } from './replication/errors';
+export { validateHandshake } from './replication/handshake';
+export type {
+  DefineReplicationOptions,
+  ReplicationLimits,
+  ReplicationProfile,
+} from './replication/profile';
+export { defineReplication } from './replication/profile';
+export {
+  applyReplicaBatch,
+  createReplicaCoordinator,
+  decodeAndApplyReplicaBatch,
+  ReplicaCoordinator,
+} from './replication/replica';
+export type { NetSessionConfig, PeerSnapshot, RawMessage } from './session/net-session';
+// Session (requirements AC-04)
+export { NetSession } from './session/net-session';
+export type { NetPluginConfig } from './session/session-plugin';
+export { netPlugin } from './session/session-plugin';

package/src/replication/authority.ts

@@ -0,0 +1,145 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { projectComponentData } from '@forgeax/engine-ecs/externalization';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import {
+  encodeReplicationBatch,
+  type ReplicationBatch,
+  type ReplicationComponentRecord,
+  type ReplicationEntityRecord,
+} from './codec';
+import { REPLICATION_PROTOCOL_VERSION } from './constants';
+import type { NetError } from './errors';
+import { DEFAULT_REPLICATION_LIMITS, type ReplicationProfile } from './profile';
+
+export interface PublishedBatch extends ReplicationBatch {
+  readonly bytes: Uint8Array;
+}
+interface KnownEntity {
+  readonly id: number;
+  readonly components: Map<string, string>;
+}
+function stable(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+export class AuthorityCoordinator {
+  readonly #world: World;
+  readonly #profile: ReplicationProfile;
+  readonly #ids = new Map<EntityHandle, number>();
+  readonly #known = new Map<EntityHandle, KnownEntity>();
+  #nextId = 1;
+  #tick = 0;
+  constructor(world: World, profile: ReplicationProfile) {
+    this.#world = world;
+    this.#profile = profile;
+  }
+  idFor(entity: EntityHandle): number {
+    return this.#ids.get(entity) ?? 0;
+  }
+  publish(): Result<PublishedBatch, NetError> {
+    return this.#publish(false);
+  }
+  publishFull(): Result<PublishedBatch, NetError> {
+    return this.#publish(true);
+  }
+  #publish(forceFull: boolean): Result<PublishedBatch, NetError> {
+    const candidateIds = new Map(this.#ids);
+    let candidateNextId = this.#nextId;
+    const current = new Map<
+      EntityHandle,
+      { id: number; components: ReplicationComponentRecord[] }
+    >();
+    const query = this.#world.query(this.#profile.entities).unwrap();
+    // Allocate every visible entity id before projecting any component data.
+    // Query iteration visits storage groups independently, so projecting while
+    // discovering ids can encode references to a later chunk as zero.
+    for (const row of query) {
+      if (!candidateIds.has(row.entity)) candidateIds.set(row.entity, candidateNextId++);
+    }
+    for (const row of query) {
+      const entity = row.entity;
+      const components: ReplicationComponentRecord[] = [];
+      for (const component of this.#profile.components) {
+        const raw = this.#world.get(entity, component);
+        if (raw.ok) {
+          components.push({
+            name: component.name,
+            data: projectComponentData(
+              component,
+              raw.value as Record<string, unknown>,
+              (reference) => candidateIds.get(reference as EntityHandle) ?? 0,
+            ),
+          });
+        }
+      }
+      const id = candidateIds.get(entity);
+      if (id !== undefined) current.set(entity, { id, components });
+    }
+
+    const full = forceFull || this.#tick === 0;
+    const entities: ReplicationEntityRecord[] = [];
+    for (const [entity, entry] of current) {
+      const prior = this.#known.get(entity);
+      const components =
+        full || prior === undefined
+          ? entry.components
+          : [
+              ...entry.components.filter(
+                (component) => prior.components.get(component.name) !== stable(component.data),
+              ),
+              ...[...prior.components.keys()]
+                .filter((name) => !entry.components.some((component) => component.name === name))
+                .map((name) => ({ name, operation: 'remove' as const, data: {} })),
+            ];
+      if (full || prior === undefined || components.length > 0)
+        entities.push({ id: entry.id, kind: 'upsert', components });
+    }
+    // A full baseline is consumed by a fresh replica, so it must describe
+    // only live entities. Despawn records refer to the previous authority
+    // baseline and would be unknown identities on a late-joining replica.
+    if (!full)
+      for (const [entity, prior] of this.#known) {
+        if (!current.has(entity)) entities.push({ id: prior.id, kind: 'despawn', components: [] });
+      }
+
+    const candidateKnown = new Map<EntityHandle, KnownEntity>();
+    for (const [entity, entry] of current) {
+      candidateKnown.set(entity, {
+        id: entry.id,
+        components: new Map(
+          entry.components.map((component) => [component.name, stable(component.data)]),
+        ),
+      });
+    }
+    for (const [entity] of candidateIds) {
+      if (!current.has(entity)) candidateIds.delete(entity);
+    }
+
+    const batch: ReplicationBatch = {
+      version: REPLICATION_PROTOCOL_VERSION,
+      fingerprint: this.#profile.fingerprint,
+      tick: this.#tick + 1,
+      full,
+      entities,
+    };
+    const encoded = encodeReplicationBatch(
+      batch,
+      this.#profile.limits ?? DEFAULT_REPLICATION_LIMITS,
+    );
+    if (!encoded.ok) return err(encoded.error);
+
+    this.#ids.clear();
+    for (const [entity, id] of candidateIds) this.#ids.set(entity, id);
+    this.#known.clear();
+    for (const [entity, known] of candidateKnown) this.#known.set(entity, known);
+    this.#nextId = candidateNextId;
+    this.#tick = batch.tick;
+    return ok({ ...batch, bytes: encoded.value });
+  }
+}
+export function createAuthorityCoordinator(
+  world: World,
+  profile: ReplicationProfile,
+): AuthorityCoordinator {
+  return new AuthorityCoordinator(world, profile);
+}