volume

Documentation

Overview

Package volume provides helpers for representing a remote filesystem.

Plugins should use these helpers when representing a filesystem where the structure and stats are retrieved all-at-once. The filesystem representation should be stored in 'DirMap'. The root of the filesystem is then created with 'NewDir'.

Index

• Constants
• func ChildSchemas() []*plugin.EntrySchema
• func List(ctx context.Context, impl Interface) ([]plugin.Entry, error)
• func NormalErrorPOSIX(text string) bool
• func NormalErrorPowerShell(text string) bool
• func StatCmdPOSIX(path string, maxdepth int) []string
• func StatCmdPowershell(path string, maxdepth int) []string
• type Children
• type DirMap
  • func ParseStatPOSIX(output io.Reader, base string, start string, maxdepth int) (DirMap, error)
  • func ParseStatPowershell(output io.Reader, base string, start string, maxdepth int) (DirMap, error)
• type FS
  • func NewFS(ctx context.Context, name string, executor plugin.Execable, maxdepth int) *FS
  • func (d *FS) ChildSchemas() []*plugin.EntrySchema
  • func (d *FS) List(ctx context.Context) ([]plugin.Entry, error)
  • func (d *FS) Schema() *plugin.EntrySchema
  • func (d *FS) VolumeDelete(ctx context.Context, path string) (bool, error)
  • func (d *FS) VolumeList(ctx context.Context, path string) (DirMap, error)
  • func (d *FS) VolumeRead(ctx context.Context, path string) ([]byte, error)
  • func (d *FS) VolumeStream(ctx context.Context, path string) (io.ReadCloser, error)
  • func (d *FS) VolumeWrite(ctx context.Context, path string, b []byte, _ os.FileMode) error
• type Interface

Constants

const ListTTL = 30 * time.Second

ListTTL represents the List op's TTL. The entry implementing volume.Interface should set the List op's TTL to this value.

const RootPath = ""

RootPath is the root of the filesystem described by a DirMap returned from VolumeList.

Functions

func ChildSchemas

func ChildSchemas() []*plugin.EntrySchema

ChildSchemas returns a volume's child schema

func List

func List(ctx context.Context, impl Interface) ([]plugin.Entry, error)

List constructs an array of entries for the given path from a DirMap. If a directory that hasn't been explored yet is listed it will conduct further exploration. Requests are cached against the supplied Interface using the VolumeListCB op.

func NormalErrorPOSIX

func NormalErrorPOSIX(text string) bool

NormalErrorPOSIX returns whether this line of text is normal error output for StatCmdPOSIX.

Find may return a non-zero exit code, with messages in stdout like

stat: ‘/dev/fd/4’: No such file or directory
find: File system loop detected; ‘/proc/7/cwd’ is part of the same file system loop as ‘/’.
find: ‘/root’: Permission denied

These are considered normal and handled by ParseStatPOSIX.

func NormalErrorPowerShell

func NormalErrorPowerShell(text string) bool

NormalErrorPowerShell returns whether this line of text is normal error output for StatCmdPowerShell.

Currently no error messages are considered ignorable.

func StatCmdPOSIX

func StatCmdPOSIX(path string, maxdepth int) []string

StatCmdPOSIX returns the POSIX command required to stat all the files in a directory up to maxdepth.

func StatCmdPowershell

func StatCmdPowershell(path string, maxdepth int) []string

StatCmdPowershell returns the PowerShell command required to stat all the files in a directory up to maxdepth.

Types

type Children

type Children = map[string]plugin.EntryAttributes

Children represents a directory's children. It is a map of <child_basename> => <child_attributes>.

type DirMap

type DirMap = map[string]Children

A DirMap is a map of <dir_path> => <children>. If <children> is nil, then that means that <dir_path>'s children haven't been discovered yet, so we will run VolumeList on <dir_path>.

func ParseStatPOSIX

func ParseStatPOSIX(output io.Reader, base string, start string, maxdepth int) (DirMap, error)

ParseStatPOSIX an output stream that is the result of running StatCmdPOSIX. Strips 'base' from the file paths, and maps each directory to a map of files in that directory and their attr (attributes). The 'maxdepth' used to produce the output is required to identify directories where we do not know their contents. 'start' denotes where the search started from, and is the basis for calculating maxdepth.

func ParseStatPowershell

func ParseStatPowershell(output io.Reader, base string, start string, maxdepth int) (DirMap, error)

ParseStatPowershell an output stream that is the result of running StatCmdPowershell. Strips 'base' from the file paths, and maps each directory to a map of files in that directory and their attr (attributes). The 'maxdepth' used to produce the output is required to identify directories where we do not know their contents. 'start' denotes where the search started from, and is the basis for calculating maxdepth.

type FS

type FS struct {
	plugin.EntryBase
	// contains filtered or unexported fields
}

FS presents a view of the filesystem of an Execable resource.

func NewFS

func NewFS(ctx context.Context, name string, executor plugin.Execable, maxdepth int) *FS

NewFS creates a new FS entry with the given name, using the supplied executor to satisfy volume operations.

func (*FS) ChildSchemas

func (d *FS) ChildSchemas() []*plugin.EntrySchema

ChildSchemas returns the FS entry's child schema

func (*FS) List

func (d *FS) List(ctx context.Context) ([]plugin.Entry, error)

List creates a hierarchy of the filesystem of an Execable resource (the executor).

func (*FS) Schema

func (d *FS) Schema() *plugin.EntrySchema

Schema returns the FS entry's schema

func (*FS) VolumeDelete

func (d *FS) VolumeDelete(ctx context.Context, path string) (bool, error)

VolumeDelete satisfies the Interface required by Delete to delete volume nodes.

func (*FS) VolumeList

func (d *FS) VolumeList(ctx context.Context, path string) (DirMap, error)

VolumeList satisfies the Interface required by List to enumerate files.

func (*FS) VolumeRead

func (d *FS) VolumeRead(ctx context.Context, path string) ([]byte, error)

VolumeRead satisfies the Interface required by List to read file contents.

func (*FS) VolumeStream

func (d *FS) VolumeStream(ctx context.Context, path string) (io.ReadCloser, error)

VolumeStream satisfies the Interface required by List to stream file contents.

func (*FS) VolumeWrite

func (d *FS) VolumeWrite(ctx context.Context, path string, b []byte, _ os.FileMode) error

VolumeWrite satisfies the Interface required by Write to write content to a file.

type Interface

type Interface interface {
	plugin.Entry

	// Returns a map of volume nodes to their stats, such as that returned by ParseStatPOSIX.
	// DirMap must include items starting from the specified path. If an entry in DirMap
	// points to a nil Dir, it is assumed to be unexplored.
	VolumeList(ctx context.Context, path string) (DirMap, error)
	// Accepts a path and returns the content associated with that path.
	VolumeRead(ctx context.Context, path string) ([]byte, error)
	// Accepts a path and streams updates to the content associated with that path.
	VolumeStream(ctx context.Context, path string) (io.ReadCloser, error)
	// Accepts a path and content and writes it to the file associated with that path.
	// Mode is provided for Write operations that replace the entire file.
	VolumeWrite(ctx context.Context, path string, b []byte, m os.FileMode) error
	// Deletes the volume node at the specified path. Mirrors plugin.Deletable#Delete
	VolumeDelete(ctx context.Context, path string) (bool, error)
}

Interface presents methods to access the volume.

Method names for this interface are chosen to make it simple to distinguish them from methods implemented to satisfy plugin interfaces.