diff --git a/packages/cultcache-py/CHANGELOG.md b/packages/cultcache-py/CHANGELOG.md index 29544715..738be0b0 100644 --- a/packages/cultcache-py/CHANGELOG.md +++ b/packages/cultcache-py/CHANGELOG.md @@ -9,6 +9,7 @@ ### Added +- `CultCacheError` is exported from the package root (`from cultcache_py import CultCacheError`); it was reachable only from the private `cultcache_py.cache` module. - `CultCache.update` and `update_global` return `UpdateResult(outcome, document)`; `UpdateOutcome` is `UPDATED`, `DECLINED` or `LOST_RACE`. The single-file store gains `read(key)` (the record and its content version, the SHA-256 C# computes) and `commit_if(envelope, expected)`, the version is the SHA-256 of the record re-encoded as `[key, schemaId, storedAt, payload]` with minimal MessagePack encodings, which is the SHA-256 of the record's stored bytes exactly when the writer encoded it minimally (every writer in this library does; a record another writer encoded with a wider-than-needed length or integer has the version of its minimal form, not of its bytes). Both looked up by the cache and not `BackingStore` protocol members (variants:cut_spec:cut-update-with-retry-py). - `read_payload_tree(type_name, payload, decoder=None, depth_faults=(msgpack.exceptions.StackError,))`: the exported owner of the one-value, depth-first payload read that `decode_payload` uses, for payloads read outside a definition (`cultnet-py`'s witness bundle decode needs it, so `cultnet-py` now requires `cultcache-py>=0.4.0`). The manifest version is 0.4.0, the minor these Unreleased breaking changes imply, set in this change so the workspace install resolves the new bound; the `## Unreleased` heading becomes `## [0.4.0]` when it is tagged. diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index c06cc2a9..f6574618 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -69,6 +69,7 @@ store. ## Public Surface +- `CultCacheError` (a `RuntimeError`, exported from the package root): the cache's refusals (a unique-index violation; a key held by two types on load, while the same conflict on a write is a `SchemaConflictError`, a `ValueError`) 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(...)` @@ -184,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/src/cultcache_py/__init__.py b/packages/cultcache-py/src/cultcache_py/__init__.py index 363c338e..9d8437ae 100644 --- a/packages/cultcache-py/src/cultcache_py/__init__.py +++ b/packages/cultcache-py/src/cultcache_py/__init__.py @@ -1,7 +1,7 @@ from .backing_store import BackingStore, CultCacheEnvelope from .backing_store import CultCacheSchemaCatalogEntry, CultCacheSchemaCatalogMember from . import leaves -from .cache import CultCache, CultCacheBuilder, ForeignRecord, UpdateOutcome, UpdateResult, convert +from .cache import CultCache, CultCacheBuilder, CultCacheError, ForeignRecord, UpdateOutcome, UpdateResult, convert from .documents import ( MAX_PAYLOAD_DEPTH, JSON_PAYLOAD_CODEC, @@ -30,6 +30,7 @@ __all__ = [ "BackingStore", "CultCache", "CultCacheBuilder", + "CultCacheError", "CultCachePayloadDepthError", "CultCachePayloadFormatError", "CultCacheEnvelope", diff --git a/packages/cultcache-py/tests/test_first_call.py b/packages/cultcache-py/tests/test_first_call.py index 232f6c7d..42cc5aa8 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 @@ -93,5 +95,62 @@ class FirstCallTests(unittest.TestCase): self.assertIn("```python\n" + snippet + "```", docs) +class RootExportTests(unittest.TestCase): + 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") + 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__) + + def test_a_batch_with_one_tailed_envelope_is_refused_whole_and_earlier_records_stay(self) -> None: + document = define_document_type("tests.tail_batch") + with tempfile.TemporaryDirectory() as directory: + for store in ( + SingleFileMessagePackBackingStore(Path(directory) / "batch.cc"), + JsonLinesBackingStore(Path(directory) / "batch.jsonl"), + ): + name = type(store).__name__ + cache = CultCache.builder().register_document_type(document).add_generic_store(store).build() + cache.put(document, "early", {"a": 0}) + before = store.pull_all() + good = document.encode_payload({"a": 1}) + with self.assertRaisesRegex(ValueError, r"1 bytes after its first MessagePack value \(refused on read\)"): + cache.put_envelopes( + document, + [ + CultCacheEnvelope.create(key="good", type=document.type, payload=good), + CultCacheEnvelope.create(key="bad", type=document.type, payload=good + b"\xc0"), + ], + ) + self.assertEqual(store.pull_all(), before, name) + self.assertEqual([item.key for item in before], ["early"], name) + self.assertIsNone(cache.get(document, "good"), name) + + if __name__ == "__main__": unittest.main() +