From a8f0c645dcb1f775f574c13f41cc460d7ccacbb5 Mon Sep 17 00:00:00 2001 From: EnRaiha <15997552+EnRaiha@users.noreply.github.com> Date: Wed, 23 Sep 2026 07:09:56 +0800 Subject: [PATCH 1/2] docs: fix the WASM examples, the PromQL paths, and six dangling links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The WASM pages documented an API that does not exist: `NodeDB` / `NodeDB.open(name)`, `db.exec`, `db.query`, `db.loadSnapshot`, and a "static snapshots" workflow with no implementation anywhere in Lite. The example now uses the real surface — `init`, `NodeDbLiteWasm.openInMemory`, `executeSql`, `vectorInsert`, `vectorSearch` — and the snapshot paragraph is gone. The limitations list gains the real persistence story (`openPersistent*` through `run_opfs_worker`) and the status line stops claiming all eight engines work on WASM today. `routes/promql/mod.rs` placed the API at `/obsv/api`; the registered paths are `/v1/obsv/api/v1/*`, so a Grafana data source pointed at the documented URL 404s. `docs/lite.md` and `docs/cli.md` fill six inbound links that pointed at nothing. `cli.md` carries the binary's real usage text — there is no `ndb` client — and `lite.md` states what Lite shares, what it syncs, and where parity is unverified. The three wrong relative paths (`../bitemporal.md`, `../wasm.md` from query-language, and `security/encryption.md`'s `protocols.md#tls`) resolve. Evidence: link scan over `docs/` reports zero dangling targets. --- docs/ai/on-device.md | 21 ++++----- docs/cli.md | 46 +++++++++++++++++++ docs/lite.md | 40 ++++++++++++++++ docs/query-language.md | 6 +-- docs/security/encryption.md | 2 +- docs/wasm.md | 6 ++- .../control/server/http/routes/promql/mod.rs | 4 +- 7 files changed, 106 insertions(+), 19 deletions(-) create mode 100644 docs/cli.md create mode 100644 docs/lite.md diff --git a/docs/ai/on-device.md b/docs/ai/on-device.md index 0ad9e1fd7..d130e47ca 100644 --- a/docs/ai/on-device.md +++ b/docs/ai/on-device.md @@ -106,25 +106,26 @@ NodeDB-Lite compiles to WebAssembly. Run semantic search in the browser with no ```javascript // Load NodeDB-Lite WASM module -import { NodeDB } from "nodedb-lite-wasm"; +import init, { NodeDbLiteWasm } from "nodedb-lite-wasm"; -const db = await NodeDB.open("my-search-app"); +await init(); + +const db = await NodeDbLiteWasm.openInMemory(); // Create collection and index -await db.exec(`CREATE COLLECTION docs TYPE document`); -await db.exec( +await db.executeSql(`CREATE COLLECTION docs TYPE document`); +await db.executeSql( `CREATE VECTOR INDEX idx_docs_embedding ON docs METRIC cosine DIM 384`, ); -// Load a static snapshot (pre-built dataset) -await db.loadSnapshot("/data/docs-snapshot.ndb"); +// Index a vector +await db.vectorInsert("docs", "doc-1", embedding); // Search in the browser — no backend needed -const results = await db.query( - `SEARCH docs USING VECTOR(embedding, ARRAY[${queryVector.join(",")}], 10)`, -); +const results = await db.vectorSearch("docs", queryVector, 10); ``` + **Use cases:** - Documentation search widgets (embed in any website) @@ -132,8 +133,6 @@ const results = await db.query( - Privacy-sensitive search (data never leaves the browser) - Offline-capable progressive web apps -**Static snapshots:** Pre-build a dataset on your server, export as a snapshot file, host on a CDN. The WASM module loads the snapshot at startup — no live database connection needed. - ## Privacy Model All data stays on the device by default. Sync is opt-in and explicit. diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 000000000..492dcdbfa --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,46 @@ +# CLI + +The server binary is `nodedb`. There is no separate client binary: query clients speak pgwire, +HTTP, the native protocol, or RESP — see [Protocols](protocols.md). + +``` +nodedb — NodeDB server + operator tooling + +USAGE: + nodedb [CONFIG_FILE] Run the server (default mode) + nodedb --version Print version and exit + nodedb regen-certs --data-dir D --node-id N + Reissue this node's cert under the existing CA + nodedb rotate-ca --stage --data-dir D Generate a new CA, write to ca.d/, emit staged bundle + nodedb rotate-ca --finalize --remove FP Ask the running node to remove CA with fingerprint FP + nodedb join-token --create --data-dir D --for-node N [--ttl 10m] + Emit a one-time HMAC token for a joining node + nodedb healthcheck [--port N] Probe local HTTP /health (exit 0=healthy, 1=unhealthy) + nodedb help Print this message +``` + +Running with no argument reads the default config path; `nodedb /etc/nodedb.toml` reads that +file instead. Every flag above is parsed by hand — the binary deliberately does not pull in a +CLI framework. + +## Reserved verbs + +These are parsed but not implemented; each exits with the usage message: + +``` +nodedb migrate Schema/data migration +nodedb backup Online backup +nodedb restore Restore from backup +nodedb verify Consistency check +nodedb repair Repair corrupted data +nodedb dump Logical export +nodedb fsck Filesystem consistency check +``` + +Online backup and restore are driven from SQL instead today (`BACKUP TENANT`, `RESTORE TENANT`). + +## Health probe + +`nodedb healthcheck` exits `0` when the local HTTP endpoint answers healthy and `1` otherwise, +which is the intended Kubernetes liveness/readiness probe. The endpoint itself is the HTTP +`/healthz` family described in [Architecture](architecture.md). diff --git a/docs/lite.md b/docs/lite.md new file mode 100644 index 000000000..07da3ce86 --- /dev/null +++ b/docs/lite.md @@ -0,0 +1,40 @@ +# NodeDB-Lite + +NodeDB-Lite is the embedded build of NodeDB. It runs the same query surface and storage engines +inside your process instead of as a server, and it lives in its own repository — +[NodeDB-Lab/nodedb-lite](https://github.com/NodeDB-Lab/nodedb-lite) — because it ships on a +different cadence and targets platforms the server does not: mobile, desktop, and WASM. + +## What is shared + +Lite consumes the same crates the server compiles: `nodedb-array`, `nodedb-columnar`, +`nodedb-crdt`, `nodedb-fts`, `nodedb-graph`, `nodedb-spatial`, `nodedb-strict`, `nodedb-vector`, +plus the cross-cutting `nodedb-types`, `nodedb-physical`, `nodedb-mem`, `nodedb-query` and +`nodedb-codec`. An engine fix lands in both builds. + +The engines without a shared crate — document, KV, timeseries, sparse vectors, HTAP — are +implemented once per repository. Their behaviour is not compared by a shared test suite today; +treat cross-build parity there as unverified. + +## Sync + +Lite syncs to an Origin cluster over the Sync protocol (WebSocket), so an embedded client writes +locally and replicates in the background. The protocol itself is described in +[Protocols](protocols.md); the offline patterns are in +[Offline sync patterns](offline-sync-patterns.md). + +Sync coverage differs by engine: array has a dedicated subtree, the columnar family (columnar, +timeseries, spatial), vector and FTS have dedicated outbound paths, document/KV/CRDT/strict use +the generic delta path, and graph plus sparse vectors have no sync path yet. + +## WASM + +Lite compiles to WebAssembly for browsers and Node.js under the `nodedb-lite-wasm` crate — see +[WASM Build and Deployment](wasm.md). Lite-WASM is a client only: it never acts as a Raft member +or a vShard host. + +## Where to go next + +- [Getting Started](getting-started.md) — the server path +- [WASM Build and Deployment](wasm.md) — building and running Lite in a browser +- [Protocols](protocols.md) — the Sync protocol Lite speaks diff --git a/docs/query-language.md b/docs/query-language.md index e89590b76..4c3dbb623 100644 --- a/docs/query-language.md +++ b/docs/query-language.md @@ -1043,7 +1043,7 @@ AS OF VALID TIME 1700000000000; Time values are milliseconds since Unix epoch. For current time, use `extract(epoch from now()) * 1000` or `(SELECT extract(epoch from now() at time zone 'utc') * 1000)`. -See [Bitemporal Queries](../bitemporal.md) for detailed use cases. +See [Bitemporal Queries](bitemporal.md) for detailed use cases. ## Transactions @@ -1299,7 +1299,7 @@ SHOW USERS; - [Getting Started](getting-started.md) — First queries walkthrough - [Architecture](architecture.md) — How the three-plane execution model works - Engine guides: [Vectors](vectors.md) | [Graph](graph.md) | [Documents](documents.md) | [KV](kv.md) | [Timeseries](timeseries.md) | [Spatial](spatial.md) | [Full-Text](full-text-search.md) | [Array](array.md) -- [Bitemporal Queries](../bitemporal.md) — System time and valid time semantics -- [WASM](../wasm.md) — Browser and Node.js deployment +- [Bitemporal Queries](bitemporal.md) — System time and valid time semantics +- [WASM](wasm.md) — Browser and Node.js deployment [Back to docs](README.md) diff --git a/docs/security/encryption.md b/docs/security/encryption.md index 70dd02ba5..5f309a67a 100644 --- a/docs/security/encryption.md +++ b/docs/security/encryption.md @@ -161,7 +161,7 @@ or be stored in shared object storage without additional encryption. ## Encryption in Transit -See [protocols.md — TLS](protocols.md#tls) for wire encryption +See [protocols.md — TLS](../protocols.md#tls) for wire encryption configuration. All five listeners support TLS. Plaintext is the default and is appropriate only for local development. diff --git a/docs/wasm.md b/docs/wasm.md index 4a718edfc..cbd4e2160 100644 --- a/docs/wasm.md +++ b/docs/wasm.md @@ -4,7 +4,9 @@ NodeDB-Lite compiles to WebAssembly and exposes the same `NodeDb` trait you use in native Lite. To talk to an Origin cluster from the browser, use Lite-WASM locally and replicate via CRDT sync over WebSocket — never run Origin in the browser. -**Status: Experimental.** Lite-WASM support is feature-complete for all eight engines. Testing and CI integration are ongoing; treat the build as preview-quality. Report issues via GitHub. +**Status: Experimental.** All eight engines are implemented for the WASM build, but treat it +as preview-quality: CI integration is ongoing, and the array engine's first write fails until the +commit-clock fix lands in the storage layer. Report issues via GitHub. ## Building for WASM @@ -191,7 +193,7 @@ See [NodeDB-Lite](https://github.com/NodeDB-Lab/nodedb-lite) for full CRDT sync ## Limitations and Known Issues - **Lite only — no Origin in WASM.** The distributed Origin server is not a WASM target. Browser/Node clients run Lite-WASM locally and sync to a separately-deployed Origin cluster over WebSocket -- **No file persistence** — WASM runs in-memory only. For persistence, use `localStorage` or IndexedDB via a wrapper +- **Persistence needs the OPFS worker** — `openPersistent*` keeps data in the Origin Private File System through `run_opfs_worker`. The default constructors (`open`, `openInMemory`) are in-memory only - **Single-threaded** — no thread-per-core, no parallel execution; everything runs on the JS/WASM main thread - **No io_uring, no native sockets** — storage and network I/O go through JS host APIs (`fetch`, IndexedDB, WebSocket); there is no NVMe path - **No cluster role** — Lite-WASM is a client/edge node only. It cannot act as a Raft member or vShard host diff --git a/nodedb/src/control/server/http/routes/promql/mod.rs b/nodedb/src/control/server/http/routes/promql/mod.rs index a9f2dc7c3..b8a2db227 100644 --- a/nodedb/src/control/server/http/routes/promql/mod.rs +++ b/nodedb/src/control/server/http/routes/promql/mod.rs @@ -1,8 +1,8 @@ // SPDX-License-Identifier: BUSL-1.1 -//! Prometheus-compatible PromQL HTTP API at `/obsv/api/v1/*`. +//! Prometheus-compatible PromQL HTTP API at `/v1/obsv/api/v1/*`. //! -//! Grafana data source URL: `http://nodedb:6480/obsv/api` +//! Grafana data source URL: `http://nodedb:6480/v1/obsv/api` pub mod buildinfo; pub mod handlers; From d1d6413ab6fdfc7dae39d13c749be818acdf96b8 Mon Sep 17 00:00:00 2001 From: EnRaiha <15997552+EnRaiha@users.noreply.github.com> Date: Wed, 23 Sep 2026 07:12:40 +0800 Subject: [PATCH 2/2] docs: drop the phantom CONSISTENCY clause and correct the default data dir MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cross-checking this doc set against `nodedb-docs` turned up two claims that both sets get wrong. `CONSISTENCY = '...'` is not a SQL clause: `bounded_staleness` appears only in the session-parameter parser (`set_validation.rs`, `read_consistency.rs`), and the mirror read path reads the level from the session. The example now sets it with `SET default_read_consistency` first. The default data directory follows platform conventions (`$XDG_DATA_HOME/nodedb`, `~/Library/Application Support/nodedb`, `%LOCALAPPDATA%\nodedb\data`), not `~/.nodedb/data`. Evidence: `grep -rn "nodedb/data\|CONSISTENCY=" docs/*.md` → no hits; the accepted staleness grammar is `bounded_staleness:` (`read_consistency.rs:28-45`). --- docs/databases.md | 5 ++++- docs/getting-started.md | 4 ++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/databases.md b/docs/databases.md index 131cc8371..03abe3533 100644 --- a/docs/databases.md +++ b/docs/databases.md @@ -242,8 +242,11 @@ Uses: - `Strong` — returns `STALE_READ_NOT_LEADER` with source endpoint hint - `Eventual` — served immediately +The level is a session setting, not a query clause: + ```sql -SELECT * FROM orders CONSISTENCY='bounded_staleness'; -- served from mirror +SET default_read_consistency = 'bounded_staleness:5s'; -- served from the mirror +SELECT * FROM orders; ``` ### Bootstrap and Lag diff --git a/docs/getting-started.md b/docs/getting-started.md index 7f2ab69f9..5026a9c8b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -107,7 +107,7 @@ tar -xzf nodedb.tar.gz # Optional: install system-wide sudo mv nodedb /usr/local/bin/ -# Run with all defaults (data goes to ~/.nodedb/data) +# Run with all defaults (Linux data dir: ~/.local/share/nodedb) nodedb ``` @@ -257,7 +257,7 @@ port named — the server never comes up missing a protocol. | `ports.sync` | `NODEDB_PORT_SYNC` | `9090` | | `ports.resp` | `NODEDB_PORT_RESP` | disabled | | `ports.ilp` | `NODEDB_PORT_ILP` | disabled | -| `data_dir` | `NODEDB_DATA_DIR` | `~/.nodedb/data` (binary), `/var/lib/nodedb` (Docker) | +| `data_dir` | `NODEDB_DATA_DIR` | `$XDG_DATA_HOME/nodedb` or `~/.local/share/nodedb` (Linux), `~/Library/Application Support/nodedb` (macOS), `%LOCALAPPDATA%\nodedb\data` (Windows); `/var/lib/nodedb` (Docker) | | `memory_limit` | `NODEDB_MEMORY_LIMIT` | `1 GiB` | | `data_plane_cores` | `NODEDB_DATA_PLANE_CORES` | CPUs - 1 | | `max_connections` | `NODEDB_MAX_CONNECTIONS` | `4096` |