driver

Documentation

Index

• Variables
• func WalkFallback(ctx context.Context, driver StorageDriver, from string, f WalkFn, ...) error
• func WithStartAfterHint(startAfterHint string) func(*WalkOptions)
• type ErrUnsupportedMethod
  • func (err ErrUnsupportedMethod) Error() string
• type Error
  • func (err Error) Error() string
• type Errors
  • func (e Errors) Error() string
• type FileInfo
• type FileInfoFields
• type FileInfoInternal
  • func (fi FileInfoInternal) IsDir() bool
  • func (fi FileInfoInternal) ModTime() time.Time
  • func (fi FileInfoInternal) Path() string
  • func (fi FileInfoInternal) Size() int64
• type FileWriter
• type InvalidOffsetError
  • func (err InvalidOffsetError) Error() string
• type InvalidPathError
  • func (err InvalidPathError) Error() string
• type PathNotFoundError
  • func (err PathNotFoundError) Error() string
• type StorageDriver
• type Version
  • func (version Version) Major() uint
  • func (version Version) Minor() uint
• type WalkFn
• type WalkOptions

Variables

var ErrFilledBuffer = errors.New("we have enough entries")

ErrFilledBuffer is used as a return value from onFileFunc to indicate that the requested number of entries has been reached and the walk can stop.

var ErrSkipDir = errors.New("skip this directory")

ErrSkipDir is used as a return value from onFileFunc to indicate that the directory named in the call is to be skipped. It is not returned as an error by any function.

var PathRegexp = regexp.MustCompile(`^(/[A-Za-z0-9._-]+)+$`)

PathRegexp is the regular expression which each file path must match. A file path is absolute, beginning with a slash and containing a positive number of path components separated by slashes, where each component is restricted to alphanumeric characters or a period, underscore, or hyphen.

Functions

func WalkFallback

func WalkFallback(ctx context.Context, driver StorageDriver, from string, f WalkFn, options ...func(*WalkOptions)) error

WalkFallback traverses a filesystem defined within driver, starting from the given path, calling f on each file. It uses the List method and Stat to drive itself. If the returned error from the WalkFn is ErrSkipDir the directory will not be entered and Walk will continue the traversal. If the returned error from the WalkFn is ErrFilledBuffer, the walk stops.

func WithStartAfterHint

func WithStartAfterHint(startAfterHint string) func(*WalkOptions)

Types

type ErrUnsupportedMethod

type ErrUnsupportedMethod struct {
	DriverName string
}

ErrUnsupportedMethod may be returned in the case where a StorageDriver implementation does not support an optional method.

func (ErrUnsupportedMethod) Error

func (err ErrUnsupportedMethod) Error() string

type Error

type Error struct {
	DriverName string
	Enclosed   error
}

Error is a catch-all error type which captures an error string and the driver type on which it occurred.

func (Error) Error

func (err Error) Error() string

type Errors

type Errors struct {
	DriverName string
	Errs       []error
}

Errors provides the envelope for multiple errors for use within the storagedriver implementations.

func (Errors) Error

func (e Errors) Error() string

type FileInfo

type FileInfo interface {
	// Path provides the full path of the target of this file info.
	Path() string

	// Size returns current length in bytes of the file. The return value can
	// be used to write to the end of the file at path. The value is
	// meaningless if IsDir returns true.
	Size() int64

	// ModTime returns the modification time for the file. For backends that
	// don't have a modification time, the creation time should be returned.
	ModTime() time.Time

	// IsDir returns true if the path is a directory.
	IsDir() bool
}

FileInfo returns information about a given path. Inspired by os.FileInfo, it elides the base name method for a full path instead.

type FileInfoFields

type FileInfoFields struct {
	// Path provides the full path of the target of this file info.
	Path string

	// Size is current length in bytes of the file. The value of this field
	// can be used to write to the end of the file at path. The value is
	// meaningless if IsDir is set to true.
	Size int64

	// ModTime returns the modification time for the file. For backends that
	// don't have a modification time, the creation time should be returned.
	ModTime time.Time

	// IsDir returns true if the path is a directory.
	IsDir bool
}

FileInfoFields provides the exported fields for implementing FileInfo interface in storagedriver implementations. It should be used with InternalFileInfo.

type FileInfoInternal

type FileInfoInternal struct {
	FileInfoFields
}

FileInfoInternal implements the FileInfo interface. This should only be used by storagedriver implementations that don't have a specialized FileInfo type.

func (FileInfoInternal) IsDir

func (fi FileInfoInternal) IsDir() bool

IsDir returns true if the path is a directory.

func (FileInfoInternal) ModTime

func (fi FileInfoInternal) ModTime() time.Time

ModTime returns the modification time for the file. For backends that don't have a modification time, the creation time should be returned.

func (FileInfoInternal) Path

func (fi FileInfoInternal) Path() string

Path provides the full path of the target of this file info.

func (FileInfoInternal) Size

func (fi FileInfoInternal) Size() int64

