hackney (hackney v4.2.3)

View Source

Summary

Types

conn/0
request_ret/0
url/0

Functions

body(ConnPid)

Read the full response body after start_response/1. Consumes the response stream and returns it as a single binary.

body(ConnPid, Timeout)

Same as body/1 with a receive timeout.

checkout(URL)
checkout(URL, Headers)
checkout(URL, Headers, Body)
checkout(URL, Headers, Body, Options)
close(ConnPid)

Close a connection.

connect(URL)
connect(Hackney_url, Options)
connect(Transport, Host, Port)

Connect to a host and return a connection handle (hackney_conn PID).

connect(Transport, Host, Port, Options)
cookies(Headers)

Parse cookies from response headers.

copy(URL)
copy(URL, Headers)
copy(URL, Headers, Body)
copy(URL, Headers, Body, Options)
default_ua()
delete(URL)
delete(URL, Headers)
delete(URL, Headers, Body)
delete(URL, Headers, Body, Options)
finish_send_body(ConnPid)

Finish sending the streaming request body.

get(URL)
get(URL, Headers)
get(URL, Headers, Body)
get(URL, Headers, Body, Options)
get_version()
head(URL)
head(URL, Headers)
head(URL, Headers, Body)
head(URL, Headers, Body, Options)
location(ConnPid)

Get the final URL after following redirects. First checks the stored location (set after redirects), then falls back to the Location header from the last response.

lock(URL)
lock(URL, Headers)
lock(URL, Headers, Body)
lock(URL, Headers, Body, Options)
merge(URL)
merge(URL, Headers)
merge(URL, Headers, Body)
merge(URL, Headers, Body, Options)
mkactivity(URL)
mkactivity(URL, Headers)
mkactivity(URL, Headers, Body)
mkactivity(URL, Headers, Body, Options)
mkcol(URL)
mkcol(URL, Headers)
mkcol(URL, Headers, Body)
mkcol(URL, Headers, Body, Options)
move(URL)
move(URL, Headers)
move(URL, Headers, Body)
move(URL, Headers, Body, Options)
msearch(URL)
msearch(URL, Headers)
msearch(URL, Headers, Body)
msearch(URL, Headers, Body, Options)
notify(URL)
notify(URL, Headers)
notify(URL, Headers, Body)
notify(URL, Headers, Body, Options)
options(URL)
options(URL, Headers)
options(URL, Headers, Body)
options(URL, Headers, Body, Options)
parse_proxy_url(Url)

Parse a proxy URL and extract host, port, and optional credentials. Supports URLs like: - "http://proxy.example.com:8080" - "http://user:pass@proxy.example.com:8080" - "https://admin:secret@secure-proxy.example.com:443" - "socks5://socks.example.com:1080" - "socks5://user:pass@socks.example.com:1080"

patch(URL)
patch(URL, Headers)
patch(URL, Headers, Body)
patch(URL, Headers, Body, Options)
pause_stream(ConnPid)

Pause async streaming.

peercert(ConnPid)

Get the peer SSL certificate. Returns the DER-encoded certificate of the peer, or an error if the connection is not SSL or the certificate is unavailable.

peername(ConnPid)

Get the remote address and port.

post(URL)
post(URL, Headers)
post(URL, Headers, Body)
post(URL, Headers, Body, Options)
propfind(URL)
propfind(URL, Headers)
propfind(URL, Headers, Body)
propfind(URL, Headers, Body, Options)
proppatch(URL)
proppatch(URL, Headers)
proppatch(URL, Headers, Body)
proppatch(URL, Headers, Body, Options)
purge(URL)
purge(URL, Headers)
purge(URL, Headers, Body)
purge(URL, Headers, Body, Options)
put(URL)
put(URL, Headers)
put(URL, Headers, Body)
put(URL, Headers, Body, Options)
redirect_location(Headers)

Get redirect location from headers.

