Documentation
¶
Overview ¶
Package audit_hook provides the audit extension for Nexus. It bridges lifecycle events from the plugin.Registry to an audit recorder (typically Chronicle). This follows the dispatch/audit_hook pattern exactly.
Usage:
nexus.WithExtension(audit_hook.New(audit_hook.RecorderFunc(func(ctx context.Context, event *audit_hook.AuditEvent) error {
log.Println("audit:", event.Action, event.Resource)
return nil
})))
Index ¶
- type Action
- type AuditEvent
- type Category
- type Extension
- func (e *Extension) Name() string
- func (e *Extension) OnBudgetExceeded(ctx context.Context, tenantID id.TenantID) error
- func (e *Extension) OnBudgetWarning(ctx context.Context, tenantID id.TenantID, usedPct float64) error
- func (e *Extension) OnCircuitOpened(ctx context.Context, providerName string) error
- func (e *Extension) OnFallbackTriggered(ctx context.Context, from, to string) error
- func (e *Extension) OnGuardrailBlocked(ctx context.Context, guardName string, requestID id.RequestID) error
- func (e *Extension) OnGuardrailRedacted(ctx context.Context, guardName, field string) error
- func (e *Extension) OnKeyCreated(ctx context.Context, keyID id.KeyID, tenantID id.TenantID) error
- func (e *Extension) OnKeyRevoked(ctx context.Context, keyID id.KeyID) error
- func (e *Extension) OnProviderFailed(ctx context.Context, providerName, model string, err error) error
- func (e *Extension) OnRequestCached(ctx context.Context, requestID id.RequestID, model string) error
- func (e *Extension) OnRequestCompleted(ctx context.Context, requestID id.RequestID, model, providerName string, ...) error
- func (e *Extension) OnRequestFailed(ctx context.Context, requestID id.RequestID, model string, err error) error
- func (e *Extension) OnRequestReceived(ctx context.Context, requestID id.RequestID, model, tenantID string) error
- func (e *Extension) OnStreamCompleted(ctx context.Context, requestID id.RequestID, model, providerName string, ...) error
- func (e *Extension) OnStreamFailed(ctx context.Context, requestID id.RequestID, model string, err error) error
- func (e *Extension) OnStreamStarted(ctx context.Context, requestID id.RequestID, model, providerName string) error
- func (e *Extension) OnTenantCreated(ctx context.Context, tenantID id.TenantID) error
- func (e *Extension) OnTenantDisabled(ctx context.Context, tenantID id.TenantID) error
- type Option
- type Recorder
- type RecorderFunc
- type Resource
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Action ¶
type Action string
Action is the type of audit event.
const ( // Request actions ActionRequestReceived Action = "request.received" ActionRequestCompleted Action = "request.completed" ActionRequestFailed Action = "request.failed" ActionRequestCached Action = "request.cached" // Provider actions ActionProviderFailed Action = "provider.failed" ActionCircuitOpened Action = "circuit.opened" ActionFallbackTriggered Action = "fallback.triggered" // Guardrail actions ActionGuardrailBlocked Action = "guardrail.blocked" ActionGuardrailRedacted Action = "guardrail.redacted" // Tenant/Key actions ActionTenantCreated Action = "tenant.created" ActionTenantDisabled Action = "tenant.disabled" ActionKeyCreated Action = "key.created" ActionKeyRevoked Action = "key.revoked" // Budget actions ActionBudgetWarning Action = "budget.warning" ActionBudgetExceeded Action = "budget.exceeded" // Stream actions ActionStreamStarted Action = "stream.started" ActionStreamCompleted Action = "stream.completed" ActionStreamFailed Action = "stream.failed" )
type AuditEvent ¶
type AuditEvent struct {
Timestamp time.Time `json:"timestamp"`
Action Action `json:"action"`
Resource Resource `json:"resource"`
Category Category `json:"category"`
ActorID string `json:"actor_id,omitempty"` // tenant or key ID
TenantID string `json:"tenant_id,omitempty"`
ResourceID string `json:"resource_id,omitempty"`
Details map[string]any `json:"details,omitempty"`
}
AuditEvent is an audit log entry.
type Extension ¶
type Extension struct {
// contains filtered or unexported fields
}
Extension implements all plugin lifecycle hooks and records audit events.
func (*Extension) OnBudgetExceeded ¶
func (*Extension) OnBudgetWarning ¶
func (*Extension) OnCircuitOpened ¶
func (*Extension) OnFallbackTriggered ¶
func (*Extension) OnGuardrailBlocked ¶
func (*Extension) OnGuardrailRedacted ¶
func (*Extension) OnKeyCreated ¶
func (*Extension) OnKeyRevoked ¶
func (*Extension) OnProviderFailed ¶
func (*Extension) OnRequestCached ¶
func (*Extension) OnRequestCompleted ¶
func (*Extension) OnRequestFailed ¶
func (*Extension) OnRequestReceived ¶
func (*Extension) OnStreamCompleted ¶
func (*Extension) OnStreamFailed ¶
func (*Extension) OnStreamStarted ¶
func (*Extension) OnTenantCreated ¶
type Option ¶
type Option func(*Extension)
Option configures the audit extension.
func WithActions ¶
WithActions filters to only record specific actions.
func WithLogger ¶
WithLogger sets a custom logger for the extension.
type Recorder ¶
type Recorder interface {
Record(ctx context.Context, event *AuditEvent) error
}
Recorder persists audit events. It takes the event by pointer, like chronicle's emitter and dispatch's audit_hook. Each call gets a fresh event that the recorder may keep or modify.
type RecorderFunc ¶
type RecorderFunc func(ctx context.Context, event *AuditEvent) error
RecorderFunc is a function adapter for Recorder.
func (RecorderFunc) Record ¶
func (f RecorderFunc) Record(ctx context.Context, event *AuditEvent) error