observability

package
v2.0.4 Latest Latest
Warning

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

 Go to latest Published: Aug 16, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidMutationOutcome = errors.New("invalid security audit mutation outcome")
	ErrSecurityAuditNotFound  = errors.New("security audit journal record not found")
	ErrSecurityAuditCompleted = errors.New("security audit mutation is already completed")
	ErrSecurityAuditCapacity  = errors.New("security audit journal capacity exhausted")
)
View Source 
var (
	ErrInvalidEvent              = errors.New("plugin observability event is invalid")
	ErrInvalidAuditDetails       = errors.New("plugin audit details are invalid")
	ErrInvalidDiagnosticSeverity = errors.New("plugin diagnostic severity is invalid")
	ErrInvalidDiagnosticMessage  = errors.New("plugin diagnostic message is invalid")
	ErrInvalidDiagnosticDetails  = errors.New("plugin diagnostic details are invalid")
	ErrInvalidDiagnosticFailure  = errors.New("plugin diagnostic failure is invalid")
	ErrDiagnosticScopeRequired   = errors.New("complete diagnostic owner scope is required")
)

Functions

func ValidateAuditEvent 

func ValidateAuditEvent(event AuditEvent) error

func ValidateDiagnosticEvent 

func ValidateDiagnosticEvent(event DiagnosticEvent) error

Types

type AuditEvent 

type AuditEvent struct {
	EventID           string         `json:"event_id,omitempty"`
	Type              string         `json:"type"`
	PluginID          string         `json:"plugin_id"`
	PluginInstanceID  string         `json:"plugin_instance_id,omitempty"`
	SurfaceID         string         `json:"surface_id,omitempty"`
	SurfaceInstanceID string         `json:"surface_instance_id,omitempty"`
	RequestID         string         `json:"request_id,omitempty"`
	Actor             string         `json:"actor,omitempty"`
	OccurredAt        time.Time      `json:"occurred_at,omitempty"`
	Details           map[string]any `json:"details,omitempty"`
}

type AuditSink 

type AuditSink interface {
	AppendPluginAudit(ctx context.Context, event AuditEvent) error
}

type DiagnosticDetails 

type DiagnosticDetails struct {
	ExecutionsDeleted         int64                     `json:"executions_deleted,omitempty"`
	InvocationID              string                    `json:"invocation_id,omitempty"`
	Method                    string                    `json:"method,omitempty"`
	FailureCode               string                    `json:"failure_code,omitempty"`
	RuntimeProcessFailureCode RuntimeProcessFailureCode `json:"runtime_process_failure_code,omitempty"`
	ExecutionID               string                    `json:"execution_id,omitempty"`
	RuntimeInstanceID         string                    `json:"runtime_instance_id,omitempty"`
	RuntimeGenerationID       string                    `json:"runtime_generation_id,omitempty"`
	RuntimeVersion            string                    `json:"runtime_version,omitempty"`
	RustIPCVersion            string                    `json:"rust_ipc_version,omitempty"`
	WASMABIVersion            string                    `json:"wasm_abi_version,omitempty"`
	ContractSetSHA256         string                    `json:"contract_set_sha256,omitempty"`
	RuntimeTargetOS           string                    `json:"runtime_target_os,omitempty"`
	RuntimeTargetArch         string                    `json:"runtime_target_arch,omitempty"`
	RuntimeBinarySHA256       string                    `json:"runtime_binary_sha256,omitempty"`
	OS                        string                    `json:"os,omitempty"`
	Arch                      string                    `json:"arch,omitempty"`
	Stream                    string                    `json:"stream,omitempty"`
	PackageHash               string                    `json:"package_hash,omitempty"`
	Artifact                  string                    `json:"artifact,omitempty"`
	PluginInstanceID          string                    `json:"plugin_instance_id,omitempty"`
	StoreID                   string                    `json:"store_id,omitempty"`
	Operation                 string                    `json:"operation,omitempty"`
	Hostcall                  string                    `json:"hostcall,omitempty"`
	Code                      string                    `json:"code,omitempty"`
	ConnectorID               string                    `json:"connector_id,omitempty"`
	Transport                 string                    `json:"transport,omitempty"`
	RevokeEpoch               uint64                    `json:"revoke_epoch,omitempty"`
	StageID                   string                    `json:"stage_id,omitempty"`
	Reason                    string                    `json:"reason,omitempty"`
	SurfaceInstanceID         string                    `json:"surface_instance_id,omitempty"`
}

