Engine Configuration

The iii Engine is configured via a YAML file (default: config.yaml). Configuration supports environment variable expansion and module-specific settings.

Configuration File

Default Location: config.yaml Override: iii --config path/to/config.yaml Example Location: engine/config.yaml

Structure

port: 49134  # Optional: WebSocket port (default: 49134)

modules:
  - class: modules::api::RestApiModule
    config:
      # Module-specific configuration
  - class: modules::queue::QueueModule
    config:
      # Module-specific configuration

Environment Variables

Configuration files support environment variable expansion:

${VARIABLE_NAME:default_value}

Examples:

modules:
  - class: modules::queue::QueueModule
    config:
      adapter:
        config:
          redis_url: ${REDIS_URL:redis://localhost:6379}

If REDIS_URL is set, it will be used; otherwise, redis://localhost:6379 is the default.

Top-Level Options

port

Type: number Default: 49134 Description: WebSocket port for worker connections

port: 49134

modules

Type: array Default: Default modules (if config file is missing) Description: List of modules to load

modules:
  - class: modules::api::RestApiModule
  - class: modules::queue::QueueModule

Default Modules

If no config.yaml is found, the engine loads:

modules::api::RestApiModule
modules::queue::QueueModule
modules::cron::CronModule
modules::stream::StreamModule
modules::observability::OtelModule

Module Configuration

Each module has its own configuration schema:

REST API Module

Class: modules::api::RestApiModule

- class: modules::api::RestApiModule
  config:
    port: 3111
    host: 127.0.0.1
    default_timeout: 30000  # milliseconds
    concurrency_request_limit: 1024
    cors:
      allowed_origins:
        - '*'  # Use '*' for all origins, or list specific origins
      allowed_methods:
        - GET
        - POST
        - PUT
        - DELETE
        - OPTIONS

Options:

port (number, default: 3111): HTTP server port
host (string, default: "127.0.0.1"): Bind address
default_timeout (number, default: 30000): Request timeout in milliseconds
concurrency_request_limit (number, default: 1024): Max concurrent requests
cors.allowed_origins (array): CORS allowed origins
cors.allowed_methods (array): CORS allowed HTTP methods

Queue Module

Class: modules::queue::QueueModule

- class: modules::queue::QueueModule
  config:
    adapter:
      class: modules::queue::RedisAdapter
      config:
        redis_url: redis://localhost:6379

Adapter Options:

RedisAdapter

adapter:
  class: modules::queue::RedisAdapter
  config:
    redis_url: redis://localhost:6379

RabbitMQAdapter

adapter:
  class: modules::queue::RabbitMQAdapter
  config:
    amqp_url: amqp://localhost:5672

BuiltinAdapter (In-Memory)

adapter:
  class: modules::queue::BuiltinAdapter
  config: {}

Cron Module

Class: modules::cron::CronModule

- class: modules::cron::CronModule
  config:
    adapter:
      class: modules::cron::KvCronAdapter
      # or modules::cron::RedisAdapter

Adapter Options:

KvCronAdapter (File-Based)

adapter:
  class: modules::cron::KvCronAdapter
  config: {}

RedisAdapter

adapter:
  class: modules::cron::RedisAdapter
  config:
    redis_url: redis://localhost:6379

State Module

Class: modules::state::StateModule

- class: modules::state::StateModule
  config:
    adapter:
      class: modules::state::adapters::KvStore
      config:
        store_method: file_based  # Options: in_memory, file_based
        file_path: ./data/state_store.db

Adapter Options:

KvStore

adapter:
  class: modules::state::adapters::KvStore
  config:
    store_method: file_based  # or in_memory
    file_path: ./data/state_store.db  # Required for file_based

RedisAdapter

adapter:
  class: modules::state::adapters::RedisAdapter
  config:
    redis_url: redis://localhost:6379

Stream Module

Class: modules::stream::StreamModule

- class: modules::stream::StreamModule
  config:
    port: 3112
    host: 127.0.0.1
    adapter:
      class: modules::stream::adapters::RedisAdapter
      config:
        redis_url: redis://localhost:6379

Options:

port (number, default: 3112): WebSocket server port for clients
host (string, default: "127.0.0.1"): Bind address

Adapter Options:

RedisAdapter

adapter:
  class: modules::stream::adapters::RedisAdapter
  config:
    redis_url: redis://localhost:6379

KvStore (In-Memory)

adapter:
  class: modules::stream::adapters::KvStore
  config:
    store_method: in_memory

KV Server Module

Class: modules::kv_server::KvServer

- class: modules::kv_server::KvServer
  config:
    store_method: file_based  # Options: in_memory, file_based
    file_path: ./data/kv_store
    save_interval_ms: 5000

Options:

store_method (string): "in_memory" or "file_based"
file_path (string): Path to persistent storage (for file_based)
save_interval_ms (number, default: 5000): Save interval in milliseconds

Observability Module

Class: modules::observability::OtelModule

- class: modules::observability::OtelModule
  config:
    # Core Configuration
    enabled: true
    service_name: iii
    service_version: 0.2.0
    service_namespace: production

    # Trace Exporter
    exporter: otlp  # Options: otlp, memory, both
    endpoint: http://localhost:4317

    # Sampling
    sampling_ratio: 1.0

    # Memory Storage
    memory_max_spans: 10000

    # Metrics
    metrics_enabled: true
    metrics_exporter: memory  # Options: memory, otlp
    metrics_retention_seconds: 3600
    metrics_max_count: 10000

    # Logs
    logs_enabled: true
    logs_exporter: memory  # Options: memory, otlp, both
    logs_max_count: 1000
    logs_retention_seconds: 3600
    logs_batch_size: 100
    logs_flush_interval_ms: 5000
    logs_sampling_ratio: 1.0
    logs_console_output: true

Core Options:

enabled (boolean, default: true): Enable/disable observability
service_name (string, default: "iii"): Service name in traces
service_version (string): Service version
service_namespace (string): Service namespace (e.g., "production")

Trace Options:

exporter (string): "otlp", "memory", or "both"
endpoint (string): OTLP collector endpoint
sampling_ratio (number, 0.0-1.0): Sampling rate (1.0 = 100%)
memory_max_spans (number): Max spans to keep in memory

Advanced Sampling:

sampling:
  default: 0.1  # 10% default
  parent_based: true  # Respect parent span sampling
  rules:
    - operation: "health.*"
      rate: 0.01  # 1% for health checks
    - operation: "api.critical.*"
      rate: 1.0  # 100% for critical APIs
    - service: "payment-*"
      rate: 1.0  # 100% for payment services
  rate_limit:
    max_traces_per_second: 100

Metrics Options:

metrics_enabled (boolean, default: true): Enable metrics
metrics_exporter (string): "memory" or "otlp"
metrics_retention_seconds (number): How long to keep metrics
metrics_max_count (number): Max metrics to store

Logs Options:

logs_enabled (boolean, default: true): Enable logs
logs_exporter (string): "memory", "otlp", or "both"
logs_max_count (number): Max log records to store
logs_retention_seconds (number): How long to keep logs
logs_batch_size (number): Batch size for OTLP export
logs_flush_interval_ms (number): Flush interval in milliseconds
logs_sampling_ratio (number, 0.0-1.0): Log sampling rate
logs_console_output (boolean): Output SDK logs to engine console

Alert Rules (Optional):

alerts:
  - name: high_error_rate
    metric: iii.invocations.error
    threshold: 100
    operator: ">"  # Options: >, >=, <, <=, ==, !=
    window_seconds: 60
    cooldown_seconds: 300
    action: log  # Options: log, webhook, function
    # webhook_url: https://hooks.example.com/alert
    # function_id: alerts.handle_error

Bridge Client Module

Class: modules::bridge_client::BridgeClientModule Purpose: Connect to remote iii engine and forward/expose functions

- class: modules::bridge_client::BridgeClientModule
  config:
    url: ws://remote-engine:49134
    service_id: bridge-client
    service_name: bridge-client
    expose:
      - local_function: logger.info
        remote_function: logger.info
    forward:
      - local_function: remote.kv.get
        remote_function: kv_server.get
        timeout_ms: 5000

Options:

url (string): Remote engine WebSocket URL
service_id (string): Service identifier
service_name (string): Service name
expose (array): Expose local functions to remote engine
forward (array): Forward remote functions to local engine

Complete Example

Here’s a production-ready configuration:

port: 49134

modules:
  # REST API
  - class: modules::api::RestApiModule
    config:
      port: ${API_PORT:3111}
      host: 0.0.0.0
      default_timeout: 30000
      concurrency_request_limit: 2048
      cors:
        allowed_origins:
          - https://app.example.com
        allowed_methods:
          - GET
          - POST
          - PUT
          - DELETE
          - OPTIONS

  # Queue with Redis
  - class: modules::queue::QueueModule
    config:
      adapter:
        class: modules::queue::RedisAdapter
        config:
          redis_url: ${REDIS_URL:redis://localhost:6379}

  # Cron with Redis coordination
  - class: modules::cron::CronModule
    config:
      adapter:
        class: modules::cron::RedisAdapter
        config:
          redis_url: ${REDIS_URL:redis://localhost:6379}

  # State with Redis backend
  - class: modules::state::StateModule
    config:
      adapter:
        class: modules::state::adapters::RedisAdapter
        config:
          redis_url: ${REDIS_URL:redis://localhost:6379}

  # Stream with Redis pub/sub
  - class: modules::stream::StreamModule
    config:
      port: ${STREAM_PORT:3112}
      host: 0.0.0.0
      adapter:
        class: modules::stream::adapters::RedisAdapter
        config:
          redis_url: ${REDIS_URL:redis://localhost:6379}

  # Observability with OTLP export
  - class: modules::observability::OtelModule
    config:
      enabled: ${OTEL_ENABLED:true}
      service_name: ${SERVICE_NAME:iii}
      service_version: ${SERVICE_VERSION:0.2.0}
      service_namespace: ${ENVIRONMENT:production}
      exporter: otlp
      endpoint: ${OTEL_ENDPOINT:http://localhost:4317}
      sampling_ratio: ${SAMPLING_RATIO:1.0}
      metrics_enabled: true
      logs_enabled: true

Minimal Configuration

For development without external dependencies:

modules:
  - class: modules::api::RestApiModule
    config:
      port: 3111
      host: 127.0.0.1

  - class: modules::queue::QueueModule
    config:
      adapter:
        class: modules::queue::BuiltinAdapter

  - class: modules::cron::CronModule
    config:
      adapter:
        class: modules::cron::KvCronAdapter

  - class: modules::observability::OtelModule
    config:
      enabled: false

Configuration Loading

Implementation: src/modules/config.rs The engine loads configuration in this order:

Read YAML file (or use defaults if missing)
Expand environment variables
Parse YAML into EngineConfig struct
Validate module class names
Create modules with configurations

Docker Configuration

Mount configuration as read-only volume:

docker run -p 3111:3111 -p 49134:49134 \
  -v ./config.yaml:/app/config.yaml:ro \
  iiidev/iii:latest

Ports Reference

Port	Service	Config Key
49134	WebSocket (workers)	Top-level `port`
3111	HTTP API	`RestApiModule.config.port`
3112	Stream API (WebSocket)	`StreamModule.config.port`
9464	Prometheus metrics	(auto-configured by OtelModule)

Next Steps

Engine Overview - Architecture and concepts
Modules Reference - Module documentation
Protocol Reference - WebSocket message types

​Engine Configuration

​Configuration File

​Structure

​Environment Variables

​Top-Level Options

​port

​modules

​Default Modules

​Module Configuration

​REST API Module

​Queue Module

​RedisAdapter

​RabbitMQAdapter

​BuiltinAdapter (In-Memory)

​Cron Module

​KvCronAdapter (File-Based)

​RedisAdapter

​State Module

​KvStore

​RedisAdapter

​Stream Module

​RedisAdapter

​KvStore (In-Memory)

​KV Server Module

​Observability Module

​Bridge Client Module

​Complete Example

​Minimal Configuration

​Configuration Loading

​Docker Configuration

​Ports Reference

​Next Steps

Engine Configuration

Configuration File

Structure

Environment Variables

Top-Level Options

port

modules

Default Modules

Module Configuration

REST API Module

Queue Module

RedisAdapter

RabbitMQAdapter

BuiltinAdapter (In-Memory)

Cron Module

KvCronAdapter (File-Based)

RedisAdapter

State Module

KvStore

RedisAdapter

Stream Module

RedisAdapter

KvStore (In-Memory)

KV Server Module

Observability Module

Bridge Client Module

Complete Example

Minimal Configuration

Configuration Loading

Docker Configuration

Ports Reference

Next Steps