rustlavel_audit/lib.rs
1//! Audit logging: who did what, to which record, from where, and when.
2//!
3//! Different from the application log on purpose. A log line is for whoever is
4//! debugging; an audit entry is a record somebody may be asked about a year
5//! later — "who deleted that account?" — and it therefore lives in the
6//! database, beside the data it describes, rather than in a file that rotates.
7//!
8//! ```ignore
9//! App::new().plugin(Audit::new(db.clone()))
10//! // and in the registry the CLI generates:
11//! registry.extend(rustlavel_audit::migrations());
12//! ```
13//!
14//! Then, from anywhere with a request:
15//!
16//! ```ignore
17//! use rustlavel_audit::AuditExt;
18//!
19//! req.audit("users.deleted")
20//! .on("User", user.id)
21//! .describe(format!("{} deleted {}", actor, user.name))
22//! .with("email", Json::from(user.email.as_str()))
23//! .save()
24//! .await?;
25//! ```
26//!
27//! **What the builder does not let you do is forget the context.** The actor,
28//! the address and the user agent are read off the request rather than passed
29//! in, because an entry that says "someone updated the settings" answers
30//! nothing, and a caller in a hurry is exactly who writes that entry.
31
32pub mod entry;
33pub mod plugin;
34pub mod store;
35pub mod tables;
36
37pub use entry::{Builder, Entry};
38pub use plugin::{Audit, AuditExt};
39pub use store::{Filter, Page, Trail};
40pub use tables::{TABLE, migrations};
41
42/// What an application file usually needs from this package.
43///
44/// `Page`, `Entry`, `Builder` and `Filter` are deliberately not here: they are
45/// ordinary enough names that a glob import of several preludes would make one
46/// of them ambiguous — `rustlavel_db` already exports a `Page` — and a name
47/// that silently means something else is worse than one extra `use`. Spell
48/// them `rustlavel::audit::Page` when you need them.
49pub mod prelude {
50 pub use crate::plugin::{Audit, AuditExt};
51 pub use crate::store::Trail;
52}