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 App
  • func (d *App) Component(typ, name string) (*Component, error)
• type Component
• type Dir
  • func NewBasicDir(cacheDir, dataDir string) Dir
  • func NewScopedDir(parent Dir, path string) (Dir, error)
  • func TestDir(t testing.T) (Dir, func())
• type Project
  • func NewProject(path string) (*Project, error)
  • func (p *Project) App(name string) (*App, error)

Types

type App

type App struct {
	Dir
}

App is an implementation of Dir that encapsulates the directories for a single app.

func (*App) Component

func (d *App) Component(typ, name string) (*Component, error)

Component returns a Dir implementation scoped to a specific component.

type Component

type Component struct {
	Dir
}

Component is an implementation of Dir that encapsulates the directories for a single app.

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() string

	// DataDir returns the path to a folder that can be used for data
	// that is persisted between runs.
	DataDir() string
}

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

func NewBasicDir

func NewBasicDir(cacheDir, dataDir string) Dir

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

func NewScopedDir

func NewScopedDir(parent Dir, path 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 NewProject

func NewProject(path string) (*Project, error)

NewProject creates the directory structure for a project. This will create the physical directories on disk if they do not already exist.

func (*Project) App

func (p *Project) App(name string) (*App, error)

App returns the Dir implementation scoped to a specific app.