actr-framework 0.3.1

Actor-RTC framework core (stub for code generation testing)
Documentation 
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

//! MessageDispatcher trait - Message routing and dispatching

use actr_protocol::{ActorResult, RpcEnvelope};
use async_trait::async_trait;
use bytes::Bytes;

use crate::{Context, Workload};

/// MessageDispatcher - Message dispatcher interface
///
/// Responsible for routing incoming message envelopes to corresponding handler methods.
///
/// # Design Characteristics
///
/// - **Static routing**: Implemented via compile-time match statements, no runtime lookup overhead
/// - **Zero-sized type (ZST)**: Router itself occupies no memory
/// - **Code generation**: Implementation is auto-generated by `actr-cli` codegen
///
/// # Code Generation Example
///
/// ```rust,ignore
/// // Generated by code generator
/// pub struct EchoServiceRouter<T: EchoServiceHandler>(PhantomData<T>);
///
/// #[async_trait]
/// impl<T: EchoServiceHandler> MessageDispatcher for EchoServiceRouter<T> {
///     type Workload = EchoServiceWorkload<T>;
///
///     async fn dispatch<C: Context>(
///         workload: &Self::Workload,
///         envelope: RpcEnvelope,
///         ctx: &C,
///     ) -> ActorResult<Bytes> {
///         match envelope.route_key.as_str() {
///             "echo.EchoService.Echo" => {
///                 let req = EchoRequest::decode(&*envelope.payload)?;
///                 let resp = workload.0.echo(req, ctx).await?;
///                 Ok(resp.encode_to_vec().into())
///             }
///             _ => Err(ProtocolError::Actr(ActrError::UnknownRoute {
///                 route_key: envelope.route_key.to_string()
///             }))
///         }
///     }
/// }
/// ```
// Same cross-target rationale as `Context` / `Workload`: `?Send` on wasm32,
// native default `Send` auto trait elsewhere. `MaybeSendSync` silently
// re-adds `Send + Sync` on native.
#[cfg_attr(not(target_arch = "wasm32"), async_trait)]
#[cfg_attr(target_arch = "wasm32", async_trait(?Send))]
pub trait MessageDispatcher: crate::MaybeSendSync + 'static {
    /// Associated Workload type
    type Workload: Workload<Dispatcher = Self>;

    /// Dispatch message to corresponding handler method and execute full request-response cycle
    ///
    /// # Responsibilities
    ///
    /// 1. **Routing**: Select handler method based on `envelope.route_key`
    /// 2. **Decoding**: Deserialize payload into concrete message type
    /// 3. **Dispatching**: Invoke workload's business logic method
    /// 4. **Encoding**: Serialize response into bytes
    ///
    /// # Parameters
    ///
    /// - `workload`: Workload instance (contains user business logic)
    /// - `envelope`: Message envelope (contains route_key and payload)
    /// - `ctx`: Execution context (generic, supports any Context implementation)
    ///
    /// # Returns
    ///
    /// Returns serialized response bytes
    async fn dispatch<C: Context>(
        workload: &Self::Workload,
        envelope: RpcEnvelope,
        ctx: &C,
    ) -> ActorResult<Bytes>;
}