Size returns current length in bytes of the file. The return value can be used to write to the end of the file at path. The value is meaningless if IsDir returns true.

type FileWriter

type FileWriter interface {
	io.WriteCloser

	// Size returns the number of bytes written to this FileWriter.
	Size() int64

	// Cancel removes any written content from this FileWriter.
	Cancel(context.Context) error

	// Commit flushes all content written to this FileWriter and makes it
	// available for future calls to StorageDriver.GetContent and
	// StorageDriver.Reader.
	Commit() error
}

FileWriter provides an abstraction for an opened writable file-like object in the storage backend. The FileWriter must flush all content written to it on the call to Close, but is only required to make its content readable on a call to Commit.

type InvalidOffsetError

type InvalidOffsetError struct {
	Path       string
	Offset     int64
	DriverName string
}

InvalidOffsetError is returned when attempting to read or write from an invalid offset.

func (InvalidOffsetError) Error

func (err InvalidOffsetError) Error() string

type InvalidPathError

type InvalidPathError struct {
	Path       string
	DriverName string
}

InvalidPathError is returned when the provided path is malformed.

func (InvalidPathError) Error

func (err InvalidPathError) Error() string

type PathNotFoundError

type PathNotFoundError struct {
	Path       string
	DriverName string
}

PathNotFoundError is returned when operating on a nonexistent path.

func (PathNotFoundError) Error

func (err PathNotFoundError) Error() string

type StorageDriver

type StorageDriver interface {
	// Name returns the human-readable "name" of the driver, useful in error
	// messages and logging. By convention, this will just be the registration
	// name, but drivers may provide other information here.
	Name() string

	// GetContent retrieves the content stored at "path" as a []byte.
	// This should primarily be used for small objects.
	GetContent(ctx context.Context, path string) ([]byte, error)

	// PutContent stores the []byte content at a location designated by "path".
	// This should primarily be used for small objects.
	PutContent(ctx context.Context, path string, content []byte) error

	// Reader retrieves an io.ReadCloser for the content stored at "path"
	// with a given byte offset.
	// May be used to resume reading a stream by providing a nonzero offset.
	Reader(ctx context.Context, path string, offset int64) (io.ReadCloser, error)

	// Writer returns a FileWriter which will store the content written to it
	// at the location designated by "path" after the call to Commit.
	Writer(ctx context.Context, path string, append bool) (FileWriter, error)

	// Stat retrieves the FileInfo for the given path, including the current
	// size in bytes and the creation time.
	Stat(ctx context.Context, path string) (FileInfo, error)

	// List returns a list of the objects that are direct descendants of the
	// given path.
	List(ctx context.Context, path string) ([]string, error)

	// Move moves an object stored at sourcePath to destPath, removing the
	// original object.
	// Note: This may be no more efficient than a copy followed by a delete for
	// many implementations.
	Move(ctx context.Context, sourcePath string, destPath string) error

	// Delete recursively deletes all objects stored at "path" and its subpaths.
	Delete(ctx context.Context, path string) error

	// URLFor returns a URL which may be used to retrieve the content stored at
	// the given path, possibly using the given options.
	// May return an ErrUnsupportedMethod in certain StorageDriver
	// implementations.
	URLFor(ctx context.Context, path string, options map[string]interface{}) (string, error)

	// Walk traverses a filesystem defined within driver, starting
	// from the given path, calling f on each file.
	// If the returned error from the WalkFn is ErrSkipDir and fileInfo refers
	// to a directory, the directory will not be entered and Walk
	// will continue the traversal.
	// If the returned error from the WalkFn is ErrFilledBuffer, processing stops.
	Walk(ctx context.Context, path string, f WalkFn, options ...func(*WalkOptions)) error
}

StorageDriver defines methods that a Storage Driver must implement for a filesystem-like key/value object storage. Storage Drivers are automatically registered via an internal registration mechanism, and generally created via the StorageDriverFactory interface (https://godoc.org/github.com/nlandolfi/distribution/registry/storage/driver/factory). Please see the aforementioned factory package for example code showing how to get an instance of a StorageDriver

type Version

type Version string

Version is a string representing the storage driver version, of the form Major.Minor. The registry must accept storage drivers with equal major version and greater minor version, but may not be compatible with older storage driver versions.

const CurrentVersion Version = "0.1"

CurrentVersion is the current storage driver Version.

func (Version) Major

func (version Version) Major() uint

Major returns the major (primary) component of a version.

func (Version) Minor

func (version Version) Minor() uint

Minor returns the minor (secondary) component of a version.

type WalkFn

type WalkFn func(fileInfo FileInfo) error

WalkFn is called once per file by Walk

type WalkOptions

type WalkOptions struct {
	// If StartAfterHint is set, the walk may start with the first item lexographically
	// after the hint, but it is not guaranteed and drivers may start the walk from the path.
	StartAfterHint string
}

WalkOptions provides options to the walk function that may adjust its behaviour