CultLib/src/GameCult.Caching/README.md

265 lines
7.3 KiB
Markdown

# GameCult.Caching
`GameCult.Caching` is an attribute-driven typed cache with a canonical
single-file MessagePack store. Domain models stay clean. The cache owns record
keys, schema ids, timestamps, and persistence metadata instead of smearing
that sludge across every class.
## Authoring Model
Cacheable models are plain classes annotated with cache intent.
```csharp
using GameCult.Caching;
using MessagePack;
[CultDocument("gamecult.item_data", "gamecult.item_data.v1")]
public sealed class ItemData
{
[Key(0)]
[CultName]
public string Name = string.Empty;
[Key(1)]
[CultIndex]
public string Category = string.Empty;
[Key(2)]
public int Value;
}
```
Available cache attributes:
- `CultDocument(schemaName, schemaVersion)`
- `CultName`
- `CultIndex(alias?)`
- `CultGlobal`
- `CultReference(targetType?, many: false)`
`CultDocumentRegistry` builds every document descriptor by reflection over
these attributes and MessagePack's `[Key]`/`[IgnoreMember]`; it is the only
descriptor authority.
## Main Concepts
### Record keys and handles
`CultCache` gives each stored document a cache-owned `CultRecordKey`. You work
with typed handles instead of forcing storage identity into the domain object.
```csharp
var cache = new CultCache();
var handle = await cache.AddAsync(new ItemData
{
Name = "Potion",
Category = "Consumable",
Value = 50
});
var potion = cache.Get<ItemData>(handle.Key);
```
### Name and index lookups
Name and index lookups are driven from attributes, not manual registration.
```csharp
var byName = cache.GetByName<ItemData>("Potion");
var byIndex = cache.GetByIndex<ItemData>("Category", "Consumable");
```
### Explicit references
References stay explicit in the domain. The cache will resolve them on demand,
but it will not quietly build an entire haunted object graph behind your back.
```csharp
[CultDocument("gamecult.quest_data", "gamecult.quest_data.v1")]
public sealed class QuestData
{
[Key(0)] public string Title = string.Empty;
[Key(1)] [CultReference] public CultRecordRef<ItemData> Reward;
}
```
## Persistence Shape
CultCache persistence is store-shaped, not entry-shaped:
1. store header
2. embedded schema catalog
3. records
Each persisted record carries:
- `key`
- `schemaId`
- `storedAt`
- `payload`
The domain payload stays free of storage metadata.
## Backing Store
CultCache now has one sanctioned persistence format:
- `SingleFileMessagePackBackingStore`
It persists the whole store as:
1. store format version
2. embedded schema catalog
3. persisted records
Each persisted record carries:
- `key`
- `schemaId`
- `storedAt`
- `payload`
## Happy Path
```csharp
using GameCult.Caching;
using GameCult.Caching.MessagePack;
var cache = await CultCacheMessagePack.OpenAsync("Data.msgpack");
var handle = await cache.UpsertAsync(new ItemData
{
Name = "Potion",
Category = "Consumable",
Value = 50
});
await cache.FlushAsync();
```
If you want the explicit assembly rite, the lower-level `CultCache` +
`SingleFileMessagePackBackingStore` path is still there. The helper is just the
blessed front door.
## Managed Documents And SoA Storage
Gameplay code keeps authoring normal typed documents. CultCache owns the record
identity, reactive presentation, and CPU-local structure-of-arrays table behind
that POCO surface.
```csharp
[CultDocument("game.player_transform", "game.player_transform.v1")]
public sealed class PlayerTransform
{
[CultName] public string Name = string.Empty;
public float PositionX;
public float PositionY;
public int Health;
}
var player = cache.Document<PlayerTransform>(new CultRecordKey("player:alice"));
await player.ReplaceAsync(new PlayerTransform
{
Name = "Alice",
PositionX = 4,
PositionY = 8,
Health = 100
});
using var subscription = player.Watch().Subscribe(current => Render(current));
player.Value!.Health = 90;
await player.CommitAsync();
var table = cache.Soa<PlayerTransform>();
Span<float> x = table.Column<float>(nameof(PlayerTransform.PositionX)).Span;
Span<float> y = table.Column<float>(nameof(PlayerTransform.PositionY)).Span;
Span<int> health = table.Column<int>(nameof(PlayerTransform.Health)).Span;
for (var row = 0; row < table.Count; row++)
{
x[row] += 0.016f;
}
```
`Document<T>()` is the standard presentation. `Soa<T>()` exposes the
cache-owned physical table for hot loops and diagnostics; it is not a second
domain model callers have to maintain.
## Element ids
A document type that holds a list of objects gives every object type in that list
(union arms included) a string member marked `[CultElementId]`, next to its
`[Key]`. The id is what lets a variant override one list element instead of the
whole list. Lists of strings, numbers and other non-object values need none.
The rule covers the shapes the id walk owns: arrays, `IEnumerable<T>` classes and
interfaces, dictionary values, and integer-keyed `[MessagePackObject]` and `[Union]`
types. Any other holder is one whole value: `ImmutableArray<T>`, `ArraySegment<T>`,
`Memory<T>`, `KeyValuePair`, tuples, `Lazy<T>`, a class without `[MessagePackObject]`,
a `[DataContract]` or string-keyed type, and a type or member declaring
`[MessagePackFormatter]`. Its elements carry no element ids: a `[CultElementId]`
member inside it is a plain string, never minted or checked, and a variant can only
replace the holder whole.
```csharp
[MessagePackObject]
public sealed class Line
{
[Key(0)] [CultElementId] public string Id = string.Empty;
[Key(1)] public string Text = string.Empty;
}
```
Leave `Id` empty and the cache mints a random id when the record is written. An
id you set yourself must be exactly 12 lowercase hex characters
(`0123456789ab`); anything else is refused with a `CultElementIdException`.
For readable ids, derive them: `[CultElementId(nameof(Name))]` makes an unset id
the text of that member (a string or number on the same type, unique within its
list), and a derived id may be any text. A readable name set by hand on a
non-derived list id is refused; the same member outside a list is unconstrained.
## Persistence discipline
Persistence stays manual by default. Mutations mark the cache and attached
backing stores dirty; nothing silently flushes every object write just because
that felt convenient in the moment.
Useful surfaces:
- `CultCacheMessagePack.OpenAsync(path)`
- `cache.IsDirty`
- `store.IsDirty`
- `cache.Document<T>(key)`
- `cache.Soa<T>()`
- `cache.UpsertAsync(document)`
- `cache.FlushAllBackingStores()`
- `cache.FlushAsync()`
- `cache.FlushBackingStore(store)`
- `cache.PrepareForReloadOrShutdown()`
- `cache.PrepareForReloadOrShutdownAsync()`
- `cache.FlushAttachedStoresOnDispose`
- `store.FlushOnDispose`
This is built for callers like Aquarium that want durable runtime state while
still choosing *when* to pay the write cost.
Single-file MessagePack remains a single-writer format. The atomic replace path
protects against partial writes, not competing writers trampling each other.
## Schema migration diagnostics
CultCache does not quietly fall back from exact `schemaId` resolution to
"close enough, probably." When a persisted schema drifts, the cache now emits a
typed migration report describing:
- exact vs compatible-drift resolution
- ignored extra slots
- defaulted missing slots
- warning codes/messages
Compatibility rules and canonical fixture receipts live in
`Contracts/cultcache-schema-compatibility.md`.