Store

Documentation

Overview

Package Store provides a content-addressed directory store over one vfs.Fs.

Index

• Constants
• Variables
• func BuildDirPresent(srcFS vfs.Fs, path string) bool
• func EnsureBuildRootAt(bldRoot string)
• func EnsureRootWithTag(fsys vfs.Fs, tagComment string)
• func IsReservedName(name string) bool
• func Nuke(bldRoot string, allowedFiles ...string)
• func NukeDir(friendlyName, dir string, owned func(e fs.FileInfo) bool)
• func OSConfigExists(path string) bool
• func VFSConfigExists(fs vfs.Fs, path string) bool
• func VirtualConfigPathForDir(srcDir string) string
• func VirtualSuffix(name string) string
• type CheckStats
  • func (st CheckStats) HasProblems() bool
• type GCStats
• type PublishPlan
• type Store
  • func NewStore(fs vfs.Fs) *Store
  • func (s *Store) Check(out io.Writer, fix bool, allowedFiles ...string) CheckStats
  • func (s *Store) Contains(root, hash string) bool
  • func (s *Store) CopyFileIn(srcFs vfs.Fs, srcPath, dstPath string)
  • func (s *Store) EmptyCacheDirs(out io.Writer) (emptied int)
  • func (s *Store) EnsureCacheDir(path string) string
  • func (s *Store) GC(srcPresent func(path string) bool, reportFreedSpace bool) GCStats
  • func (s *Store) GetDirtySkipHash(path string) string
  • func (s *Store) GetLinkTarget(root, name string) string
  • func (s *Store) HashSrc(srcFs vfs.Fs, dir string, filter *FilterFiles.Filter, allowLinks bool) string
  • func (s *Store) Link(root, name, hash string) (prev string)
  • func (s *Store) LinkPath(root, path, hash string)
  • func (s *Store) MakeBuildSubdir(dir string)
  • func (s *Store) MoveStore(root string, srcDir string, plan PublishPlan) string
  • func (s *Store) Restore(root, hash, dstDir string)
  • func (s *Store) RestoreLink(root, hash, dstDir string)
  • func (s *Store) SetDirtySkipHash(path, skipHash string)
  • func (s *Store) SrcPrep(srcFs vfs.Fs, srcDir string, filter *FilterFiles.Filter, allowLinks bool) string
  • func (s *Store) SrcPrepEmpty(srcDir string) string
  • func (s *Store) Store(root string, srcFs vfs.Fs, srcDir string, pruneNested bool, ...) string
  • func (s *Store) StoreAsHash(root string, srcFs vfs.Fs, srcDir string, pruneNested bool, ...)

Constants

const (
	InRoot         = "in"
	OutRoot        = "out"
	BldSandboxRoot = "bld"
	DirtyRoot      = "dirty"
	TmpRoot        = "tmp"
	UserRoot       = "user"

	BuildConfigName = "BUFA"

	// A shell provider's published definition, beside its binary. Outside the reserved
	// BUFA/*.BUFA namespace on purpose: it stages and publishes like any source file.
	ShellDefFileName = BuildConfigName + ".shell"

	// A bld dep's published env exports, at its output root. Outside the reserved namespace
	// like BUFA.shell, for the same reason.
	EnvFileName = BuildConfigName + ".env"

	// Appended to the source root's path to form its sibling build dir: C:\Proj -> C:\Proj.BUFA
	BuildRootDirSuffix = "." + BuildConfigName

	// The source-root marker file: detects the project root and holds the root config — nothing
	// else. The bare (empty-suffix) member of the *.BUFA namespace, so no dir can declare a
	// virtual config colliding with it.
	SrcRootFileName = "." + BuildConfigName

	// Appended to a dir's base name to form the virtual config declaring it: clj.BUFA -> virtual
	// build dir clj. The three constants above are distinct naming choices whose values coincide.
	VirtualConfigSuffix = "." + BuildConfigName

	// source-root marker; a dir or a file (worktrees and submodules mark with a file)
	GitRootMarker = ".git"
)

const CacheDirTagName = "CACHEDIR.TAG"

const PathLinkPrefix = "∕"

Variables

var AllowBufaDir = false

A BUFA-named directory is ordinary content, not the reserved-name violation. Build sets it once from the root marker's allowBufaDir. A package var, not a parameter: the flag is almost never used (building bufa itself), not worth threading through every walk signature.

Functions

func BuildDirPresent

func BuildDirPresent(srcFS vfs.Fs, path string) bool

func EnsureBuildRootAt

func EnsureBuildRootAt(bldRoot string)

func EnsureRootWithTag

func EnsureRootWithTag(fsys vfs.Fs, tagComment string)

EnsureRootWithTag creates fsys's root dir and tags it iff this call created it.

func IsReservedName

func IsReservedName(name string) bool

func Nuke

func Nuke(bldRoot string, allowedFiles ...string)

func NukeDir

func NukeDir(friendlyName, dir string, owned func(e fs.FileInfo) bool)

NukeDir deletes dir entirely, but only after owned admits every entry; anything else refuses the whole operation, naming the offenders (dirs with a trailing '/'). A missing dir is a no-op.

