Skip to main content

Crate dogwood_local_engine

Crate dogwood_local_engine 

Source
Expand description

§Dogwood Local Engine

A durable, incremental temporal engine for Dogwood policies. The engine observes a stream of events, decides each request against the events that came before it, and stores its state on disk so that after a restart it resumes with the history it had already seen.

A Dogwood policy can refer to past actions and their outcomes: permit a read only if the same user logged in within the last hour, permit a push only if the tests passed and none have failed since. Deciding such a policy means accounting for every event, ordering concurrent submissions, and keeping the history across crashes. This crate provides an engine that does so and that is built to be embedded as a library in the harness that mediates the agent’s tool calls. Policies are parsed and type-checked by the dogwood-language crate, whose interpreter defines the language’s semantics. This crate implements that crate’s TemporalEngine trait, so the two work together and agree on every verdict.

§Install

To use the engine, add it and the language crate to a project:

[dependencies]
dogwood-local-engine = "1.1"
dogwood-language = "1.1"

The language crate is needed alongside the engine because it defines the policy and schema types and the Event type that the engine consumes.

§Getting started

This section walks through one complete use of the engine: a policy, the schema it is written against, the events of a short session and the verdicts the engine returns for them, and the Rust program that opens a store, installs the policy, and submits those events. It then shows that a restart keeps the history. The example is read_after_login from the Dogwood language repository: permit a Read only if the same user logged in within the last hour.

§The policy

@id("allow_login")
permit (principal, action == Drupe::Action::"Login", resource);

@id("read_after_login")
permit (
    principal,
    action == Drupe::Action::"Read",
    resource
)
when temporal {
    formerly within 1h Drupe::Action::"Login"::response{ input.user: context.input.user }
};

The when temporal clause is evaluated against the event history. It holds when a Login response occurred in the last hour whose input.user equals the input.user of the current request. That correlation is what makes the policy say “the same user” rather than “anyone”.

§The schema

The policy and the events share a vocabulary, declared in a schema. For each action the schema names the principals that can take it, the resources it acts on, and the fields of its request input.

namespace Drupe {
  type LoginInput = { user: String };
  type ReadInput = { user: String };
  entity Gateway;
  entity OAuthUser = { id: String } tags String;
  action "Login" appliesTo {
    principal: [OAuthUser],
    resource: [Gateway],
    context: { input: LoginInput }
  };
  action "Read" appliesTo {
    principal: [OAuthUser],
    resource: [Gateway],
    context: { input: ReadInput }
  };
}

§The events

An event is a record of one step of a tool call. A call produces a request event when it is made and a response event when it returns. The engine issues a verdict for every request event; response events are recorded as history and get no verdict. Here is one session of four events, with the verdict the engine returns for each request:

@0     Login::request   { user: "alice" }   -> ALLOW   // allow_login
@5     Login::response  { user: "alice" }
@10    Read::request    { user: "alice" }   -> ALLOW   // logged in 5s ago
@7200  Read::request    { user: "alice" }   -> DENY    // login is 2h old

At @0 alice logs in; allow_login permits the request. At @5 the login returns and the engine records the response. At @10 alice reads. A Login response for the same user is five seconds behind the request, well inside the hour, so the read is allowed. At @7200 alice reads again. The only login is two hours old, the window has passed, and the read is denied.

§Open, install, submit

The following program opens a store, installs the policy, and submits the first three events.

use dogwood_language::{Event, EventBuilder, Value};
use dogwood_local_engine::{DurableError, DurableTemporalEngine, Outcome};

const POLICY: &str = r#"
@id("allow_login")
permit (principal, action == Drupe::Action::"Login", resource);

@id("read_after_login")
permit (principal, action == Drupe::Action::"Read", resource)
when temporal {
    formerly within 1h Drupe::Action::"Login"::response{ input.user: context.input.user }
};
"#;

const SCHEMA: &str = r#"
namespace Drupe {
  type LoginInput = { user: String };
  type ReadInput = { user: String };
  entity Gateway;
  entity OAuthUser = { id: String } tags String;
  action "Login" appliesTo {
    principal: [OAuthUser], resource: [Gateway], context: { input: LoginInput }
  };
  action "Read" appliesTo {
    principal: [OAuthUser], resource: [Gateway], context: { input: ReadInput }
  };
}
"#;

