oxide_core

oxide_core is the Rust-side engine for Oxide. It provides the primitives for:

Defining reducers (Reducer)
Owning state in an engine (ReducerEngine)
Streaming revisioned snapshots (StateSnapshot<T>)
Optional persistence helpers (feature-gated)

This crate is intentionally usage-agnostic. For end-to-end Rust ↔ Flutter wiring, see the repository examples and the root README.

Add It To Your Crate

In your Cargo.toml:

[dependencies]
oxide_core = "0.1.0"

When working inside this repository, use a combined version + path dependency (Cargo prefers path locally, while published crates resolve by version):

oxide_core = { version = "0.1.0", path = "../rust/oxide_core" }

Core Concepts

Reducer

Reducers are stateful controllers that mutate state in response to actions and side-effects:

use oxide_core::{CoreResult, Reducer, StateChange};

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CounterState {
  pub value: u64,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CounterAction {
  Inc,
}

pub enum CounterSideEffect {}

#[derive(Default)]
pub struct CounterReducer;
impl Reducer for CounterReducer {
  type State = CounterState;
  type Action = CounterAction;
  type SideEffect = CounterSideEffect;

  fn init(
    &mut self,
    _sideeffect_tx: oxide_core::tokio::sync::mpsc::UnboundedSender<Self::SideEffect>,
  ) {}

  fn reduce(&mut self, state: &mut Self::State, action: Self::Action) -> CoreResult<StateChange> {
    match action {
      CounterAction::Inc => state.value = state.value.saturating_add(1),
    }
    Ok(StateChange::FullUpdate)
  }

  fn effect(
    &mut self,
    _state: &mut Self::State,
    _effect: Self::SideEffect,
  ) -> CoreResult<StateChange> {
    Ok(StateChange::None)
  }
}

ReducerEngine

ReducerEngine<R> is the async-safe facade for dispatching actions and observing snapshots:

use oxide_core::ReducerEngine;

# use oxide_core::{CoreResult, Reducer, StateChange};
# use oxide_core::tokio::sync::mpsc;
# #[derive(Debug, Clone, PartialEq, Eq)]
# pub struct CounterState {
#   pub value: u64,
# }
# #[derive(Debug, Clone, PartialEq, Eq)]
# pub enum CounterAction {
#   Inc,
# }
# pub enum CounterSideEffect {}
# #[derive(Default)]
# pub struct CounterReducer;
# impl Reducer for CounterReducer {
#   type State = CounterState;
#   type Action = CounterAction;
#   type SideEffect = CounterSideEffect;
#
#   fn init(&mut self, _sideeffect_tx: mpsc::UnboundedSender<Self::SideEffect>) {}
#
#   fn reduce(&mut self, state: &mut Self::State, action: Self::Action) -> CoreResult<StateChange> {
#     match action {
#       CounterAction::Inc => state.value = state.value.saturating_add(1),
#     }
#     Ok(StateChange::FullUpdate)
#   }
#
#   fn effect(
#     &mut self,
#     _state: &mut Self::State,
#     _effect: Self::SideEffect,
#   ) -> CoreResult<StateChange> {
#     Ok(StateChange::None)
#   }
# }
let runtime = tokio::runtime::Runtime::new().unwrap();
runtime.block_on(async {
  let engine = ReducerEngine::<CounterReducer>::new(
    CounterReducer::default(),
    CounterState { value: 0 },
  );
  let snap = engine.dispatch(CounterAction::Inc).await.unwrap();
  let current = engine.current().await;
  assert_eq!(snap.revision, current.revision);
});

Async Runtime Behavior

ReducerEngine starts an internal async loop to process side-effects. Engine creation is safe even when there is no ambient Tokio runtime (for example, when entered from a synchronous FFI boundary):

If a Tokio runtime is currently available, Oxide spawns tasks onto it.
Otherwise, when built with the default frb-spawn feature, Oxide uses Flutter Rust Bridge’s cross-platform spawn helper.
If frb-spawn is disabled, Oxide falls back to an internal global Tokio runtime for background work.

In a normal Rust binary, the simplest approach is to run inside a Tokio runtime:

use oxide_core::ReducerEngine;

#[tokio::main(flavor = "multi_thread")]
async fn main() {
  let engine = ReducerEngine::<CounterReducer>::new(CounterReducer::default(), CounterState { value: 0 });
  let _ = engine.dispatch(CounterAction::Inc).await.unwrap();
}

Invariant: No Partial Mutation On Error

Dispatch uses clone-first semantics:

The current state is cloned.
The reducer runs against the clone.
If the reducer returns StateChange::None, the clone is discarded and no snapshot is emitted.
If the reducer returns an error, the live state is not updated and no snapshot is emitted.

This makes it safe to write reducers as normal &mut State code while preserving strong error semantics.

Feature Flags

frb-spawn (default): enables FRB’s spawn helper for cross-platform task spawning
state-persistence: enables bincode encode/decode helpers in oxide_core::persistence
persistence-json: adds JSON encode/decode helpers (requires state-persistence)
full: enables all persistence features

Commands

From rust/:

cargo test

To run benches (if enabled for your environment):

cargo bench

License

Dual-licensed under MIT OR Apache-2.0. See LICENSE.

oxide_core 0.1.0