| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .. | ||
| contracts | ||
| examples | ||
| src | ||
| tests | ||
| .gitignore | ||
| Cargo.toml | ||
| README.md | ||
CultNet RS
cultnet-rs is the Rust sibling of cultnet-ts: typed MessagePack messages,
4-byte length-prefixed direct-pipe framing, stop-and-wait RUDP message delivery,
CultLib-shaped security helpers, and CultCache replication without making
callers paw through raw envelopes like we lost a bet.
The contract is intentionally boring:
cultnet.schema.v0sends schema-versioned MessagePack objects.gamecult.networking.v0maps the legacy C# union shape explicitly.- schema discovery uses explicit catalog request/response messages; no inbound auto-detect sludge.
- document put/delete/snapshot messages move typed CultCache entries.
- raw document put/snapshot messages preserve canonical MessagePack payload bytes for bit-compatible neighbors.
cultnet.transport.rudp.v0carries one CultNet message per acknowledged UDP datagram with timeout/retry semantics.- hello messages advertise
supportedMutationContracts, so callers discover which document types are read-only, which accept typed intents, which authority owns the mutation, and which receipt documents prove the outcome. - payloads are decoded through registered Rust types before entering the cache.
This crate is not an HTTP wrapper. It is the wire vocabulary Epiphany, Ghostlight, VoidBot, and the rest of the swarm can share.
The public API surface is the schema plus its mutation contracts. A runtime does not expose a pile of bespoke verbs and hope everyone remembers the ritual; it advertises typed documents, typed intents, and typed receipts. Polite machines knock on the contract before touching the furniture.
Receipts
cargo test
The initial tests prove:
- CultLib-compatible AES-GCM string encryption and HMAC session tokens
- 4-byte big-endian MessagePack framing
- schema-versioned message round trips
- legacy
gamecult.networking.v0login mapping - schema discovery catalog responses with canonical JSON schema hashes
- CultCache snapshot replication through registered typed documents
- raw snapshot replication that preserves the original payload bytes
- document mutation contract advertisement through hello frames and registries
- acknowledged localhost UDP delivery through
cultnet.transport.rudp.v0
RUDP Transport
cultnet.transport.rudp.v0 is the Rust crate's first non-TCP daemon transport.
It is intentionally small: one CultNet message becomes one UDP data packet, the
receiver sends an acknowledgement packet, and the sender retries until the ack
arrives or the retry budget is spent.
This is a daemon health/control substrate, not a bulk stream transport. It does not fragment oversized messages, multiplex streams, or promise congestion control. Large snapshots should stay in CultCache/CultMesh storage and move by document reference or a later chunking contract. The useful invariant is simple: Rust runtimes can now move a typed CultNet message across UDP without reaching for TCP as the hidden truth path.
Schema Discovery
cultnet-rs now ships a built-in schema registry for the shared swarm contract
surface:
- core wire messages
- legacy
gamecult.networking.v0auth/sample payloads - schema catalog request/response messages
- the canonical
ghostlight.agent-statedocument payload schema
Use builtin_schema_registry() when you want the standard catalog, or register
your own closed-world schema set with CultNetSchemaRegistry. Discovery stays
explicit on purpose: peers advertise only the contracts they were compiled to
understand, the same way CultCache only consumes the document types you
registered instead of pretending polymorphism is a public park.
Local Fast Lane
cultnet-rs now mirrors the raw replication seam from cultnet-ts:
cultnet.document_put_raw.v0cultnet.snapshot_response_raw.v0
Those messages carry the exact persisted MessagePack payload bytes from
CultCache along with the typed envelope metadata. Combined with
CultCache::put_envelope::<T>(), that lets a bit-compatible neighbor ingest the
document without re-encoding the payload first.
That still is not zero-copy in the religious sense. Frames allocate, bytes move, and the receiving cache still decodes once to keep typed reads and validation honest. The win is narrower and realer: identical payload bytes stop getting decoded into generic sludge and then encoded right back into the same bytes for no reason.