@net-mesh/browser 0.37.0

package/dist/local.js

@@ -0,0 +1,160 @@
+/**
+ * `@net-mesh/browser/local` — a mesh in one page, for developing a game
+ * without an anchor.
+ *
+ * ```ts
+ * import { createLocalMesh } from '@net-mesh/browser/local';
+ *
+ * const mesh = createLocalMesh();
+ * const hostNode = mesh.node();
+ * const playerNode = mesh.node();
+ * const host = hostStore({ definition, transport: hostNode, … });
+ * const player = joinStore({ definition, transport: playerNode, host: hostNode.nodeIdHex(), … });
+ * ```
+ *
+ * A local node satisfies the same structural type `connect()`'s node
+ * does for the store, so `hostStore`, `joinStore` and `hostPlayer` are
+ * the real ones and every frame is really encoded, parsed, chunked,
+ * assembled and dispatched. What is NOT real is the network: delivery
+ * is a function call in this page, and the peer on each frame is
+ * assigned by this module rather than proved by a handshake.
+ *
+ * So a game that works here has working game logic and working store
+ * wiring. It is not evidence that two browsers can reach each other —
+ * that takes an anchor and `connect()`.
+ *
+ * Discovery works too: `announce(tags)` and `query(tag)` behave like
+ * the real node's, including the announcement expiring, so a lobby
+ * list or a find-the-host loop can be built offline as well.
+ *
+ * Nothing here loads the wasm node: importing this subpath costs no
+ * download.
+ */
+/**
+ * How long an announcement stays discoverable: the leaf's default,
+ * 300 s (`net-mesh-leaf` `DEFAULT_TTL_SECS`). A node that announces
+ * once and never again drops out of `query` after it, as on the mesh.
+ */
+export const LOCAL_ANNOUNCEMENT_TTL_MS = 300_000;
+function randomId() {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    let hex = '';
+    for (const byte of bytes)
+        hex += byte.toString(16).padStart(2, '0');
+    return hex;
+}
+function canonicalId(id) {
+    const raw = id.startsWith('0x') ? id.slice(2) : id;
+    if (!/^[0-9a-fA-F]{1,16}$/.test(raw)) {
+        throw new TypeError(`a local node id is up to 16 hex digits, got ${JSON.stringify(id)}`);
+    }
+    return raw.toLowerCase().padStart(16, '0');
+}
+/** Create an empty local mesh. */
+export function createLocalMesh(options = {}) {
+    const listeners = new Map();
+    const ttl = options.announcementTtlMs ?? LOCAL_ANNOUNCEMENT_TTL_MS;
+    const now = options.now ?? (() => Date.now());
+    const announcements = new Map();
+    function deliver(to, from, payload, streamId) {
+        const targets = listeners.get(to);
+        if (targets === undefined)
+            throw new Error(`no local node ${to} on this mesh`);
+        for (const handler of [...targets]) {
+            // A copy per receiver, as a network would hand each its own
+            // bytes: a receiver that mutates its payload must not change
+            // what another receiver — or the sender — holds.
+            handler({ type: 'stream_data', streamId, peerNode: from, payload: payload.slice() });
+        }
+    }
+    function node(requested) {
+        const self = requested === undefined ? randomId() : canonicalId(requested);
+        if (listeners.has(self))
+            throw new Error(`local node ${self} is already on this mesh`);
+        const own = new Set();
+        listeners.set(self, own);
+        let closed = false;
+        return {
+            nodeIdHex: () => self,
+            openStream: options => {
+                if (closed)
+                    throw new Error(`local node ${self} is closed`);
+                const peer = options.peer === undefined ? null : canonicalId(options.peer);
+                // The label stands in for the id a real node derives from it:
+                // both ends name the same stream without exchanging one.
+                const streamId = options.label;
+                let open = true;
+                const stream = {
+                    send: payload => 
+                    // Asynchronous on purpose: a real `send` is a promise, and a
+                    // game that only worked with synchronous delivery would be
+                    // hiding an ordering assumption.
+                    Promise.resolve().then(() => {
+                        if (!open || closed)
+                            throw new Error('this local stream is closed');
+                        if (peer === null)
+                            throw new Error('a local stream needs a peer');
+                        deliver(peer, self, payload, streamId);
+                    }),
+                    close: () => {
+                        open = false;
+                    },
+                };
+                return stream;
+            },
+            onEvent: handler => {
+                own.add(handler);
+                return () => {
+                    own.delete(handler);
+                };
+            },
+            announce: capabilities => {
+                if (closed)
+                    return Promise.reject(new Error(`local node ${self} is closed`));
+                const version = (announcements.get(self)?.version ?? 0n) + 1n;
+                announcements.set(self, { capabilities: Object.freeze([...capabilities]), at: now(), version });
+                return Promise.resolve();
+            },
+            query: capability => {
+                if (closed)
+                    return Promise.reject(new Error(`local node ${self} is closed`));
+                const at = now();
+                const found = [];
+                for (const [id, entry] of announcements) {
+                    if (id === self || at - entry.at >= ttl || !entry.capabilities.includes(capability))
+                        continue;
+                    found.push({
+                        nodeId: BigInt(`0x${id}`).toString(10),
+                        peerIdHex: id,
+                        entityId: null,
+                        capabilities: entry.capabilities,
+                        rtcAddr: null,
+                        noisePubkey: null,
+                        version: entry.version.toString(),
+                    });
+                }
+                return Promise.resolve(found);
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                own.clear();
+                announcements.delete(self);
+                if (listeners.get(self) === own)
+                    listeners.delete(self);
+            },
+        };
+    }
+    return {
+        node,
+        nodes: () => [...listeners.keys()],
+        close: () => {
+            for (const handlers of listeners.values())
+                handlers.clear();
+            listeners.clear();
+            announcements.clear();
+        },
+    };
+}