treetop-client

A Rust client library for Treetop policy authorization servers.

Treetop is a Cedar-based policy evaluation service. This client provides a typed, async API for evaluating authorization requests, managing policies, and querying server status.

Compatibility

This version targets treetop-rest v0.0.7. CI verifies the stable health, version, policy, and authorization contract against v0.0.4, v0.0.5, v0.0.6, and v0.0.7; v0.0.7 receives the complete endpoint suite. Newer response fields use #[serde(default)] for backward compatibility.

Features

• Type-driven design -- strongly typed request/response types with serde, wire-compatible with the Treetop REST API
• Connection pooling -- built on reqwest with configurable pool sizes and idle timeouts
• Secure token handling -- upload tokens backed by SecretString (zeroized on drop, redacted in Debug output)
• Validated request boundaries -- private request fields, Cedar identifier checks, and validated IP/header newtypes
• TLS by default -- uses rustls (pure-Rust TLS, no OpenSSL dependency) with optional custom root certificates
• Bounded responses -- successful response bodies are capped at 16 MiB by default, with a configurable limit
• Builder patterns -- ergonomic builders for client configuration, authorization requests, users, resources, and actions
• Batch authorization -- evaluate multiple authorization requests in a single API call
• Correlation IDs -- clone-with-override pattern for request tracing without shared mutable state
• Schema management -- download and upload Cedar schema data alongside policies

Installation

Add to your Cargo.toml:

[dependencies]
treetop-client = "0.0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Quick start

use treetop_client::{
    Action, AuthorizeRequest, Client, Request, Resource, User,
};

#[tokio::main]
async fn main() -> treetop_client::Result<()> {
    // Create a client
    let client = Client::builder("https://treetop.example.com").build()?;

    // Check server health
    client.health().await?;

    // Simple authorization check
    let allowed = client
        .is_allowed(Request::new(
            User::new("alice"),
            Action::new("view"),
            Resource::new("Document", "doc-42"),
        ))
        .await?;

    println!("Allowed: {allowed}");
    Ok(())
}

Usage

Client configuration

use std::time::Duration;
use treetop_client::{Client, UploadToken};

let client = Client::builder("https://treetop.example.com")
    .connect_timeout(Duration::from_secs(5))
    .request_timeout(Duration::from_secs(30))
    .pool_idle_timeout(Duration::from_secs(90))
    .pool_max_idle_per_host(10)
    .max_response_bytes(16 * 1024 * 1024)
    .upload_token(UploadToken::new("my-secret-token"))
    .build()?;

Upload tokens require HTTPS unless the destination is loopback. For an explicitly accepted plaintext development server, opt in with .danger_allow_insecure_uploads(true). The default HTTP client also rejects redirects so a token cannot be forwarded to a redirect target. A custom reqwest client bypasses that redirect policy, so configure its policy deliberately.

For custom TLS configuration:

use treetop_client::Client;

let client = Client::builder("https://treetop.internal")
    .add_root_certificate(my_ca_cert)
    .build()?;

Or bring your own pre-configured reqwest client:

let client = Client::builder("https://treetop.example.com")
    .with_reqwest_client(my_reqwest_client)
    .build()?;

Correlation IDs

Correlation IDs are managed via a clone-with-override pattern. The cloned client shares the same connection pool:

let traced = client.with_correlation_id("req-abc-123")?;
traced.authorize(&request).await?;  // sends x-correlation-id header

// Original client is unaffected
client.authorize(&request).await?;  // no correlation header

Authorization

Request fields are private and exposed through read-only accessors. authorize() validates the complete batch before transport; try_new and try_with_* constructors are available when you want validation at construction time. AttrValue::ip() always validates its IP/CIDR value.

Single check

use treetop_client::{Action, Request, Resource, User};

let allowed = client
    .is_allowed(Request::new(
        User::new("alice").with_group_names(&["admins"]),
        Action::new("delete"),
        Resource::new("Host", "web-01"),
    ))
    .await?;

Batch authorization

use treetop_client::{Action, AttrValue, AuthorizeRequest, Request, Resource, User};

