Skip to main content

nautilus_network/http/
mod.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Asynchronous HTTP requests with rate limiting, connection reuse, and bounded responses.
17//!
18//! # Architecture
19//!
20//! [`HttpClient`] applies quota policy before delegating requests to [`InnerHttpClient`]. The inner
21//! client owns one reusable Hyper client, preserving its connection pool across requests and clones.
22//!
23//! # Rate limiting and requests
24//!
25//! Requests can await default and per-key quotas from one or more shared
26//! [`RateLimiter`](crate::ratelimiter::RateLimiter) instances. Sharing a limiter across clients
27//! enforces one process-wide budget for scopes such as an IP address or account. The client accepts
28//! default and per-request headers, repeated query values, raw bodies, and client-level and
29//! per-request timeouts. Default header values are marked sensitive: `Debug` hides them, and
30//! HTTP/2 excludes them from the header compression table.
31//!
32//! # Proxy routing
33//!
34//! By default the client honors ambient proxy configuration: with `use_system_proxy` left at its
35//! default of `true` and no explicit `proxy_url`, requests are routed through the proxy named by
36//! `HTTP_PROXY`, `HTTPS_PROXY`, or `ALL_PROXY` (lowercase variants included), except destinations
37//! matched by `NO_PROXY`.
38//!
39//! This default is a deliberate trust decision on the process environment: an actor who controls
40//! it chooses the proxy that observes all plaintext HTTP traffic and the CONNECT tunnels that
41//! carry HTTPS.
42//!
43//! An optional explicit `proxy_url` applies to both HTTP and HTTPS traffic and always takes
44//! precedence over ambient lookup. Passing `use_system_proxy(false)` disables ambient lookup, so
45//! requests route directly only when `proxy_url` is unset.
46//!
47//! HTTP status errors remain [`HttpResponse`] values for adapter-specific handling. The transport
48//! retries requests canceled before transmission on reused connections, and allows two retries for
49//! remote HTTP/2 `GOAWAY(NO_ERROR)` or `REFUSED_STREAM` errors. Other transport failures and HTTP
50//! status codes do not trigger retries. Adapters can apply [`crate::retry::RetryManager`] when the
51//! operation and venue error are safe to retry.
52//!
53//! # Connection and response policy
54//!
55//! Production clients built through [`HttpClient::builder`] enable `TCP_NODELAY`, pooled idle
56//! connections, and HTTP/2 keepalive while idle.
57//!
58//! HTTP/2 connections use fixed flow-control windows of 16 MiB per stream and 32 MiB per
59//! connection, larger than Hyper's fixed defaults of 2 MiB and 5 MiB. Setting
60//! `NAUTILUS_HTTP2_ADAPTIVE_WINDOW=true` before building a client enables Hyper's adaptive windows
61//! instead, which start at 65,535 bytes and grow toward 16 MiB through PING probes and SETTINGS
62//! updates. Cloudflare-fronted endpoints can reset large response bodies mid-transfer under
63//! adaptive windows. The value `false` keeps fixed windows, and any other value fails the build.
64//!
65//! Buffered requests advertise gzip unless default or per-request headers set `Accept-Encoding`.
66//! Gzip responses are decoded before return; unsupported encodings and corrupt bodies are errors.
67//! The request deadline includes gzip decoding. Responses whose method or status forbids content
68//! preserve their encoding metadata. Decoded responses omit `Content-Encoding` and `Content-Length`,
69//! even when selected through `header_keys`.
70//!
71//! Buffered responses reject wire bodies larger than 100 MiB, including chunked bodies without a
72//! declared length. Decoded bodies have a separate 100 MiB default limit, configurable through
73//! `max_decompressed_bytes`. [`HttpClient::get_stream`] returns raw body chunks without decoding,
74//! adding `Accept-Encoding`, or applying a total size limit. Request URLs in transport errors and
75//! response-stream diagnostics are limited to their origin (scheme, host, and port). Setting `redact_url(true)` on the
76//! builder omits the origin too. This policy controls the URL context added by this client;
77//! diagnostic messages from lower layers are unchanged. The client logs request metadata only, never URLs.
78//!
79//! Hyper owns the lifecycle of individual pooled connections, so this client exposes no socket
80//! state sink or explicit reconnect operation. Callers observe connection failure through each
81//! request result and retain the client to preserve its pool.
82
83pub mod client;
84pub mod error;
85pub mod types;
86
87mod stream;
88
89#[cfg(not(all(feature = "simulation", madsim)))]
90mod connector;
91#[cfg(all(feature = "simulation", madsim))]
92mod simulation;
93#[cfg(not(all(feature = "simulation", madsim)))]
94mod transport;
95
96#[cfg(all(test, not(all(feature = "simulation", madsim))))]
97mod tests;
98
99// Re-exports
100pub use client::{HttpClient, HttpRedirectPolicy, InnerHttpClient};
101pub use error::HttpClientError;
102pub use http::{
103    Method, StatusCode,
104    header::{RETRY_AFTER, USER_AGENT},
105};
106use nautilus_core::consts::NAUTILUS_USER_AGENT;
107pub use stream::HttpResponseStream;
108pub use types::{HttpMethod, HttpResponse, HttpStatus, parse_retry_after};
109pub use url::Url;
110
111/// Returns the standard headers every NautilusTrader HTTP and WebSocket client sends.
112///
113/// Carries the NautilusTrader [`USER_AGENT`] with the compile-time version.
114#[must_use]
115pub fn create_standard_nautilus_headers() -> Vec<(String, String)> {
116    vec![(USER_AGENT.to_string(), NAUTILUS_USER_AGENT.to_string())]
117}