nedb-engine 2.6.2__tar.gz → 2.7.0__tar.gz

{nedb_engine-2.6.2 → nedb_engine-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nedb-engine
-Version: 2.6.2
+Version: 2.7.0
 Summary: NEDB — a versioned, self-compressing, time-traveling embedded database (replay-protected, idempotent, relational, searchable) with durable AOF persistence and a server daemon (nedbd).
 Project-URL: Homepage, https://github.com/aiassistsecure/nedb
 Project-URL: Repository, https://github.com/aiassistsecure/nedb
@@ -176,6 +176,50 @@ MongoClient(db)["users"].find({"status": "active"}).sort("age", -1).to_list()
 
 ---
 
+## Official Python client — talk to nedbd over HTTP
+
+Running the daemon? `nedb.client.NedbClient` is the official client for its
+HTTP API — extracted from the battle-tested clients that ran a production
+Redis→NEDB mainnet migration, speaking the full route surface: queries,
+atomic CAS transactions, TTL, indexes, relations, Merkle proofs, and the
+Mongo-compat endpoint. Env-var defaults (`NEDBD_URL`, `NEDBD_TOKEN`,
+`NEDB_DB`) mirror the daemon's own.
+
+```python
+from nedb import NedbClient, PreconditionFailed, op_put
+
+c = NedbClient("http://127.0.0.1:7070", db="app", token="s3cret")
+c.ensure_database()
+
+c.put("users", "u1", {"id": "u1", "email": "a@b.c"}, idem="signup-u1")
+c.query('FROM users WHERE email = "a@b.c"')      # full NQL rides through
+c.query("FROM users AS OF 41")                    # time-travel included
+
+# Atomic all-or-nothing transaction with engine-checked preconditions —
+# the primitive that replaces Redis Lua scripts (if_seq: N = CAS, -1 = create-once)
+doc = c.get_doc("users", "u1")                    # docs carry _seq
+c.tx([op_put("users", "u1", {**doc, "plan": "pro"}, if_seq=doc["_seq"])])
+
+# Contested writes: retry ONLY on PreconditionFailed, capped backoff
+def bump():
+    d = c.get_doc("counters", "hits") or {"n": 0}
+    return c.tx([op_put("counters", "hits", {"n": d.get("n", 0) + 1},
+                        if_seq=d.get("_seq", -1))])
+c.cas_retry(bump)
+
+# Integrity, verifiable WITHOUT trusting the server
+proof = c.proof(c.log(limit=1)[0]["hash"])
+from nedb import verify_proof; verify_proof(proof)  # -> True, locally
+```
+
+A CAS miss raises the **same `PreconditionFailed`** (with the same
+`.failures` shape) the embedded engine raises — code written against
+`NEDB.tx` ports to the HTTP client without changing its except-clauses.
+Typed errors throughout: `NedbAuthError`, `NedbNotFound`, `NedbBadRequest`,
+`NedbConflict`, `CasExhausted`.
+
+---
+
 ## Redis layer-2 — wrap_redis()
 
 Already running on Redis? Wrap your connection in one line and gain NEDB features *alongside* your existing Redis app — no migration required.

{nedb_engine-2.6.2 → nedb_engine-2.7.0}/README.md

@@ -155,6 +155,50 @@ MongoClient(db)["users"].find({"status": "active"}).sort("age", -1).to_list()
 
 ---
 
+## Official Python client — talk to nedbd over HTTP
+
+Running the daemon? `nedb.client.NedbClient` is the official client for its
+HTTP API — extracted from the battle-tested clients that ran a production
+Redis→NEDB mainnet migration, speaking the full route surface: queries,
+atomic CAS transactions, TTL, indexes, relations, Merkle proofs, and the
+Mongo-compat endpoint. Env-var defaults (`NEDBD_URL`, `NEDBD_TOKEN`,
+`NEDB_DB`) mirror the daemon's own.
+
+```python
+from nedb import NedbClient, PreconditionFailed, op_put
+
+c = NedbClient("http://127.0.0.1:7070", db="app", token="s3cret")
+c.ensure_database()
+
+c.put("users", "u1", {"id": "u1", "email": "a@b.c"}, idem="signup-u1")
+c.query('FROM users WHERE email = "a@b.c"')      # full NQL rides through
+c.query("FROM users AS OF 41")                    # time-travel included
+
+# Atomic all-or-nothing transaction with engine-checked preconditions —
+# the primitive that replaces Redis Lua scripts (if_seq: N = CAS, -1 = create-once)
+doc = c.get_doc("users", "u1")                    # docs carry _seq
+c.tx([op_put("users", "u1", {**doc, "plan": "pro"}, if_seq=doc["_seq"])])
+
+# Contested writes: retry ONLY on PreconditionFailed, capped backoff
+def bump():
+    d = c.get_doc("counters", "hits") or {"n": 0}
+    return c.tx([op_put("counters", "hits", {"n": d.get("n", 0) + 1},
+                        if_seq=d.get("_seq", -1))])
+c.cas_retry(bump)
+
+# Integrity, verifiable WITHOUT trusting the server
+proof = c.proof(c.log(limit=1)[0]["hash"])
+from nedb import verify_proof; verify_proof(proof)  # -> True, locally
+```
+
+A CAS miss raises the **same `PreconditionFailed`** (with the same
+`.failures` shape) the embedded engine raises — code written against
+`NEDB.tx` ports to the HTTP client without changing its except-clauses.
+Typed errors throughout: `NedbAuthError`, `NedbNotFound`, `NedbBadRequest`,
+`NedbConflict`, `CasExhausted`.
+
+---
+
 ## Redis layer-2 — wrap_redis()
 
 Already running on Redis? Wrap your connection in one line and gain NEDB features *alongside* your existing Redis app — no migration required.

{nedb_engine-2.6.2 → nedb_engine-2.7.0}/pyproject.toml

@@ -10,7 +10,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nedb-engine"
-version = "2.6.2"
+version = "2.7.0"
 description = "NEDB — a versioned, self-compressing, time-traveling embedded database (replay-protected, idempotent, relational, searchable) with durable AOF persistence and a server daemon (nedbd)."
 readme = "README.md"
 requires-python = ">=3.8"

{nedb_engine-2.6.2 → nedb_engine-2.7.0}/python/nedb/__init__.py

@@ -18,6 +18,11 @@ from __future__ import annotations
 
 from .engine import NEDB, PreconditionFailed
 from .log import Op, OpLog, ReplayError
+from .client import (
+    NedbClient, op_put, op_del,
+    NedbError, NedbAuthError, NedbNotFound, NedbBadRequest,
+    NedbConflict, CasExhausted,
+)
 from .query import Query, parse_nql
 from .snapshot import save_snapshot, load_snapshot
 from .crypto import resolve_tmk, rewrap_dek
@@ -89,4 +94,4 @@ __all__ = [
     "verify_proof", "fold_head",
     "_native", "__has_native__",
 ]
-__version__ = "2.6.2"
+__version__ = "2.7.0"

nedb_engine-2.7.0/python/nedb/client.py

@@ -0,0 +1,411 @@
+"""
+NedbClient — the official Python client for nedbd's HTTP API.
+
+Extracted from production: this client is the promotion of the two
+battle-tested hand-rolled clients that ran the AiAS mainnet migration
+(the storage adapter's ``NedbdClient`` and the backfill's ``Nedbd``),
+unified and extended to speak the daemon's full route surface. Design
+choices carry their scars:
+
+  * **Typed errors, one vocabulary.** A CAS miss raises the SAME
+    :class:`~nedb.engine.PreconditionFailed` the embedded engine raises,
+    with the same ``.failures`` shape — code written against ``NEDB.tx``
+    ports to the HTTP client without changing its except-clauses.
+  * **No transparent write retries.** Writes are only safe to repeat when
+    the caller supplies an ``idem`` key (the daemon dedupes replays into
+    silent no-ops), so the client never retries on its own. The one
+    sanctioned loop is :meth:`NedbClient.cas_retry`, which retries ONLY
+    on ``PreconditionFailed`` with capped exponential backoff — the same
+    discipline the AiAS Lua-parity guards shipped with.
+  * **Env-var defaults** (``NEDBD_URL``, ``NEDBD_TOKEN``, ``NEDB_DB``)
+    mirror the daemon's own configuration surface, so
+    ``NedbClient()`` with no arguments does the right thing next to a
+    conventionally-configured nedbd.
+
+Quick start::
+
+    from nedb.client import NedbClient, op_put
+
+    c = NedbClient("http://127.0.0.1:7070", db="app")
+    c.ensure_database()
+    c.put("users", "u1", {"id": "u1", "email": "a@b.c"})
+    c.query('FROM users WHERE email = "a@b.c"')
+
+    # atomic CAS transaction — all-or-nothing, engine-checked
+    doc = c.get_doc("users", "u1")
+    c.tx([op_put("users", "u1", {**doc, "plan": "pro"},
+                 if_seq=doc["_seq"])])
+
+    # contested writes: retry only on precondition failures
+    def bump():
+        d = c.get_doc("counters", "hits") or {"n": 0}
+        return c.tx([op_put("counters", "hits", {"n": int(d.get("n", 0)) + 1},
+                            if_seq=d.get("_seq", -1))])
+    c.cas_retry(bump)
+
+Not yet wrapped (use :meth:`NedbClient.request` directly if needed):
+the files API (``POST/GET …/files``) — its tier/version semantics get a
+dedicated helper in a follow-up release.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple, TypeVar
+
+from .engine import PreconditionFailed  # one exception type, both transports
+
+__all__ = [
+    "NedbClient", "op_put", "op_del",
+    "NedbError", "NedbAuthError", "NedbNotFound", "NedbBadRequest",
+    "NedbConflict", "CasExhausted", "PreconditionFailed",
+]
+
+T = TypeVar("T")
+
+DEFAULT_URL = "http://localhost:7070"
+DEFAULT_TIMEOUT_S = 30.0
+CAS_MAX_RETRIES = 16       # matches the AiAS guard budget
+CAS_BACKOFF_BASE_S = 0.01  # grows 1.5x per attempt …
+CAS_BACKOFF_CAP_S = 0.2    # … capped here
+
+
+# ── errors ───────────────────────────────────────────────────────────────────
+
+class NedbError(RuntimeError):
+    """Base error for daemon interactions. ``status`` is the HTTP status
+    (``None`` for transport failures); ``payload`` is the parsed error body."""
+
+    def __init__(self, message: str, status: Optional[int] = None,
+                 payload: Optional[dict] = None):
+        super().__init__(message)
+        self.status = status
+        self.payload = payload or {}
+
+
+class NedbAuthError(NedbError):
+    """401/403 — missing or invalid bearer token."""
+
+
+class NedbNotFound(NedbError):
+    """404 — unknown database, route, or op hash."""
+
+
+class NedbBadRequest(NedbError):
+    """400 — malformed request or NQL error."""
+
+
+class NedbConflict(NedbError):
+    """409 that is NOT a CAS precondition failure — e.g. a nonce replay
+    (``ReplayError`` server-side). Preconditions raise
+    :class:`~nedb.engine.PreconditionFailed` instead."""
+
+
+class CasExhausted(NedbError):
+    """:meth:`NedbClient.cas_retry` lost the race ``max_retries`` times in a
+    row. At sane write volumes this indicates a stuck loop or a hot-doc
+    pathology, not load."""
+
+
+# ── tx op builders ───────────────────────────────────────────────────────────
+
+def op_put(coll: str, doc_id: str, doc: dict, *,
+           if_seq: Optional[int] = None,
+           ttl_s: Optional[float] = None,
+           caused_by: Optional[List[int]] = None,
+           evidence: Optional[str] = None,
+           confidence: Optional[float] = None,
+           valid_from: Optional[str] = None,
+           valid_to: Optional[str] = None) -> Dict[str, Any]:
+    """A ``put`` op for :meth:`NedbClient.tx`.
+
+    ``if_seq`` semantics (checked atomically across the whole tx):
+      * ``N``  — the doc's current ``_seq`` must equal N (CAS update)
+      * ``-1`` — the doc must NOT exist (create-once)
+      * ``None`` — unconditional
+    """
+    op: Dict[str, Any] = {"op": "put", "coll": coll, "id": doc_id, "doc": doc}
+    if if_seq is not None:
+        op["if_seq"] = if_seq
+    if ttl_s is not None:
+        op["ttl_s"] = ttl_s
+    if caused_by is not None:
+        op["caused_by"] = caused_by
+    if evidence is not None:
+        op["evidence"] = evidence
+    if confidence is not None:
+        op["confidence"] = confidence
+    if valid_from is not None:
+        op["valid_from"] = valid_from
+    if valid_to is not None:
+        op["valid_to"] = valid_to
+    return op
+
+
+def op_del(coll: str, doc_id: str, *,
+           if_seq: Optional[int] = None) -> Dict[str, Any]:
+    """A ``del`` op for :meth:`NedbClient.tx` (``if_seq`` as in
+    :func:`op_put`)."""
+    op: Dict[str, Any] = {"op": "del", "coll": coll, "id": doc_id}
+    if if_seq is not None:
+        op["if_seq"] = if_seq
+    return op
+
+
+# ── the client ───────────────────────────────────────────────────────────────
+
+class NedbClient:
+    """Synchronous client for one nedbd daemon, scoped to one database.
+
+    Thread-safe: holds no mutable state beyond configuration, and every
+    request is an independent HTTP call (nedbd's Sequencer provides the
+    single-committer serialization server-side).
+    """
+
+    def __init__(self, url: Optional[str] = None, db: Optional[str] = None,
+                 token: Optional[str] = None,
+                 timeout: float = DEFAULT_TIMEOUT_S,
+                 client_tag: str = "nedb-client"):
+        self.url = (url or os.getenv("NEDBD_URL", DEFAULT_URL)).rstrip("/")
+        self.db = db or os.getenv("NEDB_DB", "default")
+        self.token = token if token is not None else os.getenv("NEDBD_TOKEN")
+        self.timeout = timeout
+        self.client_tag = client_tag
+
+    # ── transport ────────────────────────────────────────────────────────────
+
+    def request(self, method: str, path: str, body: Optional[dict] = None,
+                timeout: Optional[float] = None) -> dict:
+        """Raw authenticated request. Public on purpose: routes this client
+        doesn't wrap yet stay reachable without giving up auth/error typing."""
+        req = urllib.request.Request(
+            f"{self.url}{path}",
+            data=json.dumps(body).encode() if body is not None else None,
+            method=method)
+        req.add_header("Content-Type", "application/json")
+        if self.token:
+            req.add_header("Authorization", f"Bearer {self.token}")
+        try:
+            with urllib.request.urlopen(
+                    req, timeout=self.timeout if timeout is None else timeout
+            ) as resp:
+                return json.loads(resp.read().decode())
+        except urllib.error.HTTPError as e:
+            raw = e.read().decode(errors="replace")
+            try:
+                payload = json.loads(raw)
+            except json.JSONDecodeError:
+                payload = {"error": raw[:300]}
+            self._raise_typed(e.code, payload, method, path)
+        except urllib.error.URLError as e:
+            raise NedbError(
+                f"nedbd unreachable at {self.url}: {e.reason}") from e
+
+    @staticmethod
+    def _raise_typed(status: int, payload: dict, method: str,
+                     path: str) -> None:
+        msg = str(payload.get("error") or payload)[:300]
+        if status == 409 and payload.get("error") == "precondition_failed":
+            exc = PreconditionFailed(payload.get("failures") or [])
+            exc.seq = payload.get("seq")  # server seq at rejection time
+            raise exc
+        if status in (401, 403):
+            raise NedbAuthError(msg, status, payload)
+        if status == 404:
+            raise NedbNotFound(msg, status, payload)
+        if status == 400:
+            raise NedbBadRequest(msg, status, payload)
+        if status == 409:
+            raise NedbConflict(msg, status, payload)
+        raise NedbError(f"nedbd {method} {path} -> {status}: {msg}",
+                        status, payload)
+
+    def _dbp(self, action: str = "") -> str:
+        tail = f"/{action}" if action else ""
+        return f"/v1/databases/{self.db}{tail}"
+
+    # ── server / database management ─────────────────────────────────────────
+
+    def health(self) -> dict:
+        """``GET /health`` — unauthenticated liveness + daemon version."""
+        return self.request("GET", "/health")
+
+    def wait_ready(self, timeout: float = 10.0, interval: float = 0.2) -> dict:
+        """Poll ``/health`` until the daemon answers (startup helper)."""
+        deadline = time.time() + timeout
+        last: Optional[Exception] = None
+        while time.time() < deadline:
+            try:
+                return self.health()
+            except NedbError as e:  # noqa: PERF203 — startup poll
+                last = e
+                time.sleep(interval)
+        raise NedbError(f"nedbd not ready after {timeout}s: {last}")
+
+    def databases(self) -> List[dict]:
+        return self.request("GET", "/v1/databases").get("databases", [])
+
+    def database_detail(self, name: Optional[str] = None) -> dict:
+        return self.request("GET", f"/v1/databases/{name or self.db}")
+
+    def create_database(self, name: Optional[str] = None,
+                        init: Optional[dict] = None) -> dict:
+        body: Dict[str, Any] = {"name": name or self.db}
+        if init is not None:
+            body["init"] = init
+        return self.request("POST", "/v1/databases", body)
+
+    def ensure_database(self, name: Optional[str] = None) -> bool:
+        """Create the database iff missing (idempotent). True if created."""
+        want = name or self.db
+        if want in (self.health().get("databases") or []):
+            return False
+        self.create_database(want)
+        return True
+
+    def drop_database(self, name: str) -> dict:
+        """``DELETE /v1/databases/{name}`` — destructive; the name is
+        REQUIRED (never defaults to ``self.db``) so a drop is always spelled
+        out at the call site."""
+        return self.request("DELETE", f"/v1/databases/{name}")
+
+    # ── reads ────────────────────────────────────────────────────────────────
+
+    def query(self, nql: str) -> List[dict]:
+        """Run NQL, return rows. (AS OF / VALID AS OF / TRACE / ORDER BY /
+        LIMIT / GROUP BY all ride through — the daemon owns the grammar.)"""
+        return self.query_full(nql).get("rows", [])
+
+    def query_full(self, nql: str) -> dict:
+        """Run NQL, return the full envelope ``{rows, count, seq, head}``."""
+        return self.request("POST", self._dbp("query"), {"nql": nql})
+
+    def get_doc(self, coll: str, doc_id: str) -> Optional[dict]:
+        """Fetch one doc by id (returns ``None`` when absent). Docs carry
+        ``_id`` and ``_seq`` — feed ``_seq`` to ``op_put(if_seq=…)``."""
+        if '"' in coll or '"' in str(doc_id):
+            raise NedbBadRequest(f"unquotable identifier: {coll}:{doc_id}")
+        rows = self.query(f'FROM {coll} WHERE _id = "{doc_id}"')
+        return rows[0] if rows else None
+
+    def count(self, coll: str) -> int:
+        return int(self.query_full(f"FROM {coll}").get("count", 0))
+
+    # ── writes ───────────────────────────────────────────────────────────────
+
+    def put(self, coll: str, doc_id: str, doc: dict, *,
+            idem: Optional[str] = None,
+            ttl_s: Optional[float] = None,
+            nonce: Optional[int] = None,
+            caused_by: Optional[List[int]] = None,
+            evidence: Optional[str] = None,
+            confidence: Optional[float] = None,
+            valid_from: Optional[str] = None,
+            valid_to: Optional[str] = None,
+            client: Optional[str] = None) -> dict:
+        """Single unconditional put → ``{ok, doc, seq, head}``.
+
+        ``idem`` makes the write replay-safe: the daemon dedupes a repeated
+        key into a silent no-op returning the ORIGINAL result — the property
+        the AiAS backfill's restart-safety is built on. For compare-and-set
+        preconditions use :meth:`tx` (``if_seq`` is transactional-only).
+        """
+        body: Dict[str, Any] = {"coll": coll, "id": doc_id, "doc": doc,
+                                "client": client or self.client_tag}
+        for k, v in (("idem", idem), ("ttl_s", ttl_s), ("nonce", nonce),
+                     ("caused_by", caused_by), ("evidence", evidence),
+                     ("confidence", confidence), ("valid_from", valid_from),
+                     ("valid_to", valid_to)):
+            if v is not None:
+                body[k] = v
+        return self.request("POST", self._dbp("put"), body)
+
+    def delete(self, coll: str, doc_id: str) -> dict:
+        """``DELETE …/rows/{coll}/{id}`` → ``{ok, seq, head}``."""
+        return self.request(
+            "DELETE", self._dbp(f"rows/{coll}/{doc_id}"))
+
+    def tx(self, ops: List[Dict[str, Any]], *,
+           client: Optional[str] = None) -> dict:
+        """Atomic all-or-nothing transaction (``POST …/batch``).
+
+        Validates every ``if_seq`` precondition first, then applies every op
+        inside one group-commit — the engine primitive that replaced Redis
+        Lua scripts. Raises :class:`~nedb.engine.PreconditionFailed` (with
+        ``.failures`` and ``.seq``) when any check misses; NOTHING is applied.
+        Build ops with :func:`op_put` / :func:`op_del`.
+        """
+        return self.request("POST", self._dbp("batch"),
+                            {"ops": ops, "client": client or self.client_tag})
+
+    def cas_retry(self, fn: Callable[[], T], *,
+                  max_retries: int = CAS_MAX_RETRIES,
+                  backoff_base: float = CAS_BACKOFF_BASE_S,
+                  backoff_cap: float = CAS_BACKOFF_CAP_S) -> T:
+        """Run ``fn`` (read → build ops → :meth:`tx`), retrying ONLY on
+        :class:`PreconditionFailed` with capped exponential backoff. Every
+        other error propagates untouched. This is the guard discipline from
+        the AiAS migration, packaged."""
+        for attempt in range(max_retries):
+            try:
+                return fn()
+            except PreconditionFailed:
+                if attempt == max_retries - 1:
+                    break
+                time.sleep(min(backoff_base * (1.5 ** attempt), backoff_cap))
+        raise CasExhausted(
+            f"CAS retry budget exhausted after {max_retries} attempts")
+
+    # ── indexes / relations ──────────────────────────────────────────────────
+
+    def create_index(self, coll: str, field: str, kind: str = "eq") -> dict:
+        """Idempotent server-side."""
+        return self.request("POST", self._dbp("index"),
+                            {"coll": coll, "field": field, "kind": kind})
+
+    def ensure_indexes(self, pairs: Iterable[Tuple[str, str]]) -> int:
+        n = 0
+        for coll, field in pairs:
+            self.create_index(coll, field)
+            n += 1
+        return n
+
+    def link(self, frm: str, rel: str, to: str) -> dict:
+        return self.request("POST", self._dbp("link"),
+                            {"frm": frm, "rel": rel, "to": to})
+
+    def neighbors(self, node: str, rel: str) -> List[str]:
+        return self.request("POST", self._dbp("neighbors"),
+                            {"node": node, "rel": rel}).get("nodes", [])
+
+    # ── integrity / ops ──────────────────────────────────────────────────────
+
+    def verify(self) -> dict:
+        """Recompute the hash chain server-side → ``{ok, seq, head}``."""
+        return self.request("GET", self._dbp("verify"))
+
+    def checkpoint(self) -> dict:
+        return self.request("POST", self._dbp("checkpoint"))
+
+    def sweep(self) -> int:
+        """Expire TTL'd docs now; returns the number swept."""
+        return int(self.request("POST", self._dbp("sweep")).get("swept", 0))
+
+    def log(self, limit: int = 50) -> List[dict]:
+        """Most-recent-first op log (each op carries its chain ``hash``)."""
+        return self.request(
+            "GET", self._dbp(f"log?limit={int(limit)}")).get("log", [])
+
+    def proof(self, op_hash: str) -> dict:
+        """Merkle inclusion proof for an op hash. Verify locally with
+        :func:`nedb.proof.verify_proof` — no server trust required."""
+        return self.request("POST", self._dbp("proof"), {"hash": op_hash})
+
+    def mongo(self, collection: str, op: str, **kwargs: Any) -> dict:
+        """Thin passthrough to the Mongo-compat endpoint
+        (``find/findOne/count/insertOne/…``)."""
+        return self.request("POST", self._dbp("mongo"),
+                            {"collection": collection, "op": op, **kwargs})

{nedb_engine-2.6.2 → nedb_engine-2.7.0}/python/nedb/concurrent.py

@@ -115,6 +115,11 @@ class Sequencer:
     def checkpoint(self) -> Any:
         return self._submit("checkpoint")
 
+    def sweep(self) -> Any:
+        """TTL sweep as ONE committer intent — sweep appends delete ops, so it
+        must ride the single writer, never race it from another thread."""
+        return self._submit("sweep")
+
     # ── read API: concurrent, snapshot-isolated at committed_seq ───────────────
     def query(self, nql: str) -> List[dict]:
         plan = parse_nql(nql)
@@ -216,6 +221,8 @@ class Sequencer:
             return db.checkpoint()
         if k == "tx":
             return db.tx(*intent.args, **intent.kwargs)
+        if k == "sweep":
+            return db.sweep()
         raise ValueError(f"unknown write kind: {k}")
 
     def close(self) -> None:

{nedb_engine-2.6.2 → nedb_engine-2.7.0}/python/nedb/server.py

@@ -12,6 +12,7 @@ Config (env):
   NEDBD_PORT    bind port            (default 7070)
   NEDBD_DATA    data root directory  (default ./nedb-data)
   NEDBD_TOKEN   bearer token         (optional; if set, every /v1 route requires it)
+  NEDBD_SWEEP_S TTL sweep interval s (default 30; 0 disables the sweeper)
 
 Run:
   nedbd                 # console script (pip install nedb-engine)
@@ -24,7 +25,7 @@ HTTP API (all JSON):
   GET    /v1/databases/<name>
   DELETE /v1/databases/<name>
   POST   /v1/databases/<name>/query            {nql}
-  POST   /v1/databases/<name>/put              {coll, id, doc, client?, nonce?, idem?}
+  POST   /v1/databases/<name>/put              {coll, id, doc, client?, nonce?, idem?, ttl_s?}
   POST   /v1/databases/<name>/index            {coll, field, kind}
   POST   /v1/databases/<name>/link             {frm, rel, to}
   DELETE /v1/databases/<name>/rows/<coll>/<id>
@@ -35,6 +36,8 @@ HTTP API (all JSON):
   GET    /v1/databases/<name>/files/<filename>/root?version=N&tier=warm  — Merkle root (anchorable)
   POST   /v1/databases/<name>/proof             {hash}  — Merkle inclusion proof (verifiable offline)
   POST   /v1/databases/<name>/checkpoint        — on-demand checkpoint
+  POST   /v1/databases/<name>/sweep             — delete TTL-expired docs now (also runs
+                                                  automatically every NEDBD_SWEEP_S, default 30)
   POST   /v1/databases/<name>/batch             — ATOMIC multi-op tx: {ops: [{op, coll, id,
                                                   doc?, if_seq?, idem?, client?}], client?}
                                                   all-or-nothing; if_seq CAS preconditions
@@ -327,7 +330,7 @@ def make_handler(manager: Manager, token: Optional[str]):
                         if not coll or rid is None or not isinstance(doc, dict):
                             raise HttpError(400, "coll, id, and doc are required")
                         _scalar = ("client", "nonce", "idem", "evidence", "confidence",
-                                   "valid_from", "valid_to")
+                                   "valid_from", "valid_to", "ttl_s")
                         kw = {k: b[k] for k in _scalar if b.get(k) is not None}
                         # caused_by may live at the top level of the request body
                         # OR inside doc (natural for clients embedding it in the document).
