refactor(http3): delegate H3 stack to erlang_quic / quic_h3

Hackney's hand-rolled HTTP/3 framing, QPACK codec, control stream and
QPACK encoder/decoder stream handling are removed in favour of the
quic_h3 module shipped in erlang_quic's feat/http3 branch.

- src/hackney_quic.erl rewritten as a ~270 LOC gen_server adapter that
  translates {quic_h3, Conn, _} events into the existing
  {quic, ConnRef, _} protocol consumed by hackney_conn.
- Public hackney_quic API now exposes send_request/3 (atomic stream
  open + HEADERS) instead of the open_stream/1 + send_headers/4 pair;
  hackney_h3 updated accordingly.
- src/hackney_qpack.erl removed (~622 LOC); QPACK lives in quic_qpack.
- H3 peername/sockname/setopts/peercert now return {error, not_supported}
  since quic_h3 does not expose them.
- rebar.config: quic dep tracks erlang_quic feat/http3 branch.

Author: benoitc

NEWS.md

@@ -1,5 +1,26 @@
 # NEWS
 
+UNRELEASED
+----------
+
+### Refactor
+
+- HTTP/3 is now delegated to the `erlang_quic` library's `quic_h3` module
+  (branch `feat/http3`). Hackney no longer ships its own HTTP/3 framing,
+  QPACK codec, control-stream or unidirectional-stream handling:
+  - `hackney_quic.erl` is now a thin ~270 LOC gen_server adapter that
+    translates `{quic_h3, Conn, _}` events into the existing
+    `{quic, ConnRef, _}' message protocol consumed by `hackney_conn`.
+  - The public `hackney_quic` API now exposes `send_request/3` (atomic
+    stream-open + HEADERS) instead of the separate `open_stream/1` +
+    `send_headers/4` pair; `hackney_h3` updated to use it.
+  - `hackney_qpack.erl` removed (~622 LOC); the QPACK codec lives in
+    `quic_qpack` in the `quic` dependency.
+  - H3 peername/sockname/setopts/peercert now return `{error, not_supported}`:
+    the underlying `quic_h3` connection does not expose them.
+- `rebar.config`: `quic` dependency switched to
+  `{git, "https://github.com/benoitc/erlang_quic.git", {branch, "feat/http3"}}`.
+
 3.2.1 - 2026-03-01
 ------------------
 

guides/http3_guide.md

@@ -17,7 +17,7 @@ Hackney supports HTTP/3, the latest version of HTTP built on QUIC (UDP-based tra
 
 ## Requirements
 
-HTTP/3 support uses a pure Erlang QUIC implementation. QUIC support is available automatically when hackney is compiled - no external dependencies required.
+HTTP/3 support is provided by the [`erlang_quic`](https://github.com/benoitc/erlang_quic) dependency (module `quic_h3`), which handles the QUIC transport, QPACK header compression, HTTP/3 framing, and control streams. Hackney hosts only a thin adapter (`hackney_quic`) that translates `quic_h3` events into the internal connection protocol. No C dependencies, no external binaries required.
 
 ## Quick Start
 

rebar.config

@@ -25,23 +25,18 @@
   {prometheus_gauge, declare, 1},
   {prometheus_histogram, observe, 3},
   {prometheus_histogram, declare, 1},
-  %% quic (HTTP/3 support)
-  {quic, connect, 4},
-  {quic, open_stream, 1},
-  {quic, open_unidirectional_stream, 1},
-  {quic, send_data, 4},
-  {quic, reset_stream, 3},
-  {quic, peername, 1},
-  {quic, sockname, 1},
-  {quic, close, 2},
-  {quic_connection, lookup, 1},
-  %% hackney_quic wrapper functions called by hackney_conn
+  %% quic / quic_h3 (HTTP/3 support)
+  {quic_h3, connect, 3},
+  {quic_h3, request, 2},
+  {quic_h3, send_data, 4},
+  {quic_h3, cancel, 3},
+  {quic_h3, close, 1},
+  %% hackney_quic wrapper functions called by hackney_conn/hackney_h3
   {hackney_quic, connect, 4},
   {hackney_quic, close, 2},
   {hackney_quic, process, 1},
-  {hackney_quic, peername, 1},
-  {hackney_quic, sockname, 1},
-  {hackney_quic, setopts, 2},
+  {hackney_quic, send_request, 3},
+  {hackney_quic, send_data, 4},
   %% hackney_h3 functions called by hackney_conn
   {hackney_h3, send_request, 6},
   {hackney_h3, send_request_headers, 5},
@@ -56,8 +51,9 @@
 {pre_hooks, [{clean, "rm -rf *~ */*~ */*.xfm test/*.beam"}]}.
 
 {deps, [
-        %% Pure Erlang QUIC for HTTP/3 support
-        {quic, "~>0.10.2"},
+        %% Pure Erlang QUIC + HTTP/3 stack
+        {quic, {git, "https://github.com/benoitc/erlang_quic.git",
+                {branch, "feat/http3"}}},
         {idna, "~>7.1.0"},
         {mimerl, "~>1.4"},
         {certifi, "~>2.16.0"},

src/hackney_conn.erl

@@ -1509,26 +1509,23 @@ handle_common({call, From}, sockname, _State, #conn_data{transport = Transport,
     Result = Transport:sockname(Socket),
     {keep_state_and_data, [{reply, From, Result}]};
 
-%% HTTP/3 socket operations
+%% HTTP/3 socket operations — peername/sockname/peercert/setopts not exposed
+%% by the underlying quic_h3 connection.
 handle_common({call, From}, peername, _State,
               #conn_data{h3_conn = H3Conn} = _Data) when H3Conn =/= undefined ->
-    Result = hackney_quic:peername(H3Conn),
-    {keep_state_and_data, [{reply, From, Result}]};
+    {keep_state_and_data, [{reply, From, {error, not_supported}}]};
 
 handle_common({call, From}, sockname, _State,
               #conn_data{h3_conn = H3Conn} = _Data) when H3Conn =/= undefined ->
-    Result = hackney_quic:sockname(H3Conn),
-    {keep_state_and_data, [{reply, From, Result}]};
+    {keep_state_and_data, [{reply, From, {error, not_supported}}]};
 
 handle_common({call, From}, peercert, _State,
               #conn_data{h3_conn = H3Conn} = _Data) when H3Conn =/= undefined ->
-    %% QUIC/HTTP3 does not expose peer certificate through this API
     {keep_state_and_data, [{reply, From, {error, not_supported}}]};
 
-handle_common({call, From}, {setopts, Opts}, _State,
+handle_common({call, From}, {setopts, _Opts}, _State,
               #conn_data{h3_conn = H3Conn} = _Data) when H3Conn =/= undefined ->
-    Result = hackney_quic:setopts(H3Conn, Opts),
-    {keep_state_and_data, [{reply, From, Result}]};
+    {keep_state_and_data, [{reply, From, {error, not_supported}}]};
 
 %% Low-level send operation
 handle_common({call, From}, {send, Data}, _State, #conn_data{transport = Transport, socket = Socket} = _Data)

src/hackney_h3.erl

@@ -39,8 +39,6 @@
     send_body_chunk/4,
     finish_send_body/3,
     %% Stream management
-    new_stream/1,
-    close_stream/2,
     get_stream_state/2,
     update_stream_state/3,
     %% Response parsing
@@ -260,24 +258,19 @@ await_response(ConnRef, StreamId) ->
 -spec send_request(h3_conn(), method(), binary(), binary(), headers(), binary()) ->
     {ok, stream_id(), streams_map()} | {error, term()}.
 send_request(ConnRef, Method, Host, Path, Headers, Body) ->
-    case hackney_quic:open_stream(ConnRef) of
-        {ok, StreamId} ->
-            AllHeaders = build_request_headers(Method, Host, Path, Headers),
-            HasBody = Body =/= <<>> andalso Body =/= [],
-            Fin = not HasBody,
-            case hackney_quic:send_headers(ConnRef, StreamId, AllHeaders, Fin) of
-                ok when HasBody ->
-                    case hackney_quic:send_data(ConnRef, StreamId, Body, true) of
-                        ok ->
-                            {ok, StreamId, #{StreamId => {undefined, waiting_headers}}};
-                        {error, _} = Error ->
-                            Error
-                    end;
+    AllHeaders = build_request_headers(Method, Host, Path, Headers),
+    HasBody = Body =/= <<>> andalso Body =/= [],
+    Fin = not HasBody,
+    case hackney_quic:send_request(ConnRef, AllHeaders, Fin) of
+        {ok, StreamId} when HasBody ->
+            case hackney_quic:send_data(ConnRef, StreamId, Body, true) of
                 ok ->
                     {ok, StreamId, #{StreamId => {undefined, waiting_headers}}};
                 {error, _} = Error ->
                     Error
             end;
+        {ok, StreamId} ->
+            {ok, StreamId, #{StreamId => {undefined, waiting_headers}}};
         {error, _} = Error ->
             Error
     end.
@@ -287,15 +280,10 @@ send_request(ConnRef, Method, Host, Path, Headers, Body) ->
 -spec send_request_headers(h3_conn(), method(), binary(), binary(), headers()) ->
     {ok, stream_id(), streams_map()} | {error, term()}.
 send_request_headers(ConnRef, Method, Host, Path, Headers) ->
-    case hackney_quic:open_stream(ConnRef) of
+    AllHeaders = build_request_headers(Method, Host, Path, Headers),
+    case hackney_quic:send_request(ConnRef, AllHeaders, false) of
         {ok, StreamId} ->
-            AllHeaders = build_request_headers(Method, Host, Path, Headers),
-            case hackney_quic:send_headers(ConnRef, StreamId, AllHeaders, false) of
-                ok ->
-                    {ok, StreamId, #{StreamId => {undefined, waiting_headers}}};
-                {error, _} = Error ->
-                    Error
-            end;
+            {ok, StreamId, #{StreamId => {undefined, waiting_headers}}};
         {error, _} = Error ->
             Error
     end.
@@ -321,17 +309,6 @@ finish_send_body(ConnRef, StreamId, Streams) ->
 %% Stream management
 %%====================================================================
 
-%% @doc Open a new stream for a request.
--spec new_stream(h3_conn()) -> {ok, stream_id()} | {error, term()}.
-new_stream(ConnRef) ->
-    hackney_quic:open_stream(ConnRef).
-
-%% @doc Close a specific stream.
--spec close_stream(h3_conn(), stream_id()) -> ok.
-close_stream(_ConnRef, _StreamId) ->
-    %% HTTP/3 streams are closed when fin is sent/received
-    ok.
-
 %% @doc Get the state of a specific stream.
 -spec get_stream_state(stream_id(), streams_map()) ->
     {ok, {term(), stream_state()}} | {error, not_found}.
@@ -404,24 +381,19 @@ wait_connected(ConnRef, Timeout, StartTime) ->
     end.
 
 do_request(ConnRef, Method, Host, Path, Headers, Body, Timeout) ->
-    case hackney_quic:open_stream(ConnRef) of
-        {ok, StreamId} ->
-            AllHeaders = build_request_headers(Method, Host, Path, Headers),
-            HasBody = Body =/= <<>> andalso Body =/= [],
-            Fin = not HasBody,
-            case hackney_quic:send_headers(ConnRef, StreamId, AllHeaders, Fin) of
-                ok when HasBody ->
-                    case hackney_quic:send_data(ConnRef, StreamId, Body, true) of
-                        ok ->
-                            await_response_loop(ConnRef, StreamId, Timeout, undefined, [], <<>>);
-                        {error, _} = Error ->
-                            Error
-                    end;
+    AllHeaders = build_request_headers(Method, Host, Path, Headers),
+    HasBody = Body =/= <<>> andalso Body =/= [],
+    Fin = not HasBody,
+    case hackney_quic:send_request(ConnRef, AllHeaders, Fin) of
+        {ok, StreamId} when HasBody ->
+            case hackney_quic:send_data(ConnRef, StreamId, Body, true) of
                 ok ->
                     await_response_loop(ConnRef, StreamId, Timeout, undefined, [], <<>>);
                 {error, _} = Error ->
                     Error
             end;
+        {ok, StreamId} ->
+            await_response_loop(ConnRef, StreamId, Timeout, undefined, [], <<>>);
         {error, _} = Error ->
             Error
     end.