Publish Ghostlight state through CultMesh

This commit is contained in:
Meta Vens 2026-08-16 21:22:24 +02:00
commit a80a269f4b
57 changed files with 12783 additions and 20 deletions

241
Cargo.lock generated
View file

@ -2,6 +2,41 @@
# It is not intended for manual editing.
version = 4
[[package]]
name = "aead"
version = "0.5.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0"
dependencies = [
"crypto-common",
"generic-array",
]
[[package]]
name = "aes"
version = "0.8.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0"
dependencies = [
"cfg-if",
"cipher",
"cpufeatures 0.2.17",
]
[[package]]
name = "aes-gcm"
version = "0.10.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "831010a0f742e1209b3bcea8fab6a8e149051ba6099432c8cb2cc117dec3ead1"
dependencies = [
"aead",
"aes",
"cipher",
"ctr",
"ghash",
"subtle",
]
[[package]]
name = "aho-corasick"
version = "1.1.5"
@ -193,6 +228,16 @@ dependencies = [
"windows-link 0.2.1",
]
[[package]]
name = "cipher"
version = "0.4.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
dependencies = [
"crypto-common",
"inout",
]
[[package]]
name = "core-foundation-sys"
version = "0.8.7"
@ -224,9 +269,36 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
dependencies = [
"generic-array",
"rand_core 0.6.4",
"typenum",
]
[[package]]
name = "ctr"
version = "0.9.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0369ee1ad671834580515889b80f2ea915f23b8be8d0daa4bbaf2ac5c7590835"
dependencies = [
"cipher",
]
[[package]]
name = "cultcache-rs"
version = "0.1.0"
dependencies = [
"anyhow",
"chrono",
"cultcache-rs-derive 0.1.0",
"fs2",
"pretty_assertions",
"rmp-serde",
"serde",
"serde_bytes",
"serde_json",
"tempfile",
"uuid",
]
[[package]]
name = "cultcache-rs"
version = "0.1.0"
@ -234,7 +306,7 @@ source = "git+https://github.com/GameCult/cultcache-rs.git?rev=0ba87453115e3d44e
dependencies = [
"anyhow",
"chrono",
"cultcache-rs-derive",
"cultcache-rs-derive 0.1.0 (git+https://github.com/GameCult/cultcache-rs.git?rev=0ba87453115e3d44e8fcb7419866cd7dd70fb096)",
"fs2",
"redb",
"rmp-serde",
@ -245,6 +317,15 @@ dependencies = [
"windows-sys 0.59.0",
]
[[package]]
name = "cultcache-rs-derive"
version = "0.1.0"
dependencies = [
"proc-macro2",
"quote",
"syn 2.0.119",
]
[[package]]
name = "cultcache-rs-derive"
version = "0.1.0"
@ -255,6 +336,48 @@ dependencies = [
"syn 2.0.119",
]
[[package]]
name = "cultmesh-rs"
version = "0.1.0"
dependencies = [
"anyhow",
"cultcache-rs 0.1.0",
"cultnet-rs",
"pretty_assertions",
"rmp-serde",
"serde",
"tempfile",
]
[[package]]
name = "cultnet-rs"
version = "0.1.0"
dependencies = [
"aes-gcm",
"anyhow",
"base64",
"chrono",
"cultcache-rs 0.1.0",
"hmac",
"pretty_assertions",
"rand 0.9.5",
"rmp-serde",
"rmpv",
"serde",
"serde_bytes",
"serde_json",
"sha2",
"socket2 0.5.10",
"tempfile",
"uuid",
]
[[package]]
name = "diff"
version = "0.1.13"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "56254986775e3233ffa9c4d7d3faaf6d36a2c09d30b20687e9f88bc8bafc16c8"
[[package]]
name = "digest"
version = "0.10.7"
@ -263,6 +386,7 @@ checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
dependencies = [
"block-buffer",
"crypto-common",
"subtle",
]
[[package]]
@ -432,6 +556,16 @@ dependencies = [
"wasm-bindgen",
]
[[package]]
name = "ghash"
version = "0.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f0d8a4362ccb29cb0b265253fb0a2728f592895ee6854fd9bc13f2ffda266ff1"
dependencies = [
"opaque-debug",
"polyval",
]
[[package]]
name = "ghostlight-dungeon"
version = "0.1.0"
@ -440,7 +574,10 @@ dependencies = [
"async-trait",
"axum",
"chrono",
"cultcache-rs",
"cultcache-rs 0.1.0",
"cultcache-rs 0.1.0 (git+https://github.com/GameCult/cultcache-rs.git?rev=0ba87453115e3d44e8fcb7419866cd7dd70fb096)",
"cultmesh-rs",
"cultnet-rs",
"rand 0.9.5",
"reqwest",
"rmp-serde",
@ -459,6 +596,15 @@ dependencies = [
"zeroize",
]
[[package]]
name = "hmac"
version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6c49c37c09c17a53d937dfbb742eb3a961d65a994e6bcdcf37e7399d0cc8ab5e"
dependencies = [
"digest",
]
[[package]]
name = "http"
version = "1.5.0"
@ -564,7 +710,7 @@ dependencies = [
"libc",
"percent-encoding",
"pin-project-lite",
"socket2",
"socket2 0.6.5",
"tokio",
"tower-service",
"tracing",
@ -698,6 +844,15 @@ dependencies = [
"icu_properties",
]
[[package]]
name = "inout"
version = "0.1.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01"
dependencies = [
"generic-array",
]
[[package]]
name = "ipnet"
version = "2.12.1"
@ -838,6 +993,12 @@ version = "1.21.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
[[package]]
name = "opaque-debug"
version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
[[package]]
name = "parking_lot"
version = "0.12.5"
@ -873,6 +1034,18 @@ version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
[[package]]
name = "polyval"
version = "0.6.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9d1fe60d06143b2430aa532c94cfe9e29783047f06c0d7fd359a9a51b729fa25"
dependencies = [
"cfg-if",
"cpufeatures 0.2.17",
"opaque-debug",
"universal-hash",
]
[[package]]
name = "potential_utf"
version = "0.1.6"
@ -891,6 +1064,16 @@ dependencies = [
"zerocopy",
]
[[package]]
name = "pretty_assertions"
version = "1.4.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3ae130e2f271fbc2ac3a40fb1d07180839cdbbe443c7a27e1e3c13c5cac0116d"
dependencies = [
"diff",
"yansi",
]
[[package]]
name = "proc-macro2"
version = "1.0.107"
@ -913,7 +1096,7 @@ dependencies = [
"quinn-udp",
"rustc-hash",
"rustls",
"socket2",
"socket2 0.6.5",
"thiserror",
"tokio",
"tracing",
@ -951,7 +1134,7 @@ dependencies = [
"cfg_aliases",
"libc",
"once_cell",
"socket2",
"socket2 0.6.5",
"tracing",
"windows-sys 0.61.2",
]
@ -1008,6 +1191,15 @@ dependencies = [
"rand_core 0.9.5",
]
[[package]]
name = "rand_core"
version = "0.6.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
dependencies = [
"getrandom 0.2.17",
]
[[package]]
name = "rand_core"
version = "0.9.5"
@ -1161,6 +1353,17 @@ dependencies = [
"serde",
]
[[package]]
name = "rmpv"
version = "1.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7a4e1d4b9b938a26d2996af33229f0ca0956c652c1375067f0b45291c1df8417"
dependencies = [
"rmp",
"serde",
"serde_bytes",
]
[[package]]
name = "rustc-hash"
version = "2.1.3"
@ -1395,6 +1598,16 @@ version = "1.15.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
[[package]]
name = "socket2"
version = "0.5.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e22376abed350d73dd1cd119b57ffccad95b4e585a7cda43e286245ce23c0678"
dependencies = [
"libc",
"windows-sys 0.52.0",
]
[[package]]
name = "socket2"
version = "0.6.5"
@ -1538,7 +1751,7 @@ dependencies = [
"parking_lot",
"pin-project-lite",
"signal-hook-registry",
"socket2",
"socket2 0.6.5",
"tokio-macros",
"windows-sys 0.61.2",
]
@ -1719,6 +1932,16 @@ version = "1.0.24"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
[[package]]
name = "universal-hash"
version = "0.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea"
dependencies = [
"crypto-common",
"subtle",
]
[[package]]
name = "untrusted"
version = "0.9.0"
@ -2161,6 +2384,12 @@ version = "0.6.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
[[package]]
name = "yansi"
version = "1.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cfe53a6657fd280eaa890a3bc59152892ffa3e30101319d168b781ed6529b049"
[[package]]
name = "yoke"
version = "0.8.3"

View file

@ -1,5 +1,11 @@
[workspace]
members = ["crates/ghostlight-dungeon"]
members = [
"crates/ghostlight-dungeon",
"vendor/cultcache-rs",
"vendor/cultcache-rs/cultcache-rs-derive",
"vendor/cultnet-rs",
"vendor/cultmesh-rs",
]
resolver = "2"
[workspace.package]
@ -12,7 +18,10 @@ anyhow = "1"
async-trait = "0.1"
axum = { version = "0.8", features = ["macros"] }
chrono = { version = "0.4", features = ["serde"] }
cultcache-rs = { git = "https://github.com/GameCult/cultcache-rs.git", rev = "0ba87453115e3d44e8fcb7419866cd7dd70fb096" }
cultcache-legacy = { package = "cultcache-rs", git = "https://github.com/GameCult/cultcache-rs.git", rev = "0ba87453115e3d44e8fcb7419866cd7dd70fb096" }
cultcache-rs = { path = "vendor/cultcache-rs" }
cultnet-rs = { path = "vendor/cultnet-rs" }
cultmesh-rs = { path = "vendor/cultmesh-rs" }
rand = "0.9"
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls", "stream"] }
rmp-serde = "1.3"

View file

@ -9,7 +9,10 @@ anyhow.workspace = true
async-trait.workspace = true
axum.workspace = true
chrono.workspace = true
cultcache-legacy.workspace = true
cultcache-rs.workspace = true
cultnet-rs.workspace = true
cultmesh-rs.workspace = true
rand.workspace = true
reqwest.workspace = true
rmp-serde.workspace = true

View file

@ -796,7 +796,7 @@ fn assess(c: &Campaign, intent: ActionIntent) -> ActionAssessment {
fn commit(
store: &CampaignStore,
row: cultcache_rs::CultCacheEnvelope,
row: cultcache_legacy::CultCacheEnvelope,
mut campaign: Campaign,
kind: &str,
roll: Option<RollReceipt>,
@ -828,7 +828,7 @@ fn commit(
fn commit_with_records(
store: &CampaignStore,
row: cultcache_rs::CultCacheEnvelope,
row: cultcache_legacy::CultCacheEnvelope,
mut campaign: Campaign,
kind: &str,
evidence: Vec<VaultEvidenceReceipt>,

View file

@ -5,6 +5,7 @@ pub mod domain;
pub mod gestalt;
pub mod initiative;
pub mod kernel;
pub mod mesh;
pub mod model;
pub mod narrator;
pub mod persistence;

View file

@ -16,6 +16,7 @@ use ghostlight_dungeon::{
},
gestalt::GestaltPresencePlanner,
kernel::CommandResult,
mesh::MeshPublisher,
model::{DeepSeekPort, ModelPort, ModelStageRequest, run_validated_stage},
narrator::Narrator,
persistence::CampaignStore,
@ -51,6 +52,7 @@ struct AppState {
compile_previews: Arc<Mutex<BTreeMap<String, OwnedPreview<WorldCompilePreview>>>>,
expansion_previews: Arc<Mutex<BTreeMap<String, OwnedPreview<RegionExpansionPreview>>>>,
live_turns: Arc<AtomicUsize>,
mesh: MeshPublisher,
}
struct LiveTurnGuard(Arc<AtomicUsize>);
@ -85,7 +87,7 @@ struct AuthState {
struct AuthOwner {
store: CampaignStore,
row: cultcache_rs::CultCacheEnvelope,
row: cultcache_legacy::CultCacheEnvelope,
state: AuthState,
}
@ -181,6 +183,11 @@ async fn main() -> anyhow::Result<()> {
} else {
("missing-secret".into(), None, None, None)
};
let mesh_target = std::env::var("GHOSTLIGHT_ODIN_RUDP")
.ok()
.map(|value| value.parse())
.transpose()?;
let mesh = MeshPublisher::open(runtime_root.join("service/mesh.cc"), mesh_target)?;
let state = AppState {
registry,
runtime_root,
@ -196,7 +203,9 @@ async fn main() -> anyhow::Result<()> {
compile_previews: Arc::new(Mutex::new(BTreeMap::new())),
expansion_previews: Arc::new(Mutex::new(BTreeMap::new())),
live_turns: Arc::new(AtomicUsize::new(0)),
mesh,
};
refresh_mesh(&state).await?;
tokio::spawn(scheduler_loop(state.clone()));
let release_web_root = std::env::current_exe()?
.parent()
@ -239,10 +248,11 @@ async fn main() -> anyhow::Result<()> {
Ok(())
}
async fn health(State(state): State<AppState>) -> Json<serde_json::Value> {
Json(
serde_json::json!({"schema":"ghostlight.service_health.v1","status":"ok","campaigns":state.registry.list().await.len(),"deepseek":state.deepseek_status}),
)
async fn health(State(state): State<AppState>) -> Response {
match state.mesh.health() {
Ok(value) => Json(value).into_response(),
Err(error) => (StatusCode::SERVICE_UNAVAILABLE, error.to_string()).into_response(),
}
}
async fn invite(Path(token): Path<String>, State(state): State<AppState>) -> Response {
@ -483,7 +493,12 @@ async fn approve_preview(
{
Ok(runtime) => match select_campaign(&state, &session, campaign_id).await {
Ok(()) => match load_campaign(&runtime.store) {
Ok(campaign) => Json(CommandResult::Created { campaign }).into_response(),
Ok(campaign) => {
if let Err(error) = refresh_mesh(&state).await {
tracing::warn!(%error, "campaign approval CultMesh publication failed");
}
Json(CommandResult::Created { campaign }).into_response()
}
Err(error) => {
(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()).into_response()
}
@ -900,6 +915,9 @@ async fn command(
.await
.ok()
.flatten();
if let Err(error) = refresh_mesh(&state).await {
tracing::warn!(%error, "post-command CultMesh publication failed");
}
return Json(serde_json::json!({"primary":result,"presence":presence_result,"reaction_wave":reaction,"npc_initiative":initiative,"narration":narration})).into_response();
}
Err(error) => {
@ -930,6 +948,9 @@ async fn command(
.await
.ok()
.flatten();
if let Err(error) = refresh_mesh(&state).await {
tracing::warn!(%error, "post-command CultMesh publication failed");
}
return Json(
serde_json::json!({"primary":result,"presence":presence_result,"narration":narration}),
)
@ -946,6 +967,9 @@ async fn command(
.await
.ok()
.flatten();
if let Err(error) = refresh_mesh(&state).await {
tracing::warn!(%error, "post-command CultMesh publication failed");
}
Json(serde_json::json!({"result":result,"narration":narration})).into_response()
} else {
Json(result).into_response()
@ -1001,9 +1025,41 @@ async fn scheduler_loop(state: AppState) {
}
}
}
if let Err(error) = refresh_mesh(&state).await {
tracing::warn!(%error, "CultMesh projection refresh failed");
}
}
}
async fn refresh_mesh(state: &AppState) -> anyhow::Result<serde_json::Value> {
let mut snapshots = Vec::new();
for id in state.registry.list().await {
let runtime = state.registry.runtime(id).await?;
let campaign = load_campaign(&runtime.store)?;
let mut narrations = runtime
.store
.keys("narration_projection.v1")?
.into_iter()
.filter_map(|key| {
runtime
.store
.load::<NarrationProjection>("narration_projection.v1", &key)
.ok()
.flatten()
.map(|(_, value)| value)
})
.filter(|value| value.campaign_id == campaign.id)
.collect::<Vec<_>>();
narrations.sort_by_key(|value| value.source_revision);
snapshots.push((campaign, narrations));
}
let publisher = state.mesh.clone();
let deepseek = state.deepseek_status.clone();
let pressure = state.live_turns.load(Ordering::SeqCst);
tokio::task::spawn_blocking(move || publisher.publish_snapshot(&snapshots, &deepseek, pressure))
.await?
}
#[derive(Deserialize)]
struct CampaignBranchRequest {
name: String,
@ -1099,7 +1155,12 @@ async fn fork_campaign(
}
};
match select_campaign(&state, &session, campaign.id).await {
Ok(()) => Json(campaign).into_response(),
Ok(()) => {
if let Err(error) = refresh_mesh(&state).await {
tracing::warn!(%error, "campaign fork CultMesh publication failed");
}
Json(campaign).into_response()
}
Err(error) => {
(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()).into_response()
}
@ -1139,7 +1200,12 @@ async fn reset_campaign(
}
};
match select_campaign(&state, &session, campaign.id).await {
Ok(()) => Json(campaign).into_response(),
Ok(()) => {
if let Err(error) = refresh_mesh(&state).await {
tracing::warn!(%error, "campaign reset CultMesh publication failed");
}
Json(campaign).into_response()
}
Err(error) => {
(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()).into_response()
}
@ -1474,6 +1540,7 @@ mod tests {
compile_previews: Arc::new(Mutex::new(BTreeMap::new())),
expansion_previews: Arc::new(Mutex::new(BTreeMap::new())),
live_turns: Arc::new(AtomicUsize::new(0)),
mesh: MeshPublisher::open(dir.path().join("mesh.cc"), None).unwrap(),
};
let left_runtime = session_runtime(&state, "left").await.unwrap().unwrap();
let right_runtime = session_runtime(&state, "right").await.unwrap().unwrap();

View file

@ -0,0 +1,319 @@
use crate::{
domain::{
ActionAssessment, ActorState, ActorStateDelta, Campaign, CanonCandidate, Event,
GestaltMemberDelta, GestaltPersonaState, InstitutionState, Location, NarrationProjection,
NewsIssue, RollReceipt, VaultEvidenceReceipt, WorldActionProposal, WorldClock,
WorldCommitReceipt, WorldCompilePreview, WorldFact,
},
model::ModelStageReceipt,
surface::player_surface,
};
use anyhow::{Context, Result};
use chrono::Utc;
use cultcache_rs::DatabaseEntry;
use cultmesh_rs::{
CultMesh, CultMeshNode, CultMeshNodeOptions, CultMeshRudpDocumentPublishOptions,
};
use serde_json::{Value, json};
use std::{
net::SocketAddr,
path::Path,
sync::{Arc, Mutex},
};
pub const PROVIDER_ID: &str = "gamecult.ghostlight.dungeon";
pub const HEALTH_KEY: &str = "ghostlight:dungeon:health";
pub const ADVERTISEMENT_KEY: &str = "eve:provider:gamecult.ghostlight.dungeon";
#[derive(Clone, Debug, PartialEq, DatabaseEntry)]
#[cultcache(type = "gamecult.eve.surface", schema = "gamecult.eve.surface.v1")]
pub struct EveSurfaceRecord {
#[cultcache(key = 0)]
pub value: Value,
}
#[derive(Clone, Debug, PartialEq, DatabaseEntry)]
#[cultcache(
type = "gamecult.eve.surface_state",
schema = "gamecult.eve.surface_state.v1"
)]
pub struct EveSurfaceStateRecord {
#[cultcache(key = 0)]
pub provider_id: String,
#[cultcache(key = 1)]
pub title: String,
#[cultcache(key = 2)]
pub version: i64,
#[cultcache(key = 3)]
pub updated_at: String,
#[cultcache(key = 4)]
pub surface: Value,
}
#[derive(Clone, Debug, PartialEq, DatabaseEntry)]
#[cultcache(
type = "gamecult.eve.provider_advertisement",
schema = "gamecult.eve.provider_advertisement.v1"
)]
pub struct EveProviderAdvertisementRecord {
#[cultcache(key = 0)]
pub value: Value,
}
#[derive(Clone, Debug, PartialEq, DatabaseEntry)]
#[cultcache(
type = "ghostlight.service_health",
schema = "ghostlight.service_health.v1"
)]
pub struct ServiceHealthRecord {
#[cultcache(key = 0)]
pub value: Value,
}
#[derive(Clone, Debug, PartialEq, DatabaseEntry)]
#[cultcache(
type = "ghostlight.schema_catalog",
schema = "ghostlight.schema_catalog.v1"
)]
pub struct SchemaCatalogRecord {
#[cultcache(key = 0)]
pub value: Value,
}
cultmesh_rs::cultmesh_documents!(GhostlightDocuments {
EveSurfaceRecord => "gamecult.eve.surface.v1",
EveSurfaceStateRecord => "gamecult.eve.surface_state.v1",
EveProviderAdvertisementRecord => "gamecult.eve.provider_advertisement.v1",
ServiceHealthRecord => "ghostlight.service_health.v1",
SchemaCatalogRecord => "ghostlight.schema_catalog.v1",
});
#[derive(Clone)]
pub struct MeshPublisher {
node: Arc<Mutex<CultMeshNode>>,
rudp_target: Option<SocketAddr>,
}
impl MeshPublisher {
pub fn open(store_path: impl AsRef<Path>, rudp_target: Option<SocketAddr>) -> Result<Self> {
if let Some(parent) = store_path.as_ref().parent() {
std::fs::create_dir_all(parent)?;
}
let node = CultMesh::create_node(
store_path,
GhostlightDocuments,
CultMeshNodeOptions {
runtime_id: "ghostlight-dungeon-starfire".into(),
pull_on_start: true,
},
)?;
Ok(Self {
node: Arc::new(Mutex::new(node)),
rudp_target,
})
}
pub fn publish_snapshot(
&self,
campaigns: &[(Campaign, Vec<NarrationProjection>)],
deepseek_status: &str,
live_turn_pressure: usize,
) -> Result<Value> {
let updated_at = Utc::now().to_rfc3339();
let health = json!({
"schema":"ghostlight.service_health.v1",
"status":"ok",
"campaigns":campaigns.len(),
"deepseek":deepseek_status,
"scheduler":{"live_turn_pressure":live_turn_pressure},
"updatedAtUtc":updated_at,
"runtime":"ghostlight-dungeon-starfire",
"commit":option_env!("GHOSTLIGHT_BUILD_COMMIT").unwrap_or("development")
});
let schema_ids = vec![
"gamecult.eve.surface.v1",
"gamecult.eve.surface_state.v1",
"gamecult.eve.provider_advertisement.v1",
"ghostlight.service_health.v1",
"ghostlight.schema_catalog.v1",
"ghostlight.campaign.v1",
"ghostlight.player_action_assessment.v1",
"ghostlight.roll_receipt.v1",
"ghostlight.world_commit_receipt.v1",
"ghostlight.persona_stage_receipt.v1",
"ghostlight.actor_state_delta.v1",
"ghostlight.world_action_proposal.v1",
"ghostlight.strategic_tick.v1",
"ghostlight.news_issue.v1",
"ghostlight.canon_candidate.v1",
];
let catalog = json!({
"schema":"ghostlight.schema_catalog.v1",
"providerId":PROVIDER_ID,
"schemas":schema_catalog(),
"updatedAtUtc":updated_at
});
let surfaces = campaigns
.iter()
.map(|(campaign, _)| {
json!({
"schema":"gamecult.eve.surface.v1",
"surfaceId":format!("ghostlight.campaign.{}",campaign.id),
"key":format!("eve:surface:ghostlight.campaign.{}",campaign.id),
"transport":"cultmesh-record",
"status":"available",
"audience":"authenticated-player",
"mode":"interactive",
"surfaceKind":"interactive-world",
"interactionModel":"provider-command-receipts"
})
})
.collect::<Vec<_>>();
let advertisement = json!({
"schema":"gamecult.eve.provider_advertisement.v1",
"providerId":PROVIDER_ID,
"serviceId":"ghostlight-dungeon-starfire",
"verseId":"gamecult.private",
"rootVerse":"gamecult",
"canonicalService":"ghostlight-dungeon",
"locatedService":"starfire",
"cultMeshAddress":"cultmesh://gamecult.private/ghostlight/providers/dungeon",
"title":"GhostlightDungeon",
"kind":"narrative.simulation",
"updatedAtUtc":updated_at,
"freshness":{"state":"live","lastSeenAtUtc":updated_at,"maxAgeMs":360000},
"schemas":schema_ids,
"surfaces":surfaces,
"commands":[{"command":"ghostlight.world.commands","schema":"gamecult.eve.command.v1","transport":"cultmesh","summary":"Revision-bound world command intents; WorldKernel owns receipts."}]
});
let mut node = self
.node
.lock()
.map_err(|_| anyhow::anyhow!("mesh lock poisoned"))?;
self.put_and_publish(
&mut node,
HEALTH_KEY,
&ServiceHealthRecord {
value: health.clone(),
},
)?;
self.put_and_publish(
&mut node,
"ghostlight:schema-catalog",
&SchemaCatalogRecord { value: catalog },
)?;
self.put_and_publish(
&mut node,
ADVERTISEMENT_KEY,
&EveProviderAdvertisementRecord {
value: advertisement,
},
)?;
for (campaign, narrations) in campaigns {
let surface = player_surface(campaign, narrations);
let key = format!("eve:surface:ghostlight.campaign.{}", campaign.id);
self.put_and_publish(
&mut node,
&key,
&EveSurfaceRecord {
value: surface.clone(),
},
)?;
self.put_and_publish(
&mut node,
format!("eve:surface-state:ghostlight.campaign.{}", campaign.id),
&EveSurfaceStateRecord {
provider_id: PROVIDER_ID.into(),
title: campaign.name.clone(),
version: campaign.revision as i64,
updated_at: updated_at.clone(),
surface,
},
)?;
}
node.flush()?;
Ok(health)
}
pub fn health(&self) -> Result<Value> {
self.node
.lock()
.map_err(|_| anyhow::anyhow!("mesh lock poisoned"))?
.get_required::<ServiceHealthRecord>(HEALTH_KEY)
.map(|record| record.value)
}
fn put_and_publish<T>(
&self,
node: &mut CultMeshNode,
key: impl Into<String>,
value: &T,
) -> Result<()>
where
T: DatabaseEntry + serde::Serialize,
{
let key = key.into();
node.put(&key, value)?;
if let Some(target) = self.rudp_target {
let mut options =
CultMeshRudpDocumentPublishOptions::odin(target, "ghostlight-dungeon-starfire");
options.source_agent_id = Some(PROVIDER_ID.into());
options.source_role = Some("narrative-simulation".into());
options.tags = vec!["ghostlight".into(), "eve".into(), "private".into()];
node.publish_document_to_rudp_catalog(&key, value, options)
.with_context(|| format!("publish {key} to Odin RUDP catalog"))?;
}
Ok(())
}
}
fn schema_catalog() -> Value {
json!({
"ghostlight.vault_evidence_receipt.v1": schemars::schema_for!(VaultEvidenceReceipt),
"ghostlight.world_compile_preview.v1": schemars::schema_for!(WorldCompilePreview),
"ghostlight.campaign.v1": schemars::schema_for!(Campaign),
"ghostlight.world_fact.v1": schemars::schema_for!(WorldFact),
"ghostlight.location.v1": schemars::schema_for!(Location),
"ghostlight.actor_state.v1": schemars::schema_for!(ActorState),
"ghostlight.institution_state.v1": schemars::schema_for!(InstitutionState),
"ghostlight.world_clock.v1": schemars::schema_for!(WorldClock),
"ghostlight.event.v1": schemars::schema_for!(Event),
"ghostlight.player_action_assessment.v1": schemars::schema_for!(ActionAssessment),
"ghostlight.roll_receipt.v1": schemars::schema_for!(RollReceipt),
"ghostlight.world_commit_receipt.v1": schemars::schema_for!(WorldCommitReceipt),
"ghostlight.persona_stage_receipt.v1": schemars::schema_for!(ModelStageReceipt),
"ghostlight.actor_state_delta.v1": schemars::schema_for!(ActorStateDelta),
"ghostlight.world_action_proposal.v1": schemars::schema_for!(WorldActionProposal),
"ghostlight.news_issue.v1": schemars::schema_for!(NewsIssue),
"ghostlight.canon_candidate.v1": schemars::schema_for!(CanonCandidate),
"ghostlight.gestalt_persona_state.v1": schemars::schema_for!(GestaltPersonaState),
"ghostlight.gestalt_member_delta.v1": schemars::schema_for!(GestaltMemberDelta)
})
}
#[cfg(test)]
mod tests {
use super::*;
use tempfile::tempdir;
#[test]
fn health_is_read_from_the_same_typed_mesh_record_that_is_published() {
let temp = tempdir().unwrap();
let publisher = MeshPublisher::open(temp.path().join("mesh.cc"), None).unwrap();
let written = publisher.publish_snapshot(&[], "fixture-ready", 2).unwrap();
assert_eq!(publisher.health().unwrap(), written);
assert_eq!(written["scheduler"]["live_turn_pressure"], 2);
let catalog = publisher
.node
.lock()
.unwrap()
.get_required::<SchemaCatalogRecord>("ghostlight:schema-catalog")
.unwrap();
assert!(catalog.value["schemas"]["ghostlight.campaign.v1"]["$schema"].is_string());
drop(catalog);
drop(publisher);
let reopened = MeshPublisher::open(temp.path().join("mesh.cc"), None).unwrap();
assert_eq!(reopened.health().unwrap(), written);
}
}

View file

@ -1,5 +1,6 @@
use anyhow::{Result, anyhow};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
use std::time::Instant;
@ -15,7 +16,7 @@ pub struct ModelStageRequest {
pub source_receipt_ids: Vec<String>,
}
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema, PartialEq)]
pub struct ModelStageReceipt {
pub schema: String,
pub provider: String,

View file

@ -1,7 +1,7 @@
use crate::domain::{Campaign, VaultEvidenceReceipt};
use anyhow::{Context, Result, anyhow};
use chrono::Utc;
use cultcache_rs::{CacheBackingStore, CultCacheEnvelope, OwnedRedbMessagePackBackingStore};
use cultcache_legacy::{CacheBackingStore, CultCacheEnvelope, OwnedRedbMessagePackBackingStore};
use serde::{Serialize, de::DeserializeOwned};
use std::path::Path;

10
vendor/README.md vendored Normal file
View file

@ -0,0 +1,10 @@
# Vendored GameCult Rust substrate
`cultcache-rs`, `cultnet-rs`, and `cultmesh-rs` are copied together from Odin
commit `d34cb7e914e017e376d6f5fa98d464659baf1d73`. They are one compatible
protocol generation and must be updated as a set. Ghostlight vendors the set so
an immutable Starfire release can be rebuilt from its own exact Git commit.
The older CultCache revision named `cultcache-legacy` remains confined to the
campaign persistence adapter until campaign stores are migrated. It does not
own CultMesh documents or publication.

2
vendor/cultcache-rs/.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
/target
Cargo.lock

24
vendor/cultcache-rs/Cargo.toml vendored Normal file
View file

@ -0,0 +1,24 @@
[package]
name = "cultcache-rs"
version = "0.1.0"
edition = "2024"
publish = false
[lib]
name = "cultcache_rs"
path = "src/lib.rs"
[dependencies]
anyhow = "1"
chrono = { version = "0.4", features = ["serde"] }
cultcache-rs-derive = { path = "cultcache-rs-derive" }
fs2 = "0.4"
rmp-serde = "1.3"
serde = { version = "1", features = ["derive"] }
serde_bytes = "0.11"
serde_json = "1"
uuid = { version = "1", features = ["v4"] }
[dev-dependencies]
pretty_assertions = "1.4"
tempfile = "3"

332
vendor/cultcache-rs/README.md vendored Normal file
View file

@ -0,0 +1,332 @@
# CultCache Rust
`cultcache-rs` is the Rust port of the useful part of GameCult's CultCache:
a polymorphism-aware in-memory cache that remembers through pluggable backing
stores.
Consumer code should think in domain types:
```rust
let player = cache.get_required::<PlayerData>("player:meta")?;
cache.put("player:meta", &player)?;
```
The persistence layer should deal with envelopes, routing, MessagePack payload
bytes, and schema identity. Application code should not paw at loose JSON files
like a sad little bureaucrat with a clipboard.
## What It Is
CultCache is a domain cache with persistence adapters.
- `CultCache` is the query and mutation surface.
- Domain structs implement `DatabaseEntry`.
- Entries are stored behind a `type::key` identity, so multiple entry types
can share a logical key without colliding.
- Each payload is encoded directly from the known `DatabaseEntry` type into
MessagePack bytes.
- Backing stores are adapters, not the public data model.
- Writes persist to the resolved backing store before the in-memory cache is
updated.
- Type-specific backing stores beat generic backing stores.
- `SingleFileMessagePackBackingStore` is the first concrete store and guards
file access with a sidecar lock file.
This is not an ORM, not a database, and not distributed consensus in a novelty
hat. If multiple processes write the same backing file, use an external lock or
a coordinator.
## Current API
```rust
use cultcache_rs::{CultCache, DatabaseEntry, SingleFileMessagePackBackingStore};
#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
#[cultcache(type = "settings")]
struct Settings {
#[cultcache(key = 0)]
theme: String,
#[cultcache(key = 1, default)]
retries: u32,
}
let mut cache = CultCache::new();
cache.register_entry_type::<Settings>()?;
cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new("cache.cc"));
cache.pull_all_backing_stores()?;
cache.put("app", &Settings {
theme: "ash".to_string(),
retries: 3,
})?;
let settings = cache.get_required::<Settings>("app")?;
# Ok::<(), anyhow::Error>(())
```
For a closed set of entries, generate a registry instead of repeating yourself:
```rust
use cultcache_rs::cultcache_registry;
cultcache_registry!(GameCultEntries {
Settings,
PlayerData,
});
let mut cache = CultCache::new();
cache.register_registry(GameCultEntries)?;
```
The important part is that callers retrieve domain values directly:
```rust
let settings: Settings = cache.get_required("app")?;
let all_settings: Vec<Settings> = cache.get_all()?;
```
The cache is the ergonomic surface. The backing store is the memory prosthetic.
## How This Maps From Original CultCache
The original C# CultCache relies on runtime reflection:
- cacheable models inherit from `DatabaseEntry`
- the cache scans child classes at startup
- `Get<T>(id)` returns a `T`
- optional `INamedEntry` enables name lookup
- optional field/property indexes are registered by member name
- backing stores pull/push/delete `DatabaseEntry` values
Rust does not have C#-style assembly scanning or runtime subclass discovery.
The closest honest Rust translation is:
- domain structs implement a marker trait, `DatabaseEntry`
- the derive macro generates a positional array formatter from explicit integer
field slots
- the envelope carries the polymorphic type discriminator
- unknown persisted type ids fail closed instead of constructing arbitrary
runtime types
- a generated registry should eventually replace repetitive manual
registration
Manual `register_entry_type::<T>()` is still accepted, but entry identity no
longer needs a hand-written impl: `#[derive(DatabaseEntry)]` declares it beside
the domain type. `cultcache_registry!` provides the current generated resolver
surface for a closed entry set.
## Intended Rust Ergonomics
The target user-facing shape should be:
```rust
#[derive(Clone, DatabaseEntry)]
#[cultcache(type = "player")]
pub struct PlayerData {
#[cultcache(key = 0)]
pub id: String,
#[cultcache(key = 1)]
pub name: String,
#[cultcache(key = 2)]
pub faction: String,
}
let mut cache = CultCache::builder()
.with_generated_entries(game_entries())
.with_generic_store(SingleFileMessagePackBackingStore::new("cache.cc"))
.build()?;
cache.pull_all_backing_stores()?;
let player = cache.get_required::<PlayerData>("player:ari")?;
```
The current `cultcache_registry!` macro is deliberately simple. The remaining
ergonomic endpoint is automatic inventory or build-script generation so users
do not have to maintain the registry list by hand.
The registry is the Rust equivalent of C# reflection and MessagePack resolver
setup. It should know:
- entry type id
- generated MessagePack/serde formatter path
- Rust type name / schema name
- optional store domain route
- optional name key extractor
- optional secondary indexes
- optional global singleton marker
In other words: code generation should restore the original CultCache feeling
without pretending Rust has runtime reflection hiding under the floorboards.
## Current Surface
- `CultCache::new`
- `register_entry_type::<T>`
- `add_generic_backing_store`
- `add_backing_store`
- `pull_all_backing_stores`
- `get::<T>`
- `get_required::<T>`
- `get_envelope::<T>`
- `get_required_envelope::<T>`
- `get_all::<T>`
- `put::<T>`
- `put_envelope::<T>`
- `update::<T>`
- `delete::<T>`
- `snapshot`
- `SingleFileMessagePackBackingStore`
## Backing Store Routing
Generic store:
```rust
cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new("cache.cc"));
```
Type-specific store:
```rust
cache.add_backing_store(
SingleFileMessagePackBackingStore::new("players.cc"),
["player"],
);
```
When writing a `PlayerData`, the cache checks type-specific stores first. If none
match, it writes to the first generic store. Later matching stores are mirrors.
This mirrors the C# behavior:
- specific domain stores own their domain
- the first generic store is the primary generic write target
- later generic stores mirror writes
- this is not multi-master
## Persistence Semantics
`put` persists before mutating the in-memory cache. If persistence fails, the
cache does not pretend the write succeeded.
The envelope is MessagePack, and the payload inside each envelope is also raw
MessagePack bytes encoded from the registered concrete `DatabaseEntry` type.
That avoids the old bootstrap path where payloads were normalized through
`serde_json::Value`.
For bit-compatible neighbors, that also enables a real fast lane:
- `get_envelope::<T>()` exports the canonical persisted bytes for a typed entry
- `put_envelope::<T>()` ingests the same envelope into another cache instance
without re-encoding the payload first
It still decodes once for validation and typed reads. We are not pretending one
`Vec<u8>` became metaphysically zero-copy because we believed in it harder. But
the stupid decode/re-encode loop is gone.
The `DatabaseEntry` derive does not trust Rust source field order as the durable
schema. Every persisted member must declare a stable integer slot:
```rust
#[derive(Clone, DatabaseEntry)]
#[cultcache(type = "player")]
pub struct PlayerData {
#[cultcache(key = 0)]
pub id: String,
#[cultcache(key = 1)]
pub name: String,
#[cultcache(key = 2, default)]
pub level: u32,
}
```
The derive emits a tuple/array formatter. Gaps serialize as nil. Missing fields
marked `default` use `Default::default()` when older payloads are read. Deleted
field slots should stay reserved until an explicit store migration rewrites the
data.
The single-file MessagePack store rewrites an atomic snapshot. That is a sane
starting point for small typed state surfaces, settings, Epiphany agent memory,
heartbeat state, and other compact control-plane data. Large corpora should use
a sharded store or a real database instead of asking one file to become a
warehouse and then acting wounded when physics invoices us.
The single-file store uses a sidecar lock file for shared reads and exclusive
writes. That protects ordinary multi-process access to the same file. It is
still not a multi-master replication protocol, and it is not a substitute for a
coordinator when higher-level write ordering matters.
## Near-Term Ergonomic Improvements
1. **Derive macro**
- `#[derive(DatabaseEntry)]`
- `#[cultcache(type = "...")]`
- `#[cultcache(key = N)]` on every persisted field
- tuple/array formatter generation landed
- optional `#[cultcache(name)]`, `#[cultcache(index)]`, and
`#[cultcache(global)]` are still future work
2. **Generated registry**
- a `CultCacheRegistry` trait
- `cache.register_registry(GameCultEntries)`
- basic macro registry landed
- automatic inventory/build-script generation and store routes are future work
3. **Name and index lookups**
- `cache.get_by_name::<T>("Potion")`
- `cache.get_by_index::<T>("faction", "Lucent")`
- generated extractors instead of reflection strings
4. **Schema/version metadata**
- schema version in the envelope or payload metadata
- explicit migration hooks
- refusal on unknown persisted entry types unless a migration/resolver is
installed
5. **Projection helpers**
- JSON projection for review and git diffs
- vector stripping / large-field elision for agent memory surfaces
## Why Not Skip Registration Immediately?
Rust can only deserialize polymorphic data into concrete types if something
maps the persisted `type` discriminator to the Rust type. In C#, reflection and
MessagePack resolvers can discover a closed `DatabaseEntry` inheritance tree at
runtime and route it through known formatters. In Rust, that map has to come from
somewhere:
- explicit registration
- a generated registry
- a macro inventory crate
- a hand-written resolver
Explicit registration is the simplest honest implementation. Generated registry
is the ergonomic destination. Hand-written resolver tables are the punishment
we give ourselves if we get lazy.
## Security Model
CultCache should never parse arbitrary structured data into arbitrary runtime
types. It only accepts persisted envelopes whose `type` discriminator resolves
to a known `DatabaseEntry` type registered in the cache or generated registry.
That is the Rust version of the original trick:
- C# refuses to store objects outside the `DatabaseEntry` root type.
- Runtime-visible `DatabaseEntry` subclasses get dedicated formatters.
- Unknown or unregistered types are rejected.
- MessagePack payload bytes deserialize through known concrete formatters, not
an open-world type loader or generic structured-value bridge.
The derive/registry work should preserve that shape. Its job is to remove
manual registration ceremony, not to loosen the closed-world boundary.
## License
Private GameCult infrastructure for now. Public packaging can wait until the
API grows enough teeth to deserve strangers.

View file

@ -0,0 +1,13 @@
[package]
name = "cultcache-rs-derive"
version = "0.1.0"
edition = "2024"
publish = false
[lib]
proc-macro = true
[dependencies]
proc-macro2 = "1"
quote = "1"
syn = { version = "2", features = ["derive", "parsing"] }

View file

@ -0,0 +1,243 @@
use proc_macro::TokenStream;
use quote::format_ident;
use quote::quote;
use syn::Data;
use syn::DeriveInput;
use syn::Fields;
use syn::LitInt;
use syn::LitStr;
use syn::Type;
use syn::parse_macro_input;
#[proc_macro_derive(DatabaseEntry, attributes(cultcache))]
pub fn derive_database_entry(input: TokenStream) -> TokenStream {
let input = parse_macro_input!(input as DeriveInput);
let ident = input.ident.clone();
let mut entry_type: Option<LitStr> = None;
let mut schema_name: Option<LitStr> = None;
for attribute in input
.attrs
.iter()
.filter(|attr| attr.path().is_ident("cultcache"))
{
let parse_result = attribute.parse_nested_meta(|meta| {
if meta.path.is_ident("type") {
entry_type = Some(meta.value()?.parse()?);
Ok(())
} else if meta.path.is_ident("schema") {
schema_name = Some(meta.value()?.parse()?);
Ok(())
} else {
Err(meta.error("unsupported cultcache attribute"))
}
});
if let Err(error) = parse_result {
return error.to_compile_error().into();
}
}
let Some(entry_type) = entry_type else {
return syn::Error::new_spanned(
ident,
"DatabaseEntry derive requires #[cultcache(type = \"...\")]",
)
.to_compile_error()
.into();
};
let schema_name = schema_name.unwrap_or_else(|| LitStr::new(&ident.to_string(), ident.span()));
let fields = match input.data {
Data::Struct(data) => match data.fields {
Fields::Named(fields) => fields.named,
_ => {
return syn::Error::new_spanned(
ident,
"DatabaseEntry derive requires a named struct",
)
.to_compile_error()
.into();
}
},
_ => {
return syn::Error::new_spanned(ident, "DatabaseEntry derive requires a struct")
.to_compile_error()
.into();
}
};
let mut slots: Vec<CultCacheSlot> = Vec::new();
for field in fields {
let Some(field_ident) = field.ident else {
return syn::Error::new_spanned(field.ty, "DatabaseEntry derive requires named fields")
.to_compile_error()
.into();
};
let mut key: Option<usize> = None;
let mut default = false;
for attribute in field
.attrs
.iter()
.filter(|attr| attr.path().is_ident("cultcache"))
{
let parse_result = attribute.parse_nested_meta(|meta| {
if meta.path.is_ident("key") {
let value: LitInt = meta.value()?.parse()?;
key = Some(value.base10_parse()?);
Ok(())
} else if meta.path.is_ident("default") {
default = true;
Ok(())
} else {
Err(meta.error("unsupported field cultcache attribute"))
}
});
if let Err(error) = parse_result {
return error.to_compile_error().into();
}
}
let Some(key) = key else {
return syn::Error::new_spanned(
field_ident,
"DatabaseEntry fields require #[cultcache(key = N)]",
)
.to_compile_error()
.into();
};
if slots.iter().any(|slot| slot.key == key) {
return syn::Error::new_spanned(
field_ident,
format!("duplicate DatabaseEntry slot {key}"),
)
.to_compile_error()
.into();
}
slots.push(CultCacheSlot {
key,
ident: field_ident,
ty: field.ty,
default,
});
}
slots.sort_by_key(|slot| slot.key);
let max_slot = slots.iter().map(|slot| slot.key).max().unwrap_or(0);
let serialize_elements = (0..=max_slot).map(|slot| {
if let Some(field) = slots.iter().find(|field| field.key == slot) {
let field_ident = &field.ident;
quote! {
tuple.serialize_element(&self.#field_ident)?;
}
} else {
quote! {
tuple.serialize_element(&())?;
}
}
});
let option_declarations = slots.iter().map(|field| {
let variable = format_ident!("slot_{}", field.key);
let ty = &field.ty;
quote! {
let mut #variable: ::std::option::Option<#ty> = ::std::option::Option::None;
}
});
let deserialize_match_arms = (0..=max_slot).map(|slot| {
if let Some(field) = slots.iter().find(|field| field.key == slot) {
let variable = format_ident!("slot_{}", field.key);
let ty = &field.ty;
quote! {
#slot => {
#variable = seq.next_element::<#ty>()?;
}
}
} else {
quote! {
#slot => {
let _ = seq.next_element::<::serde::de::IgnoredAny>()?;
}
}
}
});
let build_fields = slots.iter().map(|field| {
let field_ident = &field.ident;
let variable = format_ident!("slot_{}", field.key);
if field.default {
quote! {
#field_ident: #variable.unwrap_or_default()
}
} else {
let field_name = field_ident.to_string();
quote! {
#field_ident: #variable.ok_or_else(|| ::serde::de::Error::missing_field(#field_name))?
}
}
});
quote! {
impl ::cultcache_rs::DatabaseEntry for #ident {
const TYPE: &'static str = #entry_type;
const SCHEMA_NAME: &'static str = #schema_name;
}
impl ::serde::Serialize for #ident {
fn serialize<S>(&self, serializer: S) -> ::std::result::Result<S::Ok, S::Error>
where
S: ::serde::Serializer,
{
use ::serde::ser::SerializeTuple;
let mut tuple = serializer.serialize_tuple(#max_slot + 1)?;
#(#serialize_elements)*
tuple.end()
}
}
impl<'de> ::serde::Deserialize<'de> for #ident {
fn deserialize<D>(deserializer: D) -> ::std::result::Result<Self, D::Error>
where
D: ::serde::Deserializer<'de>,
{
struct CultCacheVisitor;
impl<'de> ::serde::de::Visitor<'de> for CultCacheVisitor {
type Value = #ident;
fn expecting(&self, formatter: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
formatter.write_str(concat!("a CultCache array for ", stringify!(#ident)))
}
fn visit_seq<A>(self, mut seq: A) -> ::std::result::Result<Self::Value, A::Error>
where
A: ::serde::de::SeqAccess<'de>,
{
#(#option_declarations)*
let mut index = 0usize;
while index <= #max_slot {
match index {
#(#deserialize_match_arms)*
_ => unreachable!(),
}
index += 1;
}
while let ::std::option::Option::Some(_) = seq.next_element::<::serde::de::IgnoredAny>()? {}
Ok(#ident {
#(#build_fields),*
})
}
}
deserializer.deserialize_tuple(#max_slot + 1, CultCacheVisitor)
}
}
}
.into()
}
struct CultCacheSlot {
key: usize,
ident: syn::Ident,
ty: Type,
default: bool,
}

View file

@ -0,0 +1,121 @@
use anyhow::Result;
use anyhow::anyhow;
use cultcache_rs::CultCache;
use cultcache_rs::DatabaseEntry;
use cultcache_rs::SingleFileMessagePackBackingStore;
use serde_json::json;
use std::collections::BTreeMap;
const INTEROP_TYPE: &str = "cultcache.interop-note";
const INTEROP_SCHEMA_VERSION: &str = "cultcache.interop_note.v1";
#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
#[cultcache(type = "cultcache.interop-note", schema = "CultCacheInteropNote")]
struct CultCacheInteropNote {
#[cultcache(key = 0)]
schema_version: String,
#[cultcache(key = 1)]
document_id: String,
#[cultcache(key = 2)]
author_runtime_id: String,
#[cultcache(key = 3)]
title: String,
#[cultcache(key = 4)]
body: String,
#[cultcache(key = 5, default)]
tags: Vec<String>,
}
fn main() -> Result<()> {
let mut args = std::env::args().skip(1);
let mode = args
.next()
.ok_or_else(|| anyhow!("expected mode: write | read"))?;
let options = parse_args(args.collect());
let file = require_arg(&options, "file")?;
match mode.as_str() {
"write" => write_note(file, require_arg(&options, "runtime-id")?)?,
"read" => read_note(file)?,
_ => return Err(anyhow!("unknown mode {mode}")),
}
Ok(())
}
fn write_note(file: &str, runtime_id: &str) -> Result<()> {
let mut cache = build_cache(file)?;
cache.pull_all_backing_stores()?;
let note = CultCacheInteropNote {
schema_version: INTEROP_SCHEMA_VERSION.to_string(),
document_id: format!("note:{runtime_id}"),
author_runtime_id: runtime_id.to_string(),
title: format!("{runtime_id} wrote a CultCache note"),
body: "The v1 store format is the contract.".to_string(),
tags: vec![
runtime_id.to_string(),
"rust".to_string(),
"interop".to_string(),
],
};
cache.put(&note.document_id, &note)?;
print_note(&note)
}
fn read_note(file: &str) -> Result<()> {
let mut cache = build_cache(file)?;
cache.pull_all_backing_stores()?;
let notes = cache.get_all::<CultCacheInteropNote>()?;
let note = notes
.first()
.ok_or_else(|| anyhow!("no {INTEROP_TYPE} records found"))?;
print_note(note)
}
fn build_cache(file: &str) -> Result<CultCache> {
let mut cache = CultCache::new();
cache.register_entry_type::<CultCacheInteropNote>()?;
cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(file));
Ok(cache)
}
fn print_note(note: &CultCacheInteropNote) -> Result<()> {
println!(
"{}",
serde_json::to_string(&json!({
"schemaVersion": note.schema_version,
"documentId": note.document_id,
"authorRuntimeId": note.author_runtime_id,
"title": note.title,
"body": note.body,
"tags": note.tags,
}))?
);
Ok(())
}
fn parse_args(args: Vec<String>) -> BTreeMap<String, String> {
let mut parsed = BTreeMap::new();
let mut index = 0;
while index < args.len() {
let token = &args[index];
if !token.starts_with("--") {
index += 1;
continue;
}
let name = token.trim_start_matches("--").to_string();
let value = args
.get(index + 1)
.cloned()
.unwrap_or_else(|| panic!("missing value for --{name}"));
parsed.insert(name, value);
index += 2;
}
parsed
}
fn require_arg<'a>(options: &'a BTreeMap<String, String>, name: &str) -> Result<&'a str> {
options
.get(name)
.map(String::as_str)
.ok_or_else(|| anyhow!("missing required argument --{name}"))
}

919
vendor/cultcache-rs/src/lib.rs vendored Normal file
View file

@ -0,0 +1,919 @@
use anyhow::Context;
use anyhow::Result;
use anyhow::anyhow;
use serde::Serialize;
use serde::de::DeserializeOwned;
use std::collections::BTreeMap;
use std::collections::BTreeSet;
use std::fs;
use std::fs::File;
use std::fs::OpenOptions;
use std::path::Path;
use std::path::PathBuf;
extern crate self as cultcache_rs;
pub use cultcache_rs_derive::DatabaseEntry;
pub trait DatabaseEntry: Serialize + DeserializeOwned + Clone + Send + 'static {
const TYPE: &'static str;
const SCHEMA_NAME: &'static str = "DatabaseEntry";
}
pub trait CultCacheRegistry {
fn register_entries(&self, cache: &mut CultCache) -> Result<()>;
}
#[macro_export]
macro_rules! cultcache_registry {
($name:ident { $($entry:ty),* $(,)? }) => {
#[derive(Clone, Copy, Debug, Default)]
pub struct $name;
impl $crate::CultCacheRegistry for $name {
fn register_entries(&self, cache: &mut $crate::CultCache) -> ::anyhow::Result<()> {
$(
cache.register_entry_type::<$entry>()?;
)*
Ok(())
}
}
};
}
#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CultCacheEnvelope {
pub key: String,
#[serde(rename = "type")]
pub r#type: String,
#[serde(with = "serde_bytes")]
pub payload: Vec<u8>,
pub stored_at: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub schema_id: Option<String>,
}
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
struct PersistedStoreSnapshot(
String,
Vec<PersistedSchemaCatalogEntry>,
Vec<PersistedRecord>,
);
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
struct PersistedSchemaCatalogEntry(
String,
String,
String,
String,
String,
Vec<String>,
Vec<PersistedSchemaCatalogMember>,
);
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
struct PersistedSchemaCatalogMember(
u32,
String,
String,
bool,
bool,
Option<String>,
bool,
Option<String>,
);
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
struct PersistedRecord(
String,
String,
String,
#[serde(with = "serde_bytes")] Vec<u8>,
);
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct PushAllOptions {
pub soft: bool,
}
pub trait CacheBackingStore: Send {
fn pull_all(&self) -> Result<Vec<CultCacheEnvelope>>;
fn push(&mut self, entry: &CultCacheEnvelope) -> Result<()>;
fn delete(&mut self, entry: &CultCacheEnvelope) -> Result<()>;
fn push_all(&mut self, entries: &[CultCacheEnvelope], _options: PushAllOptions) -> Result<()> {
let existing = self.pull_all()?;
for entry in existing {
self.delete(&entry)?;
}
for entry in entries {
self.push(entry)?;
}
Ok(())
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SingleFileMessagePackBackingStore {
path: PathBuf,
}
impl SingleFileMessagePackBackingStore {
pub fn new(path: impl Into<PathBuf>) -> Self {
Self { path: path.into() }
}
pub fn path(&self) -> &Path {
&self.path
}
fn read_all_unlocked(&self) -> Result<Vec<CultCacheEnvelope>> {
if !self.path.exists() {
return Ok(Vec::new());
}
let bytes = fs::read(&self.path)
.with_context(|| format!("failed to read {}", self.path.display()))?;
if bytes.is_empty() {
return Ok(Vec::new());
}
decode_store_snapshot(&bytes)
.or_else(|_| rmp_serde::from_slice(&bytes))
.with_context(|| format!("failed to decode MessagePack {}", self.path.display()))
}
fn write_all_unlocked(&self, entries: &[CultCacheEnvelope]) -> Result<()> {
if let Some(parent) = self.path.parent() {
fs::create_dir_all(parent)
.with_context(|| format!("failed to create {}", parent.display()))?;
}
let bytes = rmp_serde::to_vec(&encode_store_snapshot(entries))
.context("failed to encode MessagePack")?;
let tmp_path = temporary_path_for(&self.path);
fs::write(&tmp_path, bytes)
.with_context(|| format!("failed to write {}", tmp_path.display()))?;
if self.path.exists() {
fs::remove_file(&self.path)
.with_context(|| format!("failed to replace {}", self.path.display()))?;
}
fs::rename(&tmp_path, &self.path).with_context(|| {
format!(
"failed to move {} to {}",
tmp_path.display(),
self.path.display()
)
})?;
Ok(())
}
fn with_shared_lock<T>(&self, action: impl FnOnce() -> Result<T>) -> Result<T> {
let lock = self.open_lock_file()?;
fs2::FileExt::lock_shared(&lock)
.with_context(|| format!("failed to lock {}", self.lock_path().display()))?;
let result = action();
fs2::FileExt::unlock(&lock)
.with_context(|| format!("failed to unlock {}", self.lock_path().display()))?;
result
}
fn with_exclusive_lock<T>(&self, action: impl FnOnce() -> Result<T>) -> Result<T> {
let lock = self.open_lock_file()?;
fs2::FileExt::lock_exclusive(&lock)
.with_context(|| format!("failed to lock {}", self.lock_path().display()))?;
let result = action();
fs2::FileExt::unlock(&lock)
.with_context(|| format!("failed to unlock {}", self.lock_path().display()))?;
result
}
fn open_lock_file(&self) -> Result<File> {
let lock_path = self.lock_path();
if let Some(parent) = lock_path.parent() {
fs::create_dir_all(parent)
.with_context(|| format!("failed to create {}", parent.display()))?;
}
OpenOptions::new()
.create(true)
.read(true)
.truncate(false)
.write(true)
.open(&lock_path)
.with_context(|| format!("failed to open {}", lock_path.display()))
}
fn lock_path(&self) -> PathBuf {
let mut lock_name = self
.path
.file_name()
.map(|value| value.to_os_string())
.unwrap_or_else(|| "cultcache.cc".into());
lock_name.push(".lock");
self.path.with_file_name(lock_name)
}
}
impl CacheBackingStore for SingleFileMessagePackBackingStore {
fn pull_all(&self) -> Result<Vec<CultCacheEnvelope>> {
self.with_shared_lock(|| self.read_all_unlocked())
}
fn push(&mut self, entry: &CultCacheEnvelope) -> Result<()> {
self.with_exclusive_lock(|| {
let mut entries = self.read_all_unlocked()?;
entries.retain(|candidate| entry_id(candidate) != entry_id(entry));
entries.push(entry.clone());
entries.sort_by_key(entry_id);
self.write_all_unlocked(&entries)
})
}
fn delete(&mut self, entry: &CultCacheEnvelope) -> Result<()> {
self.with_exclusive_lock(|| {
let mut entries = self.read_all_unlocked()?;
entries.retain(|candidate| entry_id(candidate) != entry_id(entry));
self.write_all_unlocked(&entries)
})
}
fn push_all(&mut self, entries: &[CultCacheEnvelope], _options: PushAllOptions) -> Result<()> {
self.with_exclusive_lock(|| {
let mut entries = entries.to_vec();
entries.sort_by_key(entry_id);
self.write_all_unlocked(&entries)
})
}
}
struct CultCacheStoreRegistration {
store: Box<dyn CacheBackingStore>,
types: BTreeSet<String>,
}
pub struct CultCache {
definitions: BTreeMap<String, &'static str>,
entries: BTreeMap<String, CultCacheEnvelope>,
stores: Vec<CultCacheStoreRegistration>,
}
impl CultCache {
pub fn new() -> Self {
Self {
definitions: BTreeMap::new(),
entries: BTreeMap::new(),
stores: Vec::new(),
}
}
pub fn register_entry_type<T: DatabaseEntry>(&mut self) -> Result<()> {
if T::TYPE.trim().is_empty() {
return Err(anyhow!(
"CultCache entry types must declare a non-empty type"
));
}
if let Some(existing_schema) = self.definitions.get(T::TYPE)
&& *existing_schema != T::SCHEMA_NAME
{
return Err(anyhow!(
"CultCache already has a different definition registered for type {:?}",
T::TYPE
));
}
self.definitions.insert(T::TYPE.to_string(), T::SCHEMA_NAME);
Ok(())
}
pub fn register_document_type<T: DatabaseEntry>(&mut self) -> Result<()> {
self.register_entry_type::<T>()
}
pub fn register_registry<R: CultCacheRegistry>(&mut self, registry: R) -> Result<&mut Self> {
registry.register_entries(self)?;
Ok(self)
}
pub fn add_backing_store(
&mut self,
store: impl CacheBackingStore + 'static,
types: impl IntoIterator<Item = impl Into<String>>,
) {
self.stores.push(CultCacheStoreRegistration {
store: Box::new(store),
types: types.into_iter().map(Into::into).collect(),
});
}
pub fn add_generic_backing_store(&mut self, store: impl CacheBackingStore + 'static) {
self.add_backing_store(store, Vec::<String>::new());
}
pub fn pull_all_backing_stores(&mut self) -> Result<()> {
self.entries.clear();
let known_types: BTreeSet<String> = self.definitions.keys().cloned().collect();
for registration in &mut self.stores {
for entry in registration.store.pull_all()? {
if !known_types.contains(&entry.r#type) {
return Err(anyhow!(
"No schema is registered for persisted entry type {:?}",
entry.r#type
));
}
self.entries.insert(entry_id(&entry), entry);
}
}
Ok(())
}
pub fn get<T: DatabaseEntry>(&self, key: &str) -> Result<Option<T>> {
self.require_entry_type::<T>()?;
let Some(entry) = self.entries.get(&entry_id_parts(T::TYPE, key)) else {
return Ok(None);
};
let payload = rmp_serde::from_slice(&entry.payload).with_context(|| {
format!(
"failed to decode CultCache entry {:?} at key {:?} as {}",
T::TYPE,
key,
T::SCHEMA_NAME
)
})?;
Ok(Some(payload))
}
pub fn get_required<T: DatabaseEntry>(&self, key: &str) -> Result<T> {
self.get::<T>(key)?
.ok_or_else(|| anyhow!("CultCache has no {:?} entry at key {:?}", T::TYPE, key))
}
pub fn get_envelope<T: DatabaseEntry>(&self, key: &str) -> Result<Option<CultCacheEnvelope>> {
self.require_entry_type::<T>()?;
Ok(self.entries.get(&entry_id_parts(T::TYPE, key)).cloned())
}
pub fn get_required_envelope<T: DatabaseEntry>(&self, key: &str) -> Result<CultCacheEnvelope> {
self.get_envelope::<T>(key)?
.ok_or_else(|| anyhow!("CultCache has no {:?} envelope at key {:?}", T::TYPE, key))
}
pub fn get_all<T: DatabaseEntry>(&self) -> Result<Vec<T>> {
self.require_entry_type::<T>()?;
let mut values = Vec::new();
for entry in self.entries.values() {
if entry.r#type != T::TYPE {
continue;
}
values.push(rmp_serde::from_slice(&entry.payload).with_context(|| {
format!(
"failed to decode CultCache entry {:?} at key {:?} as {}",
T::TYPE,
entry.key,
T::SCHEMA_NAME
)
})?);
}
Ok(values)
}
pub fn put<T: DatabaseEntry>(&mut self, key: impl Into<String>, value: &T) -> Result<T> {
self.require_entry_type::<T>()?;
let key = key.into();
let payload = rmp_serde::to_vec(value).with_context(|| {
format!(
"failed to encode CultCache entry {:?} at key {:?} as {}",
T::TYPE,
key,
T::SCHEMA_NAME
)
})?;
let parsed: T = rmp_serde::from_slice(&payload).with_context(|| {
format!(
"failed to validate CultCache entry {:?} at key {:?} as {}",
T::TYPE,
key,
T::SCHEMA_NAME
)
})?;
let entry = CultCacheEnvelope {
key: key.clone(),
r#type: T::TYPE.to_string(),
payload,
stored_at: now_utc_second(),
schema_id: Some(T::TYPE.to_string()),
};
let route = self.resolve_route_indices(T::TYPE);
let Some(primary_index) = route.first().copied() else {
return Err(anyhow!(
"No backing store is registered for entry type {:?}",
T::TYPE
));
};
self.stores[primary_index].store.push(&entry)?;
for mirror_index in route.iter().skip(1).copied() {
self.stores[mirror_index].store.push(&entry)?;
}
self.entries.insert(entry_id(&entry), entry);
Ok(parsed)
}
pub fn put_envelope<T: DatabaseEntry>(&mut self, entry: CultCacheEnvelope) -> Result<T> {
self.require_entry_type::<T>()?;
if entry.r#type != T::TYPE {
return Err(anyhow!(
"CultCache envelope type {:?} does not match registered Rust type {:?}",
entry.r#type,
T::TYPE
));
}
if entry.key.trim().is_empty() {
return Err(anyhow!(
"CultCache envelope keys for type {:?} must be non-empty",
T::TYPE
));
}
if entry.stored_at.trim().is_empty() {
return Err(anyhow!(
"CultCache envelope stored_at for type {:?} must be non-empty",
T::TYPE
));
}
let parsed: T = rmp_serde::from_slice(&entry.payload).with_context(|| {
format!(
"failed to validate CultCache envelope {:?} at key {:?} as {}",
T::TYPE,
entry.key,
T::SCHEMA_NAME
)
})?;
let route = self.resolve_route_indices(T::TYPE);
let Some(primary_index) = route.first().copied() else {
return Err(anyhow!(
"No backing store is registered for entry type {:?}",
T::TYPE
));
};
self.stores[primary_index].store.push(&entry)?;
for mirror_index in route.iter().skip(1).copied() {
self.stores[mirror_index].store.push(&entry)?;
}
self.entries.insert(entry_id(&entry), entry);
Ok(parsed)
}
pub fn put_raw_envelope(&mut self, entry: CultCacheEnvelope) -> Result<()> {
if !self.definitions.contains_key(&entry.r#type) {
return Err(anyhow!(
"No entry type registered for CultCache envelope type {:?}",
entry.r#type
));
}
if entry.key.trim().is_empty() {
return Err(anyhow!(
"CultCache envelope keys for type {:?} must be non-empty",
entry.r#type
));
}
if entry.stored_at.trim().is_empty() {
return Err(anyhow!(
"CultCache envelope stored_at for type {:?} must be non-empty",
entry.r#type
));
}
let route = self.resolve_route_indices(&entry.r#type);
let Some(primary_index) = route.first().copied() else {
return Err(anyhow!(
"No backing store is registered for entry type {:?}",
entry.r#type
));
};
self.stores[primary_index].store.push(&entry)?;
for mirror_index in route.iter().skip(1).copied() {
self.stores[mirror_index].store.push(&entry)?;
}
self.entries.insert(entry_id(&entry), entry);
Ok(())
}
pub fn update<T, F>(&mut self, key: &str, updater: F) -> Result<T>
where
T: DatabaseEntry,
F: FnOnce(Option<T>) -> T,
{
let current = self.get::<T>(key)?;
self.put::<T>(key.to_string(), &updater(current))
}
pub fn delete<T: DatabaseEntry>(&mut self, key: &str) -> Result<bool> {
self.require_entry_type::<T>()?;
let id = entry_id_parts(T::TYPE, key);
let Some(entry) = self.entries.get(&id).cloned() else {
return Ok(false);
};
let route = self.resolve_route_indices(T::TYPE);
let Some(primary_index) = route.first().copied() else {
return Err(anyhow!(
"No backing store is registered for entry type {:?}",
T::TYPE
));
};
self.stores[primary_index].store.delete(&entry)?;
for mirror_index in route.iter().skip(1).copied() {
self.stores[mirror_index].store.delete(&entry)?;
}
self.entries.remove(&id);
Ok(true)
}
pub fn snapshot(&self) -> Vec<CultCacheEnvelope> {
self.entries.values().cloned().collect()
}
fn require_entry_type<T: DatabaseEntry>(&self) -> Result<()> {
match self.definitions.get(T::TYPE) {
Some(schema_name) if *schema_name == T::SCHEMA_NAME => Ok(()),
_ => Err(anyhow!(
"CultCache entry type {:?} is not registered on this cache instance",
T::TYPE
)),
}
}
fn resolve_route_indices(&self, type_id: &str) -> Vec<usize> {
let type_specific: Vec<usize> = self
.stores
.iter()
.enumerate()
.filter_map(|(index, registration)| {
registration.types.contains(type_id).then_some(index)
})
.collect();
if !type_specific.is_empty() {
return type_specific;
}
self.stores
.iter()
.enumerate()
.filter_map(|(index, registration)| registration.types.is_empty().then_some(index))
.collect()
}
}
impl Default for CultCache {
fn default() -> Self {
Self::new()
}
}
fn entry_id(entry: &CultCacheEnvelope) -> String {
entry_id_parts(&entry.r#type, &entry.key)
}
fn entry_id_parts(r#type: &str, key: &str) -> String {
format!("{type}::{key}", type = r#type)
}
fn now_utc_second() -> String {
chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
}
fn encode_store_snapshot(entries: &[CultCacheEnvelope]) -> PersistedStoreSnapshot {
let mut schema_names = BTreeMap::<String, String>::new();
for entry in entries {
schema_names.insert(
entry
.schema_id
.clone()
.unwrap_or_else(|| entry.r#type.clone()),
entry.r#type.clone(),
);
}
let catalog = schema_names
.into_iter()
.map(|(schema_id, document_type)| {
PersistedSchemaCatalogEntry(
schema_id.clone(),
document_type,
format!("{schema_id}.v1"),
schema_id.clone(),
format!(
"{{\"schemaName\":\"{}\",\"schemaVersion\":\"{}.v1\",\"members\":[]}}",
escape_json_string(&schema_id),
escape_json_string(&schema_id)
),
vec![schema_id],
Vec::new(),
)
})
.collect();
let records = entries
.iter()
.map(|entry| {
PersistedRecord(
entry.key.clone(),
entry
.schema_id
.clone()
.unwrap_or_else(|| entry.r#type.clone()),
entry.stored_at.clone(),
entry.payload.clone(),
)
})
.collect();
PersistedStoreSnapshot("cultcache.store.v1".to_string(), catalog, records)
}
fn decode_store_snapshot(bytes: &[u8]) -> Result<Vec<CultCacheEnvelope>> {
let snapshot: PersistedStoreSnapshot =
rmp_serde::from_slice(bytes).context("failed to decode CultCache v1 snapshot")?;
if snapshot.0 != "cultcache.store.v1" {
return Err(anyhow!("unsupported CultCache snapshot {}", snapshot.0));
}
let catalog = snapshot
.1
.into_iter()
.map(|entry| (entry.0, entry.1))
.collect::<BTreeMap<_, _>>();
snapshot
.2
.into_iter()
.map(|record| {
let r#type = catalog.get(&record.1).cloned().ok_or_else(|| {
anyhow!(
"CultCache record {:?} references missing schema {:?}",
record.0,
record.1
)
})?;
Ok(CultCacheEnvelope {
key: record.0,
r#type,
stored_at: record.2,
payload: record.3,
schema_id: Some(record.1),
})
})
.collect()
}
fn escape_json_string(value: &str) -> String {
value.replace('\\', "\\\\").replace('"', "\\\"")
}
fn temporary_path_for(path: &Path) -> PathBuf {
let mut file_name = path
.file_name()
.map(|value| value.to_os_string())
.unwrap_or_else(|| "cultcache.cc".into());
file_name.push(format!(".{}.tmp", uuid::Uuid::new_v4()));
path.with_file_name(file_name)
}
#[cfg(test)]
mod tests {
use super::*;
use pretty_assertions::assert_eq;
#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
#[cultcache(type = "settings")]
struct Settings {
#[cultcache(key = 0)]
theme: String,
#[cultcache(key = 1, default)]
retries: u32,
}
#[derive(Clone, Debug, PartialEq, Eq, DatabaseEntry)]
#[cultcache(type = "note")]
struct Note {
#[cultcache(key = 0)]
title: String,
#[cultcache(key = 1)]
body: String,
}
cultcache_registry!(TestEntries { Settings, Note });
#[test]
fn familiar_cultcache_flow_persists_and_reloads_typed_documents() -> Result<()> {
let temp = tempfile::tempdir()?;
let store_path = temp.path().join("cache.cc");
let settings = Settings {
theme: "ash".to_string(),
retries: 3,
};
let mut cache = CultCache::new();
cache.register_entry_type::<Settings>()?;
cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&store_path));
cache.pull_all_backing_stores()?;
cache.put("app", &settings)?;
assert_eq!(cache.get_required::<Settings>("app")?, settings);
let mut reloaded = CultCache::new();
reloaded.register_entry_type::<Settings>()?;
reloaded.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&store_path));
reloaded.pull_all_backing_stores()?;
assert_eq!(reloaded.get_required::<Settings>("app")?, settings);
Ok(())
}
#[test]
fn entry_identity_is_polymorphic_by_type_and_key() -> Result<()> {
let temp = tempfile::tempdir()?;
let store_path = temp.path().join("cache.cc");
let mut cache = CultCache::new();
cache.register_registry(TestEntries)?;
cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&store_path));
cache.put(
"shared",
&Settings {
theme: "green".to_string(),
retries: 1,
},
)?;
cache.put(
"shared",
&Note {
title: "same key".to_string(),
body: "different type".to_string(),
},
)?;
assert_eq!(cache.snapshot().len(), 2);
assert_eq!(cache.get_required::<Note>("shared")?.title, "same key");
assert_eq!(cache.get_required::<Settings>("shared")?.theme, "green");
Ok(())
}
#[test]
fn type_specific_store_routes_before_generic_store() -> Result<()> {
let temp = tempfile::tempdir()?;
let generic_path = temp.path().join("generic.cc");
let settings_path = temp.path().join("settings.cc");
let mut cache = CultCache::new();
cache.register_entry_type::<Settings>()?;
cache.register_entry_type::<Note>()?;
cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&generic_path));
cache.add_backing_store(
SingleFileMessagePackBackingStore::new(&settings_path),
["settings"],
);
cache.put(
"app",
&Settings {
theme: "ash".to_string(),
retries: 3,
},
)?;
cache.put(
"memo",
&Note {
title: "hello".to_string(),
body: "world".to_string(),
},
)?;
let generic_entries = SingleFileMessagePackBackingStore::new(&generic_path).pull_all()?;
let settings_entries = SingleFileMessagePackBackingStore::new(&settings_path).pull_all()?;
assert_eq!(generic_entries[0].r#type, "note");
assert_eq!(settings_entries[0].r#type, "settings");
Ok(())
}
#[test]
fn update_and_delete_follow_the_cache_api() -> Result<()> {
let temp = tempfile::tempdir()?;
let store_path = temp.path().join("cache.cc");
let mut cache = CultCache::new();
cache.register_entry_type::<Settings>()?;
cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&store_path));
let updated = cache.update::<Settings, _>("app", |current| {
let mut current = current.unwrap_or(Settings {
theme: "ash".to_string(),
retries: 0,
});
current.retries += 1;
current
})?;
assert_eq!(updated.retries, 1);
assert!(cache.delete::<Settings>("app")?);
assert!(cache.get::<Settings>("app")?.is_none());
Ok(())
}
#[test]
fn pull_rejects_unregistered_persisted_entry_type() -> Result<()> {
let temp = tempfile::tempdir()?;
let store_path = temp.path().join("cache.cc");
let mut store = SingleFileMessagePackBackingStore::new(&store_path);
store.push(&CultCacheEnvelope {
key: "unknown".to_string(),
r#type: "unregistered".to_string(),
payload: rmp_serde::to_vec(&1_u8)?,
stored_at: now_utc_second(),
schema_id: Some("unregistered".to_string()),
})?;
let mut cache = CultCache::new();
cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&store_path));
let error = cache.pull_all_backing_stores().unwrap_err();
assert!(
error
.to_string()
.contains("No schema is registered for persisted entry type")
);
Ok(())
}
#[test]
fn payload_is_binary_messagepack_not_json_value() -> Result<()> {
let temp = tempfile::tempdir()?;
let store_path = temp.path().join("cache.cc");
let mut cache = CultCache::new();
cache.register_entry_type::<Settings>()?;
cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&store_path));
cache.put(
"app",
&Settings {
theme: "ash".to_string(),
retries: 3,
},
)?;
let entry = cache.snapshot().remove(0);
let decoded: Settings = rmp_serde::from_slice(&entry.payload)?;
assert_eq!(decoded.theme, "ash");
assert!(!entry.payload.is_empty());
Ok(())
}
#[test]
fn corrupted_payload_fails_during_typed_retrieval() -> Result<()> {
let temp = tempfile::tempdir()?;
let store_path = temp.path().join("cache.cc");
let mut store = SingleFileMessagePackBackingStore::new(&store_path);
store.push(&CultCacheEnvelope {
key: "app".to_string(),
r#type: "settings".to_string(),
payload: vec![0xc1],
stored_at: now_utc_second(),
schema_id: Some("settings".to_string()),
})?;
let mut cache = CultCache::new();
cache.register_entry_type::<Settings>()?;
cache.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&store_path));
cache.pull_all_backing_stores()?;
let error = cache.get_required::<Settings>("app").unwrap_err();
assert!(
error
.to_string()
.contains("failed to decode CultCache entry")
);
Ok(())
}
#[test]
fn put_envelope_reuses_existing_messagepack_payload() -> Result<()> {
let temp = tempfile::tempdir()?;
let origin_store = temp.path().join("origin.cc");
let target_store = temp.path().join("target.cc");
let mut origin = CultCache::new();
origin.register_entry_type::<Settings>()?;
origin.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&origin_store));
origin.put(
"app",
&Settings {
theme: "ash".to_string(),
retries: 3,
},
)?;
let envelope = origin.get_required_envelope::<Settings>("app")?;
let mut target = CultCache::new();
target.register_entry_type::<Settings>()?;
target.add_generic_backing_store(SingleFileMessagePackBackingStore::new(&target_store));
let applied = target.put_envelope::<Settings>(envelope.clone())?;
assert_eq!(
applied,
Settings {
theme: "ash".to_string(),
retries: 3,
}
);
assert_eq!(target.get_required::<Settings>("app")?, applied);
assert_eq!(
target.get_required_envelope::<Settings>("app")?.payload,
envelope.payload
);
Ok(())
}
}

