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 ¶
type Attributes struct { // CacheControl specifies caching attributes that providers may use // when serving the blob. // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control CacheControl string // ContentDisposition specifies whether the blob content is expected to be // displayed inline or as an attachment. // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition ContentDisposition string // ContentEncoding specifies the encoding used for the blob's content, if any. // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding ContentEncoding string // ContentLanguage specifies the language used in the blob's content, if any. // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Language ContentLanguage string // ContentType is the MIME type of the blob object. It must not be empty. // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type ContentType string // Metadata holds key/value pairs associated with the blob. // Keys will be lowercased by the portable 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 // MD5 is an MD5 hash of the blob contents or nil if not available. MD5 []byte // 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 { // ErrorCode should return a code that describes the error, which was returned by // one of the other methods in this interface. ErrorCode(error) gcerrors.ErrorCode // As converts i to provider-specific types. // See https://gocloud.dev/concepts/as/ for background information. As(i interface{}) bool // ErrorAs allows providers to expose provider-specific types for returned // errors. // See https://gocloud.dev/concepts/as/ for background information. ErrorAs(error, interface{}) bool // Attributes returns attributes for the blob. If the specified object does // not exist, Attributes must return an error for which ErrorCode returns // gcerrors.NotFound. // The portable type will not modify the returned Attributes. 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 ErrorCode returns // gcerrors.NotFound. // 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, contentType string, opts *WriterOptions) (Writer, error) // Copy copies the object associated with srcKey to dstKey. // // If the source object does not exist, Copy must return an error for which // ErrorCode returns gcerrors.NotFound. // // If the destination object already exists, it should be overwritten. // // opts is guaranteed to be non-nil. Copy(ctx context.Context, dstKey, srcKey string, opts *CopyOptions) error // Delete deletes the object associated with key. If the specified object does // not exist, Delete must return an error for which ErrorCode returns // gcerrors.NotFound. 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 ErrorCode returns // gcerrors.Unimplemented. SignedURL(ctx context.Context, key string, opts *SignedURLOptions) (string, error) // Close cleans up any resources used by the Bucket. Once Close is called, // there will be no method calls to the Bucket other than As, ErrorAs, and // ErrorCode. There may be open readers or writers that will receive calls. // It is up to the driver as to how these will be handled. Close() error }
Bucket provides read, write and delete operations on objects within it on the blob service.
func NewPrefixedBucket ¶ added in v0.14.0
NewPrefixedBucket returns a Bucket based on b with all keys modified to have prefix.
type CopyOptions ¶ added in v0.13.0
type CopyOptions struct { // BeforeCopy is a callback that must be called before initiating the Copy. // asFunc allows providers to expose provider-specific types; // see Bucket.As for more details. BeforeCopy func(asFunc func(interface{}) bool) error }
CopyOptions controls options for Copy.
type ListObject ¶
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 // MD5 is an MD5 hash of the blob contents or nil if not available. MD5 []byte // 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 ¶
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. It is guaranteed to be >= 0. 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.
type ListPage ¶
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. // The portable type will not modify the returned ReaderAttributes. 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 ¶
type ReaderAttributes struct { // ContentType is the MIME type of the blob object. It must not be empty. // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type 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 ¶
type ReaderOptions struct { // BeforeRead is a callback that must be called exactly once before // any data is read, unless NewRangedReader returns an error before then, in // which case it should not be called at all. // asFunc allows providers to expose provider-specific types; // see Bucket.As for more details. BeforeRead func(asFunc func(interface{}) bool) error }
ReaderOptions controls Reader behaviors.
type SignedURLOptions ¶
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 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 // CacheControl specifies caching attributes that providers may use // when serving the blob. // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control CacheControl string // ContentDisposition specifies whether the blob content is expected to be // displayed inline or as an attachment. // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition ContentDisposition string // ContentEncoding specifies the encoding used for the blob's content, if any. // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding ContentEncoding string // ContentLanguage specifies the language used in the blob's content, if any. // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Language ContentLanguage string // ContentMD5 is used as a message integrity check. // The portable type checks that the MD5 hash of the bytes written matches // ContentMD5. // If len(ContentMD5) > 0, driver implementations may pass it to their // underlying network service to guarantee the integrity of the bytes in // transit. 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.