WebTransport for Erlang

An Erlang implementation of the WebTransport protocol over:

• HTTP/3 (draft-ietf-webtrans-http3-17) using native QUIC streams; draft-15 clients are accepted too, and so are draft-07 (Safari 26) and draft-02 (Chrome, Firefox) clients in the default auto mode
• HTTP/2 (draft-ietf-webtrans-http2-16) using RFC 9297 capsules, over TLS 1.3 only

docs/compliance.md lists what is implemented and the known gaps.

WebTransport provides bidirectional communication between a client and server using reliable streams and unreliable datagrams over HTTP/3 or HTTP/2.

Listeners and clients support IPv4 and IPv6 (bind via ip/family; the client accepts IP-literal hosts and address tuples with Happy Eyeballs racing). webtransport:listener_sockname/1 reports the bound address. 0-RTT support covers session-ticket capture and connection-level acceptance reporting (webtransport:early_data_accepted/1); see docs/configuration.md.

Requirements

• Erlang/OTP 27.0 or later
• rebar3
• OpenSSL (for certificate generation)

Installation

Add to your rebar.config:

{deps, [
    {webtransport, {git, "https://github.com/benoitc/erlang-webtransport.git", {branch, "main"}}}
]}.

Fetch and compile:

rebar3 get-deps
rebar3 compile

TLS certificates

WebTransport requires TLS. For local development, generate a self-signed certificate:

openssl req -x509 -newkey rsa:2048 \
  -keyout key.pem -out cert.pem \
  -days 365 -nodes -subj '/CN=localhost'

This produces two files in the current directory:

• cert.pem -- the X.509 certificate
• key.pem -- the unencrypted private key

For production, use certificates from a trusted CA (e.g. Let's Encrypt). The certfile and keyfile options accept absolute or relative file paths.

Quick start

Compile the bundled examples and start a shell with examples/ on the code path:

erlc -o examples examples/echo_server.erl examples/echo_client.erl
ERL_FLAGS="-pa examples" rebar3 shell --apps webtransport

The -pa examples flag is required so that echo_server (or any other handler module you keep outside src/) is reachable from the session process; otherwise session init fails with {handler_not_loaded, echo_server, nofile}.

1. Start the server

{ok, _} = webtransport:start_listener(my_server, #{
    transport => h3,
    port => 4433,
    certfile => "cert.pem",
    keyfile => "key.pem",
    handler => echo_server
}).

2. Connect a client

{ok, Session} = webtransport:connect("localhost", 4433, <<"/echo">>, #{
    transport => h3,
    verify => verify_none
}).

3. Send and receive

%% Open a bidirectional stream
{ok, Stream} = webtransport:open_stream(Session, bidi).

%% Send data
ok = webtransport:send(Session, Stream, <<"hello">>).

%% Receive the echo
receive
    {webtransport, Session, {stream, Stream, bidi, Data}} ->
        io:format("Got: ~s~n", [Data])  %% prints "Got: echo: hello"
after 3000 ->
    io:format("timeout~n")
end.

%% Send a datagram (unreliable)
ok = webtransport:send_datagram(Session, <<"ping">>).

receive
    {webtransport, Session, {datagram, DgData}} ->
        io:format("Got: ~s~n", [DgData])  %% prints "Got: echo: ping"
after 3000 ->
    io:format("timeout~n")
end.

%% Clean up
webtransport:close_session(Session).
webtransport:stop_listener(my_server).

Writing a handler

Handlers implement the webtransport_handler behaviour. The session process calls your handler's callbacks when events occur.

Minimal handler

-module(my_handler).
-behaviour(webtransport_handler).

-export([init/3, handle_stream/4, handle_datagram/2,
         handle_stream_closed/3, terminate/2]).

