b2

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2026 License: Apache-2.0 Imports: 27 Imported by: 18

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

View Source 
const (
	UnknownType BucketType = ""
	Private                = "allPrivate"
	Public                 = "allPublic"
	Snapshot               = "snapshot"
)

Variables

View Source 
var ErrClosed = errors.New("file already closed")

Functions

func IsNotExist 

func IsNotExist(err error) bool

IsNotExist reports whether a given error indicates that an object or bucket does not exist.

func IsUpdateConflict 

func IsUpdateConflict(err error) bool

IsUpdateConflict reports whether a given error is the result of a bucket update conflict.

Types

type AsReplicationDestination added in v0.9.0 

type AsReplicationDestination struct {
	SourceToDestinationKeyMapping map[string]string
}

type AsReplicationSource added in v0.7.0 

type AsReplicationSource struct {
	ReplicationRules       []ReplicationRules
	SourceApplicationKeyID string
}

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            // Can be "none" for large files.  If set on upload, will be used 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.
	Retention       *FileRetention    // Object Lock retention of this file, nil when it has none or the key may not read it.
	LegalHold       LegalHold         // Object Lock legal hold of this file, empty when unset or the key may not read it.
}

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 

func (b *Bucket) AuthToken(ctx context.Context, prefix string, valid time.Duration) (string, error)

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) BaseURL 

func (b *Bucket) BaseURL() string

BaseURL returns the base URL to use for all files uploaded to this bucket.

func (*Bucket) Copy added in v0.9.0 

func (b *Bucket) Copy(ctx context.Context, sourceFileID, destinationFileName string, opts ...CopyOption) (*Object, error)

Copy creates destinationFileName from sourceFileID without transferring the file's bytes through the caller. The copy is written to the receiver bucket unless CopyToBucket is given, and the source file may be in any bucket of the same account.

The resulting file must be smaller than 5 GB; B2 rejects a larger source with source_too_large unless CopyRange selects a smaller part of it. Copying a larger file takes b2_copy_part, which blazer does not wrap.

Copy does not expose B2's per-copy Object Lock (fileRetention, legalHold) or server-side encryption (sourceServerSideEncryption, destinationServerSideEncryption) parameters. The copy takes the destination bucket's defaults, and a source file encrypted with a customer-provided key (SSE-C) cannot be copied.

A copy that is retried after a lost response can leave an extra file version.

func (*Bucket) CreateKey added in v0.5.0 

func (b *Bucket) CreateKey(ctx context.Context, name string, opts ...KeyOption) (*Key, error)

CreateKey creates a scoped application key that is valid only for this bucket.

func (*Bucket) Delete 

func (b *Bucket) Delete(ctx context.Context) error

Delete removes a bucket. The bucket must be empty.

func (*Bucket) GetFileInfoByName added in v0.9.0 

func (b *Bucket) GetFileInfoByName(ctx context.Context, name string) (*Attrs, error)

GetFileInfoByName returns the current visible file's metadata without downloading the file. A missing or hidden name returns a not-exist error.

func (*Bucket) ID added in v0.9.0 

func (b *Bucket) ID() string

ID returns the bucket's B2 identifier, as reported when the bucket was created or listed. It makes no network call.

func (*Bucket) List added in v0.4.0 

func (b *Bucket) List(ctx context.Context, opts ...ListOption) *ObjectIterator

List returns an iterator for selecting objects in a bucket. The default behavior, with no options, is to list all currently un-hidden objects.

func (*Bucket) Name 

func (b *Bucket) Name() string

Name returns the bucket's name.

func (*Bucket) NotificationRules added in v0.9.0 

func (b *Bucket) NotificationRules(ctx context.Context) ([]NotificationRule, error)

NotificationRules retrieves this bucket's complete notification rule set.

func (*Bucket) Object 

func (b *Bucket) Object(name string) *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 

func (b *Bucket) Reveal(ctx context.Context, name string) error

Reveal unhides (if hidden) the named object. If there are multiple objects of a given name, it will reveal the most recent.

func (*Bucket) S3URL added in v0.7.0 

func (b *Bucket) S3URL() string

func (*Bucket) SetNotificationRules added in v0.9.0 

func (b *Bucket) SetNotificationRules(ctx context.Context, rules []NotificationRule) error

