hyperlane_core/hook/
trait.rs

1use super::*;
2
3/// A generic trait for functions that take a `Context` and return a value.
4///
5/// This trait encapsulates the common behavior of being a sendable, synchronous
6/// function that accepts a `Context`. It is used as a base for other, more
7/// specific function traits.
8pub trait FnContext<R>: Fn(&mut Context) -> R + Send + Sync {}
9
10/// A trait for functions that return a pinned, boxed, sendable future.
11///
12/// This trait is essential for creating type-erased async function pointers,
13/// which is a common pattern for storing and dynamically dispatching different
14/// asynchronous handlers in a collection.
15pub trait FnContextPinBox<T>: FnContext<FutureBox<T>> {}
16
17/// A trait for static, sendable, synchronous functions that return a future.
18///
19/// This trait ensures that a hook function is safe to be sent across threads
20/// and has a static lifetime, making it suitable for use in long-lived components
21/// of the application, such as the main router.
22pub trait FnContextStatic<Fut, T>: FnContext<Fut> + 'static
23where
24    Fut: Future<Output = T> + Send,
25{
26}
27
28/// A trait for futures that are sendable and have a static lifetime.
29///
30/// This marker trait simplifies generic bounds for asynchronous operations, ensuring
31///   that futures can be safely managed by the async runtime without lifetime issues.
32pub trait FutureSendStatic<T>: Future<Output = T> + Send + 'static {}
33
34/// A trait for `Send`-able futures with a generic output.
35///
36/// This trait is used for asynchronous operations that need to be sendable across threads,
37/// such as in the server's request processing pipeline.
38pub trait FutureSend<T>: Future<Output = T> + Send {}
39
40/// A trait for thread-safe, reference-counted closures that produce a boxed future.
41///
42/// This trait is used for storing and executing asynchronous operations that need to be
43/// sendable across threads, such as in the server's request processing pipeline.
44pub trait FutureFn<T>: Fn() -> FutureBox<T> + Send + Sync {}
45
46/// Trait for server lifecycle hooks that process requests.
47///
48/// `ServerHook` provides a unified interface for different types of request processing
49/// handlers in the server lifecycle, including route handlers, middleware, and panic hooks.
50/// All hooks follow the same pattern: instantiation via `new` and execution via `handle`.
51///
52/// This trait is designed to work with the server's request processing pipeline, where
53/// each hook receives the `Context` directly for both initialization and processing.
54pub trait ServerHook: Send + Sync + 'static {
55    /// Creates a new instance of this hook from the context.
56    ///
57    /// This method is called by the framework to instantiate the hook,
58    /// passing in the `Context` directly.
59    ///
60    /// # Arguments
61    ///
62    /// - `&mut Stream` - The stream object providing server configuration and state
63    /// - `&mut Context` - The request context containing all request/response data.
64    ///
65    /// # Returns
66    ///
67    /// A future that resolves to a new instance of this hook.
68    fn new(stream: &mut Stream, ctx: &mut Context) -> impl Future<Output = Self> + Send;
69
70    /// Executes the hook's processing logic.
71    ///
72    /// This method contains the actual logic for processing the request.
73    /// It receives the `Context` as a parameter for accessing request/response data.
74    ///
75    /// # Arguments
76    ///
77    /// - `&mut Stream` - The stream object providing server configuration and state
78    /// - `&mut Context` - The request context for accessing request/response data.
79    ///
80    /// # Returns
81    ///
82    /// - `Status` - `Status::Continue` if the pipeline should proceed, `Status::Reject` if the pipeline should be aborted.
83    fn handle(self, stream: &mut Stream, ctx: &mut Context) -> impl Future<Output = Status> + Send;
84}
hyperlane_core/hook/trait.rs

hyperlane_core/hook/
trait.rs