report(URL)
report(URL, Headers)
report(URL, Headers, Body)
report(URL, Headers, Body, Options)
request(URL)

Make a request.

request(Method, URL)
request(Method, URL, Headers)
request(Method, URL, Headers, Body)
request(Method, URL, Headers, Body, Options)

Make a request.

resume_stream(ConnPid)

Resume async streaming.

search(URL)
search(URL, Headers)
search(URL, Headers, Body)
search(URL, Headers, Body, Options)
send_body(ConnPid, Data)

Send a chunk of the request body. Used when request was initiated with body = stream.

send_request(ConnPid, _)

Send a request on an existing connection.

setopts(ConnPid, Options)

Set socket options.

sockname(ConnPid)

Get the local address and port.

start_response(ConnPid)

Start receiving the response after sending the full body. Returns {ok, Status, Headers, ConnPid}.

stop_async(ConnPid)

Stop async mode and return to sync mode.

stream_body(ConnPid)

Read the response body one chunk at a time after start_response/1. Returns {ok, Chunk} per chunk and done when the body is fully consumed.

stream_next(ConnPid)

Request next chunk in {async, once} mode.

subscribe(URL)
subscribe(URL, Headers)
subscribe(URL, Headers, Body)
subscribe(URL, Headers, Body, Options)
trace(URL)
trace(URL, Headers)
trace(URL, Headers, Body)
trace(URL, Headers, Body, Options)
unlock(URL)
unlock(URL, Headers)
unlock(URL, Headers, Body)
unlock(URL, Headers, Body, Options)
unsubscribe(URL)
unsubscribe(URL, Headers)
unsubscribe(URL, Headers, Body)
unsubscribe(URL, Headers, Body, Options)
ws_close(WsPid)

Close WebSocket connection gracefully.

ws_close(WsPid, _)
ws_connect(URL)

Connect to a WebSocket server. URL should use ws:// or wss:// scheme.

ws_connect(URL, Options)
ws_recv(WsPid)

Receive a WebSocket frame (passive mode only). Blocks until a frame is received or timeout. Returns {ok, Frame} or {error, Reason}.

ws_recv(WsPid, Timeout)
ws_send(WsPid, Frame)

Send a WebSocket frame. Frame types: - {text, Data} - Text message - {binary, Data} - Binary message - ping | {ping, Data} - Ping frame - pong | {pong, Data} - Pong frame - close | {close, Code, Reason} - Close frame

ws_setopts(WsPid, Opts)

Set WebSocket options. Supported options: [{active, true | false | once}]

wt_close(WtPid)

Close a WebTransport session gracefully.

wt_close(WtPid, _)
wt_close_stream(WtPid, StreamId)

Close a stream gracefully (send FIN).

wt_connect(URL)

Connect to a WebTransport server.

wt_connect(URL, Options)
wt_open_stream(WtPid, Type)

Open a new stream multiplexed over the session.

wt_recv(WtPid)

Receive the next message on the default channel (passive mode).

wt_recv(WtPid, Timeout)
wt_reset_stream(WtPid, StreamId, ErrorCode)

Abruptly terminate a stream with an error code.

wt_send(WtPid, Frame)

Send on a WebTransport connection. Frame forms: {text, Data}, {binary, Data}, Data (write to the default stream); {datagram, Data}; {stream, StreamId, Data} or {stream, StreamId, Data, fin|nofin}.

wt_send_datagram(WtPid, Data)

Send an unreliable datagram.

wt_session_info(WtPid)

Return WebTransport session information.

wt_setopts(WtPid, Opts)

Set WebTransport options. Supported: [{active, true | false | once}]

wt_stop_sending(WtPid, StreamId, ErrorCode)

Ask the peer to stop sending on a stream.

wt_stream_recv(WtPid, StreamId)

Receive the next chunk on a stream (passive mode).

wt_stream_recv(WtPid, StreamId, Timeout)
wt_stream_send(WtPid, StreamId, Data)