1233
vendor/cultmesh-rs/Cargo.lock generated vendored Normal file

File diff suppressed because it is too large Load diff

20
vendor/cultmesh-rs/Cargo.toml vendored Normal file
View file

@ -0,0 +1,20 @@
[package]
name = "cultmesh-rs"
version = "0.1.0"
edition = "2024"
publish = false
[lib]
name = "cultmesh_rs"
path = "src/lib.rs"
[dependencies]
anyhow = "1"
cultcache-rs = { path = "../cultcache-rs" }
cultnet-rs = { path = "../cultnet-rs" }
serde = { version = "1", features = ["derive"] }
[dev-dependencies]
pretty_assertions = "1.4.1"
rmp-serde = "1"
tempfile = "3"

1277
vendor/cultmesh-rs/src/lib.rs vendored Normal file

File diff suppressed because it is too large Load diff

2
vendor/cultnet-rs/.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
/target
Cargo.lock

32
vendor/cultnet-rs/Cargo.toml vendored Normal file
View file

@ -0,0 +1,32 @@
[package]
name = "cultnet-rs"
version = "0.1.0"
edition = "2024"
publish = false
license = "MIT"
description = "CultNet-style typed MessagePack messaging, direct-pipe framing, security helpers, and CultCache replication for Rust runtimes."
[lib]
name = "cultnet_rs"
path = "src/lib.rs"
[dependencies]
aes-gcm = "0.10"
anyhow = "1"
base64 = "0.22"
chrono = { version = "0.4", features = ["serde"] }
cultcache-rs = { path = "../cultcache-rs" }
hmac = "0.12"
rand = "0.9"
rmp-serde = "1.3"
rmpv = { version = "1.3", features = ["with-serde"] }
serde = { version = "1", features = ["derive"] }
serde_bytes = "0.11"
serde_json = "1"
sha2 = "0.10"
socket2 = "0.5"
uuid = { version = "1", features = ["v4"] }
[dev-dependencies]
pretty_assertions = "1.4"
tempfile = "3"

