nquic_session_cache (nquic v1.0.0)

View Source

Per-instance session ticket cache for QUIC 0-RTT resumption.

Each cache is a gen_server that owns one named ETS table and runs a periodic eviction sweep. Multiple caches can coexist on the same node (one per logical client of the library), identified by the Name atom passed to start_link/1,2.

Usage

Start the cache under your own supervisor before using nquic:

-spec children() -> [supervisor:child_spec()].
children() ->
    [nquic_session_cache:child_spec(my_quic_tickets, #{sweep_ms => 60_000})].

Then reference it in connect options:

{ok, Conn} = nquic:connect(Host, Port, #{session_cache => my_quic_tickets}).

All cache functions fail loudly (badarg from the underlying ETS call) if Name does not refer to a live cache. There is no auto-start: the caller is responsible for initialising the cache synchronously before any nquic connect is issued.

Custom backends

The session_cache connect option also accepts {module, Mod} where Mod exports the triple:

store(Host, Port, Ticket) -> ok.
lookup(Host, Port)        -> {ok, Ticket} | {error, not_found}.
delete(Host, Port)        -> ok.

Use this to plug in an application-specific storage (Redis, Mnesia, etc).

Summary

Types

cache_name()
host()

Functions

child_spec(Name)

Standard child spec with the default sweep interval.

child_spec(Name, Opts)

Standard child spec with custom options.

clear(Name)

Drop every entry in cache Name. Raises badarg if not started.

delete(Name, Host, Port)

Delete a ticket from cache Name. Raises badarg if not started.

handle_call(Request, From, State)
handle_cast(Msg, State)
handle_info/2
init/1
lookup(Name, Host, Port)

Look up a session ticket for {Host, Port} in cache Name. Returns {ok, Ticket} for a live ticket, {error, not_found} for a miss or an expired entry. Raises badarg if Name is not a live cache.

maybe_load_ticket(Host, Port, Opts)

If Opts does not already carry a session_ticket, resolve the configured session_cache selector and inject any cached ticket into Opts. Returns Opts unchanged on miss or when no cache is configured. Accepts the same selector shape as the connect/3,4 option: false (no cache), an atom naming a started cache, or {module, Mod} for a custom backend exporting lookup/2.

size(Name)

Return the number of entries in cache Name.

start_link(Name)

Start a cache registered under Name with default options.

start_link(Name, Opts)

Start a cache registered under Name. Accepted options

stop(Name)

Stop the cache and tear down its ETS table.

store(Name, Host, Port, TicketData)

Store a session ticket under {Host, Port} for the cache Name. Raises badarg if Name is not a live cache; start it via start_link/1,2 or child_spec/1,2 first.

terminate/2

Types

cache_name()

-type cache_name() :: atom().

host()

-type host() :: inet:hostname() | inet:ip_address().

Functions

child_spec(Name)

-spec child_spec(cache_name()) -> supervisor:child_spec().

Standard child spec with the default sweep interval.

child_spec(Name, Opts)

-spec child_spec(cache_name(), map()) -> supervisor:child_spec().

Standard child spec with custom options.

clear(Name)

-spec clear(cache_name()) -> ok.

Drop every entry in cache Name. Raises badarg if not started.

delete(Name, Host, Port)

-spec delete(cache_name(), host(), inet:port_number()) -> ok.

Delete a ticket from cache Name. Raises badarg if not started.

handle_call(Request, From, State)

-spec handle_call(term(),
                  gen_server:from(),
                  #state{name :: cache_name(),
                         sweep_ms :: pos_integer(),
                         sweep_ref :: reference() | undefined}) ->
                     {reply,
                      {error, unknown_request},
                      #state{name :: cache_name(),
                             sweep_ms :: pos_integer(),
                             sweep_ref :: reference() | undefined}}.

handle_cast(Msg, State)

-spec handle_cast(term(),
                  #state{name :: cache_name(),
                         sweep_ms :: pos_integer(),
                         sweep_ref :: reference() | undefined}) ->
                     {noreply,
                      #state{name :: cache_name(),
                             sweep_ms :: pos_integer(),
                             sweep_ref :: reference() | undefined}}.

handle_info/2

-spec handle_info(sweep | term(),
                  #state{name :: cache_name(),
                         sweep_ms :: pos_integer(),
                         sweep_ref :: reference() | undefined}) ->
                     {noreply,
                      #state{name :: cache_name(),
                             sweep_ms :: pos_integer(),
                             sweep_ref :: reference() | undefined}}.

init/1

-spec init({cache_name(), map()}) ->
              {ok,
               #state{name :: cache_name(),
                      sweep_ms :: pos_integer(),
                      sweep_ref :: reference() | undefined}}.

lookup(Name, Host, Port)

-spec lookup(cache_name(), host(), inet:port_number()) -> {ok, map()} | {error, not_found}.

Look up a session ticket for {Host, Port} in cache Name. Returns {ok, Ticket} for a live ticket, {error, not_found} for a miss or an expired entry. Raises badarg if Name is not a live cache.

maybe_load_ticket(Host, Port, Opts)

-spec maybe_load_ticket(host(), inet:port_number(), map()) -> map().

If Opts does not already carry a session_ticket, resolve the configured session_cache selector and inject any cached ticket into Opts. Returns Opts unchanged on miss or when no cache is configured. Accepts the same selector shape as the connect/3,4 option: false (no cache), an atom naming a started cache, or {module, Mod} for a custom backend exporting lookup/2.

size(Name)

-spec size(cache_name()) -> non_neg_integer().

Return the number of entries in cache Name.

start_link(Name)

-spec start_link(cache_name()) -> {ok, pid()} | ignore | {error, term()}.

Start a cache registered under Name with default options.

start_link(Name, Opts)

-spec start_link(cache_name(), map()) -> {ok, pid()} | ignore | {error, term()}.

Start a cache registered under Name. Accepted options:

  • sweep_ms - eviction interval in milliseconds (default 60000). Returns {error, {already_started, Pid}} if a cache with this name is already registered. This call is synchronous: when it returns `{ok, }the ETS table is live and ready forstore/4/lookup/3`.

stop(Name)

-spec stop(cache_name()) -> ok.

Stop the cache and tear down its ETS table.

store(Name, Host, Port, TicketData)

-spec store(cache_name(), host(), inet:port_number(), map()) -> ok.

Store a session ticket under {Host, Port} for the cache Name. Raises badarg if Name is not a live cache; start it via start_link/1,2 or child_spec/1,2 first.

terminate/2

-spec terminate(term(),
                #state{name :: cache_name(),
                       sweep_ms :: pos_integer(),
                       sweep_ref :: reference() | undefined}) ->
                   ok.