func OSConfigExists

func OSConfigExists(path string) bool

func VFSConfigExists

func VFSConfigExists(fs vfs.Fs, path string) bool

func VirtualConfigPathForDir

func VirtualConfigPathForDir(srcDir string) string

func VirtualSuffix

func VirtualSuffix(name string) string

Types

type CheckStats

type CheckStats struct {
	CheckedContent    int // D<hash> content dirs re-hashed
	CheckedLinks      int // ∕<path> and B<combined> index links resolved
	CorruptContent    int // D entries whose content hash mismatches the name
	BadLinks          int // index links that dangle or target the wrong kind of entry
	UnexpectedEntries int // names with no valid prefix, or wrong-kind squatters on index-link / cache-dir names
	RemovedEntries    int // entries deleted (fix mode only)
}

func (CheckStats) HasProblems

func (st CheckStats) HasProblems() bool

type GCStats

type GCStats struct {
	StalePathLinks       int // ∕<path> links whose source dir is gone / no longer a build dir
	OrphanContent        int // D<hash> content dirs nothing live references
	OrphanBuildLinks     int // out/ B<combined> input links with no surviving ∕<path> roots
	StaleDirtySkipHashes int // dirty/ ∕<path> skip hashes whose source dir is no longer a build dir
	OrphanCacheDirs      int // user/ P<hash> cache dirs no surviving ∕<path> link references
	LeftoverScratchDirs  int // bld/ and tmp/ dirs a failed or interrupted build left behind
	BytesFreed           uint64
}

type PublishPlan

type PublishPlan struct {
	// acts on files and links by their own srcDir-relative path, never on dirs
	Filter *FilterFiles.Filter
	// deleted kind-blind; unmatched keys are harmless
	PruneDirs, ExtPrune Util.Set[string]
	// the only links a safe-mode publish admits; AllowLinks waives the policy
	KeepLinks  Util.Set[string]
	AllowLinks bool
}

type Store

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

func NewStore

func NewStore(fs vfs.Fs) *Store

func (*Store) Check

func (s *Store) Check(out io.Writer, fix bool, allowedFiles ...string) CheckStats

cmd/bufa passes every fix run unconditionally: whatever is reported here MUST be removed under fix.

func (*Store) Contains

func (s *Store) Contains(root, hash string) bool

func (*Store) CopyFileIn

func (s *Store) CopyFileIn(srcFs vfs.Fs, srcPath, dstPath string)

func (*Store) EmptyCacheDirs

func (s *Store) EmptyCacheDirs(out io.Writer) (emptied int)

Keeps the P… dirs and ∕ links themselves; any other name is reported and left untouched.

func (*Store) EnsureCacheDir

func (s *Store) EnsureCacheDir(path string) string

func (*Store) GC

func (s *Store) GC(srcPresent func(path string) bool, reportFreedSpace bool) GCStats

Over-collection is self-healing: anything wrongly collected is re-staged or re-built on the next build.

func (*Store) GetDirtySkipHash

func (s *Store) GetDirtySkipHash(path string) string

func (*Store) GetLinkTarget

func (s *Store) GetLinkTarget(root, name string) string

A single Readlink does the work — a separate Lstat probe would double the OS file opens on Windows for no extra signal.

func (*Store) HashSrc

func (s *Store) HashSrc(srcFs vfs.Fs, dir string, filter *FilterFiles.Filter, allowLinks bool) string

func (*Store) Link

func (s *Store) Link(root, name, hash string) (prev string)

func (*Store) LinkPath

func (s *Store) LinkPath(root, path, hash string)

func (*Store) MakeBuildSubdir

func (s *Store) MakeBuildSubdir(dir string)

The only way a build subdir comes to exist: a bare MkdirAll would mint the root untagged.

func (*Store) MoveStore

func (s *Store) MoveStore(root string, srcDir string, plan PublishPlan) string

Scan is read-only and runs to completion before apply mutates, so a failed publish leaves the kept-for-debug sandbox exactly as the script left it.

func (*Store) Restore

func (s *Store) Restore(root, hash, dstDir string)

func (*Store) RestoreLink

func (s *Store) RestoreLink(root, hash, dstDir string)

dstDir must not exist: os.Symlink refuses an existing name, so Restore's empty-destination invariant is self-enforcing here.

func (*Store) SetDirtySkipHash

func (s *Store) SetDirtySkipHash(path, skipHash string)

func (*Store) SrcPrep

func (s *Store) SrcPrep(srcFs vfs.Fs, srcDir string, filter *FilterFiles.Filter, allowLinks bool) string

func (*Store) SrcPrepEmpty

func (s *Store) SrcPrepEmpty(srcDir string) string

func (*Store) Store

func (s *Store) Store(root string, srcFs vfs.Fs, srcDir string, pruneNested bool,
	filter *FilterFiles.Filter, allowLinks bool,
) string

func (*Store) StoreAsHash

func (s *Store) StoreAsHash(root string, srcFs vfs.Fs, srcDir string, pruneNested bool,
	filter *FilterFiles.Filter, allowLinks bool, hash string,
)