LemonCore.ConfigCache (lemon_core v0.1.0)

View Source

ETS-backed cache for merged Lemon configuration.

Goals:

  • Avoid hot-path TOML disk reads/parsing.
  • Provide consistent semantics: cached reads by default + explicit reload.
  • Detect on-disk changes via periodic (TTL) file fingerprint checks (mtime/size).

Instances

The cache is named (default LemonCore.ConfigCache) and every public function takes an optional leading server argument. A second instance gets its own ETS table, derived from its name, so several caches can coexist in one node. Options come from start_link/1 first, falling back to Application.get_env(:lemon_core, name).

Summary

Types

server()

A running config cache, addressed by its registered name.

Functions

available?(server \\ __MODULE__)

Returns true if the cache is running and its ETS table exists.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get(cwd \\ nil, opts \\ [])

Get the cached base config for cwd (merged global + project TOML, no env/overrides).

get(server, cwd, opts)

Get the cached base config for cwd from a specific cache instance.

invalidate(cwd \\ nil)

Drop the cached entry for cwd.

invalidate(server, cwd)

Drop the cached entry for cwd in a specific cache instance.

reload(cwd \\ nil, opts \\ [])

Force reload the cached base config for cwd from disk.

reload(server, cwd, opts)

Force reload the cached base config for cwd in a specific cache instance.

start_link(opts \\ [])
table_for(server)

Return the ETS table name backing a cache instance.

Types

server()

@type server() :: atom()

A running config cache, addressed by its registered name.

Functions

available?(server \\ __MODULE__)

@spec available?(server()) :: boolean()

Returns true if the cache is running and its ETS table exists.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get(cwd \\ nil, opts \\ [])

@spec get(
  String.t() | nil,
  keyword()
) :: LemonCore.Config.t()

Get the cached base config for cwd (merged global + project TOML, no env/overrides).

Uses a TTL to avoid frequent stat calls; when the TTL elapses it will check file fingerprints (mtime/size) and reload if they changed.

Cache keys are based on the resolved config file paths (global + project). This is important for tests, where HOME may change between cases.

get(server, cwd, opts)

@spec get(server(), String.t() | nil, keyword()) :: LemonCore.Config.t()

Get the cached base config for cwd from a specific cache instance.

invalidate(cwd \\ nil)

@spec invalidate(String.t() | nil) :: :ok

Drop the cached entry for cwd.

invalidate(server, cwd)

@spec invalidate(server(), String.t() | nil) :: :ok

Drop the cached entry for cwd in a specific cache instance.

reload(cwd \\ nil, opts \\ [])

@spec reload(
  String.t() | nil,
  keyword()
) :: LemonCore.Config.t()

Force reload the cached base config for cwd from disk.

Options

  • :validate - Whether to validate the config and log warnings on validation errors (default: false to maintain backward compatibility)

Examples

# Reload without validation
LemonCore.ConfigCache.reload()

# Reload with validation warnings
LemonCore.ConfigCache.reload(validate: true)

reload(server, cwd, opts)

@spec reload(server(), String.t() | nil, keyword()) :: LemonCore.Config.t()

Force reload the cached base config for cwd in a specific cache instance.

start_link(opts \\ [])

table_for(server)

@spec table_for(server()) :: atom()

Return the ETS table name backing a cache instance.