96
vendor/cultnet-rs/README.md vendored Normal file
View file

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

View file

@ -0,0 +1,19 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-delete.schema.json",
"title": "CultNet Document Delete Message",
"type": "object",
"required": [
"schemaVersion",
"messageId",
"schemaId",
"recordKey"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.document_delete.v0" },
"messageId": { "type": "string", "minLength": 1 },
"schemaId": { "type": "string", "minLength": 1 },
"recordKey": { "type": "string", "minLength": 1 }
}
}

View file

@ -0,0 +1,40 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-mutation-contract.schema.json",
"title": "CultNet Document Mutation Contract",
"type": "object",
"required": [
"documentType",
"operations",
"authority"
],
"additionalProperties": false,
"properties": {
"documentType": { "type": "string", "minLength": 1 },
"payloadSchemaVersion": { "type": "string", "minLength": 1 },
"operations": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"enum": ["snapshot", "documentPut", "documentDelete", "intentSubmit", "receiptWatch"]
}
},
"authority": {
"type": "string",
"enum": ["readOnly", "localUser", "coordinator", "runtime", "denied"]
},
"intentDocumentTypes": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"receiptDocumentTypes": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"notes": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
}
}
}

View file

@ -0,0 +1,19 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put-raw.schema.json",
"title": "CultNet Raw Document Put Message",
"type": "object",
"required": [
"schemaVersion",
"messageId",
"document"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.document_put_raw.v0" },
"messageId": { "type": "string", "minLength": 1 },
"document": {
"$ref": "./cultnet.raw-document-record.schema.json"
}
}
}