SetNotificationRules replaces this bucket's complete notification rule set. To add one rule, callers must first read the existing set, append the rule, and write the complete result.

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

	// The initial list (a JSON array) of CORS rules for this bucket.
	// See CORS Rules (https://www.backblaze.com/docs/cloud-storage-cross-origin-resource-sharing-rules) for an overview and the rule structure.
	CORSRules []CORSRule

	// The default Object Lock retention settings for this bucket. See Object Lock for an overview and the parameter structure.
	// If specified, the existing default bucket retention settings will be replaced with the new settings. If not specified,
	// the setting will remain unchanged. Setting the value requires the writeBucketRetentions capability and that the bucket is Object Lock-enabled.
	// Object Lock: https://www.backblaze.com/docs/cloud-storage-enable-object-lock-with-the-native-api.
	DefaultRetention *Retention
	// The default server-side encryption settings for this bucket. See Server-Side Encryption settings for new files uploaded to this bucket.
	// This field is filtered based on application key capabilities; readBucketEncryption capability is required to access the value.
	// See Server-Side Encryption for an overview and the parameter structure. If specified, the existing default bucket encryption settings will
	// be replaced with the new settings. If not specified, the setting will remain unchanged. Setting the value requires the writeBucketEncryption
	// capability. Server-Side Encryption settings: https://www.backblaze.com/docs/cloud-storage-enable-server-side-encryption-with-the-native-api.
	DefaultServerSideEncryption *ServerSideEncryption

	// If present, the Boolean value specifies whether the bucket has Object Lock enabled. Once Object Lock is enabled on a bucket, it cannot be disabled.
	// A value of true will be accepted if you have writeBucketRetentions capability. But you cannot enable Object Lock on a restricted bucket
	// (e.g. share buckets, snapshot) or on a bucket that contains source replication configuration.
	// A value of false will only be accepted if the bucket does not have Object Lock enabled. After enabling Object Lock on a bucket containing files with
	// metadata over the lower 2,048 byte limit, API requests to b2_update_file_retention and b2_update_file_legal_hold will be rejected. This is because
	// setting file retention or legal hold on a file adds additional headers when the file is downloaded, for example, with b2_download_file_by_name.
	// In such cases, you can use b2_copy_file with a REPLACE metadataDirective to copy the file, give it less metadata, and also specify the fileRetention
	// and legalHold parameters. The original file can then be deleted with b2_delete_file_version.
	// Object Lock: https://www.backblaze.com/docs/cloud-storage-enable-object-lock-with-the-native-api.
	FileLockEnabled bool

	// The configuration to create a Replication Rule. See Cloud Replication Rules. At least one of the asReplicationSource or asReplicationDestination
	// parameters is required, but they can also both be present.
	// NOTE: The first time that you configure Cloud Replication, complete the following tasks to ensure that you have the correct permission:
	// 1. Verify your email address.
	// 2. Have a payment history on file or make a payment.
	ReplicationConfig *ReplicationConfiguration
}

BucketAttrs holds a bucket's metadata attributes.

type BucketType 

type BucketType string

type CORSRule added in v0.7.0 

type CORSRule struct {
	Name              string
	AllowedOrigins    []string
	AllowedHeaders    []string
	AllowedOperations []string
	ExposeHeaders     []string
	MaxAgeSeconds     int
}

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a Backblaze B2 client.

func NewClient 

func NewClient(ctx context.Context, account, key string, opts ...ClientOption) (*Client, error)

NewClient creates and returns a new Client with valid B2 service account tokens.

func (*Client) Bucket 

func (c *Client) Bucket(ctx context.Context, name string) (*Bucket, error)

Bucket returns a bucket if it exists.

func (*Client) CreateKey added in v0.5.0 

func (c *Client) CreateKey(ctx context.Context, name string, opts ...KeyOption) (*Key, error)

CreateKey creates an application key for all buckets in the project, or for the buckets named by the BucketIDs option. The secret is only accessible on the returned Key.

func (*Client) ListBuckets 

func (c *Client) ListBuckets(ctx context.Context, bucketTypes ...string) ([]*Bucket, error)

ListBuckets returns all the available buckets.

func (*Client) ListKeys added in v0.5.0 

func (c *Client) ListKeys(ctx context.Context, count int, cursor string) ([]*Key, string, error)

ListKeys lists all the keys associated with this project. It takes the maximum number of keys it should return in a call, as well as a cursor (which should be empty for the initial call). It will return up to count keys, as well as the cursor for the next invocation.

ListKeys returns io.EOF when there are no more keys, although it may do so concurrently with the final set of keys.

func (*Client) NewBucket 

