brainlessdb 0.17.2__tar.gz → 0.17.3__tar.gz

{brainlessdb-0.17.2 → brainlessdb-0.17.3}/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 
 
+## [0.17.3] - 2026-10-21
+
+### 🐛 Bug Fixes
+
+- Make update() atomic and unindex by recorded values, not mutated attributes
+
+
 ## [0.17.2] - 2026-08-22
 
 ### 🐛 Bug Fixes

{brainlessdb-0.17.2 → brainlessdb-0.17.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brainlessdb
-Version: 0.17.2
+Version: 0.17.3
 Summary: Typed collections backed by NATS JetStream KV
 Author-email: "INSOFT s.r.o." <helpdesk@insoft.cz>
 License-Expression: MIT

{brainlessdb-0.17.2 → brainlessdb-0.17.3}/brainlessdb/__init__.py

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

{brainlessdb-0.17.2 → brainlessdb-0.17.3}/brainlessdb/collection.py

@@ -188,6 +188,10 @@ class Collection(Generic[T]):
         self._indexes: dict[str, dict[Any, set[str]]] = {f: {} for f in self._analysis.indexed_fields}
         # Uniques: field -> value -> uid
         self._uniques: dict[str, dict[Any, str]] = {f: {} for f in self._analysis.unique_fields}
+        # What _index_add actually recorded per uid: (indexed values, unique values).
+        # Removal goes by these, never by the entity's current attributes - the
+        # stored object is often mutated in place before save() re-indexes it.
+        self._indexed: dict[str, tuple[dict[str, Any], dict[str, Any]]] = {}
 
         # Callbacks: list of (callback, trigger_local)
         self._on_change: list[tuple[Callable, bool]] = []
@@ -234,13 +238,19 @@ class Collection(Generic[T]):
     # === Indexing ===
 
     def _index_add(self, obj: T) -> None:
+        """(Re)index `obj`, replacing whatever was indexed for its uid before."""
         uid = str(obj.uuid)
+        self._index_remove(uid)
+        indexed: dict[str, Any] = {}
+        uniques: dict[str, Any] = {}
         for field in self._analysis.indexed_fields:
             val = getattr(obj, field, None)
             self._indexes[field].setdefault(val, set()).add(uid)
+            indexed[field] = val
         for field in self._analysis.unique_fields:
             val = getattr(obj, field, None)
             if val is not None:
+                uniques[field] = val
                 prev = self._uniques[field].get(val)
                 if prev is not None and prev != uid:
                     _log.warning(
@@ -248,18 +258,22 @@ class Collection(Generic[T]):
                         self.name, field, val, prev, uid,
                     )
                 self._uniques[field][val] = uid
+        self._indexed[uid] = (indexed, uniques)
 
-    def _index_remove(self, obj: T) -> None:
-        uid = str(obj.uuid)
-        for field in self._analysis.indexed_fields:
-            val = getattr(obj, field, None)
-            if val in self._indexes[field]:
-                self._indexes[field][val].discard(uid)
-                if not self._indexes[field][val]:
+    def _index_remove(self, uid: str) -> None:
+        """Drop the index/unique entries recorded for `uid` by _index_add."""
+        recorded = self._indexed.pop(uid, None)
+        if recorded is None:
+            return
+        indexed, uniques = recorded
+        for field, val in indexed.items():
+            uids = self._indexes[field].get(val)
+            if uids is not None:
+                uids.discard(uid)
+                if not uids:
                     del self._indexes[field][val]
-        for field in self._analysis.unique_fields:
-            val = getattr(obj, field, None)
-            if val is not None and self._uniques[field].get(val) == uid:
+        for field, val in uniques.items():
+            if self._uniques[field].get(val) == uid:
                 del self._uniques[field][val]
 
     def _check_unique(self, obj: T) -> None:
@@ -289,7 +303,7 @@ class Collection(Generic[T]):
         obj = self._entities.pop(uid, None)
         if obj is None:
             return None
-        self._index_remove(obj)
+        self._index_remove(uid)
         _unregister(obj.uuid)
         self._metadata.pop(uid, None)
         self._dirty.discard(uid)
@@ -468,8 +482,11 @@ class Collection(Generic[T]):
 
     # === CRUD ===
 
-    def add(self, obj: Union[T, dict[str, Any]]):
-        """Add or update struct in collection."""
+    def add(self, obj: Union[T, dict[str, Any]]) -> T:
+        """Add or update struct in collection.
+
+        Stores a validated copy (never `obj` itself) and returns it. Raises before
+        touching the collection when validation or a unique constraint fails."""
         # Pre-process dict to inject local class type tag if needed
         if isinstance(obj, dict) and "_" in obj and isinstance(obj["_"], dict):
             local = obj["_"]
@@ -487,15 +504,13 @@ class Collection(Generic[T]):
 
         self._check_unique(obj)
 
-        if old:
-            self._index_remove(old)
-
         self._entities[uid] = obj
         self._index_add(obj)
         self._dirty.add(uid)
         _register(obj.uuid, self)
         self._client.schedule_flush()
         self._fire_change(old, obj, local=True)
+        return obj
 
     def get(self, uuid: str) -> Optional[T]:
         return self._entities.get(uuid)
@@ -506,7 +521,7 @@ class Collection(Generic[T]):
         if not item:
             return False
 
-        self._index_remove(item)
+        self._index_remove(uid)
         _unregister(item.uuid)
         del self._entities[uid]
         self._dirty.discard(uid)
@@ -528,6 +543,7 @@ class Collection(Generic[T]):
             idx.clear()
         for uq in self._uniques.values():
             uq.clear()
+        self._indexed.clear()
 
     # === Filtering ===
 
@@ -730,7 +746,7 @@ class Collection(Generic[T]):
                     if e.operation == "DEL":
                         item = self._entities.get(uid)
                         if item:
-                            self._index_remove(item)
+                            self._index_remove(uid)
                             _unregister(item.uuid)
                             del self._entities[uid]
                             self._metadata.pop(uid, None)
@@ -760,8 +776,6 @@ class Collection(Generic[T]):
                                 continue
 
                             self._metadata[uid] = w.m
-                            if old:
-                                self._index_remove(old)
                             self._entities[uid] = new
                             self._index_add(new)
                             _register(new.uuid, self)
@@ -802,7 +816,6 @@ class Collection(Generic[T]):
                         if old_data == new_data:
                             continue
 
-                        self._index_remove(old)
                         if kind == "state":
                             new = self._from_parts(e.key, self._to_config(old), new_data, self._to_local(old))
                         else:

{brainlessdb-0.17.2 → brainlessdb-0.17.3}/brainlessdb/struct.py

@@ -91,7 +91,7 @@ class BrainlessBucket(Struct, kw_only=True, tag=True, tag_field="TYPE"):
     def save(self) -> None:
         """Mark entity as dirty in its collection."""
         collection = _registry.get(self._uuid)
-        if collection:
+        if collection is not None:
             collection.add(self)
 
     @classmethod
@@ -146,17 +146,31 @@ class BrainlessBucket(Struct, kw_only=True, tag=True, tag_field="TYPE"):
         return cls(**kwargs)
 
     def update(self, data: dict) -> "BrainlessBucket":
-        """Update fields from dict, supports nested structs."""
+        """Apply `data` atomically, validate, save and return self.
+
+        Keys that are not struct fields are ignored; a dict given for a field
+        holding a nested struct is merged into it. The merged result is fully
+        converted (lists of dicts become structs, ...) and saved before `self`
+        is touched: when validation or the collection (UniqueConstraintError)
+        rejects it, `self` and the collection are left unchanged. On success
+        `self` holds the converted values; like after save(), the collection
+        stores its own validated copy, so re-fetch to get the stored object.
+        """
+        fields = self.__struct_fields__
+        merged = to_builtins(self)
         for key, value in data.items():
-            if not hasattr(self, key):
+            if key not in fields:
                 continue
-            if isinstance(value, dict):
-                current = getattr(self, key)
-                if current is not None and hasattr(current, "__struct_fields__"):
-                    merged = {**to_builtins(current), **value}
-                    value = convert(merged, type(current))
-            setattr(self, key, value)
-        self.save()
+            current = getattr(self, key)
+            if isinstance(value, dict) and hasattr(current, "__struct_fields__"):
+                value = {**to_builtins(current), **value}
+            merged[key] = to_builtins(value)
+        new = convert(merged, type(self))
+        collection = _registry.get(self._uuid)
+        if collection is not None:
+            collection.add(new)
+        for f in fields:
+            setattr(self, f, getattr(new, f))
         return self
 
 

{brainlessdb-0.17.2 → brainlessdb-0.17.3}/pyproject.toml

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

brainlessdb-0.17.3/tests/test_update_atomic.py

@@ -0,0 +1,243 @@
+"""Atomic update() and index bookkeeping.
+
+Production incident (Uniqa, ucs-server device sync): `update()` setattr'd the
+incoming values on the live entity before `save()` validated them. A unique
+clash made `save()` raise, leaving the live Device with `lines` as plain dicts
+(every `line.line_id` predicate then crashed) and the indexes keyed by values
+the entity no longer held. A second defect made it worse: `Collection.add()`
+removed index entries using the *old* object, which was the same live object
+the caller had just mutated, so the previously indexed values were never
+removed and later swaps clashed on values nobody held any more.
+"""
+
+from typing import Annotated, Optional, Union
+
+import msgspec
+import pytest
+from msgspec import Meta
+
+from brainlessdb import BrainlessBucket, BrainlessDBFeat, BrainlessStruct, UniqueConstraintError
+from tests.conftest import UniqueUserV1
+
+
+class LineExtensionV1(BrainlessStruct):
+    line_id: int = 0
+    extension_id: int = 0
+
+
+class LineTrunkV1(BrainlessStruct):
+    line_id: int = 0
+    trunk_id: int = 0
+
+
+class SettingsV1(BrainlessStruct):
+    codec: str = "opus"
+    volume: int = 5
+
+
+class GadgetV1(BrainlessBucket):
+    @staticmethod
+    def allows_app(app: str) -> bool:
+        return True
+
+    id: int = 0
+    mac: Annotated[Optional[str], Meta(extra={"brainlessdb_flags": BrainlessDBFeat.UNIQUE})] = None
+    group: Annotated[int, Meta(extra={"brainlessdb_flags": BrainlessDBFeat.INDEX})] = 0
+    lines: list[Union[LineExtensionV1, LineTrunkV1]] = []
+    settings: Optional[SettingsV1] = None
+
+
+@pytest.fixture
+async def gadgets(db):
+    coll = db.collection(GadgetV1)
+    await db.start()
+    return coll
+
+
+def _snapshot(coll) -> tuple:
+    return (
+        {f: {v: set(u) for v, u in idx.items()} for f, idx in coll._indexes.items()},
+        {f: dict(uq) for f, uq in coll._uniques.items()},
+    )
+
+
+class TestUpdateAtomic:
+    @pytest.mark.asyncio
+    async def test_rejected_by_unique_clash_leaves_entity_and_indexes_unchanged(self, gadgets):
+        gadgets.add(GadgetV1(id=1, mac="aa", group=1, lines=[LineExtensionV1(line_id=1, extension_id=10)]))
+        gadgets.add(GadgetV1(id=2, mac="bb", group=1))
+        live = gadgets.find(id=2)
+        before = msgspec.to_builtins(live)
+        indexes = _snapshot(gadgets)
+
+        with pytest.raises(UniqueConstraintError):
+            live.update(
+                {
+                    "mac": "aa",
+                    "group": 7,
+                    "lines": [{"TYPE": "LineExtensionV1", "line_id": 5, "extension_id": 50}],
+                    "settings": {"volume": 9},
+                }
+            )
+
+        assert gadgets.find(id=2) is live
+        assert msgspec.to_builtins(live) == before
+        assert live.lines == []
+        assert live.settings is None
+        assert _snapshot(gadgets) == indexes
+
+    @pytest.mark.asyncio
+    async def test_rejected_by_validation_leaves_entity_unchanged(self, gadgets):
+        gadgets.add(GadgetV1(id=1, mac="aa", lines=[LineTrunkV1(line_id=1, trunk_id=3)]))
+        live = gadgets.find(id=1)
+        before = msgspec.to_builtins(live)
+
+        with pytest.raises(msgspec.ValidationError):
+            live.update({"id": 9, "lines": [{"TYPE": "LineExtensionV1", "line_id": "not-an-int"}]})
+
+        assert msgspec.to_builtins(live) == before
+        assert isinstance(live.lines[0], LineTrunkV1)
+
+    @pytest.mark.asyncio
+    async def test_list_of_dicts_becomes_structs(self, gadgets):
+        gadgets.add(GadgetV1(id=1, mac="aa"))
+        live = gadgets.find(id=1)
+
+        result = live.update(
+            {
+                "lines": [
+                    {"TYPE": "LineExtensionV1", "line_id": 1, "extension_id": 10},
+                    {"TYPE": "LineTrunkV1", "line_id": 2, "trunk_id": 20},
+                ]
+            }
+        )
+
+        assert result is live
+        for obj in (live, gadgets.find(id=1)):
+            assert [type(line) for line in obj.lines] == [LineExtensionV1, LineTrunkV1]
+            assert [line.line_id for line in obj.lines] == [1, 2]
+
+    @pytest.mark.asyncio
+    async def test_dict_merges_into_nested_struct_and_unknown_keys_ignored(self, gadgets):
+        gadgets.add(GadgetV1(id=1, mac="aa", settings=SettingsV1(codec="pcma", volume=3)))
+        live = gadgets.find(id=1)
+
+        live.update({"settings": {"volume": 8}, "nope": 1, "uuid": "ignored", "save": None})
+
+        stored = gadgets.find(id=1)
+        assert stored.settings == SettingsV1(codec="pcma", volume=8)
+        assert live.settings == SettingsV1(codec="pcma", volume=8)
+
+    @pytest.mark.asyncio
+    async def test_dict_for_empty_nested_struct_is_converted(self, gadgets):
+        gadgets.add(GadgetV1(id=1, mac="aa"))
+        live = gadgets.find(id=1)
+
+        live.update({"settings": {"volume": 4}})
+
+        assert live.settings == SettingsV1(volume=4)
+        assert gadgets.find(id=1).settings == SettingsV1(volume=4)
+
+    @pytest.mark.asyncio
+    async def test_update_detached_entity_validates_without_collection(self):
+        g = GadgetV1(id=1, lines=[])
+        with pytest.raises(msgspec.ValidationError):
+            g.update({"id": "x"})
+        assert g.id == 1
+        g.update({"lines": [{"TYPE": "LineTrunkV1", "line_id": 4}]})
+        assert isinstance(g.lines[0], LineTrunkV1)
+
+    @pytest.mark.asyncio
+    async def test_swap_unique_values_via_temporary(self, gadgets):
+        gadgets.add(GadgetV1(id=1, mac="aa"))
+        gadgets.add(GadgetV1(id=2, mac="bb"))
+
+        gadgets.find(id=1).update({"mac": "tmp"})
+        gadgets.find(id=2).update({"mac": "aa"})
+        gadgets.find(id=1).update({"mac": "bb"})
+
+        assert gadgets.find(id=1).mac == "bb"
+        assert gadgets.find(id=2).mac == "aa"
+        one, two = str(gadgets.find(id=1).uuid), str(gadgets.find(id=2).uuid)
+        assert gadgets._uniques["mac"] == {"bb": one, "aa": two}
+
+    @pytest.mark.asyncio
+    async def test_swap_unique_values_via_save(self, gadgets):
+        gadgets.add(GadgetV1(id=1, mac="aa"))
+        gadgets.add(GadgetV1(id=2, mac="bb"))
+
+        g1 = gadgets.find(id=1)
+        g1.mac = "tmp"
+        g1.save()
+        g2 = gadgets.find(id=2)
+        g2.mac = "aa"
+        g2.save()
+        g1 = gadgets.find(id=1)
+        g1.mac = "bb"
+        g1.save()
+
+        one, two = str(gadgets.find(id=1).uuid), str(gadgets.find(id=2).uuid)
+        assert gadgets._uniques["mac"] == {"bb": one, "aa": two}
+
+    @pytest.mark.asyncio
+    async def test_index_moves_on_update(self, gadgets):
+        gadgets.add(GadgetV1(id=1, mac="aa", group=1))
+        uid = str(gadgets.find(id=1).uuid)
+
+        gadgets.find(id=1).update({"group": 2})
+
+        assert gadgets._indexes["group"] == {2: {uid}}
+        assert gadgets.filter(group=1) == []
+        assert [g.id for g in gadgets.filter(group=2)] == [1]
+
+
+class TestInPlaceMutationIndexes:
+    @pytest.mark.asyncio
+    async def test_in_place_mutation_then_unique_change_leaves_no_stale_entries(self, unique_users):
+        unique_users.add(UniqueUserV1(id=1, email="a@x"))
+        uid = str(unique_users.find(id=1).uuid)
+
+        live = unique_users.find(id=1)
+        live.email = "b@x"
+        live.save()
+        live = unique_users.find(id=1)
+        live.email = "c@x"
+        live.save()
+
+        assert unique_users._uniques["email"] == {"c@x": uid}
+        # both previous values are free again
+        unique_users.add(UniqueUserV1(id=2, email="a@x"))
+        unique_users.add(UniqueUserV1(id=3, email="b@x"))
+
+    @pytest.mark.asyncio
+    async def test_own_unique_value_change_does_not_clash_with_itself(self, unique_users):
+        unique_users.add(UniqueUserV1(id=1, email="a@x"))
+        live = unique_users.find(id=1)
+        live.email = "b@x"
+        live.save()
+        live = unique_users.find(id=1)
+        live.email = "a@x"
+        live.save()
+        assert unique_users.find(id=1).email == "a@x"
+        assert unique_users._uniques["email"] == {"a@x": str(live.uuid)}
+
+    @pytest.mark.asyncio
+    async def test_delete_after_in_place_mutation_frees_indexed_value(self, unique_users):
+        unique_users.add(UniqueUserV1(id=1, email="a@x"))
+        live = unique_users.find(id=1)
+        live.email = "b@x"  # mutated, never saved
+        unique_users.delete(live)
+
+        assert unique_users._uniques["email"] == {}
+        unique_users.add(UniqueUserV1(id=2, email="a@x"))
+
+    @pytest.mark.asyncio
+    async def test_rejected_save_keeps_index_on_stored_values(self, unique_users):
+        unique_users.add(UniqueUserV1(id=1, email="a@x"))
+        unique_users.add(UniqueUserV1(id=2, email="b@x"))
+        live = unique_users.find(id=2)
+        live.email = "a@x"
+        with pytest.raises(UniqueConstraintError):
+            live.save()
+        one = str(unique_users.find(id=1).uuid)
+        assert unique_users._uniques["email"] == {"a@x": one, "b@x": str(live.uuid)}

{brainlessdb-0.17.2 → brainlessdb-0.17.3}/uv.lock

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