Struct LuaComponent 

pub struct LuaComponent { /* private fields */ }

A component implemented in Lua.

Loads a Lua script and delegates Component trait methods to Lua functions.

Script Format

The Lua script must return a table with the following structure:

return {
    id = "component-id",           -- Required: unique identifier
    subscriptions = {"Echo"},      -- Required: event categories

    on_request = function(req)     -- Required: handle requests
        return { success = true, data = ... }
    end,

    on_signal = function(sig)      -- Required: handle signals
        return "Handled" | "Ignored" | "Abort"
    end,

    init = function()              -- Optional: initialization
    end,

    shutdown = function()          -- Optional: cleanup
    end,
}

Implementations

impl LuaComponent

pub fn from_file<P: AsRef<Path>>( path: P, sandbox: Arc<dyn SandboxPolicy>, ) -> Result<Self, LuaError>

Creates a new LuaComponent from a script file.

Arguments

• path - Path to the Lua script
• sandbox - Sandbox policy for file operations and exec cwd

Errors

Returns error if:

• Script file not found
• Script syntax error
• Missing required fields/callbacks

pub fn from_dir<P: AsRef<Path>>( dir: P, sandbox: Arc<dyn SandboxPolicy>, ) -> Result<Self, LuaError>

Creates a new LuaComponent from a directory containing init.lua.

The directory is added to Lua’s package.path, enabling standard require() for co-located modules (e.g. require("lib.my_module")).

Directory Structure

components/my_component/
  init.lua              -- entry point (must return component table)
  lib/
    helper.lua          -- require("lib.helper")
  vendor/
    lua_solver/init.lua -- require("vendor.lua_solver")

Errors

Returns error if init.lua not found or script is invalid.

pub fn from_script( script: &str, sandbox: Arc<dyn SandboxPolicy>, ) -> Result<Self, LuaError>

Creates a new LuaComponent from a script string.

Arguments

• script - Lua script content
• sandbox - Sandbox policy for file operations and exec cwd

Errors

Returns error if script is invalid.

pub fn from_script_with_globals( script: &str, sandbox: Arc<dyn SandboxPolicy>, globals: Option<&Map<String, Value>>, ) -> Result<Self, LuaError>

Creates a new LuaComponent from a script string with pre-injected globals.

Each top-level key in globals is set as a Lua global variable before the script executes, enabling structured data passing without string serialization.

Design: Map<String, Value> instead of serde_json::Value

The parameter accepts Map<String, Value> (a JSON object) rather than an arbitrary serde_json::Value. This follows the parse, don’t validate principle: callers must produce a Map at the boundary, so this function never encounters non-object values and needs no unreachable!() fallback. See ComponentLoader::load_from_script for the trait-level rationale.

pub fn script_path(&self) -> Option<&str>

Returns the script path if loaded from file.

pub fn reload(&mut self) -> Result<(), LuaError>

Reloads the script from file.

Errors

Returns error if reload fails.

pub fn has_emitter(&self) -> bool

Returns whether this component has an emitter set.

When true, the component can emit events via orcs.output().

pub fn has_child_context(&self) -> bool

Returns whether this component has a child context set.

When true, the component can spawn children via orcs.spawn_child().

pub fn set_child_context(&mut self, ctx: Box<dyn ChildContext>)

Sets the child context for spawning and managing children.

Once set, the Lua script can use:

• orcs.spawn_child(config) - Spawn a child
• orcs.child_count() - Get current child count
• orcs.max_children() - Get max allowed children

Arguments

• ctx - The child context

Trait Implementations

impl Component for LuaComponent

fn init(&mut self, config: &Value) -> Result<(), ComponentError>

Calls the Lua init(cfg) callback with per-component settings.

config contains [components.settings.<name>] from config.toml, plus _global (injected by builder) with global config fields. Null or empty objects are passed as nil to Lua.

fn id(&self) -> &ComponentId

Returns the component’s identifier.

fn subscriptions(&self) -> &[EventCategory]

Returns the event categories this component subscribes to.

fn subscription_entries(&self) -> Vec<SubscriptionEntry>

Returns subscription entries with optional operation-level filtering.

fn runtime_hints(&self) -> RuntimeHints

Returns runtime hints for this component.

fn status(&self) -> Status

Returns the current execution status.

fn on_request(&mut self, request: &Request) -> Result<JsonValue, ComponentError>

Handle an incoming request.

fn on_signal(&mut self, signal: &Signal) -> SignalResponse

Handle an incoming signal.

fn abort(&mut self)

Immediate abort.

fn shutdown(&mut self)

Shutdown the component.

fn snapshot(&self) -> Result<ComponentSnapshot, SnapshotError>

Captures the component’s current state as a snapshot.

fn restore(&mut self, snapshot: &ComponentSnapshot) -> Result<(), SnapshotError>

Restores the component’s state from a snapshot.

fn set_emitter(&mut self, emitter: Box<dyn Emitter>)

Sets the event emitter for this component.

fn set_child_context(&mut self, ctx: Box<dyn ChildContext>)

Sets the child context for this component.

fn status_detail(&self) -> Option<StatusDetail>

Returns detailed status information.

fn as_packageable(&self) -> Option<&dyn Packageable>

Returns this component as a Packageable if supported.

fn as_packageable_mut(&mut self) -> Option<&mut dyn Packageable>

Returns this component as a mutable Packageable if supported.

impl Send for LuaComponent

impl Sync for LuaComponent