rustfs/crates/audit/AGENTS.md

Audit Crate Instructions

Applies to crates/audit/.

rustfs-audit is the domain layer for audit event fan-out and observability. It composes shared plugin/runtime abstractions from rustfs-targets and keeps audit-specific dispatch semantics, state transitions, and metrics in this crate.

Domain Boundaries

• Keep audit-specific behavior here:
  • audit event shaping and fan-out pipeline
  • audit system lifecycle/state transitions
  • audit metrics and reporting
• Keep shared plugin/runtime mechanics in rustfs-targets:
  • no duplicated replay worker orchestration
  • no duplicated runtime manager primitives
  • no plugin install/control-plane modeling in this crate

Runtime Layering Rules

• pipeline.rs hosts:
  • AuditPipeline (dispatch and snapshot access)
  • AuditRuntimeFacade (runtime mutation path)
  • AuditRuntimeView (runtime read path)
• registry.rs should remain the single owner of runtime target container and plugin registry composition for audit.
• system.rs should coordinate lifecycle by calling facade/view/registry boundaries rather than embedding low-level runtime logic.

Change Style

• Preserve audit delivery semantics and error handling behavior unless the task explicitly changes them.
• Prefer extending shared abstractions in rustfs-targets over patching one-off audit-only runtime flows.
• Keep logging and observability machine-meaningful; avoid noisy churn in hot dispatch paths.

Testing

• Keep unit tests close to changed modules.
• Keep pipeline-layer regressions in tests/pipeline_layer_test.rs.
• Add regression tests for:
  • runtime facade activation/replace/stop/shutdown behavior
  • runtime view target/snapshot access
  • system reload and runtime commit/clear boundaries
• Suggested validation:
  • cargo test -p rustfs-audit
  • Focused: cargo test -p rustfs-audit --test pipeline_layer_test
  • Focused: cargo test -p rustfs-audit pipeline
• Full gate before commit: make pre-commit