GenServer-based session cache for GUS BIR service.

Caches authenticated sessions to avoid redundant login requests. Sessions are considered valid if they are younger than the configured TTL margin (default: 50 minutes, well under the 60-minute hard limit).

Expiry model

The cache is keyed on the {api_key, environment} pair and holds at most one entry per key (typically one entry total, since credentials are read from Application config).

Regular TTL-expired entries are replaced on the next lookup: :ets.insert/2 on a :set table is an upsert, so a stale row lives at most until the next call for that credentials pair. There is no periodic sweep, because with one entry per key there is nothing to accumulate.

For mid-TTL invalidation — where the server has killed the session before the local TTL says so, e.g. after the daily 3:20 AM maintenance window that closes all active sessions — run_with_session/1 detects the failure, evicts the stale entry, and transparently retries once with a fresh login. Callers do not need to manage this explicitly.

Setup

Add Gusex.SessionCache to your application's supervision tree:

defmodule MyApp.Application do
    use Application

    def start(_type, _args) do
        children = [
            Gusex.SessionCache,
            # ... other children
        ]

        Supervisor.start_link(children, strategy: :one_for_one)
    end
end

Configuration

config :gusex, session_ttl: 3000  # seconds, default: 3000 (50 minutes)