Skip to main content

ash_fsm/
lib.rs

1//! # ash-fsm
2//!
3//! A configurable, trait-based finite state machine library for Rust, inspired by
4//! [AshStateMachine](https://hexdocs.pm/ash_state_machine/api-reference.html).
5//!
6//! ## Design
7//!
8//! - **Traits first** — define your machine by implementing [`StateMachine`] on
9//!   any struct. The trait provides all transition logic as default methods.
10//! - **Declarative transitions** — describe allowed `(action, from → to)` triples
11//!   in [`StateMachineConfig`]. Wildcards (`*`) cover any action or any state.
12//! - **History** — every successful transition is recorded as a
13//!   [`TransitionRecord`] in a bounded ring buffer (default 100 entries,
14//!   configurable per machine).
15//! - **Serialization** — the `serde` feature (on by default) lets you round-trip
16//!   history and config through any serde-compatible format.
17//!
18//! ## Quick start
19//!
20//! ```rust
21//! use ash_fsm::{State, StateMachine};
22//! use ash_fsm::config::StateMachineConfig;
23//! use ash_fsm::transition::{Transition, TransitionRecord};
24//!
25//! // 1. Define your state enum.
26//! #[derive(Debug, Clone, PartialEq, Eq, Hash)]
27//! enum OrderState { Pending, Active, Shipped, Closed }
28//! impl State for OrderState {}
29//!
30//! // 2. Define your domain struct.
31//! struct Order {
32//!     state: OrderState,
33//!     history: Vec<TransitionRecord<OrderState>>,
34//! }
35//!
36//! // 3. Implement the trait.
37//! impl StateMachine for Order {
38//!     type State = OrderState;
39//!
40//!     fn config() -> StateMachineConfig<OrderState> {
41//!         StateMachineConfig::new(OrderState::Pending)
42//!             .transitions(vec![
43//!                 Transition::new("activate")
44//!                     .from(vec![OrderState::Pending])
45//!                     .to(vec![OrderState::Active]),
46//!                 Transition::new("ship")
47//!                     .from(vec![OrderState::Active])
48//!                     .to(vec![OrderState::Shipped]),
49//!                 // Close is allowed from any state.
50//!                 Transition::new("close")
51//!                     .from_any()
52//!                     .to(vec![OrderState::Closed]),
53//!             ])
54//!     }
55//!
56//!     fn current_state(&self) -> &OrderState { &self.state }
57//!     fn set_state(&mut self, s: OrderState) { self.state = s; }
58//!     fn history(&self) -> &[TransitionRecord<OrderState>] { &self.history }
59//!     fn history_mut(&mut self) -> &mut Vec<TransitionRecord<OrderState>> { &mut self.history }
60//! }
61//!
62//! // 4. Use it.
63//! let mut order = Order { state: OrderState::Pending, history: Vec::new() };
64//! order.validate_initial_state().unwrap();
65//! order.transition("activate", OrderState::Active).unwrap();
66//! order.transition("ship", OrderState::Shipped).unwrap();
67//! assert_eq!(order.history().len(), 2);
68//! assert_eq!(order.current_state(), &OrderState::Shipped);
69//!
70//! // Invalid transition returns an error and leaves state unchanged.
71//! let err = order.transition("activate", OrderState::Active);
72//! assert!(err.is_err());
73//! ```
74
75pub mod config;
76pub mod error;
77pub mod machine;
78pub mod shared;
79pub mod state;
80pub mod transition;
81
82// ── top-level re-exports ──────────────────────────────────────────────────────
83
84pub use config::StateMachineConfig;
85pub use error::FsmError;
86pub use machine::StateMachine;
87pub use shared::SharedMachine;
88pub use state::State;
89pub use transition::{Transition, TransitionEndpoint, TransitionRecord};
90
91#[cfg(feature = "async")]
92pub use shared::AsyncMachine;
93
94/// Convenient glob import: `use ash_fsm::prelude::*;`
95pub mod prelude {
96    #[cfg(feature = "async")]
97    pub use crate::AsyncMachine;
98    pub use crate::{
99        FsmError, SharedMachine, State, StateMachine, StateMachineConfig, Transition,
100        TransitionEndpoint, TransitionRecord,
101    };
102}
103
104// ── tests ─────────────────────────────────────────────────────────────────────
105
106#[cfg(test)]
107mod tests {
108    use super::*;
109    use crate::config::DEFAULT_HISTORY_LIMIT;
110
111    // ── helpers ───────────────────────────────────────────────────────────────
112
113    #[derive(Debug, Clone, PartialEq, Eq, Hash)]
114    enum TicketState {
115        Received,
116        NeedsMoreInfo,
117        InProgress,
118        Resolved,
119        Closed,
120        Archived,
121    }
122
123    impl State for TicketState {}
124
125    struct Ticket {
126        state: TicketState,
127        history: Vec<TransitionRecord<TicketState>>,
128    }
129
130    impl Ticket {
131        fn new() -> Self {
132            Self {
133                state: TicketState::Received,
134                history: Vec::new(),
135            }
136        }
137    }
138
139    impl StateMachine for Ticket {
140        type State = TicketState;
141
142        fn config() -> StateMachineConfig<TicketState> {
143            StateMachineConfig::new(TicketState::Received)
144                .initial_states(vec![TicketState::Received])
145                .deprecated_states(vec![TicketState::Archived])
146                .transitions(vec![
147                    Transition::new("request_info")
148                        .from(vec![TicketState::Received, TicketState::InProgress])
149                        .to(vec![TicketState::NeedsMoreInfo]),
150                    Transition::new("start")
151                        .from(vec![TicketState::Received, TicketState::NeedsMoreInfo])
152                        .to(vec![TicketState::InProgress]),
153                    Transition::new("resolve")
154                        .from(vec![TicketState::InProgress])
155                        .to(vec![TicketState::Resolved]),
156                    // close is allowed from any state
157                    Transition::new("close")
158                        .from_any()
159                        .to(vec![TicketState::Closed]),
160                ])
161        }
162
163        fn current_state(&self) -> &TicketState {
164            &self.state
165        }
166        fn set_state(&mut self, s: TicketState) {
167            self.state = s;
168        }
169        fn history(&self) -> &[TransitionRecord<TicketState>] {
170            &self.history
171        }
172        fn history_mut(&mut self) -> &mut Vec<TransitionRecord<TicketState>> {
173            &mut self.history
174        }
175    }
176
177    // ── transition tests ──────────────────────────────────────────────────────
178
179    #[test]
180    fn valid_transition_succeeds() {
181        let mut t = Ticket::new();
182        t.transition("start", TicketState::InProgress).unwrap();
183        assert_eq!(t.current_state(), &TicketState::InProgress);
184    }
185
186    #[test]
187    fn invalid_transition_returns_error() {
188        let mut t = Ticket::new();
189        let err = t.transition("resolve", TicketState::Resolved);
190        assert!(matches!(err, Err(FsmError::NoMatchingTransition { .. })));
191        // State is unchanged
192        assert_eq!(t.current_state(), &TicketState::Received);
193    }
194
195    #[test]
196    fn wildcard_from_allows_close_from_any_state() {
197        let mut t = Ticket::new();
198        t.transition("close", TicketState::Closed).unwrap();
199        assert_eq!(t.current_state(), &TicketState::Closed);
200    }
201
202    // ── history tests ─────────────────────────────────────────────────────────
203
204    #[test]
205    fn history_records_transitions() {
206        let mut t = Ticket::new();
207        t.transition("start", TicketState::InProgress).unwrap();
208        t.transition("resolve", TicketState::Resolved).unwrap();
209
210        assert_eq!(t.history().len(), 2);
211        assert_eq!(t.history()[0].from, TicketState::Received);
212        assert_eq!(t.history()[0].to, TicketState::InProgress);
213        assert_eq!(t.history()[0].action, "start");
214        assert_eq!(t.history()[1].from, TicketState::InProgress);
215        assert_eq!(t.history()[1].to, TicketState::Resolved);
216    }
217
218    #[test]
219    fn history_evicts_oldest_at_limit() {
220        struct TinyMachine {
221            state: TicketState,
222            history: Vec<TransitionRecord<TicketState>>,
223        }
224        impl StateMachine for TinyMachine {
225            type State = TicketState;
226            fn config() -> StateMachineConfig<TicketState> {
227                StateMachineConfig::new(TicketState::Received)
228                    .history_limit(2)
229                    .transitions(vec![Transition::new("*").from_any().to_any()])
230            }
231            fn current_state(&self) -> &TicketState {
232                &self.state
233            }
234            fn set_state(&mut self, s: TicketState) {
235                self.state = s;
236            }
237            fn history(&self) -> &[TransitionRecord<TicketState>] {
238                &self.history
239            }
240            fn history_mut(&mut self) -> &mut Vec<TransitionRecord<TicketState>> {
241                &mut self.history
242            }
243        }
244
245        let mut m = TinyMachine {
246            state: TicketState::Received,
247            history: Vec::new(),
248        };
249        m.transition("*", TicketState::InProgress).unwrap();
250        m.transition("*", TicketState::Resolved).unwrap();
251        m.transition("*", TicketState::Closed).unwrap(); // should evict first
252
253        assert_eq!(m.history().len(), 2);
254        assert_eq!(m.history()[0].from, TicketState::InProgress);
255    }
256
257    // ── validation tests ──────────────────────────────────────────────────────
258
259    #[test]
260    fn validate_initial_state_ok() {
261        let t = Ticket::new();
262        t.validate_initial_state().unwrap();
263    }
264
265    #[test]
266    fn validate_initial_state_err_for_invalid() {
267        let t = Ticket {
268            state: TicketState::Resolved,
269            history: Vec::new(),
270        };
271        let err = t.validate_initial_state();
272        assert!(matches!(err, Err(FsmError::InvalidInitialState { .. })));
273    }
274
275    // ── introspection tests ───────────────────────────────────────────────────
276
277    #[test]
278    fn possible_next_states_from_received() {
279        let t = Ticket::new();
280        let mut next = t.possible_next_states();
281        next.sort_by(|a, b| format!("{a:?}").cmp(&format!("{b:?}")));
282        // From Received: can go to NeedsMoreInfo (via request_info), InProgress (via start), Closed (via close)
283        assert!(next.contains(&TicketState::NeedsMoreInfo));
284        assert!(next.contains(&TicketState::InProgress));
285        assert!(next.contains(&TicketState::Closed));
286    }
287
288    #[test]
289    fn possible_next_states_for_action() {
290        let t = Ticket::new();
291        let next = t.possible_next_states_for_action("close");
292        assert_eq!(next, vec![TicketState::Closed]);
293    }
294
295    #[test]
296    fn can_transition_predicate() {
297        let t = Ticket::new();
298        assert!(t.can_transition("start", &TicketState::InProgress));
299        assert!(!t.can_transition("resolve", &TicketState::Resolved));
300    }
301
302    #[test]
303    fn all_states_includes_deprecated() {
304        let all = Ticket::all_states();
305        assert!(all.contains(&TicketState::Archived));
306    }
307
308    #[test]
309    fn active_states_excludes_deprecated() {
310        let active = Ticket::active_states();
311        assert!(!active.contains(&TicketState::Archived));
312    }
313
314    #[test]
315    fn default_history_limit_is_100() {
316        assert_eq!(DEFAULT_HISTORY_LIMIT, 100);
317        let config = Ticket::config();
318        assert_eq!(config.history_limit, 100);
319    }
320
321    // ── shared / async tests ──────────────────────────────────────────────────
322
323    mod shared_tests {
324        use super::*;
325        use crate::shared::SharedMachine;
326        use std::thread;
327
328        fn make_shared() -> SharedMachine<Ticket> {
329            SharedMachine::new(Ticket::new())
330        }
331
332        #[test]
333        fn shared_machine_transitions() {
334            let m = make_shared();
335            m.transition("start", TicketState::InProgress).unwrap();
336            assert_eq!(m.current_state(), TicketState::InProgress);
337        }
338
339        #[test]
340        fn shared_machine_invalid_transition_returns_error() {
341            let m = make_shared();
342            let err = m.transition("resolve", TicketState::Resolved);
343            assert!(matches!(err, Err(FsmError::NoMatchingTransition { .. })));
344            assert_eq!(m.current_state(), TicketState::Received);
345        }
346
347        #[test]
348        fn shared_machine_history_snapshot() {
349            let m = make_shared();
350            m.transition("start", TicketState::InProgress).unwrap();
351            let history = m.history();
352            assert_eq!(history.len(), 1);
353            assert_eq!(history[0].action, "start");
354        }
355
356        #[test]
357        fn shared_machine_send_across_threads() {
358            let m = make_shared();
359            let handle = m.clone();
360            let t = thread::spawn(move || {
361                handle.transition("start", TicketState::InProgress).unwrap();
362            });
363            t.join().unwrap();
364            assert_eq!(m.current_state(), TicketState::InProgress);
365        }
366
367        #[test]
368        fn shared_machine_concurrent_read() {
369            let m = make_shared();
370            m.transition("start", TicketState::InProgress).unwrap();
371
372            let handles: Vec<_> = (0..4)
373                .map(|_| {
374                    let clone = m.clone();
375                    thread::spawn(move || clone.current_state())
376                })
377                .collect();
378
379            for h in handles {
380                assert_eq!(h.join().unwrap(), TicketState::InProgress);
381            }
382        }
383
384        #[test]
385        fn shared_machine_with_closure() {
386            let m = make_shared();
387            let result = m.with(|inner| {
388                inner.transition("start", TicketState::InProgress).unwrap();
389                inner.history().len()
390            });
391            assert_eq!(result, 1);
392        }
393
394        #[cfg(feature = "async")]
395        mod async_tests {
396            use super::*;
397            use crate::shared::AsyncMachine;
398
399            fn make_async() -> AsyncMachine<Ticket> {
400                AsyncMachine::new(Ticket::new())
401            }
402
403            #[tokio::test]
404            async fn async_machine_transitions() {
405                let m = make_async();
406                m.transition("start", TicketState::InProgress)
407                    .await
408                    .unwrap();
409                assert_eq!(m.current_state().await, TicketState::InProgress);
410            }
411
412            #[tokio::test]
413            async fn async_machine_invalid_transition() {
414                let m = make_async();
415                let err = m.transition("resolve", TicketState::Resolved).await;
416                assert!(matches!(err, Err(FsmError::NoMatchingTransition { .. })));
417            }
418
419            #[tokio::test]
420            async fn async_machine_history() {
421                let m = make_async();
422                m.transition("start", TicketState::InProgress)
423                    .await
424                    .unwrap();
425                let hist = m.history().await;
426                assert_eq!(hist.len(), 1);
427                assert_eq!(hist[0].action, "start");
428            }
429
430            #[tokio::test]
431            async fn async_machine_send_across_tasks() {
432                let m = make_async();
433                let handle = m.clone();
434                tokio::spawn(async move {
435                    handle
436                        .transition("start", TicketState::InProgress)
437                        .await
438                        .unwrap();
439                })
440                .await
441                .unwrap();
442                assert_eq!(m.current_state().await, TicketState::InProgress);
443            }
444
445            #[tokio::test]
446            async fn async_machine_with_closure() {
447                let m = make_async();
448                let result = m
449                    .with(|inner| {
450                        inner.transition("start", TicketState::InProgress).unwrap();
451                        inner.history().len()
452                    })
453                    .await;
454                assert_eq!(result, 1);
455            }
456        }
457    }
458
459    #[cfg(feature = "serde")]
460    mod serde_tests {
461        use super::*;
462
463        #[derive(Debug, Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
464        enum SimpleState {
465            A,
466            B,
467            C,
468        }
469        impl State for SimpleState {}
470
471        struct SimpleMachine {
472            state: SimpleState,
473            history: Vec<TransitionRecord<SimpleState>>,
474        }
475        impl StateMachine for SimpleMachine {
476            type State = SimpleState;
477            fn config() -> StateMachineConfig<SimpleState> {
478                StateMachineConfig::new(SimpleState::A).transitions(vec![
479                    Transition::new("go")
480                        .from(vec![SimpleState::A])
481                        .to(vec![SimpleState::B]),
482                    Transition::new("go")
483                        .from(vec![SimpleState::B])
484                        .to(vec![SimpleState::C]),
485                ])
486            }
487            fn current_state(&self) -> &SimpleState {
488                &self.state
489            }
490            fn set_state(&mut self, s: SimpleState) {
491                self.state = s;
492            }
493            fn history(&self) -> &[TransitionRecord<SimpleState>] {
494                &self.history
495            }
496            fn history_mut(&mut self) -> &mut Vec<TransitionRecord<SimpleState>> {
497                &mut self.history
498            }
499        }
500
501        #[test]
502        fn history_serializes_and_deserializes() {
503            let mut m = SimpleMachine {
504                state: SimpleState::A,
505                history: Vec::new(),
506            };
507            m.transition("go", SimpleState::B).unwrap();
508            m.transition("go", SimpleState::C).unwrap();
509
510            let json = m.serialize_history().unwrap();
511            assert!(json.contains("\"from\":\"A\""));
512
513            let mut m2 = SimpleMachine {
514                state: SimpleState::C,
515                history: Vec::new(),
516            };
517            m2.deserialize_history(&json).unwrap();
518            assert_eq!(m2.history().len(), 2);
519            assert_eq!(m2.history()[0].from, SimpleState::A);
520            assert_eq!(m2.history()[1].from, SimpleState::B);
521        }
522
523        #[test]
524        fn config_serializes() {
525            let config = SimpleMachine::config();
526            let json = serde_json::to_string(&config).unwrap();
527            assert!(json.contains("initial_states"));
528            assert!(json.contains("transitions"));
529        }
530    }
531}