Skip to content

Latest commit

 

History

History
638 lines (396 loc) · 19 KB

hackney.md

File metadata and controls

638 lines (396 loc) · 19 KB
Raw

Module hackney

Data Types

client()

abstract datatype: client()

client_ref()


client_ref() = term()

url()


url() = #hackney_url{} | binary()

Function Index

body/1Return the full body sent with the response.
body/2Return the full body sent with the response as long as the body length doesn't go over MaxLength.
cancel_request/1Extract raw informations 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/1close the client.
connect/1
connect/2
connect/3connect a socket and create a client state.
connect/4
controlling_process/2Assign a new controlling process Pid to Client.
cookies/1
finish_send_body/1
location/1return the requested location.
pause_stream/1pause a response stream, the stream process will hibernate and be woken later by the resume function.
peername/1peername of the client.
redirect_location/1
request/1make a request.
request/2make a request.
request/3make a request.
request/4make a request.
request/5make a request.
request_info/1get request info.
resume_stream/1resume a paused response stream, the stream process will be awoken.
send_body/2send the request body until eob.
send_multipart_body/2send 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 lengthin 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

Note: You can calculate the full length of a multipart stream using the function hackney_multipart:len_mp_stream/2 .
send_request/2send a request using the current client state.
send_request/3send a request using the current client state and pass new options to it.
setopts/2set client options.
skip_body/1skip the full body.
skip_multipart/1Stream the response body.
sockname/1sockname of the client.
start_response/1start a response.
stop_async/1stop to receive asynchronously.
stream_body/1Stream the response body.
stream_multipart/1Stream the response body.
stream_next/1continue to the next stream message.

Function Details

body/1


body(Ref::client_ref()) -> {ok, binary()} | {error, atom()} | {error, {closed, binary()}}

Return the full body sent with the response.

body/2


body(Ref::client_ref(), MaxLength::non_neg_integer() | infinity) -> {ok, binary()} | {error, atom()} | {error, {closed, binary()}}

Return the full body sent with the response as long as the body length doesn't go over MaxLength.

cancel_request/1


cancel_request(Ref::client_ref()) -> {ok, {atom(), inet:socket(), binary(), hackney_response:response_state()}} | {error, term()}

Extract raw informations 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_body

  • Transport: The current transport module

  • Socket: the current socket

  • Buffer: Data fetched but not yet processed

close/1

close(Ref) -> any()

close the client

connect/1

connect(URL) -> any()

connect/2

connect(Hackney_url, Options) -> any()

connect/3

connect(Transport, Host, Port) -> any()

connect a socket and create a client state.

connect/4

connect(Transport, Host, Port, Options) -> any()

controlling_process/2


controlling_process(Ref::client_ref(), Pid::pid()) -> ok | {error, closed | not_owner | atom()}

Assign a new controlling process Pid to Client.

cookies/1


cookies(Headers::list()) -> list()

finish_send_body/1

finish_send_body(Ref) -> any()

location/1


location(Ref::client_ref()) -> binary()

return the requested location

pause_stream/1


pause_stream(Ref::client_ref()) -> ok | {error, req_not_found}

pause a response stream, the stream process will hibernate and be woken later by the resume function

peername/1

peername(Ref) -> any()

peername of the client

redirect_location/1

redirect_location(Headers) -> any()

request/1


request(URL::url() | binary() | list()) -> {ok, integer(), list(), client_ref()} | {ok, integer(), list()} | {error, term()}

make a request

request/2


request(Method::term(), URL::url() | binary() | list()) -> {ok, integer(), list(), client_ref()} | {ok, integer(), list()} | {error, term()}

make a request

request/3


request(Method::term(), URL::url() | binary() | list(), Headers::list()) -> {ok, integer(), list(), client_ref()} | {ok, integer(), list()} | {error, term()}

make a request

request/4


request(Method::term(), URL::url() | binary() | list(), Headers::list(), Body::term()) -> {ok, integer(), list(), client_ref()} | {ok, integer(), list()} | {error, term()}

make a request

request/5


request(Method::term(), Hackney_url::url() | binary() | list(), Headers0::list(), Body::term(), Options0::list()) -> {ok, integer(), list(), client_ref()} | {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 true

  • async: 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 function hackney:stream_next/1

  • {path_encode_fun, fun()}: function used to encode the path. if not set it will use hackney_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

  • {proxy, proxy_options()}: to connect via a proxy.

  • insecure: to perform "insecure" SSL connections and transfers without checking the certificate

  • {connect_timeout, infinity | integer()}: timeout used when establishing a connection, in milliseconds. Default is 8000

  • {recv_timeout, infinity | integer()}: timeout used when receiving a connection. Default is 5000

Note: if the response is async, only `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.

Note: instead of doing 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, 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 message no chunk, no close, no size. Assume close to signal end.

  • {error, term()} other errors.

request_info/1


request_info(Ref::client_ref()) -> list()

get request info

resume_stream/1


resume_stream(Ref::client_ref()) -> ok | {error, req_not_found}

resume a paused response stream, the stream process will be awoken

send_body/2


send_body(Ref::client_ref(), Body::term()) -> ok | {error, term()}

send the request body until eob. It's issued after sending a request using the request and send_request functions.

send_multipart_body/2


send_multipart_body(Ref::client_ref(), Body::term()) -> ok | {error, term()}

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 lengthin 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

Note: You can calculate the full length of a multipart stream using the function hackney_multipart:len_mp_stream/2 .

send_request/2

send_request(Ref, Req) -> any()

send a request using the current client state

send_request/3

send_request(Ref, Req, Options) -> any()

send a request using the current client state and pass new options to it.

setopts/2


setopts(Ref::client_ref(), Options::list()) -> ok

set client options. Options are:

  • async: to fetch the response asynchronously
  • {async, once}: to receive the response asynchronously once time. To receive the next message use the function hackney: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_body/1


skip_body(Ref::client_ref()) -> ok | {error, atom()}

skip the full body. (read all the body if needed).

skip_multipart/1


skip_multipart(Ref::client_ref()) -> ok | {error, term()}

Stream the response body.

sockname/1

sockname(Ref) -> any()

sockname of the client

start_response/1


start_response(Ref::client_ref()) -> {ok, integer(), list(), client_ref()} | {ok, client_ref()} | {error, term()}

start a response. Useful if you stream the body by yourself. It will fetch the status and headers of the response. and return

stop_async/1


stop_async(Ref::client_ref()) -> ok | {error, req_not_found} | {error, term()}

stop to receive asynchronously.

stream_body/1


stream_body(Ref::client_ref()) -> {ok, binary()} | done | {error, term()}

Stream the response body.

stream_multipart/1


stream_multipart(Ref::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 content

  • end_of_part : end of part

  • mp_mixed: notify the beginning of a mixed multipart part

  • mp_mixed_eof: notify the end of a mixed multipart part

  • eof: notify the end of the multipart request

stream_next/1


stream_next(Ref::client_ref()) -> ok | {error, req_not_found}

continue to the next stream message. Only use it when {async, once} is set in the client options.