`mod plugin`#

module plugin#

Generic plugin infrastructure for NeMo Flow runtimes.

This module owns:

config diagnostics and policy enums used by plugin systems
a global plugin registry
plugin registration contexts for middleware/subscriber installation
rollback bookkeeping for registrations created during plugin setup

Types

type Result<T>#: Specialized Result type for plugin operations.

Functions

fn active_plugin_report() -> Option<ConfigReport>#: Returns the last successfully configured plugin report.

None indicates that no plugin configuration is currently active.

Returns

The last successful ConfigReport, or None when no configuration is active.

Notes

This is a snapshot of the last successful activation and does not re-run validation.

fn clear_plugin_configuration() -> Result<()>#: Deregisters and clears all configured plugin components.

Registered plugin kinds remain available for future validation and initialization.

Returns

A plugin Result that is Ok(()) when the active configuration has been cleared.

Errors

Returns an error when the active configuration lock is poisoned.

Notes

Clearing active configuration does not remove plugin kinds from the global registry.

fn deregister_plugin(plugin_kind: &str) -> bool#

Removes a previously registered plugin.

This affects future validation and initialization only. Active runtime registrations remain until cleared or replaced.

Parameters

plugin_kind: Plugin kind to remove from the registry.

Returns

true when a plugin was removed from the registry and false when the kind was not registered.

Notes

Active component registrations created by previous initialization calls are not removed by this function.

async fn initialize_plugins(config: PluginConfig) -> Result<ConfigReport>#

Configures the active global plugin components.

Initialization validates the supplied config, replaces the active configuration, and rolls back partial registration on failure. If a previous configuration was active, the host attempts to restore it when the new activation fails.

Parameters

config: Plugin configuration to validate and activate.

Returns

A plugin Result containing the successful ConfigReport.

Errors

Returns an error when validation fails, when plugin registration fails, or when the previous configuration cannot be restored after a failed replace.

Notes

Initialization is replace-with-rollback: the previous active configuration is removed before the new configuration is activated.

fn list_plugin_kinds() -> Vec<String>#: Lists registered plugin kinds in sorted order.

This returns the currently registered plugin kinds without inspecting the active runtime configuration.

Returns

A sorted Vec<String> of registered plugin kinds.

Notes

Disabled or inactive components still appear here when their plugin kind is registered.

fn lookup_plugin(plugin_kind: &str) -> Option<Arc<dyn Plugin>>#

Looks up a registered plugin by kind.

Parameters

plugin_kind: Plugin kind to resolve.

Returns

The registered plugin implementation for plugin_kind, or None when the kind is unknown.

Notes

The returned plugin is shared by Arc, so callers receive a cheap clone.

fn register_plugin(plugin: Arc<dyn Plugin>) -> Result<()>#

Registers a plugin by kind.

Registering the same kind twice returns PluginError::RegistrationFailed. Register a plugin kind with the global plugin registry.

Registered plugins can then participate in validation and initialization of PluginConfig documents.

Parameters

plugin: Plugin implementation to register.

Returns

A plugin Result that is Ok(()) when the plugin kind was added to the registry.

Errors

Returns an error when a plugin with the same kind is already registered or when the registry lock is poisoned.

Notes

Registration affects future validation and initialization only.

fn rollback_registrations(registrations: &mut Vec<PluginRegistration>)#: Rolls back registrations in reverse order, ignoring rollback failures.

This is used internally during failed initialization and by clear_plugin_configuration.

fn validate_plugin_config(config: &PluginConfig) -> ConfigReport#

Validates a plugin configuration document.

This is a pure validation pass. It does not mutate the active runtime configuration.

Parameters

config: Plugin configuration to validate.

Returns

A ConfigReport describing warnings and errors discovered during validation.

Notes

Validation checks host policy, plugin multiplicity rules, unknown component kinds, and plugin-provided validation hooks.

Traits

trait Plugin#

Implemented by custom plugins that register runtime middleware.

Functions

fn allows_multiple_components(&self) -> bool#: Returns whether the plugin kind can appear multiple times in the config.

Return false for singleton components such as the built-in adaptive component.

fn plugin_kind(&self) -> &str#: Returns the unique plugin kind string.

fn register<'a>(&'a self, plugin_config: &Map<String, Json>, ctx: &'a mut PluginRegistrationContext) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'a>>#: Registers runtime middleware/subscribers for one plugin component.

The provided PluginRegistrationContext is component-scoped. Any error aborts the current initialization and triggers rollback of registrations created during the failed activation attempt.

fn validate(&self, plugin_config: &Map<String, Json>) -> Vec<ConfigDiagnostic>#: Validates one plugin component config.

Returning error-level diagnostics prevents initialize_plugins(...) from activating the configuration.

Enums

enum DiagnosticLevel#

Diagnostic severity.

Warning#: Non-fatal compatibility or validation issue.

Error#: Fatal validation issue that blocks initialization.

enum PluginError#

Error type for generic plugin operations.

InvalidConfig(String)#: Configuration validation failed.

NotFound(String)#: The requested plugin resource was not found.

Serialization(serde_json::Error)#: A serialization or deserialization operation failed.

Internal(String)#: An internal plugin-system error occurred.

RegistrationFailed(String)#: A runtime middleware/subscriber registration failed.

enum UnsupportedBehavior#

Per-policy behavior for unsupported configuration.

Ignore#: Suppress the diagnostic entirely.

Warn#: Emit a warning diagnostic.

Error#: Emit an error diagnostic.

Structs and Unions

struct ConfigDiagnostic#

One validation or compatibility diagnostic.

level: DiagnosticLevel#: Severity level for the diagnostic.