func (c *Client) NewBucket(ctx context.Context, name string, attrs *BucketAttrs) (*Bucket, error)

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) ServeHTTP added in v0.3.1 

func (c *Client) ServeHTTP(rw http.ResponseWriter, req *http.Request)

ServeHTTP serves diagnostic information about the current state of the client; essentially everything available from Client.Status()

ServeHTTP satisfies the http.Handler interface. This means that a Client can be passed directly to a path via http.Handle (or on a custom ServeMux or a custom http.Server).

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

func APIBase(url string) ClientOption

APIBase returns a ClientOption specifying the URL root of API requests.

func DefaultWriterOptions added in v0.5.0 

func DefaultWriterOptions(opts ...WriterOption) ClientOption

DefaultWriterOptions returns a ClientOption that will apply the given WriterOptions to every Writer. These options can be overridden by passing new options to NewWriter.

func ExpireSomeAuthTokens 

func ExpireSomeAuthTokens() ClientOption

ExpireSomeAuthTokens requests intermittent authentication failures from the B2 service by sending B2's documented X-Bz-Test-Mode: expire_some_account_authorization_tokens header. It is for testing re-authentication paths only; do not use it in production.

func FailSomeUploads 

func FailSomeUploads() ClientOption

FailSomeUploads requests intermittent upload failures from the B2 service by sending B2's documented X-Bz-Test-Mode: fail_some_uploads header. It is for testing retry and error-handling paths only; do not use it in production.

func ForceCapExceeded 

func ForceCapExceeded() ClientOption

ForceCapExceeded requests a cap limit from the B2 service by sending B2's documented X-Bz-Test-Mode: force_cap_exceeded header. This causes all uploads to be treated as if they would exceed the configured B2 capacity. It is for testing only; do not use it in production.

func Transport 

func Transport(rt http.RoundTripper) ClientOption

Transport sets the underlying HTTP transport mechanism. If unset, http.DefaultTransport is used.

func UserAgent added in v0.2.0 

func UserAgent(agent string) ClientOption

UserAgent sets the User-Agent HTTP header. The default header is "blazer/<version>"; the value set here will be prepended to that. This can be set multiple times.

A user agent is generally of the form "<product>/<version> (<comments>)".

type CopyOption added in v0.9.0 

type CopyOption func(*copyOptions)

CopyOption configures a Copy operation.

func CopyRange added in v0.9.0 

func CopyRange(byteRange string) CopyOption

CopyRange copies only the byte range specified by byteRange, in the form "bytes=0-99". Without it the whole source file is copied.

func CopyToBucket added in v0.9.0 

func CopyToBucket(destinationBucket *Bucket) CopyOption

CopyToBucket copies to destinationBucket, which must belong to the same account as the source file. Without this option, Copy writes to the receiver bucket.

func CopyWithMetadata added in v0.9.0 

func CopyWithMetadata(directive MetadataDirective, contentType string, info map[string]string) CopyOption

CopyWithMetadata sets the copy metadata directive. REPLACE copies use contentType and info as the destination's full metadata set, and need a non-empty contentType. COPY takes the source file's metadata, so combining it with a contentType or info is an error, as B2 documents. Copy returns the error without sending a request.

type DeleteOption added in v0.9.0 

type DeleteOption func(*deleteOptions)

DeleteOption configures Delete.

func BypassGovernance added in v0.9.0 

func BypassGovernance() DeleteOption

BypassGovernance requests deletion of a file under governance-mode Object Lock retention. The application key must have the bypassGovernance capability; B2 rejects the request for compliance-mode retention. https://www.backblaze.com/apidocs/b2-delete-file-version https://www.backblaze.com/docs/cloud-storage-object-lock

type FileRetention added in v0.9.0 

type FileRetention struct {
	Mode        RetentionMode
	RetainUntil time.Time
}

FileRetention is the Object Lock retention of a single file: a mode and the time until which the file cannot be deleted or changed. It is distinct from Retention, which is a bucket's default retention period.

type Key added in v0.5.0 

type Key struct {
	// contains filtered or unexported fields
}

Key is a B2 application key. A Key grants limited access on a global or per-bucket basis.

func (*Key) Capabilities added in v0.5.0 

func (k *Key) Capabilities() []string

Capabilities returns the list of capabilites granted by this application key.

func (*Key) Delete added in v0.5.0 

func (k *Key) Delete(ctx context.Context) error

Delete removes the key from B2.

