driver

package
Version: v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 13, 2018 License: Apache-2.0 Imports: 3 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Attributes added in v0.7.0

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

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 added in v0.7.0

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 added in v0.7.0

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 added in v0.7.0

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

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 added in v0.7.0

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 added in v0.7.0

type ReaderOptions struct{}

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

type SignedURLOptions added in v0.7.0

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

type Writer interface {
	io.WriteCloser
}

Writer writes an object to the blob.

type WriterOptions

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.

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL