Popcorn.Fetch (Popcorn v0.4.0-next.3)

View Source

Sends HTTP requests through the browser's fetch() API.

Using Req

Req is optional. If your application includes Req, Popcorn installs this adapter when it starts inside the Popcorn runtime. Popcorn preserves any adapter in Req's :default_options configuration. The adapter supports Req versions from 0.5.0 through 0.8.0-rc.0.

You can also select the adapter per request:

Req.get!("https://api.example.com/status", adapter: Popcorn.Fetch.adapter())

The adapter supports Req's :into functions, collectables, and :self streams.

It buffers request bodies before upload. The :receive_timeout option limits the wait for each response message and defaults to 30_000 ms. Adapter failures return Req.TransportError exceptions through Req's normal error handling.

Using it without Req

Use request/2 for a response map with a binary body. It does not require Req or decode JSON responses.

Browser limits

  • Cross-origin requests need permission from the target server's CORS policy.
  • The browser follows redirects. Req's :max_redirects and :redirect_log_level options do not control those redirects.
  • The browser decompresses responses. Req's :raw option cannot preserve compressed response bytes.
  • The browser controls restricted headers, such as Host and Cookie.

Summary

Types

error()

A request failure.

request()

A request with a method and URL. Headers are string pairs, and the optional body is a binary.

response()

An HTTP status, browser-visible headers, and a binary response body.

Functions

adapter()

Returns the adapter value for the installed Req version.

request(req, opts \\ [])

Sends an HTTP request and returns the complete response.

Types

error()

@type error() :: :timeout | {:fetch, String.t()} | {:bridge, term()}

A request failure.

  • :timeout - the response exceeded the timeout. The adapter aborts the browser request.
  • {:fetch, message} - the browser reported a network or fetch failure.
  • {:bridge, reason} - JavaScript execution failed. See Popcorn.Wasm.run_js/3.

request()

@type request() :: %{
  :method => String.t(),
  :url => String.t(),
  optional(:headers) => [{String.t(), String.t()}],
  optional(:body) => binary() | nil
}

A request with a method and URL. Headers are string pairs, and the optional body is a binary.

response()

@type response() :: %{
  status: non_neg_integer(),
  headers: [{String.t(), String.t()}],
  body: binary()
}

An HTTP status, browser-visible headers, and a binary response body.

Functions

adapter()

Returns the adapter value for the installed Req version.

request(req, opts \\ [])

@spec request(request(), [{:timeout, timeout()}]) ::
  {:ok, response()} | {:error, error()}

Sends an HTTP request and returns the complete response.

HTTP error statuses, such as 404, still return {:ok, response}. Transport failures return {:error, reason}. See error/0.

Options

  • :timeout - the total response timeout in milliseconds, or :infinity. Defaults to 30000. The adapter aborts the request on timeout.

Example

{:ok, response} = Popcorn.Fetch.request(%{method: "GET", url: "/api/status"})
response.body
#=> ~s({"status":"ready"})