func (DiagnosticDetails) Valid 

func (details DiagnosticDetails) Valid() bool

type DiagnosticEvent 

type DiagnosticEvent struct {
	EventID              string             `json:"event_id,omitempty"`
	Type                 string             `json:"type"`
	Severity             DiagnosticSeverity `json:"severity"`
	Message              string             `json:"message"`
	PluginID             string             `json:"plugin_id,omitempty"`
	PluginInstanceID     string             `json:"plugin_instance_id,omitempty"`
	SurfaceID            string             `json:"surface_id,omitempty"`
	SurfaceInstanceID    string             `json:"surface_instance_id,omitempty"`
	ActiveFingerprint    string             `json:"active_fingerprint,omitempty"`
	RequestID            string             `json:"request_id,omitempty"`
	CorrelationID        string             `json:"correlation_id,omitempty"`
	MutationOutcome      mutation.Outcome   `json:"mutation_outcome,omitempty"`
	OwnerSessionHash     string             `json:"-"`
	OwnerUserHash        string             `json:"-"`
	OwnerEnvHash         string             `json:"-"`
	SessionChannelIDHash string             `json:"-"`
	OccurredAt           time.Time          `json:"occurred_at,omitempty"`
	Details              DiagnosticDetails  `json:"details,omitempty"`
	Failure              Failure            `json:"-"`
}

type DiagnosticLister 

type DiagnosticLister interface {
	ListPluginDiagnostics(ctx context.Context, req ListDiagnosticRequest) ([]DiagnosticEvent, error)
}

type DiagnosticSeverity 

type DiagnosticSeverity string
const (
	DiagnosticSeverityInfo    DiagnosticSeverity = "info"
	DiagnosticSeverityWarning DiagnosticSeverity = "warning"
)

func (DiagnosticSeverity) Valid 

func (severity DiagnosticSeverity) Valid() bool

type DiagnosticsSink 

type DiagnosticsSink interface {
	AppendPluginDiagnostic(ctx context.Context, event DiagnosticEvent) error
}

type Failure 

type Failure struct {
	Code      FailureCode      `json:"code"`
	Component FailureComponent `json:"component"`
	Operation FailureOperation `json:"operation"`
}

Failure is a stable diagnostic description that intentionally excludes the underlying error text. It is safe to persist at adapter and action boundaries.

func FailureFromError 

func FailureFromError(code FailureCode, component FailureComponent, operation FailureOperation, cause error) Failure

func (Failure) Empty 

func (f Failure) Empty() bool

func (Failure) Error 

func (f Failure) Error() string

func (Failure) Valid 

func (f Failure) Valid() bool

type FailureCode 

type FailureCode string
const (
	FailureAdapter FailureCode = "adapter_failure"
	FailureOwner   FailureCode = "owner_failure"
	FailureScope   FailureCode = "scope_failure"
	FailureAction  FailureCode = "action_failure"
)

func (FailureCode) Valid 

func (code FailureCode) Valid() bool

type FailureComponent 

type FailureComponent string
const (
	FailureComponentExecution FailureComponent = "execution"
	FailureComponentHTTP      FailureComponent = "http"
	FailureComponentLifecycle FailureComponent = "lifecycle"
	FailureComponentRuntime   FailureComponent = "runtime"
	FailureComponentSecrets   FailureComponent = "secrets"
	FailureComponentSecurity  FailureComponent = "security"
)

func (FailureComponent) Valid 

func (component FailureComponent) Valid() bool

type FailureOperation 

