SigilGuard.Registry.Cache (SigilGuard v0.2.0)

GenServer-based TTL cache for SIGIL registry data.

Fetches pattern bundles on startup and refreshes them periodically based on the configured TTL. On fetch failure, retains the last known good bundle, tracks the data source for observability, and retries after :registry_retry_ms instead of waiting out the full TTL.

Source Tracking

The cache tracks where its current data came from:

:registry — freshly fetched from the SIGIL registry
:fallback — last fetch failed; serving built-in patterns (if no fetch ever succeeded) or the last known good bundle
:empty — no data available (initial state, before the first fetch)

Configuration

config :sigil_guard,
  registry_enabled: true,
  registry_ttl_ms: 3_600_000,     # 1 hour
  registry_retry_ms: 60_000,      # retry failed fetches after 1 minute
  registry_url: "https://registry.sigil-protocol.org"

Process Model

The cache is a singleton registered under SigilGuard.Registry.Cache — one instance per node, supervised by SigilGuard's application when registry_enabled: true or by the host application otherwise.

Fetches run synchronously inside the server loop: while a fetch is in flight, patterns/0, rule_count/0, and source/0 queue for up to :registry_timeout_ms. Keep that timeout below the callers' own GenServer.call timeout (5 seconds by default).

Observability

SigilGuard.Registry.Cache.rule_count()  #=> 42
SigilGuard.Registry.Cache.source()      #=> :registry

Summary

Types

source()

Where the current cached data originated.

state()

Internal GenServer state.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

patterns()

Get the current compiled patterns from the cache.

refresh()

Force a refresh of the cached patterns from the registry.

rule_count()

Return the number of patterns currently cached.

source()

Return the source of the current cached data.

start_link(opts \\ [])

Start the registry cache GenServer.

Types

source()

@type source() :: :registry | :fallback | :empty

Where the current cached data originated.

state()

@type state() :: %{
  patterns: [SigilGuard.Patterns.compiled_pattern()],
  raw_bundle: map() | nil,
  source: source(),
  fetched_at: integer() | nil,
  ttl_ms: non_neg_integer(),
  retry_ms: non_neg_integer()
}

Internal GenServer state.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

patterns()

@spec patterns() :: [SigilGuard.Patterns.compiled_pattern()]

Get the current compiled patterns from the cache.

Falls back to built-in patterns if the cache is empty.

refresh()

@spec refresh() :: :ok

Force a refresh of the cached patterns from the registry.

rule_count()

@spec rule_count() :: non_neg_integer()

Return the number of patterns currently cached.

source()

@spec source() :: source()

Return the source of the current cached data.

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Start the registry cache GenServer.