datadir

Documentation

Overview

Package datadir manages the data directories. This includes persisted data such as state as well as ephemeral data such as cache and runtime files.

This package is aware of the data model presented and provides easy helpers to create app-specific, component-specific, etc. data directories.

This package is the result of lessons learned from reimplementing "data directories" for projects such as Vagrant and Terraform. Those projects managed a list of directories directly in the CLI, forcing a lot of code to be aware of paths and making it hard to implement operations on those paths such as pruning, migration, compression, etc. As an evolution, we create the "datadir" package which has deep knowledge of the software data model and consumers interact using higher level APIs rather than direct filesystem manipulation. This gives us more room to introduce improvements in the future that broadly impact the application without having to make those changes in many places.

Index

• type Basis
  • func NewBasis(ident string) (*Basis, error)
  • func (p *Basis) Project(ident string) (*Project, error)
• type Component
• type Dir
  • func NewBasicDir(configDir, cacheDir, dataDir, tempDir string) Dir
  • func NewScopedDir(parent Dir, ident string) (Dir, error)
  • func TestDir(t testing.T) (Dir, func())
• type Project
  • func (p *Project) Target(ident string) (*Target, error)
• type Target
  • func (m *Target) Component(typ, name string) (*Component, error)
  • func (p *Target) Target(name string) (*Target, error)

Types

type Basis

type Basis struct {
	Dir
}

func NewBasis

func NewBasis(ident string) (*Basis, error)

func (*Basis) Project

func (p *Basis) Project(ident string) (*Project, error)

Project returns the Dir implementation scoped to a specific project.

type Component

type Component struct {
	Dir
}

Component is an implementation of Dir that encapsulates the directories for a specific component

type Dir

type Dir interface {
	// CacheDir returns the path to a folder that can be used for
	// cache data. This directory may not be empty if a previous run
	// stored data, but it may also be emptied at any time between runs.
	CacheDir() path.Path

	// DataDir returns the path to a folder that can be used for data
	// storage
	DataDir() path.Path

	// ConfigDir is the path to a folder that can be used for storing
	// configuration type information.
	ConfigDir() path.Path

	// TempDir returns the path to a folder that can be used for temporary
	// data storage. Directory is routinely cleaned.
	TempDir() path.Path
}

Dir is the interface implemented so that consumers can store data locally in a consistent way.

func NewBasicDir

func NewBasicDir(configDir, cacheDir, dataDir, tempDir string) Dir

NewBasicDir creates a Dir implementation with a manually specified set of directories.

func NewScopedDir

func NewScopedDir(parent Dir, ident string) (Dir, error)

NewScopedDir creates a ScopedDir for the given parent at the relative child path of path. The caller should take care that multiple scoped dirs with overlapping paths are not created, since they could still collide.

func TestDir

func TestDir(t testing.T) (Dir, func())

TestDir returns a Dir for testing.

type Project

type Project struct {
	Dir
}

Project is an implementation of Dir that encapsulates the directory for an entire project, including multiple apps.

The paths returned by the Dir interface functions will be project-global. This means that the data is shared by all applications in the project.

func (*Project) Target

func (p *Project) Target(ident string) (*Target, error)

Target returns the Dir implementation scoped to a specific target.

type Target

type Target struct {
	Dir
}

Target is an implementation of Dir that encapsulates the directories for a single target.

func (*Target) Component

func (m *Target) Component(typ, name string) (*Component, error)

Component returns a Dir implementation scoped to a specific component.

func (*Target) Target

func (p *Target) Target(name string) (*Target, error)

Target returns the Dir implementation scoped to a specific subtarget.