masque_uri (masque v0.7.0)

View Source

URI template handling for RFC 9298 CONNECT-UDP and the CONNECT-TCP draft.

RFC 9298 §3 defines the request path as the expansion of a URI template with two variables - target_host` and `target_port`. `target_host` may be an IPv4 literal, an IPv6 literal, or a registered name; colons and any non-unreserved characters are percent-encoded on the wire. The template engine now lives in `masque_uri_template; this module is a thin UDP/TCP facade that keeps its historical public API shape and does the UDP-specific validation (target_host reg-name / IP literal rules, target_port integer range).

Summary

Types

template/0
vars/0

Functions

build_authority(Host, Port)

Format a host:port authority. IPv6 literals are wrapped in square brackets per RFC 3986 §3.2.2. Used on the client side to build the CONNECT request-target and Host header.

expand(Template, Vars)

Expand a URI template using Vars. Returns the absolute path to place in the :path pseudo-header. Absolute http(s)://... templates are accepted - only the path-and-onwards portion is expanded, mirroring what servers actually match at runtime.

match(Template, Path)

Match a request path against a template.

parse_authority_form(Bin)

Parse the authority-form of a request-target used by classic CONNECT (RFC 9112 §3.2.3): host:port or [ipv6]:port. Strips the brackets from the IPv6 literal on the way out. Rejects malformed inputs (missing port, non-numeric port, empty host).

to_path(Path)

Strip an absolute http(s)://… template to its path portion. Path-shaped templates pass through unchanged.

valid_host(Host)

Validate Host as an IPv4 literal, IPv6 literal, or LDH registered name. Rejects IPv6 zone identifiers (RFC 3986 excludes the %zone suffix from URI host syntax).

Types

template/0

-type template() :: binary().

vars/0

-type vars() :: #{target_host := binary() | string(), target_port := 1..65535}.

Functions

build_authority(Host, Port)

-spec build_authority(binary(), inet:port_number()) -> binary().

Format a host:port authority. IPv6 literals are wrapped in square brackets per RFC 3986 §3.2.2. Used on the client side to build the CONNECT request-target and Host header.

expand(Template, Vars)

-spec expand(template(), vars()) -> binary().

Expand a URI template using Vars. Returns the absolute path to place in the :path pseudo-header. Absolute http(s)://... templates are accepted - only the path-and-onwards portion is expanded, mirroring what servers actually match at runtime.

match(Template, Path)

-spec match(template(), binary()) ->
               {ok, #{target_host := binary(), target_port := 1..65535}} |
               {error, no_match | bad_port | bad_host | bad_template}.

Match a request path against a template.

Returns {ok, #{target_host := Host, target_port := Port}} on success with Host as a binary (percent-decoded) and Port as an integer in 1..65535. Returns {error, Reason} otherwise.

parse_authority_form(Bin)

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

Parse the authority-form of a request-target used by classic CONNECT (RFC 9112 §3.2.3): host:port or [ipv6]:port. Strips the brackets from the IPv6 literal on the way out. Rejects malformed inputs (missing port, non-numeric port, empty host).

to_path(Path)

-spec to_path(binary()) -> binary().

Strip an absolute http(s)://… template to its path portion. Path-shaped templates pass through unchanged.

valid_host(Host)

-spec valid_host(binary()) -> boolean().

Validate Host as an IPv4 literal, IPv6 literal, or LDH registered name. Rejects IPv6 zone identifiers (RFC 3986 excludes the %zone suffix from URI host syntax).