Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

http.proxy

import http.proxy

http lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled http.proxy.* needs import http.proxy.

ReverseProxy forwards a request to another server and streams the response back; LoadBalancer spreads those forwards across several backends and stops sending to one that is failing.

Hop-by-hop headers are stripped on the way through, and forwarding headers are added, so the backend can still tell who the original client was.

Classes

ReverseProxy

class http.ReverseProxy

A reverse proxy: takes a request this server received and passes it to an upstream, then passes the upstream’s response back.

var api = http.ReverseProxy('http://127.0.0.1:9000')

server.any('/api/' + '*path', @(request, response) {
  api.handle(request, response)
})

Hop-by-hop headers are stripped in both directions, the forwarding headers an upstream needs to know who the real client is are added, and the response body is streamed rather than buffered - a proxy that holds a whole response in memory is a proxy that falls over on the first large download.

  • printable — has a @to_string(), so echo and print() show something useful

Fields

FieldTypeDescription
upstreamstringThe upstream base URL, e.g. 'http://127.0.0.1:9000'.
strip_prefix?stringA path prefix stripped from the incoming request before it is passed upstream, so /api/users can reach an…
host_header?stringWhat to send upstream as Host.
forward_headersboolWhether to add X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host and RFC 7239’s Forwarded.
trust_proxyboolWhether this proxy itself sits behind another one, and so should extend the forwarding chain it was given…
timeoutnumberHow long to wait for the upstream, in milliseconds.
on_request?functionCalled with (request, upstream_request) before the request goes out, to adjust it.
on_response?functionCalled with (request, upstream_response) once the upstream’s head has arrived and before it is passed on.

Constructor

http.ReverseProxy(upstream: string, options: ?dict)

Parameters

  • upstream (string) — the base URL to forward to
  • options (?dict) — any of the fields above, plus client to supply an HttpClient of your own

ReverseProxy.handle()

http.ReverseProxy.handle(request, response)

Forwards request upstream and writes the upstream’s response into response.

A connection failure becomes 502 Bad Gateway and a timeout 504 Gateway Timeout, which is what those statuses are for - they tell the client the failure was between this server and the next, not in the request.

Parameters

  • request (HttpRequest)
  • response (HttpResponse)

ReverseProxy.to_string()

http.ReverseProxy.to_string()

LoadBalancer

class http.LoadBalancer

Balances requests across several upstreams.

Selection is round-robin, and an upstream that fails is taken out of rotation for recovery_time seconds rather than retried on every request - which is what stops one dead backend from adding its full connect timeout to a share of all traffic.

var pool = http.LoadBalancer([
  'http://10.0.0.1:9000',
  'http://10.0.0.2:9000',
])

server.any('/' + '*path', @(request, response) {
  pool.handle(request, response)
})
  • printable — has a @to_string(), so echo and print() show something useful

Fields

FieldTypeDescription
recovery_timenumberHow long a failed upstream stays out of rotation, in seconds.
max_attemptsnumberHow many upstreams to try before giving up on a request.

Constructor

http.LoadBalancer(upstreams: list, options: ?dict)

Parameters

  • upstreams (list) — base URLs
  • options (?dict) — passed to every ReverseProxy, plus recovery_time and max_attempts

LoadBalancer.handle()

http.LoadBalancer.handle(request, response)

Forwards request to the next healthy upstream.

Parameters

  • request (HttpRequest)
  • response (HttpResponse)

LoadBalancer.healthy_count()

http.LoadBalancer.healthy_count() -> number

How many upstreams are currently in rotation.

Returns number

LoadBalancer.to_string()

http.LoadBalancer.to_string()

2026, Richard Ore and Zuri contributors