View file

@ -0,0 +1,19 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put.schema.json",
"title": "CultNet Document Put Message",
"type": "object",
"required": [
"schemaVersion",
"messageId",
"document"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.document_put.v0" },
"messageId": { "type": "string", "minLength": 1 },
"document": {
"$ref": "./cultnet.document-record.schema.json"
}
}
}

View file

@ -0,0 +1,26 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-record.schema.json",
"title": "CultNet Document Record",
"type": "object",
"required": [
"schemaId",
"recordKey",
"storedAt",
"payload"
],
"additionalProperties": false,
"properties": {
"schemaId": { "type": "string", "minLength": 1 },
"recordKey": { "type": "string", "minLength": 1 },
"storedAt": { "type": "string", "minLength": 1 },
"payload": {},
"sourceRuntimeId": { "type": "string", "minLength": 1 },
"sourceAgentId": { "type": "string", "minLength": 1 },
"sourceRole": { "type": "string", "minLength": 1 },
"tags": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
}
}
}

View file

@ -0,0 +1,15 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.error.schema.json",
"title": "CultNet Error Message",
"type": "object",
"required": [
"schemaVersion",
"error"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.error.v0" },
"error": { "type": "string", "minLength": 1 }
}
}

View file

@ -0,0 +1,41 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.hello.schema.json",
"title": "CultNet Hello Message",
"type": "object",
"required": [
"schemaVersion",
"runtimeId",
"runtimeKind"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.hello.v0" },
"runtimeId": { "type": "string", "minLength": 1 },
"runtimeKind": { "type": "string", "minLength": 1 },
"agentId": { "type": "string", "minLength": 1 },
"role": { "type": "string", "minLength": 1 },
"displayName": { "type": "string", "minLength": 1 },
"supportedDocumentTypes": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"supportedMutationContracts": {
"type": "array",
"items": {
"$ref": "./cultnet.document-mutation-contract.schema.json"
}
},
"supportedMessageVersions": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"transportProfiles": {
"type": "array",
"items": {
"$ref": "./cultnet.transport-profile.schema.json"
}
},
"supportsSchemaCatalog": { "type": "boolean" }
}
}

