Documentation
¶
Overview ¶
Package audit provides a small append-only, tamper-evident event log.
Index ¶
- Constants
- Variables
- func Scan(dir string, visit func(Entry) error) error
- func Verify(dir string) error
- type Entry
- type EntryReference
- type Event
- type Log
- func (l *Log) AliasesDirectory(directory *os.File) (bool, error)
- func (l *Log) AliasesEntry(parent *os.File, name string) (bool, error)
- func (l *Log) AliasesPath(path string) (bool, error)
- func (l *Log) Append(event Event) (Entry, error)
- func (l *Log) AppendWithReference(event Event) (Entry, EntryReference, error)
- func (l *Log) Close() error
- func (l *Log) Head() (uint64, string, error)
- func (l *Log) Path() string
- func (l *Log) ReadAll() ([]Entry, error)
- func (l *Log) ReadReference(reference EntryReference) (Entry, error)
- func (l *Log) Scan(visit func(Entry) error) error
- func (l *Log) ScanWithReferences(visit func(Entry, EntryReference) error) error
- func (l *Log) Usage() (usedBytes, maxBytes int64, err error)
- func (l *Log) Verify() error
Constants ¶
const ( // FileName is the fixed file name used inside an audit directory. FileName = "audit.jsonl" // DefaultMaxBytes bounds the audit log when callers do not select a // deployment-specific quota. DefaultMaxBytes int64 = 256 << 20 )
Variables ¶
var ( ErrClosed = errors.New("audit log is closed") ErrLocked = errors.New("audit log is already open by another writer") ErrQuotaExceeded = errors.New("audit log quota exceeded") ErrUnsupportedPlatform = errors.New("secure audit storage is unsupported on this platform") ErrUncertainDurability = errors.New("audit durability is uncertain; close and reopen the log") )
Functions ¶
Types ¶
type Entry ¶
type Entry struct {
Seq uint64 `json:"seq"`
EventID string `json:"event_id"`
ExchangeID string `json:"exchange_id"`
RequestID string `json:"request_id"`
ConversationID string `json:"conversation_id"`
Type string `json:"type"`
Status string `json:"status"`
ErrorCode string `json:"error_code"`
Timestamp string `json:"timestamp"`
Text string `json:"text"`
TextSHA256 string `json:"text_sha256"`
Details map[string]string `json:"details,omitempty"`
PreviousHash string `json:"previous_hash"`
EntryHash string `json:"entry_hash"`
}
Entry is the durable representation of an audit event.
type EntryReference ¶
type EntryReference struct {
// contains filtered or unexported fields
}
EntryReference identifies one verified entry in the append-only log without retaining its text in memory. References are valid for the lifetime of the log: successful appends never move existing bytes.
type Event ¶
type Event struct {
EventID string
ExchangeID string
RequestID string
ConversationID string
Type string
Status string
ErrorCode string
Text string
Details map[string]string
}
Event contains the caller-controlled fields for a new audit entry. Timestamp, sequence number, hashes, and the previous-chain link are assigned by Append.
type Log ¶
type Log struct {
// contains filtered or unexported fields
}
Log serializes appends from all goroutines and holds an exclusive OS lock for its lifetime so another process cannot write the same chain concurrently.
func Open ¶
Open creates or opens an audit directory, enforces restrictive permissions, and verifies the complete existing chain before allowing another append.
func OpenWithQuota ¶
OpenWithQuota opens an audit log with a maximum encoded size. An existing verified log may be opened above the selected quota for inspection and recovery, but no new entry is admitted until it fits within the quota.
func (*Log) AliasesDirectory ¶
AliasesDirectory reports whether directory is the held audit/state directory. The caller must retain the descriptor through its mutation.
func (*Log) AliasesEntry ¶
AliasesEntry reports whether name in the already-open parent directory is the reserved audit entry or an existing hard link to the held audit file. Callers can retain parent through a subsequent descriptor-relative rename, eliminating path-resolution and check-then-reopen gaps.
func (*Log) AliasesPath ¶
AliasesPath performs a best-effort path preflight for clear CLI diagnostics. It is not an authorization boundary: callers that will mutate the path must use AliasesEntry with the exact parent descriptor retained for that mutation.
func (*Log) Append ¶
Append durably adds an event. It returns only after the entry has been written and fsynced. A write or sync failure makes this handle unusable, because durability is then uncertain; reopen the log to recover safely.
func (*Log) AppendWithReference ¶
func (l *Log) AppendWithReference(event Event) (Entry, EntryReference, error)
AppendWithReference durably adds an event and returns a stable reference that can later be read without scanning the complete log.
func (*Log) ReadReference ¶
func (l *Log) ReadReference(reference EntryReference) (Entry, error)
ReadReference reads and verifies one previously indexed entry under the writer mutex. It fails closed when the live handle is closed or poisoned.
func (*Log) Scan ¶
Scan verifies the complete chain and calls visit once for each entry while holding the writer mutex. Entries are decoded one at a time, so callers can inspect long logs without retaining every message in memory. The visitor must not call methods on l.
func (*Log) ScanWithReferences ¶
func (l *Log) ScanWithReferences(visit func(Entry, EntryReference) error) error
ScanWithReferences verifies the complete chain and visits each entry with a stable byte reference. The visitor must not call methods on l.
Source Files