EngineBuilder

Builder pattern for configuring and starting the iii Engine

EngineBuilder provides a fluent API for configuring, building, and running the iii framework engine. It handles module registration, initialization, and server lifecycle.

Constructor

EngineBuilder::new()

Creates a new EngineBuilder with default settings.

pub fn new() -> Self

Returns: A new EngineBuilder instance with:

• Default module registry (from inventory)
• Address set to 0.0.0.0:49134
• Empty module list

Example:

use iii::EngineBuilder;

let builder = EngineBuilder::new();

Configuration Methods

address()

Sets the server address and port.

pub fn address(mut self, addr: &str) -> Self

addr · &str · required

Server address in format host:port (e.g., "0.0.0.0:3000")

Example:

EngineBuilder::new()
    .address("0.0.0.0:3000")

config_file_or_default()

Loads configuration from a YAML file if it exists, otherwise uses default modules.

pub fn config_file_or_default(mut self, path: &str) -> anyhow::Result<Self>

path · &str · required

Path to YAML configuration file (e.g., "config.yaml")

Returns: Result<Self> - Updated builder or error if config parsing fails

Behavior:

• If file exists: Parses YAML and loads modules from config
• If file missing: Uses default modules registered via inventory
• Supports environment variable expansion (see Configuration)

Example:

src/main.rs

EngineBuilder::new()
    .config_file_or_default(&args.config)? // Load from file or defaults
    .address(format!("0.0.0.0:{}", port).as_str())
    .build()
    .await?

register_module()

Registers a custom module type that can be instantiated by class name.

pub fn register_module<M: Module + 'static>(self, class: &str) -> Self

class · &str · required

Fully qualified class name for the module (e.g., "my::CustomModule")

M · Module · required

Type implementing the Module trait

Example:

use iii::{EngineBuilder, Module};

struct MyCustomModule;

impl Module for MyCustomModule {
    // ... implementation
}

EngineBuilder::new()
    .register_module::<MyCustomModule>("my::CustomModule")
    .add_module("my::CustomModule", None)

add_module()

Adds a module instance to be loaded at runtime.

pub fn add_module(mut self, class: &str, config: Option<Value>) -> Self

class · &str · required

Module class name (must be registered in the registry)

config · Option<Value> · default: "None"

Optional JSON configuration passed to the module’s create() method

Example:

use serde_json::json;

EngineBuilder::new()
    .add_module("my::CustomModule", Some(json!({
        "key": "value",
        "timeout": 30
    })))

Build and Execution

build()

Builds and initializes all configured modules.

pub async fn build(mut self) -> anyhow::Result<Self>

Returns: Result<Self> - Builder with initialized modules or error

Process:

1. Ensures default metrics are available
2. Adds mandatory modules if not present
3. Creates all module instances via registry
4. Calls initialize() on each module
5. Registers module functions with the engine

Example:

src/main.rs

let engine = EngineBuilder::new()
    .config_file_or_default(&args.config)?
    .address(format!("0.0.0.0:{}", port).as_str())
    .build()  // Initialize all modules
    .await?

You must call build() before serve(). The builder will panic if you call serve() without building first.

serve()

Starts the WebSocket server and begins serving requests.

pub async fn serve(self) -> anyhow::Result<()>

Returns: Result<()> - Blocks until shutdown signal received

Behavior:

1. Starts background tasks for all modules
2. Starts channel TTL sweep task
3. Sets up WebSocket routes:
   • / - Main worker connections
   • /ws/channels/{channel_id} - Channel-specific connections
4. Binds TCP listener and starts serving
5. Waits for shutdown signal (SIGTERM, SIGINT, or Ctrl+C)
6. Calls destroy() on all modules for cleanup

Example:

src/main.rs

EngineBuilder::new()
    .config_file_or_default(&args.config)?
    .address(format!("0.0.0.0:{}", port).as_str())
    .build()
    .await?
    .serve()  // Blocks until shutdown
    .await?

destroy()

Cleans up and destroys all modules. Called automatically by serve().

pub async fn destroy(self) -> anyhow::Result<()>

Returns: Result<()> - Success or first error encountered

Complete Examples

Basic Usage

src/main.rs

use iii::{EngineBuilder, logging};
use iii::modules::config::{DEFAULT_PORT, EngineConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    logging::init_log("config.yaml");

    let config = EngineConfig::config_file_or_default("config.yaml")?;
    let port = if config.port == 0 {
        DEFAULT_PORT
    } else {
        config.port
    };

    EngineBuilder::new()
        .config_file_or_default("config.yaml")?
        .address(format!("0.0.0.0:{}", port).as_str())
        .build()
        .await?
        .serve()
        .await?;
    Ok(())
}

Custom Module Registration

use iii::{EngineBuilder, Module};
use serde_json::json;

struct MyCustomModule;

impl Module for MyCustomModule {
    async fn create(
        engine: Arc<Engine>,
        config: Option<Value>,
    ) -> anyhow::Result<Box<dyn Module>> {
        // Custom initialization
        Ok(Box::new(Self))
    }
    
    // ... other trait methods
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    EngineBuilder::new()
        .register_module::<MyCustomModule>("my::CustomModule")
        .add_module("my::CustomModule", Some(json!({
            "key": "value"
        })))
        .build()
        .await?
        .serve()
        .await?;
    Ok(())
}

Programmatic Configuration

use iii::EngineBuilder;
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    EngineBuilder::new()
        .address("0.0.0.0:8080")
        .add_module("modules::api::RestApiModule", Some(json!({
            "port": 3111,
            "host": "127.0.0.1"
        })))
        .add_module("modules::queue::QueueModule", Some(json!({
            "adapter": {
                "class": "modules::queue::RedisAdapter",
                "config": {
                    "redis_url": "redis://localhost:6379"
                }
            }
        })))
        .build()
        .await?
        .serve()
        .await?;
    Ok(())
}

Type Information

Module Trait Bound

Modules registered with register_module() must implement:

pub trait Module: Send + Sync {
    async fn create(
        engine: Arc<Engine>,
        config: Option<Value>,
    ) -> anyhow::Result<Box<dyn Module>>;
    
    async fn initialize(&self) -> anyhow::Result<()>;
    fn register_functions(&self, engine: Arc<Engine>);
    async fn destroy(&self) -> anyhow::Result<()>;
    fn name(&self) -> &str;
    // ... other methods
}

Related

Configuration

Learn about EngineConfig and YAML structure

Module Trait

Module trait reference

Custom Modules

Build your own modules

Deployment

Production configuration guide