View Source erqwest (erqwest v0.2.5)

Link to this section Summary

Functions

Used to cancel streaming of a request or response body.

Close a client and idle connections in its pool. Returns immediately, but the connection pool will not be cleaned up until all in-flight requests for this client have returned.

Convenience wrapper for req/2.
Determines whether a compile-time feature is available. Enable features by adding them to the environment variable ERQWEST_FEATURES (comma separated list) at build time.
Complete sending the request body. Awaits the server's reply. Return values are as described for req/2.
Convenience wrapper for req/2.
Convenience wrapper for req/2.
Make a new client with its own connection pool. See also start_client/2.
Convenience wrapper for req/2.
Convenience wrapper for req/2.
Convenience wrapper for req/2.
Read a chunk of the response body, waiting for at most period ms or until at least length bytes have been read. length defaults to 8 MB if omitted, and period to infinity. Note that more than length bytes can be returned. Returns {more, binary()} if there is more data to be read, and {ok, binary()} once the body is complete.

Make a synchronous request.

Stream a chunk of the request body. Returns ok once the chunk has successfully been queued for transmission. Note that due to buffering this does not mean that the chunk has actually been sent. Blocks once the internal buffer is full. Call finish_send/1 once the body is complete. {reply, resp()} is returned if the server chooses to reply before the request body is complete.
Start a client registered under Name. The implementation uses persistent_term and is not intended for clients that will be frequently started and stopped. For such uses see make_client/1.
Unregisters and calls close_client/1 on a named client. This is potentially expensive and should not be called frequently, see start_client/2 for more details.

Link to this section Types

Specs

client()

Specs

client_opts() ::
    #{identity => {Pkcs12Der :: binary(), Password :: binary()},
      follow_redirects => boolean() | non_neg_integer(),
      additional_root_certs => [CertDer :: binary()],
      use_built_in_root_certs => boolean(),
      danger_accept_invalid_hostnames => boolean(),
      danger_accept_invalid_certs => boolean(),
      proxy => system | no_proxy | proxy_config(),
      connect_timeout => timeout_ms(),
      timeout => timeout_ms(),
      pool_idle_timeout => timeout_ms(),
      pool_max_idle_per_host => non_neg_integer(),
      https_only => boolean(),
      cookie_store => boolean(),
      gzip => boolean()}.

Specs

err() ::
    #{code := timeout | redirect | url | connect | request | body | cancelled | unknown,
      reason := binary()}.

Specs

feature() :: cookies | gzip.

Specs

handle()

Specs

header() :: {binary(), binary()}.

Specs

method() :: options | get | post | put | delete | head | trace | connect | patch.

Specs

proxy_config() :: [{http | https | all, proxy_spec()}].

Specs

proxy_spec() :: #{url := binary(), basic_auth => {Username :: binary(), Password :: binary()}}.

Specs

read_opts() :: #{period => timeout_ms(), length => pos_integer()}.

Specs

req_opts() ::
    #{url := binary(),
      method := method(),
      headers => [header()],
      body => iodata() | stream,
      response_body => complete | stream,
      timeout => timeout_ms()}.

Specs

req_opts_optional() ::
    #{headers => [header()],
      body => iodata() | stream,
      timeout => timeout_ms(),
      body => iodata() | stream,
      response_body => complete | stream}.

Specs

resp() :: #{status := 100..599, body := binary() | handle(), headers := [header()]}.

Specs

timeout_ms() :: non_neg_integer() | infinity.

Link to this section Functions

Specs

cancel(handle()) -> ok.
Used to cancel streaming of a request or response body.

Specs

close_client(client()) -> ok.

Close a client and idle connections in its pool. Returns immediately, but the connection pool will not be cleaned up until all in-flight requests for this client have returned.

You do not have to call this function, since the client will automatically be cleaned up when it is garbage collected by the VM.

Fails with reason badarg if the client has already been closed.
Link to this function

delete(Client, Url, Opts)

View Source

Specs

delete(client() | atom(), binary(), req_opts_optional()) ->
          {ok, resp()} | {handle, handle()} | {error, err()}.
Convenience wrapper for req/2.

Specs

feature(feature()) -> boolean().
Determines whether a compile-time feature is available. Enable features by adding them to the environment variable ERQWEST_FEATURES (comma separated list) at build time.

Specs

finish_send(handle()) -> {ok, resp()} | {error, err()}.
Complete sending the request body. Awaits the server's reply. Return values are as described for req/2.

Specs

get(client() | atom(), binary()) -> {ok, resp()} | {handle, handle()} | {error, err()}.
Convenience wrapper for req/2.

Specs

get(client() | atom(), binary(), req_opts_optional()) ->
       {ok, resp()} | {handle, handle()} | {error, err()}.
Convenience wrapper for req/2.

Specs

make_client() -> client().

Equivalent to make_client(#{}).

Specs

make_client(client_opts()) -> client().
Make a new client with its own connection pool. See also start_client/2.
Link to this function

patch(Client, Url, Opts)

View Source

Specs

patch(client() | atom(), binary(), req_opts_optional()) ->
         {ok, resp()} | {handle, handle()} | {error, err()}.
Convenience wrapper for req/2.

Specs

post(client() | atom(), binary(), req_opts_optional()) ->
        {ok, resp()} | {handle, handle()} | {error, err()}.
Convenience wrapper for req/2.

Specs

put(client() | atom(), binary(), req_opts_optional()) ->
       {ok, resp()} | {handle, handle()} | {error, err()}.
Convenience wrapper for req/2.

Specs

read(handle()) -> {more, binary()} | {ok, binary()} | {error, err()}.

Equivalent to read(Handle, #{}).

Specs

read(handle(), map() | cancel) -> {more, binary()} | {ok, binary()} | {error, err()}.
Read a chunk of the response body, waiting for at most period ms or until at least length bytes have been read. length defaults to 8 MB if omitted, and period to infinity. Note that more than length bytes can be returned. Returns {more, binary()} if there is more data to be read, and {ok, binary()} once the body is complete.

Specs

req(client() | atom(), req_opts()) -> {ok, resp()} | {handle, handle()} | {error, err()}.

Make a synchronous request.

Fails with reason badarg if any argument is invalid or if the client has already been closed. If you set body to stream, you will get back {handle, handle()}, which you need to pass to send/2 and finish_send/1 to stream the request body. If you set response_body to stream, the body key in resp() be a handle() that you need to pass to read to consume the response body. If you decide not to consume the response body, call cancel/1.

Specs

send(handle(), iodata()) -> ok | {reply, resp()} | {error, err()}.
Stream a chunk of the request body. Returns ok once the chunk has successfully been queued for transmission. Note that due to buffering this does not mean that the chunk has actually been sent. Blocks once the internal buffer is full. Call finish_send/1 once the body is complete. {reply, resp()} is returned if the server chooses to reply before the request body is complete.

Specs

start_client(atom()) -> ok.

Equivalent to start_client(Name, #{}).

Link to this function

start_client(Name, Opts)

View Source

Specs

start_client(atom(), client_opts()) -> ok.
Start a client registered under Name. The implementation uses persistent_term and is not intended for clients that will be frequently started and stopped. For such uses see make_client/1.

Specs

stop_client(atom()) -> ok.
Unregisters and calls close_client/1 on a named client. This is potentially expensive and should not be called frequently, see start_client/2 for more details.