init(_Session, _Req, _Opts) ->
    {ok, #{}}.

handle_stream(Stream, Type, Data, State) ->
    %% Echo bidi streams
    Actions = case Type of
        bidi -> [{send, Stream, <<"echo: ", Data/binary>>}];
        uni  -> []
    end,
    {ok, State, Actions}.

handle_datagram(Data, State) ->
    {ok, State, [{send_datagram, <<"echo: ", Data/binary>>}]}.

handle_stream_closed(_Stream, _Reason, State) ->
    {ok, State}.

terminate(_Reason, _State) ->
    ok.

Callback reference

All callbacks receive the handler state and return {ok, NewState}, {ok, NewState, Actions}, or {stop, Reason, NewState}.

init/3 (required)

Called when a session is established.

init(Session, Request, Opts) -> {ok, State} | {ok, State, Actions} | {error, Reason}

• Session -- the session pid (use for webtransport:open_stream/2 etc.)
• Request -- #{path := binary(), authority := binary(), headers => [{binary(), binary()}]}
• Opts -- the handler_opts map from the listener or connect call

init/2 is a back-compat shim called only when init/3 is not exported; it loses Opts.

handle_stream/4 (required)

Called when data arrives on a stream.

handle_stream(Stream, Type, Data, State) -> {ok, State} | {ok, State, Actions} | {stop, Reason, State}

• Stream -- stream ID (integer)
• Type -- bidi or uni
• Data -- binary payload

handle_stream_fin/4 (optional)

Called when data arrives with the FIN flag (last data on the stream). If not exported, handle_stream/4 is called instead.

handle_stream_fin(Stream, Type, Data, State) -> {ok, State} | {ok, State, Actions} | {stop, Reason, State}

handle_datagram/2 (required)

Called when an unreliable datagram arrives.

handle_datagram(Data, State) -> {ok, State} | {ok, State, Actions} | {stop, Reason, State}

handle_stream_closed/3 (required)

Called when a stream closes or is reset by the peer.

handle_stream_closed(Stream, Reason, State) -> {ok, State} | {stop, Reason, State}

• Reason -- normal | {reset, ErrorCode} | {error, Term} | {stop_sending, ErrorCode}

handle_info/2 (optional)

Called for any Erlang message not handled by the session state machine.

handle_info(Info, State) -> {ok, State} | {ok, State, Actions} | {stop, Reason, State}

handle_action_failed/3 (optional)

Called when an action returned by a callback fails to dispatch (e.g. sending to an unknown stream). Default behaviour: log and continue.

handle_action_failed(Action, Reason, State) -> {ok, State} | {stop, Reason, State}

origin_check/2 (optional)

Called before init/3 on server-side CONNECT requests. Return accept or {reject, Status, Reason} to refuse a session.

origin_check(Headers, Opts) -> accept | {reject, 400..599, binary()}

When not exported, the default behaviour rejects requests that carry an origin header (browser clients) with 403. Requests without an origin header (non-browser clients) are accepted. Implement this callback to allow browser origins:

origin_check(Headers, _Opts) ->
    case proplists:get_value(<<"origin">>, Headers) of
        <<"https://myapp.example.com">> -> accept;
        _ -> {reject, 403, <<"origin not allowed">>}
    end.

terminate/2 (required)

Called when the session ends.

terminate(Reason, State) -> term()

• Reason -- normal | {closed, ErrorCode, Message} | {error, Term} | Term

When the peer sends CLOSE_SESSION, Reason is {closed, ErrorCode, Message}.

Actions

Callbacks can return a list of actions as the third element of the return tuple:

handle_stream(Stream, bidi, Data, State) ->
    {ok, State, [
        {send, Stream, <<"echo: ", Data/binary>>},
        {send_datagram, <<"got data on stream">>}
    ]}.

Server API

Starting a listener

{ok, Pid} = webtransport:start_listener(Name, Opts).

Name is an atom used to identify the listener. Opts is a map:

Managing listeners

%% Stop a listener
ok = webtransport:stop_listener(Name).

%% List active listeners
[Name] = webtransport:listeners().

%% Get listener info
{ok, #{transport := h3, port := 4433, handler := my_handler}} =
    webtransport:listener_info(Name).

Embedding in an HTTP server

Use accept/4 to add WebTransport to an existing HTTP/3 or HTTP/2 server. Your server owns the listener and routing; accept/4 upgrades a specific CONNECT request into a WebTransport session -- the same pattern as WebSocket upgrade.

HTTP/3 example

%% 1. Merge WT config into your quic_h3 server
H3Opts = maps:merge(webtransport:h3_settings(), #{
    cert => CertDer, key => PrivateKey,
    handler => fun my_handler/5
}),
{ok, _} = quic_h3:start_server(my_server, 443, H3Opts).

%% 2. In your request handler, route and upgrade
my_handler(H3Conn, StreamId, <<"CONNECT">>, <<"/chat">>, Headers) ->
    {ok, _Session} = webtransport:accept(H3Conn, StreamId, Headers, #{
        transport => h3,
        handler => chat_handler,
        handler_opts => #{room => lobby}
    });
