Module erqwest

Data Types

client()

abstract datatype: client()

client_opts()

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()}

err()

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

feature()

feature() = cookies | gzip

handle()

abstract datatype: handle()

header()

header() = {binary(), binary()}

method()

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

proxy_config()

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

proxy_spec()

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

read_opts()

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

req_opts()

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

req_opts_optional()

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

resp()

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

timeout_ms()

timeout_ms() = non_neg_integer() | infinity

Function Index

cancel/1Used to cancel streaming of a request or response body.
close_client/1Close a client and idle connections in its pool.
delete/3Convenience wrapper for req/2.
feature/1Determines whether a compile-time feature is available.
finish_send/1Complete sending the request body.
get/2Convenience wrapper for req/2.
get/3Convenience wrapper for req/2.
make_client/0Equivalent to make_client(#{}).
make_client/1Make a new client with its own connection pool.
patch/3Convenience wrapper for req/2.
post/3Convenience wrapper for req/2.
put/3Convenience wrapper for req/2.
read/1Equivalent to read(Handle, #{}).
read/2Read a chunk of the response body, waiting for at most period ms or until at least length bytes have been read.
req/2Make a synchronous request.
send/2Stream a chunk of the request body.
start_client/1Equivalent to start_client(Name, #{}).
start_client/2Start a client registered under Name.
stop_client/1Unregisters and calls close_client/1 on a named client.

Function Details

cancel/1

cancel(Handle::handle()) -> ok

Used to cancel streaming of a request or response body.

close_client/1

close_client(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.

delete/3

delete(Client::client() | atom(), Url::binary(), Opts::req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}

Convenience wrapper for req/2.

feature/1

feature(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.

finish_send/1

finish_send(Handle::handle()) -> {ok, resp()} | {error, err()}

Complete sending the request body. Awaits the server's reply. Return values are as described for req/2.

get/2

get(Client::client() | atom(), Url::binary()) -> {ok, resp()} | {handle, handle()} | {error, err()}

Convenience wrapper for req/2.

get/3

get(Client::client() | atom(), Url::binary(), Opts::req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}

Convenience wrapper for req/2.

make_client/0

make_client() -> client()

Equivalent to make_client(#{}).

make_client/1

make_client(Opts::client_opts()) -> client()

Make a new client with its own connection pool. See also start_client/2.

patch/3

patch(Client::client() | atom(), Url::binary(), Opts::req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}

Convenience wrapper for req/2.

post/3

post(Client::client() | atom(), Url::binary(), Opts::req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}

Convenience wrapper for req/2.

put/3

put(Client::client() | atom(), Url::binary(), Opts::req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}

Convenience wrapper for req/2.

read/1

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

Equivalent to read(Handle, #{}).

read/2

read(Handle::handle(), Opts::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.

req/2

req(Client::client() | atom(), Req::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.

send/2

send(Handle::handle(), Data::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.

start_client/1

start_client(Name::atom()) -> ok

Equivalent to start_client(Name, #{}).

start_client/2

start_client(Name::atom(), Opts::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.

stop_client/1

stop_client(Name::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.


Generated by EDoc