@forgeax/engine-net 0.1.2

package/src/session/net-session.ts

@@ -0,0 +1,118 @@
+// @forgeax/engine-net -- NetSession host-neutral World integration.
+// (requirements AC-04, plan-strategy D-1/D-3)
+
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { NetEndpoint, PeerId } from '../endpoint/endpoint';
+import type { EndpointError } from '../endpoint/errors';
+import type { AuthorityCoordinator } from '../replication/authority';
+import type { NetError } from '../replication/errors';
+import type { ReplicationLimits } from '../replication/profile';
+import { decodeAndApplyReplicaBatch, type ReplicaCoordinator } from '../replication/replica';
+
+export interface PeerSnapshot {
+  readonly peerIds: ReadonlyArray<PeerId>;
+  readonly connected: boolean;
+}
+
+export interface NetSessionConfig {
+  readonly endpoint: NetEndpoint;
+  readonly maxRawMessages: number;
+}
+
+export interface RawMessage {
+  readonly peerId: PeerId;
+  readonly data: Uint8Array;
+}
+
+export class NetSession {
+  readonly #endpoint: NetEndpoint;
+  readonly #peerIds = new Set<PeerId>();
+  #rawMessages: RawMessage[] = [];
+  readonly #maxRawMessages: number;
+  #authority: AuthorityCoordinator | undefined;
+  readonly #pendingFullPeers = new Set<PeerId>();
+  #replica:
+    | { readonly coordinator: ReplicaCoordinator; readonly limits: ReplicationLimits }
+    | undefined;
+
+  constructor(config: NetSessionConfig) {
+    this.#endpoint = config.endpoint;
+    this.#maxRawMessages = config.maxRawMessages;
+  }
+
+  receiveEvents(): readonly NetError[] {
+    const errors: NetError[] = [];
+    for (const event of this.#endpoint.poll()) {
+      if (event.kind === 'peer-connected') {
+        this.#peerIds.add(event.peerId);
+        // Transport admission must not imply application admission, but every
+        // newly connected replica still needs the generic replication baseline.
+        this.#pendingFullPeers.add(event.peerId);
+      } else if (event.kind === 'peer-disconnected') {
+        this.#peerIds.delete(event.peerId);
+        this.#pendingFullPeers.delete(event.peerId);
+        this.#replica?.coordinator.clear();
+      } else {
+        if (this.#replica !== undefined) {
+          const result = decodeAndApplyReplicaBatch(
+            this.#replica.coordinator,
+            event.data,
+            this.#replica.limits,
+          );
+          if (!result.ok) errors.push(result.error);
+        } else if (this.#rawMessages.length < this.#maxRawMessages) {
+          this.#rawMessages.push({ peerId: event.peerId, data: event.data });
+        }
+      }
+    }
+    return errors;
+  }
+
+  drainRawMessages(): RawMessage[] {
+    return this.#rawMessages.splice(0);
+  }
+
+  getPeerSnapshot(): PeerSnapshot {
+    const peerIds = [...this.#peerIds].sort((left, right) => left - right);
+    return { peerIds, connected: peerIds.length > 0 };
+  }
+
+  sendRaw(peerId: PeerId, data: Uint8Array): Result<void, EndpointError> {
+    const result = this.#endpoint.send(peerId, data);
+    return result.ok ? ok(undefined) : err(result.error);
+  }
+
+  attachAuthority(authority: AuthorityCoordinator): void {
+    this.#authority = authority;
+  }
+
+  requestFullBaseline(peerId: PeerId): void {
+    if (this.#peerIds.has(peerId)) this.#pendingFullPeers.add(peerId);
+  }
+
+  attachReplica(coordinator: ReplicaCoordinator, limits: ReplicationLimits): void {
+    this.#replica = { coordinator, limits };
+  }
+
+  publish(): Result<void, NetError | EndpointError> {
+    if (this.#authority === undefined) return ok(undefined);
+    if (this.#pendingFullPeers.size > 0) {
+      const published = this.#authority.publishFull();
+      if (!published.ok) return err(published.error);
+      for (const peerId of this.#pendingFullPeers) {
+        if (this.#peerIds.has(peerId)) {
+          const sent = this.#endpoint.send(peerId, published.value.bytes);
+          if (!sent.ok) return err(sent.error);
+        }
+      }
+      this.#pendingFullPeers.clear();
+    }
+    const published = this.#authority.publish();
+    if (!published.ok) return err(published.error);
+    for (const peerId of this.#peerIds) {
+      const sent = this.#endpoint.send(peerId, published.value.bytes);
+      if (!sent.ok) return err(sent.error);
+    }
+    return ok(undefined);
+  }
+}

package/src/session/session-plugin.ts

@@ -0,0 +1,52 @@
+// @forgeax/engine-net -- session plugin (host-neutral World integration).
+// (requirements AC-04, plan-strategy D-1/D-3)
+
+import { FixedUpdate, Update } from '@forgeax/engine-ecs';
+import type { Plugin } from '@forgeax/engine-plugin';
+import type { NetEndpoint } from '../endpoint/endpoint';
+import { NetSession } from './net-session';
+
+export interface NetPluginConfig {
+  readonly endpoint: NetEndpoint;
+  readonly maxRawMessages?: number;
+}
+
+export function netPlugin(config: NetPluginConfig): Plugin {
+  return {
+    name: 'net-session',
+    inject: ['world'],
+    apply(ctx) {
+      const world = ctx.world;
+      const session = new NetSession({
+        endpoint: config.endpoint,
+        maxRawMessages: config.maxRawMessages ?? 256,
+      });
+      ctx.effect(() => {
+        world.insertResource('net-session', session);
+        return () => world.removeResource('net-session');
+      }, 'net/session-resource');
+      ctx.effect(() => {
+        world
+          .addSystem(Update, {
+            name: 'net-receive',
+            queries: [],
+            before: [FixedUpdate],
+            fn: (world) => world.getResource<NetSession>('net-session').receiveEvents(),
+          })
+          .unwrap();
+        return () => world.removeSystem(Update, 'net-receive');
+      }, 'net/receive');
+      ctx.effect(() => {
+        world
+          .addSystem(Update, {
+            name: 'net-publish',
+            queries: [],
+            after: [FixedUpdate],
+            fn: (world) => world.getResource<NetSession>('net-session').publish(),
+          })
+          .unwrap();
+        return () => world.removeSystem(Update, 'net-publish');
+      }, 'net/publish');
+    },
+  };
+}