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

package/src/endpoint/memory.ts

@@ -0,0 +1,194 @@
+// @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, NetEndpointConnector, 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 };
+}
+
+/** Create a replaceable, realm-neutral connector over a deterministic endpoint factory. */
+export function createMemoryEndpointConnector(
+  createEndpoint: () => NetEndpoint,
+): NetEndpointConnector {
+  return {
+    connect(signal) {
+      if (signal.aborted)
+        return Promise.resolve(
+          err(
+            new EndpointError({
+              code: 'connection-failed',
+              expected: ENDPOINT_EXPECTED['connection-failed'],
+              hint: ENDPOINT_ERROR_HINTS['connection-failed'],
+              detail: { address: 'memory', cause: 'connect aborted' },
+            }),
+          ),
+        );
+      return Promise.resolve(ok(createEndpoint()));
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+// @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, NetEndpointConnector, 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 {
+  createMemoryEndpointConnector,
+  createMemoryEndpointPair,
+  createMemoryEndpointPairWithController,
+} from './endpoint/memory';
+export { AuthorityCoordinator, createAuthorityCoordinator } from './replication/authority';
+export { decodeReplicationPacket, encodeReplicationPacket } from './replication/codec';
+export {
+  REPLICATION_PROTOCOL_PREFIX,
+  REPLICATION_PROTOCOL_VERSION,
+} from './replication/constants';
+export {
+  NetError,
+  type NetErrorCode,
+  type NetErrorDetail,
+  type NetErrorDetailByCode,
+  type NetErrorDetailFor,
+} from './replication/errors';
+export { validateHandshake } from './replication/handshake';
+export type {
+  DefineReplicationOptions,
+  ReplicationLimits,
+  ReplicationProfile,
+} from './replication/profile';
+export { DEFAULT_REPLICATION_LIMITS, defineReplication } from './replication/profile';
+export type {
+  ReplicationAckPacket,
+  ReplicationBaselinePacket,
+  ReplicationComponentRecord,
+  ReplicationDataPacket,
+  ReplicationDataPacketBase,
+  ReplicationDataPacketKind,
+  ReplicationDeltaPacket,
+  ReplicationEntityKind,
+  ReplicationEntityRecord,
+  ReplicationPacket,
+  ReplicationPacketKind,
+  ReplicationRejectionPacket,
+  ReplicationSessionPacket,
+} from './replication/protocol';
+export {
+  applyReplicationPacket,
+  createReplicaCoordinator,
+  decodeAndApplyReplicationPacket,
+  ReplicaCoordinator,
+} from './replication/replica';
+export type {
+  NetSessionConfig,
+  PeerSnapshot,
+  RawMessage,
+  SessionSnapshot,
+} from './session/net-session';
+// Session (requirements AC-04)
+export { NetSession } from './session/net-session';
+export type {
+  NetRecoveryOutcome,
+  NetRecoveryPolicy,
+  NetRecoverySnapshot,
+  NetSessionFailure,
+  NetSessionState,
+  NetSessionStateKind,
+  SessionId,
+} from './session/recovery';
+export {
+  createSessionId,
+  DEFAULT_NET_RECOVERY_POLICY,
+  isLegalNetSessionTransition,
+  RECOVERY_ERROR_CODES,
+  resolveNetRecoveryPolicy,
+  transitionNetSessionState,
+  validateNetRecoveryPolicy,
+} from './session/recovery';
+export type { NetPluginConfig } from './session/session-plugin';
+export { netPlugin } from './session/session-plugin';

package/src/replication/authority.ts

@@ -0,0 +1,177 @@
+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 type { SessionId } from '../session/recovery';
+import { encodeReplicationPacket } from './codec';
+import { REPLICATION_PROTOCOL_VERSION } from './constants';
+import type { NetError } from './errors';
+import { DEFAULT_REPLICATION_LIMITS, type ReplicationProfile } from './profile';
+import type {
+  ReplicationComponentRecord,
+  ReplicationDataPacket,
+  ReplicationEntityRecord,
+} from './protocol';
+
+export type PublishedPacket = ReplicationDataPacket & {
+  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;
+  #epoch = 0;
+  #sequence = 0;
+  readonly #sessionId: SessionId;
+  constructor(world: World, profile: ReplicationProfile, sessionId: SessionId = 1 as SessionId) {
+    this.#world = world;
+    this.#profile = profile;
+    this.#sessionId = sessionId;
+  }
+  idFor(entity: EntityHandle): number {
+    return this.#ids.get(entity) ?? 0;
+  }
+  publish(): Result<PublishedPacket, NetError> {
+    return this.#publish(false);
+  }
+  publishFull(): Result<PublishedPacket, NetError> {
+    return this.#publish(true);
+  }
+  nextPublicationEpoch(forceFull = false): number {
+    return forceFull && this.#tick > 0 ? this.#epoch + 1 : this.#epoch;
+  }
+  #publish(forceFull: boolean): Result<PublishedPacket, 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;
+    let nextEpoch = this.#epoch;
+    let nextSequence = this.#sequence;
+    if (forceFull && this.#tick > 0) {
+      nextEpoch += 1;
+      nextSequence = 0;
+    }
+    if (full && nextSequence === 0) nextSequence = 1;
+    else nextSequence += 1;
+    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 packet: ReplicationDataPacket = full
+      ? {
+          version: REPLICATION_PROTOCOL_VERSION,
+          kind: 'baseline',
+          sessionId: this.#sessionId,
+          epoch: nextEpoch,
+          sequence: nextSequence as 1,
+          fingerprint: this.#profile.fingerprint,
+          tick: this.#tick + 1,
+          entities,
+        }
+      : {
+          version: REPLICATION_PROTOCOL_VERSION,
+          kind: 'delta',
+          sessionId: this.#sessionId,
+          epoch: nextEpoch,
+          sequence: nextSequence,
+          fingerprint: this.#profile.fingerprint,
+          tick: this.#tick + 1,
+          entities,
+        };
+    const encoded = encodeReplicationPacket(
+      packet,
+      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 = packet.tick;
+    this.#epoch = nextEpoch;
+    this.#sequence = nextSequence;
+    return ok({ ...packet, bytes: encoded.value });
+  }
+}
+export function createAuthorityCoordinator(
+  world: World,
+  profile: ReplicationProfile,
+): AuthorityCoordinator {
+  return new AuthorityCoordinator(world, profile);
+}