audit

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 43 Imported by: 0

Documentation

Overview

Package audit exposes durable control history and optionally exports its outbox over OTLP.

Index

Constants

View Source
const (
	LabelOrigin  = "backplane.audit.origin"
	LabelAudit   = "backplane.audit"
	LabelID      = "backplane.audit.id"
	LabelActor   = "backplane.audit.actor"
	LabelSubject = "backplane.audit.subject"
	LabelOutcome = "backplane.audit.outcome"
)

Attributes of an application audit record (backplane.AuditLabel and the rest in the SDK name the same keys).

Variables

This section is empty.

Functions

func Exporter

func Exporter(settings Settings) func(context.Context, Entry) error

Exporter synchronously exports one committed record. The caller owns retries and acknowledges its PostgreSQL outbox only after the Collector accepts it. Redirects are forbidden so authorization never reaches a different endpoint.

func Records

Records are the rows of the batch's records marked backplane.audit=true and within the size budget, and how many were rejected.

Types

type Entry

type Entry struct {
	ID          string            `json:"id"`
	Sequence    string            `json:"sequence"`
	CreatedAt   time.Time         `json:"created_at"`
	Actor       string            `json:"actor"`
	Action      string            `json:"action"`
	Subject     string            `json:"subject"`
	Outcome     string            `json:"outcome"`
	OperationID string            `json:"operation_id"`
	Detail      store.AuditDetail `json:"detail"`
	Service     string            `json:"service,omitempty"`
}

Entry is a durable platform control audit record. Numeric identities are strings to preserve their values across consumers; id is the deduplication identity.

type ErrorSink added in v0.4.0

type ErrorSink interface {
	Limits() apperrors.Limits
	Save(ctx context.Context, records []apperrors.Record) (stored, counted int64, err error)
	Count(ctx context.Context, outcome string, n int64)
}

ErrorSink keeps the exception records the listener receives besides audit: the error store.

type Ingest

type Ingest struct {
	collogspb.UnimplementedLogsServiceServer
	deps.Component
	// contains filtered or unexported fields
}

Ingest is backplane's OTLP audit listener: the deployment's Collector exports the log records marked backplane.audit=true here (opentelemetry.proto.collector.logs.v1.LogsService over gRPC). Every record it accepts is stored before the call returns, so a failed call is the Collector's to retry; retries are deduplicated.

func NewIngest

func NewIngest(parent deps.Scope, st deps.Dependency[*store.Store], settings Settings, opts ...IngestOption) *Ingest

NewIngest serves the audit listener of settings under parent.

func (*Ingest) Addr

func (in *Ingest) Addr() net.Addr

Addr is the listener's address once started, nil before.

func (*Ingest) Export

Export stores the batch's audit records in one transaction.

func (*Ingest) Register

func (in *Ingest) Register(registrar grpc.ServiceRegistrar)

Register serves the ingest on registrar (tests; the listener does it itself).

type IngestOption added in v0.4.0

type IngestOption func(*Ingest)

IngestOption configures NewIngest.

func WithErrors added in v0.4.0

func WithErrors(sink ErrorSink) IngestOption

WithErrors installs the sink of exception records; without one they are rejected like any unmarked record.

type Option

type Option func(*Service)

Option replaces integration boundaries for acceptance testing.

func WithPublisher

func WithPublisher(publish func(context.Context, Entry) error) Option

WithPublisher configures acknowledged export; persistence and claiming stay real.

func WithRetention

func WithRetention(retention time.Duration) Option

WithRetention enables deployment-controlled cleanup; zero keeps all records.

func WithRunQueue

func WithRunQueue(fn RunQueueFunc) Option

WithRunQueue attributes a run command whose workflow id follows no Backplane convention to the service of the run's task queue.

type RunQueueFunc

type RunQueueFunc func(ctx context.Context, workflowID, runID string) (string, error)

RunQueueFunc is the task queue of a run (Temporal's DescribeWorkflowExecution).

type Service

type Service struct {
	consolev1.UnimplementedAuditServiceServer
	deps.Component
	// contains filtered or unexported fields
}

Service reads committed history. Delivery failures leave the outbox intact.

func New

func New(parent deps.Scope, st deps.Dependency[*store.Store], options ...Option) *Service

New starts outbox delivery after the store dependency is ready.

func (*Service) AuditFacets

AuditFacets lists each target's most frequent values over the records matching the filter without the target's own conditions.

func (*Service) AuditFields

AuditFields lists the attribute keys of the matching records.

func (*Service) AuditHistogram

AuditHistogram counts matching records per bucket of the range.

func (*Service) Commands

func (s *Service) Commands(
	register func(grpc.ServiceRegistrar), author func(context.Context) string,
) func(grpc.ServiceRegistrar)

Commands wraps only the enumerated external-control RPCs. Database mutations append their audit inside the actual mutation transaction instead.

func (*Service) Deliver

func (s *Service) Deliver(ctx context.Context) error

Deliver claims a bounded batch. Leases protect acknowledgments from stale replicas. A crash after publish and before acknowledgment may redeliver.

func (*Service) Expire

func (s *Service) Expire(ctx context.Context, cutoff time.Time) error

Expire removes a bounded delivered prefix and advances the cursor floor in the same transaction. A pending outbox record stops expiry before its sequence.

func (*Service) Register

func (s *Service) Register(registrar grpc.ServiceRegistrar)

Register exposes the audit API on the authenticated console registrar.

func (*Service) SearchAudit

SearchAudit reads a page of the feed, newest first.

type Settings

type Settings struct {
	Retention time.Duration `json:"retention" schemapb:"default=0s;gte=0"`
	// Listen is the OTLP audit listener (gRPC LogsService) the Collector's
	// audit pipeline exports to: BACKPLANE_AUDIT_LISTEN.
	Listen string `json:"listen" schemapb:"default=:4317"`
	// Keys the Collector presents as a bearer token; empty: none required
	// (the listener is internal): BACKPLANE_AUDIT_KEYS, a JSON array.
	Keys []config.Secret `json:"keys,omitempty"`
	// ExportURL is the optional complete OTLP/HTTP logs endpoint. Empty disables
	// export, without changing the durable PostgreSQL history or ingest API.
	ExportURL           string        `json:"export_url,omitempty"`
	ExportAuthorization config.Secret `json:"export_authorization,omitempty"`
}

Settings is deployment-only; zero retention keeps all control audit records. Entries awaiting event delivery are never expired. Application audit is never expired. No UI exposes these settings.

func (Settings) Validate

func (s Settings) Validate() error

Validate rejects negative retention without imposing a deletion policy, and short keys.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL