fakeswarm 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fakeswarm contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# fakeswarm
+
+Deterministic, single-process, in-memory fake of a Hyperswarm-like swarm. Useful for tests, examples, or labs where you need predictable peer connections without any real DHT, NAT, or network traffic.
+
+**What it is**
+- In-memory swarm that pairs peers by shared topics in a shared Map.
+- Deterministic dial election so only one side initiates.
+- Uses `@hyperswarm/secret-stream` Noise streams for realistic socket shape.
+
+**What it is not**
+- No real networking, NAT traversal, DHT, peer discovery, or reconnection logic.
+- Not a drop-in for production Hyperswarm; it is a lab fake.
+
+## Install
+
+```bash
+npm install fakeswarm
+```
+
+## Quickstart
+
+Two swarms join the same topic and exchange a message:
+
+```js
+import { createFakeSwarm } from 'fakeswarm';
+import crypto from 'crypto';
+
+const topic = crypto.randomBytes(32);
+const swarmA = createFakeSwarm();
+const swarmB = createFakeSwarm();
+
+swarmA.join(topic);
+swarmB.join(topic);
+
+swarmB.on('connection', (socket, peerInfo) => {
+  socket.on('data', (data) => {
+    console.log('B got:', data.toString(), 'from', peerInfo.id);
+  });
+});
+
+swarmA.on('connection', (socket) => {
+  socket.write('hello');
+});
+```
+
+Always call `close()` when done to unpublish topics and destroy sockets.
+
+## API
+
+### createFakeSwarm(seed?, topics?)
+- `seed` (Buffer | Uint8Array | null): optional seed passed to `hypercore-crypto.keyPair` for deterministic keys.
+- `topics` (Map) optional shared topics map. By default a module-level Map is used so multiple swarms share the same space.
+
+Returns an object with:
+- `join(topic, opts?)` -> discovery handle: joins a topic (Buffer). `opts` mirrors Hyperswarm with defaults `{ server: true, client: true }`.
+  - If `server: false`, the swarm will not publish/accept on this topic.
+  - If `client: false`, the swarm will not dial on this topic.
+  - Handle exposes `leave()` / `destroy()` (unpublish), and `refresh()` / `flushed()` (immediate no-ops for parity).
+- `leave(topic)`: unpublish without the handle.
+- `connections`: `Map<peerId, { socket, peerInfo }>` of active sockets.
+- `topics`: Set of encoded topics joined (any mode).
+- `on(event, fn)` / `off(event, fn)`: EventEmitter style. Events:
+  - `connection` `(socket, peerInfo)` where `peerInfo = { publicKey, id, initiator }`.
+  - `close` when the swarm closes.
+  - `update` when the connection set changes.
+- `flush(timeoutMs?)`: wait (best-effort) for in-flight dials to settle; useful in tests to let the tick loop quiesce.
+- `close()` / `destroy()`: unpublish, stop ticking, destroy sockets, and emit `close`.
+- `keyPair`: the generated keypair.
+- `id`: `idEncoding.encode(publicKey)` convenience string.
+
+### Join / leave semantics
+- Joining registers this swarm in the shared topics map; peers that share a topic will connect.
+- Leaving (or closing) removes the entry from the shared map to avoid ghost peers.
+
+### Determinism notes
+- Dial election: only the lexicographically smaller peerId initiates (`peerId < remotePeerId`), preventing double connects.
+- Backfill: the first `connection` listener added receives existing connections immediately (if any).
+- Flush: waits for connecting dials to drain; it does not advance time on its own.
+
+### Resource cleanup
+- Always call `close()` (or `destroy()`) to unpublish topics and destroy sockets.
+- `flush()` can be used in tests to wait until the swarm has no in-flight dials before asserting.
+
+## Limitations
+- No NAT traversal, DHT, hole-punching, or real network I/O.
+- No reconnection, banning, or peer prioritization.
+- No peer discovery beyond the shared in-memory topics map you provide.
+- Single-process only; for multi-process/multi-machine tests use real Hyperswarm.
+
+## License
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "fakeswarm",
+  "version": "0.1.2",
+  "description": "Deterministic in-memory fake hyperswarm for tests and demos.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "brittle \"test/**/*.test.js\"",
+    "lint": "eslint \"src/**/*.js\" \"test/**/*.js\""
+  },
+  "keywords": [
+    "hyperswarm",
+    "test",
+    "fake",
+    "noise"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:zacharygriffee/fakeswarm.git"
+  },
+  "dependencies": {
+    "@hyperswarm/secret-stream": "^6.9.1",
+    "hypercore-crypto": "^3.6.1",
+    "hypercore-id-encoding": "^1.3.0"
+  },
+  "devDependencies": {
+    "b4a": "^1.7.3",
+    "brittle": "^3.19.1",
+    "eslint": "^9.39.2"
+  }
+}

