A pure-Mojo HTTP/1.1 and HTTP/2 client with HTTPS support. No OpenSSL, no libcurl — TLS is handled entirely by the tls package.
GET,POST,PUT,DELETE,PATCH- HTTP and HTTPS (TLS 1.3 + TLS 1.2); HTTP/2 over TLS is negotiated with ALPN
get_many: several URLs on one HTTP/2 host in flight at once- Total request deadline, opt-in retries with backoff, configurable size limits
- Custom headers and request body
- Connection pooling (keep-alive) for repeated requests to the same host
- CA bundle loaded from system (
/etc/ssl/certs/ca-certificates.crtor/etc/ssl/cert.pem) HttpClientwith lazy-loaded, cached CA bundle (146 system certs parsed once per client)
from http_client import HttpClient
var client = HttpClient()
# Simple GET
var resp = client.get("https://api.example.com/data")
print(resp.status_code) # 200
print(resp.body)
# POST with JSON body
var resp2 = client.post(
"https://api.example.com/items",
body='{"name": "test"}',
headers='Content-Type: application/json\r\n'
)
# Parse a JSON response
var data = resp.json() # mutable JsonValue tree
var doc = resp.json_doc() # read-only JsonDoc: faster, compact, lookups are views
print(doc.get_string("name"))var data = List[UInt8]() # Parquet, an image, ...
...
var h = HttpHeaders()
h.add("Content-Type", "application/octet-stream")
# List[UInt8] or Span[UInt8]: no String wrapping, no copy on the way in
var r = client.put("https://store.example.com/obj", data, h)
# any method; follows redirects like get() (a 303 turns it into a GET)
var r2 = client.request("PUT", "https://store.example.com/obj", Span(data), h)
# the response body as bytes: a view of `body` (no copy), or an owned copy
var bytes_view = r.content()
var owned = r.to_bytes()default_content_type ("application/json") still applies to a body sent without a Content-Type; set it to "" for binary uploads that set their own.
All off or at their old values by default; set them on the client:
var client = HttpClient()
client.total_timeout_secs = 10 # whole call: redirects, retries, body (TimeoutError)
client.max_retries = 3 # connect/read failures and 429/502/503/504
client.retry_backoff_ms = 200 # doubles per attempt, jittered, capped at 30 s
# Retry-After (seconds) is honoured. POST/PATCH are retried only with
# client.retry_non_idempotent = True (a retry can repeat side effects).
client.max_response_bytes = 10 * 1024 * 1024 # default 100 MB
client.max_header_bytes = 64 * 1024 # default 1 MB
# Several URLs on one HTTP/2 host share a connection and run concurrently:
var urls = List[String]()
urls.append("https://example.com/a")
urls.append("https://example.com/b")
var responses = client.get_many(urls) # same order as urlstotal_timeout_secs caps every read to the time left (whole seconds). If a
retry's wait would pass the deadline, the last response is returned.
A request that fails on a pooled keep-alive connection is sent again on a new
one only if it is idempotent (GET, HEAD, OPTIONS, PUT, DELETE) or
retry_non_idempotent is set: the server may already have processed it.
max_batch_bytes (default 1 GB) bounds the bodies one get_many holds.
Responses in gzip, deflate, zstd and brotli are decompressed transparently. The libraries are opened at runtime, so a program using requests needs no linker flags:
- gzip / deflate: the system zlib
- zstd: libzstd from the Mojo environment (or the system)
- brotli: libbrotlidec, used only when installed (
pixi add brotli,apt install libbrotli1orbrew install brotli)
Accept-Encoding lists only the encodings whose library loaded, so a server
never sends one the client cannot decode.
- Mojo
>=1.2.0(for Mojo 1.0 / 1.1, use requests 1.5.0) - No C compiler or linker flags: every dependency is pure Mojo, and the compression libraries are opened at runtime (see Compression)
pixi run test # resilience (40) + framing (51) + client (143 HTTP, 4 HTTPS)
pixi run test-h2-local # HTTP/2 against a local server (30); needs the python `h2` package (pixi installs it)
pixi run test-hpack # 128
pixi run test-h2 # 70MIT — see LICENSE