memphis

README

Memphis

Status: Minimum Viable

Memphis is a virtual (memory) file system for golang. It provides the same functionality (and is meant to be used as) a backing store for billy, rio, and others.

Memphis stores can also be generated from on-disk directory trees. File contents of unmodified files will be read from disk, while write requests to a file will transition them to in-memory content buffers.

License

SPDX-License-Identifier: Apache-2.0

Documentation

Index

• Constants
• Variables
• type Billy
  • func (b *Billy) Capabilities() billy.Capability
  • func (b *Billy) Chmod(name string, mode os.FileMode) error
  • func (b *Billy) Chown(name string, uid, gid int) error
  • func (b *Billy) Chroot(path string) (billy.Filesystem, error)
  • func (b *Billy) Chtimes(name string, atime time.Time, mtime time.Time) error
  • func (b *Billy) Create(filename string) (billy.File, error)
  • func (b *Billy) Join(elem ...string) string
  • func (b *Billy) Lchown(name string, uid, gid int) error
  • func (b *Billy) Lstat(filename string) (os.FileInfo, error)
  • func (b *Billy) MkdirAll(filename string, perm os.FileMode) error
  • func (b *Billy) Open(filename string) (billy.File, error)
  • func (b *Billy) OpenFile(filename string, flag int, perm os.FileMode) (billy.File, error)
  • func (b *Billy) ReadDir(path string) ([]os.FileInfo, error)
  • func (b *Billy) Readlink(link string) (string, error)
  • func (b *Billy) Remove(filename string) error
  • func (b *Billy) Rename(oldpath, newpath string) error
  • func (b *Billy) Root() string
  • func (b *Billy) Stat(filename string) (os.FileInfo, error)
  • func (b *Billy) Symlink(target, link string) error
  • func (b *Billy) TempFile(dir, prefix string) (billy.File, error)
• type BillyFile
  • func (bf *BillyFile) Close() error
  • func (bf *BillyFile) Lock() error
  • func (bf *BillyFile) Read(buf []byte) (n int, err error)
  • func (bf *BillyFile) ReadAt(buf []byte, offset int64) (n int, err error)
  • func (bf *BillyFile) Seek(offset int64, whence int) (int64, error)
  • func (bf *BillyFile) Truncate(size int64) error
  • func (bf *BillyFile) Unlock() error
  • func (bf *BillyFile) Write(buf []byte) (n int, err error)
  • func (bf *BillyFile) WriteAt(buf []byte, offset int64) (n int, err error)
• type DirMeta
  • func (d *DirMeta) IsDir() bool
  • func (d *DirMeta) ModTime() time.Time
  • func (d *DirMeta) Mode() os.FileMode
  • func (d *DirMeta) Name() string
  • func (d *DirMeta) Size() int64
  • func (d *DirMeta) Sys() interface{}
• type File
  • func FileFromOS(path string, uid, gid uint32, info os.FileInfo) *File
  • func (f *File) Bytes() []byte
  • func (f *File) IsDir() bool
  • func (f *File) ModTime() time.Time
  • func (f *File) Mode() os.FileMode
  • func (f *File) Name() string
  • func (f *File) Size() int64
  • func (f *File) Sys() interface{}
• type FileContent
  • func MemBufferFrom(fc FileContent) FileContent
  • func NewEmptyFileContents() FileContent
