docs/start: C# update with retry, tested snippet; shared snippet check

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Libby 2026-11-13 14:14:42 +00:00
commit 867ff992ad
3 changed files with 98 additions and 7 deletions

View file

@ -16,7 +16,7 @@ this page.
| | CultCache | CultMath | Geometry | CultNet | CultMesh |
| --- | --- | --- | --- | --- | --- |
| **C#** | [first call, tested](#c-first-call) | [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` |
| **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) | 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 |
| **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 |
@ -70,6 +70,37 @@ public static class FirstCall
`FirstCall.Run` is the call; a second test in that file fails if the block above stops matching it. More: `src/GameCult.Caching/README.md`.
## C# update with retry
Change a record you may not be the only one changing. `Update` reads the record, hands your function a private
copy, and commits the result only if the record is still the one it read. If another writer got there first, it
reads again and runs your function again, up to five times. The source is
[`tests/GameCult.Caching.Tests/UpdateCallTests.cs`](../../tests/GameCult.Caching.Tests/UpdateCallTests.cs); the
snippet reuses `Item` from the first call.
```csharp
using GameCult.Caching;
using GameCult.Caching.MessagePack;
public static class UpdateCall
{
public static CultUpdateResult<Item> Restock(string path, CultRecordKey key)
{
var cache = CultCacheMessagePack.Create(path);
return cache.Update<Item>(key, item =>
{
item ??= new Item { Name = "Potion", Category = "Consumable" };
item.Value += 10;
return item;
});
}
}
```
The write is durable when `Update` returns, with no `PushAll`. A lost race re-runs the function, so keep it free of
side effects; when the attempts run out the result says `LostRace` instead of throwing. `UpsertAsync` plus
`PushAll` is the blind opt-out: last writer wins.
## TypeScript first call
Same shape in TypeScript: the document is a name, a schema id and a `parse`-able schema (zod here),

View file

@ -62,17 +62,23 @@ namespace GameCult.Caching.Tests
}
[Test]
public void DocsShowTheTestedSnippet()
{
var source = File.ReadAllText(SourcePath());
const string begin = "// snippet:begin\n";
var start = source.IndexOf(begin, StringComparison.Ordinal) + begin.Length;
var snippet = source[start..source.IndexOf("// snippet:end\n", StringComparison.Ordinal)];
var docs = File.ReadAllText(Path.Combine(Path.GetDirectoryName(SourcePath())!, "..", "..", "docs", "start", "README.md"));
Assert.That(docs.Replace("\r\n", "\n"), Does.Contain("```csharp\n" + snippet + "```"),
"docs/start/README.md no longer shows tests/GameCult.Caching.Tests/FirstCallTests.cs verbatim");
}
public void DocsShowTheTestedSnippet() => StartDocs.AssertShowsSnippet(SourcePath());
static string SourcePath([System.Runtime.CompilerServices.CallerFilePath] string path = "") => path;
}
// docs/start/README.md shows each tested snippet verbatim: the region between snippet:begin and snippet:end of its source file.
internal static class StartDocs
{
public static void AssertShowsSnippet(string sourcePath)
{
var source = File.ReadAllText(sourcePath).Replace("\r\n", "\n");
const string begin = "// snippet:begin\n";
var start = source.IndexOf(begin, StringComparison.Ordinal) + begin.Length;
var snippet = source[start..source.IndexOf("// snippet:end\n", StringComparison.Ordinal)];
var docs = File.ReadAllText(Path.Combine(Path.GetDirectoryName(sourcePath)!, "..", "..", "docs", "start", "README.md"));
Assert.That(docs.Replace("\r\n", "\n"), Does.Contain("```csharp\n" + snippet + "```"),
$"docs/start/README.md no longer shows {Path.GetFileName(sourcePath)} verbatim");
}
}
}

View file

@ -0,0 +1,54 @@
#nullable enable
using System;
using System.IO;
using NUnit.Framework;
// snippet:begin
using GameCult.Caching;
using GameCult.Caching.MessagePack;
public static class UpdateCall
{
public static CultUpdateResult<Item> Restock(string path, CultRecordKey key)
{
var cache = CultCacheMessagePack.Create(path);
return cache.Update<Item>(key, item =>
{
item ??= new Item { Name = "Potion", Category = "Consumable" };
item.Value += 10;
return item;
});
}
}
// snippet:end
namespace GameCult.Caching.Tests
{
// The C# update snippet that docs/start/README.md shows verbatim; it reuses FirstCallTests' Item.
public class UpdateCallTests
{
[Test]
public void RestockTwiceReadsTwenty()
{
var path = Path.Combine(Path.GetTempPath(), $"update-call-{Guid.NewGuid():N}.cc");
try
{
var key = new CultRecordKey("potion");
Assert.That(UpdateCall.Restock(path, key).Outcome, Is.EqualTo(CultUpdateOutcome.Updated));
Assert.That(UpdateCall.Restock(path, key).Outcome, Is.EqualTo(CultUpdateOutcome.Updated));
using var reader = CultCacheMessagePack.Create(path);
Assert.That(reader.Get<Item>(key)!.Value, Is.EqualTo(20));
}
finally
{
File.Delete(path);
}
}
[Test]
public void DocsShowTheTestedSnippet() => StartDocs.AssertShowsSnippet(SourcePath());
static string SourcePath([System.Runtime.CompilerServices.CallerFilePath] string path = "") => path;
}
}