Make Eve onboarding one coherent game
This commit is contained in:
parent
b0a876a220
commit
e74ba6e94c
9 changed files with 161 additions and 152 deletions
|
|
@ -29,8 +29,9 @@ temporary consumer, and runs `sample.mjs`. Success proves:
|
|||
4. the DOM binding and a separate headless observer converge on the same count;
|
||||
5. the canonical receipt and state survive reopening the `.cc` store.
|
||||
|
||||
This is not yet the promised networked multiplayer tutorial. The DOM lowerer is
|
||||
hosted by jsdom in Node and both consumers share one local CultMesh node. A real
|
||||
browser transport, Odin discovery, process separation, and a second language
|
||||
runtime require distinct executable gates. Keeping that limitation visible is
|
||||
part of the sample contract.
|
||||
This artifact checkpoint is deliberately not the network proof. The DOM lowerer
|
||||
is hosted by jsdom in Node and both consumers share one local CultMesh node. The
|
||||
same wrapper continues into a separate real Chromium/C# process chronology with
|
||||
Odin discovery, route replacement, and persistent provider state. Keeping those
|
||||
evidence layers separate prevents a fast package test from impersonating the
|
||||
network.
|
||||
|
|
|
|||
|
|
@ -18,12 +18,25 @@ simulation observations.
|
|||
## First Node
|
||||
|
||||
```csharp
|
||||
using GameCult.Caching;
|
||||
using GameCult.Mesh;
|
||||
using GameCult.Networking;
|
||||
|
||||
using var node = await CultMesh.StartNodeAsync("world.ccmp");
|
||||
// CounterState is the typed document defined in the getting-started tutorial.
|
||||
var documents = new CultNetDocumentRegistry()
|
||||
.Register(CultNetDocumentBinding.ForDocument<CounterState>());
|
||||
using var node = await CultMesh.StartNodeAsync("world.cc", new CultMeshNodeOptions
|
||||
{
|
||||
DatabaseOptions = new CultNetDatabaseOptions
|
||||
{
|
||||
RuntimeId = "counter-provider",
|
||||
DocumentRegistry = documents
|
||||
}
|
||||
});
|
||||
|
||||
var player = await node.Database.GetAsync<PlayerData>(playerKey);
|
||||
await node.Database.PutAsync(playerKey, player);
|
||||
var key = new CultRecordKey("counter:main");
|
||||
await node.Database.PutAsync(key, new CounterState { CounterId = key.Value });
|
||||
var counter = await node.Database.GetAsync<CounterState>(key);
|
||||
```
|
||||
|
||||
If you want one inspectable path that starts with a durable local cache file and
|
||||
|
|
@ -88,7 +101,7 @@ Enable durable authoritative shard logs when a node should serve replica
|
|||
catch-up after restart:
|
||||
|
||||
```csharp
|
||||
using var node = await CultMesh.StartNodeAsync("world.ccmp", new CultMeshNodeOptions
|
||||
using var node = await CultMesh.StartNodeAsync("world.cc", new CultMeshNodeOptions
|
||||
{
|
||||
EnableDurableShardLogs = true
|
||||
});
|
||||
|
|
@ -240,7 +253,7 @@ shape without local store plumbing:
|
|||
|
||||
```csharp
|
||||
var health = CultMesh.DocumentFromSingleFile<DaemonHealth>(
|
||||
"daemon-publication.ccmp",
|
||||
"daemon-publication.cc",
|
||||
new CultRecordKey("daemon:aetheria.health.v1"),
|
||||
verse);
|
||||
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@ var key = new CultRecordKey("note:intro");
|
|||
var documents = new CultNetDocumentRegistry()
|
||||
.Register(CultNetDocumentBinding.ForDocument<MeshNote>());
|
||||
|
||||
using (var node = await CultMesh.CreateNodeAsync("world.ccmp", new CultMeshNodeOptions
|
||||
using (var node = await CultMesh.CreateNodeAsync("world.cc", new CultMeshNodeOptions
|
||||
{
|
||||
DatabaseOptions = new CultNetDatabaseOptions
|
||||
{
|
||||
|
|
@ -76,7 +76,7 @@ using (var node = await CultMesh.CreateNodeAsync("world.ccmp", new CultMeshNodeO
|
|||
await node.FlushAsync();
|
||||
}
|
||||
|
||||
using (var reopened = await CultMesh.CreateNodeAsync("world.ccmp", new CultMeshNodeOptions
|
||||
using (var reopened = await CultMesh.CreateNodeAsync("world.cc", new CultMeshNodeOptions
|
||||
{
|
||||
DatabaseOptions = new CultNetDatabaseOptions
|
||||
{
|
||||
|
|
@ -92,7 +92,7 @@ using (var reopened = await CultMesh.CreateNodeAsync("world.ccmp", new CultMeshN
|
|||
|
||||
What happened:
|
||||
|
||||
1. `CultMesh.CreateNodeAsync("world.ccmp", ...)` opened a durable CultCache
|
||||
1. `CultMesh.CreateNodeAsync("world.cc", ...)` opened a durable CultCache
|
||||
snapshot file and wrapped it in a CultMesh node.
|
||||
2. `node.Database.PutAsync(...)` wrote a typed document through the public
|
||||
CultMesh database surface.
|
||||
|
|
@ -105,7 +105,7 @@ What happened:
|
|||
|
||||
If you peel this path apart, the authority split stays simple:
|
||||
|
||||
- CultCache: `world.ccmp`, schema ids, record keys, typed document payloads,
|
||||
- CultCache: `world.cc`, schema ids, record keys, typed document payloads,
|
||||
local indexes, flush/load
|
||||
- CultNet: `CultNetDocumentRegistry`, raw document puts/snapshots,
|
||||
subscriptions, shard routing, transport-facing replication
|
||||
|
|
|
|||
|
|
@ -1,22 +1,71 @@
|
|||
# 1. Persist Typed Application State
|
||||
# 1. Persist The Counter
|
||||
|
||||
Start with a typed CultCache document and a durable CultMesh node. The complete
|
||||
sample is [the durable node quickstart](../durable-node-quickstart.md).
|
||||
The tutorial builds one application all the way through: a provider-owned
|
||||
counter, an Increment operation, one browser lowerer, and one C# headless
|
||||
client. Start with the state the provider actually owns.
|
||||
|
||||
At the end of that guide you should have:
|
||||
```csharp
|
||||
using GameCult.Caching;
|
||||
using GameCult.Caching.MessagePack;
|
||||
using GameCult.Networking;
|
||||
using MessagePack;
|
||||
|
||||
- a document type with a stable schema id;
|
||||
- a `CultMeshNode` whose database owns the live local document;
|
||||
- a `.cc`/CultCache-backed durable state path;
|
||||
- a restart proof that reads the same typed document.
|
||||
[CultDocument("sample.counter_state", "sample.counter_state.v1")]
|
||||
[MessagePackObject]
|
||||
public sealed class CounterState
|
||||
{
|
||||
[Key("counterId")] public string CounterId { get; set; } = "";
|
||||
[Key("count")] public int Count { get; set; }
|
||||
}
|
||||
```
|
||||
|
||||
Do not create an Eve-shaped copy of this state. The Eve surface published in
|
||||
chapter 3 points at typed records and commands owned by the provider.
|
||||
Open a `.cc` store, register the document once, and write through the CultMesh
|
||||
database boundary:
|
||||
|
||||
Verification:
|
||||
```csharp
|
||||
var key = new CultRecordKey("counter:main");
|
||||
var registry = CultDocumentRegistry.ForTypes([typeof(CounterState)]);
|
||||
|
||||
using var cache = await CultCacheMessagePack.OpenAsync("counter.cc", new CultCacheOpenOptions
|
||||
{
|
||||
Registry = registry,
|
||||
FlushOnDispose = true,
|
||||
StoreFlushOnDispose = true
|
||||
});
|
||||
var documents = new CultNetDocumentRegistry(registry)
|
||||
.Register(CultNetDocumentBinding.ForDocument<CounterState>(
|
||||
registry,
|
||||
"sample.counter_state.v1"));
|
||||
using var database = new CultNetDatabase(cache, new CultNetDatabaseOptions
|
||||
{
|
||||
RuntimeId = "sample.counter-provider",
|
||||
DocumentRegistry = documents
|
||||
});
|
||||
|
||||
await database.PutAsync(key, new CounterState
|
||||
{
|
||||
CounterId = key.Value,
|
||||
Count = 0
|
||||
});
|
||||
await cache.FlushAsync();
|
||||
```
|
||||
|
||||
CultCache owns durable local truth. CultNet owns the portable schema mapping.
|
||||
CultMesh exposes the database and later carries subscriptions and operations.
|
||||
The renderer owns none of them.
|
||||
|
||||
The executable provider adds its receipt index to this document so the counter
|
||||
mutation and idempotency decision are committed together. See
|
||||
[`samples/eve-browser-network/Program.cs`](../../../../samples/eve-browser-network/Program.cs)
|
||||
for the exact running type and transaction.
|
||||
|
||||
Fast persistence check:
|
||||
|
||||
```powershell
|
||||
dotnet test tests/GameCult.Networking.Tests/GameCult.Networking.Tests.csproj --filter FullyQualifiedName~CultMeshNode_CanRoundTrip_DurableTypedDocument_Through_PublicDatabaseSurface
|
||||
```
|
||||
|
||||
This check proves the local typed state boundary. Chapter 4 boots the real
|
||||
provider and proves the same state across Chromium and C# after restart.
|
||||
|
||||
Next: [connect a client by stable identity](02-connect-by-identity.md).
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
# 2. Connect A Client By Stable Identity
|
||||
|
||||
Clients address a provider or Verse by stable identity. Discovery owns the
|
||||
Clients address a Verse session by stable identity. In this tutorial,
|
||||
`sample.counter-provider` is the sole authority runtime Odin advertises for the
|
||||
`sample.counter` Verse; neither identity is a socket address. Discovery owns
|
||||
current physical candidates and the session manager owns connection reuse,
|
||||
path rotation, and transport failure state.
|
||||
|
||||
|
|
@ -13,7 +15,7 @@ using var mesh = new CultMeshClient(new CultMeshClientOptions
|
|||
});
|
||||
|
||||
using var counterLease = await mesh.LeaseDocumentAsync<CounterState>(
|
||||
"sample.counter-provider",
|
||||
"sample.counter",
|
||||
"counter:main",
|
||||
cancellationToken);
|
||||
var counter = counterLease.Handle;
|
||||
|
|
@ -49,7 +51,8 @@ using var stateWatch = session.WatchState().Subscribe(state =>
|
|||
Application code does not reconnect, sleep, rank endpoints, or replace the
|
||||
session. Those decisions belong to CultMesh.
|
||||
|
||||
Verification:
|
||||
Fast session-management check (this uses controlled transports; it is not the
|
||||
network proof):
|
||||
|
||||
```powershell
|
||||
dotnet test tests/GameCult.Mesh.Tests/GameCult.Mesh.Tests.csproj --filter FullyQualifiedName~CultMeshSessionManagerTests
|
||||
|
|
@ -59,4 +62,7 @@ Advanced hosts may inject lookup sources, connectors, clocks, persistence, and
|
|||
diagnostics through the lower-level discovery and session APIs. Application
|
||||
features should not need them.
|
||||
|
||||
Chapter 4 runs the real network chronology and proves that the retained lease
|
||||
survives Odin moving `sample.counter` to a new physical provider route.
|
||||
|
||||
Next: [publish one Eve surface to multiple runtimes](03-publish-an-eve-surface.md).
|
||||
|
|
|
|||
|
|
@ -1,122 +0,0 @@
|
|||
# 4. Keep A TypeScript Provider Alive
|
||||
|
||||
A provider process should declare desired typed publications and domain command
|
||||
handlers once. It should not rebuild discovery registration, lease renewal,
|
||||
reconnect, republish, receipt delivery, and withdrawal loops in a renderer or
|
||||
scheduled export script.
|
||||
|
||||
`CultMeshProviderSession` owns that lifecycle. The application still owns its
|
||||
state and command transaction. A transport connector owns the physical CultNet
|
||||
route. Eve advertisements and surfaces are ordinary typed publications; the
|
||||
session does not import Eve or learn provider gameplay.
|
||||
|
||||
```ts
|
||||
import {
|
||||
CultMeshProviderSession,
|
||||
type CultMeshProviderReceiptStore,
|
||||
type CultMeshProviderTransport,
|
||||
} from "cultmesh-ts";
|
||||
|
||||
export async function runProvider(
|
||||
transport: CultMeshProviderTransport,
|
||||
receipts: CultMeshProviderReceiptStore,
|
||||
) {
|
||||
const provider = new CultMeshProviderSession({
|
||||
identity: {
|
||||
providerId: "voidbot.swarm",
|
||||
serviceInstanceId: "voidbot-worker-7",
|
||||
endpointId: "odin:voidbot-worker-7",
|
||||
verseId: "voidbot.local",
|
||||
},
|
||||
transport,
|
||||
receiptStore: receipts,
|
||||
publications: [
|
||||
{
|
||||
publicationId: "voidbot.swarm.advertisement",
|
||||
documentType: "gamecult.eve.provider_advertisement",
|
||||
schemaId: "gamecult.eve.provider_advertisement.v1",
|
||||
recordKey: "voidbot.swarm",
|
||||
value: providerAdvertisement,
|
||||
},
|
||||
{
|
||||
publicationId: "voidbot.swarm.surface",
|
||||
documentType: "gamecult.eve.surface_state",
|
||||
schemaId: "gamecult.eve.surface_state.v1",
|
||||
recordKey: "voidbot.swarm",
|
||||
value: currentSurface,
|
||||
},
|
||||
],
|
||||
commandHandlers: {
|
||||
"swarm.set_heat": async command =>
|
||||
applyHeatCommandTransaction(command.commandId, command.payload),
|
||||
},
|
||||
});
|
||||
|
||||
await provider.start();
|
||||
|
||||
await provider.upsertPublication({
|
||||
publicationId: "voidbot.swarm.surface",
|
||||
documentType: "gamecult.eve.surface_state",
|
||||
schemaId: "gamecult.eve.surface_state.v1",
|
||||
recordKey: "voidbot.swarm",
|
||||
value: nextSurface,
|
||||
});
|
||||
|
||||
process.once("SIGTERM", () => {
|
||||
provider.stop().catch(error => {
|
||||
console.error("CultMesh provider shutdown completed with cleanup failures.", error);
|
||||
process.exitCode = 1;
|
||||
});
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
The four identities are deliberately distinct:
|
||||
|
||||
- `providerId` names the product capability clients select;
|
||||
- `serviceInstanceId` names the running owner incarnation;
|
||||
- `endpointId` names the stable discovery/session route.
|
||||
- `verseId` names the discovery and state-sharing domain.
|
||||
|
||||
Do not replace any of them with a process id, socket address, body producer id,
|
||||
or renderer id.
|
||||
|
||||
## Receipt Rule
|
||||
|
||||
The receipt store is required and must be durable in a daemon. The in-memory
|
||||
store exported by the package is for tests and disposable tools only. The
|
||||
domain command handler must apply its mutation idempotently using `commandId`;
|
||||
the provider session deduplicates delivery and republishes the stored typed
|
||||
receipt, but it cannot make an unrelated database mutation atomic by wishing
|
||||
at it harder. `commandId` is the idempotency key: later delivery of the same
|
||||
provider, service-instance, and command kind returns the original receipt even
|
||||
if a sender incorrectly changes the payload. Reusing the ID for another kind
|
||||
or identity is rejected as a conflict.
|
||||
|
||||
The store is also the receipt outbox. `put` commits the receipt before any wire
|
||||
publication. `listPending` supplies receipts after startup or reconnect, and
|
||||
`markPublished` removes one only after the active connection accepts it. Scope
|
||||
the store to the provider and service-instance identity. If the store is
|
||||
unavailable, the session enters `degraded` and stops accepting commands until a
|
||||
renewal can drain the outbox again; a store failure is not a transport failure.
|
||||
|
||||
## Verification Checkpoint
|
||||
|
||||
Use an injected scheduler and transport fault double to prove the actual
|
||||
lifecycle:
|
||||
|
||||
1. initial registration publishes every desired document in stable order;
|
||||
2. lease renewal occurs before expiry;
|
||||
3. a failed route produces `reconnecting`, then republishes current desired
|
||||
state on the replacement connection;
|
||||
4. duplicate command delivery runs one handler transaction and republishes the
|
||||
same receipt;
|
||||
5. failed receipt transport reconnects and replays the durable outbox exactly
|
||||
until `markPublished` succeeds;
|
||||
6. shutdown drains command persistence, withdraws the lease and remaining
|
||||
publications, and closes even when cleanup reports failures;
|
||||
7. stopping during registration cannot let the stale connection publish;
|
||||
8. observers and conflicting command IDs cannot become lifecycle authorities.
|
||||
|
||||
The package suite contains this timeline in
|
||||
`packages/cultmesh-ts/test/provider-session.test.ts`.
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
# 4. Run The Multi-Runtime Game
|
||||
|
||||
The counter is now one small multiplayer game:
|
||||
|
||||
- a C# provider owns `CounterState`, Increment, idempotency, receipts, the
|
||||
`.cc` store, and the Eve surface;
|
||||
- Chromium discovers that provider through Odin, lowers the surface, and
|
||||
invokes Increment;
|
||||
- an independent C# client leases the same counter and invokes through the same
|
||||
typed operation boundary;
|
||||
- both clients remain attached when Odin moves the provider identity to a new
|
||||
physical route.
|
||||
|
||||
Run the whole chronology from the CultLib checkout:
|
||||
|
||||
```powershell
|
||||
pwsh -File ./scripts/verify-eve-getting-started.ps1
|
||||
```
|
||||
|
||||
The command owns setup and teardown. Do not start Odin, the provider, or the
|
||||
browser by hand. A successful run prints two JSON records followed by:
|
||||
|
||||
```text
|
||||
Eve getting-started verification passed: clean artifacts, DOM and headless convergence, real Chromium and C# clients, Odin discovery, receipts, persistence, and route replacement.
|
||||
```
|
||||
|
||||
## What The Command Proves
|
||||
|
||||
The first checkpoint packs the TypeScript CultCache, CultNet, CultMesh, and Eve
|
||||
packages, installs those artifacts into an empty temporary consumer, and proves
|
||||
DOM/headless convergence plus `.cc` reopen. This rejects a sample that only
|
||||
works through repository-relative source imports.
|
||||
|
||||
The second checkpoint boots separate Odin, provider, Chromium, and C# headless
|
||||
processes. Chromium performs the first increment. The provider then restarts on
|
||||
a different route, Odin advertises the replacement, and the retained clients
|
||||
resubscribe without application reconnect code. C# performs the second
|
||||
increment. Both clients must observe count 2 and both canonical receipt ids.
|
||||
|
||||
Finally, the retained C# session sends 10,000 typed no-op operations. The gate
|
||||
records throughput, p99 latency, managed-heap growth, and private-memory growth.
|
||||
It fails at 250 ms p99 or more than 8 MiB post-GC managed growth.
|
||||
|
||||
## What It Does Not Prove
|
||||
|
||||
The included Odin is a real CultNet Verse-catalog provider but still a local
|
||||
fixture. It does not prove deployed GameCult infrastructure. The package layer
|
||||
uses packed checkout artifacts until the package owners publish the named npm
|
||||
packages. Those are explicit release gates, not reasons to put endpoint or
|
||||
source-tree fallbacks into application code.
|
||||
|
||||
The process harness lives in
|
||||
[`samples/eve-browser-network`](../../../../samples/eve-browser-network/README.md).
|
||||
Application code should copy the typed state, operation, and Eve composition
|
||||
shape—not its benchmark flags or fixture orchestration.
|
||||
|
||||
For a TypeScript provider daemon, continue with the
|
||||
[`CultMeshProviderSession` guide](../../../../packages/cultmesh-ts/README.md#long-lived-providers).
|
||||
That lifecycle is an alternative provider runtime for the same ownership
|
||||
model, not a fifth chapter that changes this tutorial into a different product.
|
||||
|
|
@ -29,7 +29,7 @@ Follow the chapters in order:
|
|||
1. [Persist typed application state](01-persist-typed-state.md)
|
||||
2. [Connect a client by stable identity](02-connect-by-identity.md)
|
||||
3. [Publish one Eve surface to multiple runtimes](03-publish-an-eve-surface.md)
|
||||
4. [Keep a TypeScript provider alive](04-keep-a-typescript-provider-alive.md)
|
||||
4. [Run the multi-runtime game](04-run-the-multiruntime-game.md)
|
||||
|
||||
The intended application shape is small:
|
||||
|
||||
|
|
@ -39,6 +39,8 @@ provider daemon -> typed CultCache documents -> CultMesh advertisement
|
|||
+------------------------+--------------------+
|
||||
| | |
|
||||
Eve browser EveUnity another lowerer
|
||||
| | |
|
||||
player input player input headless / AI
|
||||
```
|
||||
|
||||
The provider owns live truth. Eve owns the surface contract. Each runtime owns
|
||||
|
|
|
|||
|
|
@ -109,7 +109,7 @@ messages directly.
|
|||
```csharp
|
||||
using GameCult.Mesh;
|
||||
|
||||
using var node = await CultMesh.CreateNodeAsync("world.ccmp", new CultMeshNodeOptions
|
||||
using var node = await CultMesh.CreateNodeAsync("world.cc", new CultMeshNodeOptions
|
||||
{
|
||||
DatabaseOptions = new CultNetDatabaseOptions
|
||||
{
|
||||
|
|
|
|||
Loading…
Reference in a new issue