func (*Key) Expires added in v0.5.0 

func (k *Key) Expires() time.Time

Expires returns the expiration date of this application key.

func (*Key) ID added in v0.5.1 

func (k *Key) ID() string

ID returns the application key ID. This, plus the secret, is necessary to authenticate to B2.

func (*Key) Name added in v0.5.0 

func (k *Key) Name() string

Name returns the user-supplied name of this application key. Key names are useless.

func (*Key) Secret added in v0.5.0 

func (k *Key) Secret() string

Secret returns the value that should be passed into NewClient(). It is only available on newly created keys; it is not available from ListKey operations.

type KeyOption added in v0.5.0 

type KeyOption func(*keyOptions)

KeyOption specifies desired properties for application keys.

func BucketIDs added in v0.9.0 

func BucketIDs(ids ...string) KeyOption

BucketIDs scopes the key to the given bucket IDs. A single ID produces a legacy single-bucket key; two or more produce a Multi-Bucket Application Key, which is usable only against B2 native API v4. Valid only on (*Client).CreateKey.

func Capabilities added in v0.5.1 

func Capabilities(caps ...string) KeyOption

Capabilities requests a key with the given capability.

func Deadline added in v0.5.0 

func Deadline(t time.Time) KeyOption

Deadline requests a key that expires after the given date.

func Lifetime added in v0.5.0 

func Lifetime(d time.Duration) KeyOption

Lifetime requests a key with the given lifetime.

func Prefix added in v0.5.0 

func Prefix(prefix string) KeyOption

Prefix limits the requested application key to be valid only for objects that begin with prefix. This can only be used when requesting an application key within a specific bucket.

type LegalHold added in v0.9.0 

type LegalHold string

LegalHold is an Object Lock legal hold state. 

const (
	LegalHoldOn  LegalHold = "on"
	LegalHoldOff LegalHold = "off"
)

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

type ListOption func(*objectIteratorOptions)

A ListOption alters the default behavior of List.

func ListDelimiter added in v0.4.0 

func ListDelimiter(delimiter string) ListOption

ListDelimiter 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 are actual objects, leave this unset.

func ListHidden added in v0.4.0 

func ListHidden() ListOption

ListHidden will include hidden objects in the output.

func ListLocker added in v0.4.4 

func ListLocker(l sync.Locker) ListOption

ListLocker passes the iterator a lock which will be held during network round-trips.

func ListPageSize added in v0.4.3 

func ListPageSize(count int) ListOption

ListPageSize configures the iterator to request the given number of objects per network round-trip. The default (and maximum) is 1000 objects, except for unfinished large files, which is 100.

func ListPrefix added in v0.4.0 

func ListPrefix(pfx string) ListOption

ListPrefix will restrict the output to objects whose names begin with prefix.

func ListUnfinished added in v0.4.0 

func ListUnfinished() ListOption

ListUnfinished will list unfinished large file operations instead of existing objects.

type MetadataDirective added in v0.9.0 

type MetadataDirective string

MetadataDirective controls whether Copy preserves or replaces file metadata. 

const (
	// CopyMetadata preserves the source file's content type and metadata.
	CopyMetadata MetadataDirective = "COPY"
	// ReplaceMetadata replaces the source file's content type and metadata.
	ReplaceMetadata MetadataDirective = "REPLACE"
)

type MethodList added in v0.3.1 

type MethodList []method

MethodList is an accumulation of RPC calls that have been made over a given period of time.

func (MethodList) CountByMethod added in v0.3.1 

func (ml MethodList) CountByMethod() map[string]int

CountByMethod returns the total RPC calls made per method.

type NotificationCustomHeader added in v0.9.0 

type NotificationCustomHeader struct {
	Name  string
	Value string
}

NotificationCustomHeader is an HTTP header B2 includes in a webhook call.

type NotificationRule added in v0.9.0 

type NotificationRule struct {
	EventTypes          []string
	IsEnabled           bool
	IsSuspended         bool
	Name                string
	ObjectNamePrefix    string
	SuspensionReason    string
	TargetConfiguration NotificationTargetConfiguration
}

NotificationRule configures B2 to deliver matching bucket events to a target. IsSuspended and SuspensionReason are returned by B2 when applicable.

type NotificationTargetConfiguration added in v0.9.0 

type NotificationTargetConfiguration struct {
	TargetType NotificationTargetType
	Webhook    *WebhookNotificationTarget
}

