http

HTTP client. Requests run ONCE unless given a retry policy.

Naming convention: import the module under its bare name (import "http"), reach members with a backslash, and call methods in camelCase: http\someMethod.

Methods

get

Send a GET request; returns {status, body, headers}. opts (curl-style): fail, fail_with_body, fail_early (bool); timeout (seconds, default 30). Retrying is NOT configured here - pass a typed HttpRetry as the retry argument; without one the request runs exactly once.

Signature: http\get(url, [headers], [opts], [retry]) -> HttpResponse - source

Returns: map[string]any

Example:

import "std";
import "http";

// A transport failure (DNS, TLS, timeout) RAISES; a 4xx/5xx does not, it arrives
// as a status. The two are different answers and are handled separately.
try {
    final r = http\get("https://api.github.com/repos/egladman/magus");
    std\print(r.status);
    std\print(r.body.sub(0, 80) + "...");
} catch (e) {
    std\print("request never reached the server");
}

download

GET url and stream the response body straight to dest, returning the HTTP status. The body never becomes a Buzz string, so arbitrary binary (a release tarball, an image layer) survives intact and a large file costs no proportional memory. A non-2xx status writes nothing. Pair it with crypto.sha256_file to verify what you fetched before using it. opts (curl-style): fail, fail_with_body, fail_early (bool); timeout (seconds, default 30). Retrying is NOT configured here - pass a typed HttpRetry as the retry argument; without one the request runs exactly once.

Signature: http\download(url, dest, [headers], [opts], [retry]) -> int - source

Returns: int

post

Send a POST request with body; returns {status, body, headers}. opts (curl-style): fail, fail_with_body, fail_early (bool); timeout (seconds, default 30). Retrying is NOT configured here - pass a typed HttpRetry as the retry argument; without one the request runs exactly once.

Signature: http\post(url, body, [headers], [opts], [retry]) -> HttpResponse - source

Returns: map[string]any

Example:

import "std";
import "http";

// Post JSON. opts carries the curl-style settings; retrying is a separate,
// typed HttpRetry argument, and without one the request runs exactly once.
// Escape { and } as \{ \} so Buzz does not try to interpolate them.
try {
    final r = http\post(
        "https://httpbin.org/post",
        "\{\"target\":\"build\"\}",
        {"Content-Type": "application/json"},
        {"timeout": 10},
        http\HttpRetry{ attempts = 3, delay_ms = 500.0 },
    );
    std\print(r.status);
} catch (e) {
    std\print("post never reached the server");
}

request

Send an HTTP request; returns {status, body, headers}. opts (curl-style): fail, fail_with_body, fail_early (bool); timeout (seconds, default 30). Retrying is NOT configured here - pass a typed HttpRetry as the retry argument; without one the request runs exactly once.

Signature: http\request(method, url, [body], [headers], [opts], [retry]) -> HttpResponse - source

Returns: map[string]any

Example:

import "std";
import "http";

// request lets you pick any method; useful for PUT/PATCH/DELETE.
try {
    final r = http\request(
        "PUT",
        "https://httpbin.org/put",
        "hello",
        { "Content-Type": "text/plain" },
        { "timeout": 10 },
    );
    std\print(r.status);
} catch (e) {
    std\print("request never reached the server");
}

server

Start a static file server in the background from an options map and return the bound port. opts keys: dir (string) serves a single directory; OR mounts (a map of URL-prefix -> dir, e.g. {"/": "docs/gen", "/console/": "console/gen"}) serves multiple roots where a request routes to the LONGEST matching prefix, so "/console/" wins over "/" for a /console/ path and the matched prefix is stripped before the file lookup. Exactly one of dir or mounts is required. port (int, optional) binds that port; 0 (the default) scans upward from 8080 and binds the first available one. Unknown keys are rejected. Serves localhost only and runs until the process exits, so pair it with a blocking call like fs.watch.

Signature: http\server(opts) -> int - source

Returns: int

Example:

import "std";
import "http";

// Serve the current build output over http on port 8080 for quick sharing.
// Blocks until the process exits; raises when the port is already taken.
try {
    http\server({"dir": "dist/", "port": 8080});
} catch (e) {
    std\print("port 8080 is not available");
}

byteSize

Byte length of the file at path. The companion to uploadChunked: the size a Content-Range needs, which len() on a Buzz string cannot give for binary data.

Signature: http\byteSize(path) -> int

Returns: int

upload_chunked

Send the file at src as the request body. chunk_size > 0 sends it in slices (capped at 32 MiB), each carrying a Content-Range header - the resumable-upload convention GitHub Actions Cache and RFC 7233 servers expect; chunk_size <= 0 sends it in one request. Returns the final [status, body].

Signature: http\upload_chunked(method, url, src, chunk_size, [headers]) -> any

Returns: any