Req

HTML & web

Outbound HTTP for the BEAM, in the spirit of Elixir's Req.

Server listens. Req calls out. Use sync get / post / … from Mix-style CLI.* tasks (selm increment) or from request handlers. Browser apps use Http from the client platform.

Req.get "http://127.0.0.1:3000/count" []

Req.post "http://127.0.0.1:3000/items"
    [ Req.header "authorization" token
    , Req.json { title = "hi" }
    ]

A successful round-trip is always Ok, including 4xx / 5xx. Transport failures (bad URL, timeout, connection refused) are Err.

For large responses, prefer stream and fold with Stream.tryFoldl / Stream.stoppableFoldl on the calling process. Closing the stream cancels the underlying request.

Types

Response

type alias Response =
{ statusCode : Int
, headers : List (String, String)
, body : String
, bodyBytes : Bytes
}

One response from a completed HTTP round-trip.

body is the response as a UTF-8 string view of the bytes. bodyBytes is the raw body for binary APIs.

Examples

case Req.get "http://127.0.0.1:3000/count" [] of
    Ok { statusCode, body } ->
        body

    Err err ->
        errorToString err

StreamResponse

type alias StreamResponse =
{ statusCode : Int
, headers : List (String, String)
, body : Stream Bytes
}

Headers plus a lazy byte stream for the response body.

OTP httpc only streams status **200** and **206**; for those, statusCode is 206 when a content-range header is present, otherwise 200. Other statuses still return here with the real code and a finite (often one-chunk) body stream.

Examples

Req.stream "http://127.0.0.1:3000/export" []

Error

type Error
= BadUrl String
| Timeout
| NetworkError String

Why an outbound call never got a response.

Examples

BadUrl "ftp://x"
Timeout
NetworkError "econnrefused"

Setting

type Setting = Setting

One request option (header, body, json, timeout, method, …).

Examples

header "authorization" token

Part

type Part = Part

One part of a multipartBody.

Examples

stringPart "title" "hi"

Values

get

get : String -> List Setting -> Result Error Response

GET url.

Examples

get "http://127.0.0.1:3000/count" []

post

post : String -> List Setting -> Result Error Response

POST url.

Examples

post "http://127.0.0.1:3000/items" [ json { title = "hi" } ]

put

put : String -> List Setting -> Result Error Response

PUT url.

Examples

put "http://127.0.0.1:3000/items/1" [ json { title = "x" } ]

delete

delete : String -> List Setting -> Result Error Response

DELETE url.

Examples

delete "http://127.0.0.1:3000/items/1" []

request

request : String -> List Setting -> Result Error Response

Request with an explicit method (or method in the settings list).

Defaults to GET when no method is set.

Examples

request "http://127.0.0.1:3000/x" [ method "PATCH", json { n = 1 } ]

stream

stream : String -> List Setting -> Result Error StreamResponse

Like request, but returns the body as a Stream Bytes.

Consume on the same process that called stream. Prefer Stream.tryFoldl / Stream.stoppableFoldl. Discarding the stream cancels the HTTP request.

Examples

stream "http://127.0.0.1:3000/export" []

body

body : String -> Setting

Set a raw request body (and default content-type to text/plain unless a content-type header is already present).

Examples

body "hello"

bytesBody

bytesBody : Bytes -> Setting

Set a binary request body (default content-type application/octet-stream unless overridden).

Examples

bytesBody bytes

formBody

formBody : List (String, String) -> Setting

Encode application/x-www-form-urlencoded fields and set the body.

Keys and values are percent-encoded. Sets content-type unless a content-type header is already present.

Examples

formBody [ ( "q", "hat" ), ( "page", "1" ) ]

json

json : a -> Setting

Encode a value as JSON (thoas), set the body, and use application/json unless a content-type header is already present.

Examples

json { title = "hi" }

multipartBody

multipartBody : List Part -> Setting

Build a multipart/form-data body from parts and set the matching content-type (unless a content-type header is already present).

Examples

multipartBody [ stringPart "title" "hi", filePart "file" "/tmp/a.csv" ]

stringPart

stringPart : String -> String -> Part

A text form field.

Examples

stringPart "title" "hi"

bytesPart

bytesPart : String -> String -> Bytes -> Part

A binary file field with an explicit MIME type (filename blob).

Examples

bytesPart "file" "text/csv" bytes

filePart

filePart : String -> String -> Part

A file field read from a filesystem path at send time.

Filename is the path basename; MIME type is application/octet-stream.

Examples

filePart "file" "/tmp/a.csv"

timeout

timeout : Int -> Setting

Request timeout in milliseconds (default 30000).

Examples

timeout 5000

method

method : String -> Setting

Override the HTTP method for request / stream (for example "PATCH").

Examples

method "PATCH"

followRedirects

followRedirects : Bool -> Setting

Follow 3xx redirects via httpc (False by default).

Examples

followRedirects True

retry

retry : Int -> Setting

Extra attempts after a transport failure (timeout / network). 0 means one try total. For stream, retries only apply before response headers arrive.

Examples

retry 2

errorToString

errorToString : Error -> String

Human-readable form of an Error for CLI / logs.

Examples

errorToString Timeout == "timeout"