Http

Http :: # (opaque)

Send requests using the shared roc-lang/http Request and Response types. This module supplies effects and small JSON/UTF-8 conveniences while leaving pure request and response construction to that package.

See the host runtime behavior for HTTP protocol, TLS trust-store, and timeout details.

default_timeout_ms : U64

Finite defaults for ordinary API calls. The host enforces the response limit before allocating the Roc response body.

with_timeout_millis : Config, U64 -> Config

Set the complete deadline, including bounded admission wait. Zero is normalized to one millisecond so every request remains finite.

send! : Request => Try(Response, [InvalidUrl(ParseErr), InvalidRequest(Str), HttpErr(TransportErr), ..])

Validate and send an HTTP request.

The request URI must be an absolute HTTP or HTTPS URL accepted by Url. Invalid URLs return InvalidUrl before any host effect occurs. Fragments are removed because they are client-side identifiers and are not sent.

request = Request.from_method(GET).with_uri("https://www.roc-lang.org")
response = Http.send!(request)?
send_with! : Request, Config => Try(Response, [InvalidUrl(ParseErr), InvalidRequest(Str), HttpErr(TransportErr), ..])

Send using an explicit finite resource policy. A timeout attached to the shared http Request takes precedence; NoTimeout uses this config.

with_json_body : Request, _ => Try(Request, [JsonErr(_), ..])

Encode a value as JSON and set it as the request body.

This uses Roc's builtin JSON encoder, so the value's type determines the encoder through static dispatch.

send_json! : Request, _ => Try(Response, [JsonErr(_), InvalidUrl(ParseErr), InvalidRequest(Str), HttpErr(TransportErr), ..])

Encode a value as JSON, attach it to the request body, and send it.

get_utf8! : Url => Try(Str, [BadBody(Str), InvalidRequest(Str), HttpErr(TransportErr), ..])

Perform an HTTP GET and decode the response body as a UTF-8 Str.

The argument is a validated Url. Quoted literals work through Url.from_quote; dynamic strings should be passed through Url.parse.

hello_str = Http.get_utf8!("http://localhost:8000")?
decode_json_response : Response => Try(_, [BadBody(Str), JsonErr(_), ..])

Decode a response body as JSON.

This uses Roc's builtin JSON parser, so the expected result type determines the parser through static dispatch.

get! : Url => Try(_, [BadBody(Str), InvalidRequest(Str), HttpErr(TransportErr), JsonErr(_), ..])

Perform an HTTP GET and decode the response body as JSON.

The argument is a validated Url. JSON parser failures are returned as JsonErr(_).

payload : Try({ foo : Str }, _)
payload = Http.get!("http://localhost:8000")

Config

:= [
    Config(
        {
            timeout_ms : U64,
            max_response_bytes : U64,
        },
    ),
]

Opaque per-request resource policy.

TransportErr : TransportErr

Errors raised by the host while sending a request, before a real HTTP response is available.