std/http

std/http is an HTTP client built on libcurl. It exposes four request functions, a Response struct, and two convenience predicates.

Importing

from std.http import get, post, post_json, get_with_headers
from std.http import is_success, is_error, Response

Example

auto r = get("https://example.com/")
if (r is ok) {
    println(r.value.status)         // 200
    println(r.value.content_type)   // "text/html; charset=UTF-8"
    println(is_success(r.value))    // true
}

The Response struct

A successful request yields a Response:

struct Response {
    int    status
    string body
    string content_type
}

Field	Type	Meaning
status	int	HTTP status code
body	string	response body
content_type	string	the Content-Type response header

Functions

Function	Returns	Notes
get(url)	Result<Response>	HTTP GET
post(url, body)	Result<Response>	HTTP POST with a body
post_json(url, body)	Result<Response>	POST with a JSON content type
get_with_headers(...)	Result<Response>	GET with custom request headers
is_success(Response)	bool	true for a successful status
is_error(Response)	bool	true for an error status

Each request returns a Result, so a connection failure (or other transport error) comes back as err rather than crashing:

auto r = get("https://does-not-resolve.example/")
if (r is err) {
    println(r.error)
}

Behavior

• Per-request connections — each call uses its own libcurl handle (no connection pooling).
• Timeout — 30 seconds per request.
• Redirects — followed automatically, up to 10 redirects.
• TLS — uses the system default certificate store.
• Response size — the response buffer is capped at 64 MiB to guard against a runaway server.
• Content-Type — scanned case-insensitively from the response headers (last value wins).
• libcurl’s global initialization is lazy — it runs once on the first request, so pluvial startup does not pay the cost when std/http is unused.

Building

std/http requires libcurl. The build picks up -lcurl from curl-config --libs and the include path from curl-config --cflags. On macOS the system libcurl works with -lcurl alone.