go-cloud: github.com/google/go-cloud/blob/driver Index | Files

package driver

import "github.com/google/go-cloud/blob/driver"

Package driver defines a set of interfaces that the blob package uses to interact with the underlying blob services.

Index

Package Files

driver.go

type Attributes Uses

type Attributes struct {
    // ContentType is the MIME type of the blob object. It must not be empty.
    ContentType string
    // Metadata holds key/value pairs associated with the blob.
    // Keys will be lowercased by the concrete type before being returned
    // to the user. If there are duplicate case-insensitive keys (e.g.,
    // "foo" and "FOO"), only one value will be kept, and it is undefined
    // which one.
    Metadata map[string]string
    // ModTime is the time the blob object was last modified.
    ModTime time.Time
    // Size is the size of the object in bytes.
    Size int64
    // AsFunc allows providers to expose provider-specific types;
    // see Bucket.As for more details.
    // If not set, no provider-specific types are supported.
    AsFunc func(interface{}) bool
}

Attributes contains attributes about a blob.

type Bucket Uses

type Bucket interface {
    // IsNotExist should return true if err, an error returned from one
    // of the other methods in this interface, represents a "key does not exist"
    // error.
    IsNotExist(err error) bool

    // IsNotImplemented should return true if err, an error returned from one
    // of the other methods in this interface, indicates that the method is not
    // implemented for this provider.
    IsNotImplemented(err error) bool

    // As allows providers to expose provider-specific types.
    //
    // i will be a pointer to the type the user wants filled in.
    // As should either fill it in and return true, or return false.
    //
    // Mutable objects should be exposed as a pointer to the object;
    // i will therefore be a **.
    //
    // A provider should document the type(s) it support in package
    // comments, and add conformance tests verifying them.
    //
    // A sample implementation might look like this, for supporting foo.MyType:
    //   mt, ok := i.(*foo.MyType)
    //   if !ok {
    //     return false
    //   }
    //   *i = foo.MyType{}  // or, more likely, the existing value
    //   return true
    //
    // See
    // https://github.com/google/go-cloud/blob/master/internal/docs/design.md#as
    // for more background.
    As(i interface{}) bool

    // ErrorAs allows providers to expose provider-specific types for returned
    // errors; see Bucket.As for more details.
    ErrorAs(error, interface{}) bool

    // Attributes returns attributes for the blob. If the specified object does
    // not exist, Attributes must return an error for which IsNotExist returns
    // true.
    Attributes(ctx context.Context, key string) (Attributes, error)

    // ListPaged lists objects in the bucket, in lexicographical order by
    // UTF-8-encoded key, returning pages of objects at a time.
    // Providers are only required to be eventually consistent with respect
    // to recently written or deleted objects. That is to say, there is no
    // guarantee that an object that's been written will immediately be returned
    // from ListPaged.
    // opts is guaranteed to be non-nil.
    ListPaged(ctx context.Context, opts *ListOptions) (*ListPage, error)

    // NewRangeReader returns a Reader that reads part of an object, reading at
    // most length bytes starting at the given offset. If length is negative, it
    // will read until the end of the object. If the specified object does not
    // exist, NewRangeReader must return an error for which IsNotExist returns
    // true.
    // opts is guaranteed to be non-nil.
    NewRangeReader(ctx context.Context, key string, offset, length int64, opts *ReaderOptions) (Reader, error)

    // NewTypedWriter returns Writer that writes to an object associated with key.
    //
    // A new object will be created unless an object with this key already exists.
    // Otherwise any previous object with the same key will be replaced.
    // The object may not be available (and any previous object will remain)
    // until Close has been called.
    //
    // contentType sets the MIME type of the object to be written. It must not be
    // empty. opts is guaranteed to be non-nil.
    //
    // The caller must call Close on the returned Writer when done writing.
    //
    // Implementations should abort an ongoing write if ctx is later canceled,
    // and do any necessary cleanup in Close. Close should then return ctx.Err().
    NewTypedWriter(ctx context.Context, key string, contentType string, opts *WriterOptions) (Writer, error)

    // Delete deletes the object associated with key. If the specified object does
    // not exist, NewRangeReader must return an error for which IsNotExist returns
    // true.
    Delete(ctx context.Context, key string) error

    // SignedURL returns a URL that can be used to GET the blob for the duration
    // specified in opts.Expiry. opts is guaranteed to be non-nil.
    // If not supported, return an error for which IsNotImplemented returns
    // true.
    SignedURL(ctx context.Context, key string, opts *SignedURLOptions) (string, error)
}

Bucket provides read, write and delete operations on objects within it on the blob service.

type ListObject Uses

