Refresh CultNet operation service substrate

This commit is contained in:
Meta Vens 2026-08-22 02:04:51 +02:00
commit 33f2132cd3
20 changed files with 5761 additions and 635 deletions

View file

@ -773,7 +773,7 @@ fn request_raw_snapshot_from_rudp_catalog(
max_payload_bytes: None,
max_fragment_bytes: Some(1200),
max_pending_reliable_packets: None,
media_reliable_expire_after_ms: None,
reconnect_policy: None,
})?;
client.connect(Vec::new())?;
let connect_deadline = Instant::now() + options.connect_timeout;
@ -871,7 +871,7 @@ pub fn publish_cultnet_messages_to_rudp_catalog(
max_payload_bytes: None,
max_fragment_bytes: Some(1200),
max_pending_reliable_packets: None,
media_reliable_expire_after_ms: None,
reconnect_policy: None,
})?;
client.connect(Vec::new())?;
let connect_deadline = Instant::now() + options.connect_timeout;

View file

@ -1,9 +1,9 @@
# 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.
4-byte length-prefixed direct-pipe framing, CultLib-shaped security helpers, and
CultCache replication without making callers paw through raw envelopes like we
lost a bet.
The contract is intentionally boring:
@ -14,8 +14,6 @@ The contract is intentionally boring:
- 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.v0` carries 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.
@ -42,24 +40,11 @@ The initial tests prove:
- schema-versioned message round trips
- legacy `gamecult.networking.v0` login mapping
- schema discovery catalog responses with canonical JSON schema hashes
- shard catalog request/response filtering and response application
- CultCache snapshot replication through registered typed documents
- raw snapshot replication that preserves the original payload bytes
- raw snapshot replication into a local same-schema Rust alias type
- 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
@ -69,14 +54,51 @@ surface:
- core wire messages
- legacy `gamecult.networking.v0` auth/sample payloads
- schema catalog request/response messages
- shard catalog request/response messages
- the canonical `ghostlight.agent-state` document 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
Use `builtin_schema_registry()` or `CultMesh::create_builtin_schema_registry()`
when you want the standard catalog, or register your own closed-world schema set
with `CultNetSchemaRegistry` / `CultMesh::create_schema_registry()`. 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.
## Shard Catalogs
Rust now exposes the same shard topology vocabulary as the other runtimes
without claiming to be the full C# service body:
```rust
use cultnet_rs::{CultMesh, CultNetMessage, CultNetShardDescriptor};
let mut catalog = CultMesh::create_shard_catalog();
catalog.upsert(CultNetShardDescriptor {
shard_id: "notes-a".to_string(),
owner_runtime_id: "rust-primary".to_string(),
epoch: 3,
is_primary: Some(true),
schema_ids: vec!["note.v0".to_string()],
key_prefix: Some("note:".to_string()),
primary_endpoints: vec!["rudp://127.0.0.1:4100".to_string()],
replica_endpoints: vec![],
read_replica_endpoints: vec![],
region: None,
authority_lease_id: None,
})?;
let response = catalog.create_catalog_response(&CultNetMessage::ShardCatalogRequest {
message_id: "discover-shards".to_string(),
schema_ids: Some(vec!["note.v0".to_string()]),
record_keys: Some(vec!["note:1".to_string()]),
})?;
```
`CultNetShardCatalog::apply_response(...)` imports remote
`cultnet.shard_catalog_response.v0` descriptors into the local catalog. The
catalog owns topology inspection only; shard-log serving, daemon policy, and
game-session authority remain separate responsibilities.
## Local Fast Lane
`cultnet-rs` now mirrors the raw replication seam from `cultnet-ts`:
@ -89,8 +111,169 @@ 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.
The receiving Rust type does not have to be the sender's concrete Rust type. If
the local registry binds a different `DatabaseEntry` to the same schema id,
`sync_raw_document_from_snapshot_response::<LocalAlias>(...)` hydrates one local
alias type directly:
```rust
let mut target_registry = CultNetDocumentRegistry::new();
target_registry.register(CultNetDocumentBinding::for_entry_with_schema_id::<UiNote>(
"aetheria.note.v1".to_string(),
"aetheria.note.v1".to_string(),
));
let note = target_registry.sync_raw_document_from_snapshot_response::<UiNote>(
&mut target_cache,
&snapshot_response,
"note:bridge",
)?;
```
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.
## Reactive Documents
For local state that should feel owned by the caller, Rust can wrap a registered
CultCache record as a managed reactive document:
```rust
use std::sync::{Arc, Mutex};
use cultnet_rs::{CultNetReactiveDocumentOptions, CultNetDocumentRegistry};
let cache = Arc::new(Mutex::new(target_cache));
let note = registry.reactive_document::<UiNote>(
Arc::clone(&cache),
"note:bridge",
CultNetReactiveDocumentOptions::default(),
)?;
{
let current = note.current();
current.lock().unwrap().body = "local prediction".to_string();
}
```
The handle polls the serialized `current` value on the configured debounce
cadence and flushes changed state back through the typed cache. `update(...)`,
`set_current(...)`, `mark_dirty()`, and `flush()` are available when the caller
wants a more explicit Rust shape.
When a canonical document put arrives while local state is dirty,
`apply_document_put_message(...)` or `apply_raw_document_put_message(...)`
records a `CultNetReactiveDocumentReconciliation`: the canonical value, the
predicted local value, and a delta that can be smoothed by the caller. CultCache
payloads serialize by numeric field slot, so Rust tuple-backed deltas use slot
keys such as `"0"` and `"1"` when field names are not present on the wire.
## CultMesh Rust Facade
Rust is still the low-level substrate runtime, not a clone of the C# game
server. It does now expose the small CultMesh entrypoint needed for practical
contact and authority ergonomics:
```rust
use cultnet_rs::{
CultMesh, CultMeshAuthorityLease, CultMeshPeerCard, CultMeshRudpClientOptions,
CultMeshRudpSocketOptions, CultNetMessage, CultNetSchemaKind,
};
use chrono::{Duration, Utc};
let schemas = CultMesh::create_builtin_schema_registry()?;
let shared_contracts = schemas.list(&cultnet_rs::CultNetSchemaCatalogOptions {
include_schema_json: false,
schema_ids: None,
kinds: Some(vec![CultNetSchemaKind::SharedContract]),
});
let mut server = CultMesh::create_rudp_server(
"rust-server",
0x1020_3040,
CultMeshRudpSocketOptions::default(),
)?;
let port = server.profile.transports[0].port.unwrap();
let peer = CultMeshPeerCard::new(
"rust-server",
"local",
[format!("rudp://127.0.0.1:{port}")],
)
.with_roles(["schema"])
.with_authority_lease_id("lease:rust-server");
let now = Utc::now();
let mut peers = CultMesh::create_peer_catalog();
let mut leases = CultMesh::create_authority_lease_catalog();
peers.upsert(peer.clone())?;
leases.upsert(CultMeshAuthorityLease {
lease_id: "lease:rust-server".to_string(),
verse_id: "local".to_string(),
peer_id: "rust-server".to_string(),
roles: vec!["schema".to_string()],
shard_ids: Vec::new(),
issuer_runtime_id: None,
valid_from: now - Duration::minutes(1),
expires_at: now + Duration::minutes(1),
})?;
let mut client = CultMesh::connect_rudp_client_for_authorized_peer(
"rust-client",
0x1020_3040,
&peers,
&leases,
"local",
"schema",
None,
now,
CultMeshRudpClientOptions {
socket_options: CultMeshRudpSocketOptions::default(),
connect_payload: b"join".to_vec(),
..CultMeshRudpClientOptions::default()
},
)?;
client.send_schema_message(&CultNetMessage::SchemaCatalogRequest {
message_id: "rust-schema-catalog".to_string(),
include_schema_json: Some(false),
schema_ids: None,
kinds: Some(vec![CultNetSchemaKind::DocumentPayload]),
})?;
```
`create_rudp_client...` remains available when the caller intentionally owns the
handshake and polling loop. `connect_rudp_client...` performs the client
handshake before returning the same schema-message-capable RUDP transport.
For caller-owned reconnect loops, `CultNetRudpReconnectLoop` keeps transport
construction outside the library while sharing the portable retry controller:
```rust
use cultnet_rs::{
CultNetReconnectPolicyOptions, CultNetRudpReconnectLoop, create_reconnect_policy,
};
let policy = create_reconnect_policy(CultNetReconnectPolicyOptions::default());
let mut reconnect = CultNetRudpReconnectLoop::new(policy, b"join".to_vec(), || {
CultMesh::create_rudp_client_for_peer(
"rust-client",
0x1020_3040,
&peer,
CultMeshRudpSocketOptions::default(),
)
});
reconnect.start()?;
let decision = reconnect.handle_closed(now_ms, 0);
if decision.is_some() {
reconnect.reconnect_if_due(now_ms)?;
}
```
`CultMesh::parse_rudp_endpoint(...)` handles advertised `rudp://host:port`
contact hints, and `CultMeshAuthorityLeaseCatalog` keeps trust separate from
discovery. A peer card can say where to dial; `peers.first_authorized(...)` and
`CultMesh::create_rudp_client_for_authorized_peer(...)` only use that contact
hint after a lease says the peer may own the requested role or shard.

View file

@ -0,0 +1,19 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "cultnet.shard_catalog_request.v0",
"type": "object",
"required": ["schemaVersion", "messageId"],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.shard_catalog_request.v0" },
"messageId": { "type": "string", "minLength": 1 },
"schemaIds": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"recordKeys": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
}
}
}

View file

@ -0,0 +1,47 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "cultnet.shard_catalog_response.v0",
"type": "object",
"required": ["schemaVersion", "messageId", "shards"],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.shard_catalog_response.v0" },
"messageId": { "type": "string", "minLength": 1 },
"shards": {
"type": "array",
"items": { "$ref": "#/$defs/shardDescriptor" }
}
},
"$defs": {
"shardDescriptor": {
"type": "object",
"required": ["shardId", "ownerRuntimeId", "epoch"],
"additionalProperties": false,
"properties": {
"shardId": { "type": "string", "minLength": 1 },
"ownerRuntimeId": { "type": "string", "minLength": 1 },
"epoch": { "type": "integer", "minimum": 0 },
"isPrimary": { "type": "boolean" },
"schemaIds": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"keyPrefix": { "type": "string", "minLength": 1 },
"primaryEndpoints": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"replicaEndpoints": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"readReplicaEndpoints": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"region": { "type": "string", "minLength": 1 },
"authorityLeaseId": { "type": "string", "minLength": 1 }
}
}
}
}

View file

