Skip to main content

Crate day_part_http

Crate day_part_http 

Source
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.
CacheValidators
Origin-supplied validators for one stored URL/representation. Keep these with the body: a 304 has no replacement body. ETags are opaque, including quotes and the W/ 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_challenge sees it.
ChallengeReply
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.
ClientBuilder
Configures a Client.
Collecting
The future Streaming::collect_future returns.
Connecting
The future Client::websocket_future returns.
Cookie
A cookie, as a jar or the platform’s store holds it.
CookieJar
A cookie store the client reads and writes itself: parsing, matching and expiry follow RFC 6265, and a Domain that names a public suffix is refused.
Download
The result of a fetch_to_file download (the body went to disk, not memory).
FetchFuture
An in-flight fetch_future request; dropping it cancels (see the cancel matrix).
Fetching
The future Client::fetch_future returns.
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_redirect sees 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.
NextChunk
The future Body::next returns.
NextMessage
The future WebSocket::next returns.
RedirectReply
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), then fetch or a Client.
Response
A complete HTTP response, body buffered in memory. For large downloads use fetch_to_file, which streams to disk instead, or read a Client’s Body in chunks.
Sending
The future Client::send_future returns.
ServerTrust
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.
TransferStatistics
Trust
Which servers a client trusts beyond the platform’s own evaluation.
TrustReply
Answers a server trust question. Dropping it unanswered keeps the platform’s verdict.
WebSocket
An open WebSocket. Read it with WebSocket::next or WebSocket::read_async, and send through it or a WsSender. Dropping it closes the connection with code 1000.
WsSender
The sending half of a WebSocket.

Enums§

Cache
Whether a client keeps an HTTP cache.
CachePolicy
How a request may use the platform’s cache.
Cookies
Where a client keeps cookies.
HttpError
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§

StreamSink
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 Client on 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 returns HttpError::Unsupported there; use fetch_async or fetch_future.
fetch_async
Perform the request without blocking; on_done runs on an unspecified background thread (capture a reactive Setter to 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 OkHttp Call.cancel, the web the fetch’s AbortController; Windows closes the WinHTTP request handle. A cancelled request that still completes resolves nothing; a platform-side cancel that beats the drop surfaces as HttpError::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 sink chunk by chunk; nothing is buffered beyond one chunk. Blocking, like fetch. bytes_written counts the bytes handed to the sink.
fetch_to_file
Download the response body straight to dest (create/truncate), never buffering it in memory. Blocking, like fetch. On error a partial dest is removed best-effort; atomicity is not promised.
fetch_to_file_async
fetch_to_file without blocking; on_done runs on an unspecified background thread.
tier
How this target realizes requests (fixed at compile time).