brainlessdb 0.14.2__tar.gz → 0.14.4__tar.gz

{brainlessdb-0.14.2 → brainlessdb-0.14.4}/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to this project will be documented in this file.
 
 
+## [0.14.4] - 2026-06-01
+
+### 📚 Documentation
+
+- Dlq key format
+
+### 🧪 Testing
+
+- Pull state+local for new entities in config watcher, avoid `:` in DLQ key
+
+
+## [0.14.3] - 2026-06-01
+
+### 🐛 Bug Fixes
+
+- Pull state+local for new entities in config watcher, avoid `:` in DLQ key
+
+
 ## [0.14.2] - 2026-04-14
 
 ### 🐛 Bug Fixes

{brainlessdb-0.14.2 → brainlessdb-0.14.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainlessdb
-Version: 0.14.2
+Version: 0.14.4
 Summary: Typed collections backed by NATS JetStream KV
 Author-email: "INSOFT s.r.o." <helpdesk@insoft.cz>
 License-Expression: MIT
@@ -291,6 +291,6 @@ async for entry in bucket.watch(timeout=3):
 
 Entities that fail to deserialize (e.g. after a schema change) are automatically moved to the `brainless_dlq` NATS KV bucket and removed from the source bucket. This applies during both initial load and live watch updates.
 
-DLQ key format: `{SourceBucket}::{EntityUID}::{Timestamp}`
+DLQ key format: `{SourceBucket}__{EntityUID}__{Timestamp}` (double underscore — NATS KV keys disallow `:`)
 
 Each entry contains `source_bucket`, `key`, `error`, `timestamp`, and the original `value` for recovery.

{brainlessdb-0.14.2 → brainlessdb-0.14.4}/README.md

@@ -280,6 +280,6 @@ async for entry in bucket.watch(timeout=3):
 
 Entities that fail to deserialize (e.g. after a schema change) are automatically moved to the `brainless_dlq` NATS KV bucket and removed from the source bucket. This applies during both initial load and live watch updates.
 
-DLQ key format: `{SourceBucket}::{EntityUID}::{Timestamp}`
+DLQ key format: `{SourceBucket}__{EntityUID}__{Timestamp}` (double underscore — NATS KV keys disallow `:`)
 
 Each entry contains `source_bucket`, `key`, `error`, `timestamp`, and the original `value` for recovery.

{brainlessdb-0.14.2 → brainlessdb-0.14.4}/brainlessdb/__init__.py

@@ -1,6 +1,6 @@
 """Brainless DB - Typed collections backed by NATS JetStream KV."""
 
-__version__ = "0.14.2"
+__version__ = "0.14.4"
 
 from typing import Any, Optional, TypeVar
 

{brainlessdb-0.14.2 → brainlessdb-0.14.4}/brainlessdb/client.py

@@ -62,7 +62,7 @@ class BrainlessDB:
             "value": original,
         }
         ts = entry["timestamp"].replace(":", "-").replace("+", "-")
-        dlq_key = f"{source_bucket}::{key}::{ts}"
+        dlq_key = f"{source_bucket}__{key}__{ts}"
         payload = json.dumps(entry).encode()
         try:
             if self._dlq_bucket is None:

{brainlessdb-0.14.2 → brainlessdb-0.14.4}/brainlessdb/collection.py

@@ -226,6 +226,20 @@ class Collection(Generic[T]):
                 _log.error("Failed to decode key '%s' from bucket '%s': %s", k, bucket.name, ex)
         return result
 
+    @staticmethod
+    async def _fetch_extra(bucket: Optional[Bucket], uid: str) -> Optional[dict]:
+        """Fetch a single state/local row for `uid`. Returns None if absent."""
+        if not bucket:
+            return None
+        raw = await bucket.get(uid)
+        if not raw:
+            return None
+        try:
+            return msgspec.json.decode(raw)
+        except Exception as ex:
+            _log.error("Failed to decode '%s' from bucket '%s': %s", uid, bucket.name, ex)
+            return None
+
     # === CRUD ===
 
     def add(self, obj: Union[T, dict[str, Any]]):
@@ -493,13 +507,17 @@ class Collection(Generic[T]):
                             self._metadata[uid] = w.m
                             if old:
                                 self._index_remove(old)
-
-                            new = self._from_parts(
-                                uid,
-                                w.d,
-                                self._to_state(old) if old else None,
-                                self._to_local(old),
-                            )
+                                state_data = self._to_state(old)
+                                local_data = self._to_local(old)
+                            else:
+                                # New entity (created by another process) — pull state
+                                # and local from their buckets, since _to_state(None)
+                                # would yield no STATE-flagged fields and required
+                                # fields would be missing.
+                                state_data = await self._fetch_extra(self._state_bucket, uid)
+                                local_data = await self._fetch_extra(self._local_bucket, uid)
+
+                            new = self._from_parts(uid, w.d, state_data, local_data)
                             self._entities[uid] = new
                             self._index_add(new)
                             _register(new.uuid, self)

