hyperlane 20.0.2

use crate::*;

/// A generic trait for functions that take a `Context` and return a value.
///
/// This trait encapsulates the common behavior of being a sendable, synchronous
/// function that accepts a `Context`. It is used as a base for other, more
/// specific function traits.
pub trait FnContext<R>: Fn(&mut Context) -> R + Send + Sync {}

/// A trait for functions that return a pinned, boxed, sendable future.
///
/// This trait is essential for creating type-erased async function pointers,
/// which is a common pattern for storing and dynamically dispatching different
/// asynchronous handlers in a collection.
pub trait FnContextPinBox<T>: FnContext<FutureBox<T>> {}

/// A trait for static, sendable, synchronous functions that return a future.
///
/// This trait ensures that a hook function is safe to be sent across threads
/// and has a static lifetime, making it suitable for use in long-lived components
/// of the application, such as the main router.
pub trait FnContextStatic<Fut, T>: FnContext<Fut> + 'static
where
    Fut: Future<Output = T> + Send,
{
}

/// A trait for futures that are sendable and have a static lifetime.
///
/// This marker trait simplifies generic bounds for asynchronous operations, ensuring
///   that futures can be safely managed by the async runtime without lifetime issues.
pub trait FutureSendStatic<T>: Future<Output = T> + Send + 'static {}

/// A trait for `Send`-able futures with a generic output.
///
/// This trait is used for asynchronous operations that need to be sendable across threads,
/// such as in the server's request processing pipeline.
pub trait FutureSend<T>: Future<Output = T> + Send {}

/// A trait for thread-safe, reference-counted closures that produce a boxed future.
///
/// This trait is used for storing and executing asynchronous operations that need to be
/// sendable across threads, such as in the server's request processing pipeline.
pub trait FutureFn<T>: Fn() -> FutureBox<T> + Send + Sync {}

/// Trait for server lifecycle hooks that process requests.
///
/// `ServerHook` provides a unified interface for different types of request processing
/// handlers in the server lifecycle, including route handlers, middleware, and panic hooks.
/// All hooks follow the same pattern: instantiation via `new` and execution via `handle`.
///
/// This trait is designed to work with the server's request processing pipeline, where
/// each hook receives the `Context` directly for both initialization and processing.
pub trait ServerHook: Send + Sync + 'static {
    /// Creates a new instance of this hook from the context.
    ///
    /// This method is called by the framework to instantiate the hook,
    /// passing in the `Context` directly.
    ///
    /// # Arguments
    ///
    /// - `&mut Context` - The request context containing all request/response data.
    ///
    /// # Returns
    ///
    /// A future that resolves to a new instance of this hook.
    fn new(ctx: &mut Context) -> impl Future<Output = Self> + Send;

    /// Executes the hook's processing logic.
    ///
    /// This method contains the actual logic for processing the request.
    /// It receives the `Context` as a parameter for accessing request/response data.
    ///
    /// # Arguments
    ///
    /// - `&mut Context` - The request context for accessing request/response data.
    ///
    /// # Returns
    ///
    /// A future that resolves when the processing is complete.
    fn handle(self, ctx: &mut Context) -> impl Future<Output = ()> + Send;
}