filesystem

README

filesystem

A simple filesystem interface in Go

The filesystem package provides a unified interface to a real backed filesystem. An example use case for this might be a server that wants to provide CRUD access to a filesystem.

Here's an example of how you might use this package.

The first step is to create a Filesystemer object based on the absolute filesystem path you want to represent (using a provided constructor):

fs := NewPassThroughFilesystem('/my/abs/path', false)

At this point, all interaction with the Filesystemer should be relative to the root path. For example, to check if /my/abs/path/lower/dir exists, you'd do something like:

fs.PathExists('lower/dir') // false

If it did not exist, and you wanted to make a director there, you could do:

fs.MkPath('lower/dir')

If you wanted to then make a file in this path, you might do:

fileBytes, err := ioutil.ReadFile('/tmp/roflcopter.jpeg')
fs.MkFile('lower/dir/roflcopter.jpeg', fileBytes)

Then to retrieve the file, you'd do:

myFiler, err := fs.GetFile('lower/dir/roflcopter.jpeg')

To remove the newly created file, this would work:

fs.RmPath('lower/dir/roflcopter.jpeg')
// Alternatively, recursively delete the whole directory
// fs.RmPath('lower')

Documentation

Overview

The filesystem package provides a unified interface to a real backed filesystem. An example use case for this might be a server that wants to provide CRUD access to a filesystem.

Here's an example of how you might use this package. The first step is to create a Filesystemer object based on the absolute filesystem path you want to represent (using a provided constructor):

fs := NewPassThroughFilesystem('/my/abs/path', false)

At this point, all interaction with the Filesystemer should be relative to the root path. For example, to check if /my/abs/path/lower/dir exists, you'd do something like:

fs.PathExists('lower/dir') // false

If it did not exist, and you wanted to make a director there, you could do:

fs.MkPath('lower/dir')

If you wanted to then make a file in this path, you might do:

fileBytes, err := ioutil.ReadFile('/tmp/roflcopter.jpeg')
fs.MkFile('lower/dir/roflcopter.jpeg', fileBytes)

Then to retrieve the file, you'd do:

myFiler, err := fs.GetFile('lower/dir/roflcopter.jpeg')

To remove the newly created file, this would work:

fs.RmPath('lower/dir/roflcopter.jpeg')
// Alternatively, recursively delete the whole directory
// fs.RmPath('lower')

Index

• Variables
• type FSFile
  • func (fsfile *FSFile) AbsPath() string
  • func (fsfile *FSFile) File() ([]byte, error)
• type FSFiler
• type Filesystemer
• type PassThroughFilesystem
  • func NewPassThroughFilesystem(absPath string, create bool) (*PassThroughFilesystem, error)
  • func (fs *PassThroughFilesystem) GetFile(path string) (FSFiler, error)
  • func (fs *PassThroughFilesystem) MkFile(path string, content []byte) error
  • func (fs *PassThroughFilesystem) MkPath(path string) error
  • func (fs *PassThroughFilesystem) PathExists(path string) bool
  • func (fs *PassThroughFilesystem) RmPath(path string) error
  • func (fs *PassThroughFilesystem) RootPath() string
• type TransientFilesystem
  • func NewTransientFilesystem(absPath string, create bool) (*TransientFilesystem, error)
  • func (fs *TransientFilesystem) GetFile(path string) (FSFiler, error)
  • func (fs *TransientFilesystem) MkFile(path string, content []byte) error
  • func (fs *TransientFilesystem) MkPath(path string) error
  • func (fs *TransientFilesystem) PathExists(path string) bool
  • func (fs *TransientFilesystem) RmPath(path string) error
  • func (fs *TransientFilesystem) RootPath() string
  • func (fs *TransientFilesystem) Sync() error
• type TransientFilesystemer

Variables

var (
	ErrFileNoExist     = errors.New("file does not exist")
	ErrPathNoExist     = errors.New("path does not exist")
	ErrFileExists      = errors.New("file already exists")
	ErrPathNotAbsolute = errors.New("path is not absolute")
)

Types

type FSFile

type FSFile struct {
	os.FileInfo
	// contains filtered or unexported fields
}

A FSFile object contains all the information that you would normally find in a os.FileInfo object, plus the file itself in a byte slice.

func (*FSFile) AbsPath

func (fsfile *FSFile) AbsPath() string

AbsPath returns the absolute path of the file on the filesystem

func (*FSFile) File

func (fsfile *FSFile) File() ([]byte, error)

File returns the file stored in a FSFile

type FSFiler

type FSFiler interface {
	os.FileInfo
	File() ([]byte, error)
	AbsPath() string
}

FSFiler knows everything that a normal os.FileInfo does, but it also has access to the underlying file.

type Filesystemer

type Filesystemer interface {
	//ArbitraryAction()
	PathExists(path string) bool
	MkPath(path string) error
	RmPath(path string) error // Applies to both paths + files
	MkFile(path string, content []byte) error
	GetFile(path string) (FSFiler, error)
	RootPath() string
}

