1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
//! Worker-side actor runtime.
//!
//! Actors are durable, keyed virtual objects. Each key has at most one writer at a time,
//! and its state lives on the Orcher server rather than in the worker.
//!
//! ## Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────┐
//! │ WORKER - USER CODE │
//! │ ┌────────────────────────────────────────────────┐ │
//! │ │ #[actor] │ │
//! │ │ pub struct ShoppingCart; │ │
//! │ │ │ │
//! │ │ #[operations] │ │
//! │ │ impl ShoppingCart { │ │
//! │ │ #[operation(exclusive)] │ │
//! │ │ async fn add_item(ctx, item) { ... } │ │
//! │ │ } │ │
//! │ │ │ │
//! │ │ Handlers execute here │ │
//! │ └────────────────────────────────────────────────┘ │
//! │ │
//! │ Worker::builder() │
//! │ .build().await? │
//! │ .run().await │
//! └─────────────────────────────────────────────────────┘
//! │
//! │ RPC (state access + operation execution)
//! ▼
//! ┌─────────────────────────────────────────────────────┐
//! │ SERVER - COORDINATOR │
//! │ ┌────────────────────────────────────────────────┐ │
//! │ │ Routes operations to workers │ │
//! │ │ Enforces single writer per key │ │
//! │ │ Persists state │ │
//! │ │ Does not execute handlers │ │
//! │ └────────────────────────────────────────────────┘ │
//! └─────────────────────────────────────────────────────┘
//! ```
//!
//! ## Key concepts
//!
//! - **Actor**: a stateful entity identified by a key. Each instance owns its own state.
//! - **Exclusive operation**: runs serialized per key and may read and write state.
//! - **Shared operation**: runs concurrently with other shared operations on the same
//! key, and may only read state; writes are refused. An exclusive operation waits
//! for running shared ones, then runs alone.
//! - **State**: scoped by key as `actor:{actor_name}:{key}:{state_key}`, read and written
//! over RPC, and persisted by the server. The worker may cache it locally.
//!
//! ## Example
//!
//! ```rust
//! use orcher_sdk::prelude::*;
//!
//! #[derive(Clone, Serialize, Deserialize)]
//! pub struct Item {
//! name: String,
//! price_cents: u64,
//! quantity: u32,
//! }
//!
//! // Define an actor.
//! #[actor(name = "ShoppingCart")]
//! pub struct ShoppingCart;
//!
//! // Implement its operations.
//! #[operations]
//! impl ShoppingCart {
//! #[operation(exclusive)]
//! pub async fn add_item(ctx: ActorContext, item: Item) -> Result<Vec<Item>> {
//! let mut items = ctx
//! .state()
//! .get::<Vec<Item>>("cart")
//! .await?
//! .unwrap_or_default();
//!
//! items.push(item);
//! ctx.state().set("cart", &items).await?;
//!
//! Ok(items)
//! }
//!
//! #[operation(shared)]
//! pub async fn total_cents(ctx: SharedActorContext) -> Result<u64> {
//! let items = ctx
//! .state()
//! .get::<Vec<Item>>("cart")
//! .await?
//! .unwrap_or_default();
//!
//! Ok(items.iter().map(|i| i.price_cents * u64::from(i.quantity)).sum())
//! }
//! }
//!
//! // A worker built in the same binary registers the actor automatically. Any
//! // process calls it through a client, by key:
//! async fn add_to_cart(client: &Client) -> Result<u64> {
//! let cart = client.actor::<ShoppingCart>("user-123");
//! let item = Item { name: "tea".to_string(), price_cents: 450, quantity: 2 };
//! cart.add_item(item).await?;
//! cart.total_cents().await
//! }
//! ```
//!
//! ## Modules
//!
//! - [`context`]: the handler contexts, [`ActorContext`] and [`SharedActorContext`].
//! - [`definition`]: static actor definitions collected for auto-registration.
//! - [`executor`]: [`ActorExecutor`], the handler registry and dispatcher.
//! - [`invocation`]: [`ActorInvocationClient`], for calling operations on other actors.
//! - [`state`]: state access; [`state::client`] reads and writes through the worker
//! host, [`state::manager`] is the typed API handlers use.
//! - [`testing`]: helpers for unit-testing handlers without a server.
//! - [`types`]: core types such as [`ActorKey`] and [`OperationMode`].
pub use ;
pub use ;
pub use ActorInvocationClient;
pub use ;
pub use ;
pub use ;
// Implemented by the `#[actor]` and `#[operations]` macros.
pub use ;
pub use ;
/// The most commonly used actor types, for glob import.
///
/// ```rust
/// use orcher_sdk::actor::prelude::*;
/// ```