cultcache-py: pin CultCacheError on a convert refusal; state that store push does not judge payload bytes and the cache write path does
Some checks failed
CultMesh portability and performance / ubuntu-latest reactive semantics and leases (pull_request) Has been cancelled

The store holds no definition, so it cannot judge a JSON- or custom-codec payload; put_envelope decodes under the definition before any store is touched.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Libby 2026-11-17 03:28:55 +00:00
commit 562d318b48
2 changed files with 34 additions and 9 deletions

View file

@ -69,7 +69,7 @@ store.
## Public Surface
- `CultCacheError` (a `RuntimeError`, exported from the package root): the cache's refusals (a duplicate registration, a unique-index violation, a key held by two types). Import it from `cultcache_py`, not from the private `cache` module. Any `convert` refusal raised as a `CultCacheError` is caught by it too, once `convert` lands.
- `CultCacheError` (a `RuntimeError`, exported from the package root): the cache's refusals (a unique-index violation, a key held by two types) and `convert`'s (`source_missing`, `destination_exists`, a refused record). Import it from `cultcache_py`, not from the private `cache` module.
- `define_document_type(...)`
- `define_database_entry_type(...)`
- `database_entry_field(...)`
@ -185,9 +185,14 @@ digit (`0` to `9`), below.
rewritten under the definitions' own codec, records of other types keep their
bytes, and the new file is fsynced before the call returns. Open it with the
default definitions, then swap it in yourself. The source is never written. A
refused record raises `CultCacheError` naming the type, record key and code, and
refused record raises `CultCacheError` (importable from `cultcache_py`) naming the type, record key and code, and
leaves no destination; a killed run leaves the source as it was and a partial
destination, so delete the destination and run again.
- A store's `push` does not validate payload bytes: a store holds no definition, so it cannot know a record's codec (a JSON or
custom-codec payload is not one MessagePack value) and carries the bytes it is given, as it carries a foreign record. The
cache write path judges them: `put_envelope(s)` decodes the payload under the definition before any store is touched, so a
payload with bytes after its first value is refused (`ValueError`, "bytes after its first MessagePack value (refused on read)")
and nothing is written. A tail pushed straight through a store is refused at the next load.
- A JSON payload that is a single digit (`0` to `9`) is also a valid one-byte
MessagePack integer and reads as 48 to 57 under the default, with no refusal. Only a
document whose whole value is such a digit meets this; objects, lists and

View file

@ -1,10 +1,12 @@
"""The Python CultCache first call from docs/start/README.md. The docs show the region between the
`snippet` markers verbatim, and test_docs_show_the_tested_snippet fails when they differ."""
import tempfile
import unittest
from pathlib import Path
from cultcache_py import UpdateOutcome
import cultcache_py
from cultcache_py import CultCacheEnvelope, JsonLinesBackingStore, UpdateOutcome
# snippet:begin
import tempfile
@ -94,17 +96,35 @@ class FirstCallTests(unittest.TestCase):
class RootExportTests(unittest.TestCase):
def test_cultcacheerror_is_importable_from_the_root_and_catches_a_cache_refusal(self) -> None:
import cultcache_py
from cultcache_py import CultCache, CultCacheError, define_document_type
def test_cultcacheerror_from_the_root_catches_a_convert_refusal(self) -> None:
from cultcache_py import CultCacheError, convert
from cultcache_py.cache import CultCacheError as private
self.assertIs(CultCacheError, private)
self.assertIn("CultCacheError", cultcache_py.__all__)
document = define_document_type("tests.root_export")
cache = CultCache.builder().register_document_type(document).build()
with self.assertRaises(CultCacheError):
cache.get_required(document, "absent")
with tempfile.TemporaryDirectory() as directory:
source = SingleFileMessagePackBackingStore(Path(directory) / "source.cc")
source.push(CultCacheEnvelope.create(key="k", type=document.type, payload=document.encode_payload({"a": 1})))
destination = Path(directory) / "destination.cc"
destination.write_bytes(b"in the way")
with self.assertRaises(CultCacheError) as caught:
convert(source, destination, [document])
self.assertIn("destination_exists", str(caught.exception))
self.assertEqual(destination.read_bytes(), b"in the way")
def test_the_cache_write_path_refuses_a_payload_tail_and_writes_nothing(self) -> None:
document = define_document_type("tests.tail")
with tempfile.TemporaryDirectory() as directory:
for store in (
SingleFileMessagePackBackingStore(Path(directory) / "tail.cc"),
JsonLinesBackingStore(Path(directory) / "tail.jsonl"),
):
cache = CultCache.builder().register_document_type(document).add_generic_store(store).build()
tailed = document.encode_payload({"a": 1}) + b"\xc0"
with self.assertRaisesRegex(ValueError, r"1 bytes after its first MessagePack value \(refused on read\)"):
cache.put_envelope(document, CultCacheEnvelope.create(key="k", type=document.type, payload=tailed))
self.assertEqual(store.pull_all(), [], type(store).__name__)
if __name__ == "__main__":