my_handler(H3Conn, StreamId, <<"CONNECT">>, <<"/game">>, Headers) ->
    {ok, _Session} = webtransport:accept(H3Conn, StreamId, Headers, #{
        transport => h3,
        handler => game_handler
    });
my_handler(H3Conn, StreamId, <<"GET">>, _Path, _Headers) ->
    quic_h3:send_response(H3Conn, StreamId, 200, []),
    quic_h3:send_data(H3Conn, StreamId, <<"hello">>, true).

HTTP/2 example

H2Opts = maps:merge(webtransport:h2_settings(), #{
    cert => "cert.pem", key => "key.pem",
    handler => fun my_h2_handler/5
}),
{ok, _} = h2:start_server(443, H2Opts).

my_h2_handler(Conn, StreamId, <<"CONNECT">>, <<"/wt">> = Path, Headers) ->
    %% h2 passes the method and path as arguments, not as headers.
    {ok, _Session} = webtransport:accept(Conn, StreamId, Headers, #{
        transport => h2,
        handler => my_wt_handler,
        path => Path
    });
my_h2_handler(Conn, StreamId, <<"GET">>, Path, Headers) ->
    serve_static(Conn, StreamId, Path, Headers).

accept/4 options

accept/4 validates the CONNECT headers and the client's SETTINGS, negotiates the subprotocol, starts a session, sends 200, then registers the session as the stream handler so capsules sent with the request are handled after the 200, and returns {ok, Session}. Merge h3_settings/0 into your server options: it sets defer_requests_until_settings, without which a request that arrives ahead of the client's SETTINGS is refused. The session pid works with all session API functions (send/3, open_stream/2, etc.).

See the Integration guide for details.

Client API

Connecting

{ok, Session} = webtransport:connect(Host, Port, Path, Opts).

Connecting with a custom handler

{ok, Session} = webtransport:connect(Host, Port, Path, Opts, MyHandler).

When no handler is given, webtransport_client_handler is used. It forwards all events to the calling process as messages.

Default client messages

When using the default handler, the process that called connect/4 receives:

Session API

Once connected, use these functions on the session pid:

%% Streams
{ok, Stream} = webtransport:open_stream(Session, bidi).  %% or uni
ok = webtransport:send(Session, Stream, Data).
ok = webtransport:send(Session, Stream, Data, fin).
ok = webtransport:close_stream(Session, Stream).
ok = webtransport:reset_stream(Session, Stream, ErrorCode).
ok = webtransport:stop_sending(Session, Stream, ErrorCode).

%% Datagrams
ok = webtransport:send_datagram(Session, Data).

%% Session lifecycle
ok = webtransport:drain_session(Session).
ok = webtransport:close_session(Session).
ok = webtransport:close_session(Session, ErrorCode).
ok = webtransport:close_session(Session, ErrorCode, Reason).

%% Introspection
{ok, Info} = webtransport:session_info(Session).
%% Info :: #{transport, stream_count, local_max_data, remote_max_data,
%%           local_max_streams_bidi, local_max_streams_uni,
%%           remote_max_streams_bidi, remote_max_streams_uni,
%%           bytes_sent, bytes_received, wt_draft, max_datagram_size,
%%           protocol => binary(), close_info => {Code, Msg}}

Compatibility mode

The HTTP/3 WebTransport spec has evolved through multiple drafts. The IETF is on draft-17; Chrome and Firefox still use draft-02 and Safari 26 uses draft-07. This library keeps the latest and the legacy paths disjoint:

