Struct PluginViolation 

pub struct PluginViolation {
    pub code: String,
    pub reason: String,
    pub description: Option<String>,
    pub details: HashMap<String, Value>,
    pub plugin_name: Option<String>,
    pub proto_error_code: Option<i64>,
}

Structured policy violation returned by a plugin that denies execution.

Carries a machine-readable code, human-readable reason, and optional diagnostic details. Corresponds to the Python PluginViolation type.

Examples

use cpex_core::error::PluginViolation;

let v = PluginViolation::new("missing_permission", "User lacks pii_access");
assert_eq!(v.code, "missing_permission");
assert_eq!(v.reason, "User lacks pii_access");

Fields

code: String

Machine-readable violation identifier (e.g., "missing_permission").

reason: String

Short human-readable reason for the denial.

description: Option<String>

Optional detailed explanation.

details: HashMap<String, Value>

Structured diagnostic data for logging or debugging.

plugin_name: Option<String>

Name of the plugin that produced the violation. Set by the framework after the plugin returns, not by the plugin itself.

proto_error_code: Option<i64>

Protocol-level error code for the host to map to the wire format. MCP: JSON-RPC codes (e.g., -32603). HTTP: status codes (e.g., 403). Set by the plugin; the host interprets it.

Implementations

impl PluginViolation

pub fn new(code: impl Into<String>, reason: impl Into<String>) -> Self

Create a new violation with a code and reason.

Examples found in repository

examples/plugin_demo.rs (lines 87-90)

    async fn handle(
        &self,
        payload: &ToolInvokePayload,
        _extensions: &Extensions,
        _ctx: &mut PluginContext,
    ) -> PluginResult<ToolInvokePayload> {
        if payload.user.is_empty() {
            println!("  [identity-resolver] DENIED: no user identity");
            return PluginResult::deny(PluginViolation::new(
                "no_identity",
                "User identity is required",
            ));
        }
        println!(
            "  [identity-resolver] OK: user '{}' identified",
            payload.user
        );
        PluginResult::allow()
    }
}

impl HookHandler<ToolPostInvoke> for IdentityResolver {
    async fn handle(
        &self,
        payload: &ToolInvokePayload,
        _extensions: &Extensions,
        _ctx: &mut PluginContext,
    ) -> PluginResult<ToolInvokePayload> {
        println!(
            "  [identity-resolver] post-invoke: user '{}' completed '{}'",
            payload.user, payload.tool_name
        );
        PluginResult::allow()
    }
}

/// PII guard — blocks access to sensitive tools without clearance.
struct PiiGuard {
    cfg: PluginConfig,
}

#[async_trait]
impl Plugin for PiiGuard {
    fn config(&self) -> &PluginConfig {
        &self.cfg
    }
    // initialize() and shutdown() use defaults — no setup needed
}

impl HookHandler<ToolPreInvoke> for PiiGuard {
    async fn handle(
        &self,
        payload: &ToolInvokePayload,
        _extensions: &Extensions,
        ctx: &mut PluginContext,
    ) -> PluginResult<ToolInvokePayload> {
        // Check if the user has PII clearance (simulated via context)
        let has_clearance = ctx
            .get_global("pii_clearance")
            .and_then(|v| v.as_bool())
            .unwrap_or(false);

        if !has_clearance {
            println!(
                "  [pii-guard] DENIED: user '{}' lacks PII clearance for '{}'",
                payload.user, payload.tool_name
            );
            return PluginResult::deny(PluginViolation::new(
                "pii_access_denied",
                "PII clearance required",
            ));
        }

        println!(
            "  [pii-guard] OK: user '{}' has PII clearance",
            payload.user
        );
        PluginResult::allow()
    }
}

/// Audit logger — logs all tool invocations (fire-and-forget).
struct AuditLogger {
    cfg: PluginConfig,
}

#[async_trait]
impl Plugin for AuditLogger {
    fn config(&self) -> &PluginConfig {
        &self.cfg
    }
    // initialize() and shutdown() use defaults — no setup needed
}

impl HookHandler<ToolPreInvoke> for AuditLogger {
    async fn handle(
        &self,
        payload: &ToolInvokePayload,
        _extensions: &Extensions,
        _ctx: &mut PluginContext,
    ) -> PluginResult<ToolInvokePayload> {
        println!(
            "  [audit-logger] LOG: user='{}' tool='{}' args='{}'",
            payload.user, payload.tool_name, payload.arguments
        );
        PluginResult::allow()
    }
}

impl HookHandler<ToolPostInvoke> for AuditLogger {
    async fn handle(
        &self,
        payload: &ToolInvokePayload,
        _extensions: &Extensions,
        _ctx: &mut PluginContext,
    ) -> PluginResult<ToolInvokePayload> {
        println!(
            "  [audit-logger] LOG: post-invoke user='{}' tool='{}'",
            payload.user, payload.tool_name
        );
        PluginResult::allow()
    }
}

