Foundation.Services.ConfigServer (foundation v0.1.0)

GenServer implementation for configuration management.

Handles configuration persistence, updates, and notifications. Delegates business logic to ConfigLogic module.

This server provides a centralized point for configuration access and modification, with support for subscriptions to configuration changes.

See @type server_state for the internal state structure.

Examples

# Get configuration
{:ok, config} = Foundation.Services.ConfigServer.get()

# Update a configuration value
:ok = Foundation.Services.ConfigServer.update([:ai, :provider], :openai)

# Subscribe to configuration changes
:ok = Foundation.Services.ConfigServer.subscribe()

Summary

Types

metrics()

Metrics tracking for the configuration server

server_state()

Internal state of the configuration server

Functions

available?()

Check if the configuration service is available.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get()

Get the complete configuration.

get(path)

Get a configuration value by path.

init(opts)

Initialize the GenServer state.

initialize()

Initialize the configuration service with default options.

initialize(opts)

Initialize the configuration service with custom options.

reset()

Reset configuration to defaults.

reset_state()

Reset all internal state for testing purposes.

start_link(opts \\ [])

Start the configuration server.

status()

Get configuration service status.

stop()

Stop the configuration server.

subscribe(pid \\ self())

Subscribe to configuration change notifications.

unsubscribe(pid \\ self())

Unsubscribe from configuration change notifications.

updatable_paths()

Get the list of paths that can be updated at runtime.

update(path, value)

Update a configuration value at the given path.

validate(config)

Validate a configuration structure.

Types

metrics()

@type metrics() :: %{
  start_time: integer(),
  updates_count: non_neg_integer(),
  last_update: integer() | nil
}

Metrics tracking for the configuration server

server_state()

@type server_state() :: %{
  config: Foundation.Types.Config.t(),
  subscribers: [pid()],
  monitors: %{required(reference()) => pid()},
  metrics: metrics(),
  namespace: Foundation.ProcessRegistry.namespace()
}

Internal state of the configuration server

Functions

available?()

@spec available?() :: boolean()

Check if the configuration service is available.

Returns true if the GenServer is running and registered.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get()

@spec get() ::
  {:ok, Foundation.Types.Config.t()} | {:error, Foundation.Types.Error.t()}

Get the complete configuration.

Returns the current configuration or an error if the service is unavailable.

get(path)

@spec get([atom()]) :: {:ok, term()} | {:error, Foundation.Types.Error.t()}

Get a configuration value by path.

Parameters

  • path: List of atoms representing the path to the configuration value

Examples

{:ok, provider} = get([:ai, :provider])
{:ok, timeout} = get([:capture, :processing, :timeout])

init(opts)

@spec init(keyword()) :: {:ok, server_state()} | {:stop, term()}

Initialize the GenServer state.

Builds the initial configuration and sets up metrics tracking.

initialize()

@spec initialize() :: :ok | {:error, Foundation.Types.Error.t()}

Initialize the configuration service with default options.

Examples

:ok = Foundation.Services.ConfigServer.initialize()

initialize(opts)

@spec initialize(keyword()) :: :ok | {:error, Foundation.Types.Error.t()}

Initialize the configuration service with custom options.

Parameters

  • opts: Keyword list of initialization options

Examples

:ok = Foundation.Services.ConfigServer.initialize(cache_size: 1000)

reset()

@spec reset() :: :ok | {:error, Foundation.Types.Error.t()}

Reset configuration to defaults.

Resets the configuration to its default values and notifies all subscribers.

reset_state()

@spec reset_state() :: :ok | {:error, Foundation.Types.Error.t()}

Reset all internal state for testing purposes.

Clears all subscribers, metrics, and resets configuration to defaults. This function should only be used in test environments.

start_link(opts \\ [])

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

Start the configuration server.

Parameters

  • opts: Keyword list of options passed to GenServer initialization
    • :namespace - The namespace to register in (defaults to :production)

status()

@spec status() :: {:ok, map()} | {:error, Foundation.Types.Error.t()}

Get configuration service status.

Examples

{:ok, status} = Foundation.Services.ConfigServer.status()

stop()

@spec stop() :: :ok

Stop the configuration server.

subscribe(pid \\ self())

@spec subscribe(pid()) :: :ok | {:error, Foundation.Types.Error.t()}

Subscribe to configuration change notifications.

Parameters

  • pid: Process to subscribe (defaults to calling process)

Examples

:ok = Foundation.Services.ConfigServer.subscribe()
:ok = Foundation.Services.ConfigServer.subscribe(some_pid)

unsubscribe(pid \\ self())

@spec unsubscribe(pid()) :: :ok | {:error, Foundation.Types.Error.t()}

Unsubscribe from configuration change notifications.

Parameters

  • pid: Process to unsubscribe (defaults to calling process)

updatable_paths()

@spec updatable_paths() :: [[atom(), ...], ...]

Get the list of paths that can be updated at runtime.

Delegates to the ConfigLogic module for the list of updatable paths.

update(path, value)

@spec update([atom()], term()) :: :ok | {:error, Foundation.Types.Error.t()}

Update a configuration value at the given path.

Parameters

  • path: List of atoms representing the path to the configuration value
  • value: New value to set

Examples

:ok = update([:ai, :provider], :openai)
:ok = update([:capture, :ring_buffer, :size], 2048)

validate(config)

@spec validate(Foundation.Types.Config.t()) ::
  :ok | {:error, Foundation.Types.Error.t()}

Validate a configuration structure.

Delegates to the ConfigValidator module for validation logic.