Documentation
¶
Overview ¶
Package auditcore implements the auditcore Cell: tamper-evident audit log with hash chain (via runtime/audit/ledger framework), event consumption, and query.
Index ¶
- Constants
- func RegisterReadiness(reg cell.Registrar, p healthz.RepoProber) error
- type AuditCore
- type Option
- func WithBootstrapStore(s *audit.BootstrapLedgerStore) Option
- func WithCursorCodec(codec *query.CursorCodec) Option
- func WithEmitter(e outbox.CellEmitter) Option
- func WithLedgerProtocol(p *ledger.Protocol) Option
- func WithLedgerStore(s ledger.Store) Option
- func WithLogger(l *slog.Logger) Option
- func WithMetricsProvider(p metrics.Provider) Option
- func WithOutboxDeps(pub outbox.CellPublisher, writer outbox.CellWriter) Option
- func WithQueryStore(s ledger.QueryStore) Option
- func WithTxManager(tx persistence.CellTxManager) Option
Constants ¶
const ProbeRepoReady healthz.ProbeName = "auditcore_repo_ready"
ProbeRepoReady is the canonical readiness probe name for the auditcore cell's primary repository. The "_ready" suffix is required by the PROBENAME-SEALED-FUNNEL-01 convention.
Variables ¶
This section is empty.
Functions ¶
func RegisterReadiness ¶
func RegisterReadiness(reg cell.Registrar, p healthz.RepoProber) error
RegisterReadiness registers a healthz.RepoProber implementation as the cell-level repository readiness probe on the given Registrar. This is the sole sanctioned entry point — handwritten cell code must NOT call reg.RegisterReadiness directly with a bare string (locked by PROBENAME-SEALED-FUNNEL-01).
Emitter health probes are NOT generated per-cell: they go through the shared kernel funnel cell.RegisterEmitterHealthProbes(reg, emitter), which handles the healthz.ProbeSet assertion and typed-nil guard in one place.
Types ¶
type AuditCore ¶
AuditCore is the auditcore Cell implementation. +cell:listener:ref=cell.PrimaryListener,prefix=/api/v1/audit
func NewAuditCore ¶
NewAuditCore creates a new AuditCore Cell.
type Option ¶
type Option func(*AuditCore)
Option configures an AuditCore Cell.
func WithBootstrapStore ¶
func WithBootstrapStore(s *audit.BootstrapLedgerStore) Option
WithBootstrapStore injects the sealed *audit.BootstrapLedgerStore into the Cell so the auditappendbootstrap subscriber slice can write bootstrap-chain entries. This is an internal wiring option — it is only callable from the cellmodules/auditcore composition-root layer.
Bare-nil inputs are silently ignored (builder-option semantics). The final validation happens in initSlices: DurabilityDurable mode with a nil store fails fast at Init() (ErrCellMissingBootstrapStore); demo/test mode tolerates nil — the auditappendbootstrap.Service then permanently Rejects any consumed event to DLX rather than Requeueing.
func WithCursorCodec ¶
func WithCursorCodec(codec *query.CursorCodec) Option
WithCursorCodec sets the cursor codec for pagination.
func WithEmitter ¶
func WithEmitter(e outbox.CellEmitter) Option
WithEmitter injects a pre-composed outbox.CellEmitter directly into the Cell. Preferred path for tests and for composition roots that have already built an Emitter.
Mutually exclusive with WithOutboxDeps — setting both causes Init() to fail fast with ErrCellInvalidConfig. Durability for L2 slice decisions is derived from the injected emitter's Durable() method (DurabilityReporter).
ref: kubernetes/client-go rest.RESTClientFor — factory composes the typed client; resulting struct does not retain raw config fields.
func WithLedgerProtocol ¶
WithLedgerProtocol injects the *ledger.Protocol into the Cell.
Both bare-nil and typed-nil are rejected at Init() time (ledgerProtocolNil sentinel sticky). Pattern mirrors runtime/auth/session WithFingerprint (strong-dependency wiring option — runtime-api.md §Option 范式分层).
func WithLedgerStore ¶
WithLedgerStore injects the ledger.Store into the Cell. Used by the appender slices for writes and by strict tail verify at startup.
Both bare-nil and typed-nil are rejected at Init() time (ledgerStoreNil sentinel sticky). Pattern mirrors WithLedgerProtocol above.
func WithMetricsProvider ¶
WithMetricsProvider sets the metrics provider used by the DirectEmitter in demo mode. Required when WithOutboxDeps sets a publisher without a real outboxWriter. Pass metrics.NopProvider{} explicitly in tests.
func WithOutboxDeps ¶
func WithOutboxDeps(pub outbox.CellPublisher, writer outbox.CellWriter) Option
WithOutboxDeps wires sealed outbox dependencies (CellPublisher + CellWriter). Composition roots construct each via outbox.WrapPublisherForCell / outbox.WrapWriterForCell. The framework composes them into an outbox.Emitter at Init() time via outbox.ResolveCellEmitter.
Accumulative: a nil argument leaves the previously-set value in place; multiple calls combine their non-nil arguments. Does NOT clear previous state — `WithOutboxDeps(nil, nil)` is a no-op, not a reset. Mutually exclusive with WithEmitter; Init() fails fast if both are set.
AI-HARD per ADR cell-raw-infra-sealed-marker: the option signature rejects raw outbox.Publisher / outbox.Writer at compile time.
func WithQueryStore ¶
func WithQueryStore(s ledger.QueryStore) Option
WithQueryStore injects a narrow QueryStore for the auditquery slice. When not supplied, the slice falls back to the ledger.Store wired via WithLedgerStore (which satisfies QueryStore by structural typing).
The composition root uses this option to inject a ledger.MultiStore that fans out reads across multiple chains (issue #1121 / ADR 202605270230 — the auditcore relay chain and the bootstrap chain). Aggregator types that implement only QueryStore (e.g. *ledger.MultiStore) are deliberately not accepted by WithLedgerStore — a compile error prevents routing writes through a read-side fan-out.
Builder-style noop on typed-nil — final validation happens in Init when the slice services are constructed.
func WithTxManager ¶
func WithTxManager(tx persistence.CellTxManager) Option
WithTxManager sets the CellTxManager for transactional guarantees (L2 atomicity). Composition roots construct via persistence.WrapForCell.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package auditcoretest provides testutil helpers for the auditcore Cell.
|
Package auditcoretest provides testutil helpers for the auditcore Cell. |
|
internal
|
|
|
appender
Package appender is the single-source implementation of the auditcore audit-append behavior, shared by the four slice packages auditappend{user,config,session,role}.
|
Package appender is the single-source implementation of the auditcore audit-append behavior, shared by the four slice packages auditappend{user,config,session,role}. |
|
dto
Package dto holds typed payload structs for auditcore event contracts.
|
Package dto holds typed payload structs for auditcore event contracts. |
|
slices
|
|
|
auditappendbootstrap
Package auditappendbootstrap is the audit-append-bootstrap slice: it consumes event.auth.bootstrap-failed.v1 events and appends them to the bootstrap audit ledger via runtime/audit.AppendBootstrapAuthFail.
|
Package auditappendbootstrap is the audit-append-bootstrap slice: it consumes event.auth.bootstrap-failed.v1 events and appends them to the bootstrap audit ledger via runtime/audit.AppendBootstrapAuthFail. |
|
auditappendconfig
Package auditappendconfig is the audit-append-config slice: it consumes config-change events and appends them to the audit ledger.
|
Package auditappendconfig is the audit-append-config slice: it consumes config-change events and appends them to the audit ledger. |
|
auditappendrole
Package auditappendrole is the audit-append-role slice: it consumes role assignment events and appends them to the audit ledger.
|
Package auditappendrole is the audit-append-role slice: it consumes role assignment events and appends them to the audit ledger. |
|
auditappendsession
Package auditappendsession is the audit-append-session slice: it consumes session lifecycle events and appends them to the audit ledger.
|
Package auditappendsession is the audit-append-session slice: it consumes session lifecycle events and appends them to the audit ledger. |
|
auditappenduser
Package auditappenduser is the audit-append-user slice: it consumes user lifecycle events and appends them to the audit ledger.
|
Package auditappenduser is the audit-append-user slice: it consumes user lifecycle events and appends them to the audit ledger. |
|
auditquery
Package auditquery implements the audit-query slice: query audit entries via HTTP using ledger.Store.
|
Package auditquery implements the audit-query slice: query audit entries via HTTP using ledger.Store. |