monolake-core 0.3.0

MonoLake Core Abstraction and Utils
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

//! HTTP handling traits and types for asynchronous services.
//!
//! This module provides traits and types for implementing HTTP handlers
//! that can be used with asynchronous services. It defines a common interface
//! for processing HTTP requests and generating responses, with support for
//! connection management and context-aware handling.
//!
//! # Key Components
//!
//! - [`HttpHandler`]: A trait for implementing HTTP request handlers.
//! - [`ResponseWithContinue`]: A type alias for responses that indicate whether to continue
//!   processing the connection.
//! - [`HttpAccept`]: A type alias for connection acceptance information.
//!
//! # Usage
//!
//! The `HttpHandler` trait is automatically implemented for types
//! that implement the [`Service`] trait with
//! request type `(Request<B>, CX)` and return type
//! [`ResponseWithContinue`].
use std::future::Future;

use http::{Request, Response};
use service_async::Service;

use crate::sealed::SealedT;

/// A tuple representing an HTTP response along with a connection continuation flag.
///
/// # Type Parameters
///
/// - `B`: The body type of the response.
///
/// # Fields
///
/// - `Response<B>`: The HTTP response.
/// - `bool`: A flag indicating whether to continue processing the connection.
///   - `true`: Continue processing the connection.
///   - `false`: Close the connection after sending the response.
///
/// Note: The service does not need to add the `Connection: close` header itself;
/// this is handled by the HTTP core service based on this flag.
pub type ResponseWithContinue<B> = (Response<B>, bool);

/// A tuple representing an accepted HTTP connection with its context.
///
/// # Type Parameters
///
/// - `Stream`: The type of the I/O stream for the connection.
/// - `CX`: The type of the connection context, typically a `certain_map`.
///
/// # Fields
///
/// - `bool`: Indicates whether the connection is using HTTP/2.
///   - `true`: The connection is using HTTP/2.
///   - `false`: The connection is using HTTP/1.x.
/// - `Stream`: The I/O stream for the connection.
/// - `CX`: The context of the connection, providing additional information or state.
pub type HttpAccept<Stream, CX> = (bool, Stream, CX);

struct HttpSeal;

/// A trait for HTTP request handlers.
///
/// This trait defines the interface for processing HTTP requests and generating responses.
/// It is designed to work with asynchronous services and supports context-aware handling.
///
/// Implementors of this trait can process HTTP requests and return responses along with
/// a boolean flag indicating whether to continue processing the connection.
///
/// # Type Parameters
///
/// - `CX`: The context type for additional request processing information.
/// - `B`: The body type of the incoming request.
///
/// # Associated Types
///
/// - `Body`: The body type of the outgoing response.
/// - `Error`: The error type that may occur during request handling.
///
/// # Examples
///
/// ```ignore
/// use your_crate::{HttpHandler, ResponseWithContinue};
/// use http::{Request, Response};
///
/// struct MyHandler;
///
/// impl HttpHandler<(), Vec<u8>> for MyHandler {
///     type Body = Vec<u8>;
///     type Error = std::io::Error;
///
///     async fn handle(&self, request: Request<Vec<u8>>, ctx: ())
///         -> Result<ResponseWithContinue<Self::Body>, Self::Error> {
///         // Process the request and generate a response
///         let response = Response::new(Vec::new());
///         Ok((response, true))
///     }
/// }
/// ```
///
/// The [`HttpHandler`] trait is automatically implemented for types
/// that implement the [`Service`] trait with
/// request type `(Request<B>, CX)` and return type
/// [`ResponseWithContinue`].
#[allow(private_bounds)]
pub trait HttpHandler<CX, B>: SealedT<HttpSeal, (CX, B)> {
    type Body;
    type Error;

    fn handle(
        &self,
        request: Request<B>,
        ctx: CX,
    ) -> impl Future<Output = Result<ResponseWithContinue<Self::Body>, Self::Error>>;
}

impl<T, CX, IB, OB> SealedT<HttpSeal, (CX, IB)> for T where
    T: Service<(Request<IB>, CX), Response = ResponseWithContinue<OB>>
{
}

impl<T, CX, IB, OB> HttpHandler<CX, IB> for T
where
    T: Service<(Request<IB>, CX), Response = ResponseWithContinue<OB>>,
{
    type Body = OB;
    type Error = T::Error;

    async fn handle(
        &self,
        req: Request<IB>,
        ctx: CX,
    ) -> Result<ResponseWithContinue<OB>, Self::Error> {
        self.call((req, ctx)).await
    }
}