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.Equivalent to make_client(#{}).
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.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.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.Equivalent to start_client(Name, #{}).
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
Specs
timeout_ms() :: non_neg_integer() | infinity.
Link to this section Functions
Specs
cancel(handle()) -> ok.
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.Specs
delete(client() | atom(), binary(), req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}.
req/2.
Specs
feature(feature()) -> boolean().
ERQWEST_FEATURES (comma separated list) at build time.
Specs
Complete sending the request body. Awaits the server's reply. Return values are as described forreq/2.
Specs
Convenience wrapper forreq/2.
Specs
get(client() | atom(), binary(), req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}.
req/2.
Specs
make_client() -> client().
Equivalent to make_client(#{}).
Specs
make_client(client_opts()) -> client().
start_client/2.
Specs
patch(client() | atom(), binary(), req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}.
req/2.
Specs
post(client() | atom(), binary(), req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}.
req/2.
Specs
put(client() | atom(), binary(), req_opts_optional()) -> {ok, resp()} | {handle, handle()} | {error, err()}.
req/2.
Specs
Equivalent to read(Handle, #{}).
Specs
Read a chunk of the response body, waiting for at mostperiod 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
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.
Specs
Stream a chunk of the request body. Returnsok 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, #{}).
Specs
start_client(atom(), client_opts()) -> ok.
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.
close_client/1 on a named client. This is potentially expensive and should not be called frequently, see start_client/2 for more details.