View file

@ -0,0 +1,17 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.login-success.schema.json",
"title": "CultNet Login Success Message",
"type": "object",
"required": [
"schemaVersion",
"nonce",
"session"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.login_success.v0" },
"nonce": { "type": "string", "minLength": 1 },
"session": { "type": "string", "minLength": 1 }
}
}

View file

@ -0,0 +1,19 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.login.schema.json",
"title": "CultNet Login Message",
"type": "object",
"required": [
"schemaVersion",
"nonce",
"auth",
"password"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.login.v0" },
"nonce": { "type": "string", "minLength": 1 },
"auth": { "type": "string", "minLength": 1 },
"password": { "type": "string", "minLength": 1 }
}
}

View file

@ -0,0 +1,32 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.raw-document-record.schema.json",
"title": "CultNet Raw Document Record",
"type": "object",
"required": [
"schemaId",
"recordKey",
"storedAt",
"payloadEncoding",
"payload"
],
"additionalProperties": false,
"properties": {
"schemaId": { "type": "string", "minLength": 1 },
"recordKey": { "type": "string", "minLength": 1 },
"storedAt": { "type": "string", "minLength": 1 },
"payloadEncoding": { "const": "messagepack" },
"payload": {
"type": "string",
"contentEncoding": "base64",
"x-cult-runtime-type": "bytes"
},
"sourceRuntimeId": { "type": "string", "minLength": 1 },
"sourceAgentId": { "type": "string", "minLength": 1 },
"sourceRole": { "type": "string", "minLength": 1 },
"tags": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
}
}
}

View file

@ -0,0 +1,21 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.register.schema.json",
"title": "CultNet Register Message",
"type": "object",
"required": [
"schemaVersion",
"nonce",
"email",
"password",
"name"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.register.v0" },
"nonce": { "type": "string", "minLength": 1 },
"email": { "type": "string", "minLength": 1 },
"password": { "type": "string", "minLength": 1 },
"name": { "type": "string", "minLength": 1 }
}
}

View file

@ -0,0 +1,15 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.sample-change-name.schema.json",
"title": "CultNet Sample Change Name Message",
"type": "object",
"required": [
"schemaVersion",
"name"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.sample.change_name.v0" },
"name": { "type": "string", "minLength": 1 }
}
}

View file

@ -0,0 +1,15 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.sample-chat.schema.json",
"title": "CultNet Sample Chat Message",
"type": "object",
"required": [
"schemaVersion",
"text"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.sample.chat.v0" },
"text": { "type": "string", "minLength": 1 }
}
}

View file

@ -0,0 +1,31 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.schema-catalog-request.schema.json",
"title": "CultNet Schema Catalog Request Message",
"type": "object",
"required": [
"schemaVersion",
"messageId"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.schema_catalog_request.v0" },
"messageId": { "type": "string", "minLength": 1 },
"includeSchemaJson": { "type": "boolean" },
"schemaIds": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"kinds": {
"type": "array",
"items": {
"type": "string",
"enum": [
"wire_message",
"document_payload",
"shared_contract"
]
}
}
}
}

View file

@ -0,0 +1,22 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.schema-catalog-response.schema.json",
"title": "CultNet Schema Catalog Response Message",
"type": "object",
"required": [
"schemaVersion",
"messageId",
"schemas"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.schema_catalog_response.v0" },
"messageId": { "type": "string", "minLength": 1 },
"schemas": {
"type": "array",
"items": {
"$ref": "./cultnet.schema-descriptor.schema.json"
}
}
}
}

View file

@ -0,0 +1,39 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.schema-descriptor.schema.json",
"title": "CultNet Schema Descriptor",
"type": "object",
"required": [
"schemaId",
"kind",
"wireContracts",
"contentHash"
],
"additionalProperties": false,
"properties": {
"schemaId": { "type": "string", "minLength": 1 },
"kind": {
"type": "string",
"enum": [
"wire_message",
"document_payload",
"shared_contract"
]
},
"schemaVersion": { "type": "string", "minLength": 1 },
"documentType": { "type": "string", "minLength": 1 },
"title": { "type": "string", "minLength": 1 },
"wireContracts": {
"type": "array",
"items": {
"type": "string",
"enum": [
"cultnet.schema.v0",
"gamecult.networking.v0"
]
}
},
"contentHash": { "type": "string", "minLength": 1 },
"schemaJson": { "type": "string", "minLength": 1 }
}
}