type FailureOperation string
const (
	FailureOperationExecutionRetentionPrune  FailureOperation = "execution.retention_prune"
	FailureOperationExecutionFail            FailureOperation = "execution.fail"
	FailureOperationExecutionDurationPersist FailureOperation = "execution.duration_persist"
	FailureOperationHTTPAdapter              FailureOperation = "http.adapter"
	FailureOperationLifecycle                FailureOperation = "lifecycle.operation"
	FailureOperationRuntimeStop              FailureOperation = "runtime.stop"
	FailureOperationRuntimeRevoke            FailureOperation = "runtime.revoke"
	FailureOperationRuntimeProcessStop       FailureOperation = "runtime.process.stop"
	FailureOperationRuntimeProcessExit       FailureOperation = "runtime.process.exit"
	FailureOperationRuntimeProcessOutput     FailureOperation = "runtime.process.output"
	FailureOperationRuntimeHostcall          FailureOperation = "runtime.hostcall"
	FailureOperationRuntimeIPCInvalidate     FailureOperation = "runtime.ipc.invalidate"
	FailureOperationSecretsAdapter           FailureOperation = "secrets.adapter"
	FailureOperationSecurityEventPersist     FailureOperation = "security_event.persist"
	FailureOperationSecurityMutationComplete FailureOperation = "security_mutation.complete"
	FailureOperationSecurityAuditExport      FailureOperation = "security_audit.export"
	FailureOperationMethodReject             FailureOperation = "method.reject"
)

func (FailureOperation) Valid 

func (operation FailureOperation) Valid() bool

type ListDiagnosticRequest 

type ListDiagnosticRequest struct {
	PluginID             string             `json:"plugin_id,omitempty"`
	PluginInstanceID     string             `json:"plugin_instance_id,omitempty"`
	SurfaceInstanceID    string             `json:"surface_instance_id,omitempty"`
	OwnerSessionHash     string             `json:"-"`
	OwnerUserHash        string             `json:"-"`
	OwnerEnvHash         string             `json:"-"`
	SessionChannelIDHash string             `json:"-"`
	Type                 string             `json:"type,omitempty"`
	Severity             DiagnosticSeverity `json:"severity,omitempty"`
	Limit                int                `json:"limit,omitempty"`
}

type MemorySecurityAuditJournal 

type MemorySecurityAuditJournal struct {
	// contains filtered or unexported fields
}

MemorySecurityAuditJournal is a fixed-capacity implementation for tests and in-memory hosts. Capacity pressure only evicts records that were exported; protected records make Begin fail closed. A non-positive MaxEntries uses the platform default and never disables retention limits.

func NewMemorySecurityAuditJournal 

func NewMemorySecurityAuditJournal(opts ...MemorySecurityAuditJournalOptions) *MemorySecurityAuditJournal

func (*MemorySecurityAuditJournal) BeginSecurityAudit 

func (j *MemorySecurityAuditJournal) BeginSecurityAudit(_ context.Context, event AuditEvent) (SecurityAuditRecord, error)

func (*MemorySecurityAuditJournal) CompleteSecurityAudit 

func (j *MemorySecurityAuditJournal) CompleteSecurityAudit(_ context.Context, eventID string, outcome mutation.Outcome, details map[string]any) error

func (*MemorySecurityAuditJournal) ListPendingSecurityAudits 

func (j *MemorySecurityAuditJournal) ListPendingSecurityAudits(_ context.Context) ([]SecurityAuditRecord, error)

func (*MemorySecurityAuditJournal) ListUnexportedSecurityAudits 

func (j *MemorySecurityAuditJournal) ListUnexportedSecurityAudits(_ context.Context) ([]SecurityAuditRecord, error)

func (*MemorySecurityAuditJournal) MarkSecurityAuditExported 

func (j *MemorySecurityAuditJournal) MarkSecurityAuditExported(_ context.Context, eventID string) error

func (*MemorySecurityAuditJournal) ReconcilePendingSecurityAudits 

func (j *MemorySecurityAuditJournal) ReconcilePendingSecurityAudits(_ context.Context) error

type MemorySecurityAuditJournalOptions 

type MemorySecurityAuditJournalOptions struct {
	Now        func() time.Time
	MaxEntries int
}

type MemoryStore 

type MemoryStore struct {
	// contains filtered or unexported fields
}

func NewMemoryStore 

func NewMemoryStore(opts ...MemoryStoreOptions) *MemoryStore

func (*MemoryStore) AppendPluginAudit 

func (s *MemoryStore) AppendPluginAudit(_ context.Context, event AuditEvent) error