code: String#: Stable diagnostic code suitable for machine checks.

component: Option<String>#: Optional component identifier associated with the diagnostic.

field: Option<String>#: Optional field path associated with the diagnostic.

message: String#: Human-readable diagnostic message.

struct ConfigPolicy#

Policy for how unsupported plugin/runtime config is handled.

unknown_component: UnsupportedBehavior#: Policy applied when a component kind is unknown to the plugin registry.

unknown_field: UnsupportedBehavior#: Policy applied when a known component contains an unknown field.

unsupported_value: UnsupportedBehavior#: Policy applied when a known field contains an unsupported value.

Traits implemented

impl Default for ConfigPolicy#

struct ConfigReport#

Structured validation report.

diagnostics: Vec<ConfigDiagnostic>#: Validation and compatibility diagnostics in evaluation order.

Implementations

impl ConfigReport#

Functions

fn has_errors(&self) -> bool#: Returns true when the report contains at least one error diagnostic.

struct PluginComponentSpec#

One configured plugin component.

kind: String#: Registered plugin kind string.

enabled: bool#: Whether the component should be activated.

Disabled components are still validated but skipped during runtime registration.

config: Map<String, Json>#: Component-local JSON config object passed to the plugin.

Implementations

impl PluginComponentSpec#

Functions

fn new(kind: impl Into<String>) -> Self#: Creates a new enabled component spec with empty config.

struct PluginConfig#

Canonical plugin configuration document.

version: u32#: Plugin config schema version.

components: Vec<PluginComponentSpec>#: Ordered list of top-level plugin components to validate and activate.

policy: ConfigPolicy#: Plugin-level policy for unsupported plugin kinds, fields, and values.

Traits implemented

impl Default for PluginConfig#

struct PluginRegistration#

Bookkeeping for one middleware/subscriber registration.

kind: String#: Registration kind used for bookkeeping.

name: String#: Runtime-qualified registration name.

Implementations

impl PluginRegistration#

Functions

fn new(kind: impl Into<String>, name: impl Into<String>, deregister: Box<dyn FnMut) -> Result<()> + Send>) -> Self#: Creates a new registration bookkeeping entry.

Traits implemented

impl fmt::Debug for PluginRegistration#

struct PluginRegistrationContext#

Context provided to plugin handlers during runtime registration.

Each register_* call both installs the middleware/subscriber into the NeMo Flow runtime and records the inverse deregistration closure so the host can roll back partial setup on failure.

Implementations

impl PluginRegistrationContext#

Functions

fn add_registration(&mut self, registration: PluginRegistration)#: Adds a prebuilt registration to the context.

fn extend_registrations(&mut self, registrations: Vec<PluginRegistration>)#: Extends the context with prebuilt registrations.

fn into_registrations(self) -> Vec<PluginRegistration>#: Consumes the context and returns the recorded registrations.

fn new() -> Self#: Creates an empty plugin registration context.

fn qualify_name(&self, name: &str) -> String#: Returns the runtime-qualified name for a plugin-local registration.

Plugin handlers should pass stable component-local names such as "tool" or "subscriber". The host applies the namespace so users do not have to provide component instance ids.

fn register_llm_conditional_execution_guardrail(&mut self, name: &str, priority: i32, callback: LlmConditionalFn) -> Result<()>#: Registers an LLM conditional-execution guardrail and records its rollback closure.

fn register_llm_execution_intercept(&mut self, name: &str, priority: i32, callback: LlmExecutionFn) -> Result<()>#: Registers an LLM execution intercept and records its rollback closure.

fn register_llm_request_intercept(&mut self, name: &str, priority: i32, break_chain: bool, callback: LlmRequestInterceptFn) -> Result<()>#: Registers an LLM request intercept and records its rollback closure.

fn register_llm_sanitize_request_guardrail(&mut self, name: &str, priority: i32, callback: LlmSanitizeRequestFn) -> Result<()>#: Registers an LLM sanitize-request guardrail and records its rollback closure.

fn register_llm_sanitize_response_guardrail(&mut self, name: &str, priority: i32, callback: LlmSanitizeResponseFn) -> Result<()>#: Registers an LLM sanitize-response guardrail and records its rollback closure.

fn register_llm_stream_execution_intercept(&mut self, name: &str, priority: i32, callback: LlmStreamExecutionFn) -> Result<()>#: Registers an LLM stream execution intercept and records its rollback closure.

fn register_subscriber(&mut self, name: &str, callback: EventSubscriberFn) -> Result<()>#: Registers an event subscriber and records its rollback closure.

fn register_tool_conditional_execution_guardrail(&mut self, name: &str, priority: i32, callback: ToolConditionalFn) -> Result<()>#: Registers a tool conditional-execution guardrail and records its rollback closure.

fn register_tool_execution_intercept(&mut self, name: &str, priority: i32, callback: ToolExecutionFn) -> Result<()>#: Registers a tool execution intercept and records its rollback closure.

fn register_tool_request_intercept(&mut self, name: &str, priority: i32, break_chain: bool, callback: ToolInterceptFn) -> Result<()>#: Registers a tool request intercept and records its rollback closure.

fn register_tool_sanitize_request_guardrail(&mut self, name: &str, priority: i32, callback: ToolSanitizeFn) -> Result<()>#: Registers a tool sanitize-request guardrail and records its rollback closure.

fn register_tool_sanitize_response_guardrail(&mut self, name: &str, priority: i32, callback: ToolSanitizeFn) -> Result<()>#: Registers a tool sanitize-response guardrail and records its rollback closure.

fn with_namespace(namespace: impl Into<String>) -> Self#: Creates a plugin registration context that namespaces all registration names.

mod plugin#

`mod plugin`#