// ---------------------------------------------------------------------------
// Awaiting plugin example — RemoteAuthz
// ---------------------------------------------------------------------------
//
// `HookHandler<H>` is async by design — `handle` is `async fn`.
// Plugins that don't need to `.await` anything still write
// `async fn handle` and return synchronously; this plugin shows the
// other direction, where the body genuinely awaits per-invocation
// work. The realistic version would call a remote authz service
// (gRPC, HTTP, OPA, Cedarling, etc.); here we simulate the network
// round-trip with a small `tokio::time::sleep` so the demo runs
// offline.
//
// Key things this shows:
//   1. Per-request latency state is *cached at init* — the handler
//      consults the in-memory ACL and only "calls out" on a miss.
//      Hot-path I/O is the most common source of latency regressions
//      in plugins, so prefer initialize-time loading wherever you can.
//   2. Registration uses the exact same factory pattern as any other
//      plugin — `TypedHandlerAdapter::<H, _>` and the same
//      `register_factory` call. There is no separate async path.
struct RemoteAuthz {
    cfg: PluginConfig,
    /// ACL "fetched" at init. Populated in Plugin::initialize.
    allowed_users: tokio::sync::RwLock<std::collections::HashSet<String>>,
}

#[async_trait]
impl Plugin for RemoteAuthz {
    fn config(&self) -> &PluginConfig {
        &self.cfg
    }
    /// Pretend we're loading the ACL from a remote service. In a real
    /// plugin this would be `client.fetch_acl().await`; we simulate
    /// the round-trip with a small sleep so the demo runs offline.
    async fn initialize(&self) -> Result<(), Box<PluginError>> {
        tokio::time::sleep(std::time::Duration::from_millis(2)).await;
        let mut acl = self.allowed_users.write().await;
        acl.extend(["alice", "bob"].iter().map(|s| s.to_string()));
        println!(
            "  [remote-authz] initialized — ACL cached ({} users)",
            acl.len()
        );
        Ok(())
    }
    async fn shutdown(&self) -> Result<(), Box<PluginError>> {
        println!("  [remote-authz] shutdown");
        Ok(())
    }
}

impl HookHandler<ToolPreInvoke> for RemoteAuthz {
    async fn handle(
        &self,
        payload: &ToolInvokePayload,
        _extensions: &Extensions,
        _ctx: &mut PluginContext,
    ) -> PluginResult<ToolInvokePayload> {
        // Cache hit path — fast.
        let acl = self.allowed_users.read().await;
        if acl.contains(&payload.user) {
            println!(
                "  [remote-authz] OK (cache hit): user '{}' allowed",
                payload.user
            );
            return PluginResult::allow();
        }
        drop(acl); // release read lock before the fake remote call
                   // Cache miss path — simulate a remote authz check. In a real
                   // plugin this is where you'd `.await` a gRPC or HTTP call.
                   // The latency cost is real and shows up on the request path.
        tokio::time::sleep(std::time::Duration::from_millis(1)).await;
        println!(
            "  [remote-authz] DENIED (cache miss + remote check): user '{}'",
            payload.user
        );
        PluginResult::deny(PluginViolation::new(
            "remote_authz_denied",
            format!("User '{}' not in remote ACL", payload.user),
        ))
    }

examples/cmf_capabilities_demo.rs (lines 101-104)

    async fn handle(
        &self,
        payload: &MessagePayload,
        extensions: &Extensions,
        _ctx: &mut PluginContext,
    ) -> PluginResult<MessagePayload> {
        // Determine if this is pre or post invoke based on message content
        let is_result = payload.message.is_tool_result();

        if is_result {
            // POST-INVOKE: verify the tool result came from an authorized call
            let tool_name = payload
                .message
                .get_tool_results()
                .first()
                .map(|tr| tr.tool_name.as_str())
                .unwrap_or("unknown");
            println!(
                "  [identity-checker] POST-INVOKE: verifying result from '{}'",
                tool_name
            );

            if let Some(ref security) = extensions.security {
                if let Some(ref subject) = security.subject {
                    println!(
                        "  [identity-checker] Result authorized for subject: {:?}",
                        subject.id
                    );
                }
            }
            println!("  [identity-checker] POST-INVOKE ALLOWED");
        } else {
            // PRE-INVOKE: check caller identity and roles
            let tool_name = payload
                .message
                .get_tool_calls()
                .first()
                .map(|tc| tc.name.as_str())
                .unwrap_or("unknown");
            println!(
                "  [identity-checker] PRE-INVOKE: checking identity for '{}'",
                tool_name
            );

            if let Some(ref security) = extensions.security {
                let labels: Vec<&String> = security.labels.iter().collect();
                println!("  [identity-checker] Security labels: {:?}", labels);

                if let Some(ref subject) = security.subject {
                    println!(
                        "  [identity-checker] Subject: {:?}, Roles: {:?}",
                        subject.id,
                        subject.roles.iter().collect::<Vec<_>>()
                    );

                    if security.has_label("PII") && !subject.roles.contains("hr_admin") {
                        return PluginResult::deny(PluginViolation::new(
                            "insufficient_role",
                            format!("Tool '{}' requires 'hr_admin' role for PII data", tool_name),
                        ));
                    }
                }
            }

            if extensions.http.is_some() {
                println!("  [identity-checker] WARNING: HTTP visible (unexpected!)");
            } else {
                println!("  [identity-checker] HTTP: not visible (correct — no read_headers)");
            }
            println!("  [identity-checker] PRE-INVOKE ALLOWED");
        }

        PluginResult::allow()
    }

pub fn with_description(self, description: impl Into<String>) -> Self

Attach a detailed description.

pub fn with_details(self, details: HashMap<String, Value>) -> Self

Attach structured diagnostic details.

pub fn with_proto_error_code(self, code: i64) -> Self

Attach a protocol-level error code.

Trait Implementations

impl Clone for PluginViolation

fn clone(&self) -> PluginViolation

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PluginViolation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for PluginViolation

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for PluginViolation

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Serialize for PluginViolation

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.