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

webx_core/
mediator.rs
