stow: gomodules.xyz/stow Index | Files | Directories

package stow

import "gomodules.xyz/stow"

Package stow provides an abstraction on cloud storage capabilities.

Index

Package Files

doc.go stow.go walk.go

Variables

var (
    // ErrNotFound is returned when something could not be found.
    ErrNotFound = errors.New("not found")
    // ErrBadCursor is returned by paging methods when the specified
    // cursor is invalid.
    ErrBadCursor = errors.New("bad cursor")
)
var (
    // CursorStart is a string representing a cursor pointing
    // to the first page of items or containers.
    CursorStart = ""

    // NoPrefix is a string representing no prefix. It can be used
    // in any function that asks for a prefix value, but where one is
    // not appropriate.
    NoPrefix = ""
)

func IsCursorEnd Uses

func IsCursorEnd(cursor string) bool

IsCursorEnd checks whether the cursor indicates there are no more items or not.

func IsNotSupported Uses

func IsNotSupported(err error) bool

IsNotSupported gets whether the error is due to a feature not being supported by a specific implementation.

func KindByURL Uses

func KindByURL(u *url.URL) (string, error)

KindByURL gets the kind represented by the given URL. It consults all registered locations. Error returned if no match is found.

func Kinds Uses

func Kinds() []string

Kinds gets a list of installed location kinds.

func NotSupported Uses

func NotSupported(feature string) error

NotSupported gets an error describing the feature as not supported by this implementation.

func Register Uses

func Register(kind string, makefn func(Config) (Location, error), kindmatchfn func(*url.URL) bool, validatefn func(Config) error)

Register adds a Location implementation, with two helper functions. makefn should make a Location with the given Config. kindmatchfn should inspect a URL and return whether it represents a Location of this kind or not. Code can call KindByURL to get a kind string for any given URL and all registered implementations will be consulted. Register is usually called in an implementation package's init method.

func Validate Uses

func Validate(kind string, config Config) error

Validate validates the config for a location

func Walk Uses

func Walk(container Container, prefix string, pageSize int, fn WalkFunc) error

Walk walks all Items in the Container. Returns the first error returned by the WalkFunc or nil if no errors were returned. The pageSize is the number of Items to get per request.

func WalkContainers Uses

func WalkContainers(location Location, prefix string, pageSize int, fn WalkContainersFunc) error

WalkContainers walks all Containers in the Location. Returns the first error returned by the WalkContainersFunc or nil if no errors were returned. The pageSize is the number of Containers to get per request.

type Config Uses

type Config interface {
    // Config gets a string configuration value and a
    // bool indicating whether the value was present or not.
    Config(name string) (string, bool)
    // Set sets the configuration name to specified value
    Set(name, value string)
}

Config represents key/value configuration.

type ConfigMap Uses

type ConfigMap map[string]string

ConfigMap is a map[string]string that implements the Config method.

func (ConfigMap) Config Uses

func (c ConfigMap) Config(name string) (string, bool)

Config gets a string configuration value and a bool indicating whether the value was present or not.

func (ConfigMap) Set Uses

func (c ConfigMap) Set(name, value string)

Set sets name configuration to value

type Container Uses

type Container interface {
    // ID gets a unique string describing this Container.
    ID() string
    // Name gets a human-readable name describing this Container.
    Name() string
    // Item gets an item by its ID.
    Item(id string) (Item, error)
    // Browse gets a page of prefixes and items with the specified
    // prefix and delimiter for this Container.
    // The specified cursor is a pointer to the start of
    // the items to get. It it obtained from a previous
    // call to this method, or should be CursorStart for the
    // first page.
    // delimiter returns results in a directory-like fashion.
    // Results will contain only items whose names, aside from the
    // prefix, do not contain delimiter. Items whose names,
    // aside from the prefix, contain delimiter will have their name,
    // truncated after the delimiter, returned in prefixes.
    // Duplicate prefixes are omitted. Optional.
    // count is the number of items to return per page.
    // The returned cursor can be checked with IsCursorEnd to
    // decide if there are any more items or not.
    Browse(prefix, delimiter, cursor string, count int) (*ItemPage, error)
    // Items gets a page of items with the specified
    // prefix for this Container.
    // The specified cursor is a pointer to the start of
    // the items to get. It it obtained from a previous
    // call to this method, or should be CursorStart for the
    // first page.
    // count is the number of items to return per page.
    // The returned cursor can be checked with IsCursorEnd to
    // decide if there are any more items or not.
    // Items is a shortcut for Browse where delimeter is not set.
    Items(prefix, cursor string, count int) ([]Item, string, error)
    // RemoveItem removes the Item with the specified ID.
    RemoveItem(id string) error
    // Put creates a new Item with the specified name, and contents
    // read from the reader.
    Put(name string, r io.Reader, size int64, metadata map[string]interface{}) (Item, error)
    // HasWriteAccess returns null if items cane be created and deleted from this container.
    HasWriteAccess() error
}