/// One of alice's events. The engine assigns the timestamp, so the
/// builder carries none. `field` sets the logged `input.user` that the
/// event pattern in the policy matches; `request_context` sets the
/// `context.input.user` the policy compares it against.
fn alice(action: &str, kind: &str) -> EventBuilder {
    Event::builder(action, kind)
        .principal("Drupe::OAuthUser::\"alice\"")
        .resource("Drupe::Gateway::\"gw1\"")
        .field("input", "user", Value::String("alice".to_string()))
        .request_context("input", "user", Value::String("alice".to_string()))
}

// Open the store at `path`, creating it if absent. Snapshot the monitor
// state every 1000 events.
let mut engine = DurableTemporalEngine::open(&path, 1000)?;

// Install the policy set against its schema. The event schema and macro
// library are left at their defaults.
engine.install(POLICY, SCHEMA, None, None)?;

// alice logs in. The request is a decision point; the response is history.
engine.submit(alice("Drupe::Action::Login", "request"))?;
engine.submit(alice("Drupe::Action::Login", "response"))?;

// alice reads within the hour.
let read = engine.submit(alice("Drupe::Action::Read", "request"))?;
match read.outcome {
    Outcome::Decision(verdict) => assert!(verdict.allowed()),
    Outcome::Recorded => unreachable!("a request event always gets a verdict"),
}

A few things to know about submit:

  • The engine assigns the event’s timestamp when it appends the event to its log. Callers never supply one. The assigned time is returned in Submitted::ts, in nanoseconds since the Unix epoch, and it is the instant every window is measured against.
  • A request event returns Outcome::Decision carrying the verdict. A response event returns Outcome::Recorded.
  • submit takes &mut self. To share one engine between threads, put it behind a mutex; the engine orders submissions in the order it receives them.
  • The second argument to open is the snapshot interval: how many events the engine appends between snapshots of its monitor state. 0 disables periodic snapshots and leaves checkpoints to the caller.

§Restart and recover

Opening the same path again recovers the installed policy set and the monitor state. The login is still in the window, so the next read is still allowed.

let mut engine = DurableTemporalEngine::open(path, 1000)?;
assert!(engine.has_policy());

§How the engine processes an event

Each submit takes three steps: linearize, persist, evaluate.

The engine supports concurrent submissions and linearizes them through a lock, admitting one at a time. Under that lock it stamps the event with the current time, clamped to stay strictly after the previous event even if the system clock steps back, and appends it to its log. The append position fixes the event’s place in the history. The engine syncs the append to disk before it evaluates anything, so an event that has a verdict is an event the log holds. Then, still under the lock, it evaluates the policies whose scope covers the request and returns the verdict.

Evaluation is incremental. Each temporal condition keeps only the history inside its own window, updated as events arrive, rather than rescanning the log on every request. State stays bounded for bounded windows.

On restart the engine loads its latest snapshot and replays the log records after it. Events older than the snapshot are pruned. An acknowledged submit is never lost to a crash; a store the engine cannot recover is refused rather than opened with part of its history.

§Policy updates

The policy set can change while the engine is running. install replaces the whole set from source; batch applies a list of Verbs (such as add, update, delete, and set the action schema) as one change and returns a PolicyToken for each policy it adds; list and get_policy read the set back.

A newly added policy starts with an empty history. It judges the requests after its installation and sees only the events after it, because the engine prunes events once a snapshot has captured what the current policies need, and a later policy may ask about information nothing recorded. A policy left unchanged by an update keeps the history it had accumulated.

A policy update is a record in the same log as the events. It takes its place in the order under the same lock and is synced in one transaction, so every request behind it sees the whole updated set and none sees a mixture of old and new. On recovery the engine replays updates in log order with the events. A change that fails to parse, lower, or validate writes nothing.

§What the embedding application must still do

The engine issues verdicts. It does not enforce them, and it cannot check that the events it is shown are true. The component that embeds it, the harness that mediates tool calls, is responsible for:

  • submitting every event the policies depend on;
  • authenticating where each event came from and that its fields are accurate;
  • running an action only when the verdict is allow;
  • restricting access to the store files and to the engine’s memory;
  • controlling who may change the policy set, and reporting a failed change;
  • keeping its own audit log, since the engine’s log is pruned;
  • protecting the host clock the engine reads.

