astrs_node_api/patterns/mod.rs
1//! Services, actions and streams (blueprint §9.4).
2//!
3//! > All three ride ordinary edges plus metadata correlation — no separate RPC
4//! > subsystem: services (`request_id`), actions (`goal_id`/`goal_status` FSM:
5//! > Accepted→Executing→{Succeeded, Aborted, Canceled}), streams
6//! > (`session_id`/`segment_id`/`seq`/`fin`/`flush`).
7//!
8//! That sentence is the whole design. There is no service socket, no action
9//! server, no stream channel — there are edges, and there is
10//! [`astrs_wire::Metadata`]. What this module adds is the bookkeeping that
11//! makes the three patterns *correct* rather than merely expressible:
12//!
13//! | Pattern | What is easy to get wrong | What this module does |
14//! |---|---|---|
15//! | [`service`] | Answering with the wrong (or no) `request_id` | [`ServiceRequest`] carries the id; the response helper copies it |
16//! | [`action`] | An illegal FSM transition, or a status after a terminal one | [`GoalTracker`] refuses both |
17//! | [`stream`] | Gaps, reordering, a segment that never ends | [`StreamAssembler`] detects all three |
18//!
19//! # Eviction immunity comes for free
20//!
21//! A message carrying `request_id`, `goal_id` or `goal_status` is
22//! eviction-immune in every input queue (§11.2), because
23//! [`astrs_wire::Metadata::is_correlated`] says so and
24//! [`crate::events::QueuedEvent`] forwards that to the scheduler. So a service
25//! response cannot be the message a full queue drops — which is the one drop
26//! that would wedge a client forever.
27
28pub mod action;
29pub mod service;
30pub mod stream;
31
32pub use action::{ActionOutcome, GoalId, GoalTracker};
33pub use service::{RequestId, ServiceRequest, ServiceResponse};
34pub use stream::{ChunkRef, StreamAssembler, StreamSegment, StreamWriter};
35
36/// A fresh, unique correlation id.
37///
38/// UUIDv7, so ids sort by creation time — which makes a log of correlated
39/// messages readable in the order they happened without a separate timestamp
40/// column.
41#[must_use]
42pub fn fresh_id() -> String {
43 uuid::Uuid::now_v7().to_string()
44}
45
46#[cfg(test)]
47mod tests {
48 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
49
50 use super::*;
51
52 #[test]
53 fn fresh_ids_are_unique_and_time_ordered() {
54 let first = fresh_id();
55 let second = fresh_id();
56 assert_ne!(first, second);
57 assert!(first <= second, "v7 ids sort by creation time");
58 assert_eq!(first.len(), 36, "canonical hyphenated form");
59 }
60}