NotificationTargetConfiguration is a tagged union. B2 currently supports the webhook target type, whose values are selected by TargetType.

type NotificationTargetType added in v0.9.0 

type NotificationTargetType string

NotificationTargetType identifies a B2 notification target configuration. 

const (
	// NotificationTargetWebhook sends notifications to an HTTPS webhook.
	NotificationTargetWebhook NotificationTargetType = "webhook"
)

type Object 

type Object struct {
	// contains filtered or unexported fields
}

Object represents a B2 object.

func (*Object) Attrs 

func (o *Object) Attrs(ctx context.Context) (*Attrs, error)

Attrs returns an object's attributes.

func (*Object) AuthURL added in v0.5.0 

func (o *Object) AuthURL(ctx context.Context, valid time.Duration, b2cd string) (*url.URL, error)

AuthURL returns a URL for the given object with embedded token and, possibly, b2ContentDisposition arguments. Leave b2cd blank for no content disposition.

func (*Object) Cancel added in v0.7.0 

func (o *Object) Cancel(ctx context.Context) error

Cancel cancels a large file upload

func (*Object) Delete 

func (o *Object) Delete(ctx context.Context, opts ...DeleteOption) error

Delete removes the given object, if it is a regular file or hide marker.

func (*Object) Hide 

func (o *Object) Hide(ctx context.Context) error

Hide hides the object from name-based listing.

func (*Object) ID added in v0.6.0 

func (o *Object) ID() string

ID returns an object's id

func (*Object) Name 

func (o *Object) Name() string

Name returns an object's name

func (*Object) NewRangeReader 

func (o *Object) NewRangeReader(ctx context.Context, offset, length int64) *Reader

NewRangeReader returns a reader for the given object, reading up to length bytes. If length is negative, the rest of the object is read.

func (*Object) NewReader 

func (o *Object) NewReader(ctx context.Context) *Reader

NewReader returns a reader for the given object.

func (*Object) NewWriter 

func (o *Object) NewWriter(ctx context.Context, opts ...WriterOption) *Writer

NewWriter returns a new writer for the given object. Objects that are overwritten are not deleted, but are "hidden".

Callers must close the writer when finished and check the error status.

func (*Object) URL 

func (o *Object) URL() string

URL returns the full URL to the given object.

func (*Object) UpdateFileLegalHold added in v0.9.0 

func (o *Object) UpdateFileLegalHold(ctx context.Context, legalHold LegalHold) error

UpdateFileLegalHold sets the Object Lock legal hold of this file to LegalHoldOn or LegalHoldOff.

func (*Object) UpdateFileRetention added in v0.9.0 

func (o *Object) UpdateFileRetention(ctx context.Context, retention *FileRetention, bypassGovernance bool) error

UpdateFileRetention sets the Object Lock retention of this file. A nil retention removes it. Removing governance retention, or shortening it, needs bypassGovernance and a key with the bypassGovernance capability. Compliance retention can only be extended.

type ObjectIterator added in v0.4.0 

type ObjectIterator struct {
	// contains filtered or unexported fields
}

ObjectIterator abstracts away the tricky bits of iterating over a bucket's contents.

It is intended to be called in a loop: 

for iter.Next() {
  obj := iter.Object()
  // act on obj
}
if err := iter.Err(); err != nil {
  // handle err
}

func (*ObjectIterator) Err added in v0.4.0 

func (o *ObjectIterator) Err() error

Err returns the current error or nil. If Next() returns false and Err() is nil, then all objects have been seen.

func (*ObjectIterator) Next added in v0.4.0 

func (o *ObjectIterator) Next() bool

Next advances the iterator to the next object. It should be called before any calls to Object(). If Next returns true, then the next call to Object() will be valid. Once Next returns false, it is important to check the return value of Err().

func (*ObjectIterator) Object added in v0.4.0 

func (o *ObjectIterator) Object() *Object

Object returns the current object.

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 call with a ListDelimiter option.
	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.

func (*Reader) Close 

func (r *Reader) Close() error

Close frees resources associated with the download.

func (*Reader) Read 

func (r *Reader) Read(p []byte) (int, error)

func (*Reader) Verify added in v0.5.0 

func (r *Reader) Verify() (error, bool)

Verify checks the SHA1 hash on download and compares it to the SHA1 hash submitted on upload. If the two differ, this returns an error. If the correct hash could not be calculated (if, for example, the entire object was not read, or if the object was uploaded as a "large file" and thus the SHA1 hash was not sent), this returns (nil, false).

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

