-module(nquic_session_cache).
-moduledoc """
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:
```erlang
-spec children() -> [supervisor:child_spec()].
children() ->
[nquic_session_cache:child_spec(my_quic_tickets, #{sweep_ms => 60_000})].
```
Then reference it in `connect` options:
```erlang
{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:
```erlang
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).
""".
-behaviour(gen_server).
-compile({no_auto_import, [size/1]}).
-export([
child_spec/1,
child_spec/2,
clear/1,
delete/3,
lookup/3,
maybe_load_ticket/3,
size/1,
start_link/1,
start_link/2,
stop/1,
store/4
]).
-export([handle_call/3, handle_cast/2, handle_info/2, init/1, terminate/2]).
-export_type([cache_name/0, host/0]).
-type cache_name() :: atom().
-type host() :: inet:hostname() | inet:ip_address().
-define(DEFAULT_SWEEP_MS, 60_000).
-define(DEFAULT_TTL, 7200).
-record(state, {
name :: cache_name(),
sweep_ms :: pos_integer(),
sweep_ref :: reference() | undefined
}).
%%%-----------------------------------------------------------------------------
%% API
%%%-----------------------------------------------------------------------------
-doc "Standard child spec with the default sweep interval.".
-spec child_spec(cache_name()) -> supervisor:child_spec().
child_spec(Name) ->
child_spec(Name, #{}).
-doc "Standard child spec with custom options.".
-spec child_spec(cache_name(), map()) -> supervisor:child_spec().
child_spec(Name, Opts) when is_atom(Name), is_map(Opts) ->
#{
id => {?MODULE, Name},
start => {?MODULE, start_link, [Name, Opts]},
restart => permanent,
shutdown => 5000,
type => worker,
modules => [?MODULE]
}.
-doc "Drop every entry in cache `Name`. Raises `badarg` if not started.".
-spec clear(cache_name()) -> ok.
clear(Name) when is_atom(Name) ->
true = ets:delete_all_objects(Name),
ok.
-doc "Delete a ticket from cache `Name`. Raises `badarg` if not started.".
-spec delete(cache_name(), host(), inet:port_number()) -> ok.
delete(Name, Host, Port) when is_atom(Name) ->
Key = cache_key(Host, Port),
true = ets:delete(Name, Key),
ok.
-doc """
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.
""".
-spec lookup(cache_name(), host(), inet:port_number()) ->
{ok, map()} | {error, not_found}.
lookup(Name, Host, Port) when is_atom(Name) ->
Key = cache_key(Host, Port),
case ets:lookup(Name, Key) of
[{Key, TicketData, Expiry}] ->
Now = erlang:system_time(second),
case Now < Expiry of
true ->
{ok, TicketData};
false ->
ets:delete(Name, Key),
{error, not_found}
end;
[] ->
{error, not_found}
end.
-doc """
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`.
""".
-spec maybe_load_ticket(host(), inet:port_number(), map()) -> map().
maybe_load_ticket(Host, Port, Opts) ->
case maps:get(session_ticket, Opts, undefined) of
undefined ->
case resolve_lookup(maps:get(session_cache, Opts, false), Host, Port) of
{ok, Ticket} -> Opts#{session_ticket => Ticket};
{error, _} -> Opts
end;
_ ->
Opts
end.
-doc "Return the number of entries in cache `Name`.".
-spec size(cache_name()) -> non_neg_integer().
size(Name) when is_atom(Name) ->
ets:info(Name, size).
%%%-----------------------------------------------------------------------------
%% GEN_SERVER CALLBACKS
%%%-----------------------------------------------------------------------------
-spec handle_call(term(), gen_server:from(), #state{}) ->
{reply, {error, unknown_request}, #state{}}.
handle_call(_Request, _From, State) ->
{reply, {error, unknown_request}, State}.
-spec handle_cast(term(), #state{}) -> {noreply, #state{}}.
handle_cast(_Msg, State) ->
{noreply, State}.
-spec handle_info(sweep | term(), #state{}) -> {noreply, #state{}}.
handle_info(sweep, #state{name = Name, sweep_ms = Ms} = State) ->
sweep_expired(Name),
Ref = schedule_sweep(Ms),
{noreply, State#state{sweep_ref = Ref}};
handle_info(_Info, State) ->
{noreply, State}.
-spec init({cache_name(), map()}) -> {ok, #state{}}.
init({Name, Opts}) ->
process_flag(trap_exit, true),
_ = ets:new(Name, [
named_table,
public,
set,
{read_concurrency, true},
{write_concurrency, true},
{decentralized_counters, true}
]),
SweepMs = maps:get(sweep_ms, Opts, ?DEFAULT_SWEEP_MS),
Ref = schedule_sweep(SweepMs),
{ok, #state{name = Name, sweep_ms = SweepMs, sweep_ref = Ref}}.
-doc "Start a cache registered under `Name` with default options.".
-spec start_link(cache_name()) -> {ok, pid()} | ignore | {error, term()}.
start_link(Name) ->
start_link(Name, #{}).
-doc """
Start a cache registered under `Name`.
Accepted options:
* `sweep_ms` - eviction interval in milliseconds (default 60_000).
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 for `store/4` / `lookup/3`.
""".
-spec start_link(cache_name(), map()) -> {ok, pid()} | ignore | {error, term()}.
start_link(Name, Opts) when is_atom(Name), is_map(Opts) ->
gen_server:start_link({local, Name}, ?MODULE, {Name, Opts}, []).
-doc "Stop the cache and tear down its ETS table.".
-spec stop(cache_name()) -> ok.
stop(Name) when is_atom(Name) ->
case whereis(Name) of
undefined -> ok;
_ -> gen_server:stop(Name)
end.
-doc """
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.
""".
-spec store(cache_name(), host(), inet:port_number(), map()) -> ok.
store(Name, Host, Port, TicketData) when is_atom(Name), is_map(TicketData) ->
Key = cache_key(Host, Port),
Lifetime = maps:get(lifetime, TicketData, ?DEFAULT_TTL),
Expiry = erlang:system_time(second) + Lifetime,
true = ets:insert(Name, {Key, TicketData, Expiry}),
ok.
-spec terminate(term(), #state{}) -> ok.
terminate(_Reason, #state{name = Name}) ->
case ets:info(Name) of
undefined -> ok;
_ -> ets:delete(Name)
end,
ok.
%%%-----------------------------------------------------------------------------
%% INTERNAL
%%%-----------------------------------------------------------------------------
-spec cache_key(host(), inet:port_number()) -> {host(), inet:port_number()}.
cache_key(Host, Port) ->
{Host, Port}.
-spec resolve_lookup(
false | cache_name() | {module, module()},
host(),
inet:port_number()
) -> {ok, map()} | {error, not_found}.
resolve_lookup(false, _Host, _Port) ->
{error, not_found};
resolve_lookup({module, Mod}, Host, Port) ->
Mod:lookup(Host, Port);
resolve_lookup(Name, Host, Port) when is_atom(Name) ->
lookup(Name, Host, Port).
%%%-----------------------------------------------------------------------------
%% TESTS
%%%-----------------------------------------------------------------------------
-spec schedule_sweep(pos_integer()) -> reference().
schedule_sweep(Ms) ->
erlang:send_after(Ms, self(), sweep).
-spec sweep_expired(cache_name()) -> ok.
sweep_expired(Name) ->
Now = erlang:system_time(second),
_ = ets:select_delete(
Name,
[{{'_', '_', '$1'}, [{'=<', '$1', Now}], [true]}]
),
ok.