Container represents a container.

type Item Uses

type Item interface {
    // ID gets a unique string describing this Item.
    ID() string
    // Name gets a human-readable name describing this Item.
    Name() string
    // URL gets a URL for this item.
    // For example:
    // local: file:///path/to/something
    // azure: azure://host:port/api/something
    //    s3: s3://host:post/etc
    URL() *url.URL
    // Size gets the size of the Item's contents in bytes.
    Size() (int64, error)
    // Open opens the Item for reading.
    // Calling code must close the io.ReadCloser.
    Open() (io.ReadCloser, error)
    // ETag is a string that is different when the Item is
    // different, and the same when the item is the same.
    // Usually this is the last modified datetime.
    ETag() (string, error)
    // LastMod returns the last modified date of the file.
    LastMod() (time.Time, error)
    // Metadata gets a map of key/values that belong
    // to this Item.
    Metadata() (map[string]interface{}, error)
}

Item represents an item inside a Container. Such as a file.

type ItemPage Uses

type ItemPage struct {
    Prefixes []string
    Items    []Item
    Cursor   string
}

type ItemRanger Uses

type ItemRanger interface {
    // OpenRange opens the item for reading starting at byte start and ending
    // at byte end.
    OpenRange(start, end uint64) (io.ReadCloser, error)
}

ItemRanger represents an item that can be partially downloaded.

type Location Uses

type Location interface {
    io.Closer
    // CreateContainer creates a new Container with the
    // specified name.
    CreateContainer(name string) (Container, error)
    // Containers gets a page of containers
    // with the specified prefix from this Location.
    // The specified cursor is a pointer to the start of
    // the containers to get. It it obtained from a previous
    // call to this method, or should be CursorStart for the
    // first page.
    // count is the number of items to return per page.
    // The returned cursor can be checked with IsCursorEnd to
    // decide if there are any more items or not.
    Containers(prefix string, cursor string, count int) ([]Container, string, error)
    // Container gets the Container with the specified
    // identifier.
    Container(id string) (Container, error)
    // RemoveContainer removes the container with the specified ID.
    RemoveContainer(id string) error
    // ItemByURL gets an Item at this location with the
    // specified URL.
    ItemByURL(url *url.URL) (Item, error)
}

Location represents a storage location.

func Dial Uses

func Dial(kind string, config Config) (Location, error)

Dial gets a new Location with the given kind and configuration.

type Taggable Uses

type Taggable interface {
    // Tags returns a list of tags that belong to a given Item
    Tags() (map[string]interface{}, error)
}

Taggable represents a taggable Item

type WalkContainersFunc Uses

type WalkContainersFunc func(container Container, err error) error

WalkContainersFunc is a function called for each Container visited by WalkContainers. If there was a problem, the incoming error will describe the problem and the function can decide how to handle that error. If an error is returned, processing stops.

type WalkFunc Uses

type WalkFunc func(item Item, err error) error

WalkFunc is a function called for each Item visited by Walk. If there was a problem, the incoming error will describe the problem and the function can decide how to handle that error. If an error is returned, processing stops.

Directories

PathSynopsis
azurePackage azure provides an abstraction for the Microsoft Azure Storage service.
b2
googlePackage google provides an abstraction of Google Cloud Storage.
localPackage local provides an abstraction of a general filesystem.
oraclePackage oracle provides an absraction of the Oracle Storage Cloud Service.
s3Package s3 provides an abstraction of Amazon S3 (Simple Storage Service).
swiftPackage swift provides an absraction of the Openstack Swift storage technology.
test

Package stow imports 5 packages (graph) and is imported by 43 packages. Updated 2019-11-29. Refresh now. Tools for package owners.