265 lines
7.3 KiB
Markdown
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`.
|