Skip to main content

hyperlane_core/server/
impl.rs

1use super::*;
2
3/// Provides a default implementation for Server.
4impl Default for Server {
5    /// Creates a new Server instance with default values.
6    ///
7    /// # Returns
8    ///
9    /// - `Self` - A new instance with default configuration.
10    #[inline(always)]
11    fn default() -> Self {
12        Self {
13            server_config: ServerConfig::default(),
14            request_config: RequestConfig::default(),
15            task_panic: Vec::new(),
16            request_error: Vec::new(),
17            route_matcher: RouteMatcher::new(),
18            request_middleware: Vec::new(),
19            response_middleware: Vec::new(),
20        }
21    }
22}
23
24/// Implements the `PartialEq` trait for `Server`.
25///
26/// This allows for comparing two `Server` instances for equality.
27impl PartialEq for Server {
28    /// Checks if two `Server` instances are equal.
29    ///
30    /// # Arguments
31    ///
32    /// - `&Self` - The other `Server` instance to compare against.
33    ///
34    /// # Returns
35    ///
36    /// - `bool` - `true` if the instances are equal, `false` otherwise.
37    #[inline]
38    fn eq(&self, other: &Self) -> bool {
39        self.get_server_config() == other.get_server_config()
40            && self.get_request_config() == other.get_request_config()
41            && self.get_route_matcher() == other.get_route_matcher()
42            && self.get_task_panic().len() == other.get_task_panic().len()
43            && self.get_request_error().len() == other.get_request_error().len()
44            && self.get_request_middleware().len() == other.get_request_middleware().len()
45            && self.get_response_middleware().len() == other.get_response_middleware().len()
46            && self
47                .get_task_panic()
48                .iter()
49                .zip(other.get_task_panic().iter())
50                .all(|pair: (&ServerHookHandler, &ServerHookHandler)| Arc::ptr_eq(pair.0, pair.1))
51            && self
52                .get_request_error()
53                .iter()
54                .zip(other.get_request_error().iter())
55                .all(|pair: (&ServerHookHandler, &ServerHookHandler)| Arc::ptr_eq(pair.0, pair.1))
56            && self
57                .get_request_middleware()
58                .iter()
59                .zip(other.get_request_middleware().iter())
60                .all(|pair: (&ServerHookHandler, &ServerHookHandler)| Arc::ptr_eq(pair.0, pair.1))
61            && self
62                .get_response_middleware()
63                .iter()
64                .zip(other.get_response_middleware().iter())
65                .all(|pair: (&ServerHookHandler, &ServerHookHandler)| Arc::ptr_eq(pair.0, pair.1))
66    }
67}
68
69/// Implements the `Eq` trait for `Server`.
70///
71/// This indicates that `Server` has a total equality relation.
72impl Eq for Server {}
73
74/// Implementation of `From` trait for converting `usize` address into `Server`.
75impl From<usize> for Server {
76    /// Converts a memory address into an owned `Server` by cloning from the reference.
77    ///
78    /// # Arguments
79    ///
80    /// - `usize` - The memory address of the `Server` instance.
81    ///
82    /// # Returns
83    ///
84    /// - `Server` - A cloned `Server` instance from the given address.
85    #[inline(always)]
86    fn from(address: usize) -> Self {
87        let server: &Server = address.into();
88        server.clone()
89    }
90}
91
92/// Implementation of `From` trait for converting `usize` address into `&Server`.
93impl From<usize> for &'static Server {
94    /// Converts a memory address into a reference to `Server`.
95    ///
96    /// # Arguments
97    ///
98    /// - `usize` - The memory address of the `Server` instance.
99    ///
100    /// # Returns
101    ///
102    /// - `&'static Server` - A reference to the `Server` at the given address.
103    ///
104    /// # Safety
105    ///
106    /// - The address is guaranteed to be a valid `Server` instance
107    ///   that was previously converted from a reference and is managed by the runtime.
108    #[inline(always)]
109    fn from(address: usize) -> &'static Server {
110        unsafe { &*(address as *const Server) }
111    }
112}
113
114/// Implementation of `From` trait for converting `usize` address into `&mut Server`.
115impl From<usize> for &'static mut Server {
116    /// Converts a memory address into a mutable reference to `Server`.
117    ///
118    /// # Arguments
119    ///
120    /// - `usize` - The memory address of the `Server` instance.
121    ///
122    /// # Returns
123    ///
124    /// - `&'static mut Server` - A mutable reference to the `Server` at the given address.
125    ///
126    /// # Safety
127    ///
128    /// - The address is guaranteed to be a valid `Server` instance
129    ///   that was previously converted from a reference and is managed by the runtime.
130    #[inline(always)]
131    fn from(address: usize) -> &'static mut Server {
132        unsafe { &mut *(address as *mut Server) }
133    }
134}
135
136/// Implementation of `From` trait for converting `&Server` into `usize` address.
137impl From<&Server> for usize {
138    /// Converts a reference to `Server` into its memory address.
139    ///
140    /// # Arguments
141    ///
142    /// - `&Server` - The reference to the `Server` instance.
143    ///
144    /// # Returns
145    ///
146    /// - `usize` - The memory address of the `Server` instance.
147    #[inline(always)]
148    fn from(server: &Server) -> Self {
149        server as *const Server as usize
150    }
151}
152
153/// Implementation of `From` trait for converting `&mut Server` into `usize` address.
154impl From<&mut Server> for usize {
155    /// Converts a mutable reference to `Server` into its memory address.
156    ///
157    /// # Arguments
158    ///
159    /// - `&mut Server` - The mutable reference to the `Server` instance.
160    ///
161    /// # Returns
162    ///
163    /// - `usize` - The memory address of the `Server` instance.
164    #[inline(always)]
165    fn from(server: &mut Server) -> Self {
166        server as *mut Server as usize
167    }
168}
169
170/// Implementation of `AsRef` trait for `Server`.
171impl AsRef<Server> for Server {
172    /// Converts `&Server` to `&Server` via memory address conversion.
173    ///
174    /// # Returns
175    ///
176    /// - `&Self` - A reference to the `Server` instance.
177    #[inline(always)]
178    fn as_ref(&self) -> &Self {
179        let address: usize = self.into();
180        address.into()
181    }
182}
183
184/// Implementation of `AsMut` trait for `Server`.
185impl AsMut<Server> for Server {
186    /// Converts `&mut Server` to `&mut Server` via memory address conversion.
187    ///
188    /// # Returns
189    ///
190    /// - `&mut Self` - A mutable reference to the `Server` instance.
191    #[inline(always)]
192    fn as_mut(&mut self) -> &mut Self {
193        let address: usize = self.into();
194        address.into()
195    }
196}
197
198/// Converts a `ServerConfig` into a `Server` instance.
199///
200/// This allows creating a `Server` directly from its configuration,
201/// using default values for other fields.
202impl From<ServerConfig> for Server {
203    /// Creates a new `Server` instance from the given `ServerConfig`.
204    ///
205    /// # Arguments
206    ///
207    /// - `ServerConfig` - The server configuration to use.
208    ///
209    /// # Returns
210    ///
211    /// - `Self` - A new `Server` instance with the provided configuration.
212    #[inline(always)]
213    fn from(server_config: ServerConfig) -> Self {
214        Self {
215            server_config,
216            ..Default::default()
217        }
218    }
219}
220
221/// Converts a `RequestConfig` into a `Server` instance.
222///
223/// This allows creating a `Server` directly from its request configuration,
224/// using default values for other fields.
225impl From<RequestConfig> for Server {
226    /// Creates a new `Server` instance from the given `RequestConfig`.
227    ///
228    /// # Arguments
229    ///
230    /// - `RequestConfig` - The request configuration to use.
231    ///
232    /// # Returns
233    ///
234    /// - `Self` - A new `Server` instance with the provided request configuration.
235    #[inline(always)]
236    fn from(request_config: RequestConfig) -> Self {
237        Self {
238            request_config,
239            ..Default::default()
240        }
241    }
242}
243
244/// Implementation of `Lifetime` trait for `Server`.
245impl Lifetime for Server {
246    /// Converts a reference to the server into a `'static` reference.
247    ///
248    /// # Returns
249    ///
250    /// - `&'static Self` - A reference to the server with a `'static` lifetime.
251    ///
252    /// # Safety
253    ///
254    /// - The address is guaranteed to be a valid `Server` instance
255    ///   that was previously converted from a reference and is managed by the runtime.
256    #[inline(always)]
257    unsafe fn leak(&self) -> &'static Self {
258        let address: usize = self.into();
259        address.into()
260    }
261
262    /// Converts a reference to the server into a `'static` mutable reference.
263    ///
264    /// # Returns
265    ///
266    /// - `&'static mut Self` - A mutable reference to the server with a `'static` lifetime.
267    ///
268    /// # Safety
269    ///
270    /// - The address is guaranteed to be a valid `Server` instance
271    ///   that was previously converted from a reference and is managed by the runtime.
272    #[inline(always)]
273    unsafe fn leak_mut(&self) -> &'static mut Self {
274        let address: usize = self.into();
275        address.into()
276    }
277}
278
279/// Represents the server, providing methods to configure and run it.
280///
281/// This struct wraps the `Server` configuration and routing logic,
282/// offering a high-level API for setting up the HTTP and WebSocket server.
283impl Server {
284    /// Registers a hook into the server's processing pipeline.
285    ///
286    /// This function dispatches the provided `HookType` to the appropriate
287    /// internal hook collection based on its variant. The hook will be executed
288    /// at the corresponding stage of request processing according to its type:
289    /// - `Panic` - Added to panic handlers for error recovery
290    /// - `RequestError` - Added to request error handlers
291    /// - `RequestMiddleware` - Added to pre-route middleware chain
292    /// - `Route` - Registered as a route handler for the specified path
293    /// - `ResponseMiddleware` - Added to post-route middleware chain
294    ///
295    /// # Arguments
296    ///
297    /// - `HookType` - The `HookType` instance containing the hook configuration and factory.
298    #[inline]
299    pub fn handle_hook(&mut self, hook: HookType) {
300        match hook {
301            HookType::TaskPanic(_, hook) => {
302                self.get_mut_task_panic().push(hook());
303            }
304            HookType::RequestError(_, hook) => {
305                self.get_mut_request_error().push(hook());
306            }
307            HookType::RequestMiddleware(_, hook) => {
308                self.get_mut_request_middleware().push(hook());
309            }
310            HookType::Route(path, hook) => {
311                self.get_mut_route_matcher().add(path, hook()).unwrap();
312            }
313            HookType::ResponseMiddleware(_, hook) => {
314                self.get_mut_response_middleware().push(hook());
315            }
316        };
317    }
318
319    /// Sets the server configuration from a JSON string.
320    ///
321    /// # Arguments
322    ///
323    /// - `C` - The configuration.
324    ///
325    /// # Returns
326    ///
327    /// - `&mut Self` - Reference to self for method chaining.
328    #[inline]
329    pub fn config_from_json<C>(&mut self, json: C) -> &mut Self
330    where
331        C: AsRef<str>,
332    {
333        let config: ServerConfig = serde_json::from_str(json.as_ref()).unwrap();
334        self.set_server_config(config);
335        self
336    }
337
338    /// Sets the server configuration.
339    ///
340    /// # Arguments
341    ///
342    /// - `ServerConfig` - The server configuration.
343    ///
344    /// # Returns
345    ///
346    /// - `&mut Self` - Reference to self for method chaining.
347    #[inline(always)]
348    pub fn server_config(&mut self, config: ServerConfig) -> &mut Self {
349        self.set_server_config(config);
350        self
351    }
352
353    /// Sets the HTTP request config.
354    ///
355    /// # Arguments
356    ///
357    /// - `RequestConfig` - The HTTP request config to set.
358    ///
359    /// # Returns
360    ///
361    /// - `&mut Self` - Reference to self for method chaining.
362    #[inline(always)]
363    pub fn request_config(&mut self, config: RequestConfig) -> &mut Self {
364        self.set_request_config(config);
365        self
366    }
367
368    /// Registers a task panic handler to the processing pipeline.
369    ///
370    /// This method allows registering task panic handlers that implement the `ServerHook` trait,
371    /// which will be executed when a panic occurs during request processing.
372    ///
373    /// # Returns
374    ///
375    /// - `&mut Self` - Reference to self for method chaining.
376    #[inline(always)]
377    pub fn task_panic<S>(&mut self) -> &mut Self
378    where
379        S: ServerHook,
380    {
381        self.get_mut_task_panic().push(Hook::factory::<S>());
382        self
383    }
384
385    /// Registers a request error handler to the processing pipeline.
386    ///
387    /// This method allows registering request error handlers that implement the `ServerHook` trait,
388    /// which will be executed when a request error occurs during HTTP request processing.
389    ///
390    /// # Returns
391    ///
392    /// - `&mut Self` - Reference to self for method chaining.
393    #[inline(always)]
394    pub fn request_error<S>(&mut self) -> &mut Self
395    where
396        S: ServerHook,
397    {
398        self.get_mut_request_error().push(Hook::factory::<S>());
399        self
400    }
401
402    /// Registers a route hook for a specific path.
403    ///
404    /// This method allows registering route handlers that implement the `ServerHook` trait,
405    /// providing type safety and better code organization.
406    ///
407    /// # Arguments
408    ///
409    /// - `impl AsRef<str>` - The route path pattern.
410    ///
411    /// # Returns
412    ///
413    /// - `&mut Self` - Reference to self for method chaining.
414    #[inline(always)]
415    pub fn route<S>(&mut self, path: impl AsRef<str>) -> &mut Self
416    where
417        S: ServerHook,
418    {
419        self.get_mut_route_matcher()
420            .add(path.as_ref(), Hook::factory::<S>())
421            .unwrap();
422        self
423    }
424
425    /// Registers request middleware to the processing pipeline.
426    ///
427    /// This method allows registering middleware that implements the `ServerHook` trait,
428    /// which will be executed before route handlers for every incoming request.
429    ///
430    /// # Returns
431    ///
432    /// - `&mut Self` - Reference to self for method chaining.
433    #[inline(always)]
434    pub fn request_middleware<S>(&mut self) -> &mut Self
435    where
436        S: ServerHook,
437    {
438        self.get_mut_request_middleware().push(Hook::factory::<S>());
439        self
440    }
441
442    /// Registers response middleware to the processing pipeline.
443    ///
444    /// This method allows registering middleware that implements the `ServerHook` trait,
445    /// which will be executed after route handlers for every outgoing response.
446    ///
447    /// # Returns
448    ///
449    /// - `&mut Self` - Reference to self for method chaining.
450    #[inline(always)]
451    pub fn response_middleware<S>(&mut self) -> &mut Self
452    where
453        S: ServerHook,
454    {
455        self.get_mut_response_middleware()
456            .push(Hook::factory::<S>());
457        self
458    }
459
460    /// Format the host and port into a bindable address string.
461    ///
462    /// # Arguments
463    ///
464    /// - `H` - The host address.
465    /// - `u16` - The port number.
466    ///
467    /// # Returns
468    ///
469    /// - `String` - The formatted address string in the form "host:port".
470    #[inline(always)]
471    pub fn format_bind_address<H>(host: H, port: u16) -> String
472    where
473        H: AsRef<str>,
474    {
475        format!("{}{COLON}{port}", host.as_ref())
476    }
477
478    /// Flushes the standard output stream.
479    ///
480    /// # Returns
481    ///
482    /// - `io::Result<()>` - The result of the flush operation.
483    #[inline(always)]
484    pub fn try_flush_stdout() -> io::Result<()> {
485        stdout().flush()
486    }
487
488    /// Flushes the standard output stream.
489    ///
490    /// # Panics
491    ///
492    /// This function will panic if the flush operation fails.
493    #[inline(always)]
494    pub fn flush_stdout() {
495        stdout().flush().unwrap();
496    }
497
498    /// Flushes the standard error stream.
499    ///
500    /// # Returns
501    ///
502    /// - `io::Result<()>` - The result of the flush operation.
503    #[inline(always)]
504    pub fn try_flush_stderr() -> io::Result<()> {
505        stderr().flush()
506    }
507
508    /// Flushes the standard error stream.
509    ///
510    /// # Panics
511    ///
512    /// This function will panic if the flush operation fails.
513    #[inline(always)]
514    pub fn flush_stderr() {
515        stderr().flush().unwrap();
516    }
517
518    /// Flushes both the standard output and error streams.
519    ///
520    /// # Returns
521    ///
522    /// - `io::Result<()>` - The result of the flush operation.
523    #[inline(always)]
524    pub fn try_flush_stdout_and_stderr() -> io::Result<()> {
525        Self::try_flush_stdout()?;
526        Self::try_flush_stderr()
527    }
528
529    /// Flushes both the standard output and error streams.
530    ///
531    /// # Panics
532    ///
533    /// This function will panic if either flush operation fails.
534    #[inline(always)]
535    pub fn flush_stdout_and_stderr() {
536        Self::flush_stdout();
537        Self::flush_stderr();
538    }
539
540    /// Executes trait-based request middleware in sequence.
541    ///
542    /// # Arguments
543    ///
544    /// - `&mut Stream` - The `Stream` for the current request.
545    /// - `&mut Context` - The `Context` for the current request.
546    ///
547    /// # Returns
548    ///
549    /// - `bool` - `true` if the lifecycle was aborted, `false` otherwise.
550    pub(super) async fn handle_request_middleware(
551        &self,
552        stream: &mut Stream,
553        ctx: &mut Context,
554    ) -> bool {
555        for hook in self.get_request_middleware().iter() {
556            if hook(stream, ctx).await.is_reject() {
557                return true;
558            }
559        }
560        false
561    }
562
563    /// Executes a trait-based route hook if one matches.
564    ///
565    /// # Arguments
566    ///
567    /// - `&mut Stream` - The `Stream` for the current request.
568    /// - `&mut Context` - The `Context` for the current request.
569    /// - `&str` - The request path to match.
570    ///
571    /// # Returns
572    ///
573    /// - `bool` - `true` if the lifecycle was aborted, `false` otherwise.
574    pub(super) async fn handle_route_matcher(
575        &self,
576        stream: &mut Stream,
577        ctx: &mut Context,
578        path: &str,
579    ) -> bool {
580        if let Some(hook) = self.get_route_matcher().try_resolve_route(ctx, path)
581            && hook(stream, ctx).await.is_reject()
582        {
583            return true;
584        }
585        false
586    }
587
588    /// Executes trait-based response middleware in sequence.
589    ///
590    /// # Arguments
591    ///
592    /// - `&mut Stream` - The `Stream` for the current request.
593    /// - `&mut Context` - The `Context` for the current request.
594    ///
595    /// # Returns
596    ///
597    /// - `bool` - `true` if the lifecycle was aborted, `false` otherwise.
598    pub(super) async fn handle_response_middleware(
599        &self,
600        stream: &mut Stream,
601        ctx: &mut Context,
602    ) -> bool {
603        for hook in self.get_response_middleware().iter() {
604            if hook(stream, ctx).await.is_reject() {
605                return true;
606            }
607        }
608        false
609    }
610
611    /// Handles errors that occur while processing HTTP requests.
612    ///
613    /// # Arguments
614    ///
615    /// - `&mut Stream` - The `Stream` for the current request.
616    /// - `&mut Context` - The `Context` for the current request.
617    /// - `&RequestError` - The error that occurred.
618    pub async fn handle_request_error(
619        &self,
620        stream: &mut Stream,
621        ctx: &mut Context,
622        error: &RequestError,
623    ) {
624        ctx.set_request_error_data(error.clone());
625        stream.set_closed(false);
626        for hook in self.get_request_error().iter() {
627            if hook(stream, ctx).await.is_reject() {
628                return;
629            }
630        }
631    }
632
633    /// The core request handling pipeline.
634    ///
635    /// This function orchestrates the execution of request middleware, the route hook,
636    /// and response middleware. It supports both function-based and trait-based handlers.
637    ///
638    /// # Arguments
639    ///
640    /// - `&mut Stream` - The `Stream` for the current request.
641    /// - `&mut Context` - The `Context` for the current request.
642    /// - `Request` - The incoming request to be processed.
643    /// - `Option<String>` - The original target supplied by a multiplexed protocol.
644    ///
645    /// # Returns
646    ///
647    /// - `bool` - A boolean indicating whether the connection should be kept alive.
648    pub(crate) async fn request_hook(
649        &self,
650        stream: &mut Stream,
651        ctx: &mut Context,
652        request: Request,
653        target: Option<String>,
654    ) -> bool {
655        let keep_alive: bool = request.is_enable_keep_alive();
656        let version: RequestVersion = request.get_version().clone();
657        ctx.set_original_head(Some(request.get_method().is_head()));
658        ctx.set_request(request);
659        ctx.get_mut_response().reset().set_version(version);
660        ctx.clear_route_params();
661        ctx.reset_request_attributes();
662        match target {
663            Some(target) => {
664                ctx.set_request_target(target);
665            }
666            None => {
667                if let Some(target) = stream.get_line_buffer().split_ascii_whitespace().nth(1) {
668                    ctx.set_request_target(target);
669                } else {
670                    ctx.clear_attribute();
671                }
672            }
673        }
674        stream.set_closed(false);
675        if self.handle_request_middleware(stream, ctx).await {
676            return stream.is_keep_alive(keep_alive);
677        }
678        // A static route is the common case and needs nothing but the path,
679        // so the path is borrowed from the request instead of being copied
680        // out of it. Only a pattern route, which is the rarer case, pays for
681        // the copy.
682        let static_hook: Option<&ServerHookHandler> = {
683            let path: &str = ctx.get_request().get_path().as_str();
684            self.get_route_matcher().try_resolve_static_route(path)
685        };
686        if let Some(hook) = static_hook {
687            if hook(stream, ctx).await.is_reject() {
688                return stream.is_keep_alive(keep_alive);
689            }
690        } else {
691            let route: RequestPath = ctx.get_request().get_path().clone();
692            if self.handle_route_matcher(stream, ctx, &route).await {
693                return stream.is_keep_alive(keep_alive);
694            }
695        }
696        if self.handle_response_middleware(stream, ctx).await {
697            return stream.is_keep_alive(keep_alive);
698        }
699        stream.is_keep_alive(keep_alive)
700    }
701
702    /// Handles subsequent HTTP requests on a persistent (keep-alive) connection.
703    ///
704    /// # Arguments
705    ///
706    /// - `&mut Stream` - The `Stream` for the current request.
707    /// - `&mut Context` - The `Context` for the current request.
708    /// - `Request` - The initial request that established the keep-alive connection.
709    async fn handle_http_requests(&self, stream: &mut Stream, ctx: &mut Context, request: Request) {
710        if !self.request_hook(stream, ctx, request, None).await {
711            return;
712        }
713        loop {
714            let mut reused_request: Request = mem::take(ctx.get_mut_request());
715            match stream.try_fill_http_request(&mut reused_request).await {
716                Ok(()) => {
717                    if !self.request_hook(stream, ctx, reused_request, None).await {
718                        return;
719                    }
720                }
721                Err(error) => {
722                    ctx.set_original_head(None).set_request(reused_request);
723                    let version: Option<HttpVersion> = h1_error_response_version(stream, &error);
724                    Box::pin(reply_to_request_error(self, stream, ctx, &error, version)).await;
725                    return;
726                }
727            }
728        }
729    }
730
731    /// Handles a single client connection, determining whether it's an HTTP or WebSocket request.
732    ///
733    /// It reads the initial request from the stream and dispatches it to the appropriate hook.
734    /// Both arguments are borrowed: the stream and the context belong to the
735    /// caller, so this leaves them alive for whatever runs next — the panic
736    /// hooks after an unwind, or the next request on a keep alive connection.
737    ///
738    /// # Arguments
739    ///
740    /// - `&mut Stream` - The `Stream` for the current request.
741    /// - `&mut Context` - The `Context` for the current request.
742    async fn handle_connection(&self, stream: &mut Stream, ctx: &mut Context) {
743        match stream.try_get_http_request().await {
744            Ok(request) => {
745                self.handle_http_requests(stream, ctx, request).await;
746            }
747            Err(error) => {
748                let version: Option<HttpVersion> = h1_error_response_version(stream, &error);
749                Box::pin(reply_to_request_error(self, stream, ctx, &error, version)).await;
750            }
751        }
752    }
753
754    /// Serves one HTTP/1.1 connection through the existing keep alive pipeline.
755    ///
756    /// This is the same pipeline a plaintext connection has always used: the
757    /// request parser runs in a loop, so keep alive, upgrades and raw writes
758    /// behave exactly as they did before TLS and the multiplexed protocols
759    /// existed. A handler that panics is caught here and reported through the
760    /// existing task panic hooks, so the accept loop survives it and the hooks
761    /// see the panic while the stream and context are still alive.
762    ///
763    /// # Arguments
764    ///
765    /// - `&mut Stream` - The stream carrying the connection.
766    ///
767    /// # Returns
768    ///
769    /// - `()` - Resolves once the connection is finished.
770    pub(crate) async fn serve_h1_connection_stream(&self, stream: &mut Stream) {
771        let mut ctx: Context = Context::default();
772        let panicked: Option<PanicData> =
773            catch_connection_panic(self.handle_connection(stream, &mut ctx)).await;
774        let Some(panic) = panicked else {
775            return;
776        };
777        ctx.set_task_panic(panic)
778            .get_mut_response()
779            .set_status_code(HttpStatus::InternalServerError.code());
780        stream.set_closed(false);
781        for hook in self.get_task_panic().iter() {
782            if hook(stream, &mut ctx).await.is_reject() {
783                break;
784            }
785        }
786    }
787
788    /// Serves one request that arrived on a multiplexed protocol stream.
789    ///
790    /// The lifecycle is the one an HTTP/1.1 request runs: the request
791    /// middleware, the matched route and the response middleware, in that
792    /// order, against the same context and the same error hook. A panic inside
793    /// it is caught the same way a connection panic is.
794    ///
795    /// # Arguments
796    ///
797    /// - `&mut Stream` - The stream the pipeline writes its response onto.
798    /// - `&mut Context` - The context for the current request.
799    /// - `Request` - The request converted from the protocol head and body.
800    /// - `String` - The complete original target before query-map conversion.
801    ///
802    /// # Returns
803    ///
804    /// - `()` - Resolves once the pipeline has finished writing.
805    pub(crate) async fn run_protocol_lifecycle(
806        &self,
807        stream: &mut Stream,
808        ctx: &mut Context,
809        request: Request,
810        target: String,
811    ) {
812        let panicked: Option<PanicData> = catch_connection_panic(async {
813            let _keep_alive: bool = self.request_hook(stream, ctx, request, Some(target)).await;
814        })
815        .await;
816        let Some(panic) = panicked else {
817            return;
818        };
819        ctx.set_task_panic(panic)
820            .get_mut_response()
821            .set_status_code(HttpStatus::InternalServerError.code());
822        stream.set_closed(false);
823        for hook in self.get_task_panic().iter() {
824            if hook(stream, ctx).await.is_reject() {
825                break;
826            }
827        }
828    }
829
830    /// Starts the server, binds to the configured address, and begins listening.
831    ///
832    /// The configured protocol selects the listener. HTTP/1.1 and HTTP/2 share
833    /// the TCP listener, the latter speaking its own preface and optionally
834    /// wrapping the connection in TLS, while HTTP/3 binds a QUIC UDP endpoint.
835    /// Invalid TLS material and an HTTP/3 configuration without TLS are both
836    /// rejected before the socket is bound, so a misconfigured server fails to
837    /// start rather than accepting connections it cannot serve.
838    ///
839    /// The accept loop owns a clone of the server instead of borrowing it, so
840    /// running a short lived `Server` stays safe and dropping it leaves no
841    /// leaked allocation behind.
842    ///
843    /// # Returns
844    ///
845    /// - `Result<ServerControlHook, Box<ServerError>>` - The shutdown hook on
846    ///   success, or the failure that prevented the server from binding.
847    pub async fn run(&self) -> Result<ServerControlHook, Box<ServerError>> {
848        let server_config: &ServerConfig = self.get_server_config();
849        let protocol: ServerProtocol = server_config.get_protocol();
850        let tls_config: Option<TlsConfig> = server_config.get_tls().clone();
851        if protocol == ServerProtocol::Http3 && tls_config.is_none() {
852            return Err(Box::new(ServerError::MissingTlsForHttp3));
853        }
854        let stream_tls: Option<Arc<rustls::ServerConfig>> = match tls_config.clone() {
855            Some(_) if protocol == ServerProtocol::Http3 => None,
856            Some(config) => Some(build_stream_tls_config(&config, &protocol)?),
857            None => None,
858        };
859        let bind_address: &String = server_config.get_address();
860        let server: Arc<Server> = Arc::new(Self::clone(self));
861        let request_config: RequestConfig = *self.get_request_config();
862        let (shutdown_sender, shutdown_receiver) = channel(());
863        let (running_sender, running_receiver) = channel(SERVER_RUNNING);
864        let _: JoinHandle<()> = match protocol {
865            ServerProtocol::Http3 => {
866                let Some(config) = tls_config.clone() else {
867                    return Err(Box::new(ServerError::MissingTlsForHttp3));
868                };
869                let quic_config: Arc<quinn::crypto::rustls::QuicServerConfig> = Arc::new(
870                    quinn::crypto::rustls::QuicServerConfig::try_from(build_quic_tls_config(
871                        &config,
872                    )?)
873                    .map_err(
874                        |error: quinn::crypto::rustls::NoInitialCipherSuite| {
875                            Box::new(ServerError::Tls(format!(
876                                "no compatible cipher suite for quic: {}",
877                                error
878                            )))
879                        },
880                    )?,
881                );
882                let bind_addr: SocketAddr =
883                    bind_address
884                        .parse::<SocketAddr>()
885                        .map_err(|error: AddrParseError| {
886                            Box::new(ServerError::Tls(format!(
887                                "invalid bind address {}: {}",
888                                bind_address, error
889                            )))
890                        })?;
891                let endpoint: Endpoint =
892                    Endpoint::server(quinn::ServerConfig::with_crypto(quic_config), bind_addr)
893                        .map_err(|error: io::Error| Box::new(ServerError::from(error)))?;
894                let env: ConnectionEnv = ConnectionEnv {
895                    server,
896                    request_config,
897                    protocol,
898                };
899                spawn(async move {
900                    let _: Result<(), Box<ServerError>> =
901                        quic_accept(env, endpoint, shutdown_receiver, running_sender).await;
902                })
903            }
904            _ => {
905                let tcp_listener: TcpListener = TcpListener::bind(&bind_address)
906                    .await
907                    .map_err(|error: io::Error| Box::new(ServerError::from(error)))?;
908                let env: ConnectionEnv = ConnectionEnv {
909                    server,
910                    request_config,
911                    protocol,
912                };
913                spawn(async move {
914                    tcp_accept(
915                        env,
916                        stream_tls,
917                        AcceptSignal {
918                            listener: tcp_listener,
919                            shutdown_receiver,
920                            running_sender,
921                        },
922                    )
923                    .await;
924                })
925            }
926        };
927        let wait_hook: ServerControlHookHandler<()> = Arc::new(move || {
928            let mut running_receiver_clone: Receiver<bool> = running_receiver.clone();
929            Box::pin(async move {
930                while !*running_receiver_clone.borrow_and_update() {
931                    let _: Result<(), tokio::sync::watch::error::RecvError> =
932                        running_receiver_clone.changed().await;
933                }
934            })
935        });
936        let shutdown_hook: ServerControlHookHandler<()> = Arc::new(move || {
937            let shutdown_sender_clone: Sender<()> = shutdown_sender.clone();
938            Box::pin(async move {
939                let _: Result<(), tokio::sync::watch::error::SendError<()>> =
940                    shutdown_sender_clone.send(());
941            })
942        });
943        let mut server_control_hook: ServerControlHook = ServerControlHook::default();
944        server_control_hook.set_shutdown_hook(shutdown_hook);
945        server_control_hook.set_wait_hook(wait_hook);
946        Ok(server_control_hook)
947    }
948}