func (*MemoryStore) AppendPluginDiagnostic 

func (s *MemoryStore) AppendPluginDiagnostic(_ context.Context, event DiagnosticEvent) error

func (*MemoryStore) BeginSecurityAudit 

func (s *MemoryStore) BeginSecurityAudit(ctx context.Context, event AuditEvent) (SecurityAuditRecord, error)

MemoryStore exposes the journal contract as well as the ordinary audit sink, allowing a host configured with one in-memory observability adapter to retain the same mutation semantics as a persistent store.

func (*MemoryStore) CompleteSecurityAudit 

func (s *MemoryStore) CompleteSecurityAudit(ctx context.Context, eventID string, outcome mutation.Outcome, details map[string]any) error

func (*MemoryStore) ListPendingSecurityAudits 

func (s *MemoryStore) ListPendingSecurityAudits(ctx context.Context) ([]SecurityAuditRecord, error)

func (*MemoryStore) ListPluginDiagnostics 

func (s *MemoryStore) ListPluginDiagnostics(_ context.Context, req ListDiagnosticRequest) ([]DiagnosticEvent, error)

func (*MemoryStore) ListUnexportedSecurityAudits 

func (s *MemoryStore) ListUnexportedSecurityAudits(ctx context.Context) ([]SecurityAuditRecord, error)

func (*MemoryStore) MarkSecurityAuditExported 

func (s *MemoryStore) MarkSecurityAuditExported(ctx context.Context, eventID string) error

func (*MemoryStore) ReconcilePendingSecurityAudits 

func (s *MemoryStore) ReconcilePendingSecurityAudits(ctx context.Context) error

type MemoryStoreOptions 

type MemoryStoreOptions struct {
	Now                 func() time.Time
	MaxAuditEvents      int
	MaxDiagnosticEvents int
}

type RuntimeProcessFailureCode 

type RuntimeProcessFailureCode string
const (
	RuntimeProcessFailed                      RuntimeProcessFailureCode = "RUNTIME_PROCESS_FAILED"
	RuntimeProcessExitUnexpected              RuntimeProcessFailureCode = "RUNTIME_PROCESS_EXIT_UNEXPECTED"
	RuntimeProcessExitUnrecognized            RuntimeProcessFailureCode = "RUNTIME_PROCESS_EXIT_UNRECOGNIZED"
	RuntimeProcessSignalled                   RuntimeProcessFailureCode = "RUNTIME_PROCESS_SIGNALLED"
	RuntimeProcessWriterCapacityOverflow      RuntimeProcessFailureCode = "IPC_WRITER_CAPACITY_OVERFLOW"
	RuntimeProcessWriterCapacityLimitExceeded RuntimeProcessFailureCode = "IPC_WRITER_CAPACITY_LIMIT_EXCEEDED"
	RuntimeProcessWriterStartFailed           RuntimeProcessFailureCode = "IPC_WRITER_START_FAILED"
	RuntimeProcessWriterClosed                RuntimeProcessFailureCode = "IPC_WRITER_CLOSED"
	RuntimeProcessWriterBatchSizeOverflow     RuntimeProcessFailureCode = "IPC_WRITER_BATCH_SIZE_OVERFLOW"
	RuntimeProcessWriterWriteFailed           RuntimeProcessFailureCode = "IPC_WRITER_WRITE_FAILED"
	RuntimeProcessWriterFlushFailed           RuntimeProcessFailureCode = "IPC_WRITER_FLUSH_FAILED"
	RuntimeProcessWriterPanicked              RuntimeProcessFailureCode = "IPC_WRITER_PANICKED"
)

func RuntimeProcessFailureCodes 

func RuntimeProcessFailureCodes() []RuntimeProcessFailureCode

RuntimeProcessFailureCodes returns an owned copy of the released diagnostic code set.

func (RuntimeProcessFailureCode) Valid 

func (code RuntimeProcessFailureCode) Valid() bool

type SQLiteStore 

type SQLiteStore struct {
	// contains filtered or unexported fields
}

func NewSQLiteStore 

func NewSQLiteStore(ctx context.Context, path string, opts ...MemoryStoreOptions) (*SQLiteStore, error)

