| Overview |  |
abstract datatype: client()
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() = #{code := timeout | redirect | url | connect | request | body | cancelled | unknown, reason := binary()}
feature() = cookies | gzip
abstract datatype: handle()
header() = {binary(), binary()}
method() = options | get | post | put | delete | head | trace | connect | patch
proxy_config() = [{http | https | all, proxy_spec()}]
proxy_spec() = #{url := binary(), basic_auth => {Username::binary(), Password::binary()}}
read_opts() = #{period => timeout_ms(), length => pos_integer()}
req_opts() = #{url := binary(), method := method(), headers => [header()], body => iodata() | stream, response_body => complete | stream, timeout => timeout_ms()}
req_opts_optional() = #{headers => [header()], body => iodata() | stream, timeout => timeout_ms(), body => iodata() | stream, response_body => complete | stream}
resp() = #{status := 100..599, body := binary() | handle(), headers := [header()]}
timeout_ms() = non_neg_integer() | infinity
| cancel/1 | Used to cancel streaming of a request or response body. |
| close_client/1 | Close a client and idle connections in its pool. |
| delete/3 | Convenience wrapper for req/2. |
| feature/1 | Determines whether a compile-time feature is available. |
| finish_send/1 | Complete sending the request body. |
| get/2 | Convenience wrapper for req/2. |
| get/3 | Convenience wrapper for req/2. |
| make_client/0 | Equivalent to make_client(#{}). |
| make_client/1 | Make a new client with its own connection pool. |
| patch/3 | Convenience wrapper for req/2. |
| post/3 | Convenience wrapper for req/2. |
| put/3 | Convenience wrapper for req/2. |
| read/1 | Equivalent to read(Handle, #{}). |
| read/2 | Read a chunk of the response body, waiting for at most period ms or
until at least length bytes have been read. |
| req/2 | Make a synchronous request. |
| send/2 | Stream a chunk of the request body. |
| start_client/1 | Equivalent to start_client(Name, #{}). |
| start_client/2 | Start a client registered under Name. |
| stop_client/1 | Unregisters and calls close_client/1 on a named client. |
cancel(Handle::handle()) -> ok
Used to cancel streaming of a request or response body.
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(Client::client() | atom(), Url::binary(), Opts::req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}
Convenience wrapper for req/2.
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.
Complete sending the request body. Awaits the server's reply. Return
values are as described for req/2.
Convenience wrapper for req/2.
get(Client::client() | atom(), Url::binary(), Opts::req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}
Convenience wrapper for req/2.
make_client() -> client()
Equivalent to make_client(#{}).
make_client(Opts::client_opts()) -> client()
Make a new client with its own connection pool. See also start_client/2.
patch(Client::client() | atom(), Url::binary(), Opts::req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}
Convenience wrapper for req/2.
post(Client::client() | atom(), Url::binary(), Opts::req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}
Convenience wrapper for req/2.
put(Client::client() | atom(), Url::binary(), Opts::req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}
Convenience wrapper for req/2.
Equivalent to read(Handle, #{}).
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(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 setbody 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.
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(Name::atom()) -> ok
Equivalent to start_client(Name, #{}).
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(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