cultcache-rs: update tests, content-version vector, docs snippet, README and CHANGELOG

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Libby 2026-11-13 19:56:42 +00:00
commit 6e6c123100
7 changed files with 816 additions and 9 deletions

View file

@ -18,7 +18,7 @@ this page.
| --- | --- | --- | --- | --- | --- |
| **C#** | [first call, tested](#c-first-call); [update, tested](#c-update-with-retry) | [package](../../packages/cultmath/README.md); snippet not yet | [package](../../src/GameCult.Geometry/README.md); snippet not yet | [first call, tested](#c-cultnet-first-call); [package](../../src/GameCult.Networking) | [quickstart](../../src/GameCult.Mesh/docs/durable-node-quickstart.md); run by `scripts/verify-eve-getting-started.ps1` |
| **TypeScript** | [first call, tested](#typescript-first-call); [update, tested](#typescript-update-with-retry) | not yet | not yet | [first call, tested](#typescript-cultnet-first-call); [package](../../packages/cultnet-ts/README.md) | [package](../../packages/cultmesh-ts/README.md); snippet not yet; [recipe: two-client .io game](io-game.md), tested with two live clients, browser page not yet run |
| **Rust** | [first call, tested](#rust-first-call) | [native core](../../packages/cultmath/native/cultmath-core); snippet not yet | not yet | [first call, tested](#rust-cultnet-first-call); [package](../../packages/cultnet-rs/README.md), [examples](../../packages/cultnet-rs/examples) | [package](../../packages/cultmesh-rs); snippet not yet |
| **Rust** | [first call, tested](#rust-first-call); [update, tested](#rust-update-with-retry) | [native core](../../packages/cultmath/native/cultmath-core); snippet not yet | not yet | [first call, tested](#rust-cultnet-first-call); [package](../../packages/cultnet-rs/README.md), [examples](../../packages/cultnet-rs/examples) | [package](../../packages/cultmesh-rs); snippet not yet |
| **Python** | [first call, tested](#python-first-call) | not yet | not yet | [first call, tested](#python-cultnet-first-call); [package](../../packages/cultnet-py/README.md) | [package](../../packages/cultmesh-py/README.md); snippet not yet |
For the whole
@ -220,6 +220,36 @@ fn first_call() -> anyhow::Result<()> {
}
```
## Rust update with retry
`update` changes a record from what the store holds now and commits only if it is still that record. The source is the
second region of
[`packages/cultcache-rs/tests/first_call.rs`](../../packages/cultcache-rs/tests/first_call.rs), which uses the `Item` of
the first call above; a test in that file fails if the block stops matching the file.
```rust
fn restock(path: &Path) -> anyhow::Result<CultUpdateResult<Item>> {
let mut cache = CultCache::new();
cache.register_entry_type::<Item>()?;
cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(path))?;
cache.pull_all_backing_stores()?;
cache.update::<Item, _>("item:potion", |item| {
// The store's copy of the record, or nothing if it has none; this may run again on a lost race.
let mut item = item.unwrap_or(Item {
name: "Potion".to_string(),
category: "Consumable".to_string(),
value: 0,
});
item.value += 10;
Some(item)
})
}
```
The write is durable when `update` returns. A lost race re-runs the closure, so keep it free of side effects; when the
attempts run out (five, or the bound `update_with_attempts` takes) the outcome says `LostRace` instead of failing, and
returning `None` writes nothing and says `Declined`. `put` is the blind opt-out: last writer wins.
## Python first call
A document is a definition with an encoder and decoder; `name=` registers the name lookup, `indexes=` unique lookups and