Trait Plugin 

pub trait Plugin: Send + Sync {
    // Required method
    fn config(&self) -> &PluginConfig;

    // Provided methods
    fn initialize<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Box<PluginError>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn shutdown<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<(), Box<PluginError>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
}

Core plugin interface — lifecycle management only.

Every plugin in the CPEX framework — regardless of language or deployment model — implements this trait. It covers lifecycle (initialize, shutdown) and identity (config). Hook-specific logic is defined separately by handler traits generated by define_hook!.

Lifecycle

1. initialize() — called once after loading, before any hooks fire.
2. Hook handlers — called on each hook invocation (defined by handler traits).
3. shutdown() — called once during graceful teardown.

Hook Handlers

A plugin implements one or more handler traits alongside Plugin:

impl Plugin for MyPlugin {
    fn config(&self) -> &PluginConfig { &self.config }
    async fn initialize(&self) -> Result<(), Box<PluginError>> { Ok(()) }
    async fn shutdown(&self) -> Result<(), Box<PluginError>> { Ok(()) }
}

impl CmfHookHandler for MyPlugin {
    fn cmf_hook(&self, payload: MessagePayload, ext: &Extensions, ctx: &PluginContext) -> PluginResult<MessagePayload> {
        PluginResult::allow()
    }
}

Trust Model

The manager wraps each plugin in a PluginRef with an authoritative config from the config loader. The executor reads scheduling decisions (mode, priority, hooks, capabilities) from the PluginRef — never from plugin.config(). The plugin’s own config() is available for the plugin’s reading during hook execution.

Implementors

• Native Rust plugins (implement directly)
• cpex-hosts::wasm (bridges to WASM guest via wasmtime)
• cpex-hosts::python (bridges to Python plugin classes via PyO3)
• cpex-hosts::native (bridges to dlopen’d shared libraries)

Required Methods

fn config(&self) -> &PluginConfig

Returns the plugin’s configuration.

Available for the plugin’s own reading during hook execution. The manager/executor never reads this — they use the authoritative config from PluginRef.trusted_config().

Provided Methods

fn initialize<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), Box<PluginError>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

One-time initialization after loading.

Called before any hook invocations. Use this to establish connections, load resources, or validate configuration. Default implementation does nothing.

fn shutdown<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<(), Box<PluginError>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Graceful shutdown.

Called once during teardown. Use this to flush buffers, close connections, or release resources. Default implementation does nothing.

Dyn Compatibility

This trait is dyn compatible.

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

Implementors