beamdb 0.9.2 → 0.12.0

package/README.md

@@ -23,6 +23,7 @@
 - [Wire Protocol](#wire-protocol)
 - [Configuration](#configuration)
 - [Testing](#testing)
+- [Benchmarks](#benchmarks)
 - [Features](#features)
 - [Security](#security)
 - [Contributing](#contributing)
@@ -111,7 +112,7 @@ await init();
 
 // Create a BEAM node
 const beam = new Beam();                        // in-memory (lost on reload)
-// or: const beam = new Beam.new_persistent();   // IndexedDB (survives reload)
+// or: const beam = Beam.new_persistent();   // IndexedDB (survives reload)
 
 // Connect to a relay server
 beam.connect("wss://relay.example.com/ws");
@@ -125,7 +126,7 @@ beam.put_null("users.alice.deleted");    // explicit null
 // Read once (returns a Promise)
 const name = await beam.get("users.alice.name");  // "Alice"
 
-// Subscribe to updates at a path
+// Subscribe to child updates (Gun.js .on() semantics)
 beam.on("users.alice.name", (value) => {
   console.log("name changed:", value);
 });
@@ -180,7 +181,7 @@ beam.stop();
 import init, { Beam } from "./beam.js";
 await init();
 
-const beam = new Beam.new_persistent();
+const beam = Beam.new_persistent();
 beam.connect("wss://relay.example.com/ws");
 
 // Writes survive page reload via IndexedDB
@@ -244,6 +245,10 @@ BEAM browser nodes are wire-compatible with Gun.js. A BEAM WASM node can:
 - Verify Gun.js SEA signatures (P-256 ECDSA, double-hashed)
 - Interoperate with the Gun.js graph format
 
+Bidirectional compatibility is verified by Playwright E2E tests
+(`tests/e2e/gun-beam-interop.spec.mjs`) covering Gun.js→BEAM, BEAM→Gun.js,
+and bidirectional convergence scenarios.
+
 ## Quick Start
 
 ### Build & Run a Node
@@ -799,6 +804,7 @@ let config = Config {
     my_pub: Some("x.y".into()),
     broadcast_buffer_size: 4096,
     ice_servers: vec!["stun:stun.l.google.com:19302".into()],
+    dedup_capacity: 100_000,
 };
 # }
 ```
@@ -872,7 +878,6 @@ cargo clippy -- -D warnings
 # Doctests only (verifies README code examples compile)
 cargo test --doc
 
-# Benchmarks
 cargo bench
 
 # Run a specific integration test
@@ -903,6 +908,114 @@ cargo test --test wire_live -- --ignored  # Layer 3: live integration (needs Nod
 
 ---
 
+## Benchmarks
+
+BEAM includes a comprehensive benchmarking suite covering relay throughput,
+micro-benchmarks for hot-path components, and storage performance.
+
+### Local Put Throughput
+
+Local (non-relay) puts through the actor pipeline — measures the full
+`Node::handle → Router::route → MemoryStorage::apply` path with no network I/O:
+
+| Scenario | Messages | Throughput |
+|----------|----------|------------|
+| 1 sender × 10k | 10,000 | ~24,000–53,000 puts/sec |
+
+Throughput varies with system load. On a dedicated machine with no
+competing processes, expect 50,000+ puts/sec. The bottleneck is
+`Value` cloning for broadcast channels — further gains require
+`Arc<Value>` to make cloning a refcount bump.
+
+### Relay Throughput
+
+Real WebSocket connections through a memory-only relay (no disk I/O):
+
+| Scenario | Messages | Throughput |
+|----------|----------|------------|
+| 1 sender × 10k | 10,000 | ~5,300 msgs/sec |
+| 1 sender × 50k | 50,000 | ~10,600 msgs/sec |
+| 10 senders × 5k | 50,000 | ~11,400 msgs/sec |
+
+The relay's internal processing (parse + dedup + route + serialize) runs in
+microseconds — the bottleneck is client-side `put().await`, not the relay.
+
+### Micro-Benchmarks (Criterion)
+
+| Operation | Time |
+|-----------|------|
+| Parse small Put JSON | 1,067 ns |
+| Parse medium Put JSON | 2.00 µs |
+| Serialize small Put JSON | 69 ns |
+| Parse Get | 677 ns |
+| Dedup check (fresh) | 274 µs |
+| Dedup check (duplicate) | 41.8 µs |
+| Actor mailbox send+recv | 309 µs |
+
+### WASM Benchmarks (Node.js)
+
+| Operation | WASM | Native | Ratio |
+|-----------|------|--------|-------|
+| Parse small Put | 7.9 µs | 1,067 ns | ~7.4× |
+| Serialize small Put | 8.6 µs | 69 ns | ~125× |
+| Parse Get | 4.5 µs | 677 ns | ~6.7× |
+
+Run with: `wasm-pack test --node --no-default-features -- --nocapture`
+
+### WASM Relay Throughput (Browser-only)
+
+`web_sys::WebSocket` callbacks don't fire in Node.js `wasm-bindgen-test-runner`
+([known limitation](https://github.com/wasm-bindgen/wasm-bindgen/issues/4921)).
+Use the browser benchmark page to measure WASM relay throughput:
+
+```bash
+cargo run -- start --port 4944 --memory-storage true --redb-storage false
+python3 -m http.server 8080 -d examples/
+# Open http://localhost:8080/bench.html in a browser
+```
+
+Previous v0.11.0 browser results: ~115–651 msgs/sec depending on batch size.
+
+### Browser Benchmark
+
+An interactive benchmark page is available at `examples/bench.html`:
+
+```bash
+# Start a relay
+cargo run -- start --port 4944 --memory-storage true --redb-storage false
+
+# Serve the benchmark page
+python3 -m http.server 8080 -d examples/
+
+# Open in browser
+open http://localhost:8080/bench.html
+```
+
+The browser benchmark measures:
+- **Relay TPS**: end-to-end throughput through a real relay
+- **Put throughput**: local WASM API fire-and-forget puts
+- **Get throughput**: local WASM API promise resolution
+- **Put→Get round-trip**: full local cycle
+
+### Running Benchmarks
+
+```bash
+# Relay throughput (release mode required)
+cargo test --release --test relay_throughput_bench -- --ignored --nocapture
+
+# Micro-benchmarks (hot-path components)
+cargo bench --bench my_benchmark -- "wire_|dup_check|actor_mailbox"
+
+# Storage benchmarks
+cargo bench --bench my_benchmark -- "write_storm|read_storm|mixed"
+
+# Live metrics endpoint (while relay is running)
+curl http://localhost:8080/metrics
+```
+
+See [`benches/RESULTS.md`](benches/RESULTS.md) for full results with
+methodology and analysis.
+
 ## Features
 
 | Feature | Default | Enables |

package/beam.d.ts

@@ -115,11 +115,11 @@ export interface InitOutput {
     readonly beam_put_num: (a: number, b: number, c: number, d: number) => void;
     readonly beam_stop: (a: number) => void;
     readonly task_worker_entry_point: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_1101: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_1115: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_234: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_234_2: (a: number, b: number, c: number) => void;
-    readonly __wasm_bindgen_func_elem_234_3: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_1109: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_1123: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_232: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_232_2: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_232_3: (a: number, b: number, c: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;

package/beam.js

@@ -290,7 +290,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_1115(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_1123(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -308,7 +308,7 @@ function __wbg_get_imports() {
                     const a = state0.a;
                     state0.a = 0;
                     try {
-                        return __wasm_bindgen_func_elem_1115(a, state0.b, arg0, arg1);
+                        return __wasm_bindgen_func_elem_1123(a, state0.b, arg0, arg1);
                     } finally {
                         state0.a = a;
                     }
@@ -432,23 +432,23 @@ function __wbg_get_imports() {
             return addHeapObject(ret);
         }, arguments); },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 12, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_234);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 15, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_232);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000002: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 269, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_1101);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 272, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_1109);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000003: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("IDBVersionChangeEvent")], shim_idx: 12, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_234_2);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("IDBVersionChangeEvent")], shim_idx: 15, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_232_2);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000004: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("MessageEvent")], shim_idx: 12, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
-            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_234_3);
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [NamedExternref("MessageEvent")], shim_idx: 15, ret: Unit, inner_ret: Some(Unit) }, mutable: true }) -> Externref`.
+            const ret = makeMutClosure(arg0, arg1, __wasm_bindgen_func_elem_232_3);
             return addHeapObject(ret);
         },
         __wbindgen_cast_0000000000000005: function(arg0) {
@@ -475,22 +475,22 @@ function __wbg_get_imports() {
     };
 }
 
-function __wasm_bindgen_func_elem_234(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_234(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_232(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_232(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_234_2(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_234_2(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_232_2(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_232_2(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_234_3(arg0, arg1, arg2) {
-    wasm.__wasm_bindgen_func_elem_234_3(arg0, arg1, addHeapObject(arg2));
+function __wasm_bindgen_func_elem_232_3(arg0, arg1, arg2) {
+    wasm.__wasm_bindgen_func_elem_232_3(arg0, arg1, addHeapObject(arg2));
 }
 
-function __wasm_bindgen_func_elem_1101(arg0, arg1, arg2) {
+function __wasm_bindgen_func_elem_1109(arg0, arg1, arg2) {
     try {
         const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
-        wasm.__wasm_bindgen_func_elem_1101(retptr, arg0, arg1, addHeapObject(arg2));
+        wasm.__wasm_bindgen_func_elem_1109(retptr, arg0, arg1, addHeapObject(arg2));
         var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
         var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
         if (r1) {
@@ -501,8 +501,8 @@ function __wasm_bindgen_func_elem_1101(arg0, arg1, arg2) {
     }
 }
 
-function __wasm_bindgen_func_elem_1115(arg0, arg1, arg2, arg3) {
-    wasm.__wasm_bindgen_func_elem_1115(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
+function __wasm_bindgen_func_elem_1123(arg0, arg1, arg2, arg3) {
+    wasm.__wasm_bindgen_func_elem_1123(arg0, arg1, addHeapObject(arg2), addHeapObject(arg3));
 }
 
 

package/package.json

@@ -6,7 +6,7 @@
     "David Newman <david.r.newman@proton.me>"
   ],
   "description": "BEAM — distributed graph database syncing over WebSocket, WebRTC, and multicast. Successor to rod.",
-  "version": "0.9.2",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",