Struct EvalTrace 

pub struct EvalTrace { /* private fields */ }

A tree of PolicyEvalResult nodes capturing every policy decision made during an access evaluation.

Returned as part of AccessEvaluation. Use EvalTrace::format to render a human-readable tree, useful for debugging and audit logging.

The tree records policy decisions. The inputs that informed a decision — the facts a fact-backed policy consulted — are attached to the individual PolicyEvalResult nodes as FactProvenance and rendered inline by EvalTrace::format. Operational fact-load telemetry (latency, batch fan-out, cache hits) is a separate concern surfaced through tracing spans (gatehouse.fact_load), not through this tree.

Example

// An empty trace produces a fallback message:
let empty = EvalTrace::new();
assert_eq!(empty.format(), "No evaluation trace available");

// A trace built from a policy result renders a decision tree:
let trace = EvalTrace::with_root(PolicyEvalResult::granted(
    "AdminPolicy",
    Some("User is admin".into()),
));
assert!(trace.format().contains("AdminPolicy GRANTED"));

Implementations

impl EvalTrace

pub fn new() -> Self

Creates an empty trace with no evaluation results.

pub fn with_root(result: PolicyEvalResult) -> Self

Creates a trace with the given PolicyEvalResult as the root node.

pub fn set_root(&mut self, result: PolicyEvalResult)

Sets (or replaces) the root node of the evaluation tree.

pub fn root(&self) -> Option<&PolicyEvalResult>

Returns a reference to the root PolicyEvalResult, if present.

pub fn format(&self) -> String

Returns a formatted, indented representation of the evaluation tree.

Each node shows a ✔ or ✘ prefix, the policy name, and the reason. Combined nodes indent their children for readability.

Examples found in repository

examples/mfa_freshness_context.rs (line 246)

fn report(label: &str, eval: &AccessEvaluation) {
    println!("{label} → {}\n{}", verdict(eval), eval.trace().format());
}

examples/actix_web.rs (line 401)

fn forbidden(reason: &str, trace: &EvalTrace) -> HttpResponse {
    HttpResponse::Forbidden().body(format!("Denied: {}\n{}", reason, trace.format()))
}

examples/combinator_policy.rs (line 121)

async fn main() {
    let user = User::new();
    let document = Document::new();
    let action = ViewAction;
    let context = ();
    // These policies have no fact sources, so each evaluation binds
    // `EvaluationSession::empty()`. The checker contributes its own `OR` root
    // to the trace; the combinator's short-circuit behaviour (what this example
    // measures) happens inside it regardless.

    println!("=== AND Policy Short-Circuit Example ===");
    {
        let counter = Arc::new(AtomicUsize::new(0));

        // Create an AND policy with a non-grant policy first
        let and_policy = CountingPolicy {
            allow: false,
            name: "DenyFirst".to_string(),
            counter: counter.clone(),
        }
        .and(CountingPolicy {
            allow: true,
            name: "AllowSecond".to_string(),
            counter: counter.clone(),
        });

        let mut checker = PermissionChecker::<DocumentDomain>::new();
        checker.add_policy(and_policy);

        println!("Evaluating AND(DenyFirst, AllowSecond):");
        let session = EvaluationSession::empty();
        let result = checker
            .bind(&session, &user, &action, &context)
            .check(&document)
            .await;
        println!(
            "Result: {}",
            if result.is_granted() {
                "Access granted"
            } else {
                "Access denied"
            }
        );
        println!("Policies evaluated: {}", counter.load(Ordering::SeqCst));
        println!("Trace:\n{}", result.trace().format());

        // The second policy should not be evaluated due to short-circuiting
        assert_eq!(counter.load(Ordering::SeqCst), 1);
    }

    println!("\n=== OR Policy Short-Circuit Example ===");
    {
        let counter = Arc::new(AtomicUsize::new(0));

        // Create an OR policy with an allow policy first
        let or_policy = CountingPolicy {
            allow: true,
            name: "AllowFirst".to_string(),
            counter: counter.clone(),
        }
        .or(CountingPolicy {
            allow: false,
            name: "DenySecond".to_string(),
            counter: counter.clone(),
        });

        let mut checker = PermissionChecker::<DocumentDomain>::new();
        checker.add_policy(or_policy);

        println!("Evaluating OR(AllowFirst, DenySecond):");
        let session = EvaluationSession::empty();
        let result = checker
            .bind(&session, &user, &action, &context)
            .check(&document)
            .await;
        println!(
            "Result: {}",
            if result.is_granted() {
                "Access granted"
            } else {
                "Access denied"
            }
        );
        println!("Policies evaluated: {}", counter.load(Ordering::SeqCst));
        println!("Trace:\n{}", result.trace().format());

        // The second policy should not be evaluated due to short-circuiting
        assert_eq!(counter.load(Ordering::SeqCst), 1);
    }

    println!("\n=== Complex Nested Policy Example ===");
    {
        let counter = Arc::new(AtomicUsize::new(0));

        // Create a complex nested policy: OR(AND(Deny, Allow), Allow)
        let inner_and = CountingPolicy {
            allow: false,
            name: "DenyInner".to_string(),
            counter: counter.clone(),
        }
        .and(CountingPolicy {
            allow: true,
            name: "AllowInner".to_string(),
            counter: counter.clone(),
        });

        let complex_policy = inner_and.or(CountingPolicy {
            allow: true,
            name: "AllowOuter".to_string(),
            counter: counter.clone(),
        });

        let mut checker = PermissionChecker::<DocumentDomain>::new();
        checker.add_policy(complex_policy);

        println!("Evaluating OR(AND(DenyInner, AllowInner), AllowOuter):");
        let session = EvaluationSession::empty();
        let result = checker
            .bind(&session, &user, &action, &context)
            .check(&document)
            .await;
        println!(
            "Result: {} for document with ID {} for user with ID {}",
            if result.is_granted() {
                "Access granted"
            } else {
                "Access denied"
            },
            document.id,
            user.id
        );
        println!("Policies evaluated: {}", counter.load(Ordering::SeqCst));
        println!("Trace:\n{}", result.trace().format());

        // The inner AND should evaluate only DenyInner (shorts-circuit),
        // then the OR continues to AllowOuter which grants access
        assert_eq!(counter.load(Ordering::SeqCst), 2);
    }
}

Trait Implementations

impl Clone for EvalTrace

fn clone(&self) -> EvalTrace

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for EvalTrace

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

Formats the value using the given formatter.

impl Default for EvalTrace

fn default() -> EvalTrace

Returns the “default value” for a type.

impl Serialize for EvalTrace

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

where __S: Serializer,

Serialize this value into the given Serde serializer.