View file

@ -0,0 +1,23 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.snapshot-request.schema.json",
"title": "CultNet Snapshot Request Message",
"type": "object",
"required": [
"schemaVersion",
"messageId"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.snapshot_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,22 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.snapshot-response-raw.schema.json",
"title": "CultNet Raw Snapshot Response Message",
"type": "object",
"required": [
"schemaVersion",
"messageId",
"documents"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.snapshot_response_raw.v0" },
"messageId": { "type": "string", "minLength": 1 },
"documents": {
"type": "array",
"items": {
"$ref": "./cultnet.raw-document-record.schema.json"
}
}
}
}

View file

@ -0,0 +1,22 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.snapshot-response.schema.json",
"title": "CultNet Snapshot Response Message",
"type": "object",
"required": [
"schemaVersion",
"messageId",
"documents"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.snapshot_response.v0" },
"messageId": { "type": "string", "minLength": 1 },
"documents": {
"type": "array",
"items": {
"$ref": "./cultnet.document-record.schema.json"
}
}
}
}

View file

@ -0,0 +1,81 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.transport-profile.schema.json",
"title": "CultNet Transport Profile",
"type": "object",
"required": [
"schemaVersion",
"runtimeId",
"transports"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.transport_profile.v0" },
"runtimeId": { "type": "string", "minLength": 1 },
"transports": {
"type": "array",
"items": {
"type": "object",
"required": [
"transportId",
"protocol",
"channels"
],
"additionalProperties": false,
"properties": {
"transportId": { "type": "string", "minLength": 1 },
"protocol": {
"type": "string",
"enum": [
"tcp_framed",
"litenetlib",
"websocket",
"rudp"
]
},
"host": { "type": "string", "minLength": 1 },
"port": { "type": "integer", "minimum": 1, "maximum": 65535 },
"path": { "type": "string", "minLength": 1 },
"discoveryGroup": { "type": "string", "minLength": 1 },
"wireContracts": {
"type": "array",
"items": { "type": "string", "minLength": 1 }
},
"channels": {
"type": "array",
"items": {
"type": "object",
"required": [
"channelId",
"delivery",
"ordering"
],
"additionalProperties": false,
"properties": {
"channelId": { "type": "string", "minLength": 1 },
"delivery": {
"type": "string",
"enum": [
"reliable",
"unreliable"
]
},
"ordering": {
"type": "string",
"enum": [
"ordered",
"unordered",
"sequenced"
]
},
"maxPayloadBytes": { "type": "integer", "minimum": 1 },
"maxFragmentBytes": { "type": "integer", "minimum": 1 },
"maxPendingReliablePackets": { "type": "integer", "minimum": 1 }
}
}
}
}
}
}
}
}

View file

@ -0,0 +1,17 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/cultnet-ts/contracts/cultnet.verify.schema.json",
"title": "CultNet Verify Message",
"type": "object",
"required": [
"schemaVersion",
"nonce",
"session"
],
"additionalProperties": false,
"properties": {
"schemaVersion": { "const": "cultnet.verify.v0" },
"nonce": { "type": "string", "minLength": 1 },
"session": { "type": "string", "minLength": 1 }
}
}

View file