@@ -369,6 +372,10 @@ def make_handler(manager: Manager, token: Optional[str]):
                         head = db.checkpoint()
                         self._send(200, {"ok": True, "head": head, "seq": db.seq})
                         return
+                    if method == "POST" and action == "sweep":
+                        swept = db.sweep()
+                        self._send(200, {"ok": True, "swept": swept, "seq": db.seq})
+                        return
                     if method == "GET" and action == "log":
                         limit = int(query.get("limit", ["50"])[0])
                         ops = [o.to_dict() for o in db.log.ops[-limit:]][::-1]
@@ -913,6 +920,26 @@ def main() -> None:
     token = args.token
     resp2_port = args.resp2_port
     manager = Manager(data)
+
+    # TTL sweeper: engine expiry is lazy (as_of=None gets) but daemon reads are
+    # snapshot-pinned, so expired docs would linger forever without an active
+    # sweep. Runs every NEDBD_SWEEP_S seconds (default 30; 0 disables) through
+    # each Sequencer's committer intent — single-writer discipline preserved.
+    sweep_s = float(os.environ.get("NEDBD_SWEEP_S", "30"))
+    if sweep_s > 0:
+        def _sweeper():
+            import time as _t
+            while True:
+                _t.sleep(sweep_s)
+                for _name in list(manager._open.keys()):
+                    try:
+                        n = manager._open[_name].sweep()
+                        if n:
+                            _log(f"  [nedbd] ttl sweep [{_name}]: {n} expired", level=1)
+                    except Exception as _e:  # noqa: BLE001
+                        _log(f"  [nedbd] ttl sweep [{_name}] error: {_e}", level=1)
+        threading.Thread(target=_sweeper, name="nedbd-ttl-sweeper", daemon=True).start()
+
     httpd = ThreadingHTTPServer((host, port), make_handler(manager, token))
     auth = "on" if token else "off"
     BANNER = f"""\