• type Placer
  • func (p *Placer) BasePath() fs.AbsolutePath
  • func (p *Placer) Chmod(path fs.RelPath, perms fs.Perms) error
  • func (p *Placer) LStat(path fs.RelPath) (*fs.Metadata, error)
  • func (p *Placer) Lchown(path fs.RelPath, uid uint32, gid uint32) error
  • func (p *Placer) MkdevBlock(path fs.RelPath, major int64, minor int64, perms fs.Perms) error
  • func (p *Placer) MkdevChar(path fs.RelPath, major int64, minor int64, perms fs.Perms) error
  • func (p *Placer) Mkdir(path fs.RelPath, perms fs.Perms) error
  • func (p *Placer) Mkfifo(path fs.RelPath, perms fs.Perms) error
  • func (p *Placer) Mklink(path fs.RelPath, target string) error
  • func (p *Placer) OpenFile(path fs.RelPath, flag int, perms fs.Perms) (fs.File, error)
  • func (p *Placer) ReadDirNames(path fs.RelPath) ([]string, error)
  • func (p *Placer) Readlink(path fs.RelPath) (target string, isSymlink bool, err error)
  • func (p *Placer) ResolveLink(symlink string, startingAt fs.RelPath) (fs.RelPath, error)
  • func (p *Placer) SetTimesLNano(path fs.RelPath, mtime time.Time, atime time.Time) error
  • func (p *Placer) SetTimesNano(path fs.RelPath, mtime time.Time, atime time.Time) error
  • func (p *Placer) Stat(path fs.RelPath) (*fs.Metadata, error)
• type Tree
  • func FromOS(osPath string) *Tree
  • func New() *Tree
  • func (t *Tree) AsBillyFS(euid, egid uint32) *Billy
  • func (t *Tree) Create(name string, euid, egid uint32, perm os.FileMode) *File
  • func (t *Tree) CreateDir(name string, euid, egid uint32, perm os.FileMode) *Tree
  • func (t *Tree) Get(p []string, followSymlinks bool) (*File, *Tree, error)
  • func (t *Tree) WalkDir(p []string) *Tree
• type TruncatableContents

Constants

const Separator = "/"

Separator provides a stable path separator the memphis FS expects.

Variables

var ErrExists = errors.New("EExists")

ErrExists indicates a file already exists at a location

var ErrNotDir = errors.New("ENotDir")

ErrNotDir indicates the proposed location is not a directory

Types

type Billy

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

Billy wraps a filesystem subtree in the billy filesystem interface

func (*Billy) Capabilities

func (b *Billy) Capabilities() billy.Capability

Capabilities tells billy what this FS can do

func (*Billy) Chmod

func (b *Billy) Chmod(name string, mode os.FileMode) error

Chmod changes file permissions

func (*Billy) Chown

func (b *Billy) Chown(name string, uid, gid int) error

Chown changes file ownership

func (*Billy) Chroot

func (b *Billy) Chroot(path string) (billy.Filesystem, error)

Chroot returns a subtree of the filesystem

func (*Billy) Chtimes

func (b *Billy) Chtimes(name string, atime time.Time, mtime time.Time) error

Chtimes changes file access time

func (*Billy) Create

func (b *Billy) Create(filename string) (billy.File, error)

Create makes a new empty file

func (*Billy) Join

func (b *Billy) Join(elem ...string) string

Join constructs a path

func (*Billy) Lchown

func (b *Billy) Lchown(name string, uid, gid int) error

Lchown changes symlink ownership

func (*Billy) Lstat

func (b *Billy) Lstat(filename string) (os.FileInfo, error)

Lstat provides symlink info

func (*Billy) MkdirAll

func (b *Billy) MkdirAll(filename string, perm os.FileMode) error

MkdirAll creates a new directory

func (*Billy) Open

func (b *Billy) Open(filename string) (billy.File, error)

Open is a shortcut to openfile

func (*Billy) OpenFile

func (b *Billy) OpenFile(filename string, flag int, perm os.FileMode) (billy.File, error)

OpenFile opens a file for access

func (*Billy) ReadDir

func (b *Billy) ReadDir(path string) ([]os.FileInfo, error)

ReadDir lists directory contents

func (*Billy) Readlink

func (b *Billy) Readlink(link string) (string, error)

Readlink returns symlink contents

func (*Billy) Remove

func (b *Billy) Remove(filename string) error

Remove deletes a file

func (*Billy) Rename

func (b *Billy) Rename(oldpath, newpath string) error

