README
¶
Audit module
modules/audit is the audit trail: it records every event the composed
modules emit and keeps the records for a configured period. The manifest
declares module.SubscribeAll, so a module that emits an event is audited by
having emitted it, wherever it sits in the composition. audit:read guards
/api/v1/audit/events and the admin entry at /admin/audit/events; the
retention job removes expired rows tenant by tenant.
Compose it in apps/platformkit/modules.go
with audit.Deps{Tenants, RetentionDays}; config.example.yaml's
audit.retention_days supplies the period, zero means a year, and Feature
optionally puts the trail behind a plan feature. Consumers import
contracts/ for the record, events and permission, never
internal/. make test TEST_PACKAGES=./modules/audit/... needs the
development database.
Documentation
¶
Overview ¶
Package audit is the module manifest: what the kernel needs to know about the audit trail that it cannot learn from a function call.
What it does is subscribe to everything, and the manifest says so with one field: module.SubscribeAll. The kernel expands it into one subscription per declared event once every manifest is in hand, so a module that emits an event is audited by having emitted it — wherever it sits in the composition, and with nothing registered anywhere to make that true.
main used to compute the list and pass it in, which worked only while audit was composed last. A module listed after it was a module nothing recorded, and the failure was silence.
It declares no events of its own. An audit of audits is a loop.
What a payload may carry ¶
The trail stores every payload as its module published it, verbatim, and that is the design: what happened is the event's name and the module's own account of it, and a schema that tried to normalise those would be a schema every new module had to be taught. The price is a convention, and it is stated here because this is the module that pays it — an event carries identifiers, not content.
It is a convention rather than a check, because nothing can read a payload and tell a title from a secret. What it is now is a convention with one enforced case: notification.email_requested used to carry the whole message, address and body and link, which put every notice in the audit trail and would have put every set-password link there the day one was mailed. It carries two identifiers now, and the worker reads the row back. A payload that carries content is a payload kept for a year in a table an administrator can read.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Migrations = db.MigrationSource{ Owner: "audit", Files: db.Sub(schema, "migrations"), Adopts: []db.Adoption{{Owner: "platformkit", Versions: []int64{10, 15, 23}}}, }
Migrations is this module's SQL as one source — the audit trail and its record index — owned as "audit". The manifest hands the kernel the same files and adoption, and a test composes the schema it needs beside the foundation: dbtest.Schema(t, audit.Migrations).
The files keep the version numbers they had when the foundation applied them under its own name, so an installation migrated before this module owned its SQL is adopted by checksum rather than migrated again (see db.Adoption and docs/adr/0011). New files continue from the highest number.
Functions ¶
Types ¶
type Deps ¶
type Deps struct {
// Tenants is how the retention sweep reaches every tenant.
Tenants jobs.TenantLister
// RetentionDays is how long a row is kept; zero means a year. It is a
// dependency rather than a constant because a retention period is a
// compliance obligation, and a module that chose one would be choosing
// somebody else's. config.Audit is where it comes from.
RetentionDays int
// Feature is the plan feature the trail belongs to, or empty when this
// installation gives it to everybody. It is a dependency and not a constant
// for the same reason RetentionDays is: which features a product sells is
// the composition's decision, and a module that chose one would be pricing
// somebody else's product. See httpx.Auth.Needing.
Feature string
}
Deps is what this module cannot make for itself.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package contracts is everything another module, an app or a test may know about the audit trail: the row, the query, the permission and the Service interface.
|
Package contracts is everything another module, an app or a test may know about the audit trail: the row, the query, the permission and the Service interface. |
|
audittest
Package audittest is the conformance suite for contracts.Service, and a fake that passes it.
|
Package audittest is the conformance suite for contracts.Service, and a fake that passes it. |
|
Package internal is every implementation of the audit module.
|
Package internal is every implementation of the audit module. |