Write to a stream (no FIN).

wt_stream_send(WtPid, StreamId, Data, Fin)

Write to a stream, optionally closing the write side (FIN).

Types

conn/0

-type conn() :: pid().

request_ret/0

-type request_ret() ::
          {ok, integer(), list(), binary()} | {ok, integer(), list()} | {ok, conn()} | {error, term()}.

url/0

-type url() ::
          #hackney_url{transport :: atom(),
                       scheme :: atom() | binary(),
                       netloc :: binary(),
                       raw_path :: binary() | undefined,
                       path :: binary() | undefined | nil,
                       qs :: binary(),
                       fragment :: binary(),
                       host :: string(),
                       port :: integer() | undefined,
                       user :: binary(),
                       password :: binary()} |
          binary().

Functions

body(ConnPid)

-spec body(conn()) -> {ok, binary()} | {error, term()}.

Read the full response body after start_response/1. Consumes the response stream and returns it as a single binary.

body(ConnPid, Timeout)

-spec body(conn(), timeout()) -> {ok, binary()} | {error, term()}.

Same as body/1 with a receive timeout.

checkout(URL)

checkout(URL, Headers)

checkout(URL, Headers, Body)

checkout(URL, Headers, Body, Options)

close(ConnPid)

-spec close(conn()) -> ok.

Close a connection.

connect(URL)

connect(Hackney_url, Options)

connect(Transport, Host, Port)

-spec connect(module(), string(), inet:port_number()) -> {ok, conn()} | {error, term()}.

Connect to a host and return a connection handle (hackney_conn PID).

connect(Transport, Host, Port, Options)

-spec connect(module(), string(), inet:port_number(), list()) -> {ok, conn()} | {error, term()}.

cookies(Headers)

-spec cookies(list()) -> list().

Parse cookies from response headers.

copy(URL)

copy(URL, Headers)

copy(URL, Headers, Body)

copy(URL, Headers, Body, Options)

default_ua()

delete(URL)

delete(URL, Headers)

delete(URL, Headers, Body)

delete(URL, Headers, Body, Options)

finish_send_body(ConnPid)

-spec finish_send_body(conn()) -> ok | {error, term()}.

Finish sending the streaming request body.

get(URL)

get(URL, Headers)

get(URL, Headers, Body)

get(URL, Headers, Body, Options)

get_version()

head(URL)

head(URL, Headers)

head(URL, Headers, Body)

head(URL, Headers, Body, Options)

location(ConnPid)

-spec location(conn()) -> binary() | undefined.

Get the final URL after following redirects. First checks the stored location (set after redirects), then falls back to the Location header from the last response.

lock(URL)

lock(URL, Headers)

lock(URL, Headers, Body)

lock(URL, Headers, Body, Options)

merge(URL)

merge(URL, Headers)

merge(URL, Headers, Body)

merge(URL, Headers, Body, Options)

mkactivity(URL)

mkactivity(URL, Headers)

mkactivity(URL, Headers, Body)

mkactivity(URL, Headers, Body, Options)

mkcol(URL)

mkcol(URL, Headers)

mkcol(URL, Headers, Body)

mkcol(URL, Headers, Body, Options)

move(URL)

move(URL, Headers)

move(URL, Headers, Body)

move(URL, Headers, Body, Options)

msearch(URL)

msearch(URL, Headers)

msearch(URL, Headers, Body)

msearch(URL, Headers, Body, Options)

notify(URL)

notify(URL, Headers)

notify(URL, Headers, Body)

notify(URL, Headers, Body, Options)

options(URL)

options(URL, Headers)

options(URL, Headers, Body)

options(URL, Headers, Body, Options)

parse_proxy_url(Url)

-spec parse_proxy_url(binary() | string()) ->
                         {ok,
                          #{scheme := atom(),
                            host := string(),
                            port := inet:port_number(),
                            user := binary() | undefined,
                            password := binary() | undefined}} |
                         {error, invalid_proxy_url}.

