Documentation
¶
Overview ¶
Package secrets assembles a namespace's secrets from the objects a backend holds for it: an append-only set of per-write segments over zero or more folded snapshots. Each write appends a new, uniquely named segment, so concurrent writers never overwrite one another. Reads fold the snapshots and segments together by a Lamport clock — last write per key wins, ties between machines are reported as conflicts. Compaction collapses what it reads into a fresh snapshot and deletes the objects it folded.
Every object is one age message sealed under the master key, and every object is bound to the vault's authenticated header by a manifest entry (a keyed MAC of its plaintext — see internal/crypto). A fold trusts the manifest, not the storage listing: a manifest-listed object that is missing, altered, or relocated is an alarm, and an object the manifest does not know is folded in only when it can be nothing but an honest in-flight write.
Index ¶
- Constants
- func Exists(ctx context.Context, store backend.Backend, name string) (bool, error)
- func UpgradeObjects(ctx context.Context, store backend.Backend, mk *crypto.MasterKey) (map[string]crypto.ManifestEntry, error)
- type Conflict
- type Namespace
- func (n *Namespace) Append(ctx context.Context, prev *State, seq int, key, value string, deleted bool) (*State, string, crypto.ManifestEntry, error)
- func (n *Namespace) Compact(ctx context.Context, commit func(crypto.ManifestDelta) error) error
- func (n *Namespace) Fold(ctx context.Context) (*State, error)
- type State
Constants ¶
const DefaultCompactThreshold = 16
DefaultCompactThreshold is the segment count at or above which a write triggers automatic compaction. It bounds the objects a cold read folds, so reads stay fast without anyone running `notenv compact` by hand.
Variables ¶
This section is empty.
Functions ¶
func Exists ¶
Exists reports whether a namespace has any stored object yet. It only lists, so it needs no master key.
func UpgradeObjects ¶ added in v0.8.0
func UpgradeObjects(ctx context.Context, store backend.Backend, mk *crypto.MasterKey) (map[string]crypto.ManifestEntry, error)
UpgradeObjects rewrites every payload object in the vault to the current format under mk — stamping each with the object key it lives under — and returns the manifest entries that record them. It is the one reader that accepts the previous payload format, used by `notenv key migrate`; normal reads reject anything but the current format. Idempotent: a re-run after a partial failure rewrites already-upgraded objects to the same bytes.
Types ¶
type Conflict ¶
Conflict reports a key written concurrently on more than one machine (equal Lamport). Winner's value is the one kept; the others are shadowed but remain recoverable from their segments until the next compaction.
type Namespace ¶
type Namespace struct {
// contains filtered or unexported fields
}
Namespace reads and writes one namespace's secrets through a backend, sealing every object under master. machine identifies and orders this machine's writes so two machines never produce the same segment. manifest is the verified header's object manifest; folds check every object against it.
func For ¶
func For(store backend.Backend, name string, master *crypto.MasterKey, machine string, manifest map[string]crypto.ManifestEntry) *Namespace
For binds a namespace to a backend, master key, and the verified header's manifest.
func (*Namespace) Append ¶
func (n *Namespace) Append(ctx context.Context, prev *State, seq int, key, value string, deleted bool) (*State, string, crypto.ManifestEntry, error)
Append writes one key change as a new segment and returns the resulting state, the object key the segment landed under (so the caller can remove the write again if recording it in the manifest fails), and the manifest entry that records it. prev is the fold this write builds on; its Lamport sets the new clock.
func (*Namespace) Compact ¶
Compact folds the namespace into a single fresh snapshot and removes the objects it folded, adopting any in-flight writes it found along the way. It writes the new snapshot before deleting anything and only deletes objects it read, so a write that lands concurrently — under a name it never listed — is never lost.
commit makes the snapshot authoritative: it must apply the given manifest delta to the vault header (under the compare-and-swap, which also confirms the master this compaction sealed with is still the vault's master). If it errors, Compact removes its own snapshot and returns with the namespace untouched. After the subsumed objects are deleted, commit is called once more, best-effort, to prune their now-pointless entries.
type State ¶
type State struct {
Secrets map[string]string
Conflicts []Conflict
// Adoptable lists objects the fold trusted as honest in-flight writes (see
// classify) but the manifest does not record yet, with the entries a writer
// should add to adopt them.
Adoptable map[string]crypto.ManifestEntry
// Prunable lists manifest entries marked folded whose objects are confirmed
// gone; any writer may drop them.
Prunable []string
// Strays lists unknown snapshots the fold ignored (a compaction that crashed
// between writing its snapshot and recording it); `notenv compact` removes
// them.
Strays []string
// contains filtered or unexported fields
}
State is a folded namespace: the resolved secrets and any same-key conflicts detected during the fold. lamport is the highest Lamport folded, the basis for the next write's clock; segments is how many segment objects it folded.
func (*State) HasHistory ¶
HasHistory reports whether any write has ever been folded into this state; false means the namespace is untouched (distinct from one emptied by deletes).
func (*State) SegmentCount ¶
SegmentCount is how many uncompacted segment objects this fold read, the signal a caller uses to decide whether the next write should compact.
Source Files