diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index 61b90341..02982c47 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -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 diff --git a/packages/cultcache-py/tests/test_first_call.py b/packages/cultcache-py/tests/test_first_call.py index 9b6b65dc..32bafa56 100644 --- a/packages/cultcache-py/tests/test_first_call.py +++ b/packages/cultcache-py/tests/test_first_call.py @@ -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__":