Parse a proxy URL and extract host, port, and optional credentials. Supports URLs like: - "http://proxy.example.com:8080" - "http://user:pass@proxy.example.com:8080" - "https://admin:secret@secure-proxy.example.com:443" - "socks5://socks.example.com:1080" - "socks5://user:pass@socks.example.com:1080"

Returns a map with keys: scheme, host, port, user, password Fixes issue #741: Extract proxy basic auth from URL

patch(URL)

patch(URL, Headers)

patch(URL, Headers, Body)

patch(URL, Headers, Body, Options)

pause_stream(ConnPid)

-spec pause_stream(conn()) -> ok.

Pause async streaming.

peercert(ConnPid)

-spec peercert(conn()) -> {ok, binary()} | {error, term()}.

Get the peer SSL certificate. Returns the DER-encoded certificate of the peer, or an error if the connection is not SSL or the certificate is unavailable.

peername(ConnPid)

-spec peername(conn()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, term()}.

Get the remote address and port.

post(URL)

post(URL, Headers)

post(URL, Headers, Body)

post(URL, Headers, Body, Options)

propfind(URL)

propfind(URL, Headers)

propfind(URL, Headers, Body)

propfind(URL, Headers, Body, Options)

proppatch(URL)

proppatch(URL, Headers)

proppatch(URL, Headers, Body)

proppatch(URL, Headers, Body, Options)

purge(URL)

purge(URL, Headers)

purge(URL, Headers, Body)

purge(URL, Headers, Body, Options)

put(URL)

put(URL, Headers)

put(URL, Headers, Body)

put(URL, Headers, Body, Options)

redirect_location(Headers)

Get redirect location from headers.

report(URL)

report(URL, Headers)

report(URL, Headers, Body)

report(URL, Headers, Body, Options)

request(URL)

-spec request(url()) -> request_ret().

Make a request.

request(Method, URL)

-spec request(atom() | binary(), url()) -> request_ret().

request(Method, URL, Headers)

-spec request(atom() | binary(), url(), list()) -> request_ret().

request(Method, URL, Headers, Body)

-spec request(atom() | binary(), url(), list(), term()) -> request_ret().

request(Method, URL, Headers, Body, Options)

-spec request(atom() | binary(), url(), list(), term(), list()) -> request_ret().

Make a request.

Args: - Method: HTTP method (get, post, put, delete, etc.) - URL: Full URL or parsed hackney_url record - Headers: List of headers - Body: Request body (binary, iolist, {form, KVs}, {file, Path}, etc.) - Options: Request options

Options: - async: true | once - Receive response asynchronously - stream_to: PID to receive async messages - follow_redirect: Follow redirects automatically - max_redirect: Maximum number of redirects (default 5) - location_trusted: If true, forward auth credentials on cross-host redirects (default false) - pool: Pool name or false for no pooling - connect_timeout: Connection timeout in ms (default 8000) - recv_timeout: Receive timeout in ms (default 5000)

Returns: - {ok, Status, Headers, Body}: Success with response body - {ok, Status, Headers}: HEAD request - {ok, Ref}: Async mode - use stream_next/1 to receive messages - {ok, ConnPid}: Streaming body mode (body = stream) - use send_body/2, finish_send_body/1 - {error, Reason}: Error

Note: The with_body option is deprecated and ignored. Body is always returned directly.

resume_stream(ConnPid)

-spec resume_stream(conn()) -> ok.

Resume async streaming.

search(URL)

search(URL, Headers)

search(URL, Headers, Body)

search(URL, Headers, Body, Options)

send_body(ConnPid, Data)

-spec send_body(conn(), iodata()) -> ok | {error, term()}.

Send a chunk of the request body. Used when request was initiated with body = stream.

send_request(ConnPid, _)