Server default: auto -- the server inspects :protocol and the Sec-Webtransport-Http3-Draft02 header on each CONNECT request and dispatches to the matching code path. A webtransport request is draft-07 when the client sent SETTINGS_WEBTRANSPORT_MAX_SESSIONS and no draft-02 header, draft-02 otherwise; a connection carries one draft-07 session. In latest mode the server advertises SETTINGS_WT_ENABLED under both the draft-17 and the draft-15 codepoints and picks the version from the client's SETTINGS (draft-17 section 7.1); the client sends the draft-17 codepoint only. Pin to latest or legacy_browser_compat to refuse the other:

%% Accept only draft-17 and draft-15 clients
webtransport:start_listener(strict, #{
    transport => h3,
    port => 4433,
    certfile => "cert.pem",
    keyfile => "key.pem",
    handler => my_handler,
    compat_mode => latest
}).

Client default: latest. To connect to a draft-02 server:

{ok, Session} = webtransport:connect("example.com", 443, <<"/wt">>, #{
    transport => h3,
    compat_mode => legacy_browser_compat,
    verify => verify_none
}).

Use compat_mode => draft07 for a draft-07 server.

HTTP/2 WebTransport (transport => h2) has no draft-02 variant; compat_mode applies only to HTTP/3.

Flow control

WebTransport provides session-level and per-stream flow control. These are the limits you grant the peer; the limits the peer grants you come from its SETTINGS. Defaults:

Override at listener or connect time:

webtransport:start_listener(my_server, #{
    transport => h3,
    port => 4433,
    certfile => "cert.pem",
    keyfile => "key.pem",
    handler => my_handler,
    max_data => 4194304,        %% 4 MB
    max_streams_bidi => 200,
    max_streams_uni => 50
}).

The library enforces:

• When flow control applies -- always on HTTP/2. On HTTP/3 only when both sides sent a non-zero initial limit in their SETTINGS (draft-17 section 5.1); otherwise limits are not enforced and flow-control capsules are ignored.
• Strictly increasing limits -- a WT_MAX_DATA, WT_MAX_STREAM_DATA or WT_MAX_STREAMS that does not raise the previous value, or a stream limit above 2^60, closes the session with WT_FLOW_CONTROL_ERROR.
• Overruns -- data beyond what we granted, or a stream beyond our stream limit, closes the session with WT_FLOW_CONTROL_ERROR.
• Cumulative stream limits -- stream limits count every stream opened in the session. As the peer's streams finish, the library sends WT_MAX_STREAMS so the peer can always have max_streams_* open. When your own open fails with stream_limit_reached, WT_STREAMS_BLOCKED is sent and the handler's handle_stream_credit/2 runs once the peer grants more.
• HTTP/3 prohibition -- WT_MAX_STREAM_DATA and WT_STREAM_DATA_BLOCKED capsules are session errors on HTTP/3 (per-stream flow control uses native QUIC).
• HTTP/2 WebTransport-Init -- the WebTransport-Init header (draft-16 section 4.3.2) carries initial per-stream data limits. When both SETTINGS and the header are present, the greater value is used. A header that does not parse is refused with 400.
• Large sends -- send/4 accepts a payload of any size and returns ok once it is queued. Bytes beyond the session window (both transports) or the stream window (HTTP/2) wait in order on the stream, FIN is held until they are out, and the queue drains as the peer raises its limits. WT_DATA_BLOCKED tells the peer we are waiting.
• Credit on receive -- the library sends WT_MAX_DATA (both transports) and WT_MAX_STREAM_DATA (HTTP/2) once half of a window has been consumed, so a peer that honours our windows is never left waiting.

Datagram limits

Datagrams are bounded by the transport:

Sending a datagram larger than the limit returns {error, datagram_too_large}.

Error codes

The library uses draft-defined error codes:

On HTTP/3, application error codes (32 bits) are mapped into the WT_APPLICATION_ERROR range of QUIC error codes per draft-17 section 4.4; protocol codes such as WT_SESSION_GONE are sent as is, and a reset whose code is outside the range reaches the handler as {reset, undefined}. On HTTP/2 the codes for session errors are not assigned yet: a session error is WT_CLOSE_SESSION followed by RST_STREAM(PROTOCOL_ERROR), or FLOW_CONTROL_ERROR for flow-control violations.

