hackney_altsvc (hackney v4.0.0)

View Source

Alt-Svc header parsing and caching for HTTP/3 discovery.

This module parses Alt-Svc response headers to discover HTTP/3 endpoints and caches them for future requests.

Alt-Svc Header Format

   Alt-Svc: h3=":443"; ma=86400, h3-29=":443"
   Alt-Svc: clear

Usage

After receiving an HTTP/1.1 or HTTP/2 response, check for Alt-Svc:

   case hackney_altsvc:parse_and_cache(Host, Headers) of
       {ok, h3, Port} -> %% HTTP/3 available on Port
       none -> %% No HTTP/3 advertised
   end

Before connecting, check the cache:

   case hackney_altsvc:lookup(Host, Port) of
       {ok, h3, H3Port} -> %% Try HTTP/3 on H3Port
       none -> %% No cached Alt-Svc
   end

Summary

Functions

cache(Host, OrigPort, H3Port, MaxAge)

Cache an Alt-Svc entry.

clear(Host, Port)

Clear cached Alt-Svc for a host/port.

clear_all()

Clear all cached Alt-Svc entries.

init()

Initialize the Alt-Svc cache. Called at application start.

is_h3_blocked(Host, Port)

Check if HTTP/3 is blocked for a host (negative cache).

lookup(Host, Port)

Lookup cached Alt-Svc for a host/port. Returns {ok, h3, H3Port} if HTTP/3 is available and not expired.

mark_h3_blocked(Host, Port)

Mark HTTP/3 as blocked for a host (negative cache for 5 min).

parse(Header)

Parse an Alt-Svc header value. Returns list of {Protocol, Host, Port, MaxAge} tuples. Protocol is h3 atom for HTTP/3 variants, or binary for other protocols. Host is 'same' if not specified (use origin host).

parse_and_cache(Host, Port, Headers)

Parse Alt-Svc header from response headers and cache if h3 found.

Functions

cache(Host, OrigPort, H3Port, MaxAge)

-spec cache(Host :: binary() | string(),
            OrigPort :: inet:port_number(),
            H3Port :: inet:port_number(),
            MaxAge :: non_neg_integer()) ->
               ok.

Cache an Alt-Svc entry.

clear(Host, Port)

-spec clear(Host :: binary() | string(), Port :: inet:port_number()) -> ok.

Clear cached Alt-Svc for a host/port.

clear_all()

-spec clear_all() -> ok.

Clear all cached Alt-Svc entries.

init()

-spec init() -> ok.

Initialize the Alt-Svc cache. Called at application start.

is_h3_blocked(Host, Port)

-spec is_h3_blocked(Host :: binary() | string(), Port :: inet:port_number()) -> boolean().

Check if HTTP/3 is blocked for a host (negative cache).

lookup(Host, Port)

-spec lookup(Host :: binary() | string(), Port :: inet:port_number()) ->
                {ok, h3, inet:port_number()} | none.

Lookup cached Alt-Svc for a host/port. Returns {ok, h3, H3Port} if HTTP/3 is available and not expired.

mark_h3_blocked(Host, Port)

-spec mark_h3_blocked(Host :: binary() | string(), Port :: inet:port_number()) -> ok.

Mark HTTP/3 as blocked for a host (negative cache for 5 min).

parse(Header)

-spec parse(binary() | string()) ->
               [{h3 | binary(), same | binary(), inet:port_number(), non_neg_integer()}].

Parse an Alt-Svc header value. Returns list of {Protocol, Host, Port, MaxAge} tuples. Protocol is h3 atom for HTTP/3 variants, or binary for other protocols. Host is 'same' if not specified (use origin host).

parse_and_cache(Host, Port, Headers)

-spec parse_and_cache(Host :: binary() | string(),
                      Port :: inet:port_number(),
                      Headers :: [{binary(), binary()}]) ->
                         {ok, h3, inet:port_number()} | cleared | none.

Parse Alt-Svc header from response headers and cache if h3 found.

Honors RFC 7838: a clear value invalidates any cached entry for the origin. Multiple Alt-Svc headers are merged before parsing as if they had been comma-concatenated (RFC 7230 §3.2.2).

Returns {ok, h3, Port} if HTTP/3 is now cached for the origin, cleared if the cache was invalidated, or none otherwise.