-spec send_request(conn(), {atom(), binary(), list(), term()}) ->
                      {ok, integer(), list(), conn()} | {ok, integer(), list()} | {error, term()}.

Send a request on an existing connection.

setopts(ConnPid, Options)

-spec setopts(conn(), list()) -> ok | {error, term()}.

Set socket options.

sockname(ConnPid)

-spec sockname(conn()) -> {ok, {inet:ip_address(), inet:port_number()}} | {error, term()}.

Get the local address and port.

start_response(ConnPid)

-spec start_response(conn()) -> {ok, integer(), list(), conn()} | {error, term()}.

Start receiving the response after sending the full body. Returns {ok, Status, Headers, ConnPid}.

stop_async(ConnPid)

-spec stop_async(conn()) -> ok | {error, term()}.

Stop async mode and return to sync mode.

stream_body(ConnPid)

-spec stream_body(conn()) -> {ok, binary()} | done | {error, term()}.

Read the response body one chunk at a time after start_response/1. Returns {ok, Chunk} per chunk and done when the body is fully consumed.

stream_next(ConnPid)

-spec stream_next(conn()) -> ok.

Request next chunk in {async, once} mode.

subscribe(URL)

subscribe(URL, Headers)

subscribe(URL, Headers, Body)

subscribe(URL, Headers, Body, Options)

trace(URL)

trace(URL, Headers)

trace(URL, Headers, Body)

trace(URL, Headers, Body, Options)

unlock(URL)

unlock(URL, Headers)

unlock(URL, Headers, Body)

unlock(URL, Headers, Body, Options)

unsubscribe(URL)

unsubscribe(URL, Headers)

unsubscribe(URL, Headers, Body)

unsubscribe(URL, Headers, Body, Options)

ws_close(WsPid)

-spec ws_close(pid()) -> ok.

Close WebSocket connection gracefully.

ws_close(WsPid, _)

-spec ws_close(pid(), {integer(), binary()}) -> ok.

ws_connect(URL)

-spec ws_connect(binary() | string()) -> {ok, pid()} | {error, term()}.

Connect to a WebSocket server. URL should use ws:// or wss:// scheme.

Options:

  • active: false | true | once (default false)
  • headers: Extra headers for upgrade request
  • protocols: Sec-WebSocket-Protocol values
  • connect_timeout: Connection timeout in ms (default 8000)
  • recv_timeout: Receive timeout in ms (default infinity)
  • connect_options: Options passed to transport connect
  • ssl_options: Additional SSL options

Returns {ok, WsPid} on success, where WsPid is the hackney_ws process.

ws_connect(URL, Options)

-spec ws_connect(binary() | string(), list()) -> {ok, pid()} | {error, term()}.

ws_recv(WsPid)

-spec ws_recv(pid()) -> {ok, hackney_ws:ws_frame()} | {error, term()}.

Receive a WebSocket frame (passive mode only). Blocks until a frame is received or timeout. Returns {ok, Frame} or {error, Reason}.

ws_recv(WsPid, Timeout)

-spec ws_recv(pid(), timeout()) -> {ok, hackney_ws:ws_frame()} | {error, term()}.

ws_send(WsPid, Frame)

-spec ws_send(pid(), hackney_ws:ws_frame()) -> ok | {error, term()}.

Send a WebSocket frame. Frame types: - {text, Data} - Text message - {binary, Data} - Binary message - ping | {ping, Data} - Ping frame - pong | {pong, Data} - Pong frame - close | {close, Code, Reason} - Close frame

ws_setopts(WsPid, Opts)

-spec ws_setopts(pid(), list()) -> ok | {error, term()}.

Set WebSocket options. Supported options: [{active, true | false | once}]

wt_close(WtPid)

-spec wt_close(pid()) -> ok.

Close a WebTransport session gracefully.

wt_close(WtPid, _)

-spec wt_close(pid(), {non_neg_integer(), binary()}) -> ok.

