Modularize CultMesh transport planes
This commit is contained in:
parent
434db81e43
commit
c16163a82f
19 changed files with 2162 additions and 171 deletions
|
|
@ -2,6 +2,8 @@
|
|||
|
||||
Incident record: [CultMesh bulk content over custom RUDP, July 2026](postmortem-2026-07-cultmesh-bulk-rudp.md).
|
||||
|
||||
Physical-plane authority: [CultMesh transport planes](transport-planes.md).
|
||||
|
||||
## Objective
|
||||
|
||||
CultMesh should give an application one typed, watchable route to a Verse,
|
||||
|
|
@ -676,16 +678,17 @@ body in process.
|
|||
**Owner:** CultMesh negotiation selects a body transport from provider-owned
|
||||
capabilities and consumer demand. The selected transport owns byte movement;
|
||||
`CultMeshContentTransferService` continues to own content identity, resumable
|
||||
verification, and atomic cache promotion. CultNet RUDP does not own bulk-body
|
||||
performance.
|
||||
verification, and atomic cache promotion. TCP owns remote immutable content;
|
||||
CultNet RUDP does not own bulk-body performance.
|
||||
|
||||
**Inputs:** content hash and size, provider-advertised transport candidates,
|
||||
consumer-supported transports, same-machine evidence, and platform support.
|
||||
|
||||
**Outputs:** an authorized mapped body for same-machine deployments, or a
|
||||
dedicated remote byte stream feeding the existing verification/promotion owner.
|
||||
Typed control state, reactive variables, commands, and receipts remain CultNet
|
||||
messages and are not smuggled into the bulk stream.
|
||||
dedicated TCP byte stream feeding the existing verification/promotion owner.
|
||||
Schemas, commands, receipts, and manifests use framed TCP CultNet messages.
|
||||
Realtime state uses a separately negotiated QUIC stream or datagram and is not
|
||||
smuggled through either snapshots or the immutable-content stream.
|
||||
|
||||
**Derived state:** selected plane, physical endpoint, mapped-file descriptor,
|
||||
stream progress, and transport telemetry. None can change content identity,
|
||||
|
|
|
|||
74
src/GameCult.Mesh/docs/transport-planes.md
Normal file
74
src/GameCult.Mesh/docs/transport-planes.md
Normal file
|
|
@ -0,0 +1,74 @@
|
|||
# CultMesh Transport Planes
|
||||
|
||||
CultMesh selects a transport per workload. It does not ask one wire protocol to
|
||||
be equally good at files, realtime state, and same-machine memory access.
|
||||
|
||||
## Authority map
|
||||
|
||||
**Owner:** `CultMeshSessionManager` selects an advertised route through a
|
||||
registered connector for each traffic class. A connector owns only its physical
|
||||
connection and byte movement.
|
||||
|
||||
**Inputs:** stable endpoint identity, advertised physical candidates, connector
|
||||
support and priority, caller cancellation, and locality evidence for body
|
||||
negotiation.
|
||||
|
||||
**Outputs:**
|
||||
|
||||
| Workload | Preferred plane | Contract |
|
||||
| --- | --- | --- |
|
||||
| Schemas, commands, receipts, manifests | TCP | `cultnet+tcp://` through `ICultMeshTransportConnector` |
|
||||
| Immutable chunks and other file-shaped bodies | TCP byte stream | `cultmesh-content+tcp://` through `ICultMeshContentTransportConnector` |
|
||||
| Realtime state | QUIC streams or datagrams | `ICultMeshRealtimeTransportConnector` with an explicit delivery mode |
|
||||
| Same-machine SoA and large bodies | mapped/shared memory | body transport negotiation |
|
||||
|
||||
The TCP content plane sends typed CultNet request and response headers, then
|
||||
streams raw chunk bytes outside the schema envelope. The transfer service owns
|
||||
range hashing, resume checkpoints, provider failover, full-body verification,
|
||||
and atomic promotion regardless of the selected content connector.
|
||||
`CultMeshClient` installs the TCP schema and TCP content connectors by default.
|
||||
Passing explicit connector lists replaces those defaults.
|
||||
|
||||
Realtime frames declare whether they require reliable ordered delivery,
|
||||
latest-only delivery, or unreliable delivery. The contract is ready for a QUIC
|
||||
connector; no RUDP implementation is installed implicitly in its place.
|
||||
|
||||
**Derived state:** connector choice, physical endpoint, connection health, and
|
||||
transport diagnostics. None of these grant provider authority or become content
|
||||
identity.
|
||||
|
||||
**Forbidden writers:** applications and renderers do not choose unadvertised
|
||||
endpoints, implement reconnect loops, or bypass verification. Schema messages
|
||||
must not carry bulk bodies. RUDP/LiteNetLib cannot become an implicit default
|
||||
for any traffic class. QUIC does not own schemas or immutable files merely
|
||||
because it can transport bytes.
|
||||
|
||||
**Shared paths:** discovery and identity resolution remain common. Each traffic
|
||||
class has its own connector set, connection cache, priority tiers, and failure
|
||||
state. All content connectors feed the same transfer and promotion owner.
|
||||
|
||||
**Cut line:** the former RUDP content server is
|
||||
`CultMeshLegacyRudpContentServer`, and its connector must be registered
|
||||
explicitly. It has basement priority and exists for compatibility and parity
|
||||
measurement. The legacy datagram schema connector is likewise explicit and
|
||||
lower priority than TCP. Existing hot-state publishers that still package
|
||||
payloads as schema messages must move to the realtime connector contract; the
|
||||
new seam does not pretend that migration has already occurred.
|
||||
|
||||
## Security and release gate
|
||||
|
||||
The current TCP connectors are a local-development transport and are plaintext.
|
||||
Remote release requires authenticated encryption and binding the authenticated
|
||||
peer to the advertised provider identity. Adding TLS must not move discovery,
|
||||
authorization, content verification, or application semantics into the TCP
|
||||
adapter.
|
||||
|
||||
## Local parity evidence
|
||||
|
||||
On 2026-07-19, the parity harness moved a 13 MiB payload on loopback using
|
||||
1 MiB content chunks. Raw TCP reached 127.4 MiB/s, verified CultMesh TCP content
|
||||
reached 59.0 MiB/s, raw MsQuic reached 51.5 MiB/s, and legacy CultMesh RUDP
|
||||
reached 10.7 MiB/s while emitting 18,112,867 wire bytes. CultMesh TCP includes
|
||||
chunk hashing, durable checkpoints, final hashing, and atomic promotion, so this
|
||||
is not a claim of raw protocol parity. It is a repeatable workload comparison
|
||||
and leaves the remaining framework overhead visible.
|
||||
Loading…
Reference in a new issue