work-with-audit

name	work-with-audit
description	Work on HFS audit logging. Use for FHIR AuditEvent, IHE BALP profiles, audit sinks (database/file/CloudWatch), path exclusions, and HFS_AUDIT_* configuration.

Audit Logging

Use this when working in helios-audit. The crate emits FHIR AuditEvent records (IHE BALP profiles) for HFS interactions. It is consumed by helios-rest, helios-hfs, and helios-persistence; middleware records request/response activity and writes to a configured sink.

Behavior

• Off by default (HFS_AUDIT_BACKEND=none). Choose a backend to enable auditing.
• BALP AuditEvents use the R4-family AuditEvent model. R5/R6 builds alias to R4B as the BALP baseline (R5/R6 restructured AuditEvent).
• Paths can be excluded (e.g. /health, /metadata) via HFS_AUDIT_EXCLUDE_PATHS.
• AuditEvent.source.observer defaults to Device/hfs (HFS_AUDIT_SOURCE_OBSERVER).

Persistence-layer operation events

Beyond the request/response events the middleware records, three long-running or destructive operations emit their own lifecycle events through helpers in helios-persistence (core::bulk_export::audit::record_export_event, core::storage::audit::record_purge_event, search::reindex::audit::record_reindex_event). Every event carries an audit-operation detail naming the operation:

audit-operation	Emitted at	Outcome codes	Other details
bulk-export	REST kick-off, and the worker's terminal transition (complete / cancel / fail)	0 / 4 / 8	bulk-export-operation (the phase), job-id, export-level, resource-types
purge	handler, on success and on failure	0 / 8	count, resource-type
reindex	job start, and its terminal state (complete / cancel / fail)	0 / 4 / 8	phase, job-id, resources-processed, resource-types

Note the phase detail is keyed bulk-export-operation for export but phase for reindex — the former predates the shared helper and is kept for consumers already parsing it.

Two things to know when touching these:

• helios-audit is a required (non-optional) dependency of helios-persistence. It used to sit behind an audit cargo feature, which made the shared helpers unreachable from helios-rest — so REST hand-rolled a duplicate export-event emitter, and the coverage CI job (which does not enable the feature) built a different crate than CI did.
• The test double for asserting on emitted events is a CollectorSink defined in test code (crates/rest/tests/persistence_operations.rs, and inline in the persistence unit tests). Do not add an in-memory sink to sinks/: CI builds --all-features --release, so a feature-gated test sink ships in the release binary.

Backends (HFS_AUDIT_BACKEND)

Value	Sink
none (default)	disabled (NullSink)
file	NDJSON to HFS_AUDIT_FILE_PATH
database / db	DatabaseSink — HFS_AUDIT_DATABASE_URL (SQL); MongoDB via HFS_AUDIT_MONGODB_DATABASE
cloudwatch / cloudwatch-logs / cwl	CloudWatch Logs — requires --features cloudwatch

Environment

Variable	Default	Description
HFS_AUDIT_BACKEND	none	Sink selection (see table)
HFS_AUDIT_FILE_PATH	none	File sink output path
HFS_AUDIT_DATABASE_URL	none	Database sink connection
HFS_AUDIT_MONGODB_DATABASE	none	MongoDB database name for the database sink
HFS_AUDIT_EXCLUDE_PATHS	none	Comma-separated paths to skip
HFS_AUDIT_SOURCE_OBSERVER	Device/hfs	AuditEvent.source.observer reference
HFS_AUDIT_CLOUDWATCH_LOG_GROUP / _LOG_STREAM / _REGION	none	CloudWatch Logs target
HFS_AUDIT_S3_BUCKET / _PREFIX / _REGION / _VALIDATE_BUCKETS	none	S3-related sink fields

Features

default = ["R4"]; R4/R4B/R5/R6 select the FHIR AuditEvent model (R5/R6 pull the R4B baseline). cloudwatch enables the CloudWatch Logs sink.

Key API

AuditConfig / AuditBackend, AuditEventBuilder, AuditMiddlewareState / AuditAgent / AuditResponseContext, AuditSink (DatabaseSink, FileSink, CloudWatchLogsSink, NullSink), ExclusionFilter, AuditCorrelation / BundleAuditEntry, AuditAction.

Code map / tests

config.rs, middleware.rs, balp.rs, builder.rs, sinks/ (database, file, cloudwatch, null), exclusion.rs, correlation.rs, lifecycle.rs, patient.rs. CI: .github/workflows/audit-events.yml. Unit tests inline in src/; integration tests under crates/audit/tests/ where present.