masque_server (masque v0.7.0)

View Source

MASQUE CONNECT-UDP proxy listener.

Two public entry points:

  • start_listener/2 starts a dedicated quic_h3 server that handles MASQUE end-to-end; the usual case for a pure MASQUE proxy.
  • h3_handlers/1 returns the handler and connection_handler functions that a caller can splat into their own quic_h3:start_server/3 opts. This lets users who already run an HTTP/3 service add CONNECT-UDP support without giving up ownership of the listener; non-MASQUE requests can be routed to a fallback fun.

For each inbound request the handler validates the Extended CONNECT envelope per RFC 9298, matches the :path against the configured URI template, and either accepts the tunnel (2xx response, stream left open for subsequent datagrams) or rejects with the HTTP status selected by masque_errors:handshake_status/1 (or defers to the caller's fallback fun when provided).

Summary

Types

connection_handler_fun/0
h3_handler_fun/0
listener_name/0
listener_opts/0

Functions

h3_handlers(Opts0)

Return the handler and connection_handler functions for a MASQUE proxy, in a shape that can be dropped into a user-owned quic_h3:start_server/3 call.

start_listener(Name, Opts0)

Start a MASQUE listener as a dedicated quic_h3 server.

stop_listener(Name)

Stop a MASQUE listener.

Types

connection_handler_fun/0

-type connection_handler_fun() :: fun((pid()) -> map()).

h3_handler_fun/0

-type h3_handler_fun() ::
          fun((Conn :: pid(),
               StreamId :: non_neg_integer(),
               Method :: binary(),
               Path :: binary(),
               Headers :: [{binary(), binary()}]) ->
                  any()).

listener_name/0

-type listener_name() :: atom().

listener_opts/0

-type listener_opts() :: masque:listener_opts().

Functions

h3_handlers(Opts0)

-spec h3_handlers(map()) ->
                     #{handler := h3_handler_fun(), connection_handler := connection_handler_fun()}.

Return the handler and connection_handler functions for a MASQUE proxy, in a shape that can be dropped into a user-owned quic_h3:start_server/3 call.

Accepted keys (all optional unless noted):

  • uri_template - RFC 6570 template, default the RFC 9298 well-known path template.
  • handler - module implementing the masque_handler behaviour, default masque_udp_proxy_handler.
  • handler_opts - arbitrary term passed to the handler module's init/2 callback.
  • fallback - fun(Conn, StreamId, Method, Path, Headers) -> any() invoked when the request is not a CONNECT-UDP tunnel. Absent → non-MASQUE requests are rejected with 405/501/404 as appropriate.

Caveat: MASQUE must be the H3 connection's owner (HTTP Datagrams are delivered to that pid), so the returned connection_handler overrides the listener-wide owner. Sharing a single quic_h3 connection with another extension that also needs the owner slot (e.g. WebTransport) is not supported in v0.1; run those on separate listeners.

start_listener(Name, Opts0)

-spec start_listener(listener_name(), listener_opts()) -> {ok, pid()} | {error, term()}.

Start a MASQUE listener as a dedicated quic_h3 server.

Required keys: port, cert, key (DER-encoded, same shape as quic_h3:start_server/3 expects). Optional uri_template defaults to RFC 9298's well-known path; optional handler defaults to masque_udp_proxy_handler; optional fallback is invoked for requests that are not CONNECT-UDP tunnels (see h3_handlers/1).

stop_listener(Name)

-spec stop_listener(listener_name()) -> ok | {error, term()}.

Stop a MASQUE listener.