rama_http_types/conn.rs
1//! HTTP connection utilities.
2
3use std::time::Duration;
4
5use crate::proto::h2::{PseudoHeaderOrder, frame::EarlyFrameCapture, frame::Settings};
6use rama_core::extensions::Extension;
7
8#[derive(Debug, Clone, Default, Extension)]
9#[extension(tags(http))]
10/// Optional parameters that can be set in the [`Extensions`] of a (h1) request
11/// to customise the connection of the h1 connection.
12///
13/// Can be used by Http connector services, especially in the context of proxies,
14/// where there might not be one static config that is to be applied to all client connections.
15///
16/// [`Extensions`]: rama_core::extensions::Extensions
17pub struct Http1ClientContextParams {
18 /// Set whether HTTP/1 connections will write header names as title case at
19 /// the socket level.
20 ///
21 /// Default is `false`.
22 pub title_header_case: bool,
23}
24
25#[derive(Debug, Clone, Default, Extension)]
26#[extension(tags(http))]
27/// Optional parameters that can be set in the [`Extensions`] of a (h2) request
28/// to customise the connection of the h2 connection.
29///
30/// Can be used by Http connector services, especially in the context of proxies,
31/// where there might not be one static config that is to be applied to all client connections.
32///
33/// [`Extensions`]: rama_core::extensions::Extensions
34pub struct H2ClientContextParams {
35 /// Pseudo order of the headers stream
36 pub headers_pseudo_order: Option<PseudoHeaderOrder>,
37
38 /// Early frames to be applied first
39 pub early_frames: Option<EarlyFrameCapture>,
40
41 /// The `SETTINGS_INITIAL_WINDOW_SIZE` option for HTTP2
42 /// stream-level flow control.
43 pub init_stream_window_size: Option<u32>,
44
45 /// The max connection-level flow control for HTTP2.
46 pub init_connection_window_size: Option<u32>,
47
48 /// An interval for HTTP2 Ping frames should be sent to keep a
49 /// connection alive.
50 pub keep_alive_interval: Option<Duration>,
51
52 /// A timeout for receiving an acknowledgement of the keep-alive ping.
53 pub keep_alive_timeout: Option<Duration>,
54
55 /// Whether HTTP2 keep-alive should apply while the connection is idle.
56 pub keep_alive_while_idle: Option<bool>,
57
58 /// The max size of received header frames.
59 pub max_header_list_size: Option<u32>,
60
61 /// The `SETTINGS_MAX_FRAME_SIZE` option for HTTP2.
62 pub max_frame_size: Option<u32>,
63
64 /// The `SETTINGS_MAX_CONCURRENT_STREAMS` option for HTTP2,
65 /// limiting the number of concurrent streams the remote peer
66 /// may initiate.
67 pub max_concurrent_streams: Option<u32>,
68
69 /// Whether to use an adaptive flow control.
70 pub adaptive_window: Option<bool>,
71
72 /// The initial maximum of locally initiated (send) streams.
73 ///
74 /// This value is overwritten by the value included in the initial
75 /// `SETTINGS` frame received from the peer.
76 pub initial_max_send_streams: Option<usize>,
77
78 /// The maximum write buffer size for each HTTP2 stream.
79 pub max_send_buf_size: Option<u32>,
80
81 /// The maximum number of HTTP2 concurrent locally reset streams.
82 pub max_concurrent_reset_streams: Option<usize>,
83
84 /// The maximum number of pending reset streams allowed before a
85 /// `GOAWAY` will be sent.
86 pub max_pending_accept_reset_streams: Option<usize>,
87
88 /// The maximum number of local resets due to protocol errors made
89 /// by the remote peer.
90 pub max_local_error_reset_streams: Option<usize>,
91
92 /// The duration to remember locally reset streams.
93 pub reset_stream_duration: Option<Duration>,
94}
95
96pub use rama_net::http::TargetHttpVersion;
97
98#[derive(Debug, Clone, Default, Extension)]
99#[extension(tags(http))]
100/// Per-conn override for the h2 server's initial SETTINGS frame, set on
101/// the IO's [`Extensions`]. Any field left `None` retains the builder
102/// default. `Some(value)` overrides one-to-one; this type can't express
103/// "explicitly unset" — set the builder directly if you need that.
104///
105/// Used primarily by MITM relays. Note: [`HttpMitmRelay`][] only
106/// auto-populates `enable_connect_protocol` and `max_concurrent_streams`;
107/// other fields are independent per-direction budgets and remain
108/// available as direct per-conn overrides for callers who want them.
109///
110/// [`HttpMitmRelay`]: https://docs.rs/rama-http-backend/latest/rama_http_backend/proxy/mitm/struct.HttpMitmRelay.html
111/// [`Extensions`]: rama_core::extensions::Extensions
112pub struct H2ServerContextParams {
113 /// Whether to advertise the [extended CONNECT protocol][1] in the
114 /// initial SETTINGS frame.
115 ///
116 /// [1]: https://datatracker.ietf.org/doc/html/rfc8441#section-4
117 pub enable_connect_protocol: Option<bool>,
118
119 /// `SETTINGS_MAX_CONCURRENT_STREAMS`.
120 pub max_concurrent_streams: Option<u32>,
121
122 /// `SETTINGS_HEADER_TABLE_SIZE`.
123 pub header_table_size: Option<u32>,
124
125 /// `SETTINGS_MAX_FRAME_SIZE`.
126 pub max_frame_size: Option<u32>,
127
128 /// `SETTINGS_MAX_HEADER_LIST_SIZE`.
129 pub max_header_list_size: Option<u32>,
130
131 /// `SETTINGS_INITIAL_WINDOW_SIZE` (stream-level flow control).
132 pub initial_stream_window_size: Option<u32>,
133
134 /// Connection-level flow-control window.
135 pub initial_connection_window_size: Option<u32>,
136
137 /// Whether to use adaptive flow control. If `Some(true)`, the
138 /// stream/connection window-size overrides above are reset to the
139 /// spec default before adaptive control takes over.
140 pub adaptive_window: Option<bool>,
141}
142
143#[derive(Debug, Clone, Extension)]
144#[extension(tags(http))]
145/// The peer's initial (first non-ACK) h2 [`Settings`] frame, set as an
146/// extension on every h2 client response. Captured once per connection;
147/// subsequent SETTINGS updates are not reflected. Stored once in
148/// `Arc<PeerH2Settings>` and shared per-response via
149/// [`rama_core::extensions::Extensions::insert_arc`].
150pub struct PeerH2Settings(pub Settings);