volo_http/server/protocol.rs
1//! Protocol related types.
2//!
3//! For more details, refer to [`Http1Config`] and [`Http2Config`].
4//!
5//! And in most cases, users do not need to pay attention to this mod.
6
7use hyper_util::rt::TokioExecutor;
8
9/// Configuration of the http1 part of the [`Server`].
10///
11/// This config is created by [`Server::http1_config`]
12///
13/// [`Server`]: crate::server::Server
14/// [`Server::http1_config`]: crate::server::Server::http1_config
15#[cfg(feature = "http1")]
16pub struct Http1Config<'a> {
17 pub(super) inner: hyper_util::server::conn::auto::Http1Builder<'a, TokioExecutor>,
18}
19
20#[cfg(feature = "http1")]
21impl Http1Config<'_> {
22 /// Set whether the `date` header should be included in HTTP responses.
23 ///
24 /// Note that including the `date` header is recommended by RFC 7231.
25 ///
26 /// Default is `true`.
27 pub fn set_auto_date_header(&mut self, auto_date_header: bool) -> &mut Self {
28 self.inner.auto_date_header(auto_date_header);
29 self
30 }
31
32 /// Set whether HTTP/1 connections should support half-closures.
33 ///
34 /// Clients can chose to shutdown their write-side while waiting
35 /// for the server to respond. Setting this to `true` will
36 /// prevent closing the connection immediately if `read`
37 /// detects an EOF in the middle of a request.
38 ///
39 /// Default is `false`.
40 pub fn set_half_close(&mut self, half_close: bool) -> &mut Self {
41 self.inner.half_close(half_close);
42 self
43 }
44
45 /// Enables or disables HTTP/1 keep-alive.
46 ///
47 /// Default is true.
48 pub fn set_keep_alive(&mut self, keep_alive: bool) -> &mut Self {
49 self.inner.keep_alive(keep_alive);
50 self
51 }
52
53 /// Set whether HTTP/1 connections will write header names as title case at
54 /// the socket level.
55 ///
56 /// Default is false.
57 pub fn set_title_case_headers(&mut self, title_case_headers: bool) -> &mut Self {
58 self.inner.title_case_headers(title_case_headers);
59 self
60 }
61
62 /// Set whether HTTP/1 connections will silently ignored malformed header lines.
63 ///
64 /// If this is enabled and a header line does not start with a valid header name, or does not
65 /// include a colon at all, the line will be silently ignored and no error will be reported.
66 ///
67 /// Default is `false`.
68 pub fn set_ignore_invalid_headers(&mut self, ignore_invalid_headers: bool) -> &mut Self {
69 self.inner.ignore_invalid_headers(ignore_invalid_headers);
70 self
71 }
72
73 /// Set the maximum number of headers.
74 ///
75 /// When a request is received, the parser will reserve a buffer to store headers for optimal
76 /// performance.
77 ///
78 /// If server receives more headers than the buffer size, it responds to the client with
79 /// "431 Request Header Fields Too Large".
80 ///
81 /// Note that headers is allocated on the stack by default, which has higher performance. After
82 /// setting this value, headers will be allocated in heap memory, that is, heap memory
83 /// allocation will occur for each request, and there will be a performance drop of about 5%.
84 ///
85 /// Default is 100.
86 pub fn set_max_headers(&mut self, max_headers: usize) -> &mut Self {
87 self.inner.max_headers(max_headers);
88 self
89 }
90}
91
92/// Configuration of the http2 part of the [`Server`].
93///
94/// [`Server`]: crate::server::Server
95#[cfg(feature = "http2")]
96pub struct Http2Config<'a> {
97 pub(super) inner: hyper_util::server::conn::auto::Http2Builder<'a, TokioExecutor>,
98}
99
100#[cfg(feature = "http2")]
101impl Http2Config<'_> {
102 /// Configures the maximum number of pending reset streams allowed before a GOAWAY will be sent.
103 ///
104 /// This will default to the default value set by the [`h2` crate](https://crates.io/crates/h2).
105 /// As of v0.4.0, it is 20.
106 ///
107 /// See <https://github.com/hyperium/hyper/issues/2877> for more information.
108 pub fn max_pending_accept_reset_streams(&mut self, max: impl Into<Option<usize>>) -> &mut Self {
109 self.inner.max_pending_accept_reset_streams(max);
110 self
111 }
112
113 /// Configures the maximum number of local reset streams allowed before a GOAWAY will be sent.
114 ///
115 /// If not set, hyper will use a default, currently of 1024.
116 ///
117 /// If `None` is supplied, hyper will not apply any limit.
118 /// This is not advised, as it can potentially expose servers to DOS vulnerabilities.
119 ///
120 /// See <https://rustsec.org/advisories/RUSTSEC-2024-0003.html> for more information.
121 pub fn max_local_error_reset_streams(&mut self, max: impl Into<Option<usize>>) -> &mut Self {
122 self.inner.max_local_error_reset_streams(max);
123 self
124 }
125
126 /// Sets the [`SETTINGS_INITIAL_WINDOW_SIZE`][spec] option for HTTP2
127 /// stream-level flow control.
128 ///
129 /// Passing `None` will do nothing.
130 ///
131 /// If not set, hyper will use a default.
132 ///
133 /// [spec]: https://http2.github.io/http2-spec/#SETTINGS_INITIAL_WINDOW_SIZE
134 pub fn initial_stream_window_size(&mut self, sz: impl Into<Option<u32>>) -> &mut Self {
135 self.inner.initial_stream_window_size(sz);
136 self
137 }
138
139 /// Sets the max connection-level flow control for HTTP2.
140 ///
141 /// Passing `None` will do nothing.
142 ///
143 /// If not set, hyper will use a default.
144 pub fn initial_connection_window_size(&mut self, sz: impl Into<Option<u32>>) -> &mut Self {
145 self.inner.initial_connection_window_size(sz);
146 self
147 }
148
149 /// Sets whether to use an adaptive flow control.
150 ///
151 /// Enabling this will override the limits set in
152 /// `http2_initial_stream_window_size` and
153 /// `http2_initial_connection_window_size`.
154 pub fn adaptive_window(&mut self, enabled: bool) -> &mut Self {
155 self.inner.adaptive_window(enabled);
156 self
157 }
158
159 /// Sets the maximum frame size to use for HTTP2.
160 ///
161 /// Passing `None` will do nothing.
162 ///
163 /// If not set, hyper will use a default.
164 pub fn max_frame_size(&mut self, sz: impl Into<Option<u32>>) -> &mut Self {
165 self.inner.max_frame_size(sz);
166 self
167 }
168
169 /// Sets the [`SETTINGS_MAX_CONCURRENT_STREAMS`][spec] option for HTTP2
170 /// connections.
171 ///
172 /// Default is 200. Passing `None` will remove any limit.
173 ///
174 /// [spec]: https://http2.github.io/http2-spec/#SETTINGS_MAX_CONCURRENT_STREAMS
175 pub fn max_concurrent_streams(&mut self, max: impl Into<Option<u32>>) -> &mut Self {
176 self.inner.max_concurrent_streams(max);
177 self
178 }
179
180 /// Sets an interval for HTTP2 Ping frames should be sent to keep a
181 /// connection alive.
182 ///
183 /// Pass `None` to disable HTTP2 keep-alive.
184 ///
185 /// Default is currently disabled.
186 ///
187 /// # Cargo Feature
188 pub fn keep_alive_interval(
189 &mut self,
190 interval: impl Into<Option<std::time::Duration>>,
191 ) -> &mut Self {
192 self.inner.keep_alive_interval(interval);
193 self
194 }
195
196 /// Sets a timeout for receiving an acknowledgement of the keep-alive ping.
197 ///
198 /// If the ping is not acknowledged within the timeout, the connection will
199 /// be closed. Does nothing if `http2_keep_alive_interval` is disabled.
200 ///
201 /// Default is 20 seconds.
202 ///
203 /// # Cargo Feature
204 pub fn keep_alive_timeout(&mut self, timeout: std::time::Duration) -> &mut Self {
205 self.inner.keep_alive_timeout(timeout);
206 self
207 }
208
209 /// Set the maximum write buffer size for each HTTP/2 stream.
210 ///
211 /// Default is currently ~400KB, but may change.
212 ///
213 /// # Panics
214 ///
215 /// The value must be no larger than `u32::MAX`.
216 pub fn max_send_buf_size(&mut self, max: usize) -> &mut Self {
217 self.inner.max_send_buf_size(max);
218 self
219 }
220
221 /// Enables the [extended CONNECT protocol].
222 ///
223 /// [extended CONNECT protocol]: https://datatracker.ietf.org/doc/html/rfc8441#section-4
224 pub fn enable_connect_protocol(&mut self) -> &mut Self {
225 self.inner.enable_connect_protocol();
226 self
227 }
228
229 /// Sets the max size of received header frames.
230 ///
231 /// Default is currently ~16MB, but may change.
232 pub fn max_header_list_size(&mut self, max: u32) -> &mut Self {
233 self.inner.max_header_list_size(max);
234 self
235 }
236
237 /// Set whether the `date` header should be included in HTTP responses.
238 ///
239 /// Note that including the `date` header is recommended by RFC 7231.
240 ///
241 /// Default is true.
242 pub fn auto_date_header(&mut self, enabled: bool) -> &mut Self {
243 self.inner.auto_date_header(enabled);
244 self
245 }
246}