http

import http

A complete HTTP stack: a client, a server, and the pieces both are built from.

The server is meant to face the internet directly. Everything that is normally the reverse proxy’s job - TLS, static files with byte ranges and conditional requests, response compression, keep-alive, request size limits, timeouts, forwarding-header handling - is here rather than assumed to be somewhere in front.

Making a request

import http

echo http.get('https://example.com').as_text()

The module-level get(), post(), put(), patch(), delete(), head(), options() and trace() all go through one shared client, which keeps its connections open between calls. For anything that needs its own settings - a base URL, an authorization header, a cookie jar, a custom certificate authority

• build a client of your own:

var api = http.client('https://api.example.com', {
  headers: { 'Authorization': 'Bearer ' + token },
})

var user = api.get('/users/me').raise_for_status().as_dict()
api.post('/posts', { title: 'Hello', body: 'World' })

Serving requests

import http

var server = http.server(3000)

server.get('/', @(request, response) {
  response.html('<h1>Hello</h1>')
})

server.get('/users/:id', @(request, response) {
  response.json({ id: request.param('id') })
})

server.serve_files('/static', './public', { cache_age: 86400 })

server.listen()

Routes match literal segments, :name parameters, and a trailing catch-all, with the most specific pattern winning regardless of registration order. use() adds middleware, which runs outermost first and controls whether the rest of the chain runs at all:

server.use(@(request, response, next) {
  if request.header('x-api-key') != key {
    response.json({ error: 'unauthorized' }, 401)
    return
  }
  next()
})

Serving over TLS

var server = http.server(443, '0.0.0.0')
server.load_certs('/etc/certs/site.crt', '/etc/certs/site.key')
server.listen()

Using more than one core

listen() serves connections on the calling thread. serve() runs the same pipeline across a pool of isolates instead, one accept loop handing connections to workers:

# app.zu
import http

def setup(server) {
  server.get('/', @(request, response) {
    response.text('hello from a worker')
  })
}

# main.zu
import http
import .app

http.serve(app.setup, { port: 3000, workers: 8 })

setup runs inside each worker, so everything it reaches for has to be something an isolate can be handed. A module is not: a setup that names an imported module belongs in a module itself, which the isolate resolves by name and whose own imports are resolved again on that side.

What the module handles for you

Requests are parsed strictly: a header name with whitespace before its colon, two disagreeing Content-Length values, a Transfer-Encoding alongside a Content-Length, an obsolete folded header line - each of these is a way to make a proxy and an origin server disagree about where one message ends and the next begins, and each is refused rather than guessed at.

Bodies are decompressed on the way in and compressed on the way out, cookies are parsed and rendered per RFC 6265, dates are read in all three formats HTTP allows and written in the one it requires, and content negotiation follows the quality weights the client actually sent.

Sessions

http.session keeps per-visitor state on the server and finds it again by a cookie:

import http.session

server.use(http.session.session())

server.get('/', @(request, response) {
  var seen = request.session().get('seen', 0)

  request.session().set('seen', seen + 1)
  response.text('visit ${seen + 1}')
})

Sessions are kept in files by default, in a database through http.session.sql, or anywhere else a SessionStore can reach.

The http API

Every public name in http, wherever it is declared. Each links to the page that documents it.

Submodules

Functions

shared_client()

http.shared_client() -> HttpClient

The shared client the module-level request functions use.

Reach for this to change a setting that should apply to every casual http.get() in a program - a proxy-wide certificate authority, a longer timeout - and build your own client() for anything more specific than that.

Returns HttpClient

client()

http.client(base_url: ?string, options: ?dict) -> HttpClient

Builds a new HttpClient.

Parameters

• base_url (?string) — prefixed to any relative request target
• options (?dict) — any HttpClient field, plus headers

Returns HttpClient

set_headers()

http.set_headers(values: dict) -> HttpClient

Sets the default headers on the shared client and returns it, so a call can be chained straight onto it.

echo http.set_headers({ 'Authorization': 'Bearer ' + token })
  .get('https://example.com/me')
  .as_dict()

Parameters

• values (dict)

Returns HttpClient

get()

http.get(url: string, options: ?dict) -> HttpResponse

Sends a GET request through the shared client.

Parameters

• url (string)
• options (?dict) — see HttpClient.request()

Returns HttpResponse

post()

http.post(url: string, data, options: ?dict) -> HttpResponse

Sends a POST request through the shared client.

Parameters

• url (string)
• data (?any) — a string or bytes sent as-is, a dictionary or list sent as JSON, or a MultipartBuilder
• options (?dict)

Returns HttpResponse

put()

http.put(url: string, data, options: ?dict) -> HttpResponse

Sends a PUT request through the shared client.

Parameters

• url (string)
• data (?any)
• options (?dict)

Returns HttpResponse

patch()

http.patch(url: string, data, options: ?dict) -> HttpResponse

Sends a PATCH request through the shared client.

Parameters

• url (string)
• data (?any)
• options (?dict)

Returns HttpResponse

delete()

http.delete(url: string, options: ?dict) -> HttpResponse

Sends a DELETE request through the shared client.

Parameters

• url (string)
• options (?dict)

Returns HttpResponse

head()

http.head(url: string, options: ?dict) -> HttpResponse

Sends a HEAD request through the shared client. Redirects are not followed unless options says to.

Parameters

• url (string)
• options (?dict)

Returns HttpResponse

options()

http.options(url: string, options: ?dict) -> HttpResponse

Sends an OPTIONS request through the shared client.

Parameters

• url (string)
• options (?dict)

Returns HttpResponse

trace()

http.trace(url: string, options: ?dict) -> HttpResponse

Sends a TRACE request through the shared client.

Parameters

• url (string)
• options (?dict)

Returns HttpResponse

server()

http.server(port: ?number, host: ?string) -> HttpServer

Builds an HttpServer.

Parameters

• port (?number) — defaults to 8000
• host (?string) — defaults to '127.0.0.1'

Returns HttpServer

tls_server()

http.tls_server(port: number, cert_chain: string, private_key: string, host: ?string) -> HttpServer

Builds an HttpServer already configured for TLS.

Parameters

• port (number)
• cert_chain (string) — the PEM certificate chain, leaf first
• private_key (string) — the PEM private key
• host (?string)

Returns HttpServer

serve()

http.serve(setup, options: ?dict)

Runs a server across a pool of isolates, one per core by default.

setup is called once inside each worker with that worker’s own HttpServer, and registers the routes, middleware and settings the worker should serve with. It may be defined in the main script or in a module, and may use whatever it imports; an imported module is reloaded inside the worker rather than shared with it, so the worker gets its own copy of that module’s top-level state.

The calling isolate binds the socket and accepts connections, handing each one to a worker. It does not return until the server is stopped.

Parameters

• setup (function(1)) — receives the worker’s HttpServer
• options (?dict) — port (default 8000), host (default '127.0.0.1'), workers (default: the number of CPUs), backlog (how many accepted connections may wait for a free worker), plus cert_chain/private_key for TLS

Raises HttpError if the socket cannot be bound

2026, Richard Ore and Zuri contributors