Add cache-backed CultMesh document handles

This commit is contained in:
Meta Vens 2026-06-27 14:43:00 +01:00
commit 60a3fa9f82
4 changed files with 417 additions and 11 deletions

View file

@ -8,6 +8,7 @@ using System.Threading.Tasks;
using GameCult.Caching;
using GameCult.Caching.MessagePack;
using GameCult.Networking;
using R3;
namespace GameCult.Mesh
{
@ -412,6 +413,19 @@ namespace GameCult.Mesh
return new CultMeshDocumentHandle<TDocument>(BindLiveFeed(context, feed));
}
/// <summary>
/// Binds a mutable typed document live feed to a Verse context.
/// </summary>
public static CultMeshDocumentHandle<TDocument> BindDocument<TDocument>(
CultMeshVerseContext context,
CultMeshLiveFeed<CultMeshDocumentQueryParameters, TDocument> feed,
Func<TDocument, Task> replace)
where TDocument : class
{
if (replace == null) throw new ArgumentNullException(nameof(replace));
return new CultMeshDocumentHandle<TDocument>(BindLiveFeed(context, feed), replace);
}
/// <summary>
/// Binds a typed document live feed to a Verse.
/// </summary>
@ -424,6 +438,19 @@ namespace GameCult.Mesh
return BindDocument(verse.Context, feed);
}
/// <summary>
/// Binds a mutable typed document live feed to a Verse.
/// </summary>
public static CultMeshDocumentHandle<TDocument> BindDocument<TDocument>(
CultMeshVerse verse,
CultMeshLiveFeed<CultMeshDocumentQueryParameters, TDocument> feed,
Func<TDocument, Task> replace)
where TDocument : class
{
if (verse == null) throw new ArgumentNullException(nameof(verse));
return BindDocument(verse.Context, feed, replace);
}
/// <summary>
/// Binds a typed state pointer to a Verse context.
/// </summary>
@ -884,6 +911,30 @@ namespace GameCult.Mesh
return BindDocument(context, feed);
}
/// <summary>
/// Creates a mutable typed document handle from snapshot/watch/replace delegates and binds it to a Verse context.
/// </summary>
public static CultMeshDocumentHandle<TDocument> Document<TDocument>(
string documentId,
CultMeshVerseContext context,
Func<CultMeshQueryContext, Task<TDocument>> latest,
Func<CultMeshQueryContext, R3.Observable<TDocument>> watch,
Func<TDocument, Task> replace,
IEnumerable<CultMeshProjectionSource>? sources = null,
CultMeshRouteHint? routeHint = null)
where TDocument : class
{
if (replace == null) throw new ArgumentNullException(nameof(replace));
var feed = LiveFeed<CultMeshDocumentQueryParameters, TDocument>(
documentId,
(_parameters, queryContext) => latest(queryContext),
(_parameters, queryContext) => watch(queryContext),
sources,
routeHint);
return BindDocument(context, feed, replace);
}
/// <summary>
/// Creates a typed document handle from snapshot/watch delegates and binds it to a Verse.
/// </summary>
@ -900,6 +951,175 @@ namespace GameCult.Mesh
return Document(documentId, verse.Context, latest, watch, sources, routeHint);
}
/// <summary>
/// Creates a mutable typed document handle from snapshot/watch/replace delegates and binds it to a Verse.
/// </summary>
public static CultMeshDocumentHandle<TDocument> Document<TDocument>(
string documentId,
CultMeshVerse verse,
Func<CultMeshQueryContext, Task<TDocument>> latest,
Func<CultMeshQueryContext, R3.Observable<TDocument>> watch,
Func<TDocument, Task> replace,
IEnumerable<CultMeshProjectionSource>? sources = null,
CultMeshRouteHint? routeHint = null)
where TDocument : class
{
if (verse == null) throw new ArgumentNullException(nameof(verse));
return Document(documentId, verse.Context, latest, watch, replace, sources, routeHint);
}
/// <summary>
/// Creates a typed document handle directly over one CultCache record.
/// </summary>
public static CultMeshDocumentHandle<TDocument> Document<TDocument>(
CultCache cache,
CultRecordKey key,
CultMeshVerseContext context,
string? documentId = null,
IEnumerable<CultMeshProjectionSource>? sources = null,
CultMeshRouteHint? routeHint = null)
where TDocument : class
{
if (cache == null) throw new ArgumentNullException(nameof(cache));
if (context == null) throw new ArgumentNullException(nameof(context));
var descriptor = cache.Registry.GetRequired<TDocument>();
var sourceList = sources?.ToArray()
?? new[] { ProjectionSource(key.Value, descriptor.SchemaId, "CultCache record") };
var route = routeHint ?? new CultMeshRouteHint(CultMeshLocalityKind.InProcess, "CultCache document");
return Document<TDocument>(
ResolveDocumentId(documentId, key),
context,
_ => Task.FromResult(ReadRequired<TDocument>(cache, key)),
_ => cache.WatchRecord<TDocument>(key)
.Where(change => change.Document != null)
.Select(change => change.Document!),
async value =>
{
await cache.UpsertAsync(value, new CultRecordHandle<TDocument>(key)).ConfigureAwait(false);
},
sourceList,
route);
}
/// <summary>
/// Creates a typed document handle directly over one CultCache record.
/// </summary>
public static CultMeshDocumentHandle<TDocument> Document<TDocument>(
CultCache cache,
CultRecordKey key,
CultMeshVerse verse,
string? documentId = null,
IEnumerable<CultMeshProjectionSource>? sources = null,
CultMeshRouteHint? routeHint = null)
where TDocument : class
{
if (verse == null) throw new ArgumentNullException(nameof(verse));
return Document<TDocument>(cache, key, verse.Context, documentId, sources, routeHint);
}
/// <summary>
/// Creates a typed document handle directly over one CultCache record with a local Verse context.
/// </summary>
public static CultMeshDocumentHandle<TDocument> Document<TDocument>(
CultCache cache,
CultRecordKey key,
string? documentId = null,
IEnumerable<CultMeshProjectionSource>? sources = null,
CultMeshRouteHint? routeHint = null)
where TDocument : class
{
return Document<TDocument>(
cache,
key,
Verse("local", "local", routeHint).Context,
documentId,
sources,
routeHint);
}
/// <summary>
/// Creates a typed document handle directly over one distributed CultNet database record.
/// </summary>
public static CultMeshDocumentHandle<TDocument> Document<TDocument>(
CultNetDatabase database,
CultRecordKey key,
CultMeshVerseContext context,
string? documentId = null,
IEnumerable<CultMeshProjectionSource>? sources = null,
CultMeshRouteHint? routeHint = null)
where TDocument : class
{
if (database == null) throw new ArgumentNullException(nameof(database));
if (context == null) throw new ArgumentNullException(nameof(context));
var descriptor = CultDocumentRegistry.Shared.GetRequired<TDocument>();
var sourceList = sources?.ToArray()
?? new[] { ProjectionSource(key.Value, descriptor.SchemaId, "CultNet database record") };
var route = routeHint ?? new CultMeshRouteHint(CultMeshLocalityKind.Automatic, "CultNet database document");
return Document<TDocument>(
ResolveDocumentId(documentId, key),
context,
async _ => await ReadRequiredAsync<TDocument>(database, key).ConfigureAwait(false),
_ => database.WatchRecord<TDocument>(key)
.Where(change => change.Document != null)
.Select(change => change.Document!),
async value =>
{
await database.PutAsync(key, value).ConfigureAwait(false);
},
sourceList,
route);
}
/// <summary>
/// Creates a typed document handle directly over one distributed CultNet database record.
/// </summary>
public static CultMeshDocumentHandle<TDocument> Document<TDocument>(
CultNetDatabase database,
CultRecordKey key,
CultMeshVerse verse,
string? documentId = null,
IEnumerable<CultMeshProjectionSource>? sources = null,
CultMeshRouteHint? routeHint = null)
where TDocument : class
{
if (verse == null) throw new ArgumentNullException(nameof(verse));
return Document<TDocument>(database, key, verse.Context, documentId, sources, routeHint);
}
/// <summary>
/// Creates a typed document handle directly over one CultMesh node database record.
/// </summary>
public static CultMeshDocumentHandle<TDocument> Document<TDocument>(
CultMeshNode node,
CultRecordKey key,
CultMeshVerseContext context,
string? documentId = null,
IEnumerable<CultMeshProjectionSource>? sources = null,
CultMeshRouteHint? routeHint = null)
where TDocument : class
{
if (node == null) throw new ArgumentNullException(nameof(node));
return Document<TDocument>(node.Database, key, context, documentId, sources, routeHint);
}
/// <summary>
/// Creates a typed document handle directly over one CultMesh node database record.
/// </summary>
public static CultMeshDocumentHandle<TDocument> Document<TDocument>(
CultMeshNode node,
CultRecordKey key,
CultMeshVerse verse,
string? documentId = null,
IEnumerable<CultMeshProjectionSource>? sources = null,
CultMeshRouteHint? routeHint = null)
where TDocument : class
{
if (verse == null) throw new ArgumentNullException(nameof(verse));
return Document<TDocument>(node, key, verse.Context, documentId, sources, routeHint);
}
/// <summary>
/// Describes a typed live feed surface for tooling, UI, and diagnostics.
/// </summary>
@ -1395,5 +1615,31 @@ namespace GameCult.Mesh
return Dns.GetHostAddresses(host).FirstOrDefault()
?? throw new InvalidOperationException($"Could not resolve RUDP host {host}.");
}
private static string ResolveDocumentId(string? documentId, CultRecordKey key)
{
return string.IsNullOrWhiteSpace(documentId)
? key.Value
: documentId!;
}
private static TDocument ReadRequired<TDocument>(CultCache cache, CultRecordKey key)
where TDocument : class
{
return cache.Get<TDocument>(key)
?? throw new KeyNotFoundException(
$"CultMesh document '{key.Value}' was not found as {typeof(TDocument).FullName}.");
}
private static async Task<TDocument> ReadRequiredAsync<TDocument>(
CultNetDatabase database,
CultRecordKey key)
where TDocument : class
{
var document = await database.GetAsync<TDocument>(key).ConfigureAwait(false);
return document
?? throw new KeyNotFoundException(
$"CultMesh document '{key.Value}' was not found as {typeof(TDocument).FullName}.");
}
}
}

