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 on_start(), on_stop() hooks               │
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 service_handler;
127mod workload;
128
129// Optional utilities module
130pub mod util;
131
132// Guest-side runtime module (WASM and dynclib ABI)
133pub mod guest;
134
135// Web-target (`wasm32-unknown-unknown`) runtime glue. Compiled only when
136// the `web` feature is enabled on a wasm32 build — see `src/web/mod.rs`
137// for the target / feature gating rationale.
138#[cfg(all(target_arch = "wasm32", feature = "web"))]
139pub mod web;
140
141// Test helpers (lightweight Context implementation)
142// Only compiled under the test-utils feature (includes uuid v4, incompatible with wasm32 target)
143#[cfg(feature = "test-utils")]
144pub mod test_support;
145
146// Public re-exports
147pub use context::{Context, LogLevel, MaybeSendSync, MediaSample, MediaType};
148pub use dest::Dest;
149pub use dispatcher::MessageDispatcher;
150pub use service_handler::ServiceHandler;
151pub use workload::{
152    BackpressureEvent, CredentialEvent, ErrorCategory, ErrorEvent, PeerEvent, Workload,
153};
154
155// Re-export commonly used types for user convenience
156pub use bytes::Bytes;
157
158// Re-export async_trait to avoid users having to add it as a dependency
159pub use async_trait::async_trait;
160
161// Re-export DataStream from protocol
162pub use actr_protocol::DataStream;
163
164// Re-export backoff utilities
165pub use util::backoff::{BackoffBuilder, ExponentialBackoff};
actr_framework/lib.rs

actr_framework/
lib.rs
