GameCult/CultLib
Watch
9
0
Fork
You've already forked CultLib
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Prefer direct alias remote snapshot handles

Browse source
This commit is contained in:
Meta Vens 2026-06-27 22:53:45 +01:00
commit 672f59dba0
2 changed files with 17 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

23
src/GameCult.Mesh/docs/public-api.md
View file

@ -287,19 +287,20 @@ id, response filtering, raw MessagePack payload decode, route metadata, and
polling watch fallback:
```csharp
var remoteHealth = CultMesh.DocumentFromPeerSnapshot<DaemonHealthDocument>(
var remoteHealth = CultMesh.DocumentFromPeerSnapshot<DaemonHealthUiDocument>(
"cultnet://daemon.local:3075",
"daemon:aetheria.health.v1",
verse);
var health = await remoteHealth.LatestAsync();
var uiHealth = remoteHealth.AsSchemaAlias<DaemonHealthUiDocument>();
var uiHealth = await remoteHealth.LatestAsync();
```
Snapshot requests are record-key-first so same logical documents can still be
read when another runtime generated a different schema id for a compatible
schema alias. The decode path prefers exact schema id matches when present and
falls back to the requested record key.
falls back to the requested record key. Ask for the runtime-facing alias type
directly; `AsSchemaAlias<TAlias>()` is for adapting handles that were already
constructed elsewhere.
A domain facade can still collect existing handles into one schema-aware
catalog when it is composing pre-built surfaces:
@ -368,7 +369,7 @@ const stopRoster = pilots.watchChanges(change => refreshRoster(change));
const remoteHealth = CultMesh.documentFromPeerSnapshot(
() => daemonPeer,
"gamecult.aetheria.daemon_health.v1",
daemonHealthUiDocument,
"daemon:aetheria.health.v1",
);
const health = await remoteHealth.latest();
@ -503,12 +504,12 @@ fragmentation, and channel semantics.
TypeScript runtimes can also wrap a CultNet peer snapshot as a normal document
handle with `CultMesh.documentFromPeerSnapshot(...)`. The caller supplies the
peer or peer factory, schema id, and record key; CultMesh sends the snapshot
request, waits for the matching response, decodes the raw MessagePack document,
and returns the same `latest()`/`watch()` document surface used by local cache
and single-file documents. Exact schema ids are preferred, but record-key
publications remain readable when two runtimes alias the same logical document
through different schema names.
peer or peer factory, document definition or schema id, and record key; CultMesh
sends the snapshot request, waits for the matching response, decodes the raw
MessagePack document, and returns the same `latest()`/`watch()` document surface
used by local cache and single-file documents. Exact schema ids are preferred,
but record-key publications remain readable when two runtimes alias the same
logical document through different schema names.
### Shard Authority

10
tests/GameCult.Mesh.Tests/CultMeshStreamingTests.cs
View file

@ -2203,7 +2203,7 @@ public sealed class CultMeshStreamingTests
.Register(CultNetDocumentBinding.ForDocument<MeshNoteDocument>(CultDocumentRegistry.Shared));
var requests = new List<CultNetSnapshotRequestMessage>();
var handle = CultMesh.DocumentFromPublication<MeshNoteDocument>(
var handle = CultMesh.DocumentFromPublication<MeshNoteAliasDocument>(
CultMeshDocumentPublicationSource.PeerSnapshot(
() => new MeshSnapshotSchemaClient(request =>
{
@ -2218,13 +2218,13 @@ public sealed class CultMeshStreamingTests
PollInterval = TimeSpan.FromMilliseconds(10),
MessageIdPrefix = "mesh-test-snapshot"
});
var alias = handle.AsSchemaAlias<MeshNoteAliasDocument>();
var catalog = CultMesh.Documents(handle);
var snapshot = await alias.LatestAsync();
var snapshot = await handle.LatestAsync();
snapshot.Text.Should().Be("remote-snapshot");
snapshot.Revision.Should().Be(9);
handle.DocumentType.Should().Be(typeof(MeshNoteAliasDocument));
handle.RouteHint.Kind.Should().Be(CultMeshLocalityKind.Network);
handle.Sources.Should().ContainSingle().Which.SourceId.Should().Be(key.Value);
requests.Should().ContainSingle();
@ -2233,7 +2233,7 @@ public sealed class CultMeshStreamingTests
requests[0].RecordKeys.Should().ContainSingle().Which.Should().Be(key.Value);
(await catalog.LatestAsync<MeshNoteAliasDocument>()).Text.Should().Be("remote-snapshot");
var aliasSchemaHandle = CultMesh.DocumentFromPeerSnapshot<MeshNoteDocument>(
var aliasSchemaHandle = CultMesh.DocumentFromPeerSnapshot<MeshNoteAliasDocument>(
_ => Task.FromResult(new CultNetSnapshotResponseRawMessage
{
MessageId = "alias-schema",
@ -2261,7 +2261,7 @@ public sealed class CultMeshStreamingTests
(await aliasSchemaHandle.LatestAsync()).Text.Should().Be("record-key-fallback");
var mixedAliasSchemaHandle = CultMesh.DocumentFromPeerSnapshot<MeshNoteDocument>(
var mixedAliasSchemaHandle = CultMesh.DocumentFromPeerSnapshot<MeshNoteAliasDocument>(
_ => Task.FromResult(new CultNetSnapshotResponseRawMessage
{
MessageId = "alias-schema-with-neighbor",