Session termination

When a session closes (locally or by the peer):

1. All live streams are reset with WT_SESSION_GONE; on HTTP/3 the streams we read also get STOP_SENDING(WT_SESSION_GONE).
2. A CLOSE_SESSION capsule is sent (or received) with a 32-bit error code and a reason of at most 1024 bytes of UTF-8.
3. The CONNECT stream is closed (FIN on HTTP/3, END_STREAM on HTTP/2). The peer closing or resetting the CONNECT stream without CLOSE_SESSION also ends the session.
4. The handler's terminate/2 receives {closed, ErrorCode, Reason} as the reason.
5. On HTTP/3 a client closes its QUIC connection once its last session has ended and the server closed the CONNECT stream; a server leaves the connection open.

If the peer FINs the CONNECT stream without sending CLOSE_SESSION, the session terminates with {closed, 0, <<"peer closed CONNECT">>}.

Architecture

webtransport            Public API (connect, send, open_stream, ...)
    |
webtransport_session    gen_statem per session (flow control, handler dispatch)
    |
    +-- webtransport_h3     HTTP/3 transport (QUIC streams + datagrams)
    |     +-- wt_h3              Settings, headers, peer validation
    |     +-- wt_h3_capsule      Session and flow-control capsules, stream headers
    |     +-- webtransport_h3_router   Per-connection stream demux
    |
    +-- webtransport_h2     HTTP/2 transport (capsules over CONNECT stream)
    |     +-- wt_h2_capsule      HTTP/2 capsule encode/decode
    |     +-- wt_h2_init         WebTransport-Init header parse/encode
    |
    +-- wt_sf                   Structured field parsing (RFC 9651)
    |
    +-- webtransport_stream     Per-stream state (flow control, buffers)
    +-- wt_error                App error code mapping (draft-17 section 4.4)
    +-- webtransport_handler    Behaviour definition

Examples

The examples/ directory contains a working echo server and client.

Compile and run them:

# Generate certs (if not done already)
openssl req -x509 -newkey rsa:2048 \
  -keyout key.pem -out cert.pem \
  -days 365 -nodes -subj '/CN=localhost'

# Compile examples
erlc -o examples \
  -pa _build/default/lib/webtransport/ebin \
  -pa _build/default/lib/quic/ebin \
  -pa _build/default/lib/erlang_h2/ebin \
  -I include \
  examples/echo_server.erl examples/echo_client.erl

# Start a shell
ERL_FLAGS="-pa examples" rebar3 shell --apps webtransport

%% Start the echo server
echo_server:start(4433).

%% Run the echo client tests
echo_client:test("localhost", 4433).

Testing

# Unit tests (301 tests)
rebar3 eunit

# Integration tests (67 tests, both h2 and h3)
rebar3 ct --suite=test/webtransport_SUITE

# IPv6, sockname and 0-RTT integration tests
rebar3 ct --suite=test/webtransport_ipv6_SUITE

# Docker interop (erlang vs erlang)
cd interop && docker compose up --abort-on-container-exit --build

# Cross-implementation interop (erlang vs webtransport-go)
./scripts/interop_cross.sh

Specifications

• draft-ietf-webtrans-http3-17 -- WebTransport over HTTP/3
• draft-ietf-webtrans-http2-16 -- WebTransport over HTTP/2
• draft-ietf-webtrans-overview-14 -- The WebTransport Protocol Framework
• RFC 9297 -- HTTP Datagrams and the Capsule Protocol
• RFC 9000 -- QUIC: A UDP-Based Multiplexed and Secure Transport
• RFC 9114 -- HTTP/3
• RFC 8441 -- Bootstrapping WebSockets with HTTP/2 (Extended CONNECT)
• W3C WebTransport API -- Browser API specification

Contributing

See CONTRIBUTING.md. Report security issues privately as described in SECURITY.md.

Sponsors

License

Apache-2.0