package/src/index.js

@@ -0,0 +1,307 @@
+import EventEmitter from "events";
+import idEncoding from "hypercore-id-encoding";
+import Krypto from "hypercore-crypto";
+import NoiseStream from "@hyperswarm/secret-stream";
+
+const defaultTopics = new Map();
+
+function createFakeSwarm(seed = undefined, topics = defaultTopics) {
+    const keyPair = Krypto.keyPair(seed);
+    const peerId = idEncoding.encode(keyPair.publicKey);
+
+    // remotePeerId -> { socket, peerInfo }
+    const connections = new Map();
+
+    // remotePeerId -> Promise<void> (prevents duplicate concurrent dials)
+    const connecting = new Map();
+
+    const emitter = new EventEmitter();
+    const joinedTopics = new Set();     // all topics we joined (regardless of mode)
+    const dialTopics = new Set();       // topics where we will attempt outbound dials (client mode)
+    const publishedTopics = new Set();  // topics we publish into the shared map (server mode)
+
+    let closed = false;
+    let closing = false;
+
+    // only used for backfilling existing connections to the *first* connection listener
+    let didBackfillConnections = false;
+
+    function join(topic, opts = {}) {
+        if (closing || closed) return;
+        const topicId = idEncoding.encode(topic);
+        const { server = true, client = true } = opts ?? {};
+        joinedTopics.add(topicId);
+
+        if (client) dialTopics.add(topicId);
+        else dialTopics.delete(topicId);
+
+        // Publish only in server mode.
+        if (server) {
+            const peers = topics.get(topicId) ?? new Map();
+            peers.set(peerId, { makeConnection: _incoming });
+            topics.set(topicId, peers);
+            publishedTopics.add(topicId);
+        } else {
+            // If previously published and now called with server=false, unpublish.
+            unpublish(topicId);
+        }
+
+        const discovery = {
+            leave: () => leave(topic),
+            destroy: () => leave(topic),
+            refresh: () => Promise.resolve(),
+            flushed: () => Promise.resolve()
+        };
+
+        return discovery;
+    }
+
+    function leave(topic) {
+        if (closing || closed) return;
+
+        const topicId = idEncoding.encode(topic);
+        joinedTopics.delete(topicId);
+        dialTopics.delete(topicId);
+        unpublish(topicId);
+    }
+
+    function unpublish(topicId) {
+        publishedTopics.delete(topicId);
+        const peers = topics.get(topicId);
+        if (!peers) return;
+        peers.delete(peerId);
+        if (peers.size === 0) topics.delete(topicId);
+    }
+
+    function on(event, cb) {
+        emitter.on(event, cb);
+
+        // Backfill only for the first "connection" listener.
+        if (event === "connection" && !didBackfillConnections) {
+            didBackfillConnections = true;
+            for (const { socket, peerInfo } of connections.values()) {
+                emitter.emit("connection", socket, peerInfo);
+            }
+        }
+    }
+
+    function off(event, cb) {
+        emitter.off(event, cb);
+    }
+
+    function trackConnection(peer, socket) {
+        const drop = () => {
+            connections.delete(peer);
+            emitter.emit("update");
+        };
+        socket.once("close", drop);
+        socket.once("error", drop);
+    }
+
+    async function _incoming(conn) {
+        if (closing || closed) return;
+        if (!conn || !conn.id) return;
+        if (conn.id === peerId) return;
+        if (connections.has(conn.id)) return;
+
+        // Guard: if we're already in-flight dialing this peer, don't also accept/construct.
+        // (This is conservative; the dial-election below in loop() is the main duplication killer.)
+        if (connecting.has(conn.id)) return;
+
+        const ssLocal = new NoiseStream(false); // incoming side: non-initiator
+        const ssRemote = new NoiseStream(true); // remote side: initiator (returned to caller)
+
+        ssLocal.rawStream.pipe(ssRemote.rawStream).pipe(ssLocal.rawStream);
+
+        const remotePublicKey = conn.publicKey ?? idEncoding.decode(conn.id);
+
+        const peerInfo = {
+            id: conn.id,
+            publicKey: remotePublicKey,
+            initiator: false
+        };
+
+        connections.set(conn.id, { socket: ssLocal, peerInfo });
+        trackConnection(conn.id, ssLocal);
+        emitter.emit("update");
+
+        ssLocal.once("open", () => {
+            if (closing || closed) return;
+            ssLocal.remotePublicKey = remotePublicKey;
+            emitter.emit("connection", ssLocal, peerInfo);
+        });
+
+        return ssRemote;
+    }
+
+    function shouldDial(remotePeerId) {
+        // Deterministic dial election: only one side initiates.
+        // If both sides run the same code, this prevents double-connect.
+        return peerId < remotePeerId;
+    }
+
+    async function dial(remotePeerId, makeConnection) {
+        if (closing || closed) return;
+        if (remotePeerId === peerId) return;
+        if (connections.has(remotePeerId)) return;
+
+        if (!shouldDial(remotePeerId)) return;
+        if (connecting.has(remotePeerId)) return;
+
+        const p = (async () => {
+            const socket = await makeConnection({
+                id: peerId,
+                publicKey: keyPair.publicKey
+            });
+
+            if (closing || closed) {
+                if (socket?.destroy) await destroySocket(socket);
+                return;
+            }
+            if (!socket) return;
+
+            // It's possible we raced and connected through the other side while awaiting.
+            if (connections.has(remotePeerId)) {
+                if (socket?.destroy) await destroySocket(socket);
+                return;
+            }
+
+            const remotePublicKey = idEncoding.decode(remotePeerId);
+
+            const peerInfo = {
+                id: remotePeerId,
+                publicKey: remotePublicKey,
+                initiator: true
+            };
+
+            connections.set(remotePeerId, { socket, peerInfo });
+            trackConnection(remotePeerId, socket);
+            emitter.emit("update");
+
+            socket.once("open", () => {
+                if (closing || closed) return;
+                socket.remotePublicKey = remotePublicKey;
+                emitter.emit("connection", socket, peerInfo);
+            });
+        })().finally(() => {
+            connecting.delete(remotePeerId);
+        });
+
+        connecting.set(remotePeerId, p);
+        await p;
+    }
+
+    let tickTimer;
+
+    function tick() {
+        if (closing || closed) return;
+
+        for (const [topicId, peers] of topics.entries()) {
+            if (!dialTopics.has(topicId)) continue;
+
+            for (const [remotePeerId, { makeConnection }] of peers.entries()) {
+                if (remotePeerId === peerId) continue;              // FIX: continue, not return
+                if (connections.has(remotePeerId)) continue;        // FIX: continue, not return
+                if (closing || closed) return;
+
+                // Fire and forget; connection is guarded by connecting map
+                // (but still awaits inside dial for sequencing correctness).
+                void dial(remotePeerId, makeConnection);
+            }
+        }
+
+        if (closing || closed) return;
+        tickTimer = setTimeout(tick, 10);
+    }
+
+    async function flush(timeoutMs = 100) {
+        if (closing || closed) return;
+
+        const start = Date.now();
+        let stableZero = 0;
+
+        while (!closed && !closing) {
+            // Wait for any in-flight dial promises.
+            await Promise.allSettled(Array.from(connecting.values()));
+
+            if (connecting.size === 0) {
+                stableZero += 1;
+                if (stableZero >= 2) return; // two consecutive quiet checks
+            } else {
+                stableZero = 0;
+            }
+
+            if (Date.now() - start >= timeoutMs) return;
+            await new Promise((resolve) => setTimeout(resolve, 5));
+        }
+    }
+
+    async function destroySocket(s) {
+        if (!s) return;
+        await new Promise((resolve) => {
+            const done = () => resolve();
+
+            try {
+                if (s.destroyed) return resolve();
+                s.once?.("close", done);
+                s.once?.("error", done);
+                if (typeof s.destroy === "function") s.destroy();
+                else setImmediate(done);
+                // Fallback in case no events fire.
+                setTimeout(done, 10);
+            } catch {
+                resolve();
+            }
+        });
+    }
+
+    tick();
+
+    return {
+        async close() {
+            if (closed || closing) return;
+            closing = true;
+
+            if (tickTimer) clearTimeout(tickTimer);
+
+            // Stop publishing our topics (prevents new dials toward us)
+            for (const topicId of Array.from(publishedTopics)) {
+                unpublish(topicId);
+            }
+            publishedTopics.clear();
+            dialTopics.clear();
+            joinedTopics.clear();
+
+            // Wait for in-flight connects to settle (best-effort)
+            await Promise.allSettled(Array.from(connecting.values()));
+
+            // Destroy sockets best-effort.
+            await Promise.allSettled(
+                Array.from(connections.values()).map(({ socket }) => destroySocket(socket))
+            );
+
+            connections.clear();
+            emitter.emit("update");
+            closed = true;
+            emitter.emit("close");
+        },
+
+        // Alias used by some labs; accepts options for API parity but ignores them.
+        async destroy(_opts = {}) {
+            await this.close();
+        },
+
+        connections,       // Map(remotePeerId -> { socket, peerInfo })
+        join,
+        leave,
+        flush,
+        topics: joinedTopics,
+        on,
+        off,
+        keyPair,
+        id: peerId
+    };
+}
+
+export { createFakeSwarm }
+export default createFakeSwarm;