Struct Context 

pub struct Context { /* private fields */ }

Implementations

impl Context

pub fn builder(node_id: impl Into<String>) -> ContextBuilder

Create a context builder

Shorthand for ContextBuilder::new(node_id).

Example

let ctx = Context::builder("my-node")
    .with_instance("instance-1")
    .build()
    .await?;

impl Context

pub fn get_redis_url() -> Result<String>

Get Redis URL from infrastructure configuration

pub fn get_control_plane_redis_url() -> Result<Option<String>>

Get control plane Redis URL from infrastructure configuration

impl Context

pub async fn new(node_id: &str) -> Result<Self>

Create a new context

Arguments

• node_id - Unique identifier for this node (fallback if NODE_NAME env var not set)

Environment Variables

• NODE_NAME - If set, overrides the node_id parameter. This allows node-runner to set full identifiers like @mecha10/speaker for consistent naming across the CLI, dashboard, and health reporting.

Example

let ctx = Context::new("my-node").await?;

pub fn with_instance(self, instance: &str) -> Self

Set an instance name for this context (builder pattern)

This allows the same node implementation to run multiple instances with different names. The node_id becomes “{node_name}/{instance}”.

Example

// Single instance (no instance name)
let ctx = Context::new("camera_fake").await?;
// node_id: "camera_fake"

// Multi-instance (with instance names)
let left_ctx = Context::new("camera_fake").await?.with_instance("left");
// node_id: "camera_fake/left"

let right_ctx = Context::new("camera_fake").await?.with_instance("right");
// node_id: "camera_fake/right"

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

Get the instance name if set

Returns None for single-instance nodes, or Some(instance) for multi-instance nodes.

pub fn node_id(&self) -> &str

Get the node ID

pub async fn is_shutdown(&self) -> bool

Check if shutdown has been requested

pub async fn shutdown(&self)

Request shutdown

pub async fn wait_for_shutdown(&self)

Wait for shutdown signal

pub fn logging_span(&self) -> Span

Enter a logging span with this node’s context

This returns a guard that, when entered, adds the node_id to all log messages. The span is automatically exited when the guard is dropped.

Example

use mecha10_core::prelude::*;

let _guard = ctx.logging_span().entered();
info!("This message includes node_id automatically");
debug!("So does this one");

impl Context

pub async fn load_node_config<T>(&self, node_name: &str) -> Result<T>

where T: DeserializeOwned + Default,

Load node configuration with environment-aware file-level fallback

This method implements the V2 configuration system with:

• Environment-specific configs (dev/staging/production), selected within a config file’s {"dev": {...}, "production": {...}} envelope (see Self::load_environment_aware_config)
• File-level fallback (no key-by-key merging)
• Automatic project-root discovery via crate::fs_utils::find_project_root

Tier order (mirrors mecha10_cli_core::paths::config::node_config_candidates, the canonical 2-tier resolution order for node configs – this method can’t call that helper directly since mecha10-core is a dependency of mecha10-cli-core, not the reverse, but it must stay in sync with it):

1. configs/nodes/@mecha10/{node_name}/config.json - Framework nodes
2. configs/nodes/{node_name}/config.json - Project nodes (preferred)
3. T::default() - Default implementation, if neither tier has a config file (or no project root could be found)

Environment Detection:

• Uses MECHA10_ENV env var (default: “dev”)
• Supported values: “dev”, “staging”, “production”, or custom

Semantic Validation:

• Not run here. This method is generic over T with only a DeserializeOwned + Default bound, and stable Rust has no specialization – a function generic over T can’t conditionally call crate::config::Validate::validate only when T happens to implement it. Node types that need semantic validation should call validate() explicitly on the config returned here.

Type Parameters

• T - Configuration type that implements DeserializeOwned + Default

Arguments

• node_name - Name of the node (e.g., “simulator”, “camera-streamer”)

Returns

The loaded configuration of type T, using the first available source in the fallback chain.

Example

use mecha10_core::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Deserialize, Serialize, Default)]
struct SimBridgeConfig {
    camera_width: u32,
    camera_height: u32,
    camera_fps: u32,
}

let config: SimBridgeConfig = ctx.load_node_config("simulator").await?;

impl Context

pub async fn state_manager(&self) -> Result<Arc<ConcreteStateManager>>

Get or create a state manager for this node

The state manager provides persistent storage for node state across restarts. By default, it uses filesystem storage in ./state/ directory.

Example

use mecha10_core::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize)]
struct MyState {
    counter: u64,
    position: (f64, f64),
}

let state_mgr = ctx.state_manager().await?;

// Load previous state
let mut state = state_mgr
    .load::<MyState>("my_node")
    .await?
    .unwrap_or(MyState {
        counter: 0,
        position: (0.0, 0.0),
    });

// Update state
state.counter += 1;

// Save state
state_mgr.save("my_node", &state).await?;

pub async fn set_state_manager(&self, manager: Arc<ConcreteStateManager>)

Set a custom state manager for this context

This allows using alternative backends (Redis, PostgreSQL, etc.) or custom implementations.

Example

use mecha10_core::prelude::*;
use std::sync::Arc;

// Use in-memory state manager for testing
let mem_mgr = Arc::new(MemoryStateManager::new());
ctx.set_state_manager(mem_mgr).await;

Trait Implementations

impl AuthExt for Context

async fn register_policy(&self, policy: &Policy) -> Result<()>

Register a policy

async fn get_policy(&self, role: &str) -> Result<Option<Policy>>

Get a policy by role name

async fn list_policies(&self) -> Result<Vec<Policy>>

List all registered policies

async fn assign_role(&self, node_id: &str, role: &str) -> Result<()>

Assign a role to a node

async fn get_role(&self, node_id: &str) -> Result<Option<String>>

Get the role assigned to a node

async fn check_permission( &self, node_id: &str, permission: Permission, topic: &str, ) -> Result<bool>

Check if a node has permission to perform an action on a topic

async fn delete_policy(&self, role: &str) -> Result<()>

Delete a policy

async fn unassign_role(&self, node_id: &str) -> Result<()>

Remove role assignment from a node

impl Clone for Context

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl SchemaRegistryExt for Context

async fn register_schema(&self, schema: &MessageSchema) -> Result<()>

Register a schema in the registry

async fn get_schema( &self, name: &str, version: u32, ) -> Result<Option<MessageSchema>>

Get a specific version of a schema

async fn get_latest_schema(&self, name: &str) -> Result<Option<MessageSchema>>

Get the latest version of a schema

async fn list_schemas(&self) -> Result<Vec<MessageSchema>>

List all registered schemas (returns latest version of each)

async fn get_schema_versions(&self, name: &str) -> Result<Vec<MessageSchema>>

Get all versions of a schema

async fn delete_schema(&self, name: &str, version: Option<u32>) -> Result<()>

Delete a schema version

impl SchemaVersioningExt for Context

async fn check_compatibility( &self, name: &str, old_version: u32, new_version: u32, mode: CompatibilityMode, ) -> Result<CompatibilityCheck>

Check compatibility between two schema versions

async fn register_versioned_schema( &self, schema: &MessageSchema, mode: CompatibilityMode, ) -> Result<CompatibilityCheck>

Register a new schema version with compatibility check

async fn get_version_info( &self, name: &str, ) -> Result<Option<MessageVersionInfo>>

Get version info for a message type

async fn deprecate_version( &self, name: &str, version: u32, message: String, ) -> Result<()>

Mark a schema version as deprecated

async fn is_version_deprecated(&self, name: &str, version: u32) -> Result<bool>

Check if using a deprecated version