webx_core/
mediator.rs

1//! Mediator traits: IMediator, IRequest, IEventRequest.
2
3pub mod default;
4pub mod dispatch;
5pub mod pipeline;
6pub use default::Mediator;
7pub use dispatch::dispatch;
8pub use pipeline::build_chain as build_pipeline_chain;
9
10use crate::error::Result;
11
12/// Marker trait for a request (command or query) carrying a structured response `TResponse`.
13///
14/// The HTTP adapter serializes `TResponse` as JSON, so it must implement
15/// [`serde::Serialize`] — unless it is [`crate::route::scan::ResponseData`],
16/// the raw-response envelope used for file downloads and other responses that
17/// control their own status, headers and body. That is why this trait itself
18/// only requires `Send`: the `Serialize` bound is enforced where the value is
19/// actually serialized.
20///
21/// - `TResponse: Serialize` → framework writes JSON and sets status 200
22/// - `TResponse = ()`        → framework writes no body and sets status 204
23/// - `TResponse = ResponseData` → the handler builds the whole response
24///
25/// ```ignore
26/// impl IRequest<UserModel> for GetUserRequest {}
27/// impl IRequest<()> for DeleteUserRequest {}
28/// impl IRequest<ResponseData> for DownloadFileRequest {}
29/// ```
30pub trait IRequest<TResponse>: Send + 'static
31where
32    TResponse: Send + 'static,
33{
34}
35
36/// Marker trait for an event (notification) that does not produce a response.
37///
38/// Use `IEventRequest` for fire-and-forget notifications.
39///
40/// ```ignore
41/// impl IEventRequest for UserCreatedEvent {}
42/// ```
43pub trait IEventRequest: Clone + Send + 'static {}
44
45/// The mediator dispatches requests to their handlers and publishes events
46/// to all registered handlers.
47///
48/// Analogous to MediatR's IMediator.
49///
50/// # Object safety
51///
52/// The trait is dyn-compatible for callers that only need type-erased dispatch:
53/// the generic `send`/`publish` methods require `Self: Sized`, while
54/// [`IMediator::send_boxed`] takes/returns `Box<dyn Any + Send>` and is the one
55/// available on `dyn IMediator`:
56///
57/// ```ignore
58/// let mediator: Arc<dyn IMediator> = Arc::new(Mediator::new(provider));
59/// let response = mediator.send_boxed(Box::new(CreateOrderRequest { .. })).await?;
60/// let order = *response.downcast::<OrderView>().expect("typed response");
61/// ```
62#[async_trait::async_trait]
63pub trait IMediator: Send + Sync {
64    /// Send a request and return its structured response.
65    async fn send<T, R>(&self, req: T) -> Result<R>
66    where
67        T: IRequest<R> + Send + 'static,
68        R: Send + 'static,
69        Self: Sized;
70
71    /// Send a type-erased request and return a type-erased response.
72    ///
73    /// Works through `Arc<dyn IMediator>`: the request's `TypeId` is looked up
74    /// in the handler registry and the generated boxed dispatch downcasts it,
75    /// runs the same pipeline + handler path as [`IMediator::send`], and boxes
76    /// the response for the caller to downcast.
77    async fn send_boxed(
78        &self,
79        req: Box<dyn std::any::Any + Send>,
80    ) -> Result<Box<dyn std::any::Any + Send>>;
81
82    /// Publish an event to all registered handlers.
83    ///
84    /// Stays generic (not available on `dyn IMediator`): event handlers are
85    /// resolved from DI by their concrete `IEventHandler<T>` type.
86    async fn publish<T: IEventRequest>(&self, event: T) -> Result<()>
87    where
88        Self: Sized;
89}
webx_core/mediator.rs

webx_core/
mediator.rs