Rename a file

func (*Billy) Root

func (b *Billy) Root() string

Root prints the path of the current fs root

func (*Billy) Stat

func (b *Billy) Stat(filename string) (os.FileInfo, error)

Stat returns file metadata

func (*Billy) Symlink

func (b *Billy) Symlink(target, link string) error

Symlink creates a symbolic link

func (*Billy) TempFile

func (b *Billy) TempFile(dir, prefix string) (billy.File, error)

TempFile create an empty tempfile

type BillyFile

type BillyFile struct {
	*File
	// contains filtered or unexported fields
}

BillyFile is a wrapper to file contents implementing the implicit position cursor for read/write

func (*BillyFile) Close

func (bf *BillyFile) Close() error

Close closes the file - not relevant in this implementation.

func (*BillyFile) Lock

func (bf *BillyFile) Lock() error

Lock is not used in this implementation

func (*BillyFile) Read

func (bf *BillyFile) Read(buf []byte) (n int, err error)

Read is a more common implementation implemented by ReadAt

func (*BillyFile) ReadAt

func (bf *BillyFile) ReadAt(buf []byte, offset int64) (n int, err error)

ReadAt is a passthrough.

func (*BillyFile) Seek

func (bf *BillyFile) Seek(offset int64, whence int) (int64, error)

Seek changes file position

func (*BillyFile) Truncate

func (bf *BillyFile) Truncate(size int64) error

Truncate changes the size of the file contents

func (*BillyFile) Unlock

func (bf *BillyFile) Unlock() error

Unlock is not used in this implementation

func (*BillyFile) Write

func (bf *BillyFile) Write(buf []byte) (n int, err error)

Write modifies file contents

func (*BillyFile) WriteAt

func (bf *BillyFile) WriteAt(buf []byte, offset int64) (n int, err error)

WriteAt is a passthrough.

type DirMeta

type DirMeta struct {
	*Tree
	// contains filtered or unexported fields
}

DirMeta is a struct of metadata about a directory

func (*DirMeta) IsDir

func (d *DirMeta) IsDir() bool

IsDir is true for directories

func (*DirMeta) ModTime

func (d *DirMeta) ModTime() time.Time

ModTime is when the directory was last modified

func (*DirMeta) Mode

func (d *DirMeta) Mode() os.FileMode

Mode is the os.FileMode (permissions) for the directory

func (*DirMeta) Name

func (d *DirMeta) Name() string

Name of the directory

func (*DirMeta) Size

func (d *DirMeta) Size() int64

Size of the directory

func (*DirMeta) Sys

func (d *DirMeta) Sys() interface{}

Sys provides os.FileInfo trapdoor down to undefined behavior

type File

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

File holds the metadata of a FS object

func FileFromOS

func FileFromOS(path string, uid, gid uint32, info os.FileInfo) *File

FileFromOS creates a file representing an underlying OS file. writes will transition the file contents to a memory buffer.

func (*File) Bytes

func (f *File) Bytes() []byte

Bytes returns a direct buffer of the contents of the file

func (*File) IsDir

func (f *File) IsDir() bool

IsDir returns if the file is a directory (no)

func (*File) ModTime

func (f *File) ModTime() time.Time

ModTime returns when the file was modified

func (*File) Mode

func (f *File) Mode() os.FileMode

Mode returns the file's mode

func (*File) Name

func (f *File) Name() string

Name returns the file name

func (*File) Size

func (f *File) Size() int64

Size returns the file's size

func (*File) Sys

func (f *File) Sys() interface{}

Sys is a wildcard in the OS interface

type FileContent

type FileContent interface {
	Size() int64
	io.ReaderAt
	io.WriterAt
}

FileContent represents the actual data of a file.

func MemBufferFrom

func MemBufferFrom(fc FileContent) FileContent

MemBufferFrom copies a file contents into a memoryContents format where it can be truncated

func NewEmptyFileContents

func NewEmptyFileContents() FileContent

