Documentation
¶
Overview ¶
Package journal implements durable admission only. Callers perform preflight between Lookup and Admit, and effects after Admit returns Fresh, outside locks. An error from Admit never permits an effect, even if a write reached disk.
Index ¶
- Constants
- Variables
- func LinuxBootSample(path string) (boot string, sec, nsec int64, ok bool)
- type Admission
- type Clock
- type ClockFunc
- type Digest
- type Key
- type KeyKind
- type Limits
- type Navigation
- type Options
- type PlatformClock
- type RatePolicy
- type Receipt
- type Record
- type Result
- type Sample
- type Snapshot
- type Store
- func (s *Store) Admit(ctx context.Context, a Admission) (out Result, err error)
- func (s *Store) Collect(ctx context.Context) error
- func (s *Store) Finalize(ctx context.Context, k Key, attempt, status, reason, backend string) error
- func (s *Store) FinalizeOutcome(ctx context.Context, k Key, attempt, status, reason, backend string, ...) error
- func (s *Store) Lookup(ctx context.Context, k Key, digest Digest) (out Result, err error)
- func (s *Store) Namespace() string
- type Target
Constants ¶
const MaxRate = 10000
MaxRate is the existing maximum record/JSON-array budget. Rate capacity does not reserve storage: the independent record, byte and retention limits apply.
const MinRetention uint64 = 7 * 24 * 60 * 60
const Protocol = "agent-notify/journal/v1"
const TrustedBootIDPath = "/proc/sys/kernel/random/boot_id"
TrustedBootIDPath is the kernel procfs boot identity. Production clocks inject this path explicitly; the zero PlatformClock never implies a filesystem root.
Variables ¶
Functions ¶
Types ¶
type Admission ¶
type Admission struct {
Rates RatePolicy
Key Key
Digest Digest
TrackingID string
Decision Snapshot
}
type Clock ¶
type Clock interface{ Sample() Sample }
Clock must return promptly and be safe for concurrent calls. Unavailable samples freeze collection and rate recovery; nil has the same behavior.
func DefaultClock ¶
func DefaultClock() Clock
DefaultClock is the production Linux journal clock. Tests that need an unavailable clock still construct the zero PlatformClock.
type Digest ¶
type Digest [32]byte
Digest is computed by the service from versioned normalized caller payload, never from mutable delivery configuration. No payload is accepted or stored.
type Navigation ¶
type Navigation struct {
}
type PlatformClock ¶
type PlatformClock struct{ BootIDPath string }
PlatformClock requires an explicitly injected boot ID path on Linux (normally TrustedBootIDPath). No user HOME/config path is consulted. CLOCK_BOOTTIME includes elapsed suspend time and never uses wall time.
func (PlatformClock) Sample ¶
func (c PlatformClock) Sample() Sample
type RatePolicy ¶
RatePolicy is a trusted configuration snapshot, never model payload. Windows are fixed at 60 seconds (session/runtime) and 2 seconds (runtime burst). The whole-zero value selects defaults; individual zero values never disable a limiter. Enablement and configuration generation fencing belong to callers.
func (RatePolicy) Normalize ¶
func (p RatePolicy) Normalize() (RatePolicy, error)
Normalize validates a snapshot and resolves the backward-compatible default. Session and burst limits cannot exceed the enclosing runtime minute limit.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
func Initialize ¶
Initialize is setup-only, for an explicitly never-initialized private root. The registry must remember initialization outside caches. Normal consumers must use Open; missing expected state must never trigger Initialize.
func Open ¶
Open requires a complete existing namespace/journal/lock set. It never repairs or creates missing state, including when the entire expected root was lost.
func (*Store) Collect ¶
Collect never affects OS notifications or callbacks. Unavailable/regressed clocks freeze GC. The logical clock baseline is persisted even when frozen.
func (*Store) Finalize ¶
Finalize only changes status/reason/backend; original identity and decision are immutable. On any error after the effect the caller reports unknown and must not retry delivery. A completed token cannot be finalized twice.
func (*Store) FinalizeOutcome ¶
func (s *Store) FinalizeOutcome(ctx context.Context, k Key, attempt, status, reason, backend string, navigation *Navigation) error
FinalizeOutcome atomically records terminal navigation separately from the immutable admission. Nil preserves the legacy Finalize representation. This is draft unreleased v1 state: existing records remain readable, but old readers reject the optional field/new suppressed enum. Activation must fence older writers and rollback paths; never reset history or change namespace.
Source Files