@noy-db/by-peer 0.1.0-pre.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+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,89 @@
+# @noy-db/by-peer
+
+WebRTC peer-to-peer transport for [noy-db](https://github.com/vLannaAi/noy-db) — no server in the middle.
+
+> First member of the `by-*` family of session-share transports. See [`docs/packages/by-transports.md`](../../docs/packages/by-transports.md) for the family contract and roster.
+>
+> Previously published as `@noy-db/p2p` — same code, renamed to fit the prefix family.
+
+## Install
+
+```sh
+pnpm add @noy-db/by-peer @noy-db/hub
+```
+
+## Why
+
+Classic cloud sync routes every envelope through a central store. `@noy-db/by-peer` lets two browsers (or two Node processes) shake hands over any signaling channel you pick and then sync directly over a WebRTC DataChannel. Any TURN relay in the path only ever sees noy-db's AES-256-GCM ciphertext — the transport is independent of the encryption.
+
+## Use as a SyncTarget
+
+```ts
+import { createNoydb } from '@noy-db/hub'
+import { to } from '@noy-db/to-browser-idb'
+import { peerStore, createOffer, acceptOffer } from '@noy-db/by-peer'
+
+// Peer A — initiator
+const initiator = await createOffer()
+shareWithPeerB(initiator.offer)             // QR code, Matrix, pastebin, …
+await initiator.accept(await receiveAnswer())
+const channel = await initiator.channel
+
+const db = await createNoydb({
+  store: to(),
+  sync: { store: peerStore({ channel }), role: 'sync-peer' },
+})
+```
+
+Peer B mirrors the handshake with `acceptOffer` and runs `servePeerStore({ channel, store })` so its local store answers the incoming RPC calls.
+
+## Read-only peers
+
+```ts
+servePeerStore({
+  channel,
+  store: local,
+  allow: new Set(['get', 'list', 'loadAll', 'listPage', 'ping']),
+})
+```
+
+Denied methods surface as a remote `Error` at the client.
+
+## Leader election (cross-tab coordination)
+
+When 3+ tabs share a `BroadcastChannel`-backed `PeerChannel` (typically via `@noy-db/by-tabs`) and each runs `servePeerStore`, every non-sending tab responds to every RPC — producing duplicate responses for the same request id and `O(N²)` channel traffic at scale (issue [#3](https://github.com/vLannaAi/noy-db/issues/3)).
+
+Opt in to leader-election semantics via the Web Locks API. Only the lock-holding tab registers an RPC handler; others queue silently and take over when the holder's tab closes (the lock auto-releases).
+
+```ts
+import { tabsChannel } from '@noy-db/by-tabs'
+import { servePeerStore } from '@noy-db/by-peer'
+
+const channel = tabsChannel({ name: 'my-app:vault' })
+
+servePeerStore({
+  channel,
+  store: localStore,
+  leaderElection: { lockName: 'noy-db:peer-server:my-app:vault' },
+})
+```
+
+The same `lockName` MUST be used by every tab participating in the role. Browser support: Chrome 69+, Firefox 96+, Safari 15.4+. For tests or non-browser hosts, pass a stub `MinimalLockManager` via `leaderElection.locks`.
+
+The 2-tab case works correctly without `leaderElection` (BroadcastChannel doesn't echo to sender). Enable for any consumer expecting 3+ tabs.
+
+## Transport abstraction
+
+`PeerChannel` is the only primitive — any reliable in-order string channel works. The same wrapper is reused by every other `by-*` package:
+
+| Transport | Factory | Package |
+|---|---|---|
+| WebRTC DataChannel | `fromDataChannel(dc)` | `@noy-db/by-peer` |
+| In-memory pair (tests) | `pairInMemory()` | `@noy-db/by-peer` |
+| BroadcastChannel | `tabsChannel(name)` | `@noy-db/by-tabs` |
+| WebSocket / SSE relay | (planned) | `@noy-db/by-server` |
+| Liveblocks / Yjs room | (planned) | `@noy-db/by-room` |
+
+## Status
+
+`0.1.0-pre.1` — prototype. LAN-first. Multi-peer mesh is a follow-up.

package/dist/index.cjs

@@ -0,0 +1,491 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  acceptOffer: () => acceptOffer,
+  createOffer: () => createOffer,
+  createRpcClient: () => createRpcClient,
+  fromDataChannel: () => fromDataChannel,
+  pairInMemory: () => pairInMemory,
+  peerStore: () => peerStore,
+  servePeerStore: () => servePeerStore,
+  serveRpc: () => serveRpc
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/channel.ts
+function pairInMemory() {
+  function make() {
+    const listeners = { message: /* @__PURE__ */ new Set(), close: /* @__PURE__ */ new Set() };
+    const closed = { v: false };
+    const ch = {
+      get isOpen() {
+        return !closed.v;
+      },
+      send() {
+      },
+      on(event, listener) {
+        if (event === "message") {
+          listeners.message.add(listener);
+          return () => listeners.message.delete(listener);
+        }
+        listeners.close.add(listener);
+        return () => listeners.close.delete(listener);
+      },
+      close() {
+        if (closed.v) return;
+        closed.v = true;
+        for (const fn of listeners.close) fn();
+      }
+    };
+    return { ch, listeners, closed };
+  }
+  const a = make();
+  const b = make();
+  function closeBoth() {
+    if (!a.closed.v) {
+      a.closed.v = true;
+      for (const fn of a.listeners.close) fn();
+    }
+    if (!b.closed.v) {
+      b.closed.v = true;
+      for (const fn of b.listeners.close) fn();
+    }
+  }
+  a.ch.send = (payload) => {
+    if (b.closed.v) throw new Error("PeerChannel closed");
+    queueMicrotask(() => {
+      for (const fn of b.listeners.message) fn(payload);
+    });
+  };
+  b.ch.send = (payload) => {
+    if (a.closed.v) throw new Error("PeerChannel closed");
+    queueMicrotask(() => {
+      for (const fn of a.listeners.message) fn(payload);
+    });
+  };
+  a.ch.close = closeBoth;
+  b.ch.close = closeBoth;
+  return [a.ch, b.ch];
+}
+function fromDataChannel(dc) {
+  const listeners = { message: /* @__PURE__ */ new Set(), close: /* @__PURE__ */ new Set() };
+  let closed = false;
+  dc.addEventListener("message", (ev) => {
+    if (typeof ev.data !== "string") return;
+    for (const fn of listeners.message) fn(ev.data);
+  });
+  dc.addEventListener("close", () => {
+    if (closed) return;
+    closed = true;
+    for (const fn of listeners.close) fn();
+  });
+  return {
+    get isOpen() {
+      return !closed && dc.readyState === "open";
+    },
+    send(payload) {
+      if (closed || dc.readyState !== "open") {
+        throw new Error(`PeerChannel not open (readyState: ${dc.readyState})`);
+      }
+      dc.send(payload);
+    },
+    on(event, listener) {
+      if (event === "message") {
+        listeners.message.add(listener);
+        return () => listeners.message.delete(listener);
+      }
+      listeners.close.add(listener);
+      return () => listeners.close.delete(listener);
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      try {
+        dc.close();
+      } catch {
+      }
+      for (const fn of listeners.close) fn();
+    }
+  };
+}
+
+// src/rpc.ts
+function createRpcClient(channel, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 3e4;
+  const pending = /* @__PURE__ */ new Map();
+  let counter = 0;
+  const offMessage = channel.on("message", (payload) => {
+    let msg;
+    try {
+      msg = JSON.parse(payload);
+    } catch {
+      return;
+    }
+    if (msg.t !== "res") return;
+    const entry = pending.get(msg.id);
+    if (!entry) return;
+    clearTimeout(entry.timer);
+    pending.delete(msg.id);
+    if (msg.ok) {
+      entry.resolve(msg.result);
+    } else {
+      const e = msg.error ?? { name: "Error", message: "unknown remote error" };
+      const err = new Error(e.message);
+      err.name = e.name;
+      if (typeof e.version === "number") {
+        ;
+        err.version = e.version;
+      }
+      entry.reject(err);
+    }
+  });
+  const offClose = channel.on("close", () => {
+    for (const [, entry] of pending) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error("PeerChannel closed before response"));
+    }
+    pending.clear();
+  });
+  return {
+    async call(method, args) {
+      const id = `${Date.now().toString(36)}-${(++counter).toString(36)}`;
+      const req = { t: "req", id, method, args };
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error(`RPC ${method} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        pending.set(id, {
+          resolve,
+          reject,
+          timer
+        });
+        try {
+          channel.send(JSON.stringify(req));
+        } catch (err) {
+          clearTimeout(timer);
+          pending.delete(id);
+          reject(err instanceof Error ? err : new Error(String(err)));
+        }
+      });
+    },
+    dispose() {
+      offMessage();
+      offClose();
+      for (const [, entry] of pending) {
+        clearTimeout(entry.timer);
+        entry.reject(new Error("RPC client disposed"));
+      }
+      pending.clear();
+    }
+  };
+}
+function serveRpc(channel, handler) {
+  async function handle(payload) {
+    let msg;
+    try {
+      msg = JSON.parse(payload);
+    } catch {
+      return;
+    }
+    if (msg.t !== "req") return;
+    let response;
+    try {
+      const result = await handler(msg.method, msg.args);
+      response = { t: "res", id: msg.id, ok: true, result };
+    } catch (err) {
+      const e = err;
+      response = {
+        t: "res",
+        id: msg.id,
+        ok: false,
+        error: {
+          name: e.name ?? "Error",
+          message: e.message ?? String(err),
+          ...typeof e.version === "number" && { version: e.version }
+        }
+      };
+    }
+    if (!channel.isOpen) return;
+    try {
+      channel.send(JSON.stringify(response));
+    } catch {
+    }
+  }
+  const offMessage = channel.on("message", (payload) => {
+    void handle(payload);
+  });
+  return () => offMessage();
+}
+
+// src/peer-store.ts
+var import_hub = require("@noy-db/hub");
+function peerStore(opts) {
+  const rpc = createRpcClient(opts.channel, { timeoutMs: opts.timeoutMs ?? 3e4 });
+  async function call(method, args) {
+    try {
+      return await rpc.call(method, args);
+    } catch (err) {
+      const e = err;
+      if (e.name === "ConflictError" && typeof e.version === "number") {
+        throw new import_hub.ConflictError(e.version, e.message);
+      }
+      throw err;
+    }
+  }
+  return {
+    name: opts.name ?? "by-peer",
+    async get(vault, collection, id) {
+      return call("get", [vault, collection, id]);
+    },
+    async put(vault, collection, id, envelope, expectedVersion) {
+      await call("put", [vault, collection, id, envelope, expectedVersion]);
+    },
+    async delete(vault, collection, id) {
+      await call("delete", [vault, collection, id]);
+    },
+    async list(vault, collection) {
+      return call("list", [vault, collection]);
+    },
+    async loadAll(vault) {
+      return call("loadAll", [vault]);
+    },
+    async saveAll(vault, data) {
+      await call("saveAll", [vault, data]);
+    },
+    async ping() {
+      try {
+        return await call("ping", []);
+      } catch {
+        return false;
+      }
+    },
+    dispose() {
+      rpc.dispose();
+    }
+  };
+}
+
+// src/serve.ts
+var CORE_METHODS = /* @__PURE__ */ new Set([
+  "get",
+  "put",
+  "delete",
+  "list",
+  "loadAll",
+  "saveAll",
+  "ping",
+  "listSince",
+  "listPage",
+  "listVaults"
+]);
+function servePeerStore(opts) {
+  if (!opts.leaderElection) {
+    return startServing(opts);
+  }
+  return startServingWithLeaderElection(opts);
+}
+function startServing(opts) {
+  const { store, channel, allow } = opts;
+  return serveRpc(channel, async (method, args) => {
+    if (!CORE_METHODS.has(method)) {
+      throw new Error(`Unknown RPC method: ${method}`);
+    }
+    if (allow && !allow.has(method)) {
+      throw new Error(`Method not allowed: ${method}`);
+    }
+    switch (method) {
+      case "get": {
+        const [vault, collection, id] = args;
+        return store.get(vault, collection, id);
+      }
+      case "put": {
+        const [vault, collection, id, envelope, expectedVersion] = args;
+        await store.put(vault, collection, id, envelope, expectedVersion);
+        return null;
+      }
+      case "delete": {
+        const [vault, collection, id] = args;
+        await store.delete(vault, collection, id);
+        return null;
+      }
+      case "list": {
+        const [vault, collection] = args;
+        return store.list(vault, collection);
+      }
+      case "loadAll": {
+        const [vault] = args;
+        return store.loadAll(vault);
+      }
+      case "saveAll": {
+        const [vault, data] = args;
+        await store.saveAll(vault, data);
+        return null;
+      }
+      case "ping": {
+        if (!store.ping) return true;
+        return store.ping();
+      }
+      case "listSince": {
+        if (!store.listSince) throw new Error("listSince not supported by remote store");
+        const [vault, collection, since] = args;
+        return store.listSince(vault, collection, since);
+      }
+      case "listPage": {
+        if (!store.listPage) throw new Error("listPage not supported by remote store");
+        const [vault, collection, cursor, limit] = args;
+        return store.listPage(vault, collection, cursor, limit);
+      }
+      case "listVaults": {
+        if (!store.listVaults) throw new Error("listVaults not supported by remote store");
+        return store.listVaults();
+      }
+    }
+    throw new Error(`Unhandled method: ${method}`);
+  });
+}
+function startServingWithLeaderElection(opts) {
+  const leader = opts.leaderElection;
+  const locks = leader.locks ?? getDefaultLocks();
+  const ac = new AbortController();
+  let stopServing = null;
+  let releaseLock = null;
+  let disposed = false;
+  void locks.request(leader.lockName, { mode: "exclusive", signal: ac.signal }, () => {
+    if (disposed) return Promise.resolve();
+    stopServing = startServing(opts);
+    return new Promise((resolve) => {
+      releaseLock = resolve;
+    });
+  }).catch((err) => {
+    if (err?.name === "AbortError") return;
+    queueMicrotask(() => {
+      throw err;
+    });
+  });
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    if (stopServing) {
+      stopServing();
+      stopServing = null;
+    }
+    if (releaseLock) {
+      releaseLock();
+      releaseLock = null;
+    } else {
+      ac.abort();
+    }
+  };
+}
+function getDefaultLocks() {
+  const nav = globalThis.navigator;
+  if (nav && nav.locks) return nav.locks;
+  throw new Error(
+    "leaderElection requires the Web Locks API (navigator.locks). Use Chrome 69+, Firefox 96+, Safari 15.4+, or pass `leaderElection.locks: <stub>` for tests / non-browser hosts."
+  );
+}
+
+// src/webrtc.ts
+function requireRTC() {
+  const g = globalThis;
+  if (!g.RTCPeerConnection) {
+    throw new Error(
+      "[@noy-db/by-peer] globalThis.RTCPeerConnection is undefined \u2014 use this module in a browser, or polyfill with @roamhq/wrtc in Node"
+    );
+  }
+  return g.RTCPeerConnection;
+}
+async function createOffer(opts = {}) {
+  const RTC = requireRTC();
+  const pc = new RTC({
+    ...opts.iceServers && { iceServers: opts.iceServers }
+  });
+  const dc = pc.createDataChannel(opts.label ?? "noydb", {
+    ordered: true
+  });
+  const channelPromise = new Promise((resolve, reject) => {
+    dc.addEventListener("open", () => resolve(fromDataChannel(dc)));
+    dc.addEventListener("error", () => reject(new Error("DataChannel error")));
+  });
+  const offer = await pc.createOffer();
+  await pc.setLocalDescription(offer);
+  await waitForIceComplete(pc);
+  return {
+    offer: pc.localDescription ?? offer,
+    connection: pc,
+    channel: channelPromise,
+    async accept(answer) {
+      await pc.setRemoteDescription(answer);
+    }
+  };
+}
+async function acceptOffer(offer, opts = {}) {
+  const RTC = requireRTC();
+  const pc = new RTC({
+    ...opts.iceServers && { iceServers: opts.iceServers }
+  });
+  const channelPromise = new Promise((resolve, reject) => {
+    pc.addEventListener("datachannel", (ev) => {
+      const dc = ev.channel;
+      if (dc.readyState === "open") {
+        resolve(fromDataChannel(dc));
+      } else {
+        dc.addEventListener("open", () => resolve(fromDataChannel(dc)));
+        dc.addEventListener("error", () => reject(new Error("DataChannel error")));
+      }
+    });
+  });
+  await pc.setRemoteDescription(offer);
+  const answer = await pc.createAnswer();
+  await pc.setLocalDescription(answer);
+  await waitForIceComplete(pc);
+  return {
+    answer: pc.localDescription ?? answer,
+    connection: pc,
+    channel: channelPromise
+  };
+}
+function waitForIceComplete(pc) {
+  if (pc.iceGatheringState === "complete") return Promise.resolve();
+  return new Promise((resolve) => {
+    const check = () => {
+      if (pc.iceGatheringState === "complete") {
+        pc.removeEventListener("icegatheringstatechange", check);
+        resolve();
+      }
+    };
+    pc.addEventListener("icegatheringstatechange", check);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  acceptOffer,
+  createOffer,
+  createRpcClient,
+  fromDataChannel,
+  pairInMemory,
+  peerStore,
+  servePeerStore,
+  serveRpc
+});
+//# sourceMappingURL=index.cjs.map