@spec adapter_args(map()) :: list()

Resolve adapter args from normalized pool config or legacy single-pool config.

@spec adapter_module(
  map(),
  keyword()
) :: module() | nil

Resolve adapter module with consistent precedence: explicit override, pool config, legacy pool_config, global adapter, then optional default.

@spec capacity_strategy(map()) :: :pool | :profile | :hybrid

Resolve capacity strategy with consistent precedence: pool config, legacy pool_config, global strategy, then defaults.

@spec data_dir() :: String.t()

Resolve the data directory used for runtime persistence.

@spec get_pool_config(atom()) :: {:ok, pool_config()} | {:error, term()}

Get configuration for a specific named pool.

Returns {:ok, config} or {:error, reason}.

The error can be :pool_not_found if the pool doesn't exist, or any error from get_pool_configs/0 if there's a configuration issue.

Examples

iex> Snakepit.Config.get_pool_config(:default)
{:ok, %{name: :default, worker_profile: :process, ...}}

@spec get_pool_configs() :: validation_result()

Get and validate pool configurations from application environment.

Supports both legacy single-pool and new multi-pool configurations.

Returns {:ok, [pool_configs]} or {:error, reason}.

Examples

# With legacy config
{:ok, [%{name: :default, worker_profile: :process, ...}]}

# With multi-pool config
{:ok, [%{name: :default, ...}, %{name: :hpc, ...}]}

@spec get_profile_module(pool_config()) :: module()

Get the profile module for a pool configuration.

Returns the module that implements the WorkerProfile behaviour.

Examples

iex> Snakepit.Config.get_profile_module(%{worker_profile: :process})
Snakepit.WorkerProfile.Process

iex> Snakepit.Config.get_profile_module(%{worker_profile: :thread})
Snakepit.WorkerProfile.Thread

@spec grpc_listener_config() :: {:ok, grpc_listener_config()} | {:error, term()}

Load and validate the gRPC listener configuration.

Returns {:ok, config} or {:error, reason}.

@spec grpc_listener_config!() :: grpc_listener_config()

Load the gRPC listener configuration or raise on error.

@spec grpc_listener_port_check_interval_ms() :: pos_integer()

Interval (ms) between port readiness checks when reusing an existing gRPC listener.

@spec grpc_listener_ready_timeout_ms() :: pos_integer()

Timeout for waiting on the gRPC listener to publish its assigned port.

@spec grpc_listener_reuse_attempts() :: pos_integer()

Number of attempts to reuse or rebind a gRPC listener before failing.

@spec grpc_listener_reuse_retry_delay_ms() :: pos_integer()

Delay (ms) between gRPC listener reuse retries.

@spec grpc_listener_reuse_wait_timeout_ms() :: pos_integer()

Max wait (ms) for an already-started gRPC listener to publish its port before retrying.

@spec grpc_stream_control_timeout_ms() :: pos_integer()

Timeout for sending telemetry control messages to Python workers.

@spec grpc_stream_open_timeout_ms() :: pos_integer()

Timeout for opening telemetry streams to Python workers.

@spec grpc_worker_health_check_timeout_ms() :: pos_integer()

Timeout (ms) for GRPCWorker periodic health-check RPC calls.

@spec heartbeat_defaults() :: map()

Returns the normalized default heartbeat configuration, merged with application env overrides.

This shape is shared with snakepit_bridge.heartbeat.HeartbeatConfig. When adding new keys, update both modules to keep the cross-language schema aligned.

@spec instance_name() :: String.t() | nil

Resolve the instance name used for runtime isolation.

@spec instance_name_identifier() :: String.t() | nil

Resolve a CLI-safe instance name identifier for process scoping.

@spec instance_token() :: String.t() | nil

Resolve the instance token used for runtime isolation.

@spec instance_token_identifier() :: String.t() | nil

Resolve a CLI-safe instance token identifier for process scoping.

@spec lifecycle_check_max_concurrency() :: pos_integer()

Maximum concurrent worker checks during lifecycle scan.

@spec lifecycle_worker_action_timeout_ms() :: pos_integer()

Timeout (ms) per worker action during lifecycle checks.

@spec multi_pool_mode?() :: boolean()

Returns true when the application is configured with explicit multi-pool mode.

@spec normalize_pool_config(map()) :: pool_config()

Normalize a pool configuration by filling in defaults.

Examples

iex> Snakepit.Config.normalize_pool_config(%{name: :test})
%{
  name: :test,
  worker_profile: :process,
  pool_size: 16,
  # ... other defaults
}

@spec pool_max_workers(map()) :: pos_integer()

Resolve max workers for a pool, preserving legacy :pool_config fallback.

@spec pool_startup_batch_delay_ms(map()) :: non_neg_integer()

Resolve startup batch delay (ms) for process-profile worker initialization.

@spec pool_startup_batch_size(map()) :: pos_integer()

Resolve startup batch size for process-profile worker initialization.

@spec process_registry_dets_flush_interval_ms() :: pos_integer()

Interval (ms) for batching DETS flushes in Snakepit.Pool.ProcessRegistry.

@spec rogue_cleanup_config() :: map()

Normalized rogue cleanup configuration for process registry startup cleanup.

@spec thread_profile?(pool_config()) :: boolean()

Check if a pool configuration is using the thread profile.

Examples

iex> Snakepit.Config.thread_profile?(%{worker_profile: :thread})
true

iex> Snakepit.Config.thread_profile?(%{worker_profile: :process})
false

@spec validate_pool_config(map()) :: {:ok, pool_config()} | {:error, term()}

Validate a single pool configuration.

Returns {:ok, normalized_config} or {:error, reason}.

@spec worker_supervisor_cleanup_max_retries() :: pos_integer()

Worker restart cleanup maximum retry attempts.

@spec worker_supervisor_cleanup_retry_interval_ms() :: pos_integer()

Worker restart cleanup polling interval in milliseconds.