View file

@ -897,6 +897,9 @@ namespace GameCult.Mesh
/// <summary>Gets typed state sources this document handle depends on, when known.</summary>
IReadOnlyList<CultMeshProjectionSource> Sources { get; }
/// <summary>Gets whether this handle can replace the underlying document value.</summary>
bool CanReplace { get; }
/// <summary>Creates a same-schema alias presentation for another CLR document type.</summary>
CultMeshDocumentHandle<TAlias> AsSchemaAlias<TAlias>() where TAlias : class;
}
@ -911,11 +914,15 @@ namespace GameCult.Mesh
CultDocumentRegistry.Shared.GetRequired<TDocument>();
private readonly CultMeshBoundLiveFeed<CultMeshDocumentQueryParameters, TDocument> _feed;
private readonly Func<TDocument, Task>? _replace;
/// <summary>Creates a document handle from a Verse-bound live feed.</summary>
public CultMeshDocumentHandle(CultMeshBoundLiveFeed<CultMeshDocumentQueryParameters, TDocument> feed)
public CultMeshDocumentHandle(
CultMeshBoundLiveFeed<CultMeshDocumentQueryParameters, TDocument> feed,
Func<TDocument, Task>? replace = null)
{
_feed = feed ?? throw new ArgumentNullException(nameof(feed));
_replace = replace;
}
/// <summary>Gets the semantic document id.</summary>
@ -945,6 +952,9 @@ namespace GameCult.Mesh
/// <summary>Gets the underlying live feed used by this document handle.</summary>
public CultMeshLiveFeed<CultMeshDocumentQueryParameters, TDocument> Feed => _feed.Feed;
/// <summary>Gets whether this handle can replace the underlying document value.</summary>
public bool CanReplace => _replace != null;
/// <summary>Reads one coherent document snapshot.</summary>
public Task<TDocument> LatestAsync()
{
@ -964,6 +974,18 @@ namespace GameCult.Mesh
return Watch().Subscribe(onNext);
}
/// <summary>Replaces the underlying document when this handle is backed by mutable state.</summary>
public Task ReplaceAsync(TDocument value)
{
if (value == null) throw new ArgumentNullException(nameof(value));
if (_replace == null)
{
throw new NotSupportedException($"Document handle '{DocumentId}' is read-only.");
}
return _replace(value);
}
/// <summary>Creates a same-schema alias presentation for another CLR document type.</summary>
public CultMeshDocumentHandle<TAlias> AsSchemaAlias<TAlias>() where TAlias : class
{
@ -979,22 +1001,33 @@ namespace GameCult.Mesh
var aliasFeed = new CultMeshLiveFeed<CultMeshDocumentQueryParameters, TAlias>(
DocumentId,
async (parameters, context) => ConvertDocument<TAlias>(
async (parameters, context) => ConvertDocument<TDocument, TAlias>(
await Feed.SnapshotAsync(parameters, context).ConfigureAwait(false)),
(parameters, context) => Feed
.Watch(parameters, context)
.Select(ConvertDocument<TAlias>),
.Select(ConvertDocument<TDocument, TAlias>),
Sources,
RouteHint);
return new CultMeshDocumentHandle<TAlias>(aliasFeed.Bind(Context));
Func<TAlias, Task>? replace = _replace == null
? null
: value => _replace(ConvertDocument<TAlias, TDocument>(value));
return new CultMeshDocumentHandle<TAlias>(aliasFeed.Bind(Context), replace);
}
private static TAlias ConvertDocument<TAlias>(TDocument document) where TAlias : class
private static TTarget ConvertDocument<TSource, TTarget>(TSource document)
where TSource : class
where TTarget : class
{
if (document == null) throw new ArgumentNullException(nameof(document));
var payload = CultDocumentMessagePackSerialization.SerializeUntyped(document, typeof(TDocument));
return (TAlias)CultDocumentMessagePackSerialization.DeserializeUntyped(typeof(TAlias), payload);
if (document is TTarget alreadyTyped)
{
return alreadyTyped;
}
var payload = CultDocumentMessagePackSerialization.SerializeUntyped(document, typeof(TSource));
return (TTarget)CultDocumentMessagePackSerialization.DeserializeUntyped(typeof(TTarget), payload);
}
}

