Documentation
¶
Overview ¶
Package b2 provides a high-level interface to Backblaze's B2 cloud storage service.
It is specifically designed to abstract away the Backblaze API details by providing familiar Go interfaces, specifically an io.Writer for object storage, and an io.Reader for object download. Handling of transient errors, including network and authentication timeouts, is transparent.
Methods that perform network requests accept a context.Context argument. Callers should use the context's cancellation abilities to end requests early, or to provide timeout or deadline guarantees.
This package is in development and may make API changes.
Index ¶
- Constants
- func IsNotExist(err error) bool
- func IsUpdateConflict(err error) bool
- type Attrs
- type Bucket
- func (b *Bucket) Attrs(ctx context.Context) (*BucketAttrs, error)
- func (b *Bucket) AuthToken(ctx context.Context, prefix string, valid time.Duration) (string, error)
- func (b *Bucket) BaseURL() string
- func (b *Bucket) Delete(ctx context.Context) error
- func (b *Bucket) ListCurrentObjects(ctx context.Context, count int, c *Cursor) ([]*Object, *Cursor, error)
- func (b *Bucket) ListObjects(ctx context.Context, count int, c *Cursor) ([]*Object, *Cursor, error)
- func (b *Bucket) Name() string
- func (b *Bucket) Object(name string) *Object
- func (b *Bucket) Reveal(ctx context.Context, name string) error
- func (b *Bucket) Update(ctx context.Context, attrs *BucketAttrs) error
- type BucketAttrs
- type BucketType
- type Client
- type ClientOption
- type Cursor
- type LifecycleRule
- type Object
- func (o *Object) Attrs(ctx context.Context) (*Attrs, error)
- func (o *Object) Delete(ctx context.Context) error
- func (o *Object) Hide(ctx context.Context) error
- func (o *Object) Name() string
- func (o *Object) NewRangeReader(ctx context.Context, offset, length int64) *Reader
- func (o *Object) NewReader(ctx context.Context) *Reader
- func (o *Object) NewWriter(ctx context.Context) *Writer
- func (o *Object) URL() string
- type ObjectState
- type Reader
- type ReaderStatus
- type StatusInfo
- type Writer
- type WriterStatus
Constants ¶
const ( UnknownType BucketType = "" Private = "allPrivate" Public = "allPublic" )
Variables ¶
This section is empty.
Functions ¶
func IsNotExist ¶
IsNotExist reports whether a given error indicates that an object or bucket does not exist.
func IsUpdateConflict ¶
IsUpdateConflict reports whether a given error is the result of a bucket update conflict.
Types ¶
type Attrs ¶
type Attrs struct {
Name string // Not used on upload.
Size int64 // Not used on upload.
ContentType string // Used on upload, default is "application/octet-stream".
Status ObjectState // Not used on upload.
UploadTimestamp time.Time // Not used on upload.
SHA1 string // Not used on upload. Can be "none" for large files.
LastModified time.Time // If present, and there are fewer than 10 keys in the Info field, this is saved on upload.
Info map[string]string // Save arbitrary metadata on upload, but limited to 10 keys.
}
Attrs holds an object's metadata.
type Bucket ¶
type Bucket struct {
// contains filtered or unexported fields
}
Bucket is a reference to a B2 bucket.
func (*Bucket) Attrs ¶
func (b *Bucket) Attrs(ctx context.Context) (*BucketAttrs, error)
Attrs retrieves and returns the current bucket's attributes.
func (*Bucket) AuthToken ¶
AuthToken returns an authorization token that can be used to access objects in a private bucket. Only objects that begin with prefix can be accessed. The token expires after the given duration.
func (*Bucket) ListCurrentObjects ¶
func (b *Bucket) ListCurrentObjects(ctx context.Context, count int, c *Cursor) ([]*Object, *Cursor, error)
ListCurrentObjects is similar to ListObjects, except that it returns only current, unhidden objects in the bucket.
func (*Bucket) ListObjects ¶
ListObjects returns all objects in the bucket, including multiple versions of the same object. Cursor may be nil; when passed to a subsequent query, it will continue the listing.
ListObjects will return io.EOF when there are no objects left in the bucket, however it may do so concurrently with the last objects.
func (*Bucket) Object ¶
Object returns a reference to the named object in the bucket. Hidden objects cannot be referenced in this manner; they can only be found by finding the appropriate reference in ListObjects.
func (*Bucket) Reveal ¶
Reveal unhides (if hidden) the named object. If there are multiple objects of a given name, it will reveal the most recent.
func (*Bucket) Update ¶
func (b *Bucket) Update(ctx context.Context, attrs *BucketAttrs) error
Update modifies the given bucket with new attributes. It is possible that this method could fail with an update conflict, in which case you should retrieve the latest bucket attributes with Attrs and try again.
type BucketAttrs ¶
type BucketAttrs struct {
// Type lists or sets the new bucket type. If Type is UnknownType during a
// bucket.Update, the type is not changed.
Type BucketType
// Info records user data, limited to ten keys. If nil during a
// bucket.Update, the existing bucket info is not modified. A bucket's
// metadata can be removed by updating with an empty map.
Info map[string]string
// Reports or sets bucket lifecycle rules. If nil during a bucket.Update,
// the rules are not modified. A bucket's rules can be removed by updating
// with an empty slice.
LifecycleRules []LifecycleRule
}
BucketAttrs holds a bucket's metadata attributes.
type BucketType ¶
type BucketType string
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a Backblaze B2 client.
func (*Client) ListBuckets ¶
ListBucket returns all the available buckets.
func (*Client) NewBucket ¶
NewBucket returns a bucket. The bucket is created with the given attributes if it does not already exist. If attrs is nil, it is created as a private bucket with no info metadata and no lifecycle rules.
func (*Client) Status ¶
func (c *Client) Status() *StatusInfo
Status returns information about the current state of the client.
type ClientOption ¶
type ClientOption func(*clientOptions)
A ClientOption allows callers to adjust various per-client settings.
func ExpireSomeAuthTokens ¶
func ExpireSomeAuthTokens() ClientOption
ExpireSomeAuthTokens requests intermittent authentication failures from the B2 service.
func FailSomeUploads ¶
func FailSomeUploads() ClientOption
FailSomeUploads requests intermittent upload failures from the B2 service. This is mostly useful for testing.
func ForceCapExceeded ¶
func ForceCapExceeded() ClientOption
ForceCapExceeded requests a cap limit from the B2 service. This causes all uploads to be treated as if they would exceed the configure B2 capacity.
func Transport ¶
func Transport(rt http.RoundTripper) ClientOption
Transport sets the underlying HTTP transport mechanism. If unset, http.DefaultTransport is used.
type Cursor ¶
type Cursor struct {
// Prefix limits the listed objects to those that begin with this string.
Prefix string
// Delimiter denotes the path separator. If set, object listings will be
// truncated at this character.
//
// For example, if the bucket contains objects foo/bar, foo/baz, and foo,
// then a delimiter of "/" will cause the listing to return "foo" and "foo/".
// Otherwise, the listing would have returned all object names.
//
// Note that objects returned that end in the delimiter may not be actual
// objects, e.g. you cannot read from (or write to, or delete) an object "foo/",
// both because no actual object exists and because B2 disallows object names
// that end with "/". If you want to ensure that all objects returned by
// ListObjects and ListCurrentObjects are actual objects, leave this unset.
Delimiter string
// contains filtered or unexported fields
}
Cursor is passed to ListObjects to return subsequent pages.
type LifecycleRule ¶
type LifecycleRule struct {
// Prefix specifies all the files in the bucket to which this rule applies.
Prefix string
// DaysUploadedUntilHidden specifies the number of days after which a file
// will automatically be hidden. 0 means "do not automatically hide new
// files".
DaysNewUntilHidden int
// DaysHiddenUntilDeleted specifies the number of days after which a hidden
// file is deleted. 0 means "do not automatically delete hidden files".
DaysHiddenUntilDeleted int
}
A LifecycleRule describes an object's life cycle, namely how many days after uploading an object should be hidden, and after how many days hidden an object should be deleted. Multiple rules may not apply to the same file or set of files. Be careful when using this feature; it can (is designed to) delete your data.
type Object ¶
type Object struct {
// contains filtered or unexported fields
}
Object represents a B2 object.
func (*Object) NewRangeReader ¶
NewRangeReader returns a reader for the given object, reading up to length bytes. If length is negative, the rest of the object is read.
type ObjectState ¶
type ObjectState int
ObjectState represents the various states an object can be in.
const ( Unknown ObjectState = iota // Started represents a large upload that has been started but not finished // or canceled. Started // Uploaded represents an object that has finished uploading and is complete. Uploaded // Hider represents an object that exists only to hide another object. It // cannot in itself be downloaded and, in particular, is not a hidden object. Hider // Folder is a special state given to non-objects that are returned during a // List*Objects call with a non-empty Delimiter. Folder )
type Reader ¶
type Reader struct {
// ConcurrentDownloads is the number of simultaneous downloads to pull from
// B2. Values greater than one will cause B2 to make multiple HTTP requests
// for a given file, increasing available bandwidth at the cost of buffering
// the downloads in memory.
ConcurrentDownloads int
// ChunkSize is the size to fetch per ConcurrentDownload. The default is
// 10MB.
ChunkSize int
// contains filtered or unexported fields
}
Reader reads files from B2.
type ReaderStatus ¶
type ReaderStatus struct {
// Progress is a slice of completion ratios. The index of a ratio is its
// chunk id less one.
Progress []float64
}
ReaderStatus reports the status for each reader.
type StatusInfo ¶
type StatusInfo struct {
Writers map[string]*WriterStatus
Readers map[string]*ReaderStatus
}
StatusInfo reports information about a client.
type Writer ¶
type Writer struct {
// ConcurrentUploads is number of different threads sending data concurrently
// to Backblaze for large files. This can increase performance greatly, as
// each thread will hit a different endpoint. However, there is a ChunkSize
// buffer for each thread. Values less than 1 are equivalent to 1.
ConcurrentUploads int
// Resume an upload. If true, and the upload is a large file, and a file of
// the same name was started but not finished, then assume that we are
// resuming that file, and don't upload duplicate chunks.
Resume bool
// ChunkSize is the size, in bytes, of each individual part, when writing
// large files, and also when determining whether to upload a file normally
// or when to split it into parts. The default is 100M (1e8) The minimum is
// 5M (5e6); values less than this are not an error, but will fail. The
// maximum is 5GB (5e9).
ChunkSize int
// UseFileBuffer controls whether to use an in-memory buffer (the default) or
// scratch space on the file system. If this is true, b2 will save chunks in
// FileBufferDir.
UseFileBuffer bool
// FileBufferDir specifies the directory where scratch files are kept. If
// blank, os.TempDir() is used.
FileBufferDir string
// contains filtered or unexported fields
}
Writer writes data into Backblaze. It automatically switches to the large file API if the file exceeds ChunkSize bytes. Due to that and other Backblaze API details, there is a large buffer.
Changes to public Writer attributes must be made before the first call to Write.
func (*Writer) Close ¶
Close satisfies the io.Closer interface. It is critical to check the return value of Close on all writers.
type WriterStatus ¶
type WriterStatus struct {
// Progress is a slice of completion ratios. The index of a ratio is its
// chunk id less one.
Progress []float64
}
WriterStatus reports the status for each writer.
Source Files