NewEmptyFileContents creates a new memoryContents buffer

type Placer

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

Placer conforms a memphis directory tree to the rio FS interface

func (*Placer) BasePath

func (p *Placer) BasePath() fs.AbsolutePath

BasePath is the root of this FS - always '/'

func (*Placer) Chmod

func (p *Placer) Chmod(path fs.RelPath, perms fs.Perms) error

Chmod sets permissions of path

func (*Placer) LStat

func (p *Placer) LStat(path fs.RelPath) (*fs.Metadata, error)

LStat returns file metadata not following symlinks

func (*Placer) Lchown

func (p *Placer) Lchown(path fs.RelPath, uid uint32, gid uint32) error

Lchown sets ownership of path w/o following symlinks

func (*Placer) MkdevBlock

func (p *Placer) MkdevBlock(path fs.RelPath, major int64, minor int64, perms fs.Perms) error

MkdevBlock makes a block device at path

func (*Placer) MkdevChar

func (p *Placer) MkdevChar(path fs.RelPath, major int64, minor int64, perms fs.Perms) error

MkdevChar makes a character device at path

func (*Placer) Mkdir

func (p *Placer) Mkdir(path fs.RelPath, perms fs.Perms) error

Mkdir makes a directory at path

func (*Placer) Mkfifo

func (p *Placer) Mkfifo(path fs.RelPath, perms fs.Perms) error

Mkfifo makes a fifo node at path

func (*Placer) Mklink

func (p *Placer) Mklink(path fs.RelPath, target string) error

Mklink makes a symlink at path

func (*Placer) OpenFile

func (p *Placer) OpenFile(path fs.RelPath, flag int, perms fs.Perms) (fs.File, error)

OpenFile attempts to open a file

func (*Placer) ReadDirNames

func (p *Placer) ReadDirNames(path fs.RelPath) ([]string, error)

ReadDirNames lists files in a directory

func (*Placer) Readlink

func (p *Placer) Readlink(path fs.RelPath) (target string, isSymlink bool, err error)

Readlink reads a symlink

func (*Placer) ResolveLink

func (p *Placer) ResolveLink(symlink string, startingAt fs.RelPath) (fs.RelPath, error)

ResolveLink resolves a symlink

func (*Placer) SetTimesLNano

func (p *Placer) SetTimesLNano(path fs.RelPath, mtime time.Time, atime time.Time) error

SetTimesLNano sets modification/access times of path

func (*Placer) SetTimesNano

func (p *Placer) SetTimesNano(path fs.RelPath, mtime time.Time, atime time.Time) error

SetTimesNano sets modification/access times of path

func (*Placer) Stat

func (p *Placer) Stat(path fs.RelPath) (*fs.Metadata, error)

Stat returns file metadata

type Tree

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

Tree represents a directory

func FromOS

func FromOS(osPath string) *Tree

FromOS creates a memphis instance overlayed on an OS subtree

func New

func New() *Tree

New creates a new, empty memphis instance

func (*Tree) AsBillyFS

func (t *Tree) AsBillyFS(euid, egid uint32) *Billy

AsBillyFS provides a billy-comptatible view of the current memphis directory tree

func (*Tree) Create

func (t *Tree) Create(name string, euid, egid uint32, perm os.FileMode) *File

Create makes a new file in the directory

func (*Tree) CreateDir

func (t *Tree) CreateDir(name string, euid, egid uint32, perm os.FileMode) *Tree

CreateDir makes a new directory in the directory

func (*Tree) Get

func (t *Tree) Get(p []string, followSymlinks bool) (*File, *Tree, error)

Get attempts to get a file at a given path.

func (*Tree) WalkDir

func (t *Tree) WalkDir(p []string) *Tree

WalkDir descends to a given sub directory

type TruncatableContents

type TruncatableContents interface {
	Truncate(size int64) error
}

TruncatableContents is an optional FileContent interface for efficiency