type ReplicationConfiguration struct {
	AsReplicationSource      AsReplicationSource
	AsReplicationDestination *AsReplicationDestination
}

type ReplicationRules added in v0.7.0 

type ReplicationRules struct {
	DestinationBucketID  string
	FileNamePrefix       string
	IncludeExistingFiles bool
	IsEnabled            bool
	Priority             int
	ReplicationRuleName  string
}

type Retention added in v0.7.0 

type Retention struct {
	Mode   string
	Period *RetentionPeriod
}

type RetentionMode added in v0.9.0 

type RetentionMode string

RetentionMode is an Object Lock retention mode. 

const (
	RetentionGovernance RetentionMode = "governance"
	RetentionCompliance RetentionMode = "compliance"
)

type RetentionPeriod added in v0.7.0 

type RetentionPeriod struct {
	Duration int
	Unit     string
}

type ServerSideEncryption added in v0.7.0 

type ServerSideEncryption struct {
	Mode      string
	Algorithm string
}

func DefaultServerSideEncryption deprecated added in v0.7.0 

func DefaultServerSideEncryption() *ServerSideEncryption

DefaultServerSideEncryption returns the SSE-B2 setting.

Deprecated: use SSEB2WithAES256.

func SSEB2WithAES256 added in v0.8.0 

func SSEB2WithAES256() *ServerSideEncryption

SSEB2WithAES256 returns the SSE-B2 server-side encryption setting with the AES256 algorithm. It is the only supported bucket default; leaving BucketAttrs.DefaultServerSideEncryption nil uses the service default.

type StatusInfo 

type StatusInfo struct {
	// Writers contains the status of all current uploads with progress.
	Writers map[string]*WriterStatus

	// Readers contains the status of all current downloads with progress.
	Readers map[string]*ReaderStatus

	// RPCs contains information about recently made RPC calls over the last
	// minute, five minutes, hour, and for all time.
	RPCs map[time.Duration]MethodList
}

StatusInfo reports information about a client.

type WebhookNotificationTarget added in v0.9.0 

type WebhookNotificationTarget struct {
	URL                     string
	CustomHeaders           []NotificationCustomHeader
	HMACSHA256SigningSecret string
	MaxEventsPerBatch       int
}

WebhookNotificationTarget configures a webhook notification target.

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 

func (w *Writer) Close() error

Close satisfies the io.Closer interface. It is critical to check the return value of Close for all writers.

func (*Writer) ReadFrom added in v0.2.0 

func (w *Writer) ReadFrom(r io.Reader) (int64, error)

ReadFrom reads all of r into w, returning the first error or no error if r returns io.EOF. If r is also an io.Seeker, ReadFrom will stream r directly over the wire instead of buffering it locally. This reduces memory usage.

Do not issue multiple calls to ReadFrom, or mix ReadFrom and Write. If you have multiple readers you want to concatenate into the same B2 object, use an io.MultiReader.

Note that io.Copy will automatically choose to use ReadFrom.

ReadFrom currently doesn't handle w.Resume; if w.Resume is true, ReadFrom will act as if r is not an io.Seeker.

func (*Writer) Write 

func (w *Writer) Write(p []byte) (int, error)

Write satisfies the io.Writer interface.

type WriterOption added in v0.5.0 

type WriterOption func(*Writer)

A WriterOption sets Writer-specific behavior.

func WithAttrsOption added in v0.5.0 

func WithAttrsOption(attrs *Attrs) WriterOption

WithAttrsOption attaches the given Attrs to the writer. It does not copy Attrs.Retention or Attrs.LegalHold; use WithFileRetention and WithLegalHold.

func WithCancelOnError added in v0.5.2 

func WithCancelOnError(ctxf func() context.Context, errf func(error)) WriterOption

WithCancelOnError requests the writer, if it has started a large file upload, to call b2_cancel_large_file on any permanent error. It calls ctxf to obtain a context with which to cancel the file; this is to allow callers to set specific timeouts. If errf is non-nil, then it is called with the (possibly nil) output of b2_cancel_large_file.

func WithFileRetention added in v0.9.0 

func WithFileRetention(retention *FileRetention) WriterOption

WithFileRetention sets Object Lock retention for the file uploaded by the writer.

func WithLegalHold added in v0.9.0 

func WithLegalHold(legalHold LegalHold) WriterOption

WithLegalHold sets Object Lock legal hold for the file uploaded by the writer.

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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.