net/http
HTTP/1.1 and verified HTTPS, overall deadlines, cancellation, and native/Wasm transport boundaries.
Send HTTP or HTTPS requests#
Get(url string) and Post(url, contentType, body string) return Result<Response>. A Client supports Do(request Request), Get, and Post. NewRequest(method, url, body string) returns Result<Request>; an empty method means GET. Request and response bodies are owned strings, including binary bytes. No Body.Close call is needed. A non-2xx status is a normal response.
package main;
import "net/http";
import "time";
import "io";
func main() {
client: http.Client;
client.Timeout = 5 * time.Second;
cancel: http.Cancellation;
request := http.NewRequestWithCancel(&cancel, "GET", "https://example.com", "").unwrap();
response := client.Do(request).unwrap();
io.Println(response.StatusCode, " ", response.Body).unwrap();
}
Verify TLS peers#
The default native transport verifies the certificate chain and hostname, requires TLS 1.2 or newer, and uses libcurl’s default trust store. Client.TLSClientConfig.RootCAFile can select a PEM trust bundle for a private CA. There is no option to disable verification. TLS settings apply to the built-in native transport; a custom transport owns its TLS configuration.
Set an overall deadline#
Client.Timeout is a nonnegative nanosecond budget; use time.Second and time.Millisecond. Zero means no deadline. The budget spans preparation, DNS, TCP connect, TLS handshake, upload, and response reading. The default transport polls deadlines/cancellation at intervals of at most 10 ms, subject to operating-system scheduling, clock resolution, and libcurl operations. Timeout errors report "http: timeout exceeded". A positive Request.Deadline uses absolute time.Monotonic() nanoseconds; Do combines it with the client deadline by choosing the earlier value.
Cancel a request#
Cancellation has Cancel() and Canceled() methods; its zero value works. Pass a borrowed token pointer to NewRequestWithCancel(cancel, method, url, body), attach it with request.WithCancel(cancel), or assign Request.Cancel. Another native thread may call Cancel while Do is running. Cancellation is permanent and idempotent, can affect several requests, and returns "http: request canceled". Keep tokens at a stable address, never copy them after use, and keep them alive until every request and canceling thread finishes. This token is separate from threads.Kill.
Headers and response fields#
Request has Method, URL, Header, Body, Cancel, Deadline, and ResponseLimit fields. Do populates Deadline and ResponseLimit for transport implementations. Response has Status (for example "200 OK"), StatusCode, Header, and Body. Header supports Set, Add, Get, Values, and Del. Names are case insensitive. Get returns the first value or an empty string; Values returns an independent array, or an empty array for a missing name. Host, Connection, Content-Length, and Transfer-Encoding request headers are client-controlled.
Limit and validate responses#
Client.MaxResponseBytes is the complete HTTP wire-response limit, including headers and chunk framing. A nonpositive value selects 16 MiB. Headers and trailers have 64 KiB limits. Framed bodies finish without waiting for connection close. The client validates lengths, duplicate transfer encodings, chunk syntax, truncation, and injection attempts. It supports chunked trailers, HEAD, no-body status codes, and up to 16 informational responses. Close-delimited responses require EOF. Paths must already be escaped; fragments are removed. Redirects, IPv6 URL literals, proxies, cookies, compression, pooling, and server APIs are not implemented. Ambient proxy settings are disabled.
Native platform requirements#
The shared libcurl backend targets Linux x86-64/AArch64/RISC-V64, macOS x86-64/AArch64, and Windows x86-64/AArch64. Native programs need libcurl 7.68+ with TLS and asynchronous DNS, an appropriate CA store, and its development/import library. For example, use libcurl4-openssl-dev on Debian/Ubuntu, curl on Homebrew, or the matching curl package in MSYS2 CLANG64/CLANGARM64. Clang and the OS loader must find the library and its shared-library/DLL dependencies. The matching compiler links -lcurl automatically and records that requirement in object-cache metadata. Static HTTP executable links query pkg-config --static --libs libcurl for transitive flags. Install pkg-config and every required static library; distributions may omit static libraries for optional SSH/GSSAPI backends. Linux release installers use a private static libcurl with OpenSSL and c-ares DNS, without those optional backends. Normal program builds and dependency bundles use system libcurl.
Compile for JavaScript/Wasm#
OCOS=js OCARCH=wasm builds the same public HTTP API without libcurl or native synchronization imports. Supply Client.Transport with a RoundTripper implementing RoundTrip(request Request) Result<Response>. Ocean Do is synchronous, while browser Fetch is asynchronous: the host adapter must provide its own Fetch/worker/suspension integration. No built-in synchronous browser Fetch adapter is provided. Without an adapter, requests return "http: WebAssembly requires a host-supplied RoundTripper".
The adapter owns TLS verification, CORS and browser header policy, and must honor Request.Deadline, Request.ResponseLimit, and the borrowed cancellation token. Do checks before and after delegation and bounds the returned body, but cannot interrupt a custom transport that blocks without cooperating. Wasm Cancellation is a single-threaded flag; in-flight cancellation requires an appropriate host execution model. Alongside Ocean’s normal C-runtime imports, provide env.ocean_time_monotonic_ns() -> i64, returning JavaScript BigInt nanoseconds from a monotonic clock such as performance.now(). Client.Do generally imports this clock even when Timeout is zero because the deadline machinery references it.
OCOS=js OCARCH=wasm ocean build . -o app.wasm
Validate native and Wasm behavior#
Unit tests cover API validation, cancellation, header handling, framing, and custom transport dispatch. All library behavior tests are native Ocean *_test.oc files. The Python fixture launcher only creates local CA/server certificates and loopback servers, sets environment configuration, and invokes ocean test net/http. The Ocean tests cover verified HTTPS, rejected trust and hostnames, stalled handshakes/headers/bodies/uploads, deadlines, cancellation, concurrency, and connection failures. Without the launcher, network-dependent tests are explicitly skipped. No external service is contacted. Wasm tests build cold/hot/uncached modules and execute a custom transport in Node, asserting no native transport imports. A separate test assembles the seven monotonic-clock variants. The CI matrix provides native execution jobs for all seven targets.
ocean test net/http time --notty
python3 net/http/tests/integration.py /path/to/ocean-c
python3 net/http/tests/linking.py /path/to/ocean-c
python3 net/http/tests/wasm.py /path/to/ocean-c