Module external 

External guard adapter infrastructure.

The building blocks in this module let you wrap a synchronous external API (cloud guardrails, threat intel feeds, ML classifiers) as an async Chio guard without leaking I/O concerns into the sync chio_kernel::Guard trait.

The pieces are:

• ExternalGuard – the async trait a concrete external adapter implements. It describes the one operation we actually want to make resilient: eval(ctx) -> Result<Verdict, _>.
• AsyncGuardAdapter – composes a circuit_breaker::CircuitBreaker, token_bucket::TokenBucket, cache::TtlCache, and retry_with_jitter around an ExternalGuard.
• CircuitOpenVerdict – what the adapter returns when the breaker is open. Default is CircuitOpenVerdict::Deny (fail-closed).
• RateLimitedVerdict – what the adapter returns when the rate limiter rejects a call. Default is RateLimitedVerdict::Deny (fail-closed, per the phase-13.1 acceptance criteria).

Example

use std::sync::Arc;
use std::time::Duration;
use async_trait::async_trait;
use chio_guards::external::{
    AsyncGuardAdapter, ExternalGuard, ExternalGuardError, GuardCallContext,
};
use chio_kernel::Verdict;

struct HelloGuard;

#[async_trait]
impl ExternalGuard for HelloGuard {
    fn name(&self) -> &str { "hello" }
    fn cache_key(&self, ctx: &GuardCallContext) -> Option<String> {
        Some(ctx.tool_name.clone())
    }
    async fn eval(&self, _ctx: &GuardCallContext) -> Result<Verdict, ExternalGuardError> {
        Ok(Verdict::Allow)
    }
}

let adapter = AsyncGuardAdapter::builder(Arc::new(HelloGuard))
    .cache_ttl(Duration::from_secs(30))
    .build();

Re-exports

pub use cache::Clock;

pub use cache::TokioClock;

pub use cache::TtlCache;

pub use circuit_breaker::CircuitBreaker;

pub use circuit_breaker::CircuitBreakerConfig;

pub use circuit_breaker::CircuitState;

pub use retry::retry_with_jitter;

pub use retry::retry_with_jitter_rng;

pub use retry::BackoffStrategy;

pub use retry::RetryConfig;

pub use token_bucket::TokenBucket;

Modules

cache

TTL cache with LRU eviction for external guard verdicts.

circuit_breaker

Three-state circuit breaker for external service calls.

retry

Retry with deterministic jitter for transient external failures.

token_bucket

Simple token bucket rate limiter for the external guard adapter.

Structs

AsyncGuardAdapter

Adapter that composes circuit breaker + token bucket + TTL cache + retry on top of an ExternalGuard.

AsyncGuardAdapterBuilder

Fluent builder for AsyncGuardAdapter.

AsyncGuardAdapterConfig

Configuration for AsyncGuardAdapter. Built via AsyncGuardAdapter::builder.

GuardCallContext

Subset of guard-request information passed to an ExternalGuard.

Enums

CircuitOpenVerdict

Verdict returned when the circuit breaker is open.

ExternalGuardError

Errors surfaced from an ExternalGuard call.

RateLimitedVerdict

Verdict returned when the token bucket rejects a call.

Traits

ExternalGuard

Trait implemented by guards that call external services.