{brainlessdb-0.14.2 → brainlessdb-0.14.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "brainlessdb"
-version = "0.14.2"
+version = "0.14.4"
 description = "Typed collections backed by NATS JetStream KV"
 authors = [
     {name = "INSOFT s.r.o.", email = "helpdesk@insoft.cz"}

{brainlessdb-0.14.2 → brainlessdb-0.14.4}/tests/test_dead_letter.py

@@ -29,9 +29,12 @@ def _kv_config(name: str):
     return type("C", (), {"bucket": name})()
 
 
+DLQ_SEP = "__"
+
+
 def _dlq_find(dlq_kv, bucket: str, uid: str) -> list[dict]:
-    """Find all DLQ entries matching bucket::uid prefix."""
-    prefix = f"{bucket}::{uid}::"
+    """Find all DLQ entries matching the bucket+uid prefix."""
+    prefix = f"{bucket}{DLQ_SEP}{uid}{DLQ_SEP}"
     results = []
     for key, entry in dlq_kv._entries.items():
         if key.startswith(prefix):
@@ -40,8 +43,8 @@ def _dlq_find(dlq_kv, bucket: str, uid: str) -> list[dict]:
 
 
 def _dlq_has(dlq_kv, bucket: str, uid: str) -> bool:
-    """Check if any DLQ entry exists for bucket::uid."""
-    prefix = f"{bucket}::{uid}::"
+    """Check if any DLQ entry exists for the given bucket+uid."""
+    prefix = f"{bucket}{DLQ_SEP}{uid}{DLQ_SEP}"
     return any(k.startswith(prefix) for k in dlq_kv._entries)
 
 
@@ -316,3 +319,113 @@ class TestDeadLetterClientAPI:
         assert entries[0]["error"] == "error 2"
 
         await db.stop()
+
+
+class TestDeadLetterKeyFormat:
+    """DLQ keys must be valid NATS KV keys (no `:`, `*`, `>`, spaces)."""
+
+    @pytest.mark.asyncio
+    async def test_dlq_key_has_no_colon(self):
+        """Regression: NATS KV rejects `:` in keys, so the DLQ key must not contain one."""
+        nats = MockNats()
+        db = BrainlessDB(nats, namespace="test")
+        await db.start()
+
+        await db.dead_letter("SomeBucket", "some-key", b'{"v": 1}', "boom")
+
+        dlq_kv = nats.jetstream()._buckets["brainless_dlq"]
+        assert len(dlq_kv._entries) == 1
+        (key,) = dlq_kv._entries.keys()
+        assert ":" not in key
+        # And the parts we expect are still recoverable from the key
+        assert key.startswith("SomeBucket")
+        assert "some-key" in key
+
+        await db.stop()
+
+
+class TestWatcherStateMerge:
+    """Live config-bucket watcher must merge state for brand-new entities."""
+
+    @pytest.mark.asyncio
+    async def test_new_entity_with_required_state_field_loads_via_watch(self):
+        """Another process writes config+state; the watcher must build with state merged in,
+        not fail with 'missing required field'."""
+        from typing import Annotated
+
+        from msgspec import Meta
+
+        from brainlessdb import BrainlessBucket, BrainlessDBFeat
+
+        class StatefulV1(BrainlessBucket):
+            @staticmethod
+            def allows_app(app: str) -> bool:
+                return True
+
+            # Required STATE field — no default. Pre-fix bug: build with state=None fails here.
+            name: Annotated[str, Meta(extra={"brainlessdb_flags": BrainlessDBFeat.STATE})]
+
+        nats = MockNats()
+        db = BrainlessDB(nats, namespace="test", flush_interval=0)
+        items = db.collection(StatefulV1)
+        await db.start()
+        await asyncio.sleep(0.05)  # let watcher initialize
+
+        # Simulate another process flushing a fresh entity. Brainless writes
+        # config then state per uid; we put state first so the row exists by
+        # the time the watcher processes the config event (the common case
+        # since the watcher is async and runs after both puts have landed).
+        js = nats.jetstream()
+        state_kv = await js.create_key_value(_kv_config("StatefulV1-State"))
+        config_kv = js._buckets["StatefulV1"]
+        uid = _uuid()
+        await state_kv.put(uid, msgspec.json.encode({"name": "alice"}))
+        await config_kv.put(uid, _make_config_wrapper({}))
+
+        await asyncio.sleep(0.1)  # let watcher pick up the config event
+
+        # Entity loaded with state merged in — not dead-lettered
+        assert uid in items, "entity should have loaded via watcher"
+        assert items.get(uid).name == "alice"
+        dlq = js._buckets.get("brainless_dlq")
+        if dlq is not None:
+            assert not _dlq_has(dlq, "StatefulV1", uid)
+
+        await db.stop()
+
+    @pytest.mark.asyncio
+    async def test_new_entity_without_state_row_still_handles_required_state(self):
+        """If state row genuinely doesn't exist when config arrives, dead-letter cleanly."""
+        from typing import Annotated
+
+        from msgspec import Meta
+
+        from brainlessdb import BrainlessBucket, BrainlessDBFeat
+
+        class StatefulV1(BrainlessBucket):
+            @staticmethod
+            def allows_app(app: str) -> bool:
+                return True
+
+            name: Annotated[str, Meta(extra={"brainlessdb_flags": BrainlessDBFeat.STATE})]
+
+        nats = MockNats()
+        db = BrainlessDB(nats, namespace="test", flush_interval=0)
+        items = db.collection(StatefulV1)
+        await db.start()
+        await asyncio.sleep(0.05)
+
+        # Config-only write — no state. Build must fail, row must be DLQ'd
+        # (and removed from source so the watcher doesn't loop on the same row).
+        js = nats.jetstream()
+        config_kv = js._buckets["StatefulV1"]
+        uid = _uuid()
+        await config_kv.put(uid, _make_config_wrapper({}))
+        await asyncio.sleep(0.1)
+
+        assert uid not in items
+        assert uid not in config_kv._entries, "bad row should be removed from source"
+        dlq = js._buckets["brainless_dlq"]
+        assert _dlq_has(dlq, "StatefulV1", uid)
+
+        await db.stop()

{brainlessdb-0.14.2 → brainlessdb-0.14.4}/uv.lock

@@ -17,7 +17,7 @@ wheels = [
 
 [[package]]
 name = "brainlessdb"
-version = "0.14.1"
+version = "0.14.3"
 source = { editable = "." }
 dependencies = [
     { name = "msgspec" },