vault

package
v2.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 2, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package vault implements store.ManifestStore over a directory tree: files are the source of truth. On open, it reads every <Kind>/*.yaml file, compares each file's SHA-256 against the hash recorded in the index (a store.VaultIndex the caller opens under .cartograph/), and appends new versions for any file that is new or changed, so ListVersions and diff keep working. An fsnotify watcher (when enabled) debounces file changes 200 ms and reloads them into memory and the index. Deleting .cartograph/ and reopening rebuilds an equivalent index with the same current versions (version numbers may restart at 1).

Index

Constants

View Source 
const (
	FailurePointNone           FailurePoint = iota // No failure
	FailurePointAfterJournal                = iota // After journal.PutUnit, before file writes
	FailurePointAfterFirstFile              = iota // After first file write, before vault.yaml
	FailurePointAfterLastFile               = iota // After vault.yaml write, before mark applied
)

Variables

This section is empty.

Functions

This section is empty.

Types

type FailurePoint 

type FailurePoint int

FailurePoint is used for testing: injects a failure at a specific point in applyUnit.

type ManifestStore 

type ManifestStore struct {
	// contains filtered or unexported fields
}

ManifestStore is a file-based vault adapter. Files in <vault>/<Kind>/<id>.yaml are the source of truth. The index beside them (a store.VaultIndex under .cartograph/) keeps versions, references and summaries.

func New 

func New(ctx context.Context, vaultDir string, opts Options) (*ManifestStore, error)

New opens a vault directory and the index opts.OpenIndex opens. On open, it scans every <Kind>/*.yaml file and records new or changed versions in the index. If opts.Watch is true, a debounced watcher tracks further file changes and reloads them into memory and the index (debounce interval defaults to 200 ms, or opts.Debounce if set). Call Close() to stop the watcher and close the index.

func (*ManifestStore) Apply 

func (m *ManifestStore) Apply(ctx context.Context, refs []string) (int, error)

Apply adds refs to vault.yaml in one write. Every ref must have a file on disk, or nothing is written and the first missing one is returned as a store.NotFoundError. Refs already included are quiet.

func (*ManifestStore) Close 

func (m *ManifestStore) Close() error

Close stops the watcher (if running) and closes the index.

func (*ManifestStore) Counts 

func (m *ManifestStore) Counts(ctx context.Context) (map[string]int, error)

Counts returns manifest counts from cache (file content) and index (versions).

func (*ManifestStore) CurrentMany added in v2.3.0 

func (m *ManifestStore) CurrentMany(ctx context.Context, kind string, ids []string) ([]store.Version, error)

CurrentMany returns the current version of each of ids that exists, from the vault's memory.

func (*ManifestStore) CurrentOfKind added in v2.3.0 

func (m *ManifestStore) CurrentOfKind(ctx context.Context, kind string) ([]store.Version, error)

CurrentOfKind returns the current version of every manifest of a kind, from the vault's memory.

func (*ManifestStore) DiscardWorking 

func (m *ManifestStore) DiscardWorking(ctx context.Context, kind, id string) error

DiscardWorking throws a draft away and puts back what the vault holds.

This is the operation that could not exist before staging: the working copy was the file, so there was nothing to go back to. Now there is — the vault's own file, untouched since the last save. A ref with no vault file was never saved at all, so discarding it leaves nothing, which is the honest answer rather than an empty manifest.

func (*ManifestStore) Events added in v2.3.0 

func (m *ManifestStore) Events(ctx context.Context, after int64, limit int) ([]store.Event, error)

Events asks the index.

func (*ManifestStore) Exclude 

func (m *ManifestStore) Exclude(ctx context.Context, kind, id, name, reason, operator string) error

Exclude removes a manifest from vault.yaml and records the exclusion.

func (*ManifestStore) GetCurrent 

func (m *ManifestStore) GetCurrent(ctx context.Context, kind, id string) (store.Version, bool, error)

GetCurrent returns the current version from the in-memory cache.

func (*ManifestStore) GetVersion 

func (m *ManifestStore) GetVersion(ctx context.Context, kind, id string, number int) (store.Version, bool, error)

GetVersion delegates to the index.

func (*ManifestStore) GetWorking 

func (m *ManifestStore) GetWorking(ctx context.Context, kind, id string) ([]byte, bool, error)

GetWorking returns a manifest's working copy (the file on disk). Returns found=false when no file exists.

func (*ManifestStore) Included 

func (m *ManifestStore) Included(ctx context.Context) ([]string, error)

Included returns vault.yaml's include list.

func (*ManifestStore) Index 

func (m *ManifestStore) Index() store.VaultIndex

Index returns the vault's index: versions, summaries, references, the apply journal, project state history and the rest of what a database holds beside the vault's files. Callers that need the operational store or the apply journal go through this rather than opening the index themselves.

func (*ManifestStore) IndexReferences 

func (m *ManifestStore) IndexReferences(ctx context.Context, fromKind, fromID string, refs []store.Ref) error

IndexReferences delegates to the index.

func (*ManifestStore) IndexStatus 

func (m *ManifestStore) IndexStatus(ctx context.Context) (rebuiltOn time.Time, staleCount int, err error)

IndexStatus returns information about the vault index: when it was last rebuilt and how many files are stale (have a different SHA-256 than recorded).

func (*ManifestStore) IndexWorking 

func (m *ManifestStore) IndexWorking(ctx context.Context, kind, id string, yamlBytes []byte) error

IndexWorking records a manifest in the index's working-copy table without staging anything.

Reindex needs this: it walks every current manifest on open so ListReferencing can resolve references, and it used to do that by calling PutWorking. That was harmless while PutWorking wrote the vault file the manifest had just been read from. Now PutWorking stages a draft, so the same call made opening a vault create a draft of every manifest in it — sixty-five of them in the example instance, none of them anybody's work.

So the two jobs PutWorking was doing are separated: staging what somebody is editing, and telling the index what exists.

func (*ManifestStore) LatestNumber added in v2.3.0 

func (m *ManifestStore) LatestNumber(ctx context.Context, kind, id string) (int, error)

LatestNumber asks the index for the highest version number.

func (*ManifestStore) ListAllVersions 

func (m *ManifestStore) ListAllVersions(ctx context.Context, limit int, cursor string) ([]store.Version, string, error)

ListAllVersions returns all versions of all manifests across kinds, newest first.

func (*ManifestStore) ListExcluded 

func (m *ManifestStore) ListExcluded(ctx context.Context) ([]store.Exclusion, error)

ListExcluded returns every excluded manifest, newest first.

func (*ManifestStore) ListIDs 

func (m *ManifestStore) ListIDs(ctx context.Context, kind string) ([]string, error)

ListIDs returns IDs from cache (file content) first, then from index (versions).

func (*ManifestStore) ListReferencedBy 

func (m *ManifestStore) ListReferencedBy(ctx context.Context, fromKind, fromID string) ([]store.Ref, error)

ListReferencedBy delegates to the index.

func (*ManifestStore) ListReferencing 

func (m *ManifestStore) ListReferencing(ctx context.Context, toKind, toID string) ([]store.Summary, error)

ListReferencing delegates to the index.

func (*ManifestStore) ListStaged 

func (m *ManifestStore) ListStaged(ctx context.Context) ([]StagedRef, error)

ListStaged returns every draft in the vault, so a caller can say what is unfinished without walking the directory itself. Sorted, because two runs listing the same drafts in a different order is a bug nobody wants to chase.

func (*ManifestStore) ListSummaries 

func (m *ManifestStore) ListSummaries(ctx context.Context, kind, query string, refs []store.RefFilter) ([]store.Summary, error)

ListSummaries returns summaries of all current versions of a kind.

func (*ManifestStore) ListUnapplied 

func (m *ManifestStore) ListUnapplied(ctx context.Context) ([]store.UnappliedRef, error)

ListUnapplied scans every <Kind>/<id>.yaml and returns the ones that vault.yaml does not include and no exclusion records.

func (*ManifestStore) ListVersions 

func (m *ManifestStore) ListVersions(ctx context.Context, kind, id string) ([]store.Version, error)

ListVersions delegates to the index.

func (*ManifestStore) Name 

func (m *ManifestStore) Name() string

Name is the state manifest's id: vault.yaml's metadata.id, or the directory's name until one is written.

func (*ManifestStore) PutBundle 

func (m *ManifestStore) PutBundle(_ context.Context, projectID string, version int, files map[string][]byte) (store.Bundle, error)

PutBundle writes a handoff bundle under .cartograph/handoff/<project>/v<n>, into a temporary directory first and renamed into place, so a crash leaves either the whole bundle or none of it.

func (*ManifestStore) PutVersion 

func (m *ManifestStore) PutVersion(ctx context.Context, v store.Version) error

PutVersion writes the manifest to disk at <vault>/<Kind>/<id>.yaml and appends a version to the index. If the file on disk has changed since it was last read (SHA-256 mismatch), returns *store.ConflictError.

func (*ManifestStore) PutWorking 

func (m *ManifestStore) PutWorking(ctx context.Context, kind, id string, yamlBytes []byte) error

PutWorking stages a draft. It does not touch the vault's own tree and does not add the ref to vault.yaml: an unfinished definition is not part of the vault, and autosave is not a decision to include something. See vault_staging.go for why.

If the id is excluded, returns a ConflictError with the exclusion reason.

func (*ManifestStore) RecordSeries added in v2.3.0 

func (m *ManifestStore) RecordSeries(ctx context.Context, items []store.SeriesItem) error

RecordSeries asks the index.

func (*ManifestStore) Recover 

func (m *ManifestStore) Recover(ctx context.Context, kind, id, reason, operator string) error

Recover re-adds an excluded manifest to vault.yaml.

func (*ManifestStore) ReferencingKind added in v2.3.0 

func (m *ManifestStore) ReferencingKind(ctx context.Context, toKind string) (map[string][]store.Summary, error)

ReferencingKind returns who references each manifest of toKind.

func (*ManifestStore) Rehydrate 

func (m *ManifestStore) Rehydrate(ctx context.Context) error

Rehydrate reloads the in-memory state from vault.yaml and included manifests. Used after applying a new manifest to load it into the cache immediately.

func (*ManifestStore) SeriesAsOf added in v2.3.0 

func (m *ManifestStore) SeriesAsOf(ctx context.Context, kind, series string, ids []string, at time.Time) (map[string][]store.SeriesItem, error)

SeriesAsOf asks the index.

func (*ManifestStore) SetFailurePoint 

func (m *ManifestStore) SetFailurePoint(fp FailurePoint)

SetFailurePoint sets the failure point for testing purposes. TEST ONLY.

func (*ManifestStore) StateYAML 

func (m *ManifestStore) StateYAML(context.Context) ([]byte, bool, error)

StateYAML returns vault.yaml's bytes as written on disk.

func (*ManifestStore) VaultDir 

func (m *ManifestStore) VaultDir() string

VaultDir returns the vault root directory.

func (*ManifestStore) WithinTransaction 

func (m *ManifestStore) WithinTransaction(ctx context.Context, fn func(ctx context.Context, tx store.ManifestStore) error) error

WithinTransaction runs fn against a transactional vault store that stages writes. When fn succeeds and the index transaction commits, staged files are written to disk and added to vault.yaml in one ApplyUnit (vault.yaml written last). If fn or the index commit fails, no files are written.

type Options 

type Options struct {
	Watch bool
	// Extension is the manifest files' extension with its dot, the
	// codec's; ".yaml" when empty. vault.yaml itself is always YAML: it
	// is the adapter's own file, not a manifest.
	Extension    string
	Debounce     time.Duration // Watcher debounce interval; 0 means use default 200ms
	FailurePoint FailurePoint  // TEST ONLY: inject a failure at this point in applyUnit
	// OpenIndex opens the index the vault keeps beside its files, given
	// the directory set aside for it (.cartograph). Required: which index
	// adapter a vault runs on is the composition root's choice, never
	// the vault's.
	OpenIndex func(ctx context.Context, dir string) (store.VaultIndex, error)
}

Options control how a vault is opened.

type StagedRef 

type StagedRef struct {
	Kind string
	ID   string
}

StagedRef is one draft waiting to be saved.

type VaultManifest 

type VaultManifest struct {
	APIVersion string        `yaml:"apiVersion"`
	Kind       string        `yaml:"kind"`
	Metadata   VaultMetadata `yaml:"metadata"`
	Spec       VaultSpec     `yaml:"spec"`
}

VaultManifest represents the vault.yaml file

type VaultMetadata 

type VaultMetadata struct {
	ID string `yaml:"id"`
}

type VaultSpec 

type VaultSpec struct {
	Include []string `yaml:"include"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.