wt_close_stream(WtPid, StreamId)

-spec wt_close_stream(pid(), non_neg_integer()) -> ok | {error, term()}.

Close a stream gracefully (send FIN).

wt_connect(URL)

-spec wt_connect(binary() | string()) -> {ok, pid()} | {error, term()}.

Connect to a WebTransport server.

The URL must use the https:// scheme (wss:// is accepted as an alias so existing ws_* code can switch over by changing only the function name). WebTransport always runs over TLS.

Options:

  • transport: h3 (default) or h2
  • active: false | true | once (default false)
  • headers: extra headers for the CONNECT request
  • connect_timeout: connection timeout in ms (default 8000)
  • recv_timeout: default receive timeout in ms (default infinity)
  • ssl_options: TLS options (verify, cacerts/cacertfile, cert/certfile, key/keyfile)
  • verify: verify_peer (default) | verify_none
  • compat_mode: latest (default) | legacy_browser_compat
  • max_recv_buffer: passive buffer cap in bytes (default 64 MiB)

Returns {ok, WtPid} on success, where WtPid is the hackney_wt process.

wt_connect(URL, Options)

-spec wt_connect(binary() | string(), list()) -> {ok, pid()} | {error, term()}.

wt_open_stream(WtPid, Type)

-spec wt_open_stream(pid(), bidi | uni) -> {ok, non_neg_integer()} | {error, term()}.

Open a new stream multiplexed over the session.

wt_recv(WtPid)

-spec wt_recv(pid()) -> {ok, hackney_wt:wt_msg()} | {error, term()}.

Receive the next message on the default channel (passive mode).

wt_recv(WtPid, Timeout)

-spec wt_recv(pid(), timeout()) -> {ok, hackney_wt:wt_msg()} | {error, term()}.

wt_reset_stream(WtPid, StreamId, ErrorCode)

-spec wt_reset_stream(pid(), non_neg_integer(), non_neg_integer()) -> ok | {error, term()}.

Abruptly terminate a stream with an error code.

wt_send(WtPid, Frame)

-spec wt_send(pid(), hackney_wt:wt_frame()) -> ok | {error, term()}.

Send on a WebTransport connection. Frame forms: {text, Data}, {binary, Data}, Data (write to the default stream); {datagram, Data}; {stream, StreamId, Data} or {stream, StreamId, Data, fin|nofin}.

wt_send_datagram(WtPid, Data)

-spec wt_send_datagram(pid(), iodata()) -> ok | {error, term()}.

Send an unreliable datagram.

wt_session_info(WtPid)

-spec wt_session_info(pid()) -> {ok, map()} | {error, term()}.

Return WebTransport session information.

wt_setopts(WtPid, Opts)

-spec wt_setopts(pid(), list()) -> ok | {error, term()}.

Set WebTransport options. Supported: [{active, true | false | once}]

wt_stop_sending(WtPid, StreamId, ErrorCode)

-spec wt_stop_sending(pid(), non_neg_integer(), non_neg_integer()) -> ok | {error, term()}.

Ask the peer to stop sending on a stream.

wt_stream_recv(WtPid, StreamId)

-spec wt_stream_recv(pid(), non_neg_integer()) -> hackney_wt:stream_msg().

Receive the next chunk on a stream (passive mode).

wt_stream_recv(WtPid, StreamId, Timeout)

-spec wt_stream_recv(pid(), non_neg_integer(), timeout()) -> hackney_wt:stream_msg().

wt_stream_send(WtPid, StreamId, Data)

-spec wt_stream_send(pid(), non_neg_integer(), iodata()) -> ok | {error, term()}.

Write to a stream (no FIN).

wt_stream_send(WtPid, StreamId, Data, Fin)

-spec wt_stream_send(pid(), non_neg_integer(), iodata(), fin | nofin) -> ok | {error, term()}.

Write to a stream, optionally closing the write side (FIN).