Skip to content
Haiku OSDeep Dive Published Updated 3 min readViews unavailable

Haiku's Network Kit HTTP Client: Requests, Listeners, Cookies, and TLS Boundaries

A careful tour of Haiku network-services requests, asynchronous listeners, HTTP state, cancellation, TLS validation, and API stability boundaries.

Haiku separates low-level networking—sockets, interfaces, and address objects—from a higher network-services layer that implements URL requests such as HTTP. The distinction matters. A request object can manage protocol state, redirects, cookies, authentication callbacks, and response bodies, but the application still owns lifetime, concurrency, trust policy, and interpretation of the received bytes.

The official API reference marks the network-services group as experimental. Code against the headers shipped with the exact Haiku release you support, isolate the API behind a small adapter, and expect source-level changes. An example copied from a different release is evidence about the design, not a guarantee that every constructor and callback signature matches your system.

Requests are asynchronous state machines

An HTTP request is created for a URL and coupled to a listener. Starting it schedules work; progress and result callbacks arrive later. Keep the request and listener alive until completion or cancellation has fully settled. Destroying either object while callbacks can still run produces races that a successful one-shot test may not reveal.

A useful listener separates four kinds of information:

  1. Transport state: DNS, connection, TLS, timeout, or cancellation failure.
  2. HTTP state: status code and response headers.
  3. Body data: zero or more chunks that may be binary and need bounded storage.
  4. Final completion: the point at which resources and UI state can transition.

Do not equate an HTTP 404 or 500 with a broken TCP transaction. Conversely, receiving some body bytes does not prove the transfer completed. Check both the request result and the protocol status, and make partial-output cleanup explicit.

Headers, redirects, and cookies change trust decisions

Build the target with BUrl rather than concatenating unescaped user input. Set request headers deliberately and never log authorization values. Redirects can change host, scheme, and effective request method; before automatically forwarding credentials, compare the new origin and require HTTPS where confidentiality matters.

Cookie persistence should be scoped to a deliberate cookie jar and profile. A command-line downloader, a signed-in application, and an embedded help viewer should not silently share state. Expiry, domain, path, and secure flags are protocol rules rather than string decorations.

HTTP bodies are not text by default. Respect content length only as a hint, impose an application maximum, stream large results to a temporary file, and rename into place only after success. Decode text using the declared and supported character encoding; preserve raw bytes otherwise. Compression also means the number of network bytes and the number of decoded bytes can differ substantially.

TLS is an identity boundary

A successful encrypted connection is useful only if certificate and hostname validation remain enabled. Do not solve a private-CA problem by accepting every certificate. Install the intended trust anchor through a controlled path or provide an application-specific trust policy with a narrow scope and an auditable failure mode.

Time settings affect certificate validity, while proxies and captive portals can replace expected endpoints. Present enough error context to distinguish name resolution, TCP, certificate, protocol, and application status without exposing secrets. Retry only operations that are safe to repeat, use exponential backoff with a bound, and honor cancellation promptly.

Make the boundary testable

Wrap the experimental client behind an interface that returns a structured result: final URL, transport status, HTTP status, selected headers, byte count, and body destination. Test it with a local server that emits redirects, slow chunks, truncated bodies, oversized responses, invalid encodings, and error status codes. For TLS cases, use purpose-built test certificates instead of weakening the global policy.

This design lets the rest of the application remain stable if Haiku’s network-services API evolves. More importantly, it prevents a convenient request object from blurring the distinct questions of delivery, HTTP semantics, content safety, and remote identity.

Related:

Sources:

Comments