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?;

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

where T: DeserializeOwned + Default,

Like Self::load_node_config, but with an explicit instance_id instead of this context’s own Self::instance.

Node-runner (the supervisor process) is the main reason this is split out: it loads a node’s config.json on that node’s behalf, through a context that represents node-runner itself (not the node), so it can’t rely on self.instance() - it passes the target node’s --instance-id through explicitly instead. Every actual node binary (via node_main!/#[derive(Node)]) should just call Self::load_node_config, which already does the right thing from its own instance().

Instance-Keyed Config Files

For a multi-instance node (two camera nodes - one real, one simulated - both declared in mecha10.json via the {"name": "@mecha10/camera", "instance_id": "real"} node-list entry shape, LAB-4131), the resolved config file’s per-environment section may itself be a flat config object (today’s behavior, unchanged, used when instance_id is None) or a JSON object keyed by instance id:

{
  "dev": {
    "real": { "source": { "type": "v4l2", "device_path": "/dev/video0" }, "id": "real" },
    "sim":  { "source": { "type": "redis", "topic": "/camera/sim/raw" }, "id": "sim" }
  }
}

When instance_id is Some(id), the sub-object at that key is used as the node’s config (same shape/validation as today’s flat config). An instance_id that isn’t present as a key is an error, rather than silently falling back to T::default() - a multi-instance node whose config is missing an instance’s entry has a real misconfiguration, not an absent config file.

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

where T: DeserializeOwned + Default + JsonSchema,

Same as Self::load_node_config, but also validates the loaded JSON against T’s own schemars-derived JSON Schema before deserializing into it (LAB-4066).

This is the load-at-startup counterpart to mecha10_core::schema_validation’s preflight validation (validate_project_config/mecha10 config validate), using the same “every node supplies its own schema” principle that validation’s declared-schema lookup is built on – except here there is no lookup and no “missing schema” case to hard-error on: T: JsonSchema means T’s own derived schema always exists, enforced by the type system at compile time rather than by a runtime registry/convention check. node_main! and #[derive(Node)]’s generated run() call this (not Self::load_node_config) so every node – built-in or custom – gets this check for free the moment its Config struct derives JsonSchema (already required to export a schema for it at all, see mecha10-schema-registry).

Not used for Self::load_node_config callers that read another node’s config file generically through a deliberately-partial/lenient struct (e.g. mecha10-node-runner’s launcher-level NodeConfig) – validating a partial struct’s derived schema against another node’s full config would reject fields the reader never claimed to model, which isn’t this node’s schema to enforce.

Errors

Returns an error if the config file exists but fails to parse, fails schema validation, or fails to deserialize into T.

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 mecha10_core::state::ConcreteStateManager;
use std::sync::Arc;

// Use in-memory state manager for testing
let mem_mgr = Arc::new(ConcreteStateManager::Memory(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