hackney_h3 (hackney v4.2.0)

View Source

HTTP/3 support for hackney.

This module provides HTTP/3 functionality using pure Erlang QUIC. It handles stream management, header encoding, and request/response handling for HTTP/3 connections over QUIC.

Usage

   %% Make a simple GET request
   {ok, Status, Headers, Body} = hackney_h3:request(get, "https://cloudflare.com/")
  
   %% Make a request with options
   {ok, Status, Headers, Body} = hackney_h3:request(get, "https://example.com/",
       [{<<"user-agent">>, <<"hackney/2.0">>}], <<>>, #{timeout => 30000})

Summary

Types

body/0
h3_conn/0
headers/0
method/0
response/0
stream_id/0
stream_state/0
streams_map/0
url/0

Functions

await_response(ConnRef, StreamId)

Wait for an HTTP/3 response.

close(ConnRef)

Close the HTTP/3 connection.

close(ConnRef, Reason)

Close the HTTP/3 connection with a reason.

connect(Host, Port)

Connect to an HTTP/3 server.

connect(Host, Port, Opts)

Connect to an HTTP/3 server with options. lsquic handles its own UDP socket creation and DNS resolution.

connect(Host, Port, Opts, Owner)
early_data_accepted(ConnRef)

Whether the server accepted 0-RTT early data, or unknown before the handshake completes.

finish_send_body(ConnRef, StreamId, Streams)

Finish sending body (close stream for writing).

get_fd(Socket)
get_session_ticket(ConnRef)

Return the last session ticket delivered for this connection, or undefined if none has arrived yet. See wait_session_ticket/2 to block until one is available.

get_stream_state(StreamId, Streams)

Get the state of a specific stream.

handle_call(Request, From, State)
handle_cast(Msg, State)
handle_info(Info, State)
handle_timeout(ConnRef, NowMs)
init(_)
is_available()

Check if HTTP/3/QUIC support is available. Always returns true as pure Erlang implementation is always available.

parse_response_headers(Headers)

Parse response headers from a QUIC stream_headers event. Returns {ok, Status, ResponseHeaders} or {error, Reason}.

peercert(ConnRef)
peername(ConnRef)
process(ConnRef)
request(Method, Url)

Make an HTTP/3 request with default options.

request(Method, Url, Headers)

Make an HTTP/3 request with headers.

request(Method, Url, Headers, Body)

Make an HTTP/3 request with headers and body.

request(Method, Url, Headers, Body, Opts)

Make an HTTP/3 request with all options.

reset_stream(ConnRef, StreamId, ErrorCode)
send_body_chunk(ConnRef, StreamId, Data, Fin)

Send a chunk of body data on a stream.

send_data(ConnRef, StreamId, Data, Fin)
send_request(ConnRef, Headers, Fin)
send_request(ConnRef, Method, Host, Path, Headers, Body)

Send a complete HTTP/3 request (headers + body). Returns {ok, StreamId, UpdatedStreams} or {error, Reason}.

send_request_headers(ConnRef, Method, Host, Path, Headers)

Send HTTP/3 request headers only (for streaming body). Returns {ok, StreamId, UpdatedStreams} or {error, Reason}.

sockname(ConnRef)
terminate(Reason, State)
update_stream_state(StreamId, State, Streams)

Update the state of a stream.

wait_session_ticket(ConnRef, Timeout)

Block until a session ticket is delivered to the owner, up to Timeout ms. The caller must be the connection owner (the process that called connect/4). Returns {ok, Ticket} or {error, timeout}.

Types

body/0

-type body() :: binary() | iodata().

h3_conn/0

-type h3_conn() :: reference().

headers/0

-type headers() :: [{binary(), binary()}].

method/0

-type method() :: get | post | put | delete | head | options | patch | atom() | binary().

response/0

-type response() :: {ok, integer(), headers(), binary()} | {error, term()}.

stream_id/0

-type stream_id() :: non_neg_integer().

stream_state/0

-type stream_state() :: waiting_headers | {receiving_body, integer(), headers(), binary()} | done.

streams_map/0

-type streams_map() :: #{stream_id() => {term(), stream_state()}}.

url/0

-type url() :: binary() | string().

Functions

await_response(ConnRef, StreamId)

-spec await_response(reference(), non_neg_integer()) ->
                        {ok, integer(), headers(), binary()} | {error, term()}.

Wait for an HTTP/3 response.

close(ConnRef)

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

Close the HTTP/3 connection.

close(ConnRef, Reason)

-spec close(h3_conn(), term()) -> ok.

Close the HTTP/3 connection with a reason.

connect(Host, Port)

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

Connect to an HTTP/3 server.

connect(Host, Port, Opts)

-spec connect(binary() | string(), inet:port_number(), map()) -> {ok, reference()} | {error, term()}.

Connect to an HTTP/3 server with options. lsquic handles its own UDP socket creation and DNS resolution.

connect(Host, Port, Opts, Owner)

-spec connect(Host, Port, Opts, Owner) -> {ok, reference()} | {error, term()}
                 when
                     Host :: binary() | string(),
                     Port :: inet:port_number(),
                     Opts :: map(),
                     Owner :: pid().

early_data_accepted(ConnRef)

-spec early_data_accepted(reference()) -> boolean() | unknown | {error, term()}.

Whether the server accepted 0-RTT early data, or unknown before the handshake completes.

finish_send_body(ConnRef, StreamId, Streams)

-spec finish_send_body(h3_conn(), stream_id(), streams_map()) -> {ok, streams_map()} | {error, term()}.

Finish sending body (close stream for writing).

get_fd(Socket)

-spec get_fd(gen_udp:socket()) -> {ok, integer()} | {error, term()}.

get_session_ticket(ConnRef)

-spec get_session_ticket(reference()) -> term() | undefined | {error, term()}.

Return the last session ticket delivered for this connection, or undefined if none has arrived yet. See wait_session_ticket/2 to block until one is available.

get_stream_state(StreamId, Streams)

-spec get_stream_state(stream_id(), streams_map()) ->
                          {ok, {term(), stream_state()}} | {error, not_found}.

Get the state of a specific stream.

handle_call(Request, From, State)

handle_cast(Msg, State)

handle_info(Info, State)

handle_timeout(ConnRef, NowMs)

-spec handle_timeout(reference(), non_neg_integer()) -> non_neg_integer() | infinity.

init(_)

is_available()

-spec is_available() -> true.

Check if HTTP/3/QUIC support is available. Always returns true as pure Erlang implementation is always available.

parse_response_headers(Headers)

-spec parse_response_headers(headers()) -> {ok, integer(), headers()} | {error, term()}.

Parse response headers from a QUIC stream_headers event. Returns {ok, Status, ResponseHeaders} or {error, Reason}.

peercert(ConnRef)

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

peername(ConnRef)

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

process(ConnRef)

-spec process(reference()) -> non_neg_integer() | infinity.

request(Method, Url)

-spec request(method(), url()) -> response().

Make an HTTP/3 request with default options.

request(Method, Url, Headers)

-spec request(method(), url(), headers()) -> response().

Make an HTTP/3 request with headers.

request(Method, Url, Headers, Body)

-spec request(method(), url(), headers(), body()) -> response().

Make an HTTP/3 request with headers and body.

request(Method, Url, Headers, Body, Opts)

-spec request(method(), url(), headers(), body(), map()) -> response().

Make an HTTP/3 request with all options.

Options: - timeout: Request timeout in milliseconds (default: 30000) - recv_timeout: Response receive timeout (default: 30000) - follow_redirect: boolean to follow redirects (default: false) - max_redirect: maximum number of redirects to follow (default: 5)

reset_stream(ConnRef, StreamId, ErrorCode)

-spec reset_stream(reference(), non_neg_integer(), non_neg_integer()) -> ok | {error, term()}.

send_body_chunk(ConnRef, StreamId, Data, Fin)

-spec send_body_chunk(h3_conn(), stream_id(), binary(), boolean()) -> ok | {error, term()}.

Send a chunk of body data on a stream.

send_data(ConnRef, StreamId, Data, Fin)

-spec send_data(reference(), non_neg_integer(), iodata(), boolean()) -> ok | {error, term()}.

send_request(ConnRef, Headers, Fin)

-spec send_request(reference(), [{binary(), binary()}], boolean()) ->
                      {ok, non_neg_integer()} | {error, term()}.

send_request(ConnRef, Method, Host, Path, Headers, Body)

-spec send_request(h3_conn(), method(), binary(), binary(), headers(), binary()) ->
                      {ok, stream_id(), streams_map()} | {error, term()}.

Send a complete HTTP/3 request (headers + body). Returns {ok, StreamId, UpdatedStreams} or {error, Reason}.

send_request_headers(ConnRef, Method, Host, Path, Headers)

-spec send_request_headers(h3_conn(), method(), binary(), binary(), headers()) ->
                              {ok, stream_id(), streams_map()} | {error, term()}.

Send HTTP/3 request headers only (for streaming body). Returns {ok, StreamId, UpdatedStreams} or {error, Reason}.

sockname(ConnRef)

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

terminate(Reason, State)

update_stream_state(StreamId, State, Streams)

-spec update_stream_state(stream_id(), {term(), stream_state()}, streams_map()) -> streams_map().

Update the state of a stream.

wait_session_ticket(ConnRef, Timeout)

-spec wait_session_ticket(reference(), timeout()) -> {ok, term()} | {error, timeout}.

Block until a session ticket is delivered to the owner, up to Timeout ms. The caller must be the connection owner (the process that called connect/4). Returns {ok, Ticket} or {error, timeout}.