Expand description
day-part-http: headless cross-platform HTTP(S), by default through native networking stack (docs/http.md). No UI; any Rust code can depend on this crate.
let resp = day_part_http::fetch(&day_part_http::Request::get("https://example.com"))?;
println!("{} {} bytes", resp.status, resp.body.len());Why native stacks instead of a Rust HTTP crate: the request inherits the system configuration
(proxies + PAC, per-network VPN routing, Low Data Mode via Request::allow_constrained,
enterprise/MDM certificate stores), and the binary carries no TLS library of its own. macOS
and iOS use URLSession, Android OkHttp through a Java bridge arm, Windows WinHTTP, Linux the
system’s libcurl (opened at run time), HarmonyOS the Network Kit through an ArkTS arm, and the
web the browser’s fetch and WebSocket through a JavaScript arm, where only the asynchronous
entry points exist and the blocking calls return HttpError::Unsupported. tier reports
whether a stack is present.
Two doors. The functions at the crate root (fetch, fetch_async, fetch_future,
fetch_streamed) send one request with no state kept between requests. A Client adds
the rest of a modern HTTP surface on the same stacks: bodies streamed in chunks with
backpressure, uploads from files, streams and multipart forms, redirect and authentication
callbacks, public-key pins and server trust decisions, client identities, cookies, caches,
transfer metrics and WebSockets. capabilities reports what the platform offers.
Threading. fetch blocks the calling thread; run it on your own thread, never the UI
thread. fetch_async’s completion runs on the transport’s own thread (URLSession’s delegate
queue, OkHttp’s reader pool, the libcurl driver, WinHTTP’s callbacks, the HarmonyOS JS thread,
or the browser’s only thread); deliver results into the UI by capturing
a day_reactive::Signal::setter-style
setter in the callback; setters hop to the UI thread
themselves and silently no-op after disposal, so late completions are harmless (DESIGN §4.5):
let done = body_signal.setter();
day_part_http::fetch_async(Request::get(url), move |result| {
if let Ok(resp) = result { done.set(Some(Arc::new(resp.body))); }
});Or await it: fetch_future wraps the same completion as a Future whose drop cancels the
request where the platform can (docs/http.md’s cancel matrix); under day::task the
continuation runs on the UI thread, so results are plain signal writes (docs/async.md).
Every option is best-effort per platform (docs/http.md has the matrix):
allow_expensive/allow_constrained are native on Apple and advisory elsewhere; HTTP 4xx/5xx
are Ok responses (check Response::status), not errors.
Modules§
- simulation
- Scoped, programmable HTTP and WebSocket interception. No sockets, UI or native stack needed.
- testing
- A local HTTP/1.1 and WebSocket server for tests and demonstrations (docs/http.md “Testing”).
- transport
- The contract a backend implements (docs/http.md “Transports”). Apps reach for it to install
a test double with
ClientBuilder::transport, or to route a client through their own stack.
Structs§
- Body
- A response body, read in the chunks the platform delivers. The body pulls from the network only while its reader keeps up. Dropping it before the end cancels the request.
- Cache
Validators - Origin-supplied validators for one stored URL/representation. Keep these with the body:
a 304 has no replacement body.
ETagsare opaque, including quotes and theW/prefix. - Capabilities
- What a backend can do. The client consults it to decide what it must do itself, and apps can
read it (
day_part_http::capabilities()) to say what a platform offers. - Challenge
- An HTTP authentication challenge, as
ClientBuilder::on_challengesees it. - Challenge
Reply - Answers a challenge. Dropping it unanswered delivers the 401 (or 407) as the response.
- Client
- An HTTP client: policy shared by every request it sends, over the platform’s transport. Cloning is cheap and shares the policy, the cookies and the connections.
- Client
Builder - Configures a
Client. - Collecting
- The future
Streaming::collect_futurereturns. - Connecting
- The future
Client::websocket_futurereturns. - Cookie
- A cookie, as a jar or the platform’s store holds it.
- Cookie
Jar - A cookie store the client reads and writes itself: parsing, matching and expiry follow RFC
6265, and a
Domainthat names a public suffix is refused. - Download
- The result of a
fetch_to_filedownload (the body went to disk, not memory). - Fetch
Future - An in-flight
fetch_futurerequest; dropping it cancels (see the cancel matrix). - Fetching
- The future
Client::fetch_futurereturns. - Form
- A multipart form. Build it, then hand it to
Request::form. - Head
- The response head.
- Hop
- A redirect the client is about to follow, as
ClientBuilder::on_redirectsees it. - Identity
- A client certificate identity, presented when a server asks for one.
- InFlight
- A grip on a request started with a callback: cancel it from any thread, at any stage. Holding it does not keep the request alive, and cancelling a finished request does nothing.
- Metrics
- Timings and facts about one completed transfer. Every field a platform does not report is
None. - Next
Chunk - The future
Body::nextreturns. - Next
Message - The future
WebSocket::nextreturns. - Redirect
Reply - Answers a redirect question. Dropping it unanswered follows the redirect. It is
Send, so a handler may keep it and answer later from any thread; the exchange waits meanwhile, up to the client’s question timeout. - Request
- A request under construction. Build with
Request::get(and friends), thenfetchor aClient. - Response
- A complete HTTP response, body buffered in memory. For large downloads use
fetch_to_file, which streams to disk instead, or read aClient’sBodyin chunks. - Sending
- The future
Client::send_futurereturns. - Server
Trust - The certificate chain a server presented, with the platform’s own verdict on it.
- Session
- An isolated routing and statistics scope. Clones share settings. A new session uses the
native provider and does not inherit global interception. Default clients use
global(). - Statistics
- Application payload totals. Rates divide bytes by elapsed scope time, including idle time.
- Streaming
- A response head with its unread body.
- Transfer
Statistics - Trust
- Which servers a client trusts beyond the platform’s own evaluation.
- Trust
Reply - Answers a server trust question. Dropping it unanswered keeps the platform’s verdict.
- WebSocket
- An open WebSocket. Read it with
WebSocket::nextorWebSocket::read_async, and send through it or aWsSender. Dropping it closes the connection with code 1000. - WsSender
- The sending half of a
WebSocket.
Enums§
- Cache
- Whether a client keeps an HTTP cache.
- Cache
Policy - How a request may use the platform’s cache.
- Cookies
- Where a client keeps cookies.
- Http
Error - A transport-level failure. HTTP error statuses (4xx/5xx) are not here; they arrive as
Response::status. The portable core maps from each platform’s taxonomy (docs/http.md). - Message
- A WebSocket message.
- Method
- An HTTP request method.
- Provider
- An HTTP/WebSocket provider. Native is the default; custom providers must describe their capabilities honestly. Reqwest is optional and unavailable on wasm.
- Redirects
- Whether a client follows redirects.
- Scheme
- An HTTP authentication scheme.
- Tier
- How requests are realized on the compiled target.
Traits§
- Stream
Sink - Receives a streamed response: the head first, then each body chunk as it arrives. Implement this for progress reporting, cancellation, incremental hashing, or anything that must observe a large body without buffering it (an app store streaming an APK to disk, docs/http.md).
Functions§
- capabilities
- What a
Clienton this platform can do. - fetch
- Perform the request, blocking the calling thread until the response (or
Request::timeout). Run it on your own thread; calling this on the UI thread stalls the app (docs/http.md). On the web (web-dom) blocking is impossible on the single browser thread: this returnsHttpError::Unsupportedthere; usefetch_asyncorfetch_future. - fetch_
async - Perform the request without blocking;
on_doneruns on an unspecified background thread (capture a reactiveSetterto deliver into UI state; see the crate docs). On the web the completion runs on the browser thread, the only one, which the Setter idiom absorbs unchanged. - fetch_
future - Start the request immediately and await the result. The future is the cancellation grip:
dropping it cancels the request where the platform supports it (docs/http.md’s cancel
matrix): Apple
NSURLSessionTask.cancel, Android OkHttpCall.cancel, the web the fetch’sAbortController; Windows closes the WinHTTP request handle. A cancelled request that still completes resolves nothing; a platform-side cancel that beats the drop surfaces asHttpError::Cancelled. - fetch_
limited_ future - Fetch through the shared stateless client with a strict limit on buffered response bytes. Checks both Content-Length and streamed chunks; exceeding the limit cancels the transfer. The returned future also cancels on drop. Available on every backend, including the web.
- fetch_
limited_ with_ progress_ future - Shared-client bounded download with progress on the future’s polling thread.
See
Client::fetch_limited_with_progress_future. - fetch_
streamed - Perform the request, streaming the body into
sinkchunk by chunk; nothing is buffered beyond one chunk. Blocking, likefetch.bytes_writtencounts the bytes handed to the sink. - fetch_
to_ file - Download the response body straight to
dest(create/truncate), never buffering it in memory. Blocking, likefetch. On error a partialdestis removed best-effort; atomicity is not promised. - fetch_
to_ file_ async fetch_to_filewithout blocking;on_doneruns on an unspecified background thread.- tier
- How this target realizes requests (fixed at compile time).