logos-messaging-nim/docs/wasm-edge-node.md

Browser edge node (wasm)

library/edge/edge_lib.nim builds to a WebAssembly module exposing a small C ABI (edge_new, edge_lightpush_publish, edge_filter_subscribe, edge_store_query, edge_stop, ffi_poll). Build it with scripts/build_edge_wasm.sh; the output lands in build/wasm/edge.{js,wasm}.

The build is --threads:off, so it uses the two overrides in wasm-deps/ (ffi and brokers), wired in config.nims under -d:emscripten, plus wasm-deps/edge_builders.nim in place of libp2p/builders. See scripts/gen_edge_builders.py.

Driving the event loop: ffi_poll()

There is no worker thread in the browser build. The host owns the loop and must call ffi_poll(), which advances chronos by exactly one iteration.

That makes the host's poll rate a hard ceiling on how fast libp2p can complete anything. A handshake is not one iteration — multistream, noise, yamux, identify and the waku metadata exchange are thousands of small reads and writes, each needing a poll to progress.

Do not do this:

setInterval(() => M._ffi_poll(), 1);   // ~250 polls/s — far too slow

setInterval is clamped to ~4ms by every browser (and throttled to 1/s in a background tab), and it runs the body once per tick. Measured against a wakunode2 on localhost:

pump	identify	filter subscribe
setInterval(poll, 1)	~12.7 s	never completes
burst (below)	~1.0 s	succeeds, ~1 s end to end

With the slow pump the node gives up first — it dials /vac/waku/metadata/1.0.0 on the edge, times out, and disconnects with waku metatdata request failed: read failed: Stream Closed!, which kills the in-flight subscribe. The symptom looks like a filter bug and is not one. The waku metadata ... Stream EOF! line in the browser console is the same starvation seen from the other side.

Do this instead — burst while a request is outstanding, idle on a throttled timer so an idle node is not a CPU spinner:

const pump = (() => {
  const BURST_MS = 4, IDLE_BATCH = 64, IDLE_TICK_MS = 4;
  const chan = new MessageChannel();          // not clamped, unlike setTimeout/Interval
  let inFlight = 0, queued = false;
  const schedule = () => {
    if (queued) return;
    queued = true;
    if (inFlight > 0) chan.port2.postMessage(0); else setTimeout(tick, IDLE_TICK_MS);
  };
  const tick = () => {
    queued = false;
    if (inFlight > 0) {
      const t0 = performance.now();
      do { M._ffi_poll(); } while (performance.now() - t0 < BURST_MS);
    } else {
      for (let i = 0; i < IDLE_BATCH; i++) M._ffi_poll();
    }
    schedule();
  };
  chan.port1.onmessage = tick;
  schedule();
  return { enter: () => { inFlight++; schedule(); }, leave: () => { inFlight--; } };
})();

Call pump.enter() when submitting a request and pump.leave() from its callback — the one place every request already passes through. The idle batch still has to be generous: it is what services timers, keepalives and inbound filter pushes. 64 polls per 4ms tick holds a subscription open indefinitely (verified over several minutes).

build/wasm/chat_demo_local.html is the reference harness and uses exactly this pump.

Reproducing against a local node

wakunode2 --cluster-id=16 --shard=32 --relay=true --lightpush=true --filter=true \
          --store=true --websocket-support=true --websocket-port=8401 --tcp-port=60401 \
          --nat=extip:<your-lan-ip> --nodekey=<64 hex chars>

Point SERVICE in the demo at the /ws multiaddr the node logs under Listening on, serve build/wasm over HTTP, and open the page. A lone node answers lightpush with No peers for topic, skipping publish — that is the node having no relay mesh, not an edge failure.