@ -41,6 +41,25 @@
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"reconnectPolicy": {
"type": "object",
"required": [
"schemaVersion",
"policyId",
"baseDelayMs",
"maxDelayMs",
"maxJitterMs"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.reconnect_policy.v0" },
"policyId": { "type": "string", "minLength": 1 },
"baseDelayMs": { "type": "integer", "minimum": 0 },
"maxDelayMs": { "type": "integer", "minimum": 0 },
"maxJitterMs": { "type": "integer", "minimum": 0 },
"maxAttempts": { "type": "integer", "minimum": 1 }
}
},
"channels": {
"type": "array",
"items": {

File diff suppressed because it is too large Load diff

View file

@ -104,9 +104,23 @@ pub struct CultNetTransportDescriptor {
pub discovery_group: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub wire_contracts: Option<Vec<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub reconnect_policy: Option<CultNetReconnectPolicy>,
pub channels: Vec<CultNetTransportChannel>,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultNetReconnectPolicy {
pub schema_version: String,
pub policy_id: String,
pub base_delay_ms: u64,
pub max_delay_ms: u64,
pub max_jitter_ms: u64,
#[serde(skip_serializing_if = "Option::is_none")]
pub max_attempts: Option<u32>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CultNetTransportProtocol {
@ -128,8 +142,6 @@ pub struct CultNetTransportChannel {
pub max_fragment_bytes: Option<u32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub max_pending_reliable_packets: Option<u32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub reliable_expire_after_ms: Option<u64>,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
@ -183,6 +195,53 @@ pub struct CultNetSchemaDescriptor {
pub schema_json: Option<String>,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultNetShardDescriptor {
pub shard_id: String,
pub owner_runtime_id: String,
pub epoch: u64,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub is_primary: Option<bool>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub schema_ids: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub key_prefix: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub primary_endpoints: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub replica_endpoints: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub read_replica_endpoints: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub region: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub authority_lease_id: Option<String>,
}
impl CultNetShardDescriptor {
pub fn serves(&self, schema_id: Option<&str>, record_key: Option<&str>) -> bool {
if let Some(schema_id) = schema_id
&& !self.schema_ids.is_empty()
&& !self
.schema_ids
.iter()
.any(|candidate| candidate == schema_id)
{
return false;
}
if let Some(record_key) = record_key
&& let Some(prefix) = self.key_prefix.as_deref()
&& !record_key.starts_with(prefix)
{
return false;
}
true
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "schemaVersion")]
pub enum CultNetMessage {
@ -282,6 +341,52 @@ pub enum CultNetMessage {
message_id: String,
schemas: Vec<CultNetSchemaDescriptor>,
},
#[serde(rename = "cultnet.shard_catalog_request.v0", rename_all = "camelCase")]
ShardCatalogRequest {
message_id: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
schema_ids: Option<Vec<String>>,
#[serde(default, skip_serializing_if = "Option::is_none")]
record_keys: Option<Vec<String>>,
},
#[serde(rename = "cultnet.shard_catalog_response.v0", rename_all = "camelCase")]
ShardCatalogResponse {
message_id: String,
shards: Vec<CultNetShardDescriptor>,
},
#[serde(rename = "cultnet.operation_request.v0", rename_all = "camelCase")]
OperationRequest {
message_id: String,
service_id: String,
operation: String,
payload_schema: String,
#[serde(default = "messagepack_base64_encoding")]
payload_encoding: String,
payload: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
source_runtime_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
target_runtime_id: Option<String>,
},
#[serde(rename = "cultnet.operation_response.v0", rename_all = "camelCase")]
OperationResponse {
message_id: String,
service_id: String,
operation: String,
status: String,
payload_schema: String,
#[serde(default = "messagepack_base64_encoding")]
payload_encoding: String,
payload: String,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
diagnostics: Vec<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
source_runtime_id: Option<String>,
},
}
fn messagepack_base64_encoding() -> String {
"messagepack-base64".to_string()
}
pub fn parse_cultnet_message(
@ -473,6 +578,60 @@ fn validate_message(message: &CultNetMessage) -> Result<()> {
validate_schema_descriptor(schema)?;
}
}
CultNetMessage::ShardCatalogRequest {
message_id,
schema_ids,
record_keys,
} => {
require_non_empty(message_id, "messageId")?;
require_optional_string_vec(schema_ids.as_deref(), "schemaIds")?;
require_optional_string_vec(record_keys.as_deref(), "recordKeys")?;
}
CultNetMessage::ShardCatalogResponse { message_id, shards } => {
require_non_empty(message_id, "messageId")?;
for shard in shards {
validate_shard_descriptor(shard)?;
}
}
CultNetMessage::OperationRequest {
message_id,
service_id,
operation,
payload_schema,
payload_encoding,
payload,
source_runtime_id,
target_runtime_id,
} => {
require_non_empty(message_id, "messageId")?;
require_non_empty(service_id, "serviceId")?;
require_non_empty(operation, "operation")?;
require_non_empty(payload_schema, "payloadSchema")?;
require_exact(payload_encoding, "messagepack-base64", "payloadEncoding")?;
require_non_empty(payload, "payload")?;
require_optional_non_empty(source_runtime_id.as_deref(), "sourceRuntimeId")?;
require_optional_non_empty(target_runtime_id.as_deref(), "targetRuntimeId")?;
}
CultNetMessage::OperationResponse {
message_id,
service_id,
operation,
status,
payload_schema,
payload_encoding,
payload,
diagnostics: _,
source_runtime_id,
} => {
require_non_empty(message_id, "messageId")?;
require_non_empty(service_id, "serviceId")?;
require_non_empty(operation, "operation")?;
require_non_empty(status, "status")?;
require_non_empty(payload_schema, "payloadSchema")?;
require_exact(payload_encoding, "messagepack-base64", "payloadEncoding")?;
require_non_empty(payload, "payload")?;
require_optional_non_empty(source_runtime_id.as_deref(), "sourceRuntimeId")?;
}
}
Ok(())
}
@ -545,6 +704,22 @@ fn validate_schema_descriptor(schema: &CultNetSchemaDescriptor) -> Result<()> {
Ok(())
}
fn validate_shard_descriptor(shard: &CultNetShardDescriptor) -> Result<()> {
require_non_empty(&shard.shard_id, "shardId")?;
require_non_empty(&shard.owner_runtime_id, "ownerRuntimeId")?;
require_optional_string_vec(Some(shard.schema_ids.as_slice()), "schemaIds")?;
require_optional_non_empty(shard.key_prefix.as_deref(), "keyPrefix")?;
require_optional_string_vec(Some(shard.primary_endpoints.as_slice()), "primaryEndpoints")?;
require_optional_string_vec(Some(shard.replica_endpoints.as_slice()), "replicaEndpoints")?;
require_optional_string_vec(
Some(shard.read_replica_endpoints.as_slice()),
"readReplicaEndpoints",
)?;
require_optional_non_empty(shard.region.as_deref(), "region")?;
require_optional_non_empty(shard.authority_lease_id.as_deref(), "authorityLeaseId")?;
Ok(())
}
fn require_non_empty(value: &str, field: &str) -> Result<()> {
if value.trim().is_empty() {
return Err(anyhow!("CultNet field {field} must be non-empty"));
@ -552,6 +727,13 @@ fn require_non_empty(value: &str, field: &str) -> Result<()> {
Ok(())
}
fn require_exact(value: &str, expected: &str, field: &str) -> Result<()> {
if value != expected {
return Err(anyhow!("{field} must be {expected}"));
}
Ok(())
}
fn require_optional_non_empty(value: Option<&str>, field: &str) -> Result<()> {
if let Some(value) = value {
require_non_empty(value, field)?;

525
vendor/cultnet-rs/src/cultmesh.rs vendored Normal file
View file

@ -0,0 +1,525 @@
use anyhow::Result;
use anyhow::anyhow;
use chrono::DateTime;
use chrono::Utc;
use std::collections::BTreeMap;
use std::net::SocketAddr;
use std::net::ToSocketAddrs;
use std::net::UdpSocket;
use std::thread;
use std::time::Duration;
use std::time::Instant;
use crate::CultNetRudpSocketMode;
use crate::CultNetRudpSocketTransportConnection;
use crate::CultNetRudpSocketTransportOptions;
use crate::CultNetSchemaRegistry;
use crate::CultNetShardCatalog;
use crate::builtin_schema_registry;
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CultMeshPeerCard {
pub peer_id: String,
pub verse_id: String,
pub endpoints: Vec<String>,
pub roles: Vec<String>,
pub shard_ids: Vec<String>,
pub authority_lease_id: Option<String>,
}
impl CultMeshPeerCard {
pub fn new(
peer_id: impl Into<String>,
verse_id: impl Into<String>,
endpoints: impl IntoIterator<Item = impl Into<String>>,
) -> Self {
Self {
peer_id: peer_id.into(),
verse_id: verse_id.into(),
endpoints: endpoints.into_iter().map(Into::into).collect(),
roles: Vec::new(),
shard_ids: Vec::new(),
authority_lease_id: None,
}
}
pub fn with_roles(mut self, roles: impl IntoIterator<Item = impl Into<String>>) -> Self {
self.roles = roles.into_iter().map(Into::into).collect();
self
}
pub fn with_shard_ids(
mut self,
shard_ids: impl IntoIterator<Item = impl Into<String>>,
) -> Self {
self.shard_ids = shard_ids.into_iter().map(Into::into).collect();
self
}
pub fn with_authority_lease_id(mut self, authority_lease_id: impl Into<String>) -> Self {
self.authority_lease_id = Some(authority_lease_id.into());
self
}
pub fn rudp_endpoint(&self) -> Result<CultNetRudpEndpoint> {
let endpoint = self
.endpoints
.iter()
.find(|endpoint| endpoint.to_ascii_lowercase().starts_with("rudp://"))
.ok_or_else(|| anyhow!("Peer {} does not advertise a RUDP endpoint", self.peer_id))?;
CultMesh::parse_rudp_endpoint(endpoint)
}
}
#[derive(Clone, Debug, Default)]
pub struct CultMeshPeerCatalog {
peers: BTreeMap<String, CultMeshPeerCard>,
}
impl CultMeshPeerCatalog {
pub fn new() -> Self {
Self::default()
}
pub fn upsert(&mut self, peer: CultMeshPeerCard) -> Result<()> {
require_non_empty(&peer.peer_id, "peer.peer_id")?;
require_non_empty(&peer.verse_id, "peer.verse_id")?;
self.peers.insert(peer.peer_id.clone(), peer);
Ok(())
}
pub fn get(&self, peer_id: &str) -> Option<&CultMeshPeerCard> {
self.peers.get(peer_id)
}
pub fn peers(&self) -> Vec<CultMeshPeerCard> {
self.peers.values().cloned().collect()
}
pub fn find(&self, verse_id: &str, role: Option<&str>) -> Vec<CultMeshPeerCard> {
self.peers
.values()
.filter(|peer| {
peer.verse_id == verse_id
&& role.is_none_or(|role| peer.roles.iter().any(|value| value == role))
})
.cloned()
.collect()
}
pub fn find_authorized(
&self,
verse_id: &str,
role: &str,
leases: &CultMeshAuthorityLeaseCatalog,
shard_id: Option<&str>,
at: DateTime<Utc>,
) -> Vec<CultMeshPeerCard> {
self.find(verse_id, Some(role))
.into_iter()
.filter(|peer| leases.is_authorized(peer, role, shard_id, at))
.collect()
}
pub fn first_authorized(
&self,
verse_id: &str,
role: &str,
leases: &CultMeshAuthorityLeaseCatalog,
shard_id: Option<&str>,
at: DateTime<Utc>,
) -> Option<CultMeshPeerCard> {
self.find_authorized(verse_id, role, leases, shard_id, at)
.into_iter()
.next()
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CultMeshAuthorityLease {
pub lease_id: String,
pub verse_id: String,
pub peer_id: String,
pub roles: Vec<String>,
pub shard_ids: Vec<String>,
pub issuer_runtime_id: Option<String>,
pub valid_from: DateTime<Utc>,
pub expires_at: DateTime<Utc>,
}
impl CultMeshAuthorityLease {
pub fn covers(
&self,
peer: &CultMeshPeerCard,
role: &str,
shard_id: Option<&str>,
at: DateTime<Utc>,
) -> bool {
at >= self.valid_from
&& at < self.expires_at
&& self.verse_id == peer.verse_id
&& self.peer_id == peer.peer_id
&& self.roles.iter().any(|value| value == role)
&& peer.roles.iter().any(|value| value == role)
&& shard_id.is_none_or(|shard_id| {
self.shard_ids.is_empty() || self.shard_ids.iter().any(|value| value == shard_id)
})
}
}
#[derive(Clone, Debug, Default)]
pub struct CultMeshAuthorityLeaseCatalog {
leases: BTreeMap<String, CultMeshAuthorityLease>,
}
impl CultMeshAuthorityLeaseCatalog {
pub fn new() -> Self {
Self::default()
}
pub fn upsert(&mut self, lease: CultMeshAuthorityLease) -> Result<()> {
require_non_empty(&lease.lease_id, "lease.lease_id")?;
require_non_empty(&lease.verse_id, "lease.verse_id")?;
require_non_empty(&lease.peer_id, "lease.peer_id")?;
if lease.expires_at <= lease.valid_from {
return Err(anyhow!(
"CultMesh authority lease expiry must be after valid_from"
));
}
self.leases.insert(lease.lease_id.clone(), lease);
Ok(())
}
pub fn get(&self, lease_id: &str) -> Option<&CultMeshAuthorityLease> {
self.leases.get(lease_id)
}
pub fn leases(&self) -> Vec<CultMeshAuthorityLease> {
self.leases.values().cloned().collect()
}
pub fn is_authorized(
&self,
peer: &CultMeshPeerCard,
role: &str,
shard_id: Option<&str>,
at: DateTime<Utc>,
) -> bool {
let Some(lease_id) = peer.authority_lease_id.as_deref() else {
return false;
};
self.leases
.get(lease_id)
.is_some_and(|lease| lease.covers(peer, role, shard_id, at))
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CultNetRudpEndpoint {
pub host: String,
pub port: u16,
}
impl CultNetRudpEndpoint {
pub fn uri(&self) -> String {
if self.host.contains(':') && !self.host.starts_with('[') {
format!("rudp://[{}]:{}", self.host, self.port)
} else {
format!("rudp://{}:{}", self.host, self.port)
}
}
pub fn socket_addr(&self) -> Result<SocketAddr> {
format!("{}:{}", socket_host(&self.host), self.port)
.to_socket_addrs()
.map_err(|error| anyhow!("Invalid RUDP socket endpoint {}: {error}", self.uri()))?
.next()
.ok_or_else(|| anyhow!("RUDP socket endpoint {} did not resolve", self.uri()))
}
}
#[derive(Clone, Debug)]
pub struct CultMeshRudpSocketOptions {
pub bind_host: String,
pub bind_port: u16,
pub read_timeout: Option<Duration>,
pub initial_sequence: u32,
pub resend_delay_ms: u64,
pub max_payload_bytes: Option<u32>,
pub max_fragment_bytes: Option<u32>,
pub max_pending_reliable_packets: Option<u32>,
}
impl Default for CultMeshRudpSocketOptions {
fn default() -> Self {
Self {
bind_host: "127.0.0.1".to_string(),
bind_port: 0,
read_timeout: Some(Duration::from_millis(20)),
initial_sequence: 1,
resend_delay_ms: 250,
max_payload_bytes: None,
max_fragment_bytes: None,
max_pending_reliable_packets: None,
}
}
}
#[derive(Clone, Debug)]
pub struct CultMeshRudpClientOptions {
pub socket_options: CultMeshRudpSocketOptions,
pub connect_payload: Vec<u8>,
pub connect_timeout: Duration,
pub poll_interval: Duration,
}
impl Default for CultMeshRudpClientOptions {
fn default() -> Self {
Self {
socket_options: CultMeshRudpSocketOptions::default(),
connect_payload: Vec::new(),
connect_timeout: Duration::from_secs(1),
poll_interval: Duration::from_millis(5),
}
}
}
pub struct CultMesh;
impl CultMesh {
pub fn create_schema_registry() -> CultNetSchemaRegistry {
CultNetSchemaRegistry::new()
}
pub fn create_builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
builtin_schema_registry()
}
pub fn create_shard_catalog() -> CultNetShardCatalog {
CultNetShardCatalog::new()
}
pub fn create_peer_catalog() -> CultMeshPeerCatalog {
CultMeshPeerCatalog::new()
}
pub fn create_authority_lease_catalog() -> CultMeshAuthorityLeaseCatalog {
CultMeshAuthorityLeaseCatalog::new()
}
pub fn parse_rudp_endpoint(endpoint: &str) -> Result<CultNetRudpEndpoint> {
cultnet_rudp_endpoint(endpoint)
}
pub fn create_rudp_server(
runtime_id: impl Into<String>,
connection_id: u32,
options: CultMeshRudpSocketOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
let socket = bind_rudp_socket(&options)?;
CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions {
runtime_id: runtime_id.into(),
socket,
mode: CultNetRudpSocketMode::Server,
remote_addr: None,
connection_id,
initial_sequence: options.initial_sequence,
resend_delay_ms: options.resend_delay_ms,
transport_id: None,
max_payload_bytes: options.max_payload_bytes,
max_fragment_bytes: options.max_fragment_bytes,
max_pending_reliable_packets: options.max_pending_reliable_packets,
reconnect_policy: None,
})
}
pub fn create_rudp_client(
runtime_id: impl Into<String>,
connection_id: u32,
endpoint: &CultNetRudpEndpoint,
options: CultMeshRudpSocketOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
let socket = bind_rudp_socket(&options)?;
CultNetRudpSocketTransportConnection::new(CultNetRudpSocketTransportOptions {
runtime_id: runtime_id.into(),
socket,
mode: CultNetRudpSocketMode::Client,
remote_addr: Some(endpoint.socket_addr()?),
connection_id,
initial_sequence: options.initial_sequence,
resend_delay_ms: options.resend_delay_ms,
transport_id: None,
max_payload_bytes: options.max_payload_bytes,
max_fragment_bytes: options.max_fragment_bytes,
max_pending_reliable_packets: options.max_pending_reliable_packets,
reconnect_policy: None,
})
}
pub fn create_rudp_client_for_endpoint(
runtime_id: impl Into<String>,
connection_id: u32,
endpoint: &str,
options: CultMeshRudpSocketOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
let endpoint = Self::parse_rudp_endpoint(endpoint)?;
Self::create_rudp_client(runtime_id, connection_id, &endpoint, options)
}
pub fn create_rudp_client_for_peer(
runtime_id: impl Into<String>,
connection_id: u32,
peer: &CultMeshPeerCard,
options: CultMeshRudpSocketOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
let endpoint = peer.rudp_endpoint()?;
Self::create_rudp_client(runtime_id, connection_id, &endpoint, options)
}
pub fn create_rudp_client_for_authorized_peer(
runtime_id: impl Into<String>,
connection_id: u32,
peers: &CultMeshPeerCatalog,
leases: &CultMeshAuthorityLeaseCatalog,
verse_id: &str,
role: &str,
shard_id: Option<&str>,
at: DateTime<Utc>,
options: CultMeshRudpSocketOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
let peer = peers
.first_authorized(verse_id, role, leases, shard_id, at)
.ok_or_else(|| {
anyhow!("No authorized RUDP peer for role {role} in Verse {verse_id}")
})?;
Self::create_rudp_client_for_peer(runtime_id, connection_id, &peer, options)
}
pub fn connect_rudp_client(
runtime_id: impl Into<String>,
connection_id: u32,
endpoint: &CultNetRudpEndpoint,
options: CultMeshRudpClientOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
let runtime_id = runtime_id.into();
let mut client = Self::create_rudp_client(
runtime_id.clone(),
connection_id,
endpoint,
options.socket_options,
)?;
client.connect(options.connect_payload)?;
let deadline = Instant::now() + options.connect_timeout;
while Instant::now() < deadline {
let _ = client.receive_once()?;
client.poll_resends()?;
if client.connected() {
return Ok(client);
}
thread::sleep(options.poll_interval);
}
if client.connected() {
return Ok(client);
}
Err(anyhow!(
"Timed out waiting for RUDP client {runtime_id} to connect"
))
}
pub fn connect_rudp_client_for_endpoint(
runtime_id: impl Into<String>,
connection_id: u32,
endpoint: &str,
options: CultMeshRudpClientOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
let endpoint = Self::parse_rudp_endpoint(endpoint)?;
Self::connect_rudp_client(runtime_id, connection_id, &endpoint, options)
}
pub fn connect_rudp_client_for_peer(
runtime_id: impl Into<String>,
connection_id: u32,
peer: &CultMeshPeerCard,
options: CultMeshRudpClientOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
let endpoint = peer.rudp_endpoint()?;
Self::connect_rudp_client(runtime_id, connection_id, &endpoint, options)
}
pub fn connect_rudp_client_for_authorized_peer(
runtime_id: impl Into<String>,
connection_id: u32,
peers: &CultMeshPeerCatalog,
leases: &CultMeshAuthorityLeaseCatalog,
verse_id: &str,
role: &str,
shard_id: Option<&str>,
at: DateTime<Utc>,
options: CultMeshRudpClientOptions,
) -> Result<CultNetRudpSocketTransportConnection> {
let peer = peers
.first_authorized(verse_id, role, leases, shard_id, at)
.ok_or_else(|| {
anyhow!("No authorized RUDP peer for role {role} in Verse {verse_id}")
})?;
Self::connect_rudp_client_for_peer(runtime_id, connection_id, &peer, options)
}
}
pub fn cultnet_rudp_endpoint(endpoint: &str) -> Result<CultNetRudpEndpoint> {
let scheme = "rudp://";
if endpoint.len() < scheme.len() || !endpoint[..scheme.len()].eq_ignore_ascii_case(scheme) {
return Err(anyhow!("RUDP endpoint must use the rudp scheme"));
}
let rest = &endpoint[scheme.len()..];
let (host, port_text) = if let Some(rest) = rest.strip_prefix('[') {
let (host, port_rest) = rest
.split_once(']')
.ok_or_else(|| anyhow!("RUDP IPv6 endpoint must close the host bracket"))?;
let port_text = port_rest
.strip_prefix(':')
.ok_or_else(|| anyhow!("RUDP endpoint must include a valid port"))?;
(host.to_string(), port_text)
} else {
let (host, port_text) = rest
.rsplit_once(':')
.ok_or_else(|| anyhow!("RUDP endpoint must include a host and port"))?;
if host.contains(':') {
return Err(anyhow!("RUDP IPv6 endpoint host must be bracketed"));
}
(host.to_string(), port_text)
};
require_non_empty(&host, "rudp host")?;
let port = port_text
.parse::<u16>()
.map_err(|error| anyhow!("RUDP endpoint must include a valid port: {error}"))?;
if port == 0 {
return Err(anyhow!("RUDP endpoint port must be greater than zero"));
}
Ok(CultNetRudpEndpoint { host, port })
}
fn bind_rudp_socket(options: &CultMeshRudpSocketOptions) -> Result<UdpSocket> {
let socket = UdpSocket::bind(format!(
"{}:{}",
socket_host(&options.bind_host),
options.bind_port
))?;
socket.set_read_timeout(options.read_timeout)?;
Ok(socket)
}
fn socket_host(host: &str) -> String {
if host.contains(':') && !host.starts_with('[') {
format!("[{host}]")
} else {
host.to_string()
}
}
fn require_non_empty(value: &str, field: &str) -> Result<()> {
if value.trim().is_empty() {
return Err(anyhow!("CultMesh {field} must not be empty"));
}
Ok(())
}

View file

@ -1,17 +1,25 @@
mod contracts;
mod cultmesh;
mod framing;
mod operation_service;
mod provider_session;
mod replication;
mod rudp;
mod schema_discovery;
mod security;
mod service_identity;
mod shard_catalog;
mod transport;
pub use contracts::*;
pub use cultmesh::*;
pub use framing::*;
pub use operation_service::*;
pub use provider_session::*;
pub use replication::*;
pub use rudp::*;
pub use schema_discovery::*;
pub use security::*;
pub use service_identity::*;
pub use shard_catalog::*;
pub use transport::*;

View file

@ -0,0 +1,60 @@
use std::net::UdpSocket;
use std::time::Duration;
use anyhow::{Result, anyhow};
use crate::{
CultNetMessage, CultNetRudpSocketTransportConnection, CultNetRudpSocketTransportOptions,
};
pub const CULTNET_OPERATION_CONNECTION_ID: u32 = 0x4355_4c54;
pub struct CultNetOperationServer {
transport: CultNetRudpSocketTransportConnection,
endpoint: String,
}
impl CultNetOperationServer {
pub fn bind(runtime_id: impl Into<String>, host: &str, port: u16) -> Result<Self> {
let socket = UdpSocket::bind((host, port))?;
socket.set_read_timeout(Some(Duration::from_millis(25)))?;
let address = socket.local_addr()?;
let mut options = CultNetRudpSocketTransportOptions::server(
runtime_id,
socket,
CULTNET_OPERATION_CONNECTION_ID,
);
options.max_fragment_bytes = Some(2048);
Ok(Self {
transport: CultNetRudpSocketTransportConnection::new(options)?,
endpoint: format!("rudp://{}:{}", address.ip(), address.port()),
})
}
pub fn endpoint(&self) -> &str {
&self.endpoint
}
pub fn serve_once(
&mut self,
mut handler: impl FnMut(CultNetMessage) -> Result<CultNetMessage>,
) -> Result<bool> {
let Some(request) = self.transport.receive_schema_message_once()? else {
self.transport.poll_resends()?;
return Ok(false);
};
if !matches!(request, CultNetMessage::OperationRequest { .. }) {
return Err(anyhow!(
"CultNet operation service received a non-operation message"
));
}
let response = handler(request)?;
if !matches!(response, CultNetMessage::OperationResponse { .. }) {
return Err(anyhow!(
"CultNet operation handler returned a non-operation response"
));
}
self.transport.send_schema_message(&response)?;
Ok(true)
}
}

View file

@ -0,0 +1,625 @@
use anyhow::{Result, anyhow};
use base64::Engine;
use base64::engine::general_purpose::STANDARD;
use chrono::DateTime;
use rmpv::Value;
use serde::de::DeserializeOwned;
use serde::{Deserialize, Serialize};
use crate::{CultNetMessage, CultNetRawDocumentRecord};
pub const CULTMESH_PROVIDER_SESSION_SERVICE_ID: &str = "gamecult.mesh.provider_session";
pub const CULTMESH_PROVIDER_SESSION_PAYLOAD_ENCODING: &str = "messagepack-base64";
pub const CULTMESH_PROVIDER_REGISTER_OPERATION: &str = "provider.register";
pub const CULTMESH_PROVIDER_RENEW_OPERATION: &str = "provider.renew";
pub const CULTMESH_PROVIDER_PUBLICATION_PUT_OPERATION: &str = "provider.publication.put";
pub const CULTMESH_PROVIDER_PUBLICATION_DELETE_OPERATION: &str = "provider.publication.delete";
pub const CULTMESH_PROVIDER_RECEIPT_PUT_OPERATION: &str = "provider.receipt.put";
pub const CULTMESH_PROVIDER_WITHDRAW_OPERATION: &str = "provider.withdraw";
pub const CULTMESH_PROVIDER_REGISTRATION_SCHEMA: &str = "gamecult.mesh.provider_registration.v1";
pub const CULTMESH_PROVIDER_LEASE_SCHEMA: &str = "gamecult.mesh.provider_lease.v1";
pub const CULTMESH_PROVIDER_LEASE_RENEWAL_SCHEMA: &str = "gamecult.mesh.provider_lease_renewal.v1";
pub const CULTMESH_PROVIDER_PUBLICATION_PUT_SCHEMA: &str =
"gamecult.mesh.provider_publication_put.v1";
pub const CULTMESH_PROVIDER_PUBLICATION_DELETE_SCHEMA: &str =
"gamecult.mesh.provider_publication_delete.v1";
pub const CULTMESH_PROVIDER_COMMAND_SCHEMA: &str = "gamecult.mesh.provider_command.v1";
pub const CULTMESH_PROVIDER_RECEIPT_PUT_SCHEMA: &str = "gamecult.mesh.provider_receipt_put.v1";
pub const CULTMESH_PROVIDER_WITHDRAWAL_SCHEMA: &str = "gamecult.mesh.provider_withdrawal.v1";
pub const CULTMESH_PROVIDER_MUTATION_ACCEPTANCE_SCHEMA: &str =
"gamecult.mesh.provider_mutation_acceptance.v1";
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum CultMeshProviderOperationStatus {
Ok,
Conflict,
Expired,
Denied,
Invalid,
}
impl CultMeshProviderOperationStatus {
pub fn as_str(self) -> &'static str {
match self {
Self::Ok => "ok",
Self::Conflict => "conflict",
Self::Expired => "expired",
Self::Denied => "denied",
Self::Invalid => "invalid",
}
}
pub fn parse(value: &str) -> Result<Self> {
match value {
"ok" => Ok(Self::Ok),
"conflict" => Ok(Self::Conflict),
"expired" => Ok(Self::Expired),
"denied" => Ok(Self::Denied),
"invalid" => Ok(Self::Invalid),
_ => Err(anyhow!("Unsupported provider-session status {value:?}")),
}
}
}
pub trait CultMeshProviderSessionPayload {
fn validate(&self) -> Result<()>;
}
/// Provider-owned evidence carried verbatim in the RUDP Connect payload.
/// `client_session_id` distinguishes process/session generations; the optional
/// token remains opaque authorization evidence for the receiving service.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultMeshProviderConnectEvidenceWire {
pub client_session_id: String,
#[serde(default)]
pub session_token: Option<String>,
}
impl CultMeshProviderSessionPayload for CultMeshProviderConnectEvidenceWire {
fn validate(&self) -> Result<()> {
require_text(&self.client_session_id, "clientSessionId")?;
require_optional_text(self.session_token.as_deref(), "sessionToken")
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultMeshProviderRegistrationWire {
pub provider_id: String,
pub service_instance_id: String,
pub endpoint_id: String,
pub verse_id: String,
pub requested_lease_duration_ms: i32,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub authority_lease_id: Option<String>,
}
impl CultMeshProviderSessionPayload for CultMeshProviderRegistrationWire {
fn validate(&self) -> Result<()> {
require_identity(
&self.provider_id,
&self.service_instance_id,
&self.endpoint_id,
&self.verse_id,
)?;
require_positive(self.requested_lease_duration_ms, "requestedLeaseDurationMs")?;
require_optional_text(self.authority_lease_id.as_deref(), "authorityLeaseId")
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultMeshProviderLeaseWire {
pub provider_id: String,
pub service_instance_id: String,
pub endpoint_id: String,
pub verse_id: String,
pub lease_id: String,
pub valid_from_utc: String,
pub expires_at_utc: String,
}
impl CultMeshProviderSessionPayload for CultMeshProviderLeaseWire {
fn validate(&self) -> Result<()> {
require_identity(
&self.provider_id,
&self.service_instance_id,
&self.endpoint_id,
&self.verse_id,
)?;
require_text(&self.lease_id, "leaseId")?;
let valid_from = require_timestamp(&self.valid_from_utc, "validFromUtc")?;
let expires_at = require_timestamp(&self.expires_at_utc, "expiresAtUtc")?;
if expires_at <= valid_from {
return Err(anyhow!("Provider lease must expire after validFromUtc"));
}
Ok(())
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultMeshProviderLeaseRenewalWire {
pub lease_id: String,
pub requested_lease_duration_ms: i32,
}
impl CultMeshProviderSessionPayload for CultMeshProviderLeaseRenewalWire {
fn validate(&self) -> Result<()> {
require_text(&self.lease_id, "leaseId")?;
require_positive(self.requested_lease_duration_ms, "requestedLeaseDurationMs")
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultMeshProviderPublicationPutWire {
pub lease_id: String,
pub publication_id: String,
pub document: CultNetRawDocumentRecord,
}
impl CultMeshProviderSessionPayload for CultMeshProviderPublicationPutWire {
fn validate(&self) -> Result<()> {
require_text(&self.lease_id, "leaseId")?;
require_text(&self.publication_id, "publicationId")?;
validate_raw_document(&self.document)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultMeshProviderPublicationDeleteWire {
pub lease_id: String,
pub publication_id: String,
pub schema_id: String,
pub record_key: String,
}
impl CultMeshProviderSessionPayload for CultMeshProviderPublicationDeleteWire {
fn validate(&self) -> Result<()> {
require_text(&self.lease_id, "leaseId")?;
require_text(&self.publication_id, "publicationId")?;
require_text(&self.schema_id, "schemaId")?;
require_text(&self.record_key, "recordKey")
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultMeshProviderCommandWire {
pub command_id: String,
pub command_kind: String,
pub provider_id: String,
pub service_instance_id: String,
pub payload: Value,
}
impl CultMeshProviderSessionPayload for CultMeshProviderCommandWire {
fn validate(&self) -> Result<()> {
require_text(&self.command_id, "commandId")?;
require_text(&self.command_kind, "commandKind")?;
require_text(&self.provider_id, "providerId")?;
require_text(&self.service_instance_id, "serviceInstanceId")
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum CultMeshProviderReceiptStateWire {
Applied,
Rejected,
Failed,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultMeshProviderCommandReceiptWire {
pub receipt_id: String,
pub command_id: String,
pub command_kind: String,
pub provider_id: String,
pub service_instance_id: String,
pub state: CultMeshProviderReceiptStateWire,
pub completed_at_utc: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub result: Option<Value>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub error: Option<String>,
}
impl CultMeshProviderSessionPayload for CultMeshProviderCommandReceiptWire {
fn validate(&self) -> Result<()> {
require_text(&self.receipt_id, "receiptId")?;
require_text(&self.command_id, "commandId")?;
require_text(&self.command_kind, "commandKind")?;
require_text(&self.provider_id, "providerId")?;
require_text(&self.service_instance_id, "serviceInstanceId")?;
require_timestamp(&self.completed_at_utc, "completedAtUtc")?;
require_optional_text(self.error.as_deref(), "error")
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultMeshProviderReceiptPutWire {
pub lease_id: String,
pub receipt: CultMeshProviderCommandReceiptWire,
}
impl CultMeshProviderSessionPayload for CultMeshProviderReceiptPutWire {
fn validate(&self) -> Result<()> {
require_text(&self.lease_id, "leaseId")?;
self.receipt.validate()
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultMeshProviderWithdrawalWire {
pub lease_id: String,
}
impl CultMeshProviderSessionPayload for CultMeshProviderWithdrawalWire {
fn validate(&self) -> Result<()> {
require_text(&self.lease_id, "leaseId")
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultMeshProviderMutationAcceptanceWire {
pub accepted_at_utc: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub lease_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub publication_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub command_id: Option<String>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub receipt_id: Option<String>,
}
impl CultMeshProviderSessionPayload for CultMeshProviderMutationAcceptanceWire {
fn validate(&self) -> Result<()> {
require_timestamp(&self.accepted_at_utc, "acceptedAtUtc")?;
require_optional_text(self.lease_id.as_deref(), "leaseId")?;
require_optional_text(self.publication_id.as_deref(), "publicationId")?;
require_optional_text(self.command_id.as_deref(), "commandId")?;
require_optional_text(self.receipt_id.as_deref(), "receiptId")
}
}
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct CultMeshProviderErrorWire {}
impl CultMeshProviderSessionPayload for CultMeshProviderErrorWire {
fn validate(&self) -> Result<()> {
Ok(())
}
}
pub fn encode_provider_session_payload<T>(value: &T) -> Result<String>
where
T: CultMeshProviderSessionPayload + Serialize,
{
value.validate()?;
Ok(STANDARD.encode(rmp_serde::to_vec_named(value)?))
}
pub fn encode_provider_connect_evidence(
evidence: &CultMeshProviderConnectEvidenceWire,
) -> Result<Vec<u8>> {
evidence.validate()?;
Ok(rmp_serde::to_vec_named(evidence)?)
}
pub fn decode_provider_connect_evidence(
payload: &[u8],
) -> Result<CultMeshProviderConnectEvidenceWire> {
if payload.is_empty() {
return Err(anyhow!(
"Provider Connect evidence must be a non-empty MessagePack map"
));
}
let evidence: CultMeshProviderConnectEvidenceWire = rmp_serde::from_slice(payload)?;
evidence.validate()?;
Ok(evidence)
}
pub fn decode_provider_session_payload<T>(payload: &str) -> Result<T>
where
T: CultMeshProviderSessionPayload + DeserializeOwned,
{
require_text(payload, "payload")?;
let bytes = STANDARD
.decode(payload)
.map_err(|error| anyhow!("Provider-session payload must be MessagePack base64: {error}"))?;
let value: T = rmp_serde::from_slice(&bytes)?;
value.validate()?;
Ok(value)
}
pub fn decode_provider_command_document(
document: &CultNetRawDocumentRecord,
) -> Result<CultMeshProviderCommandWire> {
if document.schema_id != CULTMESH_PROVIDER_COMMAND_SCHEMA {
return Err(anyhow!(
"Expected provider command schema {:?}, received {:?}",
CULTMESH_PROVIDER_COMMAND_SCHEMA,
document.schema_id
));
}
let command: CultMeshProviderCommandWire = rmp_serde::from_slice(&document.payload)?;
command.validate()?;
Ok(command)
}
pub fn create_provider_session_request<T>(
message_id: impl Into<String>,
operation: impl Into<String>,
payload_schema: impl Into<String>,
payload: &T,
source_runtime_id: Option<String>,
target_runtime_id: Option<String>,
) -> Result<CultNetMessage>
where
T: CultMeshProviderSessionPayload + Serialize,
{
let message_id = message_id.into();
let operation = operation.into();
let payload_schema = payload_schema.into();
require_text(&message_id, "messageId")?;
validate_operation_schema(&operation, &payload_schema)?;
Ok(CultNetMessage::OperationRequest {
message_id,
service_id: CULTMESH_PROVIDER_SESSION_SERVICE_ID.to_string(),
operation,
payload_schema,
payload_encoding: CULTMESH_PROVIDER_SESSION_PAYLOAD_ENCODING.to_string(),
payload: encode_provider_session_payload(payload)?,
source_runtime_id,
target_runtime_id,
})
}
pub fn decode_provider_session_request<T>(
request: &CultNetMessage,
expected_operation: &str,
expected_payload_schema: &str,
) -> Result<T>
where
T: CultMeshProviderSessionPayload + DeserializeOwned,
{
let CultNetMessage::OperationRequest {
service_id,
operation,
payload_schema,
payload_encoding,
payload,
..
} = request
else {
return Err(anyhow!("Expected a CultNet operation request"));
};
require_envelope(
service_id,
operation,
payload_schema,
payload_encoding,
expected_operation,
expected_payload_schema,
)?;
decode_provider_session_payload(payload)
}
pub fn create_provider_session_response<T>(
request: &CultNetMessage,
status: CultMeshProviderOperationStatus,
payload_schema: impl Into<String>,
payload: &T,
source_runtime_id: Option<String>,
) -> Result<CultNetMessage>
where
T: CultMeshProviderSessionPayload + Serialize,
{
let CultNetMessage::OperationRequest {
message_id,
operation,
..
} = request
else {
return Err(anyhow!("Expected a CultNet operation request"));
};
require_text(message_id, "messageId")?;
require_text(operation, "operation")?;
let payload_schema = payload_schema.into();
require_text(&payload_schema, "payloadSchema")?;
Ok(CultNetMessage::OperationResponse {
message_id: message_id.clone(),
service_id: CULTMESH_PROVIDER_SESSION_SERVICE_ID.to_string(),
operation: operation.clone(),
status: status.as_str().to_string(),
payload_schema,
payload_encoding: CULTMESH_PROVIDER_SESSION_PAYLOAD_ENCODING.to_string(),
payload: encode_provider_session_payload(payload)?,
diagnostics: Vec::new(),
source_runtime_id,
})
}
pub fn create_provider_session_error_response(
request: &CultNetMessage,
status: CultMeshProviderOperationStatus,
diagnostics: Vec<String>,
source_runtime_id: Option<String>,
) -> Result<CultNetMessage> {
if status == CultMeshProviderOperationStatus::Ok {
return Err(anyhow!(
"Provider-session error responses require a non-ok status"
));
}
if diagnostics.is_empty() {
return Err(anyhow!(
"Provider-session error responses require diagnostics"
));
}
for diagnostic in &diagnostics {
require_text(diagnostic, "diagnostics[]")?;
}
let mut response = create_provider_session_response(
request,
status,
CULTMESH_PROVIDER_MUTATION_ACCEPTANCE_SCHEMA,
&CultMeshProviderErrorWire {},
source_runtime_id,
)?;
let CultNetMessage::OperationResponse {
diagnostics: response_diagnostics,
..
} = &mut response
else {
unreachable!("provider-session response helper returned a request")
};
*response_diagnostics = diagnostics;
Ok(response)
}
pub fn decode_provider_session_response<T>(
response: &CultNetMessage,
expected_operation: &str,
expected_payload_schema: &str,
) -> Result<(CultMeshProviderOperationStatus, T)>
where
T: CultMeshProviderSessionPayload + DeserializeOwned,
{
let CultNetMessage::OperationResponse {
service_id,
operation,
status,
payload_schema,
payload_encoding,
payload,
..
} = response
else {
return Err(anyhow!("Expected a CultNet operation response"));
};
require_envelope(
service_id,
operation,
payload_schema,
payload_encoding,
expected_operation,
expected_payload_schema,
)?;
Ok((
CultMeshProviderOperationStatus::parse(status)?,
decode_provider_session_payload(payload)?,
))
}
fn validate_operation_schema(operation: &str, payload_schema: &str) -> Result<()> {
let expected = match operation {
CULTMESH_PROVIDER_REGISTER_OPERATION => CULTMESH_PROVIDER_REGISTRATION_SCHEMA,
CULTMESH_PROVIDER_RENEW_OPERATION => CULTMESH_PROVIDER_LEASE_RENEWAL_SCHEMA,
CULTMESH_PROVIDER_PUBLICATION_PUT_OPERATION => CULTMESH_PROVIDER_PUBLICATION_PUT_SCHEMA,
CULTMESH_PROVIDER_PUBLICATION_DELETE_OPERATION => {
CULTMESH_PROVIDER_PUBLICATION_DELETE_SCHEMA
}
CULTMESH_PROVIDER_RECEIPT_PUT_OPERATION => CULTMESH_PROVIDER_RECEIPT_PUT_SCHEMA,
CULTMESH_PROVIDER_WITHDRAW_OPERATION => CULTMESH_PROVIDER_WITHDRAWAL_SCHEMA,
_ => {
return Err(anyhow!(
"Unsupported provider-session operation {operation:?}"
));
}
};
if payload_schema != expected {
return Err(anyhow!(
"Provider-session operation {operation:?} requires payload schema {expected:?}"
));
}
Ok(())
}
fn require_envelope(
service_id: &str,
operation: &str,
payload_schema: &str,
payload_encoding: &str,
expected_operation: &str,
expected_payload_schema: &str,
) -> Result<()> {
if service_id != CULTMESH_PROVIDER_SESSION_SERVICE_ID {
return Err(anyhow!(
"Unexpected provider-session service id {service_id:?}"
));
}
if operation != expected_operation {
return Err(anyhow!(
"Unexpected provider-session operation {operation:?}"
));
}
if payload_schema != expected_payload_schema {
return Err(anyhow!(
"Unexpected provider-session payload schema {payload_schema:?}"
));
}
if payload_encoding != CULTMESH_PROVIDER_SESSION_PAYLOAD_ENCODING {
return Err(anyhow!(
"Unexpected provider-session payload encoding {payload_encoding:?}"
));
}
Ok(())
}
fn validate_raw_document(document: &CultNetRawDocumentRecord) -> Result<()> {
require_text(&document.schema_id, "document.schemaId")?;
require_text(&document.record_key, "document.recordKey")?;
Ok(())
}
fn require_identity(
provider_id: &str,
service_instance_id: &str,
endpoint_id: &str,
verse_id: &str,
) -> Result<()> {
require_text(provider_id, "providerId")?;
require_text(service_instance_id, "serviceInstanceId")?;
require_text(endpoint_id, "endpointId")?;
require_text(verse_id, "verseId")
}
fn require_text(value: &str, field: &str) -> Result<()> {
if value.trim().is_empty() {
return Err(anyhow!("Provider-session {field} must not be empty"));
}
Ok(())
}
fn require_optional_text(value: Option<&str>, field: &str) -> Result<()> {
if let Some(value) = value {
require_text(value, field)?;
}
Ok(())
}
fn require_positive(value: i32, field: &str) -> Result<()> {
if value <= 0 {
return Err(anyhow!(
"Provider-session {field} must be greater than zero"
));
}
Ok(())
}
fn require_timestamp(value: &str, field: &str) -> Result<DateTime<chrono::FixedOffset>> {
require_text(value, field)?;
DateTime::parse_from_rfc3339(value)
.map_err(|error| anyhow!("Provider-session {field} must be RFC3339: {error}"))
}

View file

@ -9,6 +9,13 @@ use serde::de::DeserializeOwned;
use serde_json::Value;
use std::collections::BTreeMap;
use std::collections::BTreeSet;
use std::sync::Arc;
use std::sync::Mutex;
use std::sync::atomic::AtomicBool;
use std::sync::atomic::Ordering;
use std::thread;
use std::thread::JoinHandle;
use std::time::Duration;
use crate::CultNetDocumentMutationContract;
use crate::CultNetDocumentRecord;
@ -67,6 +74,56 @@ pub struct CultNetDocumentRegistry {
bindings_by_schema_id: BTreeMap<String, CultNetDocumentBinding>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CultNetReactiveDocumentOptions {
pub flush_delay: Duration,
pub detect_local_changes: bool,
pub replace_dirty_current_on_canonical_snapshot: bool,
}
impl Default for CultNetReactiveDocumentOptions {
fn default() -> Self {
Self {
flush_delay: Duration::from_millis(16),
detect_local_changes: true,
replace_dirty_current_on_canonical_snapshot: false,
}
}
}
#[derive(Clone, Debug, PartialEq)]
pub struct CultNetReactiveDocumentReconciliation<T> {
pub canonical: T,
pub predicted: T,
pub delta: BTreeMap<String, Value>,
pub version: u64,
pub received_at: String,
}
struct CultNetReactiveDocumentState<T> {
dirty: bool,
flushing: bool,
flush_queued: bool,
last_clean_payload: Vec<u8>,
reconciliation: Option<CultNetReactiveDocumentReconciliation<T>>,
reconciliation_version: u64,
last_error: Option<String>,
}
pub struct CultNetReactiveDocument<T>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
registry: CultNetDocumentRegistry,
cache: Arc<Mutex<CultCache>>,
record_key: String,
current: Arc<Mutex<T>>,
state: Arc<Mutex<CultNetReactiveDocumentState<T>>>,
options: CultNetReactiveDocumentOptions,
disposed: Arc<AtomicBool>,
detect_worker: Option<JoinHandle<()>>,
}
impl CultNetDocumentRegistry {
pub fn new() -> Self {
Self::default()
@ -352,6 +409,40 @@ impl CultNetDocumentRegistry {
Ok(applied)
}
pub fn sync_document_from_snapshot_response<T>(
&self,
cache: &mut CultCache,
response: &CultNetMessage,
record_key: &str,
) -> Result<T>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
let CultNetMessage::SnapshotResponse { documents, .. } = response else {
return Err(anyhow!("expected cultnet.snapshot_response.v0"));
};
let binding = self.require_binding(T::TYPE)?;
let document = documents
.iter()
.find(|document| {
document.schema_id == binding.schema_id && document.record_key == record_key
})
.ok_or_else(|| {
anyhow!(
"No CultNet snapshot document for schema {:?} and record key {:?}",
binding.schema_id,
record_key
)
})?;
self.apply_document_put_message::<T>(
cache,
&CultNetMessage::DocumentPut {
message_id: "snapshot-sync".to_string(),
document: document.clone(),
},
)
}
pub fn apply_raw_snapshot_response<T>(
&self,
cache: &mut CultCache,
@ -380,6 +471,52 @@ impl CultNetDocumentRegistry {
Ok(applied)
}
pub fn sync_raw_document_from_snapshot_response<T>(
&self,
cache: &mut CultCache,
response: &CultNetMessage,
record_key: &str,
) -> Result<T>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
let CultNetMessage::SnapshotResponseRaw { documents, .. } = response else {
return Err(anyhow!("expected cultnet.snapshot_response_raw.v0"));
};
let binding = self.require_binding(T::TYPE)?;
let document = documents
.iter()
.find(|document| {
document.schema_id == binding.schema_id && document.record_key == record_key
})
.ok_or_else(|| {
anyhow!(
"No raw CultNet snapshot document for schema {:?} and record key {:?}",
binding.schema_id,
record_key
)
})?;
self.apply_raw_document_put_message::<T>(
cache,
&CultNetMessage::DocumentPutRaw {
message_id: "snapshot-sync-raw".to_string(),
document: document.clone(),
},
)
}
pub fn reactive_document<T>(
&self,
cache: Arc<Mutex<CultCache>>,
record_key: impl Into<String>,
options: CultNetReactiveDocumentOptions,
) -> Result<CultNetReactiveDocument<T>>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
CultNetReactiveDocument::new(self.clone(), cache, record_key, options)
}
fn document_record_from_envelope(
&self,
envelope: &CultCacheEnvelope,
@ -428,6 +565,443 @@ impl CultNetDocumentRegistry {
}
}
impl<T> CultNetReactiveDocument<T>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
pub fn new(
registry: CultNetDocumentRegistry,
cache: Arc<Mutex<CultCache>>,
record_key: impl Into<String>,
options: CultNetReactiveDocumentOptions,
) -> Result<Self> {
let record_key = record_key.into();
if record_key.trim().is_empty() {
return Err(anyhow!("record_key must be non-empty"));
}
registry.require_binding(T::TYPE)?;
let current = {
let cache = cache
.lock()
.map_err(|_| anyhow!("CultCache mutex poisoned"))?;
cache.get_required::<T>(&record_key)?
};
let last_clean_payload = serialize_typed(&current)?;
let current = Arc::new(Mutex::new(current));
let state = Arc::new(Mutex::new(CultNetReactiveDocumentState {
dirty: false,
flushing: false,
flush_queued: false,
last_clean_payload,
reconciliation: None,
reconciliation_version: 0,
last_error: None,
}));
let disposed = Arc::new(AtomicBool::new(false));
let detect_worker = if options.detect_local_changes {
Some(start_reactive_detection_worker::<T>(
Arc::clone(&cache),
Arc::clone(&current),
Arc::clone(&state),
Arc::clone(&disposed),
options.flush_delay,
record_key.clone(),
))
} else {
None
};
Ok(Self {
registry,
cache,
record_key,
current,
state,
options,
disposed,
detect_worker,
})
}
pub fn current(&self) -> Arc<Mutex<T>> {
Arc::clone(&self.current)
}
pub fn record_key(&self) -> &str {
&self.record_key
}
pub fn is_dirty(&self) -> bool {
self.state.lock().map(|state| state.dirty).unwrap_or(false)
}
pub fn reconciliation(&self) -> Option<CultNetReactiveDocumentReconciliation<T>> {
self.state
.lock()
.ok()
.and_then(|state| state.reconciliation.clone())
}
pub fn last_error(&self) -> Option<String> {
self.state
.lock()
.ok()
.and_then(|state| state.last_error.clone())
}
pub fn update(&self, update: impl FnOnce(&mut T)) -> Result<T> {
let predicted = {
let mut current = self
.current
.lock()
.map_err(|_| anyhow!("reactive document mutex poisoned"))?;
update(&mut current);
current.clone()
};
{
let mut state = self
.state
.lock()
.map_err(|_| anyhow!("reactive document state mutex poisoned"))?;
state.dirty = true;
}
if self.options.flush_delay.is_zero() {
self.flush()?;
}
Ok(predicted)
}
pub fn set_current(&self, value: T) -> Result<T> {
{
let mut current = self
.current
.lock()
.map_err(|_| anyhow!("reactive document mutex poisoned"))?;
*current = value.clone();
}
{
let mut state = self
.state
.lock()
.map_err(|_| anyhow!("reactive document state mutex poisoned"))?;
state.dirty = true;
}
if self.options.flush_delay.is_zero() {
self.flush()?;
}
Ok(value)
}
pub fn mark_dirty(&self) -> Result<()> {
let mut state = self
.state
.lock()
.map_err(|_| anyhow!("reactive document state mutex poisoned"))?;
state.dirty = true;
Ok(())
}
pub fn refresh(&self) -> Result<T> {
let canonical = {
let cache = self
.cache
.lock()
.map_err(|_| anyhow!("CultCache mutex poisoned"))?;
cache.get_required::<T>(&self.record_key)?
};
{
let mut current = self
.current
.lock()
.map_err(|_| anyhow!("reactive document mutex poisoned"))?;
*current = canonical.clone();
}
{
let mut state = self
.state
.lock()
.map_err(|_| anyhow!("reactive document state mutex poisoned"))?;
state.last_clean_payload = serialize_typed(&canonical)?;
state.dirty = false;
state.flush_queued = false;
state.reconciliation = None;
}
Ok(canonical)
}
pub fn flush(&self) -> Result<()> {
flush_reactive_document::<T>(&self.cache, &self.current, &self.state, &self.record_key)
}
pub fn apply_document_put_message(&self, message: &CultNetMessage) -> Result<T> {
let canonical = {
let mut cache = self
.cache
.lock()
.map_err(|_| anyhow!("CultCache mutex poisoned"))?;
self.registry
.apply_document_put_message::<T>(&mut cache, message)?
};
self.apply_canonical_value(canonical)
}
pub fn apply_raw_document_put_message(&self, message: &CultNetMessage) -> Result<T> {
let canonical = {
let mut cache = self
.cache
.lock()
.map_err(|_| anyhow!("CultCache mutex poisoned"))?;
self.registry
.apply_raw_document_put_message::<T>(&mut cache, message)?
};
self.apply_canonical_value(canonical)
}
pub fn clear_reconciliation(&self) -> Result<()> {
let mut state = self
.state
.lock()
.map_err(|_| anyhow!("reactive document state mutex poisoned"))?;
state.reconciliation = None;
Ok(())
}
fn apply_canonical_value(&self, canonical: T) -> Result<T> {
let predicted = self
.current
.lock()
.map_err(|_| anyhow!("reactive document mutex poisoned"))?
.clone();
let mut state = self
.state
.lock()
.map_err(|_| anyhow!("reactive document state mutex poisoned"))?;
if state.dirty || state.flushing {
let delta = create_reconciliation_delta(&predicted, &canonical)?;
if delta.is_empty() {
state.reconciliation = None;
} else {
state.reconciliation_version += 1;
state.reconciliation = Some(CultNetReactiveDocumentReconciliation {
canonical: canonical.clone(),
predicted,
delta,
version: state.reconciliation_version,
received_at: now_utc_second(),
});
}
if !self.options.replace_dirty_current_on_canonical_snapshot {
return Ok(canonical);
}
}
drop(state);
{
let mut current = self
.current
.lock()
.map_err(|_| anyhow!("reactive document mutex poisoned"))?;
*current = canonical.clone();
}
let mut state = self
.state
.lock()
.map_err(|_| anyhow!("reactive document state mutex poisoned"))?;
state.last_clean_payload = serialize_typed(&canonical)?;
state.reconciliation = None;
Ok(canonical)
}
}
impl<T> Drop for CultNetReactiveDocument<T>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
fn drop(&mut self) {
self.disposed.store(true, Ordering::SeqCst);
let _ = self.detect_worker.take();
}
}
fn start_reactive_detection_worker<T>(
cache: Arc<Mutex<CultCache>>,
current: Arc<Mutex<T>>,
state: Arc<Mutex<CultNetReactiveDocumentState<T>>>,
disposed: Arc<AtomicBool>,
flush_delay: Duration,
record_key: String,
) -> JoinHandle<()>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
thread::spawn(move || {
let delay = if flush_delay.is_zero() {
Duration::from_millis(1)
} else {
flush_delay
};
while !disposed.load(Ordering::SeqCst) {
thread::sleep(delay);
match detect_reactive_document_change::<T>(&current, &state).and_then(|dirty| {
if dirty {
flush_reactive_document::<T>(&cache, &current, &state, &record_key)?;
}
Ok(())
}) {
Ok(()) => {}
Err(error) => {
if let Ok(mut state) = state.lock() {
state.last_error = Some(error.to_string());
}
}
}
}
})
}
fn detect_reactive_document_change<T>(
current: &Arc<Mutex<T>>,
state: &Arc<Mutex<CultNetReactiveDocumentState<T>>>,
) -> Result<bool>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
let payload = {
let current = current
.lock()
.map_err(|_| anyhow!("reactive document mutex poisoned"))?;
serialize_typed(&*current)?
};
let mut state = state
.lock()
.map_err(|_| anyhow!("reactive document state mutex poisoned"))?;
if !state.dirty && !state.flushing && payload != state.last_clean_payload {
state.dirty = true;
}
Ok(state.dirty && !state.flushing)
}
fn flush_reactive_document<T>(
cache: &Arc<Mutex<CultCache>>,
current: &Arc<Mutex<T>>,
state: &Arc<Mutex<CultNetReactiveDocumentState<T>>>,
record_key: &str,
) -> Result<()>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
let predicted = {
let mut state_guard = state
.lock()
.map_err(|_| anyhow!("reactive document state mutex poisoned"))?;
if !state_guard.dirty {
drop(state_guard);
if !detect_reactive_document_change::<T>(current, state)? {
return Ok(());
}
state_guard = state
.lock()
.map_err(|_| anyhow!("reactive document state mutex poisoned"))?;
}
if state_guard.flushing {
state_guard.flush_queued = true;
return Ok(());
}
state_guard.flushing = true;
state_guard.dirty = false;
current
.lock()
.map_err(|_| anyhow!("reactive document mutex poisoned"))?
.clone()
};
let payload = serialize_typed(&predicted)?;
{
let mut cache = cache
.lock()
.map_err(|_| anyhow!("CultCache mutex poisoned"))?;
cache.put::<T>(record_key.to_string(), &predicted)?;
}
let should_flush_again = {
let mut state = state
.lock()
.map_err(|_| anyhow!("reactive document state mutex poisoned"))?;
state.flushing = false;
state.last_clean_payload = payload;
state.last_error = None;
state.reconciliation = None;
let changed_after_flush = {
let current = current
.lock()
.map_err(|_| anyhow!("reactive document mutex poisoned"))?;
serialize_typed(&*current)? != state.last_clean_payload
};
if changed_after_flush {
state.dirty = true;
}
let should_flush_again = state.flush_queued || state.dirty;
state.flush_queued = false;
should_flush_again
};
if should_flush_again {
flush_reactive_document::<T>(cache, current, state, record_key)?;
}
Ok(())
}
fn serialize_typed<T>(value: &T) -> Result<Vec<u8>>
where
T: Serialize,
{
Ok(rmp_serde::to_vec(value)?)
}
fn create_reconciliation_delta<T>(predicted: &T, canonical: &T) -> Result<BTreeMap<String, Value>>
where
T: Serialize,
{
let predicted = serde_json::to_value(predicted)?;
let canonical = serde_json::to_value(canonical)?;
let mut delta = BTreeMap::new();
match (predicted, canonical) {
(Value::Object(predicted), Value::Object(canonical)) => {
for (key, predicted_value) in predicted {
let canonical_value = canonical.get(&key).cloned().unwrap_or(Value::Null);
if predicted_value == canonical_value {
continue;
}
delta.insert(
key,
numeric_delta(&predicted_value, &canonical_value).unwrap_or(predicted_value),
);
}
}
(Value::Array(predicted), Value::Array(canonical)) => {
for (index, predicted_value) in predicted.into_iter().enumerate() {
let canonical_value = canonical.get(index).cloned().unwrap_or(Value::Null);
if predicted_value == canonical_value {
continue;
}
delta.insert(
index.to_string(),
numeric_delta(&predicted_value, &canonical_value).unwrap_or(predicted_value),
);
}
}
(predicted, canonical) if predicted != canonical => {
delta.insert(
"value".to_string(),
numeric_delta(&predicted, &canonical).unwrap_or(predicted),
);
}
_ => {}
}
Ok(delta)
}
fn numeric_delta(predicted: &Value, canonical: &Value) -> Option<Value> {
let predicted = predicted.as_f64()?;
let canonical = canonical.as_f64()?;
serde_json::Number::from_f64(predicted - canonical).map(Value::Number)
}
fn round_trip_typed<T>(value: &T) -> Result<T>
where
T: Serialize + DeserializeOwned,

File diff suppressed because it is too large Load diff

View file

@ -353,6 +353,20 @@ pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
Some("cultnet.schema_catalog_response.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.shard-catalog-request.schema.json"),
CultNetSchemaKind::WireMessage,
vec![CultNetWireContract::CultNetSchemaV0],
Some("cultnet.shard_catalog_request.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.shard-catalog-response.schema.json"),
CultNetSchemaKind::WireMessage,
vec![CultNetWireContract::CultNetSchemaV0],
Some("cultnet.shard_catalog_response.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/ghostlight.agent-state.schema.json"),
CultNetSchemaKind::DocumentPayload,

View file

@ -703,4 +703,3 @@ mod tests {
Ok(())
}
}

134
vendor/cultnet-rs/src/shard_catalog.rs vendored Normal file
View file

@ -0,0 +1,134 @@
use anyhow::Result;
use anyhow::anyhow;
use std::collections::BTreeMap;
use std::collections::BTreeSet;
use crate::CultNetMessage;
use crate::CultNetShardDescriptor;
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct CultNetShardCatalogOptions {
pub schema_ids: Option<Vec<String>>,
pub record_keys: Option<Vec<String>>,
}
#[derive(Clone, Debug, Default)]
pub struct CultNetShardCatalog {
shards: BTreeMap<String, CultNetShardDescriptor>,
}
impl CultNetShardCatalog {
pub fn new() -> Self {
Self::default()
}
pub fn upsert(&mut self, descriptor: CultNetShardDescriptor) -> Result<()> {
validate_descriptor(&descriptor)?;
self.shards.insert(descriptor.shard_id.clone(), descriptor);
Ok(())
}
pub fn get(&self, shard_id: &str) -> Option<&CultNetShardDescriptor> {
self.shards.get(shard_id)
}
pub fn list(&self, options: &CultNetShardCatalogOptions) -> Vec<CultNetShardDescriptor> {
let schema_ids = options
.schema_ids
.as_ref()
.map(|values| values.iter().cloned().collect::<BTreeSet<_>>());
let record_keys = options
.record_keys
.as_ref()
.map(|values| values.iter().cloned().collect::<BTreeSet<_>>());
self.shards
.values()
.filter(|shard| {
let schema_match = schema_ids.as_ref().is_none_or(|requested| {
requested
.iter()
.any(|schema_id| shard.serves(Some(schema_id), None))
});
let key_match = record_keys.as_ref().is_none_or(|requested| {
requested
.iter()
.any(|record_key| shard.serves(None, Some(record_key)))
});
schema_match && key_match
})
.cloned()
.collect()
}
pub fn create_catalog_response(&self, request: &CultNetMessage) -> Result<CultNetMessage> {
let CultNetMessage::ShardCatalogRequest {
message_id,
schema_ids,
record_keys,
} = request
else {
return Err(anyhow!(
"expected cultnet.shard_catalog_request.v0 for shard discovery"
));
};
Ok(CultNetMessage::ShardCatalogResponse {
message_id: message_id.clone(),
shards: self.list(&CultNetShardCatalogOptions {
schema_ids: schema_ids.clone(),
record_keys: record_keys.clone(),
}),
})
}
pub fn apply_response(
&mut self,
response: &CultNetMessage,
) -> Result<Vec<CultNetShardDescriptor>> {
let CultNetMessage::ShardCatalogResponse { shards, .. } = response else {
return Err(anyhow!(
"expected cultnet.shard_catalog_response.v0 for shard discovery"
));
};
let mut applied = Vec::with_capacity(shards.len());
for shard in shards {
self.upsert(shard.clone())?;
applied.push(shard.clone());
}
Ok(applied)
}
}
fn validate_descriptor(descriptor: &CultNetShardDescriptor) -> Result<()> {
if descriptor.shard_id.trim().is_empty() {
return Err(anyhow!("shard_id must be non-empty"));
}
if descriptor.owner_runtime_id.trim().is_empty() {
return Err(anyhow!("owner_runtime_id must be non-empty"));
}
for schema_id in &descriptor.schema_ids {
if schema_id.trim().is_empty() {
return Err(anyhow!("schema_ids must not contain empty values"));
}
}
if descriptor
.key_prefix
.as_deref()
.is_some_and(|value| value.trim().is_empty())
{
return Err(anyhow!("key_prefix must be non-empty when present"));
}
for endpoint in descriptor
.primary_endpoints
.iter()
.chain(descriptor.replica_endpoints.iter())
.chain(descriptor.read_replica_endpoints.iter())
{
if endpoint.trim().is_empty() {
return Err(anyhow!("shard endpoints must not contain empty values"));
}
}
Ok(())
}

View file

@ -1,10 +1,9 @@
use anyhow::Result;
use anyhow::anyhow;
use serde::Deserialize;
use serde::Serialize;
use std::io::Read;
use std::io::Write;
use crate::CultNetReconnectPolicy;
use crate::CultNetTransportChannel;
use crate::CultNetTransportDelivery;
use crate::CultNetTransportDescriptor;
@ -20,7 +19,6 @@ pub struct CultNetTransportStats {
pub bytes_sent: u64,
pub frames_received: u64,
pub frames_sent: u64,
pub reliable_packets_expired: u64,
}
#[derive(Clone, Debug, PartialEq, Eq)]
@ -29,18 +27,6 @@ pub struct CultNetTransportFrame {
pub payload: Vec<u8>,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultNetReconnectPolicy {
pub schema_version: String,
pub policy_id: String,
pub base_delay_ms: u64,
pub max_delay_ms: u64,
pub max_jitter_ms: u64,
#[serde(skip_serializing_if = "Option::is_none")]
pub max_attempts: Option<u32>,
}
#[derive(Clone, Debug)]
pub struct CultNetReconnectPolicyOptions {
pub policy_id: String,
@ -91,6 +77,96 @@ pub fn compute_reconnect_delay_ms(
capped_base_delay + jitter_ms.min(policy.max_jitter_ms)
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CultNetReconnectDecision {
pub attempt: u32,
pub should_retry: bool,
pub delay_ms: u64,
pub next_attempt_at_ms: Option<u64>,
pub exhausted: bool,
}
#[derive(Clone, Debug)]
pub struct CultNetReconnectController {
pub policy: CultNetReconnectPolicy,
attempt: u32,
next_attempt_at_ms: Option<u64>,
exhausted: bool,
}
impl Default for CultNetReconnectController {
fn default() -> Self {
Self::new(create_reconnect_policy(Default::default()))
}
}
impl CultNetReconnectController {
pub fn new(policy: CultNetReconnectPolicy) -> Self {
Self {
policy,
attempt: 0,
next_attempt_at_ms: None,
exhausted: false,
}
}
pub fn attempt(&self) -> u32 {
self.attempt
}
pub fn next_attempt_at_ms(&self) -> Option<u64> {
self.next_attempt_at_ms
}
pub fn exhausted(&self) -> bool {
self.exhausted
}
pub fn reset(&mut self) {
self.attempt = 0;
self.next_attempt_at_ms = None;
self.exhausted = false;
}
pub fn can_attempt(&self, now_ms: u64) -> bool {
!self.exhausted
&& self
.next_attempt_at_ms
.is_none_or(|next_attempt_at_ms| now_ms >= next_attempt_at_ms)
}
pub fn record_failure(&mut self, now_ms: u64, jitter_ms: u64) -> CultNetReconnectDecision {
let next_attempt = self.attempt.saturating_add(1);
if self
.policy
.max_attempts
.is_some_and(|max_attempts| next_attempt > max_attempts)
{
self.exhausted = true;
self.next_attempt_at_ms = None;
return CultNetReconnectDecision {
attempt: self.attempt,
should_retry: false,
delay_ms: 0,
next_attempt_at_ms: None,
exhausted: true,
};
}
self.attempt = next_attempt;
let delay_ms = compute_reconnect_delay_ms(&self.policy, self.attempt, jitter_ms);
let next_attempt_at_ms = now_ms.saturating_add(delay_ms);
self.next_attempt_at_ms = Some(next_attempt_at_ms);
CultNetReconnectDecision {
attempt: self.attempt,
should_retry: true,
delay_ms,
next_attempt_at_ms: Some(next_attempt_at_ms),
exhausted: false,
}
}
}
#[derive(Clone, Debug, Default)]
pub struct TcpFramedTransportProfileOptions {
pub transport_id: Option<String>,
@ -117,6 +193,7 @@ pub fn create_tcp_framed_transport_profile(
path: None,
discovery_group: None,
wire_contracts: Some(vec!["cultnet.schema.v0".to_string()]),
reconnect_policy: None,
channels: vec![CultNetTransportChannel {
channel_id: "schema".to_string(),
delivery: CultNetTransportDelivery::Reliable,
@ -124,7 +201,6 @@ pub fn create_tcp_framed_transport_profile(
max_payload_bytes: options.max_payload_bytes,
max_fragment_bytes: options.max_fragment_bytes,
max_pending_reliable_packets: None,
reliable_expire_after_ms: None,
}],
}],
}

File diff suppressed because it is too large Load diff

View file

@ -0,0 +1,365 @@
use anyhow::Result;
use cultnet_rs::*;
const REGISTRATION_GOLDEN: &str = "hqpwcm92aWRlcklkqGFldGhlcmlhsXNlcnZpY2VJbnN0YW5jZUlkq2FldGhlcmlhLTQyqmVuZHBvaW50SWSvYWV0aGVyaWEtcHVibGljp3ZlcnNlSWSmcHVibGljuHJlcXVlc3RlZExlYXNlRHVyYXRpb25Nc811MLBhdXRob3JpdHlMZWFzZUlkq2F1dGhvcml0eS03";
const CONNECT_EVIDENCE_GOLDEN: &str =
"gq9jbGllbnRTZXNzaW9uSWSyYWV0aGVyaWEtY2xpZW50LTQyrHNlc3Npb25Ub2tlbrJvZGluLXNlc3Npb24tdG9rZW4=";
const TOKENLESS_CONNECT_EVIDENCE_GOLDEN: &str =
"gq9jbGllbnRTZXNzaW9uSWSwYW5vbnltb3VzLWNsaWVudKxzZXNzaW9uVG9rZW7A";
fn registration() -> CultMeshProviderRegistrationWire {
CultMeshProviderRegistrationWire {
provider_id: "aetheria".to_string(),
service_instance_id: "aetheria-42".to_string(),
endpoint_id: "aetheria-public".to_string(),
verse_id: "public".to_string(),
requested_lease_duration_ms: 30_000,
authority_lease_id: Some("authority-7".to_string()),
}
}
#[test]
fn registration_matches_csharp_and_typescript_golden_payload() -> Result<()> {
let encoded = encode_provider_session_payload(&registration())?;
assert_eq!(encoded, REGISTRATION_GOLDEN);
assert_eq!(
decode_provider_session_payload::<CultMeshProviderRegistrationWire>(&encoded)?,
registration()
);
Ok(())
}
#[test]
fn connect_evidence_is_a_validated_named_messagepack_map() -> Result<()> {
let evidence = CultMeshProviderConnectEvidenceWire {
client_session_id: "aetheria-client-42".to_string(),
session_token: Some("odin-session-token".to_string()),
};
let encoded = encode_provider_connect_evidence(&evidence)?;
assert_eq!(
base64::Engine::encode(&base64::engine::general_purpose::STANDARD, &encoded),
CONNECT_EVIDENCE_GOLDEN
);
assert_eq!(decode_provider_connect_evidence(&encoded)?, evidence);
let value: rmpv::Value = rmp_serde::from_slice(&encoded)?;
let map = value.as_map().expect("Connect evidence is a named map");
assert_eq!(
map.iter()
.find_map(|(key, value)| (key.as_str() == Some("clientSessionId")).then_some(value))
.and_then(rmpv::Value::as_str),
Some("aetheria-client-42")
);
assert_eq!(
map.iter()
.find_map(|(key, value)| (key.as_str() == Some("sessionToken")).then_some(value))
.and_then(rmpv::Value::as_str),
Some("odin-session-token")
);
assert!(
encode_provider_connect_evidence(&CultMeshProviderConnectEvidenceWire {
client_session_id: String::new(),
session_token: None,
})
.is_err()
);
assert!(
encode_provider_connect_evidence(&CultMeshProviderConnectEvidenceWire {
client_session_id: "client".to_string(),
session_token: Some(" ".to_string()),
})
.is_err()
);
assert!(decode_provider_connect_evidence(&[]).is_err());
let tokenless = CultMeshProviderConnectEvidenceWire {
client_session_id: "anonymous-client".to_string(),
session_token: None,
};
let tokenless_encoded = encode_provider_connect_evidence(&tokenless)?;
assert_eq!(
base64::Engine::encode(
&base64::engine::general_purpose::STANDARD,
&tokenless_encoded
),
TOKENLESS_CONNECT_EVIDENCE_GOLDEN
);
assert_eq!(
decode_provider_connect_evidence(&tokenless_encoded)?,
tokenless
);
Ok(())
}
#[test]
fn registration_round_trips_inside_canonical_operation_envelope() -> Result<()> {
let request = create_provider_session_request(
"register-1",
CULTMESH_PROVIDER_REGISTER_OPERATION,
CULTMESH_PROVIDER_REGISTRATION_SCHEMA,
&registration(),
Some("aetheria-42".to_string()),
Some("odin".to_string()),
)?;
let bytes = encode_cultnet_message_to_vec(&request, CultNetWireContract::CultNetSchemaV0)?;
let decoded_request =
decode_cultnet_message_from_slice(&bytes, CultNetWireContract::CultNetSchemaV0)?;
let decoded: CultMeshProviderRegistrationWire = decode_provider_session_request(
&decoded_request,
CULTMESH_PROVIDER_REGISTER_OPERATION,
CULTMESH_PROVIDER_REGISTRATION_SCHEMA,
)?;
assert_eq!(decoded, registration());
let lease = CultMeshProviderLeaseWire {
provider_id: "aetheria".to_string(),
service_instance_id: "aetheria-42".to_string(),
endpoint_id: "aetheria-public".to_string(),
verse_id: "public".to_string(),
lease_id: "lease-2".to_string(),
valid_from_utc: "2026-07-14T12:00:00Z".to_string(),
expires_at_utc: "2026-07-14T12:00:10Z".to_string(),
};
let response = create_provider_session_response(
&decoded_request,
CultMeshProviderOperationStatus::Ok,
CULTMESH_PROVIDER_LEASE_SCHEMA,
&lease,
Some("odin".to_string()),
)?;
let (status, decoded_lease) = decode_provider_session_response::<CultMeshProviderLeaseWire>(
&response,
CULTMESH_PROVIDER_REGISTER_OPERATION,
CULTMESH_PROVIDER_LEASE_SCHEMA,
)?;
assert_eq!(status, CultMeshProviderOperationStatus::Ok);
assert_eq!(decoded_lease, lease);
Ok(())
}
#[test]
fn publication_and_command_preserve_typed_messagepack_values() -> Result<()> {
let publication = CultMeshProviderPublicationPutWire {
lease_id: "lease-1".to_string(),
publication_id: "surface:pilot".to_string(),
document: CultNetRawDocumentRecord {
schema_id: "gamecult.eve.surface.v1".to_string(),
record_key: "eve:surface:pilot".to_string(),
stored_at: String::new(),
payload_encoding: CultNetRawPayloadEncoding::Messagepack,
payload: vec![0x81, 0xa2, 0x69, 0x64, 0x01],
source_runtime_id: Some("aetheria-42".to_string()),
source_agent_id: None,
source_role: None,
tags: None,
},
};
let publication_encoded = encode_provider_session_payload(&publication)?;
assert_eq!(
decode_provider_session_payload::<CultMeshProviderPublicationPutWire>(
&publication_encoded
)?,
publication
);
let command = CultMeshProviderCommandWire {
command_id: "cmd-7".to_string(),
command_kind: "pilot.thrust".to_string(),
provider_id: "aetheria".to_string(),
service_instance_id: "aetheria-42".to_string(),
payload: rmpv::Value::Map(vec![(rmpv::Value::from("axis"), rmpv::Value::F64(0.75))]),
};
let command_bytes = base64::Engine::decode(
&base64::engine::general_purpose::STANDARD,
encode_provider_session_payload(&command)?,
)?;
let decoded_command = decode_provider_command_document(&CultNetRawDocumentRecord {
schema_id: CULTMESH_PROVIDER_COMMAND_SCHEMA.to_string(),
record_key: "provider-command:aetheria:aetheria-42:cmd-7".to_string(),
stored_at: String::new(),
payload_encoding: CultNetRawPayloadEncoding::Messagepack,
payload: command_bytes,
source_runtime_id: Some("odin".to_string()),
source_agent_id: None,
source_role: Some("provider-session-broker".to_string()),
tags: None,
})?;
assert_eq!(decoded_command, command);
Ok(())
}
#[test]
fn lifecycle_validation_rejects_split_or_malformed_authority() {
let mismatched = create_provider_session_request(
"bad-schema",
CULTMESH_PROVIDER_REGISTER_OPERATION,
CULTMESH_PROVIDER_PUBLICATION_PUT_SCHEMA,
&registration(),
None,
None,
);
assert!(mismatched.is_err());
let malformed_lease = CultMeshProviderLeaseWire {
provider_id: "provider".to_string(),
service_instance_id: "instance".to_string(),
endpoint_id: "endpoint".to_string(),
verse_id: "verse".to_string(),
lease_id: "lease".to_string(),
valid_from_utc: "2026-07-14T12:00:10Z".to_string(),
expires_at_utc: "2026-07-14T12:00:00Z".to_string(),
};
assert!(encode_provider_session_payload(&malformed_lease).is_err());
let malformed_request = CultNetMessage::OperationRequest {
message_id: String::new(),
service_id: CULTMESH_PROVIDER_SESSION_SERVICE_ID.to_string(),
operation: String::new(),
payload_schema: CULTMESH_PROVIDER_REGISTRATION_SCHEMA.to_string(),
payload_encoding: CULTMESH_PROVIDER_SESSION_PAYLOAD_ENCODING.to_string(),
payload: REGISTRATION_GOLDEN.to_string(),
source_runtime_id: None,
target_runtime_id: None,
};
assert!(
create_provider_session_response(
&malformed_request,
CultMeshProviderOperationStatus::Invalid,
CULTMESH_PROVIDER_MUTATION_ACCEPTANCE_SCHEMA,
&CultMeshProviderMutationAcceptanceWire {
accepted_at_utc: "2026-07-14T12:00:00Z".to_string(),
lease_id: None,
publication_id: None,
command_id: None,
receipt_id: None,
},
None,
)
.is_err()
);
}
#[test]
fn remaining_lifecycle_payloads_round_trip_as_named_maps() -> Result<()> {
let renewal = CultMeshProviderLeaseRenewalWire {
lease_id: "lease-1".to_string(),
requested_lease_duration_ms: 30_000,
};
assert_eq!(
decode_provider_session_payload::<CultMeshProviderLeaseRenewalWire>(
&encode_provider_session_payload(&renewal)?
)?,
renewal
);
let deletion = CultMeshProviderPublicationDeleteWire {
lease_id: "lease-1".to_string(),
publication_id: "surface:pilot".to_string(),
schema_id: "gamecult.eve.surface.v1".to_string(),
record_key: "eve:surface:pilot".to_string(),
};
assert_eq!(
decode_provider_session_payload::<CultMeshProviderPublicationDeleteWire>(
&encode_provider_session_payload(&deletion)?
)?,
deletion
);
let receipt = CultMeshProviderReceiptPutWire {
lease_id: "lease-1".to_string(),
receipt: CultMeshProviderCommandReceiptWire {
receipt_id: "receipt-7".to_string(),
command_id: "cmd-7".to_string(),
command_kind: "pilot.thrust".to_string(),
provider_id: "aetheria".to_string(),
service_instance_id: "aetheria-42".to_string(),
state: CultMeshProviderReceiptStateWire::Applied,
completed_at_utc: "2026-07-14T12:01:02.345Z".to_string(),
result: Some(rmpv::Value::Map(vec![(
rmpv::Value::from("accepted"),
rmpv::Value::Boolean(true),
)])),
error: None,
},
};
assert_eq!(
decode_provider_session_payload::<CultMeshProviderReceiptPutWire>(
&encode_provider_session_payload(&receipt)?
)?,
receipt
);
let withdrawal = CultMeshProviderWithdrawalWire {
lease_id: "lease-1".to_string(),
};
assert_eq!(
decode_provider_session_payload::<CultMeshProviderWithdrawalWire>(
&encode_provider_session_payload(&withdrawal)?
)?,
withdrawal
);
let acceptance = CultMeshProviderMutationAcceptanceWire {
accepted_at_utc: "2026-07-14T12:01:03Z".to_string(),
lease_id: Some("lease-1".to_string()),
publication_id: Some("surface:pilot".to_string()),
command_id: None,
receipt_id: None,
};
assert_eq!(
decode_provider_session_payload::<CultMeshProviderMutationAcceptanceWire>(
&encode_provider_session_payload(&acceptance)?
)?,
acceptance
);
Ok(())
}
#[test]
fn non_ok_response_uses_correlated_empty_map_and_diagnostics() -> Result<()> {
let request = create_provider_session_request(
"register-denied",
CULTMESH_PROVIDER_REGISTER_OPERATION,
CULTMESH_PROVIDER_REGISTRATION_SCHEMA,
&registration(),
Some("aetheria-42".to_string()),
Some("odin".to_string()),
)?;
let response = create_provider_session_error_response(
&request,
CultMeshProviderOperationStatus::Denied,
vec!["registration authority rejected the session".to_string()],
Some("odin".to_string()),
)?;
let CultNetMessage::OperationResponse {
message_id,
operation,
status,
payload_schema,
payload,
diagnostics,
..
} = response
else {
panic!("expected operation response");
};
assert_eq!(message_id, "register-denied");
assert_eq!(operation, CULTMESH_PROVIDER_REGISTER_OPERATION);
assert_eq!(status, "denied");
assert_eq!(payload_schema, CULTMESH_PROVIDER_MUTATION_ACCEPTANCE_SCHEMA);
assert_eq!(diagnostics.len(), 1);
let bytes = base64::Engine::decode(&base64::engine::general_purpose::STANDARD, payload)?;
assert_eq!(
rmp_serde::from_slice::<rmpv::Value>(&bytes)?,
rmpv::Value::Map(Vec::new())
);
assert!(
create_provider_session_error_response(
&request,
CultMeshProviderOperationStatus::Ok,
vec!["not an error".to_string()],
None,
)
.is_err()
);
Ok(())
}

View file

@ -0,0 +1,459 @@
use std::net::UdpSocket;
use std::time::Duration;
use anyhow::{Result, anyhow};
use cultnet_rs::*;
const CONNECTION_ID: u32 = 0x4355_4c54;
fn socket() -> Result<UdpSocket> {
let socket = UdpSocket::bind("127.0.0.1:0")?;
socket.set_read_timeout(Some(Duration::from_millis(20)))?;
Ok(socket)
}
fn client(remote: std::net::SocketAddr) -> Result<CultNetRudpSocketTransportConnection> {
let mut options =
CultNetRudpSocketTransportOptions::client("provider", socket()?, remote, CONNECTION_ID);
options.max_fragment_bytes = Some(2_048);
CultNetRudpSocketTransportConnection::new(options)
}
fn connect(
hub: &mut CultNetRudpServerHub,
client: &mut CultNetRudpSocketTransportConnection,
evidence: &[u8],
) -> Result<CultNetRudpServerSessionContext> {
client.connect(evidence.to_vec())?;
let mut connected = None;
for _ in 0..20 {
if let Some(CultNetRudpServerEvent::Connected { session }) = hub.receive_event_once()? {
connected = Some(session);
break;
}
}
let session = connected.ok_or_else(|| anyhow!("hub did not receive Connect"))?;
let _ = client.receive_once()?;
assert!(client.connected());
Ok(session)
}
fn receive_frame(hub: &mut CultNetRudpServerHub) -> Result<CultNetRudpServerEvent> {
for _ in 0..20 {
if let Some(event @ CultNetRudpServerEvent::Frame { .. }) = hub.receive_event_once()? {
return Ok(event);
}
}
Err(anyhow!("hub did not receive a frame"))
}
fn receive_message(client: &mut CultNetRudpSocketTransportConnection) -> Result<CultNetMessage> {
for _ in 0..20 {
if let Some(message) = client.receive_schema_message_once()? {
return Ok(message);
}
}
Err(anyhow!("client did not receive a schema message"))
}
#[test]
fn hub_keeps_independent_peer_sessions_and_exposes_connect_evidence() -> Result<()> {
let server_socket = socket()?;
let server_addr = server_socket.local_addr()?;
let mut hub = CultNetRudpServerHub::new(CultNetRudpServerHubOptions::new(
"odin",
server_socket,
CONNECTION_ID,
))?;
let mut first = client(server_addr)?;
let mut second = client(server_addr)?;
let first_session = connect(&mut hub, &mut first, b"session-token-one")?;
let second_session = connect(&mut hub, &mut second, b"session-token-two")?;
assert_ne!(first_session.remote_addr, second_session.remote_addr);
assert_eq!(first_session.connect_payload, b"session-token-one");
assert_eq!(second_session.connect_payload, b"session-token-two");
assert_eq!(hub.sessions().len(), 2);
let first_request = create_provider_session_request(
"register-first",
CULTMESH_PROVIDER_REGISTER_OPERATION,
CULTMESH_PROVIDER_REGISTRATION_SCHEMA,
&CultMeshProviderRegistrationWire {
provider_id: "first".to_string(),
service_instance_id: "first-1".to_string(),
endpoint_id: "first-public".to_string(),
verse_id: "public".to_string(),
requested_lease_duration_ms: 30_000,
authority_lease_id: None,
},
Some("first-1".to_string()),
Some("odin".to_string()),
)?;
let second_request = create_provider_session_request(
"register-second",
CULTMESH_PROVIDER_REGISTER_OPERATION,
CULTMESH_PROVIDER_REGISTRATION_SCHEMA,
&CultMeshProviderRegistrationWire {
provider_id: "second".to_string(),
service_instance_id: "second-1".to_string(),
endpoint_id: "second-public".to_string(),
verse_id: "public".to_string(),
requested_lease_duration_ms: 30_000,
authority_lease_id: None,
},
Some("second-1".to_string()),
Some("odin".to_string()),
)?;
first.send_schema_message(&first_request)?;
second.send_schema_message(&second_request)?;
for _ in 0..2 {
let CultNetRudpServerEvent::Frame { session, frame } = receive_frame(&mut hub)? else {
unreachable!();
};
assert_eq!(frame.channel_id, "schema");
let request = decode_cultnet_message_from_slice(
&frame.payload,
CultNetWireContract::CultNetSchemaV0,
)?;
let CultNetMessage::OperationRequest { message_id, .. } = &request else {
return Err(anyhow!("expected operation request"));
};
let provider_id = if message_id == "register-first" {
"first"
} else {
"second"
};
let lease = CultMeshProviderLeaseWire {
provider_id: provider_id.to_string(),
service_instance_id: format!("{provider_id}-1"),
endpoint_id: format!("{provider_id}-public"),
verse_id: "public".to_string(),
lease_id: format!("lease-{provider_id}"),
valid_from_utc: "2026-07-14T12:00:00Z".to_string(),
expires_at_utc: "2026-07-14T12:00:30Z".to_string(),
};
let response = create_provider_session_response(
&request,
CultMeshProviderOperationStatus::Ok,
CULTMESH_PROVIDER_LEASE_SCHEMA,
&lease,
Some("odin".to_string()),
)?;
hub.send_schema_message(&session, &response)?;
}
let first_response = receive_message(&mut first)?;
let second_response = receive_message(&mut second)?;
let (_, first_lease) = decode_provider_session_response::<CultMeshProviderLeaseWire>(
&first_response,
CULTMESH_PROVIDER_REGISTER_OPERATION,
CULTMESH_PROVIDER_LEASE_SCHEMA,
)?;
let (_, second_lease) = decode_provider_session_response::<CultMeshProviderLeaseWire>(
&second_response,
CULTMESH_PROVIDER_REGISTER_OPERATION,
CULTMESH_PROVIDER_LEASE_SCHEMA,
)?;
assert_eq!(first_lease.provider_id, "first");
assert_eq!(second_lease.provider_id, "second");
assert_eq!(hub.session(first_session.remote_addr), Some(&first_session));
assert_eq!(
hub.session(second_session.remote_addr),
Some(&second_session)
);
Ok(())
}
#[test]
fn hub_fences_replaced_generations_and_does_not_replace_connect_retransmits() -> Result<()> {
let server_socket = socket()?;
let server_addr = server_socket.local_addr()?;
let mut hub = CultNetRudpServerHub::new(CultNetRudpServerHubOptions::new(
"odin",
server_socket,
CONNECTION_ID,
))?;
let mut provider = client(server_addr)?;
let original_evidence =
encode_provider_connect_evidence(&CultMeshProviderConnectEvidenceWire {
client_session_id: "provider-client-1".to_string(),
session_token: Some("shared-session-token".to_string()),
})?;
let replacement_evidence =
encode_provider_connect_evidence(&CultMeshProviderConnectEvidenceWire {
client_session_id: "provider-client-2".to_string(),
session_token: Some("shared-session-token".to_string()),
})?;
let original = connect(&mut hub, &mut provider, &original_evidence)?;
provider.connect(original_evidence.clone())?;
for _ in 0..3 {
assert!(hub.receive_event_once()?.is_none());
}
assert_eq!(hub.session(original.remote_addr), Some(&original));
provider.connect(replacement_evidence.clone())?;
let mut disconnected = None;
for _ in 0..20 {
if let Some(event @ CultNetRudpServerEvent::Disconnected { .. }) =
hub.receive_event_once()?
{
disconnected = Some(event);
break;
}
}
let disconnected =
disconnected.ok_or_else(|| anyhow!("replacement did not disconnect old generation"))?;
let CultNetRudpServerEvent::Disconnected { session, .. } = disconnected else {
return Err(anyhow!("expected old generation Disconnected event"));
};
assert_eq!(session, original);
let connected = hub
.receive_event_once()?
.ok_or_else(|| anyhow!("replacement did not connect new generation"))?;
let CultNetRudpServerEvent::Connected {
session: replacement,
} = connected
else {
return Err(anyhow!("expected replacement Connected event"));
};
assert_ne!(replacement.session_generation, original.session_generation);
let original_decoded = decode_provider_connect_evidence(&original.connect_payload)?;
let replacement_decoded = decode_provider_connect_evidence(&replacement.connect_payload)?;
assert_eq!(
original_decoded.session_token,
replacement_decoded.session_token
);
assert_ne!(
original_decoded.client_session_id,
replacement_decoded.client_session_id
);
assert!(
hub.send(&original, "schema", vec![0x80])
.unwrap_err()
.to_string()
.contains("no longer active")
);
assert_eq!(hub.session(replacement.remote_addr), Some(&replacement));
Ok(())
}
#[test]
fn identical_connect_retransmit_reuses_pending_accept_after_loss() -> Result<()> {
let server_socket = socket()?;
let server_addr = server_socket.local_addr()?;
let mut hub = CultNetRudpServerHub::new(CultNetRudpServerHubOptions::new(
"odin",
server_socket,
CONNECTION_ID,
))?;
let client_socket = socket()?;
let mut client_session = CultNetRudpSession::new(CultNetRudpSessionOptions {
connection_id: CONNECTION_ID,
initial_sequence: 1,
resend_delay_ms: 250,
max_pending_reliable_packets: None,
});
let evidence = encode_provider_connect_evidence(&CultMeshProviderConnectEvidenceWire {
client_session_id: "provider-client-lost-accept".to_string(),
session_token: Some("shared-session-token".to_string()),
})?;
let connect_packet = client_session.create_connect(0, evidence)?;
let connect_wire = encode_rudp_packet(&connect_packet)?;
client_socket.send_to(&connect_wire, server_addr)?;
let CultNetRudpServerEvent::Connected { session } = hub
.receive_event_once()?
.ok_or_else(|| anyhow!("hub did not accept first Connect"))?
else {
return Err(anyhow!("hub did not emit Connected"));
};
let mut buffer = vec![0_u8; 65_535];
let (first_len, _) = client_socket.recv_from(&mut buffer)?;
let lost_accept = decode_rudp_packet(&buffer[..first_len])?;
assert_eq!(lost_accept.packet_type, CultNetRudpPacketType::Accept);
client_socket.send_to(&connect_wire, server_addr)?;
assert!(hub.receive_event_once()?.is_none());
let (resent_len, _) = client_socket.recv_from(&mut buffer)?;
let resent_accept = decode_rudp_packet(&buffer[..resent_len])?;
assert_eq!(resent_accept, lost_accept);
assert_eq!(hub.session(session.remote_addr), Some(&session));
client_session.receive(&resent_accept, 1)?;
assert!(client_session.connected());
Ok(())
}
#[test]
fn exact_reliable_acks_clear_more_than_one_ack_window_of_fragments() -> Result<()> {
let mut sender = CultNetRudpSession::new(CultNetRudpSessionOptions {
connection_id: CONNECTION_ID,
initial_sequence: 1,
resend_delay_ms: 250,
max_pending_reliable_packets: None,
});
let mut receiver = CultNetRudpSession::new(CultNetRudpSessionOptions {
connection_id: CONNECTION_ID,
initial_sequence: 1,
resend_delay_ms: 250,
max_pending_reliable_packets: None,
});
let connect_packet = sender.create_connect(0, Vec::new())?;
let accept = receiver.accept_connect(&connect_packet, 0, Vec::new())?;
sender.receive(&accept, 0)?;
receiver.receive(&sender.create_ack_for(accept.sequence), 0)?;
let packets = sender.send_many(
"schema",
vec![0x5a; 40],
CultNetRudpSendOptions {
reliable: true,
ordered: true,
sequenced: false,
now_ms: 1,
},
Some(1),
)?;
assert_eq!(packets.len(), 40);
let mut delivered = Vec::new();
for packet in &packets {
let result = receiver.receive(packet, 2)?;
delivered.extend(result.delivered);
sender.receive(&receiver.create_ack_for(packet.sequence), 3)?;
}
assert_eq!(delivered.len(), 1);
assert_eq!(delivered[0].payload, vec![0x5a; 40]);
assert!(sender.pending_reliable_sequences().is_empty());
Ok(())
}
#[test]
fn session_and_hub_reject_configured_memory_bounds() -> Result<()> {
let mut receiver = CultNetRudpSession::new(CultNetRudpSessionOptions {
connection_id: CONNECTION_ID,
initial_sequence: 1,
resend_delay_ms: 250,
max_pending_reliable_packets: None,
});
receiver.set_max_payload_bytes(Some(4));
receiver.set_max_pending_fragment_sets(1)?;
let mut sender = CultNetRudpSession::new(CultNetRudpSessionOptions {
connection_id: CONNECTION_ID,
initial_sequence: 1,
resend_delay_ms: 250,
max_pending_reliable_packets: None,
});
let connect_packet = sender.create_connect(0, Vec::new())?;
let accept = receiver.accept_connect(&connect_packet, 0, Vec::new())?;
sender.receive(&accept, 0)?;
let oversized = sender.send_many(
"schema",
vec![1, 2, 3, 4, 5],
CultNetRudpSendOptions {
reliable: true,
ordered: true,
sequenced: false,
now_ms: 1,
},
Some(2),
)?;
receiver.receive(&oversized[0], 1)?;
receiver.receive(&oversized[1], 1)?;
assert!(receiver.receive(&oversized[2], 1).is_err());
let fragment_options = CultNetRudpSendOptions {
reliable: true,
ordered: true,
sequenced: false,
now_ms: 2,
};
let first_set = sender.send_many(
"schema",
vec![1, 2, 3, 4],
fragment_options.clone(),
Some(2),
)?;
let second_set = sender.send_many("schema", vec![5, 6, 7, 8], fragment_options, Some(2))?;
receiver.receive(&first_set[0], 2)?;
assert!(receiver.receive(&second_set[0], 2).is_err());
let server_socket = socket()?;
let server_addr = server_socket.local_addr()?;
let mut options = CultNetRudpServerHubOptions::new("odin", server_socket, CONNECTION_ID);
options.max_peers = 1;
let mut hub = CultNetRudpServerHub::new(options)?;
let mut first = client(server_addr)?;
let mut second = client(server_addr)?;
connect(&mut hub, &mut first, b"first")?;
second.connect(b"second".to_vec())?;
for _ in 0..20 {
match hub.receive_event_once() {
Err(error) => {
assert!(error.to_string().contains("peer limit"));
return Ok(());
}
Ok(_) => continue,
}
}
Err(anyhow!("hub did not enforce peer limit"))
}
#[test]
fn replay_history_is_bounded_and_idle_hub_sessions_expire() -> Result<()> {
let mut sender = CultNetRudpSession::new(CultNetRudpSessionOptions {
connection_id: CONNECTION_ID,
initial_sequence: 1,
resend_delay_ms: 250,
max_pending_reliable_packets: None,
});
let mut receiver = CultNetRudpSession::new(CultNetRudpSessionOptions {
connection_id: CONNECTION_ID,
initial_sequence: 1,
resend_delay_ms: 250,
max_pending_reliable_packets: None,
});
let connect_packet = sender.create_connect(0, Vec::new())?;
let accept = receiver.accept_connect(&connect_packet, 0, Vec::new())?;
sender.receive(&accept, 0)?;
let mut oldest = None;
for sequence in 0..4_100 {
let packet = sender.send(
"realtime",
vec![(sequence % 251) as u8],
CultNetRudpSendOptions {
reliable: false,
ordered: false,
sequenced: false,
now_ms: sequence,
},
)?;
if oldest.is_none() {
oldest = Some(packet.clone());
}
assert_eq!(receiver.receive(&packet, sequence)?.delivered.len(), 1);
}
assert!(
receiver
.receive(&oldest.expect("oldest packet"), 4_101)?
.delivered
.is_empty()
);
let server_socket = socket()?;
let server_addr = server_socket.local_addr()?;
let mut hub = CultNetRudpServerHub::new(CultNetRudpServerHubOptions::new(
"odin",
server_socket,
CONNECTION_ID,
))?;
let mut provider = client(server_addr)?;
let context = connect(&mut hub, &mut provider, b"expiring-session")?;
std::thread::sleep(Duration::from_millis(2));
assert_eq!(hub.remove_timed_out_sessions(0), vec![context]);
assert!(hub.sessions().is_empty());
Ok(())
}