func (*SQLiteStore) AppendPluginAudit 

func (s *SQLiteStore) AppendPluginAudit(ctx context.Context, event AuditEvent) error

func (*SQLiteStore) AppendPluginDiagnostic 

func (s *SQLiteStore) AppendPluginDiagnostic(ctx context.Context, event DiagnosticEvent) error

func (*SQLiteStore) BeginSecurityAudit 

func (s *SQLiteStore) BeginSecurityAudit(ctx context.Context, event AuditEvent) (SecurityAuditRecord, error)

func (*SQLiteStore) Close 

func (s *SQLiteStore) Close() error

func (*SQLiteStore) CompleteSecurityAudit 

func (s *SQLiteStore) CompleteSecurityAudit(ctx context.Context, eventID string, outcome mutation.Outcome, details map[string]any) error

func (*SQLiteStore) ListPendingSecurityAudits 

func (s *SQLiteStore) ListPendingSecurityAudits(ctx context.Context) ([]SecurityAuditRecord, error)

func (*SQLiteStore) ListPluginDiagnostics 

func (s *SQLiteStore) ListPluginDiagnostics(ctx context.Context, req ListDiagnosticRequest) ([]DiagnosticEvent, error)

func (*SQLiteStore) ListUnexportedSecurityAudits 

func (s *SQLiteStore) ListUnexportedSecurityAudits(ctx context.Context) ([]SecurityAuditRecord, error)

func (*SQLiteStore) MarkSecurityAuditExported 

func (s *SQLiteStore) MarkSecurityAuditExported(ctx context.Context, eventID string) error

func (*SQLiteStore) ReconcilePendingSecurityAudits 

func (s *SQLiteStore) ReconcilePendingSecurityAudits(ctx context.Context) error

type SecurityAuditExporter 

type SecurityAuditExporter struct {
	// contains filtered or unexported fields
}

SecurityAuditExporter delivers complete journal records to a host sink. Marking a record exported happens only after the sink acknowledges it.

func NewSecurityAuditExporter 

func NewSecurityAuditExporter(journal SecurityAuditJournal, sink AuditSink) *SecurityAuditExporter

func (*SecurityAuditExporter) Export 

func (e *SecurityAuditExporter) Export(ctx context.Context) error

type SecurityAuditJournal 

type SecurityAuditJournal interface {
	BeginSecurityAudit(ctx context.Context, event AuditEvent) (SecurityAuditRecord, error)
	CompleteSecurityAudit(ctx context.Context, eventID string, outcome mutation.Outcome, details map[string]any) error
	ListPendingSecurityAudits(ctx context.Context) ([]SecurityAuditRecord, error)
	ListUnexportedSecurityAudits(ctx context.Context) ([]SecurityAuditRecord, error)
	MarkSecurityAuditExported(ctx context.Context, eventID string) error
	ReconcilePendingSecurityAudits(ctx context.Context) error
}

SecurityAuditJournal is the durable boundary for security mutation audit records. Implementations must make Begin and Complete atomic with respect to their own storage and must preserve records when an export fails.

type SecurityAuditRecord 

type SecurityAuditRecord struct {
	EventID           string             `json:"event_id"`
	Event             AuditEvent         `json:"event"`
	State             SecurityAuditState `json:"state"`
	Outcome           mutation.Outcome   `json:"mutation_outcome,omitempty"`
	CompletionDetails map[string]any     `json:"completion_details,omitempty"`
	CreatedAt         time.Time          `json:"created_at"`
	CompletedAt       *time.Time         `json:"completed_at,omitempty"`
	ExportedAt        *time.Time         `json:"exported_at,omitempty"`
}

SecurityAuditRecord is an immutable snapshot of a journal record. EventID is stable for the entire lifecycle and is also used for exporter idempotency.

type SecurityAuditState 

type SecurityAuditState string

SecurityAuditState describes the durable state of a security mutation audit. Pending records are written before a mutation starts and must never be exported as committed events until CompleteSecurityAudit is durable. 

const (
	SecurityAuditPending   SecurityAuditState = "pending"
	SecurityAuditCompleted SecurityAuditState = "completed"
)

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.