`http_proxy`

http_proxy starts a local reverse proxy for development servers. It forwards ordinary HTTP requests and WebSocket upgrades through one public origin, avoiding browser CORS configuration when the client and backend use separate servers.

load("@http@1", "http_proxy")

http_proxy(
    "http://127.0.0.1:4321",
    [
        ("/greeter", "http://127.0.0.1:8001/greeter"),
        ("/", "http://127.0.0.1:8002"),
    ],
)

The proxy is a long-running root task. Declare the frontend and backend development servers as independent tasks in the same entrypoint; all three start concurrently.

Arguments

Argument	Required	Description
`listen`	Yes	Absolute `http://` URL with an explicit nonzero port.
`routes`	Yes	Non-empty ordered list of `(path prefix, target URL)` string tuples.
`deps`	No	Dependencies that must complete before the proxy starts serving. Defaults to `[]`.

Routes use declaration order. A prefix matches its exact path or a child path separated by /; /greeter does not match /greeterish. / is the catch-all route. Unmatched requests return HTTP 404.

The matched prefix is replaced by the target URL path. For example, ("/api", "http://127.0.0.1:8001/backend") maps /api/users?id=1 to /backend/users?id=1. Queries are preserved exactly. Route prefixes must be canonical, unescaped paths without a trailing slash. Requests containing encoded / or \ path separators return HTTP 400.

Targets may use HTTP or HTTPS. The proxy connects directly rather than using process proxy environment variables, verifies normal HTTPS certificates, sets the upstream Host, and replaces client-supplied forwarding headers with trusted X-Forwarded-For, X-Forwarded-Host, and X-Forwarded-Proto values. An unavailable target returns HTTP 502.

WebSocket handshakes and upgraded connections use the same routing and path replacement rules. Canceling the xx run closes the listener, ordinary requests, idle upstream connections, and active upgraded tunnels.