actr_framework/
lib.rs

1//! # actr-framework
2//!
3//! Actor-RTC core programming interface layer - defines the contract for user-framework interaction.
4//!
5//! ## Architectural Positioning
6//!
7//! `actr-framework` is the **SDK interface layer** of the actr system, positioned in the middle tier:
8//!
9//! ```text
10//! User Application (Workload implementation)
11//!        ↓ depends on
12//! actr-framework (this crate)  ← Stable API contract (trait definitions only)
13//!        ↓ depends on
14//! actr-protocol                ← Data type definitions
15//!        ↑ implements
16//! actr-runtime                 ← Runtime implementation (implements Context trait)
17//! ```
18//!
19//! ## Core Responsibilities
20//!
21//! 1. **Define user programming interface**: `Workload`, `MessageDispatcher` traits
22//! 2. **Define execution context interface**: `Context` trait (implemented by runtime)
23//! 3. **Type-safe RPC**: `Context::call()` and `Context::tell()` methods
24//! 4. **Lifecycle management**: `on_start`, `on_stop` hooks
25//!
26//! ## Design Principles
27//!
28//! ### 1. Interface-only, Zero Implementation
29//!
30//! ```rust,ignore
31//! // ✅ Framework defines
32//! pub trait Context {
33//!     async fn call<R: RpcRequest>(...) -> ActorResult<R::Response>;
34//! }
35//!
36//! // ✅ Runtime implements
37//! impl Context for RuntimeContext { ... }
38//! ```
39//!
40//! Framework **contains no implementation code**, all logic is in runtime.
41//!
42//! ### 2. Dependency Inversion Principle
43//!
44//! - Framework defines traits, Runtime implements traits
45//! - User code only depends on framework, not runtime
46//! - Context trait can be mocked for unit testing
47//!
48//! ### 3. Zero-Cost Abstraction
49//!
50//! - Use generics instead of trait objects (`<C: Context>` not `&dyn Context`)
51//! - Compile-time monomorphization, static dispatch
52//! - Compiler can fully inline the entire call chain
53//! - Zero virtual function call overhead
54//!
55//! ## Core Type System
56//!
57//! ### 4-Trait Architecture
58//!
59//! actr builds a type-safe message handling system with 4 traits:
60//!
61//! ```text
62//! ┌─────────────────────────────────────────────────────────┐
63//! │ 1. RpcRequest trait (actr-protocol)                     │
64//! │    - Associates Request and Response types              │
65//! │    - Provides route_key() static method                 │
66//! └─────────────────────────────────────────────────────────┘
67//!                         ↓ used by
68//! ┌─────────────────────────────────────────────────────────┐
69//! │ 2. Concrete Handler trait (code generated)             │
70//! │    - e.g., EchoServiceHandler<C: Context>               │
71//! │    - async fn echo<C: Context>(&self, req, ctx: &C)     │
72//! └─────────────────────────────────────────────────────────┘
73//!                         ↓ wrapped by
74//! ┌─────────────────────────────────────────────────────────┐
75//! │ 3. MessageDispatcher trait (this crate)                 │
76//! │    - Static routing: route_key → handler method         │
77//! │    - Zero-sized type (ZST), zero runtime overhead       │
78//! └─────────────────────────────────────────────────────────┘
79//!                         ↓ associated with
80//! ┌─────────────────────────────────────────────────────────┐
81//! │ 4. Workload trait (this crate)                          │
82//! │    - Associates Dispatcher type                         │
83//! │    - Provides actor_type(), on_start(), on_stop()       │
84//! └─────────────────────────────────────────────────────────┘
85//! ```
86//!
87//! ## Usage Example
88//!
89//! ```rust,ignore
90//! use actr_framework::{Context, Workload};
91//!
92//! // Code-generated Handler trait
93//! #[async_trait]
94//! pub trait EchoServiceHandler: Send + Sync + 'static {
95//!     async fn echo<C: Context>(
96//!         &self,
97//!         req: EchoRequest,
98//!         ctx: &C,
99//!     ) -> ActorResult<EchoResponse>;
100//! }
101//!
102//! // User implements business logic
103//! impl EchoServiceHandler for MyService {
104//!     async fn echo<C: Context>(
105//!         &self,
106//!         req: EchoRequest,
107//!         ctx: &C,
108//!     ) -> ActorResult<EchoResponse> {
109//!         // Access context data
110//!         tracing::info!("trace_id: {}", ctx.trace_id());
111//!
112//!         // Type-safe RPC call
113//!         let response = ctx.call(&target, another_request).await?;
114//!
115//!         Ok(EchoResponse {
116//!             reply: format!("Echo: {}", req.message),
117//!         })
118//!     }
119//! }
120//! ```
121
122// Module declarations
123mod context;
124mod dest;
125mod dispatcher;
126mod workload;
127
128// Optional utilities module
129pub mod util;
130
131// Test helpers (lightweight Context implementation)
132pub mod test_support;
133
134// Public re-exports
135pub use context::{Context, MediaSample, MediaType};
136pub use dest::Dest;
137pub use dispatcher::MessageDispatcher;
138pub use workload::Workload;
139
140// Re-export commonly used types for user convenience
141pub use bytes::Bytes;
142
143// Re-export async_trait to avoid users having to add it as a dependency
144pub use async_trait::async_trait;
145
146// Re-export DataStream from protocol
147pub use actr_protocol::DataStream;
actr_framework/lib.rs

actr_framework/
lib.rs
