View Source hackney (hackney v1.23.0)
Summary
Functions
Return the full body sent with the response.
Return the full body sent with the response as long as the body length doesn't go over MaxLength.
Extract raw information from the client context This feature can be useful when you want to create a simple proxy, rerouting on the headers and the status line and continue to forward the connection for example.
close the client
connect a socket and create a client state.
Assign a new controlling process Pid to Client.
return the requested location
pause a response stream, the stream process will hibernate and be woken later by the resume function
peername of the client
make a request
make a request
make a request
make a request
make a request
get request info
resume a paused response stream, the stream process will be awoken
send the request body until eob. It's issued after sending a request using the
request
and send_request
functions.send a multipart body until eof Possible value are :
eof
: end the multipart request{file, Path}
: to stream a file{file, Path, ExtraHeaders}
: to stream a file{data, Name, Content}
: to send a full part{data, Name, Content, ExtraHeaders}
: to send a full part{part, Name, Len}
: to start sending a part with a known length in a streaming fashion{part, Name, Len, ExtraHeader}
: to start sending a part in a streaming fashion{part, Name}
: to start sending a part without length in a streaming fashion{part, Name, ExtraHeader}
: to start sending a part without length in a streaming fashion{part_bin, Bin}
: To send part of part{part, eof}
: To notify the end of the part{mp_mixed, Name, MixedBoundary}
: To notify we start a part with a a mixed multipart content{mp_mixed_eof, MixedBoundary}
: To notify we end a part with a a mixed multipart content
hackney_multipart:len_mp_stream/2
.send a request using the current client state
send a request using the current client state and pass new options to it.
set client options. Options are:
async
: to fetch the response asynchronously{async, once}
: to receive the response asynchronously one time. To receive the next message use the functionhackney:stream_next/1
.{stream_to, pid()}
: to set the pid where the messages of an asynchronous response will be sent.{follow_redirect, bool()}
: if true a redirection will be followed when the response is received synchronously{force_redirect, bool()}
: if true a 301/302 redirection will be followed even on POST.{max_redirect, integer()}
the maximum number of redirections that will be followed
skip the full body. (read all the body if needed).
Stream the response body.
sockname of the client
start a response. Useful if you stream the body by yourself. It will fetch the status and headers of the response. and return
stop to receive asynchronously.
Stream the response body.
Stream the response body.
continue to the next stream message. Only use it when
{async, once}
is set in the client options.Types
-type client() :: #client{start_time :: term(), mod_metrics :: term(), transport :: term(), host :: term(), port :: term(), netloc :: term(), options :: term(), socket :: term(), socket_ref :: term(), request_ref :: term(), dynamic :: term(), pool_handler :: term(), recv_timeout :: term(), follow_redirect :: term(), max_redirect :: term(), force_redirect :: term(), retries :: term(), redirect :: term(), location :: term(), parser :: term(), headers :: term(), state :: term(), response_state :: term(), mp_boundary :: term(), req_type :: term(), expect :: term(), async :: term(), with_body :: term(), max_body :: term(), stream_to :: term(), send_fun :: term(), body_state :: term(), multipart :: term(), req_chunk_size :: term(), buffer :: term(), partial_headers :: term(), version :: term(), clen :: term(), te :: term(), connection :: term(), method :: term(), path :: term(), ctype :: term()}.
-type client_ref() :: term().
Functions
-spec body(client_ref()) -> {ok, binary()} | {error, atom()} | {error, {closed, binary()}}.
-spec body(client_ref(), non_neg_integer() | infinity) -> {ok, binary()} | {error, atom()} | {error, {closed, binary()}}.
-spec cancel_request(client_ref()) -> {ok, {atom(), inet:socket(), binary(), hackney_response:response_state()}} | {error, term()}.
Extract raw information from the client context This feature can be useful when you want to create a simple proxy, rerouting on the headers and the status line and continue to forward the connection for example.
return:{ResponseState, Transport, Socket, Buffer} | {error, Reason}
Response
: waiting_response, on_status, on_headers, on_bodyTransport
: The current transport moduleSocket
: the current socketBuffer
: Data fetched but not yet processed
-spec controlling_process(client_ref(), pid()) -> ok | {error, closed | not_owner | atom()}.
-spec location(client_ref()) -> binary().
-spec pause_stream(client_ref()) -> ok | {error, req_not_found}.
-spec request(term(), url() | binary() | list(), list(), term(), list()) -> {ok, integer(), list(), client_ref()} | {ok, integer(), list(), binary()} | {ok, integer(), list()} | {ok, client_ref()} | {error, term()}.
make a request
Args:- Method>: method used for the request (get, post, ...)
- Url: full url of the request
- Headers Proplists
- Body:
- {form, [{K, V}, ...]}: send a form url encoded
- {multipart, [{K, V}, ...]}: send a form using multipart
- {file, "/path/to/file"}: to send a file
- Bin: binary or iolist
- Options:
[{connect_options, connect_options(), {ssl_options, ssl_options()}, Others]
connect_options()
: The default connect_options are[binary, {active, false}, {packet, raw}])
. For valid options see the gen_tcp options.ssl_options()
: See the ssl options from the ssl module.with_body
: when this option is passed the body is returned directly. The response is{ok, Status, Headers, Body}
max_body
: sets maximum allowed size of the body if with_body is trueasync
: receive the response asynchronously The function return {ok, StreamRef}. When {async, once} is used the response will be received only once. To receive the other messages use the functionhackney:stream_next/1
{path_encode_fun, fun()}
: function used to encode the path. if not set it will usehackney_url:pathencode/1
the function takes the binary path as entry and return a new encoded path.{stream_to, pid()}
: If async is true or once, the response messages will be sent to this PID.{cookie, list() | binary()}
: to set a cookie or a list of cookies.- Others options are:
{follow_redirect, boolean}
: false by default, follow a redirection{max_redirect, integer}
: 5 by default, the maximum of redirection for a request{force_redirect, boolean}
: false by default, to force the redirection even on POST{basic_auth, {binary, binary}}`: HTTP basic auth username and password.</li> <li>`{proxy, proxy_options()}
: to connect via a proxy.insecure
: to perform "insecure" SSL connections and transfers without checking the certificate{checkout_timeout, infinity | integer()}
: timeout used when checking out a socket from the pool, in milliseconds. By default is equal to connect_timeout{connect_timeout, infinity | integer()}
: timeout used when establishing a connection, in milliseconds. Default is 8000{recv_timeout, infinity | integer()}
: timeout used when receiving data over a connection. Default is 5000
follow_redirect
is take in consideration for the redirection. If a valid redirection happen you receive the messages:{redirect, To, Headers
}{see_other, To, Headers}
for status 303 POST requests.
proxy_options()
: options to connect by a proxy:- binary(): url to use for the proxy. Used for basic HTTP proxy
- {Host::binary(), Port::binary}: Host and port to connect, for HTTP proxy
- {socks5, Host::binary(), Port::binary()}: Host and Port to connect to a socks5 proxy.
- {connect, Host::binary(), Port::binary()}: Host and Port to connect to an HTTP tunnel.
hackney:request(Method, ...)
you can also do hackney:Method(...)
if you prefer to use the REST syntax.Return:{ok, ResponseStatus, ResponseHeaders}
: On HEAD request if the response succeeded.{ok, ResponseStatus, ResponseHeaders, Ref}
: When the response succeeded. The request reference is used later to retrieve the body.{ok, ResponseStatus, ResponseHeaders, Body}
: When the optionwith_body
is set to true and the response succeeded.{ok, Ref}
Return the request reference when you decide to stream the request. You can use the returned reference to stream the request body and continue to handle the response.{error, {closed, PartialBody}}
A body was expected but instead the remote closed the response after sending the headers. Equivalent to the curl messageno chunk, no close, no size. Assume close to signal end
.{error, term()}
other errors.
-spec request_info(client_ref()) -> list().
-spec resume_stream(client_ref()) -> ok | {error, req_not_found}.
-spec send_body(client_ref(), term()) -> ok | {error, term()}.
request
and send_request
functions.
-spec send_multipart_body(client_ref(), term()) -> ok | {error, term()}.
eof
: end the multipart request{file, Path}
: to stream a file{file, Path, ExtraHeaders}
: to stream a file{data, Name, Content}
: to send a full part{data, Name, Content, ExtraHeaders}
: to send a full part{part, Name, Len}
: to start sending a part with a known length in a streaming fashion{part, Name, Len, ExtraHeader}
: to start sending a part in a streaming fashion{part, Name}
: to start sending a part without length in a streaming fashion{part, Name, ExtraHeader}
: to start sending a part without length in a streaming fashion{part_bin, Bin}
: To send part of part{part, eof}
: To notify the end of the part{mp_mixed, Name, MixedBoundary}
: To notify we start a part with a a mixed multipart content{mp_mixed_eof, MixedBoundary}
: To notify we end a part with a a mixed multipart content
hackney_multipart:len_mp_stream/2
.
-spec setopts(client_ref(), list()) -> ok.
async
: to fetch the response asynchronously{async, once}
: to receive the response asynchronously one time. To receive the next message use the functionhackney:stream_next/1
.{stream_to, pid()}
: to set the pid where the messages of an asynchronous response will be sent.{follow_redirect, bool()}
: if true a redirection will be followed when the response is received synchronously{force_redirect, bool()}
: if true a 301/302 redirection will be followed even on POST.{max_redirect, integer()}
the maximum number of redirections that will be followed
-spec skip_body(client_ref()) -> ok | {error, atom()}.
-spec skip_multipart(client_ref()) -> ok | {error, term()}.
-spec start_response(client_ref()) -> {ok, integer(), list(), client_ref()} | {ok, client_ref()} | {error, term()}.
-spec stop_async(client_ref()) -> {ok, client_ref()} | {error, req_not_found} | {error, term()}.
-spec stream_body(client_ref()) -> {ok, binary()} | done | {error, term()}.
-spec stream_multipart(client_ref()) -> {headers, list()} | {body, binary()} | eof | end_of_part | {error, term()}.
Stream the response body.
Return:{headers, Headers}
: the part headers{body, Bin}
: part of the contentend_of_part
: end of partmp_mixed
: notify the beginning of a mixed multipart partmp_mixed_eof
: notify the end of a mixed multipart parteof
: notify the end of the multipart request
-spec stream_next(client_ref()) -> ok | {error, req_not_found}.
{async, once}
is set in the client options.