Configuration

This guide covers all configuration options available in acton-reactive, including file locations, TOML format, and runtime customization.

Configuration File Locations

acton-reactive follows the XDG Base Directory Specification for configuration file locations.

Search Order

The framework searches for config.toml in these locations (in order):

Behavior

• If no configuration file is found, default values are used
• If a configuration file exists but is malformed, an error is logged and defaults are used
• Configuration is loaded once at startup and cached globally

Configuration Sections

Timeouts

Control various timeout behaviors (all values in milliseconds).

[timeouts]
# Timeout for individual actor shutdown
actor_shutdown = 10000      # 10 seconds

# Timeout for entire system shutdown
system_shutdown = 30000     # 30 seconds

# Maximum wait before flushing concurrent read-only handlers
read_only_handler_flush = 10  # 10 milliseconds

Limits

Control capacity and resource limits.

[limits]
# Maximum concurrent read-only handlers before forced flush
concurrent_handlers_high_water_mark = 100

# MPSC channel buffer size for actor message inboxes
actor_inbox_capacity = 255

# Size for dummy/placeholder channels
dummy_channel_size = 1

Understanding Handler Limits

Read-only handlers (act_on) can execute concurrently. The concurrent_handlers_high_water_mark prevents unbounded concurrency:

Defaults

Default values used when creating actors.

[defaults]
# Default actor name when none provided
actor_name = "actor"

# Default root ERN identifier
root_ern = "default"

Tracing

Configure logging and tracing levels.

[tracing]
# Verbosity settings (used by tracing-subscriber)
debug = "debug"
trace = "trace"
info = "info"

Paths

Directory paths for various file storage needs.

[paths]
# Log file directory
logs = "~/.local/share/acton/logs"

# Cache directory
cache = "~/.cache/acton"

# Data storage directory
data = "~/.local/share/acton"

# Configuration directory
config = "~/.config/acton"

Behavior

Toggle behavioral features on/off.

[behavior]
# Enable structured tracing output
enable_tracing = true

# Enable metrics collection
enable_metrics = false

Complete Reference

All Configuration Options

# acton-reactive Configuration
# Place this file at: ~/.config/acton/config.toml

[timeouts]
actor_shutdown = 10000           # ms - Individual actor shutdown timeout
system_shutdown = 30000          # ms - System-wide shutdown timeout
read_only_handler_flush = 10     # ms - Read-only handler flush timeout

[limits]
concurrent_handlers_high_water_mark = 100  # Max concurrent act_on handlers
actor_inbox_capacity = 255                  # Actor message queue size
dummy_channel_size = 1                      # Placeholder channel size

[defaults]
actor_name = "actor"             # Default actor name
root_ern = "default"             # Default root ERN

[tracing]
debug = "debug"
trace = "trace"
info = "info"

[paths]
logs = "~/.local/share/acton/logs"
cache = "~/.cache/acton"
data = "~/.local/share/acton"
config = "~/.config/acton"

[behavior]
enable_tracing = true
enable_metrics = false

Example Configurations

Development Configuration

Optimized for development with more verbose logging and shorter timeouts:

# ~/.config/acton/config.toml (Development)

[timeouts]
actor_shutdown = 5000            # 5 seconds - fail fast
system_shutdown = 10000          # 10 seconds
read_only_handler_flush = 5      # Faster flush

[limits]
concurrent_handlers_high_water_mark = 50   # Lower for debugging
actor_inbox_capacity = 100                  # Smaller queues
dummy_channel_size = 1

[tracing]
debug = "debug"
trace = "trace"
info = "info"

[behavior]
enable_tracing = true
enable_metrics = true            # Enable for development insights

Production Configuration

Optimized for production with higher capacity and longer timeouts:

# /etc/acton/config.toml (Production)

[timeouts]
actor_shutdown = 30000           # 30 seconds - graceful shutdown
system_shutdown = 60000          # 60 seconds
read_only_handler_flush = 50     # More batching

[limits]
concurrent_handlers_high_water_mark = 500  # Higher throughput
actor_inbox_capacity = 1000                 # Larger buffers
dummy_channel_size = 1

[tracing]
debug = "warn"                   # Less verbose
trace = "error"
info = "info"

[paths]
logs = "/var/log/acton"
cache = "/var/cache/acton"
data = "/var/lib/acton"
config = "/etc/acton"

[behavior]
enable_tracing = true
enable_metrics = true

Programmatic Access

Accessing Configuration

Configuration is available via the global CONFIG static:

use acton_reactive::common::config::CONFIG;

fn example() {
    // Access timeout settings
    let shutdown_timeout = CONFIG.timeouts.system_shutdown;

    // Access limits
    let inbox_size = CONFIG.limits.actor_inbox_capacity;

    // Access as Duration
    let duration = CONFIG.system_shutdown_timeout();
}

Configuration Loading

The configuration is loaded lazily on first access:

use acton_reactive::common::config::ActonConfig;

fn custom_load() {
    // Load manually (usually not needed)
    let config = ActonConfig::load();

    // Or use the global instance
    use acton_reactive::common::config::CONFIG;
    let _ = &*CONFIG; // Force load
}

IPC Configuration

When the ipc feature is enabled, additional configuration options are available.

IpcConfig Structure

pub struct IpcConfig {
    /// Unix socket path for IPC listener
    pub socket_path: PathBuf,

    /// Maximum concurrent connections
    pub max_connections: usize,

    /// Connection timeout
    pub connection_timeout: Duration,

    /// Rate limiting configuration
    pub rate_limit: Option<RateLimitConfig>,
}

Default IPC Values

Configuring IPC Programmatically

use acton_reactive::prelude::*;
use std::path::PathBuf;
use std::time::Duration;

#[cfg(feature = "ipc")]
async fn setup_ipc(runtime: &mut ActorRuntime) {
    use acton_reactive::common::ipc::IpcConfig;

    let ipc_config = IpcConfig {
        socket_path: PathBuf::from("/var/run/myapp/acton.sock"),
        max_connections: 50,
        connection_timeout: Duration::from_secs(60),
        rate_limit: None,
    };

    // Configure IPC with custom settings
    runtime.set_ipc_config(ipc_config);

    // Start the listener
    let listener = runtime.start_ipc_listener().await.expect("Failed to start IPC");
}

Best Practices

1. Use Sensible Defaults

The default configuration works well for most use cases. Only override values when you have specific requirements.

2. Adjust Inbox Capacity Based on Load

# High-throughput scenarios
[limits]
actor_inbox_capacity = 1000

# Memory-constrained scenarios
[limits]
actor_inbox_capacity = 50

3. Set Appropriate Shutdown Timeouts

Consider your application's cleanup requirements:

[timeouts]
# Simple apps: shorter timeouts
actor_shutdown = 5000

# Complex apps with DB connections, file I/O: longer timeouts
actor_shutdown = 30000

4. Monitor High Water Mark

If you see frequent handler flushes in logs, consider increasing the limit:

[limits]
concurrent_handlers_high_water_mark = 200

5. Use Different Configs Per Environment

# Development
export XDG_CONFIG_HOME=./config/dev
cargo run

# Production
export XDG_CONFIG_HOME=/etc/myapp
./my-acton-app