@ -0,0 +1,845 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/GameCult/Ghostlight/schemas/agent-state.schema.json",
"title": "Ghostlight Agent State Schema",
"description": "First canonical contract for Ghostlight agent, perception, relationship, event, scene, and dialogue-context state.",
"type": "object",
"required": [
"schema_version",
"world",
"agents",
"relationships",
"events",
"scenes"
],
"additionalProperties": false,
"properties": {
"schema_version": {
"const": "ghostlight.agent_state.v0"
},
"world": {
"$ref": "#/$defs/world_state"
},
"agents": {
"type": "array",
"items": {
"$ref": "#/$defs/agent"
}
},
"relationships": {
"type": "array",
"items": {
"$ref": "#/$defs/relationship"
}
},
"events": {
"type": "array",
"items": {
"$ref": "#/$defs/event"
}
},
"scenes": {
"type": "array",
"items": {
"$ref": "#/$defs/scene"
}
}
},
"$defs": {
"world_state": {
"type": "object",
"required": [
"world_id",
"setting",
"time",
"canon_context"
],
"additionalProperties": false,
"properties": {
"world_id": {
"type": "string"
},
"setting": {
"type": "string"
},
"time": {
"type": "object",
"required": [
"label"
],
"additionalProperties": true,
"properties": {
"label": {
"type": "string"
}
}
},
"canon_context": {
"type": "array",
"items": {
"type": "string"
}
},
"ambient_pressures": {
"type": "array",
"items": {
"$ref": "#/$defs/pressure"
}
}
}
},
"agent": {
"type": "object",
"required": [
"agent_id",
"identity",
"canonical_state",
"goals",
"memories",
"perceived_state_overlays"
],
"additionalProperties": false,
"properties": {
"agent_id": {
"type": "string"
},
"identity": {
"$ref": "#/$defs/identity"
},
"canonical_state": {
"$ref": "#/$defs/canonical_state"
},
"goals": {
"type": "array",
"items": {
"$ref": "#/$defs/goal"
}
},
"memories": {
"$ref": "#/$defs/memory_bundle"
},
"perceived_state_overlays": {
"type": "array",
"items": {
"$ref": "#/$defs/perceived_state_overlay"
}
}
}
},
"identity": {
"type": "object",
"required": [
"name",
"roles",
"origin",
"public_description"
],
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"roles": {
"type": "array",
"items": {
"type": "string"
}
},
"origin": {
"type": "string"
},
"public_description": {
"type": "string"
},
"private_notes": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"canonical_state": {
"type": "object",
"required": [
"underlying_organization",
"stable_dispositions",
"behavioral_dimensions",
"presentation_strategy",
"voice_style",
"situational_state",
"values"
],
"additionalProperties": false,
"properties": {
"underlying_organization": {
"$ref": "#/$defs/variable_map"
},
"stable_dispositions": {
"$ref": "#/$defs/variable_map"
},
"behavioral_dimensions": {
"$ref": "#/$defs/variable_map"
},
"presentation_strategy": {
"$ref": "#/$defs/variable_map"
},
"situational_state": {
"$ref": "#/$defs/variable_map"
},
"values": {
"type": "array",
"items": {
"$ref": "#/$defs/value_commitment"
}
},
"voice_style": {
"$ref": "#/$defs/variable_map"
}
}
},
"variable_map": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/state_variable"
}
},
"state_variable": {
"type": "object",
"required": [
"mean",
"plasticity",
"current_activation"
],
"additionalProperties": false,
"properties": {
"mean": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"plasticity": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"current_activation": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"evidence": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"value_commitment": {
"type": "object",
"required": [
"value_id",
"label",
"priority",
"unforgivable_if_betrayed"
],
"additionalProperties": false,
"properties": {
"value_id": {
"type": "string"
},
"label": {
"type": "string"
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"unforgivable_if_betrayed": {
"type": "boolean"
}
}
},
"goal": {
"type": "object",
"required": [
"goal_id",
"description",
"scope",
"priority",
"emotional_stake",
"status"
],
"additionalProperties": false,
"properties": {
"goal_id": {
"type": "string"
},
"description": {
"type": "string"
},
"scope": {
"enum": [
"immediate",
"scene",
"case",
"arc",
"life"
]
},
"priority": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"emotional_stake": {
"type": "string"
},
"blockers": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"enum": [
"active",
"blocked",
"dormant",
"resolved",
"abandoned"
]
}
}
},
"memory_bundle": {
"type": "object",
"required": [
"episodic",
"semantic",
"relationship_summaries"
],
"additionalProperties": false,
"properties": {
"episodic": {
"type": "array",
"items": {
"$ref": "#/$defs/memory"
}
},
"semantic": {
"type": "array",
"items": {
"$ref": "#/$defs/memory"
}
},
"relationship_summaries": {
"type": "array",
"items": {
"$ref": "#/$defs/memory"
}
}
}
},
"memory": {
"type": "object",
"required": [
"memory_id",
"summary",
"salience",
"confidence"
],
"additionalProperties": false,
"properties": {
"memory_id": {
"type": "string"
},
"summary": {
"type": "string"
},
"salience": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"linked_event_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"linked_relationship_id": {
"type": "string"
}
}
},
"perceived_state_overlay": {
"type": "object",
"required": [
"observer_agent_id",
"target_agent_id",
"perceived_dimensions",
"beliefs",
"distortions"
],
"additionalProperties": false,
"properties": {
"observer_agent_id": {
"type": "string"
},
"target_agent_id": {
"type": "string"
},
"perceived_dimensions": {
"$ref": "#/$defs/inferred_variable_map"
},
"beliefs": {
"type": "array",
"items": {
"$ref": "#/$defs/belief"
}
},
"distortions": {
"type": "array",
"items": {
"enum": [
"hostile_attribution",
"false_reassurance",
"overread_warmth",
"underread_threat",
"false_mask_detection",
"missed_mask_detection",
"status_injury",
"threat_amplification",
"institutional_suspicion_transfer",
"care_underread",
"mask_overfocus"
]
}
}
}
},
"belief": {
"type": "object",
"required": [
"belief_id",
"claim",
"confidence"
],
"additionalProperties": false,
"properties": {
"belief_id": {
"type": "string"
},
"claim": {
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"subject_id": {
"type": "string"
},
"claim_type": {
"enum": [
"fact",
"identity_inference",
"motive_inference",
"prediction",
"norm",
"value_read",
"relationship_read"
]
},
"evidence_event_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"visibility": {
"enum": [
"private",
"shared",
"public",
"rumor"
]
},
"emotional_charge": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
},
"relationship": {
"type": "object",
"required": [
"relationship_id",
"source_id",
"target_id",
"stance",
"summary"
],
"additionalProperties": false,
"properties": {
"relationship_id": {
"type": "string"
},
"source_id": {
"type": "string"
},
"target_id": {
"type": "string"
},
"stance": {
"$ref": "#/$defs/variable_map"
},
"summary": {
"type": "string"
},
"unresolved_incident_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"event": {
"type": "object",
"required": [
"event_id",
"kind",
"summary",
"participants",
"pressure_tags"
],
"additionalProperties": false,
"properties": {
"event_id": {
"type": "string"
},
"kind": {
"enum": [
"dialogue",
"action",
"memory",
"relationship_shift",
"scene_outcome",
"author_note"
]
},
"summary": {
"type": "string"
},
"participants": {
"type": "array",
"items": {
"type": "string"
}
},
"pressure_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"observed_exchange": {
"type": "array",
"items": {
"$ref": "#/$defs/event_exchange_turn"
}
},
"private_interpretations": {
"type": "array",
"items": {
"$ref": "#/$defs/event_private_interpretation"
}
},
"event_effects": {
"type": "array",
"items": {
"$ref": "#/$defs/event_effect"
}
}
}
},
"scene": {
"type": "object",
"required": [
"scene_id",
"location",
"participants",
"public_stakes",
"hidden_stakes",
"dialogue_context_packs"
],
"additionalProperties": false,
"properties": {
"scene_id": {
"type": "string"
},
"location": {
"type": "string"
},
"participants": {
"type": "array",
"items": {
"type": "string"
}
},
"public_stakes": {
"type": "array",
"items": {
"type": "string"
}
},
"hidden_stakes": {
"type": "array",
"items": {
"type": "string"
}
},
"dialogue_context_packs": {
"type": "array",
"items": {
"$ref": "#/$defs/dialogue_context_pack"
}
}
}
},
"dialogue_context_pack": {
"type": "object",
"required": [
"speaker_agent_id",
"listener_ids",
"speaker_local_truth",
"speaker_beliefs",
"active_memories",
"active_goals",
"presentation_constraints"
],
"additionalProperties": false,
"properties": {
"speaker_agent_id": {
"type": "string"
},
"listener_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"speaker_local_truth": {
"type": "array",
"items": {
"type": "string"
}
},
"speaker_beliefs": {
"type": "array",
"items": {
"type": "string"
}
},
"active_memories": {
"type": "array",
"items": {
"type": "string"
}
},
"active_goals": {
"type": "array",
"items": {
"type": "string"
}
},
"presentation_constraints": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"pressure": {
"type": "object",
"required": [
"pressure_id",
"label",
"intensity"
],
"additionalProperties": false,
"properties": {
"pressure_id": {
"type": "string"
},
"label": {
"type": "string"
},
"intensity": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
},
"inferred_variable_map": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/inferred_state_variable"
}
},
"inferred_state_variable": {
"type": "object",
"required": [
"observed_activation",
"attributed_disposition",
"confidence"
],
"additionalProperties": false,
"properties": {
"observed_activation": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"attributed_disposition": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"evidence": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"event_exchange_turn": {
"type": "object",
"required": [
"speaker_id",
"utterance_summary",
"dialogue_function"
],
"additionalProperties": false,
"properties": {
"speaker_id": {
"type": "string"
},
"utterance_summary": {
"type": "string"
},
"dialogue_function": {
"type": "string"
},
"observable_cues": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"event_private_interpretation": {
"type": "object",
"required": [
"agent_id",
"interpretation",
"confidence"
],
"additionalProperties": false,
"properties": {
"agent_id": {
"type": "string"
},
"interpretation": {
"type": "string"
},
"attributed_motive": {
"type": "string"
},
"appraisal_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
}
}
},
"event_effect": {
"type": "object",
"required": [
"agent_id",
"summary"
],
"additionalProperties": false,
"properties": {
"agent_id": {
"type": "string"
},
"summary": {
"type": "string"
},
"state_deltas": {
"type": "array",
"items": {
"$ref": "#/$defs/state_delta"
}
},
"new_belief_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"memory_update_ids": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"state_delta": {
"type": "object",
"required": [
"path",
"delta"
],
"additionalProperties": false,
"properties": {
"path": {
"type": "string"
},
"delta": {
"type": "number",
"minimum": -1,
"maximum": 1
}
}
}
}
}

File diff suppressed because it is too large Load diff

1224
vendor/cultnet-rs/src/contracts.rs vendored Normal file

File diff suppressed because it is too large Load diff

49
vendor/cultnet-rs/src/framing.rs vendored Normal file
View file

@ -0,0 +1,49 @@
use anyhow::Result;
use anyhow::anyhow;
pub const FRAME_HEADER_BYTES: usize = 4;
pub fn encode_frame(payload: &[u8]) -> Result<Vec<u8>> {
let len: u32 = payload
.len()
.try_into()
.map_err(|_| anyhow!("CultNet frame payload is too large"))?;
let mut frame = Vec::with_capacity(FRAME_HEADER_BYTES + payload.len());
frame.extend_from_slice(&len.to_be_bytes());
frame.extend_from_slice(payload);
Ok(frame)
}
#[derive(Clone, Debug, Default)]
pub struct LengthPrefixedMessageFramer {
buffer: Vec<u8>,
}
impl LengthPrefixedMessageFramer {
pub fn new() -> Self {
Self::default()
}
pub fn push(&mut self, chunk: impl AsRef<[u8]>) -> Vec<Vec<u8>> {
self.buffer.extend_from_slice(chunk.as_ref());
let mut frames = Vec::new();
loop {
if self.buffer.len() < FRAME_HEADER_BYTES {
break;
}
let payload_len = u32::from_be_bytes([
self.buffer[0],
self.buffer[1],
self.buffer[2],
self.buffer[3],
]) as usize;
let total_len = FRAME_HEADER_BYTES + payload_len;
if self.buffer.len() < total_len {
break;
}
frames.push(self.buffer[FRAME_HEADER_BYTES..total_len].to_vec());
self.buffer.drain(0..total_len);
}
frames
}
}

15
vendor/cultnet-rs/src/lib.rs vendored Normal file
View file

@ -0,0 +1,15 @@
mod contracts;
mod framing;
mod replication;
mod rudp;
mod schema_discovery;
mod security;
mod transport;
pub use contracts::*;
pub use framing::*;
pub use replication::*;
pub use rudp::*;
pub use schema_discovery::*;
pub use security::*;
pub use transport::*;

440
vendor/cultnet-rs/src/replication.rs vendored Normal file
View file

@ -0,0 +1,440 @@
use anyhow::Context;
use anyhow::Result;
use anyhow::anyhow;
use cultcache_rs::CultCache;
use cultcache_rs::CultCacheEnvelope;
use cultcache_rs::DatabaseEntry;
use serde::Serialize;
use serde::de::DeserializeOwned;
use serde_json::Value;
use std::collections::BTreeMap;
use std::collections::BTreeSet;
use crate::CultNetDocumentMutationContract;
use crate::CultNetDocumentRecord;
use crate::CultNetMessage;
use crate::CultNetRawDocumentRecord;
use crate::CultNetRawPayloadEncoding;
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct CultNetDocumentPutOptions {
pub stored_at: Option<String>,
pub source_runtime_id: Option<String>,
pub source_agent_id: Option<String>,
pub source_role: Option<String>,
pub tags: Option<Vec<String>>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CultNetDocumentBinding {
pub schema_id: String,
pub document_type: String,
pub mutation_contract: Option<CultNetDocumentMutationContract>,
pub payload_schema_version: Option<String>,
}
impl CultNetDocumentBinding {
pub fn for_entry<T: DatabaseEntry>(payload_schema_version: impl Into<Option<String>>) -> Self {
Self {
document_type: T::TYPE.to_string(),
schema_id: T::TYPE.to_string(),
mutation_contract: None,
payload_schema_version: payload_schema_version.into(),
}
}
pub fn for_entry_with_schema_id<T: DatabaseEntry>(
schema_id: impl Into<String>,
payload_schema_version: impl Into<Option<String>>,
) -> Self {
Self {
document_type: T::TYPE.to_string(),
schema_id: schema_id.into(),
mutation_contract: None,
payload_schema_version: payload_schema_version.into(),
}
}
pub fn with_mutation_contract(mut self, contract: CultNetDocumentMutationContract) -> Self {
self.mutation_contract = Some(contract);
self
}
}
#[derive(Clone, Debug, Default)]
pub struct CultNetDocumentRegistry {
bindings_by_type: BTreeMap<String, CultNetDocumentBinding>,
bindings_by_schema_id: BTreeMap<String, CultNetDocumentBinding>,
}
impl CultNetDocumentRegistry {
pub fn new() -> Self {
Self::default()
}
pub fn register(&mut self, binding: CultNetDocumentBinding) -> &mut Self {
self.bindings_by_schema_id
.insert(binding.schema_id.clone(), binding.clone());
self.bindings_by_type
.insert(binding.document_type.clone(), binding);
self
}
pub fn binding(&self, document_type: &str) -> Option<&CultNetDocumentBinding> {
self.bindings_by_type.get(document_type)
}
pub fn binding_by_schema_id(&self, schema_id: &str) -> Option<&CultNetDocumentBinding> {
self.bindings_by_schema_id.get(schema_id)
}
pub fn mutation_contracts(&self) -> Vec<CultNetDocumentMutationContract> {
self.bindings_by_type
.values()
.filter_map(|binding| binding.mutation_contract.clone())
.collect()
}
pub fn create_document_put_message<T>(
&self,
message_id: impl Into<String>,
record_key: impl Into<String>,
value: &T,
options: CultNetDocumentPutOptions,
) -> Result<CultNetMessage>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
let binding = self.require_binding(T::TYPE)?;
let payload = serde_json::to_value(round_trip_typed(value)?)?;
Ok(CultNetMessage::DocumentPut {
message_id: message_id.into(),
document: CultNetDocumentRecord {
schema_id: binding.schema_id.clone(),
record_key: record_key.into(),
stored_at: options.stored_at.unwrap_or_else(now_utc_second),
payload,
source_runtime_id: options.source_runtime_id,
source_agent_id: options.source_agent_id,
source_role: options.source_role,
tags: options.tags,
},
})
}
pub fn create_document_delete_message(
&self,
message_id: impl Into<String>,
schema_id: impl Into<String>,
record_key: impl Into<String>,
) -> CultNetMessage {
CultNetMessage::DocumentDelete {
message_id: message_id.into(),
schema_id: schema_id.into(),
record_key: record_key.into(),
}
}
pub fn create_raw_document_put_message_from_envelope(
&self,
message_id: impl Into<String>,
envelope: &CultCacheEnvelope,
) -> Result<CultNetMessage> {
Ok(CultNetMessage::DocumentPutRaw {
message_id: message_id.into(),
document: self.raw_document_record_from_envelope(envelope)?,
})
}
pub fn create_raw_document_put_message<T>(
&self,
message_id: impl Into<String>,
record_key: impl Into<String>,
value: &T,
options: CultNetDocumentPutOptions,
) -> Result<CultNetMessage>
where
T: DatabaseEntry + Serialize,
{
let binding = self.require_binding(T::TYPE)?;
Ok(CultNetMessage::DocumentPutRaw {
message_id: message_id.into(),
document: CultNetRawDocumentRecord {
schema_id: binding.schema_id.clone(),
record_key: record_key.into(),
stored_at: options.stored_at.unwrap_or_else(now_utc_second),
payload_encoding: CultNetRawPayloadEncoding::Messagepack,
payload: rmp_serde::to_vec(value)?,
source_runtime_id: options.source_runtime_id,
source_agent_id: options.source_agent_id,
source_role: options.source_role,
tags: options.tags,
},
})
}
pub fn create_snapshot_response(
&self,
cache: &CultCache,
message_id: impl Into<String>,
schema_ids: Option<&[String]>,
record_keys: Option<&[String]>,
) -> Result<CultNetMessage> {
let requested_schema_ids = schema_ids.map(|items| items.iter().collect::<BTreeSet<_>>());
let requested_record_keys = record_keys.map(|items| items.iter().collect::<BTreeSet<_>>());
let mut documents = Vec::new();
for envelope in cache.snapshot() {
let binding = self.require_binding(&envelope.r#type)?;
if requested_schema_ids
.as_ref()
.is_some_and(|ids| !ids.contains(&binding.schema_id))
{
continue;
}
if requested_record_keys
.as_ref()
.is_some_and(|keys| !keys.contains(&envelope.key))
{
continue;
}
documents.push(self.document_record_from_envelope(&envelope)?);
}
Ok(CultNetMessage::SnapshotResponse {
message_id: message_id.into(),
documents,
})
}
pub fn create_raw_snapshot_response(
&self,
cache: &CultCache,
message_id: impl Into<String>,
schema_ids: Option<&[String]>,
record_keys: Option<&[String]>,
) -> Result<CultNetMessage> {
let requested_schema_ids = schema_ids.map(|items| items.iter().collect::<BTreeSet<_>>());
let requested_record_keys = record_keys.map(|items| items.iter().collect::<BTreeSet<_>>());
let mut documents = Vec::new();
for envelope in cache.snapshot() {
let binding = self.require_binding(&envelope.r#type)?;
if requested_schema_ids
.as_ref()
.is_some_and(|ids| !ids.contains(&binding.schema_id))
{
continue;
}
if requested_record_keys
.as_ref()
.is_some_and(|keys| !keys.contains(&envelope.key))
{
continue;
}
documents.push(self.raw_document_record_from_envelope(&envelope)?);
}
Ok(CultNetMessage::SnapshotResponseRaw {
message_id: message_id.into(),
documents,
})
}
pub fn apply_document_put_message<T>(
&self,
cache: &mut CultCache,
message: &CultNetMessage,
) -> Result<T>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
let CultNetMessage::DocumentPut { document, .. } = message else {
return Err(anyhow!("expected cultnet.document_put.v0"));
};
let binding = self.require_binding(T::TYPE)?;
if document.schema_id != binding.schema_id {
return Err(anyhow!(
"schema id {:?} does not match registered Rust type {:?} schema {:?}",
document.schema_id,
T::TYPE,
binding.schema_id
));
}
let value: T = serde_json::from_value(document.payload.clone()).with_context(|| {
format!(
"failed to decode CultNet payload schema {:?} as {}",
binding.schema_id,
T::SCHEMA_NAME
)
})?;
cache.put(&document.record_key, &value)
}
pub fn apply_document_delete_message<T>(
&self,
cache: &mut CultCache,
message: &CultNetMessage,
) -> Result<bool>
where
T: DatabaseEntry,
{
let CultNetMessage::DocumentDelete {
schema_id,
record_key,
..
} = message
else {
return Err(anyhow!("expected cultnet.document_delete.v0"));
};
let binding = self.require_binding(T::TYPE)?;
if schema_id != &binding.schema_id {
return Err(anyhow!(
"schema id {:?} does not match registered Rust type {:?} schema {:?}",
schema_id,
T::TYPE,
binding.schema_id
));
}
cache.delete::<T>(record_key)
}
pub fn apply_raw_document_put_message<T>(
&self,
cache: &mut CultCache,
message: &CultNetMessage,
) -> Result<T>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
let CultNetMessage::DocumentPutRaw { document, .. } = message else {
return Err(anyhow!("expected cultnet.document_put_raw.v0"));
};
let binding = self.require_binding(T::TYPE)?;
if document.schema_id != binding.schema_id {
return Err(anyhow!(
"schema id {:?} does not match registered Rust type {:?} schema {:?}",
document.schema_id,
T::TYPE,
binding.schema_id
));
}
cache.put_envelope::<T>(CultCacheEnvelope {
key: document.record_key.clone(),
r#type: binding.document_type.clone(),
payload: document.payload.clone(),
stored_at: document.stored_at.clone(),
schema_id: Some(binding.schema_id.clone()),
})
}
pub fn apply_snapshot_response<T>(
&self,
cache: &mut CultCache,
response: &CultNetMessage,
) -> Result<Vec<T>>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
let CultNetMessage::SnapshotResponse { documents, .. } = response else {
return Err(anyhow!("expected cultnet.snapshot_response.v0"));
};
let mut applied = Vec::new();
let binding = self.require_binding(T::TYPE)?;
for document in documents {
if document.schema_id != binding.schema_id {
continue;
}
applied.push(self.apply_document_put_message::<T>(
cache,
&CultNetMessage::DocumentPut {
message_id: "snapshot-apply".to_string(),
document: document.clone(),
},
)?);
}
Ok(applied)
}
pub fn apply_raw_snapshot_response<T>(
&self,
cache: &mut CultCache,
response: &CultNetMessage,
) -> Result<Vec<T>>
where
T: DatabaseEntry + Serialize + DeserializeOwned,
{
let CultNetMessage::SnapshotResponseRaw { documents, .. } = response else {
return Err(anyhow!("expected cultnet.snapshot_response_raw.v0"));
};
let mut applied = Vec::new();
let binding = self.require_binding(T::TYPE)?;
for document in documents {
if document.schema_id != binding.schema_id {
continue;
}
applied.push(self.apply_raw_document_put_message::<T>(
cache,
&CultNetMessage::DocumentPutRaw {
message_id: "snapshot-apply-raw".to_string(),
document: document.clone(),
},
)?);
}
Ok(applied)
}
fn document_record_from_envelope(
&self,
envelope: &CultCacheEnvelope,
) -> Result<CultNetDocumentRecord<Value>> {
let binding = self.require_binding(&envelope.r#type)?;
let payload: Value = rmp_serde::from_slice(&envelope.payload).with_context(|| {
format!(
"failed to decode CultCache envelope {:?} at {:?} as generic CultNet payload",
envelope.r#type, envelope.key
)
})?;
Ok(CultNetDocumentRecord {
schema_id: binding.schema_id.clone(),
record_key: envelope.key.clone(),
stored_at: envelope.stored_at.clone(),
payload,
source_runtime_id: None,
source_agent_id: None,
source_role: None,
tags: None,
})
}
fn raw_document_record_from_envelope(
&self,
envelope: &CultCacheEnvelope,
) -> Result<CultNetRawDocumentRecord> {
let binding = self.require_binding(&envelope.r#type)?;
Ok(CultNetRawDocumentRecord {
schema_id: binding.schema_id.clone(),
record_key: envelope.key.clone(),
stored_at: envelope.stored_at.clone(),
payload_encoding: CultNetRawPayloadEncoding::Messagepack,
payload: envelope.payload.clone(),
source_runtime_id: None,
source_agent_id: None,
source_role: None,
tags: None,
})
}
fn require_binding(&self, document_type: &str) -> Result<&CultNetDocumentBinding> {
self.binding(document_type).ok_or_else(|| {
anyhow!("No CultNet document binding is registered for {document_type:?}")
})
}
}
fn round_trip_typed<T>(value: &T) -> Result<T>
where
T: Serialize + DeserializeOwned,
{
Ok(rmp_serde::from_slice(&rmp_serde::to_vec(value)?)?)
}
fn now_utc_second() -> String {
chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
}

1444
vendor/cultnet-rs/src/rudp.rs vendored Normal file

File diff suppressed because it is too large Load diff

View file

@ -0,0 +1,396 @@
use anyhow::Result;
use anyhow::anyhow;
use serde_json::Value;
use sha2::Digest;
use sha2::Sha256;
use std::collections::BTreeMap;
use std::collections::BTreeSet;
use crate::CultNetMessage;
use crate::CultNetSchemaDescriptor;
use crate::CultNetSchemaKind;
use crate::CultNetWireContract;
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CultNetSchemaRegistration {
pub schema_id: String,
pub kind: CultNetSchemaKind,
pub wire_contracts: Vec<CultNetWireContract>,
pub schema_version: Option<String>,
pub document_type: Option<String>,
pub title: Option<String>,
pub schema_json: Option<String>,
}
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct CultNetSchemaCatalogOptions {
pub include_schema_json: bool,
pub schema_ids: Option<Vec<String>>,
pub kinds: Option<Vec<CultNetSchemaKind>>,
}
#[derive(Clone, Debug, Default)]
pub struct CultNetSchemaRegistry {
entries: BTreeMap<String, CultNetSchemaDescriptor>,
}
impl CultNetSchemaRegistry {
pub fn new() -> Self {
Self::default()
}
pub fn register(&mut self, registration: CultNetSchemaRegistration) -> Result<()> {
if registration.schema_id.trim().is_empty() {
return Err(anyhow!("schema_id must be non-empty"));
}
if registration.wire_contracts.is_empty() {
return Err(anyhow!("wire_contracts must contain at least one entry"));
}
let content_hash = if let Some(schema_json) = registration.schema_json.as_deref() {
canonical_schema_hash(schema_json)?
} else {
return Err(anyhow!(
"schema_json is required so discovery can advertise canonical hashes"
));
};
self.entries.insert(
registration.schema_id.clone(),
CultNetSchemaDescriptor {
schema_id: registration.schema_id,
kind: registration.kind,
schema_version: registration.schema_version,
document_type: registration.document_type,
title: registration.title,
wire_contracts: registration.wire_contracts,
content_hash,
schema_json: registration.schema_json,
},
);
Ok(())
}
pub fn get(
&self,
schema_id: &str,
include_schema_json: bool,
) -> Option<CultNetSchemaDescriptor> {
self.entries
.get(schema_id)
.map(|entry| sanitize_descriptor(entry, include_schema_json))
}
pub fn list(&self, options: &CultNetSchemaCatalogOptions) -> Vec<CultNetSchemaDescriptor> {
let requested_ids = options
.schema_ids
.as_ref()
.map(|values| values.iter().cloned().collect::<BTreeSet<_>>());
let requested_kinds = options
.kinds
.as_ref()
.map(|values| values.iter().copied().collect::<BTreeSet<_>>());
self.entries
.values()
.filter(|entry| {
if let Some(requested_ids) = &requested_ids
&& !requested_ids.contains(&entry.schema_id)
{
return false;
}
if let Some(requested_kinds) = &requested_kinds
&& !requested_kinds.contains(&entry.kind)
{
return false;
}
true
})
.map(|entry| sanitize_descriptor(entry, options.include_schema_json))
.collect()
}
pub fn create_catalog_response(&self, request: &CultNetMessage) -> Result<CultNetMessage> {
let CultNetMessage::SchemaCatalogRequest {
message_id,
include_schema_json,
schema_ids,
kinds,
} = request
else {
return Err(anyhow!(
"expected cultnet.schema_catalog_request.v0 for schema discovery"
));
};
Ok(CultNetMessage::SchemaCatalogResponse {
message_id: message_id.clone(),
schemas: self.list(&CultNetSchemaCatalogOptions {
include_schema_json: include_schema_json.unwrap_or(false),
schema_ids: schema_ids.clone(),
kinds: kinds.clone(),
}),
})
}
}
fn sanitize_descriptor(
descriptor: &CultNetSchemaDescriptor,
include_schema_json: bool,
) -> CultNetSchemaDescriptor {
let mut clone = descriptor.clone();
if !include_schema_json {
clone.schema_json = None;
}
clone
}
fn canonical_schema_hash(schema_json: &str) -> Result<String> {
let value: Value = serde_json::from_str(schema_json)?;
let canonical = stable_stringify(&value);
Ok(format!("{:x}", Sha256::digest(canonical.as_bytes())))
}
fn stable_stringify(value: &Value) -> String {
match value {
Value::Null => "null".to_string(),
Value::Bool(value) => value.to_string(),
Value::Number(value) => value.to_string(),
Value::String(value) => serde_json::to_string(value).expect("string serialization"),
Value::Array(values) => format!(
"[{}]",
values
.iter()
.map(stable_stringify)
.collect::<Vec<_>>()
.join(",")
),
Value::Object(values) => {
let mut entries = values.iter().collect::<Vec<_>>();
entries.sort_by(|(left, _), (right, _)| left.cmp(right));
format!(
"{{{}}}",
entries
.into_iter()
.map(|(key, value)| {
format!(
"{}:{}",
serde_json::to_string(key).expect("key serialization"),
stable_stringify(value)
)
})
.collect::<Vec<_>>()
.join(",")
)
}
}
}
pub fn builtin_schema_registry() -> Result<CultNetSchemaRegistry> {
let mut registry = CultNetSchemaRegistry::new();
for registration in [
schema_registration(
include_str!("../contracts/cultnet.hello.schema.json"),
CultNetSchemaKind::WireMessage,
vec![CultNetWireContract::CultNetSchemaV0],
Some("cultnet.hello.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.document-mutation-contract.schema.json"),
CultNetSchemaKind::SharedContract,
vec![CultNetWireContract::CultNetSchemaV0],
None,
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.transport-profile.schema.json"),
CultNetSchemaKind::SharedContract,
vec![CultNetWireContract::CultNetSchemaV0],
Some("cultnet.transport_profile.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.login.schema.json"),
CultNetSchemaKind::WireMessage,
vec![
CultNetWireContract::CultNetSchemaV0,
CultNetWireContract::GameCultNetworkingV0,
],
Some("cultnet.login.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.register.schema.json"),
CultNetSchemaKind::WireMessage,
vec![
CultNetWireContract::CultNetSchemaV0,
CultNetWireContract::GameCultNetworkingV0,
],
Some("cultnet.register.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.verify.schema.json"),
CultNetSchemaKind::WireMessage,
vec![
CultNetWireContract::CultNetSchemaV0,
CultNetWireContract::GameCultNetworkingV0,
],
Some("cultnet.verify.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.login-success.schema.json"),
CultNetSchemaKind::WireMessage,
vec![
CultNetWireContract::CultNetSchemaV0,
CultNetWireContract::GameCultNetworkingV0,
],
Some("cultnet.login_success.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.error.schema.json"),
CultNetSchemaKind::WireMessage,
vec![
CultNetWireContract::CultNetSchemaV0,
CultNetWireContract::GameCultNetworkingV0,
],
Some("cultnet.error.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.sample-change-name.schema.json"),
CultNetSchemaKind::WireMessage,
vec![
CultNetWireContract::CultNetSchemaV0,
CultNetWireContract::GameCultNetworkingV0,
],
Some("cultnet.sample.change_name.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.sample-chat.schema.json"),
CultNetSchemaKind::WireMessage,
vec![
CultNetWireContract::CultNetSchemaV0,
CultNetWireContract::GameCultNetworkingV0,
],
Some("cultnet.sample.chat.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.document-put.schema.json"),
CultNetSchemaKind::WireMessage,
vec![CultNetWireContract::CultNetSchemaV0],
Some("cultnet.document_put.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.document-delete.schema.json"),
CultNetSchemaKind::WireMessage,
vec![CultNetWireContract::CultNetSchemaV0],
Some("cultnet.document_delete.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.raw-document-record.schema.json"),
CultNetSchemaKind::SharedContract,
vec![CultNetWireContract::CultNetSchemaV0],
None,
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.document-put-raw.schema.json"),
CultNetSchemaKind::WireMessage,
vec![CultNetWireContract::CultNetSchemaV0],
Some("cultnet.document_put_raw.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.snapshot-request.schema.json"),
CultNetSchemaKind::WireMessage,
vec![CultNetWireContract::CultNetSchemaV0],
Some("cultnet.snapshot_request.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.snapshot-response.schema.json"),
CultNetSchemaKind::WireMessage,
vec![CultNetWireContract::CultNetSchemaV0],
Some("cultnet.snapshot_response.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.snapshot-response-raw.schema.json"),
CultNetSchemaKind::WireMessage,
vec![CultNetWireContract::CultNetSchemaV0],
Some("cultnet.snapshot_response_raw.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.schema-catalog-request.schema.json"),
CultNetSchemaKind::WireMessage,
vec![
CultNetWireContract::CultNetSchemaV0,
CultNetWireContract::GameCultNetworkingV0,
],
Some("cultnet.schema_catalog_request.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/cultnet.schema-catalog-response.schema.json"),
CultNetSchemaKind::WireMessage,
vec![
CultNetWireContract::CultNetSchemaV0,
CultNetWireContract::GameCultNetworkingV0,
],
Some("cultnet.schema_catalog_response.v0"),
None,
)?,
schema_registration(
include_str!("../contracts/ghostlight.agent-state.schema.json"),
CultNetSchemaKind::DocumentPayload,
vec![CultNetWireContract::CultNetSchemaV0],
Some("ghostlight.agent_state.v0"),
Some("ghostlight.agent-state"),
)?,
] {
registry.register(registration)?;
}
Ok(registry)
}
fn schema_registration(
schema_json: &str,
kind: CultNetSchemaKind,
wire_contracts: Vec<CultNetWireContract>,
schema_version: Option<&str>,
document_type: Option<&str>,
) -> Result<CultNetSchemaRegistration> {
let value: Value = serde_json::from_str(schema_json)?;
let schema_id = value
.get("$id")
.and_then(Value::as_str)
.ok_or_else(|| anyhow!("schema is missing $id"))?;
let title = value
.get("title")
.and_then(Value::as_str)
.map(str::to_string);
Ok(CultNetSchemaRegistration {
schema_id: schema_id.to_string(),
kind,
wire_contracts,
schema_version: schema_version.map(str::to_string),
document_type: document_type.map(str::to_string),
title,
schema_json: Some(schema_json.to_string()),
})
}

270
vendor/cultnet-rs/src/security.rs vendored Normal file
View file

@ -0,0 +1,270 @@
use aes_gcm::Aes256Gcm;
use aes_gcm::KeyInit;
use aes_gcm::Nonce;
use aes_gcm::aead::Aead;
use aes_gcm::aead::Payload;
use anyhow::Result;
use anyhow::anyhow;
use base64::Engine;
use base64::engine::general_purpose::URL_SAFE_NO_PAD;
use chrono::DateTime;
use chrono::TimeZone;
use chrono::Utc;
use hmac::Hmac;
use hmac::Mac;
use rand::RngCore;
use sha2::Digest;
use sha2::Sha256;
const NONCE_LENGTH: usize = 12;
type HmacSha256 = Hmac<Sha256>;
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CultNetClientSecurityOptions {
pub connection_key: String,
encryption_key: [u8; 32],
}
impl CultNetClientSecurityOptions {
pub fn new(connection_key: impl Into<String>) -> Result<Self> {
let connection_key = connection_key.into();
if connection_key.trim().is_empty() {
return Err(anyhow!("Connection key must be provided"));
}
let encryption_key = sha256(connection_key.as_bytes());
Ok(Self {
connection_key,
encryption_key,
})
}
pub fn development() -> Self {
Self::new("gamecult-dev-connection-key").expect("development key is valid")
}
pub fn encryption_key(&self) -> [u8; 32] {
self.encryption_key
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CultNetServerSecurityOptions {
client: CultNetClientSecurityOptions,
pub session_signing_secret: String,
session_signing_key: [u8; 32],
pub is_development: bool,
}
impl CultNetServerSecurityOptions {
pub fn new(
connection_key: impl Into<String>,
session_signing_secret: impl Into<String>,
is_development: bool,
) -> Result<Self> {
let session_signing_secret = session_signing_secret.into();
if session_signing_secret.trim().is_empty() {
return Err(anyhow!("Session signing secret must be provided"));
}
Ok(Self {
client: CultNetClientSecurityOptions::new(connection_key)?,
session_signing_key: sha256(session_signing_secret.as_bytes()),
session_signing_secret,
is_development,
})
}
pub fn development() -> Self {
Self::new(
"gamecult-dev-connection-key",
"gamecult-dev-session-signing-secret",
true,
)
.expect("development security config is valid")
}
pub fn to_client_options(&self) -> CultNetClientSecurityOptions {
self.client.clone()
}
pub fn encryption_key(&self) -> [u8; 32] {
self.client.encryption_key()
}
pub fn session_signing_key(&self) -> [u8; 32] {
self.session_signing_key
}
}
pub trait CultNetEncryptionOptions {
fn encryption_key(&self) -> [u8; 32];
}
impl CultNetEncryptionOptions for CultNetClientSecurityOptions {
fn encryption_key(&self) -> [u8; 32] {
self.encryption_key()
}
}
impl CultNetEncryptionOptions for CultNetServerSecurityOptions {
fn encryption_key(&self) -> [u8; 32] {
self.encryption_key()
}
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ValidatedCultNetSessionToken {
pub user_id: String,
pub expires_at_utc: DateTime<Utc>,
}
pub struct CultNetSecret;
impl CultNetSecret {
pub fn new_nonce() -> [u8; NONCE_LENGTH] {
let mut nonce = [0_u8; NONCE_LENGTH];
rand::rng().fill_bytes(&mut nonce);
nonce
}
pub fn encrypt_string(
input: Option<&str>,
nonce: &[u8],
options: &impl CultNetEncryptionOptions,
) -> Result<Option<Vec<u8>>> {
let Some(input) = input.filter(|value| !value.is_empty()) else {
return Ok(None);
};
Ok(Some(Self::encrypt_bytes(input.as_bytes(), nonce, options)?))
}
pub fn decrypt_string(
encrypted: Option<&[u8]>,
nonce: Option<&[u8]>,
options: &impl CultNetEncryptionOptions,
) -> Result<Option<String>> {
let (Some(encrypted), Some(nonce)) = (encrypted, nonce) else {
return Ok(None);
};
let bytes = Self::decrypt_bytes(encrypted, nonce, options)?;
Ok(Some(String::from_utf8(bytes)?))
}
pub fn encrypt_bytes(
input: &[u8],
nonce: &[u8],
options: &impl CultNetEncryptionOptions,
) -> Result<Vec<u8>> {
let nonce = validate_nonce(nonce)?;
let cipher = Aes256Gcm::new_from_slice(&options.encryption_key())?;
let encrypted = cipher
.encrypt(
Nonce::from_slice(nonce),
Payload {
msg: input,
aad: &[],
},
)
.map_err(|_| anyhow!("AES-GCM encryption failed"))?;
Ok(encrypted)
}
pub fn decrypt_bytes(
encrypted: &[u8],
nonce: &[u8],
options: &impl CultNetEncryptionOptions,
) -> Result<Vec<u8>> {
let nonce = validate_nonce(nonce)?;
let cipher = Aes256Gcm::new_from_slice(&options.encryption_key())?;
cipher
.decrypt(
Nonce::from_slice(nonce),
Payload {
msg: encrypted,
aad: &[],
},
)
.map_err(|_| anyhow!("AES-GCM decryption failed"))
}
pub fn create_session_token(
user_id: &str,
expires_at_utc: DateTime<Utc>,
options: &CultNetServerSecurityOptions,
) -> Result<String> {
let payload = format!("{}|{}", user_id, expires_at_utc.timestamp());
let signature = hmac_sha256(&options.session_signing_key(), payload.as_bytes())?;
Ok(format!(
"{}.{}",
URL_SAFE_NO_PAD.encode(payload.as_bytes()),
URL_SAFE_NO_PAD.encode(signature)
))
}
pub fn try_validate_session_token(
token: Option<&str>,
options: &CultNetServerSecurityOptions,
) -> Result<Option<ValidatedCultNetSessionToken>> {
let Some(token) = token.filter(|value| !value.trim().is_empty()) else {
return Ok(None);
};
let Some((payload_part, signature_part)) = token.split_once('.') else {
return Ok(None);
};
let payload = URL_SAFE_NO_PAD.decode(payload_part)?;
let signature = URL_SAFE_NO_PAD.decode(signature_part)?;
let expected = hmac_sha256(&options.session_signing_key(), &payload)?;
if !constant_time_eq(&signature, &expected) {
return Ok(None);
}
let payload = String::from_utf8(payload)?;
let Some((user_id, expires_at)) = payload.split_once('|') else {
return Ok(None);
};
let expires_at_seconds: i64 = expires_at.parse()?;
let Some(expires_at_utc) = Utc.timestamp_opt(expires_at_seconds, 0).single() else {
return Ok(None);
};
if expires_at_utc <= Utc::now() {
return Ok(None);
}
Ok(Some(ValidatedCultNetSessionToken {
user_id: user_id.to_string(),
expires_at_utc,
}))
}
pub fn to_base64_url(input: &[u8]) -> String {
URL_SAFE_NO_PAD.encode(input)
}
pub fn from_base64_url(input: &str) -> Result<Vec<u8>> {
Ok(URL_SAFE_NO_PAD.decode(input)?)
}
}
fn validate_nonce(nonce: &[u8]) -> Result<&[u8]> {
if nonce.len() != NONCE_LENGTH {
return Err(anyhow!("Invalid nonce"));
}
Ok(nonce)
}
fn sha256(input: &[u8]) -> [u8; 32] {
Sha256::digest(input).into()
}
fn hmac_sha256(key: &[u8], input: &[u8]) -> Result<Vec<u8>> {
let mut mac = <HmacSha256 as Mac>::new_from_slice(key)?;
mac.update(input);
Ok(mac.finalize().into_bytes().to_vec())
}
fn constant_time_eq(left: &[u8], right: &[u8]) -> bool {
if left.len() != right.len() {
return false;
}
left.iter()
.zip(right)
.fold(0_u8, |acc, (left, right)| acc | (left ^ right))
== 0
}

194
vendor/cultnet-rs/src/transport.rs vendored Normal file
View file

@ -0,0 +1,194 @@
use anyhow::Result;
use anyhow::anyhow;
use serde::Deserialize;
use serde::Serialize;
use std::io::Read;
use std::io::Write;
use crate::CultNetTransportChannel;
use crate::CultNetTransportDelivery;
use crate::CultNetTransportDescriptor;
use crate::CultNetTransportOrdering;
use crate::CultNetTransportProfile;
use crate::CultNetTransportProtocol;
use crate::FRAME_HEADER_BYTES;
use crate::encode_frame;
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct CultNetTransportStats {
pub bytes_received: u64,
pub bytes_sent: u64,
pub frames_received: u64,
pub frames_sent: u64,
pub reliable_packets_expired: u64,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct CultNetTransportFrame {
pub channel_id: String,
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,
pub base_delay_ms: u64,
pub max_delay_ms: u64,
pub max_jitter_ms: u64,
pub max_attempts: Option<u32>,
}
impl Default for CultNetReconnectPolicyOptions {
fn default() -> Self {
Self {
policy_id: "default".to_string(),
base_delay_ms: 1_000,
max_delay_ms: 30_000,
max_jitter_ms: 250,
max_attempts: None,
}
}
}
pub fn create_reconnect_policy(options: CultNetReconnectPolicyOptions) -> CultNetReconnectPolicy {
CultNetReconnectPolicy {
schema_version: "cultnet.reconnect_policy.v0".to_string(),
policy_id: if options.policy_id.trim().is_empty() {
"default".to_string()
} else {
options.policy_id
},
base_delay_ms: options.base_delay_ms,
max_delay_ms: options.max_delay_ms,
max_jitter_ms: options.max_jitter_ms,
max_attempts: options.max_attempts,
}
}
pub fn compute_reconnect_delay_ms(
policy: &CultNetReconnectPolicy,
attempt: u32,
jitter_ms: u64,
) -> u64 {
let normalized_attempt = attempt.max(1);
let multiplier = 2_u64.saturating_pow(normalized_attempt.saturating_sub(1));
let capped_base_delay = policy
.base_delay_ms
.saturating_mul(multiplier)
.min(policy.max_delay_ms);
capped_base_delay + jitter_ms.min(policy.max_jitter_ms)
}
#[derive(Clone, Debug, Default)]
pub struct TcpFramedTransportProfileOptions {
pub transport_id: Option<String>,
pub host: Option<String>,
pub port: Option<u16>,
pub max_payload_bytes: Option<u32>,
pub max_fragment_bytes: Option<u32>,
}
pub fn create_tcp_framed_transport_profile(
runtime_id: impl Into<String>,
options: TcpFramedTransportProfileOptions,
) -> CultNetTransportProfile {
CultNetTransportProfile {
schema_version: "cultnet.transport_profile.v0".to_string(),
runtime_id: runtime_id.into(),
transports: vec![CultNetTransportDescriptor {
transport_id: options
.transport_id
.unwrap_or_else(|| "tcp-framed".to_string()),
protocol: CultNetTransportProtocol::TcpFramed,
host: options.host,
port: options.port,
path: None,
discovery_group: None,
wire_contracts: Some(vec!["cultnet.schema.v0".to_string()]),
channels: vec![CultNetTransportChannel {
channel_id: "schema".to_string(),
delivery: CultNetTransportDelivery::Reliable,
ordering: CultNetTransportOrdering::Ordered,
max_payload_bytes: options.max_payload_bytes,
max_fragment_bytes: options.max_fragment_bytes,
max_pending_reliable_packets: None,
reliable_expire_after_ms: None,
}],
}],
}
}
pub struct TcpFramedTransportConnection<TStream> {
stream: TStream,
pub profile: CultNetTransportProfile,
stats: CultNetTransportStats,
}
impl<TStream> TcpFramedTransportConnection<TStream> {
pub fn new(stream: TStream, profile: CultNetTransportProfile) -> Self {
Self {
stream,
profile,
stats: CultNetTransportStats::default(),
}
}
pub fn stats(&self) -> CultNetTransportStats {
self.stats.clone()
}
pub fn into_inner(self) -> TStream {
self.stream
}
}
impl<TStream> TcpFramedTransportConnection<TStream>
where
TStream: Write,
{
pub fn send(&mut self, channel_id: &str, payload: &[u8]) -> Result<()> {
if channel_id != "schema" {
return Err(anyhow!(
"tcp_framed transport only supports the schema channel, got {channel_id:?}"
));
}
let frame = encode_frame(payload)?;
self.stream.write_all(&frame)?;
self.stream.flush()?;
self.stats.bytes_sent += frame.len() as u64;
self.stats.frames_sent += 1;
Ok(())
}
}
impl<TStream> TcpFramedTransportConnection<TStream>
where
TStream: Read,
{
pub fn receive(&mut self) -> Result<CultNetTransportFrame> {
let mut header = [0_u8; FRAME_HEADER_BYTES];
self.stream.read_exact(&mut header)?;
let payload_len = u32::from_be_bytes(header) as usize;
let mut payload = vec![0_u8; payload_len];
self.stream.read_exact(&mut payload)?;
self.stats.bytes_received += (FRAME_HEADER_BYTES + payload_len) as u64;
self.stats.frames_received += 1;
Ok(CultNetTransportFrame {
channel_id: "schema".to_string(),
payload,
})
}
}

1352
vendor/cultnet-rs/tests/cultnet.rs vendored Normal file

File diff suppressed because it is too large Load diff

Binary file not shown.

Binary file not shown.