Filesystemer is the base interface that any filesystem should implement.

type PassThroughFilesystem

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

A passthrough file system doesn't have an internal representation of the actual filesystem - it is merely a proxy to the actual filesystem. The penalty of disk access is paid, but it is never out of sync with the actual contents of the filesystem. This implementation does not currently deal with file permissions. That is, to say, files/direcories created via this implementation will be subject to ownership/permissions rules enforced by the kernel. If you want to be able to set custom ownership or permissions, provide your own implementation.

func NewPassThroughFilesystem

func NewPassThroughFilesystem(absPath string, create bool) (*PassThroughFilesystem, error)

Create a new PassThroughFileSystem, given an absolute path to a directory. Will fail if the given path is inaccessible for any reason (including its inexistence), or if the path is not a directory. If create is true, then the directory will be created if it does not yet exist.

func (*PassThroughFilesystem) GetFile

func (fs *PassThroughFilesystem) GetFile(path string) (FSFiler, error)

GetFile gets the file at path and returns a FSFile object, which both describes the file and has a pointer to a copy of the file in a byte slice. If the files does not exist or path is actually a directory, an error is returned.

func (*PassThroughFilesystem) MkFile

func (fs *PassThroughFilesystem) MkFile(path string, content []byte) error

MkFile makes a file consisting of the provided content at the given path. If the path does not already exist, an error will be returned. If the file already exists, an error will be returned.

func (*PassThroughFilesystem) MkPath

func (fs *PassThroughFilesystem) MkPath(path string) error

MkPath makes a new directory under the current rootPath. The path variable is expected to be relative to the rootPath. Returns nil if the path already exists as a dir, and an error if the path already exists and is a file.

func (*PassThroughFilesystem) PathExists

func (fs *PassThroughFilesystem) PathExists(path string) bool

PathExists checks to see that the given path exists. The path argument is expected to be relative to the rootPath of the PassThroughFilesystem. Works for files and directories.

func (*PassThroughFilesystem) RmPath

func (fs *PassThroughFilesystem) RmPath(path string) error

RmPath recursively removes a path from the filesystem. The path argument can be either a file or directory relative to the rootPath. Returns an error if the path does not exist, or if there was an error removing part of the path.

func (*PassThroughFilesystem) RootPath

func (fs *PassThroughFilesystem) RootPath() string

RootPath returns the real absolute path of the filesystem

type TransientFilesystem

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

A transient filesystem has an in-memory representation of an underlying filesystem, for fast access. The in-memory structure will be updated when paths are added via the object. When the filesystem is changed outside of this API, Sync() should be called to bring the in-memory representation and actual disk contents back into sync.

func NewTransientFilesystem

func NewTransientFilesystem(absPath string, create bool) (*TransientFilesystem, error)

NewTransientFilesystem returns a new TransientFilesystem. Expects an absolute path to the location on disk. Returns an error if the path cannot be created, or if a file already exists in that location. If create is true, then the directory will be created if it does not yet exist.

func (*TransientFilesystem) GetFile

func (fs *TransientFilesystem) GetFile(path string) (FSFiler, error)

GetFile gets the file at path and returns a FSFiler object, which both describes the file and has a pointer to a copy of the file in a byte slice. If the files does not exist or path is actually a directory, an error is returned.

func (*TransientFilesystem) MkFile

func (fs *TransientFilesystem) MkFile(path string, content []byte) error

MkFile makes a file consisting of the provided content at the given path. If the path does not already exist, an error will be returned. If the file already exists, an error will be returned.

func (*TransientFilesystem) MkPath

func (fs *TransientFilesystem) MkPath(path string) error

MkPath makes a new directory under the current rootPath. The path variable is expected to be relative to the rootPath. The diectory will both be added to the internal representation AND be added to the real filesystem. Fails if the specified path is a file, returns nil if the specified path already exists.

func (*TransientFilesystem) PathExists

func (fs *TransientFilesystem) PathExists(path string) bool

PathExists checks to see that the given path exists. The path argument is expected to be relative to the rootPath of the TransientFilesystem. Works for files and directories.

func (*TransientFilesystem) RmPath

func (fs *TransientFilesystem) RmPath(path string) error

RmPath recursively removes a path from the filesystem. The path argument can be either a file or directory relative to the rootPath. Returns an error if the path does not exist, or if there was an error removing part of the path.

func (*TransientFilesystem) RootPath

func (fs *TransientFilesystem) RootPath() string

RootPath returns the real absolute path of the filesystem

func (*TransientFilesystem) Sync

func (fs *TransientFilesystem) Sync() error

Sync brings the in-memory struct and underlying file system into sync. Walk the entire tree and recreate it from scratch.

type TransientFilesystemer

type TransientFilesystemer interface {
	Filesystemer
	Sync() error
}

A TransientFilesystemer represents an in-memory representation of a filesystem.