audit

package
v0.3.0-alpha.2 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: Apache-2.0 Imports: 7 Imported by: 2

Documentation

Overview

Package audit defines bounded, channel-independent records for governed Action decisions and the Hook used to persist them.

Stability: alpha. Consumers should pin an exact pre-v1 Modary version.

Index

Constants

View Source 
const (
	MaxSummaryRunes   = 512
	MaxReasonRunes    = 2048
	MaxResources      = 32
	MaxReferences     = 32
	MaxResourceRunes  = 256
	MaxKindRunes      = 80
	MaxIDRunes        = 256
	MaxRequestIDRunes = 128
	MaxActorIDRunes   = 256
	MaxActorTypeRunes = 64
	MaxChannelRunes   = 64
	MaxActionIDRunes  = 127
	MaxVersionRunes   = 128
	MaxHashRunes      = 71
	MaxScopeKindRunes = 64
	MaxScopeIDRunes   = 256
	MaxCodeRunes      = 64
	// DefaultListLimit bounds one operational audit page by default.
	DefaultListLimit = 50
	// MaxListLimit is the largest operational audit page.
	MaxListLimit = 100
)

Persistence limits bound every user- or consumer-controlled audit field.

Variables

This section is empty.

Functions

This section is empty.

Types

type Event 

type Event struct {
	RequestID     string          `json:"request_id"`
	ActorID       string          `json:"actor_id,omitempty"`
	ActorType     string          `json:"actor_type,omitempty"`
	Channel       string          `json:"channel,omitempty"`
	ActionID      string          `json:"action_id"`
	ActionVersion string          `json:"action_version,omitempty"`
	ContractHash  string          `json:"contract_hash,omitempty"`
	Scope         scope.Execution `json:"scope"`
	InputHash     string          `json:"input_hash,omitempty"`
	PlanHash      string          `json:"plan_hash,omitempty"`
	Decision      string          `json:"decision"`
	AuditLevel    string          `json:"audit_level"`
	ResultSummary string          `json:"result_summary,omitempty"`
	Impact        *Impact         `json:"impact,omitempty"`
	ResultRefs    []Reference     `json:"result_refs,omitempty"`
	ErrorCode     string          `json:"error_code,omitempty"`
	ErrorKind     string          `json:"error_kind,omitempty"`
	Reason        string          `json:"reason,omitempty"`
	StartedAt     time.Time       `json:"started_at"`
	FinishedAt    time.Time       `json:"finished_at"`
}

Event is one normalized record of a governed Action decision or outcome. ErrorCode and ErrorKind are both present only for denied, rejected, or failed outcomes; adapters validate their semantic pairing before persistence.

func Normalize 

func Normalize(event Event) Event

Normalize applies the persistence boundary for audit data. Metadata events retain correlation fields but never business impact or result references.

type Hook 

type Hook interface {
	Record(context.Context, Event) error
}

Hook persists audit events. Returning nil asserts that the event is durably accepted; silently discarding an event violates this contract. Allowed events may be called inside the Action transaction and implementations must honor its context-bound executor. A returned error is an operational dependency failure classified as action.CodeInternal by Runtime. The official F0 implementation is components/postgres/sqlaudit. The same Hook may be called concurrently; implementations must be safe for concurrent use, honor context cancellation and deadlines, return promptly after cancellation, and treat Event as immutable for the duration of the call.

type Impact 

type Impact struct {
	Rows      int      `json:"rows,omitempty"`
	Resources []string `json:"resources,omitempty"`
}

Impact is the bounded mutation footprint attached to a detailed event.

type ListOptions 

type ListOptions struct {
	Scope    scope.Execution
	Limit    int
	BeforeID int64
}

ListOptions selects one descending, scope-bound audit page. BeforeID is an exclusive cursor returned by the previous Page.

func NormalizeListOptions 

func NormalizeListOptions(options ListOptions) (ListOptions, error)

NormalizeListOptions validates one provider-neutral audit query.

type Page 

type Page struct {
	Events       []Summary `json:"events"`
	NextBeforeID int64     `json:"next_before_id,omitempty,string"`
}

Page is one bounded audit inspection result.

type Reader 

type Reader interface {
	List(context.Context, ListOptions) (Page, error)
}

Reader exposes scope-bound audit metadata without write or raw SQL access.

type Reference 

type Reference struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
}

Reference identifies a durable result without embedding business data.

type Summary 

type Summary struct {
	ID         int64           `json:"id,string"`
	RequestID  string          `json:"request_id"`
	ActorID    string          `json:"actor_id,omitempty"`
	ActorType  string          `json:"actor_type,omitempty"`
	Channel    string          `json:"channel,omitempty"`
	ActionID   string          `json:"action_id"`
	Decision   string          `json:"decision"`
	ErrorCode  string          `json:"error_code,omitempty"`
	Scope      scope.Execution `json:"scope"`
	StartedAt  time.Time       `json:"started_at"`
	FinishedAt time.Time       `json:"finished_at"`
}

Summary is bounded operational audit metadata. It excludes inputs, result summaries, impact resources, references, and free-form reasons.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.