fakeswarm 0.1.2 → 0.2.1

package/README.md

@@ -47,8 +47,10 @@ 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.
+### createFakeSwarm(seedOrOpts?, topics?)
+- `seedOrOpts` can be:
+  - `Buffer | Uint8Array | null` (legacy seed) or
+  - `{ seed?, net? }`
 - `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:
@@ -68,9 +70,18 @@ Returns an object with:
 - `keyPair`: the generated keypair.
 - `id`: `idEncoding.encode(publicKey)` convenience string.
 
+#### Network profile (opt-in, default off)
+`net.reconnectRace` lets you simulate a quick disconnect/reconnect overlap:
+- `enabled` (boolean): default false. When false, behavior is unchanged.
+- `staleRetentionMs` (default 25): how long a closed socket is retained internally before destroy.
+- `reconnectDelayMs` (default 10): how soon a reconnect attempt is triggered.
+- `duplicateConnection` (boolean): if true, emit a second `connection` event for the new socket even while the stale one is retained.
+`connections` still exposes only the current socket per peer; stale sockets are kept internally and cleaned up after the retention window.
+
 ### 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.
+- **Testing tip:** pass a fresh `topics = new Map()` per test to avoid cross-test bleed; the default module-level map is shared across all swarms in the process.
 
 ### Determinism notes
 - Dial election: only the lexicographically smaller peerId initiates (`peerId < remotePeerId`), preventing double connects.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fakeswarm",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Deterministic in-memory fake hyperswarm for tests and demos.",
   "type": "module",
   "main": "src/index.js",

package/src/index.js

@@ -2,10 +2,20 @@ import EventEmitter from "events";
 import idEncoding from "hypercore-id-encoding";
 import Krypto from "hypercore-crypto";
 import NoiseStream from "@hyperswarm/secret-stream";
+import { normalizeArgs } from "./normalize.js";
 
 const defaultTopics = new Map();
 
-function createFakeSwarm(seed = undefined, topics = defaultTopics) {
+function createFakeSwarm(seedOrOpts = undefined, topicsArg = defaultTopics) {
+    const { seed, net, topics } = normalizeArgs(seedOrOpts, topicsArg);
+
+    const reconnectRace = {
+        enabled: !!net?.reconnectRace?.enabled,
+        staleRetentionMs: net?.reconnectRace?.staleRetentionMs ?? 25,
+        reconnectDelayMs: net?.reconnectRace?.reconnectDelayMs ?? 10,
+        duplicateConnection: !!net?.reconnectRace?.duplicateConnection
+    };
+
     const keyPair = Krypto.keyPair(seed);
     const peerId = idEncoding.encode(keyPair.publicKey);
 
@@ -15,7 +25,15 @@ function createFakeSwarm(seed = undefined, topics = defaultTopics) {
     // remotePeerId -> Promise<void> (prevents duplicate concurrent dials)
     const connecting = new Map();
 
+    // remotePeerId -> array of stale sockets kept temporarily
+    const staleSockets = new Map();
+
+    // timers we await during flush/close for determinism
+    const retentionTimers = new Set();
+    const reconnectTimers = new Set();
+
     const emitter = new EventEmitter();
+    emitter.setMaxListeners(0);
     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)
@@ -89,10 +107,44 @@ function createFakeSwarm(seed = undefined, topics = defaultTopics) {
         emitter.off(event, cb);
     }
 
+    function retainStale(peer, socket) {
+        if (!reconnectRace.enabled) return;
+        const timer = setTimeout(async () => {
+            retentionTimers.delete(timer);
+            await destroySocket(socket);
+            const arr = staleSockets.get(peer);
+            if (arr) {
+                staleSockets.set(peer, arr.filter((s) => s !== socket));
+                if (staleSockets.get(peer).length === 0) staleSockets.delete(peer);
+            }
+        }, reconnectRace.staleRetentionMs);
+        retentionTimers.add(timer);
+        const arr = staleSockets.get(peer) ?? [];
+        arr.push(socket);
+        staleSockets.set(peer, arr);
+    }
+
+    function scheduleReconnectTick() {
+        if (!reconnectRace.enabled) return;
+        const timer = setTimeout(() => {
+            reconnectTimers.delete(timer);
+            if (!closing && !closed) tick();
+        }, reconnectRace.reconnectDelayMs);
+        reconnectTimers.add(timer);
+    }
+
     function trackConnection(peer, socket) {
         const drop = () => {
-            connections.delete(peer);
-            emitter.emit("update");
+            const current = connections.get(peer)?.socket;
+            if (current === socket) {
+                connections.delete(peer);
+                emitter.emit("update");
+                retainStale(peer, socket);
+                scheduleReconnectTick();
+            } else if (reconnectRace.enabled) {
+                // stale socket closed after new one took over
+                retainStale(peer, socket);
+            }
         };
         socket.once("close", drop);
         socket.once("error", drop);
@@ -102,7 +154,10 @@ function createFakeSwarm(seed = undefined, topics = defaultTopics) {
         if (closing || closed) return;
         if (!conn || !conn.id) return;
         if (conn.id === peerId) return;
-        if (connections.has(conn.id)) return;
+        if (connections.has(conn.id)) {
+            if (!reconnectRace.duplicateConnection) return;
+            // allow duplicate event later; still accept for overlap
+        }
 
         // 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.)
@@ -143,7 +198,7 @@ function createFakeSwarm(seed = undefined, topics = defaultTopics) {
     async function dial(remotePeerId, makeConnection) {
         if (closing || closed) return;
         if (remotePeerId === peerId) return;
-        if (connections.has(remotePeerId)) return;
+        if (connections.has(remotePeerId) && !reconnectRace.duplicateConnection) return;
 
         if (!shouldDial(remotePeerId)) return;
         if (connecting.has(remotePeerId)) return;
@@ -161,7 +216,7 @@ function createFakeSwarm(seed = undefined, topics = defaultTopics) {
             if (!socket) return;
 
             // It's possible we raced and connected through the other side while awaiting.
-            if (connections.has(remotePeerId)) {
+            if (connections.has(remotePeerId) && !reconnectRace.duplicateConnection) {
                 if (socket?.destroy) await destroySocket(socket);
                 return;
             }
@@ -224,7 +279,7 @@ function createFakeSwarm(seed = undefined, topics = defaultTopics) {
             // Wait for any in-flight dial promises.
             await Promise.allSettled(Array.from(connecting.values()));
 
-            if (connecting.size === 0) {
+            if (connecting.size === 0 && retentionTimers.size === 0 && reconnectTimers.size === 0) {
                 stableZero += 1;
                 if (stableZero >= 2) return; // two consecutive quiet checks
             } else {
@@ -263,6 +318,10 @@ function createFakeSwarm(seed = undefined, topics = defaultTopics) {
             closing = true;
 
             if (tickTimer) clearTimeout(tickTimer);
+            for (const t of Array.from(retentionTimers)) clearTimeout(t);
+            for (const t of Array.from(reconnectTimers)) clearTimeout(t);
+            retentionTimers.clear();
+            reconnectTimers.clear();
 
             // Stop publishing our topics (prevents new dials toward us)
             for (const topicId of Array.from(publishedTopics)) {
@@ -279,6 +338,10 @@ function createFakeSwarm(seed = undefined, topics = defaultTopics) {
             await Promise.allSettled(
                 Array.from(connections.values()).map(({ socket }) => destroySocket(socket))
             );
+            await Promise.allSettled(
+                Array.from(staleSockets.values()).flat().map((socket) => destroySocket(socket))
+            );
+            staleSockets.clear();
 
             connections.clear();
             emitter.emit("update");

package/src/normalize.js

@@ -0,0 +1,17 @@
+export function normalizeArgs(seedOrOpts, topicsArg) {
+  const isBufferLike =
+    seedOrOpts &&
+    (Buffer.isBuffer(seedOrOpts) ||
+      seedOrOpts instanceof Uint8Array);
+
+  if (isBufferLike || seedOrOpts === null || seedOrOpts === undefined) {
+    return { seed: seedOrOpts, net: undefined, topics: topicsArg };
+  }
+
+  if (typeof seedOrOpts === "object") {
+    const { seed = undefined, net = undefined } = seedOrOpts;
+    return { seed, net, topics: topicsArg };
+  }
+
+  return { seed: undefined, net: undefined, topics: topicsArg };
+}