type ListObject struct {
    // Key is the key for this blob.
    Key string
    // ModTime is the time the blob object was last modified.
    ModTime time.Time
    // Size is the size of the object in bytes.
    Size int64
    // IsDir indicates that this result represents a "directory" in the
    // hierarchical namespace, ending in ListOptions.Delimiter. Key can be
    // passed as ListOptions.Prefix to list items in the "directory".
    // Fields other than Key and IsDir will not be set if IsDir is true.
    IsDir bool
    // AsFunc allows providers to expose provider-specific types;
    // see Bucket.As for more details.
    // If not set, no provider-specific types are supported.
    AsFunc func(interface{}) bool
}

ListObject represents a specific blob object returned from ListPaged.

type ListOptions Uses

type ListOptions struct {
    // Prefix indicates that only results with the given prefix should be
    // returned.
    Prefix string
    // Delimiter sets the delimiter used to define a hierarchical namespace,
    // like a filesystem with "directories".
    //
    // An empty delimiter means that the bucket is treated as a single flat
    // namespace.
    //
    // A non-empty delimiter means that any result with the delimiter in its key
    // after Prefix is stripped will be returned with ListObject.IsDir = true,
    // ListObject.Key truncated after the delimiter, and zero values for other
    // ListObject fields. These results represent "directories". Multiple results
    // in a "directory" are returned as a single result.
    Delimiter string
    // PageSize sets the maximum number of objects to be returned.
    // 0 means no maximum; driver implementations should choose a reasonable
    // max.
    PageSize int
    // PageToken may be filled in with the NextPageToken from a previous
    // ListPaged call.
    PageToken []byte
    // BeforeList is a callback that must be called exactly once during ListPaged,
    // before the underlying provider's list is executed.
    // asFunc allows providers to expose provider-specific types;
    // see Bucket.As for more details.
    BeforeList func(asFunc func(interface{}) bool) error
}

ListOptions sets options for listing objects in the bucket. TODO(Issue #541): Add Delimiter.

type ListPage Uses

type ListPage struct {
    // Objects is the slice of objects found. If ListOptions.PageSize != 0,
    // it should have at most ListOptions.PageSize entries.
    //
    // Objects should be returned in lexicographical order of UTF-8 encoded keys,
    // including across pages. I.e., all objects returned from a ListPage request
    // made using a PageToken from a previous ListPage request's NextPageToken
    // should have Key >= the Key for all objects from the previous request.
    Objects []*ListObject
    // NextPageToken should be left empty unless there are more objects
    // to return. The value may be returned as ListOptions.PageToken on a
    // subsequent ListPaged call, to fetch the next page of results.
    // It can be an arbitrary []byte; it need not be a valid key.
    NextPageToken []byte
}

ListPage represents a page of results return from ListPaged.

type Reader Uses

type Reader interface {
    io.ReadCloser

    // Attributes returns a subset of attributes about the blob.
    Attributes() ReaderAttributes

    // As allows providers to expose provider-specific types;
    // see Bucket.As for more details.
    As(interface{}) bool
}

Reader reads an object from the blob.

type ReaderAttributes Uses

type ReaderAttributes struct {
    // ContentType is the MIME type of the blob object. It must not be empty.
    ContentType string
    // ModTime is the time the blob object was last modified.
    ModTime time.Time
    // Size is the size of the object in bytes.
    Size int64
}

ReaderAttributes contains a subset of attributes about a blob that are accessible from Reader.

type ReaderOptions Uses

type ReaderOptions struct{}

ReaderOptions controls Reader behaviors. It is provided for future extensibility.

type SignedURLOptions Uses

type SignedURLOptions struct {
    // Expiry sets how long the returned URL is valid for. It is guaranteed to be > 0.
    Expiry time.Duration
}

SignedURLOptions sets options for SignedURL.

type Writer Uses

type Writer interface {
    io.WriteCloser
}

Writer writes an object to the blob.

type WriterOptions Uses

type WriterOptions struct {
    // BufferSize changes the default size in byte of the maximum part Writer can
    // write in a single request, if supported. Larger objects will be split into
    // multiple requests.
    BufferSize int
    // ContentMD5 may be used as a message integrity check (MIC).
    // https://tools.ietf.org/html/rfc1864
    ContentMD5 []byte
    // Metadata holds key/value strings to be associated with the blob.
    // Keys are guaranteed to be non-empty and lowercased.
    Metadata map[string]string
    // BeforeWrite is a callback that must be called exactly once before
    // any data is written, unless NewTypedWriter returns an error, in
    // which case it should not be called.
    // asFunc allows providers to expose provider-specific types;
    // see Bucket.As for more details.
    BeforeWrite func(asFunc func(interface{}) bool) error
}

WriterOptions controls behaviors of Writer.

Package driver imports 3 packages (graph) and is imported by 5 packages. Updated 2018-11-30. Refresh now. Tools for package owners.