Rust SDK Reference

Complete API reference for the coresdk-engine crate. For installation and a working example, see the Rust Quickstart.

Cargo.toml

[dependencies]
coresdk-engine = "0.1"
tokio = { version = "1", features = ["full"] }

`Engine::from_env()`

Initialises the engine from CORESDK_* environment variables (or coresdk.toml).

use coresdk_engine::{Engine, EngineConfig};

let engine = Engine::from_env()?;

To construct with explicit config:

let engine = Engine::new(EngineConfig {
    sidecar_addr: "[::1]:50051".to_string(),
    tenant_id: "acme-corp".to_string(),
    service_name: "my-api".to_string(),
    fail_mode: coresdk_engine::FailMode::Open,
    ..Default::default()
})?;

`engine.auth().authorize()`

Validates a JWT bearer token and returns an AuthDecision.

let decision = engine.auth().authorize(&token).await?;

if !decision.allowed {
    return ProblemDetail::unauthorized(decision.reason.as_deref().unwrap_or("Unauthorized"))
        .into_response();
}

let user = decision.user; // VerifiedUser

VerifiedUser fields:

Field	Type	Description
`subject`	`String`	JWT `sub` claim
`tenant_id`	`String`	Tenant the user belongs to
`claims`	`HashMap<String, Value>`	Full decoded JWT claims

`engine.policy().evaluate()`

Evaluates a Rego rule directly via the engine pool (one engine per blocking thread, never a single Mutex).

Signature

pub async fn evaluate(
    &self,
    rule: &str,
    input: serde_json::Value,
) -> Result<bool, EngineError>

Usage

use serde_json::json;

let allowed = engine.policy().evaluate(
    "data.authz.allow",
    json!({
        "user": { "role": "member", "tenant_id": "acme" },
        "action": "orders:read",
        "resource": { "tenant": "acme" },
    }),
).await?;

if !allowed {
    return ProblemDetail::forbidden("Policy denied").into_response();
}

`ProblemDetail` helpers

Convert RFC 9457 errors into Axum responses:

use coresdk_engine::ProblemDetail;

// 401 Unauthorized
ProblemDetail::unauthorized("Missing bearer token").into_response()

// 403 Forbidden
ProblemDetail::forbidden("Policy denied action 'orders:write'").into_response()

// 500 Internal Server Error
ProblemDetail::internal_error("Unexpected failure").into_response()

ProblemDetail implements IntoResponse (axum) and serialises to application/problem+json per RFC 9457.

Error types

All engine operations return Result<T, EngineError>.

use coresdk_engine::EngineError;

match result {
    Err(EngineError::TokenExpired { expired_at }) => { /* ... */ }
    Err(EngineError::TokenInvalid { reason }) => { /* ... */ }
    Err(EngineError::PolicyDenied { rule, reason }) => { /* ... */ }
    Err(EngineError::SidecarUnreachable) => { /* fail_mode applies */ }
    Err(e) => { /* catch-all for future variants */ }
}

Variant	Fields	Description
`TokenExpired`	`expired_at: DateTime<Utc>`	JWT `exp` claim is in the past
`TokenInvalid`	`reason: String`	Signature mismatch, malformed token, or missing claims
`PolicyDenied`	`rule: String`, `reason: Option<String>`	Rego rule evaluated to `false`
`SidecarUnreachable`	—	Could not connect to `CORESDK_SIDECAR_ADDR`; `fail_mode` determines behaviour
`Configuration`	`message: String`	Missing required env var or invalid value

Rust SDK Reference

Rust SDK Reference

Engine::from_env()

engine.auth().authorize()

engine.policy().evaluate()

ProblemDetail helpers

Error types

On this page

`Engine::from_env()`

`engine.auth().authorize()`

`engine.policy().evaluate()`

`ProblemDetail` helpers