View file

@ -162,11 +162,14 @@ portable machinery that makes it feel native.
`CultMeshVerse.BindLiveFeed(...)`.
- `CultMeshDocumentHandle<TDocument>` is the typed reactive document edge for
CultCache/CultNet state. It exposes document metadata, one coherent
`LatestAsync()` read, and a `Watch()` stream without forcing callers through
transport or projection layers. Same-schema CLR aliases can be requested with
`AsSchemaAlias<TAlias>()`; CultMesh verifies the shared
`LatestAsync()` read, a `Watch()` stream, and `ReplaceAsync(...)` when the
handle is backed by mutable state. Callers can bind a projected live feed, a
local `CultCache` record, a distributed `CultNetDatabase` record, or a
`CultMeshNode` record through the same surface instead of walking transport
and projection layers themselves. Same-schema CLR aliases can be requested
with `AsSchemaAlias<TAlias>()`; CultMesh verifies the shared
`[CultDocument(schemaName, schemaVersion)]` identity and uses the shared
CultCache MessagePack codec for conversion.
CultCache MessagePack codec for read/watch/replace conversion.
- `CultMeshProjectionRecipe<TParameters, TResult>` names a reusable projection
from typed source state into derived state. It records source handles,
route hints, and projection execution, and can be exposed as a typed query
@ -216,6 +219,22 @@ await movePilot.InvokeAsync(moveRequest, idempotencyKey);
A single typed document can be surfaced the same way:
```csharp
var stationStock = CultMesh.Document<StationStockDocument>(
node,
new CultRecordKey("station:starbridge:stock"),
verse);
var stock = await stationStock.LatestAsync();
using var watch = stationStock.Watch(RenderStock);
var uiAlias = stationStock.AsSchemaAlias<StationStockUiDocument>();
await uiAlias.ReplaceAsync(updatedStockFromUi);
```
Projected or derived documents can use the same handle shape with explicit
snapshot/watch delegates:
```csharp
var cockpit = CultMesh.Document(
"aetheria.ship.cockpit.current",

View file

@ -5,6 +5,7 @@ using System.Linq;
using System.Threading.Tasks;
using FluentAssertions;
using GameCult.Caching;
using GameCult.Networking;
using MessagePack;
using NUnit.Framework;
using R3;
@ -697,6 +698,92 @@ public sealed class CultMeshStreamingTests
.WithMessage("*tests.mesh_other*tests.mesh_note*");
}
[Test]
public async Task DocumentHandle_ReadsWatchesAndReplacesCultCacheRecords()
{
var cache = new CultCache();
var key = new CultRecordKey("mesh-note:cache");
await cache.UpsertAsync(new MeshNoteDocument
{
Schema = "tests.mesh_note.v1",
Text = "cache-initial",
Revision = 1
}, new CultRecordHandle<MeshNoteDocument>(key));
var handle = CultMesh.Document<MeshNoteDocument>(
cache,
key,
CultMesh.Verse("starbridge", "unity-pilot"));
var alias = handle.AsSchemaAlias<MeshNoteAliasDocument>();
handle.CanReplace.Should().BeTrue();
alias.CanReplace.Should().BeTrue();
handle.DocumentId.Should().Be(key.Value);
handle.Sources.Should().ContainSingle().Which.SchemaId.Should().Be(handle.SchemaId);
var snapshot = await alias.LatestAsync();
snapshot.Text.Should().Be("cache-initial");
MeshNoteAliasDocument observed = null!;
using var subscription = alias.Watch(value => observed = value);
await alias.ReplaceAsync(new MeshNoteAliasDocument
{
Schema = "tests.mesh_note.v1",
Text = "cache-replaced",
Revision = 2
});
cache.Get<MeshNoteDocument>(key)!.Text.Should().Be("cache-replaced");
observed.Text.Should().Be("cache-replaced");
observed.Revision.Should().Be(2);
}
[Test]
public async Task DocumentHandle_ReplacesThroughCultMeshNodeDatabase()
{
using var directory = new TemporaryDirectory();
using var node = await CultMesh.CreateNodeAsync(
Path.Combine(directory.Path, "mesh-node.cc"),
new CultMeshNodeOptions
{
DatabaseOptions = new CultNetDatabaseOptions
{
RuntimeId = "node-runtime",
Shards = new[]
{
new CultNetShardDescriptor(
"mesh",
"node-runtime",
epoch: 1,
isPrimary: true,
schemaIds: new[] { CultDocumentRegistry.Shared.GetRequired<MeshNoteDocument>().SchemaId })
}
},
StartServer = false
});
var key = new CultRecordKey("mesh-note:node");
var handle = CultMesh.Document<MeshNoteDocument>(
node,
key,
CultMesh.Verse("starbridge", "unity-pilot"));
var alias = handle.AsSchemaAlias<MeshNoteAliasDocument>();
MeshNoteDocument observed = null!;
using var subscription = handle.Watch(value => observed = value);
await alias.ReplaceAsync(new MeshNoteAliasDocument
{
Schema = "tests.mesh_note.v1",
Text = "node-replaced",
Revision = 3
});
var snapshot = await handle.LatestAsync();
snapshot.Text.Should().Be("node-replaced");
observed.Text.Should().Be("node-replaced");
observed.Revision.Should().Be(3);
}
[Test]
public void SurfaceCatalog_DescribesTypedRuntimeSurfaces()
{
@ -1039,6 +1126,27 @@ public sealed class CultMeshStreamingTests
return catalog;
}
private sealed class TemporaryDirectory : IDisposable
{
public TemporaryDirectory()
{
Path = System.IO.Path.Combine(
System.IO.Path.GetTempPath(),
"cultmesh-tests-" + Guid.NewGuid().ToString("N"));
Directory.CreateDirectory(Path);
}
public string Path { get; }
public void Dispose()
{
if (Directory.Exists(Path))
{
Directory.Delete(Path, recursive: true);
}
}
}
[CultDocument("tests.mesh_managed_player", "tests.mesh_managed_player.v1")]
private sealed class MeshManagedPlayer
{