HTTP

# crab.toml
[http]
fetch = ["api.example.com", "*.example.org"]

let page = berm_lang::http::fetch(
    "GET",
    "https://api.example.com/items",
    &[("Authorization", "Bearer {secret:EXAMPLE_KEY}")],
    b"",
)?;
let items: Vec<Item> = page.json()?;

Provider clients

Use http::Client { name, headers } to share provider headers and error handling. client.request(method, url, body) returns a successful response or an error including the provider name, status, response body and available retry metadata. client.json::<T>(method, url, body) also decodes JSON. Secret placeholders in the headers remain host-managed.

Provider-specific failures inside a successful JSON response still need checking by the integration. For generated bindings from OpenAPI 3.0 or 3.1, follow Build from OpenAPI.

Requests

• http::fetch sends one request and answers Response { status, headers, body }. A 4xx or 5xx from the far end is a Response, not an error. Redirects are answered, never followed.
• http::fetch_all(&requests) sends a batch of http::Requests at once and answers each in its place: a Response, or why there was none. Each request takes its own timeout, in milliseconds, and limit, the most bytes of the body it takes.
• Every request gives up at the call's deadline.
• http::proxy and http::proxy_all send through the host's proxy, to the hosts declared under [http] proxy. Their bytes are metered as proxied; see Usage.
• A header value or the body may carry {secret:NAME} for a secret the service declares. The host writes the value in, and the service never holds it.
• CallError::Refused means nothing was sent: an undeclared host or secret, or a secret not set.
• On Cloud, a request to a loopback, private or link-local address fails, and an answer's body holds at most 8 MiB.

Hosts

A request reaches only the hosts listed under [http] fetch or [http] proxy. Batch requests use the same lists. An omitted or empty list allows no destinations. Each entry is one of:

• a name, matched whole: api.example.com;
• *.example.com, every subdomain of example.com and not example.com itself;
• *, every host.

Matching ignores ASCII case. A request to a host not declared is refused before anything is sent. The local host refuses a host declared only through a pattern when it is, or resolves only to, a loopback, private or link-local address.

On Cloud, berm.http.fetch refuses any host that is, or resolves to, a loopback, private or link-local address, whether declared by name or through a pattern. Every request a service sends from Cloud carries CrabTalk-Service: <owner id>/<name>, replacing any value the service set.