Documentation
¶
Overview ¶
Package leasefixture plants set-authority lease artifacts and snapshots them, so every layer that observes a lease drives the SAME invalid-artifact matrix.
The substrate probe/reclaim, the pkg/indexcoord coordination wrapper, and the CLI list/reap adapters each classify these artifacts independently. Three hand-written copies of the matrix would drift, and a mapping bug in one layer could then survive with the other two still green — which is precisely the class of gap this package exists to close. The row list here is the single source of truth for what "an artifact that must never be reclaimed" means.
Artifacts are written as raw bytes against the on-disk wire contract (the doc type string is spelled out rather than imported) so a fixture stays honest if a constant is renamed: the file on disk is what every layer actually reads.
Test-support only. It lives under internal/ and is imported solely by _test.go files; nothing here is part of the product surface.
Index ¶
Constants ¶
const DocType = "gonimbus.index.set_authority.v1"
DocType is the on-disk set-authority doc type. Spelled out deliberately: the fixture pins the wire contract, not whatever an internal constant happens to hold.
const NonCanonicalName = "not-an-idx"
NonCanonicalName is a path-safe lease name that is not a canonical index-set ID. It is the sole defect in its row.
Variables ¶
This section is empty.
Functions ¶
func AssertUnchanged ¶
AssertUnchanged reports the first difference between the snapshot and the artifact as it stands now, or nil when nothing moved.
func FullID ¶
FullID returns a canonical index-set ID — the literal prefix "idx_" followed by 64 lowercase hex digits — keyed by a single hex seed so tests can mint several distinct valid IDs deterministically.
func UppercaseID ¶
func UppercaseID() string
UppercaseID returns an "idx_" name whose 64 hex digits are uppercase. Canonical Gonimbus IDs are lowercase, so this is a non-canonical name that is nonetheless path-safe and hex-decodable — the exact shape that slipped past a hex-decoding gate.
Types ¶
type Planted ¶
type Planted struct {
// Path is the lease artifact (file, directory, or symlink). Empty when the
// row plants no artifact at all.
Path string
// External is a file OUTSIDE the lease artifact that must remain untouched —
// a symlink's target. Empty when the row has none.
External string
}
Planted describes what a row put on disk.
func PlantValidUnheld ¶
PlantValidUnheld writes a well-formed authority doc for id: the positive control every layer must still reclaim.
func PlantValidUnheldAs ¶
PlantValidUnheldAs is PlantValidUnheld with a caller-chosen holder string, for tests that drive attribution (the job-record join) rather than the verdict.
Planting is how unheld residue is produced above the substrate: an owner that completes now removes its own lease, so an acquire/release pair leaves nothing behind. Real residue comes from a holder that died without running any cleanup, and what that leaves on disk is exactly this file. The substrate's own tests reproduce it with a real killed child; layers above assert classification and reporting, for which the artifact is the input that matters.
type Row ¶
type Row struct {
// Name is the subtest name; identical across layers so a matrix gap is
// obvious when comparing test output.
Name string
// TargetID is the ID a caller probes/reclaims with. Empty means "the
// canonical ID the row was planted for".
TargetID string
// NeedsSymlink marks rows a platform may not support.
NeedsSymlink bool
// Plant writes the artifact under authorityRoot for the canonical id.
Plant func(authorityRoot, id string) (Planted, error)
}
Row is one artifact class that every layer must classify as invalid and must never reclaim.
func InvalidRows ¶
func InvalidRows() []Row
InvalidRows is the canonical matrix: every artifact class that must classify invalid (or skipped) and must survive unchanged at every layer.
Rows split into three kinds, all of which must reach the same verdict:
- doc-content rows: a correctly-named lock whose doc is wrong
- name rows: a target ID that is not a canonical lease name at all
- non-regular rows: a lock pathname that is not a regular file
SINGLE DEFECT PER ROW is a hard invariant here. Everything about a row except the one property it is named for must be valid, or the row can stay green off an unrelated gate and prove nothing — which is exactly how an earlier revision of the non-canonical row (planted with a malformed body) went hollow.
The non-regular rows are the deliberate exception to reading a row as evidence about one gate: a directory or symlink lock is independently rejected by the explicit artifact-type check, by rooted path resolution refusing to traverse a symlink, and by the under-lock binding check. That redundancy is defense in depth, so those rows assert the outcome rather than any single gate.
type Snapshot ¶
type Snapshot struct {
Path string
Exists bool
Mode os.FileMode
Size int64
ModTime time.Time
Content []byte // regular files only
LinkDest string // symlinks only
}
Snapshot records everything about an artifact that a mutation would disturb. It uses Lstat throughout, so a symlink is captured as the link itself.
func TakeSnapshot ¶
TakeSnapshot captures the artifact at path. A missing path is captured as Exists=false, so "it must stay missing" is assertable too.
Source Files