Crate ferro_audit 

ferro-audit

Append-only structured before/after audit log for the Ferro framework.

Audit entries record what happened — for forensic investigation, regulatory evidence, and state replay. They are the historical twin of [ferro-events]: events are “something happened, react now”; audit entries are “something happened, here is the evidence forever”.

Example

use ferro_audit::{AuditEntry, AuditActor, AuditTarget};
use serde_json::json;

AuditEntry::record("inventory.stock.adjust")
    .actor(AuditActor::User(user_id.to_string()))
    .target(AuditTarget::new("inventory.unit", unit_id.to_string()))
    .before(json!({ "quantity": old }))
    .after(json!({ "quantity": new }))
    .reason("order_committed")
    .write(&conn)
    .await?;

Replay

AuditEntry::history_for_target(&target, &conn).await? returns the sequence of entries ordered ascending by created_at. Passing that sequence to reconstruct_state folds each entry’s after JSON into a running object — the replay primitive.

The fold is a shallow object merge: newer keys overwrite older keys at the top level only. Nested objects and arrays are replaced wholesale, not deep-merged. A consumer needing deep-merge runs its own fold over the Vec<AuditEntry>.

Schema and Migration

ferro-audit ships a SeaORM migration as CreateAuditLogTable. Register it in your consumer-side Migrator:

impl MigratorTrait for Migrator {
    fn migrations() -> Vec<Box<dyn MigrationTrait>> {
        vec![
            Box::new(ferro_audit::CreateAuditLogTable),
            // ... your app migrations
        ]
    }
}

Structs

AuditLogEntity

Generated by sea-orm-macros

AuditTarget

CreateAuditLogTable

Enums

AuditActor

AuditError

Functions

history_for_target

Return every audit entry for target, ordered ascending by created_at.

prune_older_than

Delete all audit entries strictly older than cutoff. Returns the number of rows deleted.

recent

Return the limit most recent audit entries globally, ordered descending by created_at. Useful for an admin “recent activity” panel.

recent_by_actor

Return the limit most recent audit entries for actor, ordered descending by created_at.

reconstruct_state

Fold the after payloads of an audit entry sequence into a single reconstructed state value. See module-level docs for shallow-merge semantics.

Type Aliases

AuditEntry

One persisted row of the audit_log table.