let batch = AuthorizeRequest::new()
    .add_request(Request::new(
        User::new("alice"),
        Action::new("view"),
        Resource::new("Document", "doc-1"),
    ))
    .add_request_with_id("check-2", Request::new(
        User::new("bob"),
        Action::new("edit"),
        Resource::new("Document", "doc-1")
            .with_attr("owner", AttrValue::String("alice".to_string())),
    ));

let response = client.authorize(&batch).await?;

println!("Successful: {}, Failed: {}", response.successes(), response.failures());

// Look up a result by client-provided ID
if let Some(result) = response.find_by_id("check-2") {
    println!("check-2 index: {}", result.index);
}

Detailed authorization (includes matching policies)

let response = client.authorize_detailed(&batch).await?;

Resources with attributes

use treetop_client::{AttrValue, Resource};

let resource = Resource::new("Host", "web-01.example.com")
    .with_attr("ip", AttrValue::ip("10.0.0.1")?)
    .with_attr("environment", AttrValue::String("production".to_string()))
    .with_attr("critical", AttrValue::Bool(true))
    .with_attr("priority", AttrValue::Long(1));

Namespaced types

Users, groups, and actions support Cedar namespaces:

use treetop_client::{Action, Group, User};

let user = User::new("alice")
    .with_namespace(vec!["MyApp".to_string()])
    .with_group_names(&["admins", "editors"]);

let action = Action::new("delete")
    .with_namespace(vec!["Admin".to_string()]);

let group = Group::new("superusers")
    .with_namespace(vec!["MyApp".to_string()]);

Policy management

// Download policies as structured data
let download = client.get_policies().await?;

// Download policies as raw Cedar DSL
let cedar_text = client.get_policies_raw().await?;

// Upload policies (requires upload token)
let metadata = client
    .upload_policies_raw("permit(principal, action, resource);")
    .await?;

// List policies for a specific user
let user_policies = client
    .get_user_policies("alice", &["admins".into()], &["MyApp".into()])
    .await?;

Schema management

// Download schema as structured metadata
let schema = client.get_schema().await?;

// Download schema as raw Cedar schema JSON
let raw_schema = client.get_schema_raw().await?;

// Upload schema (requires upload token)
let metadata = client
    .upload_schema_raw(r#"{"": {"entityTypes": {}, "actions": {}}}"#)
    .await?;

Server status

let version = client.version().await?;
println!("Server: {}, Cedar: {}", version.version, version.core.cedar);

let status = client.status().await?;
println!("Policies loaded: {}", status.policy_configuration.policies.entries);
println!("Context supported: {}", status.request_context.supported);

Request context

Request-scoped context is serialized on the wire via AuthRequest.context and evaluated by treetop-rest v0.0.7.

use std::collections::HashMap;
use treetop_client::{Action, AttrValue, AuthRequest, AuthorizeRequest, Request, Resource, User};

let mut context = HashMap::new();
context.insert("env".to_string(), AttrValue::String("prod".to_string()));

let request = AuthRequest::new(Request::new(
    User::new("alice"),
    Action::new("view"),
    Resource::new("Photo", "VacationPhoto94.jpg"),
))
    .with_context(context);
let batch = AuthorizeRequest::from_auth_requests([request]);

let response = client.authorize(&batch).await?;

Inspect status.request_context if you need to know whether the server runtime is currently schema-backed or running in permissive fallback mode. Uploading a schema via upload_schema_raw() or upload_schema_json() lets you verify the schema-backed path explicitly.

Prometheus metrics

let metrics_text = client.metrics().await?;

Error handling

All methods return treetop_client::Result<T>, which uses TreetopError:

use treetop_client::TreetopError;

match client.health().await {
    Ok(()) => println!("Server is healthy"),
    Err(TreetopError::Transport(e)) => println!("Network error: {e}"),
    Err(TreetopError::Api { status, message }) => {
        println!("Server returned HTTP {status}: {message}");
    }
    Err(e) => println!("Other error: {e}"),
}

License

MIT

Releasing

Stable tags drive the crates.io and GitHub release workflow. See RELEASING.md for the one-time v0.0.1 bootstrap and subsequent OIDC releases.