use std::collections::{BTreeMap, HashMap};
use std::sync::Arc;
use serde::ser::SerializeMap;
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use serde_json::{Map, Value};
use crate::error::{Result, RustyError};
type ChannelMap = BTreeMap<String, Arc<Value>>;
#[derive(Debug, Clone, Default, PartialEq)]
pub struct State {
inner: Arc<ChannelMap>,
}
impl Serialize for State {
fn serialize<S: Serializer>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error> {
let mut map = serializer.serialize_map(Some(self.inner.len()))?;
for (channel, value) in self.inner.iter() {
map.serialize_entry(channel, value.as_ref())?;
}
map.end()
}
}
impl<'de> Deserialize<'de> for State {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
Ok(Self::from_map(Map::<String, Value>::deserialize(
deserializer,
)?))
}
}
impl State {
pub fn new() -> Self {
Self::default()
}
pub fn from_map(inner: Map<String, Value>) -> Self {
Self {
inner: Arc::new(inner.into_iter().map(|(k, v)| (k, Arc::new(v))).collect()),
}
}
pub fn from_value(value: Value) -> Result<Self> {
match value {
Value::Object(inner) => Ok(Self::from_map(inner)),
other => Err(RustyError::InvalidUpdate(format!(
"state must be a JSON object, got {}",
json_type_name(&other)
))),
}
}
pub fn to_value(&self) -> Value {
Value::Object(
self.inner
.iter()
.map(|(k, v)| (k.clone(), v.as_ref().clone()))
.collect(),
)
}
pub fn into_map(self) -> Map<String, Value> {
match Arc::try_unwrap(self.inner) {
Ok(map) => map
.into_iter()
.map(|(k, v)| (k, Arc::unwrap_or_clone(v)))
.collect(),
Err(shared) => shared
.iter()
.map(|(k, v)| (k.clone(), v.as_ref().clone()))
.collect(),
}
}
pub fn iter(&self) -> impl Iterator<Item = (&str, &Value)> {
self.inner.iter().map(|(k, v)| (k.as_str(), v.as_ref()))
}
pub fn get(&self, channel: &str) -> Option<&Value> {
self.inner.get(channel).map(Arc::as_ref)
}
pub fn contains(&self, channel: &str) -> bool {
self.inner.contains_key(channel)
}
pub fn insert(&mut self, channel: impl Into<String>, value: Value) {
self.insert_shared(channel, Arc::new(value));
}
pub fn get_as<T: serde::de::DeserializeOwned>(&self, channel: &str) -> Result<Option<T>> {
match self.get(channel) {
None => Ok(None),
Some(v) => Ok(Some(T::deserialize(v)?)),
}
}
pub fn len(&self) -> usize {
self.inner.len()
}
pub fn is_empty(&self) -> bool {
self.inner.is_empty()
}
#[cfg(test)]
pub(crate) fn shared_channel(&self, channel: &str) -> Option<Arc<Value>> {
self.inner.get(channel).cloned()
}
pub(crate) fn shared_channels(&self) -> impl Iterator<Item = (&str, &Arc<Value>)> {
self.inner.iter().map(|(k, v)| (k.as_str(), v))
}
pub(crate) fn insert_shared(&mut self, channel: impl Into<String>, value: Arc<Value>) {
Arc::make_mut(&mut self.inner).insert(channel.into(), value);
}
pub(crate) fn from_shared_channels<I, S>(channels: I) -> Self
where
I: IntoIterator<Item = (S, Arc<Value>)>,
S: Into<String>,
{
Self {
inner: Arc::new(channels.into_iter().map(|(k, v)| (k.into(), v)).collect()),
}
}
pub(crate) fn channels_changed_since(&self, base: &State) -> Vec<(String, Arc<Value>)> {
self.shared_channels()
.filter(|(channel, value)| match base.inner.get(*channel) {
Some(base_value) if Arc::ptr_eq(value, base_value) => false,
Some(base_value) => value.as_ref() != base_value.as_ref(),
None => true,
})
.map(|(channel, value)| (channel.to_owned(), value.clone()))
.collect()
}
}
impl From<Map<String, Value>> for State {
fn from(inner: Map<String, Value>) -> Self {
Self::from_map(inner)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
pub enum Reducer {
#[default]
Overwrite,
Append,
DeepMerge,
AddMessages,
}
impl Reducer {
pub fn allows_multiple_writes(self) -> bool {
!matches!(self, Reducer::Overwrite)
}
pub fn apply(&self, current: Option<&Value>, update: Value) -> Value {
match self {
Reducer::Overwrite => update,
Reducer::Append => match current {
Some(Value::Array(existing)) => {
let mut out = existing.clone();
append_in_place(&mut out, update);
Value::Array(out)
}
_ => match update {
Value::Array(items) => Value::Array(items),
single => Value::Array(vec![single]),
},
},
Reducer::DeepMerge => match current {
Some(cur) => deep_merge(cur, &update),
None => update,
},
Reducer::AddMessages => add_messages(current, update),
}
}
pub(crate) fn apply_shared(&self, current: Option<Arc<Value>>, update: Value) -> Arc<Value> {
match self {
Reducer::Overwrite => Arc::new(update),
Reducer::Append => match current {
Some(mut shared) if shared.is_array() => match Arc::get_mut(&mut shared) {
Some(Value::Array(existing)) => {
append_in_place(existing, update);
shared
}
_ => {
let Value::Array(existing) = shared.as_ref() else {
unreachable!("guarded by is_array above")
};
let mut out = existing.clone();
append_in_place(&mut out, update);
Arc::new(Value::Array(out))
}
},
_ => Arc::new(match update {
Value::Array(items) => Value::Array(items),
single => Value::Array(vec![single]),
}),
},
Reducer::DeepMerge => match current {
Some(mut shared) => match Arc::get_mut(&mut shared) {
Some(current) => {
deep_merge_in_place(current, &update);
shared
}
None => Arc::new(deep_merge(shared.as_ref(), &update)),
},
None => Arc::new(update),
},
Reducer::AddMessages => match current {
Some(mut shared) if shared.is_array() => match Arc::get_mut(&mut shared) {
Some(Value::Array(messages)) => {
upsert_messages_in_place(messages, update);
shared
}
_ => {
let Value::Array(existing) = shared.as_ref() else {
unreachable!("guarded by is_array above")
};
let mut messages = existing.clone();
upsert_messages_in_place(&mut messages, update);
Arc::new(Value::Array(messages))
}
},
_ => Arc::new(add_messages(None, update)),
},
}
}
}
impl std::fmt::Display for Reducer {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let name = match self {
Reducer::Overwrite => "overwrite",
Reducer::Append => "append",
Reducer::DeepMerge => "deep_merge",
Reducer::AddMessages => "add_messages",
};
f.write_str(name)
}
}
fn json_type_name(v: &Value) -> &'static str {
match v {
Value::Null => "null",
Value::Bool(_) => "bool",
Value::Number(_) => "number",
Value::String(_) => "string",
Value::Array(_) => "array",
Value::Object(_) => "object",
}
}
fn deep_merge(a: &Value, b: &Value) -> Value {
let mut merged = a.clone();
deep_merge_in_place(&mut merged, b);
merged
}
fn deep_merge_in_place(a: &mut Value, b: &Value) {
match (&mut *a, b) {
(Value::Object(x), Value::Object(y)) => {
for (k, v) in y {
match x.get_mut(k) {
Some(cur) => deep_merge_in_place(cur, v),
None => {
x.insert(k.clone(), v.clone());
}
}
}
}
_ => *a = b.clone(),
}
}
fn append_in_place(existing: &mut Vec<Value>, update: Value) {
match update {
Value::Array(items) => existing.extend(items),
single => existing.push(single),
}
}
fn add_messages(current: Option<&Value>, update: Value) -> Value {
let mut messages: Vec<Value> = match current {
Some(Value::Array(existing)) => existing.clone(),
_ => Vec::new(),
};
upsert_messages_in_place(&mut messages, update);
Value::Array(messages)
}
fn upsert_messages_in_place(messages: &mut Vec<Value>, update: Value) {
let incoming: Vec<Value> = match update {
Value::Array(items) => items,
single => vec![single],
};
let mut index_of: HashMap<String, usize> = HashMap::with_capacity(messages.len());
for (i, m) in messages.iter().enumerate() {
if let Some(id) = m.get("id").and_then(Value::as_str) {
index_of.entry(id.to_owned()).or_insert(i);
}
}
for msg in incoming {
let msg_id = msg.get("id").and_then(Value::as_str).map(str::to_owned);
match msg_id.as_deref().and_then(|id| index_of.get(id).copied()) {
Some(i) => messages[i] = msg,
None => {
if let Some(id) = msg_id {
index_of.insert(id, messages.len());
}
messages.push(msg);
}
}
}
}
#[derive(Debug, Clone, Default)]
pub struct StateSpec {
channels: HashMap<String, Reducer>,
}
impl StateSpec {
pub fn new() -> Self {
Self::default()
}
pub fn channel(mut self, name: impl Into<String>, reducer: Reducer) -> Self {
self.channels.insert(name.into(), reducer);
self
}
pub fn add_channel(&mut self, name: impl Into<String>, reducer: Reducer) -> &mut Self {
self.channels.insert(name.into(), reducer);
self
}
pub fn reducer_for(&self, channel: &str) -> Reducer {
self.channels.get(channel).copied().unwrap_or_default()
}
pub fn try_reducer_for(&self, channel: &str) -> Option<Reducer> {
self.channels.get(channel).copied()
}
pub fn channel_names(&self) -> impl Iterator<Item = &str> {
self.channels.keys().map(String::as_str)
}
pub fn has_channel(&self, channel: &str) -> bool {
self.channels.contains_key(channel)
}
pub fn apply_super_step<I, S>(&self, state: &mut State, writes: I) -> Result<()>
where
I: IntoIterator<Item = (S, HashMap<String, Value>)>,
S: AsRef<str>,
{
let mut collected: Vec<(String, HashMap<String, Value>)> = writes
.into_iter()
.map(|(node, updates)| (node.as_ref().to_owned(), updates))
.collect();
collected.sort_by(|a, b| a.0.cmp(&b.0));
let mut write_counts: HashMap<&str, usize> = HashMap::new();
let mut first_writer: HashMap<&str, &str> = HashMap::new();
for (node, updates) in &collected {
for channel in updates.keys() {
let Some(reducer) = self.try_reducer_for(channel) else {
return Err(RustyError::InvalidUpdate(format!(
"node `{node}` wrote to undeclared channel `{channel}`; \
declare it in the StateSpec"
)));
};
if matches!(reducer, Reducer::Append | Reducer::AddMessages) {
if let Some(current) = state.get(channel) {
if !current.is_array() {
return Err(RustyError::InvalidUpdate(format!(
"node `{node}` wrote to channel `{channel}` (reducer: \
{reducer}), but the current value is a {}; the \
reducer requires an array",
json_type_name(current)
)));
}
}
}
let count = write_counts.entry(channel.as_str()).or_insert(0);
*count += 1;
first_writer
.entry(channel.as_str())
.or_insert(node.as_str());
if *count > 1 && !reducer.allows_multiple_writes() {
return Err(RustyError::InvalidUpdate(format!(
"channel `{channel}` can receive only one value per super-step \
(reducer: {reducer}); already written by node `{}`, second write from \
node `{node}`. Use a multi-write reducer (Append/DeepMerge/\
AddMessages) to handle concurrent writes.",
first_writer[channel.as_str()],
)));
}
}
}
for (_node, updates) in collected {
for (channel, update) in updates {
let reducer = self.reducer_for(&channel);
let current = Arc::make_mut(&mut state.inner).remove(&channel);
let merged = reducer.apply_shared(current, update);
state.insert_shared(channel, merged);
}
}
Ok(())
}
pub fn apply_single(
&self,
state: &mut State,
node: &str,
updates: HashMap<String, Value>,
) -> Result<()> {
self.apply_super_step(state, [(node, updates)])
}
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn updates(pairs: &[(&str, Value)]) -> HashMap<String, Value> {
pairs
.iter()
.map(|(k, v)| (k.to_string(), v.clone()))
.collect()
}
#[test]
fn overwrite_replaces() {
let mut state = State::new();
let spec = StateSpec::new().channel("x", Reducer::Overwrite);
spec.apply_single(&mut state, "n1", updates(&[("x", json!(1))]))
.unwrap();
spec.apply_single(&mut state, "n2", updates(&[("x", json!(2))]))
.unwrap();
assert_eq!(state.get("x"), Some(&json!(2)));
}
#[test]
fn last_value_double_write_fails() {
let mut state = State::new();
let spec = StateSpec::new().channel("x", Reducer::Overwrite);
let writes = vec![
("a".to_string(), updates(&[("x", json!(1))])),
("b".to_string(), updates(&[("x", json!(2))])),
];
let err = spec.apply_super_step(&mut state, writes).unwrap_err();
assert!(matches!(err, RustyError::InvalidUpdate(_)));
}
#[test]
fn append_allows_fan_in() {
let mut state = State::new();
let spec = StateSpec::new().channel("xs", Reducer::Append);
let writes = vec![
("a".to_string(), updates(&[("xs", json!([1, 2]))])),
("b".to_string(), updates(&[("xs", json!(3))])),
];
spec.apply_super_step(&mut state, writes).unwrap();
assert_eq!(state.get("xs"), Some(&json!([1, 2, 3])));
}
#[test]
fn deep_merge_is_recursive() {
let mut state = State::from_value(json!({"cfg": {"a": 1, "nested": {"x": 1}}})).unwrap();
let spec = StateSpec::new().channel("cfg", Reducer::DeepMerge);
spec.apply_single(
&mut state,
"n",
updates(&[("cfg", json!({"nested": {"y": 2}}))]),
)
.unwrap();
assert_eq!(
state.get("cfg"),
Some(&json!({"a": 1, "nested": {"x": 1, "y": 2}}))
);
}
#[test]
fn add_messages_upserts_by_id() {
let mut state = State::from_value(json!({
"messages": [{"id": "m1", "content": "old"}, {"content": "plain"}]
}))
.unwrap();
let spec = StateSpec::new().channel("messages", Reducer::AddMessages);
spec.apply_single(
&mut state,
"n",
updates(&[(
"messages",
json!([
{"id": "m1", "content": "new"},
{"content": "appended"}
]),
)]),
)
.unwrap();
assert_eq!(
state.get("messages"),
Some(&json!([
{"id": "m1", "content": "new"},
{"content": "plain"},
{"content": "appended"}
]))
);
}
#[test]
fn undeclared_channel_rejected() {
let mut state = State::new();
let spec = StateSpec::new().channel("x", Reducer::Overwrite);
let err = spec
.apply_single(&mut state, "n", updates(&[("y", json!(1))]))
.unwrap_err();
assert!(matches!(err, RustyError::InvalidUpdate(_)));
}
#[test]
fn fan_in_merge_order_is_deterministic() {
let spec = StateSpec::new()
.channel("xs", Reducer::Append)
.channel("messages", Reducer::AddMessages);
let forward = vec![
(
"b".to_string(),
updates(&[("xs", json!([2])), ("messages", json!({"id": "b", "v": 2}))]),
),
(
"a".to_string(),
updates(&[("xs", json!([1])), ("messages", json!({"id": "a", "v": 1}))]),
),
];
let mut reversed = forward.clone();
reversed.reverse();
let mut s1 = State::new();
let mut s2 = State::new();
spec.apply_super_step(&mut s1, forward).unwrap();
spec.apply_super_step(&mut s2, reversed).unwrap();
assert_eq!(s1, s2);
assert_eq!(s1.get("xs"), Some(&json!([1, 2])));
assert_eq!(
s1.get("messages"),
Some(&json!([{"id": "a", "v": 1}, {"id": "b", "v": 2}]))
);
}
#[test]
fn append_rejects_non_array_current_value() {
let mut state = State::from_value(json!({"xs": {"oops": "object"}})).unwrap();
let spec = StateSpec::new().channel("xs", Reducer::Append);
let err = spec
.apply_single(&mut state, "n", updates(&[("xs", json!([1]))]))
.unwrap_err();
assert!(matches!(err, RustyError::InvalidUpdate(_)));
assert_eq!(state.get("xs"), Some(&json!({"oops": "object"})));
}
#[test]
fn add_messages_rejects_non_array_current_value() {
let mut state = State::from_value(json!({"messages": 42})).unwrap();
let spec = StateSpec::new().channel("messages", Reducer::AddMessages);
let err = spec
.apply_single(
&mut state,
"n",
updates(&[("messages", json!({"id": "m1"}))]),
)
.unwrap_err();
assert!(matches!(err, RustyError::InvalidUpdate(_)));
assert_eq!(state.get("messages"), Some(&json!(42)));
}
#[test]
fn clone_shares_channels_until_write() {
let mut state = State::from_value(json!({"a": [1, 2, 3], "b": {"x": 1}})).unwrap();
let snapshot = state.clone();
for channel in ["a", "b"] {
assert!(Arc::ptr_eq(
&state.shared_channel(channel).unwrap(),
&snapshot.shared_channel(channel).unwrap()
));
}
state.insert("a", json!([9]));
assert!(!Arc::ptr_eq(
&state.shared_channel("a").unwrap(),
&snapshot.shared_channel("a").unwrap()
));
assert!(Arc::ptr_eq(
&state.shared_channel("b").unwrap(),
&snapshot.shared_channel("b").unwrap()
));
assert_eq!(snapshot.get("a"), Some(&json!([1, 2, 3])));
assert_eq!(state.get("a"), Some(&json!([9])));
}
#[test]
fn reducer_merge_is_copy_on_write_at_channel_granularity() {
let spec = StateSpec::new()
.channel("xs", Reducer::Append)
.channel("ys", Reducer::Append);
let mut state = State::from_value(json!({"xs": [1], "ys": ["keep"]})).unwrap();
let snapshot = state.clone();
spec.apply_single(&mut state, "n", updates(&[("xs", json!(2))]))
.unwrap();
assert_eq!(state.get("xs"), Some(&json!([1, 2])));
assert_eq!(snapshot.get("xs"), Some(&json!([1])));
assert!(Arc::ptr_eq(
&state.shared_channel("ys").unwrap(),
&snapshot.shared_channel("ys").unwrap()
));
}
#[test]
fn append_mutates_in_place_when_uniquely_owned() {
let spec = StateSpec::new().channel("xs", Reducer::Append);
let mut state = State::from_value(json!({"xs": [1]})).unwrap();
let before = Arc::as_ptr(&state.shared_channel("xs").unwrap());
spec.apply_single(&mut state, "n", updates(&[("xs", json!(2))]))
.unwrap();
assert_eq!(state.get("xs"), Some(&json!([1, 2])));
assert_eq!(before, Arc::as_ptr(&state.shared_channel("xs").unwrap()));
}
#[test]
fn deep_merge_mutates_in_place_when_uniquely_owned() {
let spec = StateSpec::new().channel("cfg", Reducer::DeepMerge);
let mut state = State::from_value(json!({"cfg": {"a": 1, "nested": {"x": 1}}})).unwrap();
let before = Arc::as_ptr(&state.shared_channel("cfg").unwrap());
spec.apply_single(
&mut state,
"n",
updates(&[("cfg", json!({"nested": {"y": 2}}))]),
)
.unwrap();
assert_eq!(
state.get("cfg"),
Some(&json!({"a": 1, "nested": {"x": 1, "y": 2}}))
);
assert_eq!(before, Arc::as_ptr(&state.shared_channel("cfg").unwrap()));
}
#[test]
fn serde_is_byte_identical_to_plain_map() {
let state = State::from_value(json!({
"blob": "payload",
"meta": {"kind": "test", "n": 42},
"list": [1, 2.5, null, true]
}))
.unwrap();
let plain = state.to_value();
assert_eq!(
serde_json::to_string(&state).unwrap(),
serde_json::to_string(&plain).unwrap()
);
assert_eq!(
serde_json::to_string_pretty(&state).unwrap(),
serde_json::to_string_pretty(&plain).unwrap()
);
let from_state_json: State =
serde_json::from_str(&serde_json::to_string(&state).unwrap()).unwrap();
let from_value_json: State = serde_json::from_value(plain).unwrap();
assert_eq!(state, from_state_json);
assert_eq!(state, from_value_json);
}
#[test]
fn into_map_and_iter_round_trip() {
let state = State::from_value(json!({"a": 1, "b": [2]})).unwrap();
let iterated: HashMap<String, Value> = state
.iter()
.map(|(k, v)| (k.to_owned(), v.clone()))
.collect();
assert_eq!(iterated["a"], json!(1));
assert_eq!(iterated["b"], json!([2]));
let snapshot = state.clone();
let map = state.into_map();
assert_eq!(map["a"], json!(1));
assert_eq!(snapshot.get("b"), Some(&json!([2])));
}
#[test]
fn channels_changed_since_diffs_by_pointer_then_value() {
let base =
State::from_value(json!({"same": 1, "changed": [1], "gone_from_delta": true})).unwrap();
let mut next = base.clone();
next.insert("changed", json!([1, 2]));
next.insert("new", json!("hello"));
next.insert("same", json!(1));
let delta = next.channels_changed_since(&base);
let names: Vec<&str> = delta.iter().map(|(k, _)| k.as_str()).collect();
assert_eq!(names, ["changed", "new"]);
assert_eq!(next.channels_changed_since(&State::new()).len(), 4);
}
}