The repository README explains each of these in detail.

§Where next

  • The Dogwood guide: the language, temporal expressions, and the CLI for validating and replaying policies before installing them.
  • dogwood-server, in the same repository, is a reference demo that puts the engine behind Unix sockets with a separate control plane for policy changes.

§License

Apache-2.0. See LICENSE and NOTICE.

Re-exports§

pub use log::DurableLog;
pub use log::LogError;
pub use log::Pruned;
pub use log::Snapshot;
pub use log::Write;

Modules§

log
The durable event log — a redb-backed, append-only, ordered store of opaque records.

Structs§

Applied
What an install or batch changed, for the operator’s benefit.
BatchResult
What a batch did.
DecisionDiagnostics
Determining policies and the authorizer’s evaluation errors.
DecisionResponse
The complete result of a durable-engine authorization decision.
DurableConfig
How to open a DurableTemporalEngine: the snapshot cadence and the clock.
DurableTemporalEngine
The durable engine: a policy set, an event log, and the running monitor, opened at a path. See the crate documentation for a walkthrough.
Installed
The installed policy bundle — everything needed to rebuild the authorizer.
LeafState
One leaf’s accumulated monitor state, shared rather than copied.
LocalTemporalEngine
A single-machine TemporalEngine: evaluates each temporal leaf at the current decision timepoint.
PolicyAttribution
One determining policy’s durable handle and annotations.
PolicyEntry
One installed policy: its opaque external handle (token), its internal ordinal (id — ordering + transplant key), its canonical statement (the rendered source, so a semantics-preserving reformat does not churn it), and the store-assigned create/update timestamps.
PolicyId
The internal ordinal: a monotonic, never-reused sequence number the engine assigns each policy in creation order. It is the ordering and transplant key — the composite (id, clause-index) retention key rests on it, and it is unique by construction (the cursor only advances, even across delete/DeleteAll), so a new policy can never inherit a deleted one’s monitor window. It is not the caller-facing handle (that is PolicyToken); it never leaves the engine except inside durable records.
PolicySet
The set of installed policies, keyed by stable id, plus the id-minting cursor.
PolicyToken
The external handle: an opaque, non-sequential token the engine mints on Add (SP + base62 of 128 random bits) and durably records so recovery re-uses it and never re-mints. This is what callers see in minted/list/get and name in Update/Delete/Reset.
SnapshotPayload
What the engine stores in a snapshot: the derived monitor state, and the policy set it was derived under.
Status
A projection of the running policy set, for status.
Submitted
An accepted DurableTemporalEngine::submit: where the event landed, and what — if anything — the caller is owed beyond that.
TickRate
The resolution of the timestamps an engine will be fed: how many ticks make up one second.
WallClock
The system clock: SystemTime::now() as epoch nanoseconds. The default, and the only clock a production deployment uses.

Enums§

BatchError
Why a batch was rejected. A batch is all-or-nothing: on any error the current set is left untouched.
Durability
When submit makes an event durable. Set with set_durability.
DurableError
A failure serving a request.
LeafStateTransferError
A leaf-state transfer cannot be performed without risking lost or incorrectly associated monitor history.
Outcome
The half of Submitted that depends on the event’s kind.
Record
One record in the durable log: an ingested event, or one policy-management verb. Every variant carries the store-assigned timestamp, its position in the one order events and policy changes share.
ShardPlan
How to partition the event stream, derived from the installed schema.
Verb
A policy-changing verb. The Add here is the control-plane form with no id — the engine mints one during the fold. Read operations (list, get_policy, action_schema) are not here: they take no durable record.

Traits§

Clock
A source of the current instant, in epoch nanoseconds.

Functions§

event_from_json
Rebuild an Event from event_to_json’s output and the timestamp its envelope carried.
event_to_json
An Event’s content as JSON, without the log envelope around it.
leaf_key
The content-derived identity of a temporal leaf: a canonical, span-free rendering of its condition. Equal keys ⇒ the same formula ⇒ state may be carried across a recompile.