Trait Host 

pub trait Host: Sized {
    type Error: Into<CommandError>;

    // Required method
    fn journal(&mut self) -> &mut Journal;

    // Provided methods
    fn before(
        &mut self,
        _spec: &CommandSpec<Self>,
        _params: &mut Value,
        _depth: usize,
    ) -> Result<(), Self::Error> { ... }
    fn validate(
        &mut self,
        _spec: &CommandSpec<Self>,
        _params: &Value,
        _depth: usize,
    ) -> Result<(), CommandError> { ... }
    fn enabled_for(
        &mut self,
        spec: &CommandSpec<Self>,
        _params: &Value,
    ) -> Result<(), String> { ... }
    fn after(
        &mut self,
        _spec: &CommandSpec<Self>,
        _params: &Value,
        _result: &Result<Value, CommandError>,
        _depth: usize,
    ) { ... }
    fn rejected(&mut self, _id: &str, _error: &CommandError, _depth: usize) { ... }
    fn scrub(&self, _id: &str, _params: &mut Value) { ... }
}

The host state commands run on, and the hooks the chokepoint calls around every command.

Registry::execute runs, in order: lookup → Host::before (may rewrite params) → parameter validation (the registry’s Validation policy, then Host::validate) → Host::enabled_for → the command under catch_unwind → Host::after → journal (mutating commands that succeeded, params passed through Host::scrub). A call that is turned away before it runs goes to Host::rejected instead of after.

depth is 0 for a call from outside (UI, CLI, agent) and grows by one for each command run from inside another command; hooks use it to log or sync only once per top-level call.

The chokepoint keeps depth itself, including for commands a body runs through Registry::execute. A host touches it (Journal::set_depth) only to run a command from a hook, where the chokepoint has already put the depth back to the caller’s: to make that command count as nested in the current call (not journaled as top-level, not logged twice), save Journal::depth, set it one higher, execute, and set the saved value back.

Mutable execution state (nesting depth, the journal) lives in a Journal the host owns, so one Registry (often a static) serves any number of documents/sessions.

Required Associated Types

type Error: Into<CommandError>

The error type command bodies return. CommandError itself, or the app’s own error with From<AppError> for CommandError (leave the id empty: the chokepoint fills it in).

Required Methods

fn journal(&mut self) -> &mut Journal

The execution state: nesting depth and journal.

Provided Methods

fn before( &mut self, _spec: &CommandSpec<Self>, _params: &mut Value, _depth: usize, ) -> Result<(), Self::Error>

Rewrite params before validation (resolve names to ids, settle an ongoing gesture…). An Err refuses the call: Host::rejected sees it converted, and Registry::execute_host hands it back unchanged as ExecError::Host.

fn validate( &mut self, _spec: &CommandSpec<Self>, _params: &Value, _depth: usize, ) -> Result<(), CommandError>

Extra parameter checks after the registry’s Validation policy and before Host::enabled_for (an Err is refused and goes to Host::rejected). With Validation::Off this is where a host validates when it wants to, e.g. only at depth 0 or only for agent calls. Default: nothing.

fn enabled_for( &mut self, spec: &CommandSpec<Self>, _params: &Value, ) -> Result<(), String>

Enabled check for one call; override when explicit targets in params change availability (the state may be adjusted temporarily, e.g. targets swapped in for the selection).

fn after( &mut self, _spec: &CommandSpec<Self>, _params: &Value, _result: &Result<Value, CommandError>, _depth: usize, )

Called after every run (ok, error or panic), at every nesting depth.

fn rejected(&mut self, _id: &str, _error: &CommandError, _depth: usize)

Called when a call is refused before running: unknown command, bad params, disabled, too deeply nested, or an error from Host::before.

fn scrub(&self, _id: &str, _params: &mut Value)

Remove secrets from params before they reach the journal.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors