b2

package
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: Nov 11, 2026 License: Apache-2.0 Imports: 36 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

Examples

Constants

View Source 
const (
	UnknownType BucketType = ""
	Private                = "allPrivate"
	Public                 = "allPublic"
	Snapshot               = "snapshot"
)
View Source 
const MaxWebhookBodySize = 1 << 20

MaxWebhookBodySize is the maximum body accepted by the webhook helpers. HTTP handlers should also limit reads to this size before allocating body bytes.

Variables

View Source 
var ErrBucketIDsOnBucket = errors.New("BucketIDs cannot be combined with (*Bucket).CreateKey; use (*Client).CreateKey to request a multi-bucket key")

ErrBucketIDsOnBucket indicates that BucketIDs was passed to Bucket.CreateKey. BucketIDs is supported only by Client.CreateKey.

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

ErrInvalidAccountInfo identifies unusable cached session data. After AuthData, AccountInfoFile.Err reports an error matching it with errors.Is for malformed JSON or an oversized session file. Missing files and filesystem failures do not match it. Custom stores can wrap it when AuthData returns ok=false to request reauthorization.

View Source 
var ErrInvalidBucketIDs = errors.New("b2: BucketIDs requires a non-empty list of non-empty bucket IDs")

ErrInvalidBucketIDs indicates an explicitly empty BucketIDs scope or an empty bucket ID passed to Client.CreateKey.

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.

func SetupReplication added in v0.10.0 

func SetupReplication(ctx context.Context, src, dst *Bucket, sourceKeyID, destinationKeyID string, opts ...ReplicationOption) error

SetupReplication configures one-way replication using caller-owned application key IDs. Callers must provision and own bucket-scoped keys: the source key needs readFiles, readFileLegalHolds and readFileRetentions; the destination key needs writeFiles, writeFileLegalHolds, writeFileRetentions and deleteFiles. The helper neither creates keys nor validates their permissions.

The keys authenticating the bucket clients need listBuckets and readBucketReplications to read configurations. Clients that perform updates need writeBuckets and writeBucketReplications for the update-bucket requests. These are management capabilities, distinct from the file capabilities of the supplied replication keys. Adding a source rule requires update permission for both buckets, including retries: the destination update is repeated even if its mapping already matches. Repairing just a missing destination mapping needs update permission only for the destination. An exact existing rule and mapping need no update permission.

The helper preserves existing rules and key mappings. It rejects unreadable configurations, conflicting source keys or destination mappings, and an existing rule with the same name but different options or a disabled state. Repeating setup for an identical enabled rule and mapping makes no updates.

Source and destination must be different buckets. The helper allows at most two rules per source, with priorities from 1 through 2147483647 inclusive. The first rule defaults to priority 128; later rules default to five above the highest existing priority, capped at 2147483647.

Setup is not atomic: the destination mapping is stored before the source rule. If the source update fails, the mapping remains; retry with the same key IDs and options to finish setup.

func VerifySignature added in v0.10.0 

func VerifySignature(body []byte, signatureHeader, signingSecret string) error

VerifySignature verifies a B2 webhook signature for the raw request body. The v1= prefix is exact; hex digits in the signature may be either case. Call this before ParseEvent, and cap HTTP reads at MaxWebhookBodySize. B2 does not specify a timestamp freshness window; consumers should deduplicate at-least-once deliveries by eventId after verification.

Types

type AccountInfo added in v0.10.0 

type AccountInfo interface {
	Set(AuthData)
	AuthData() (AuthData, bool)
	Clear()
}

AccountInfo stores an authorized session. It never stores the application key secret; callers still supply that key to NewClient for reauthorization. All methods, including an optional Err method, must support concurrent calls, including when the store is shared by multiple clients.

AuthData must return ok=false for absent or unusable data. A store may also implement Err() error to report its most recent operation's error, or nil after success. After AuthData, nil or an error matching ErrInvalidAccountInfo permits reauthorization on a cache miss; any other error is returned to the caller. ErrInvalidAccountInfo does not override ok=true: an otherwise complete session for the requested key may still be reused. Incomplete or mismatched sessions cause reauthorization. Custom stores must return ok=false for invalid data. Errors observed after Set or Clear are returned, including ErrInvalidAccountInfo. A method call and its subsequent Err check are separate operations. When a store is shared across clients, another caller can overwrite an error or see it before the original caller checks it. Concurrent safety does not provide per-call error isolation; use separate store instances when that is needed.

type AccountInfoFile added in v0.10.0 

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

AccountInfoFile stores one authorized session in JSON. The file contains a live authorization token, but never the application key secret. Keep the file and its parent directory private. File I/O failures are available via Err because AccountInfo's Set and Clear methods have no error result. On Windows, privacy depends on the directory's ACLs rather than mode bits; put the session file under the user's profile directory, such as os.UserConfigDir().

func NewAccountInfoFile added in v0.10.0 

func NewAccountInfoFile(path string) *AccountInfoFile

NewAccountInfoFile selects an opt-in session file. Its parent directory is created with mode 0700; an existing parent must already be private. On Windows, these mode bits do not create a private ACL; use a directory under the user's profile, such as os.UserConfigDir().

func (*AccountInfoFile) AuthData added in v0.10.0 

func (a *AccountInfoFile) AuthData() (AuthData, bool)

AuthData reads the latest persisted session.

func (*AccountInfoFile) Clear added in v0.10.0 

func (a *AccountInfoFile) Clear()

Clear removes the persisted session before a 401-triggered reauthorization.

func (*AccountInfoFile) Err added in v0.10.0 

func (a *AccountInfoFile) Err() error

Err reports the last file operation error, if any. After AuthData, use errors.Is(err, ErrInvalidAccountInfo) to recognize malformed JSON or an oversized file. A missing file reports nil. Filesystem errors retain their underlying errors.Is and errors.As identity. Errors after Set or Clear are storage failures; they do not request reauthorization. Err reflects the most recent operation from any caller, so concurrent calls on a shared instance can replace an error before its originating client sees it.

func (*AccountInfoFile) Set added in v0.10.0 

func (a *AccountInfoFile) Set(data AuthData)

Set writes the session atomically with file mode 0600.

type AsReplicationDestination added in v0.9.0 

type AsReplicationDestination struct {
	// SourceToDestinationKeyMapping uses source application-key IDs as keys and
	// destination application-key IDs as values. Nil and empty maps omit the
	// mapping field in the current wire encoding and are left to B2 to validate.
	// Neither form is a supported way to clear the destination role.
	SourceToDestinationKeyMapping map[string]string
}

AsReplicationDestination maps source application keys to destination keys. An explicit destination in Bucket.Update replaces the existing mapping.

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.
	ServerSideEncryption *ServerSideEncryption // Server-side encryption applied to this file, nil when none was reported.
}

Attrs holds an object's metadata.

type AuthData added in v0.10.0 

type AuthData base.AuthData

AuthData is the authorized session snapshot stored by AccountInfo. It excludes the application key secret.

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. Negative, sub-second or excessive lifetimes return base.ErrInvalidDuration. Longer fractional durations truncate to whole seconds. Pass at least one second; the server rejects zero for download authorization.

func (*Bucket) BaseURL 

func (b *Bucket) BaseURL() string

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

func (*Bucket) Compose added in v0.10.0 

func (b *Bucket) Compose(ctx context.Context, name string, parts []ComposePart, opts ...ComposeOption) (object *Object, err error)

Compose creates a large file from uploaded and server-side copied parts in the supplied order. It requires at least two parts; every part except the last must be at least five million bytes. At most 10000 parts of at most five billion bytes each are allowed. Copy ranges from the same source file may overlap. Compose defaults the content type to application/octet-stream. The known total of uploaded parts and ranged copies may not exceed 10 TB (10,000,000,000,000 bytes); whole-file copies have an unknown size and are not counted toward that limit. For a final whole-file copy, validation of the part size and total file size is deferred to B2 after the large file starts. A service rejection cancels the unfinished file like any other part failure.

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. Use Compose to include a server-side copied range in a large file.

Copy does not expose B2's per-copy Object Lock (fileRetention, legalHold) parameters. Use CopySourceSSECKey for an SSE-C source and optionally CopyDestinationSSECKey to encrypt the destination with SSE-C; otherwise the destination bucket's default encryption applies.

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. Passing BucketIDs returns ErrBucketIDsOnBucket, even when supplied without IDs.

func (*Bucket) Delete 

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

Delete removes a bucket. The bucket must be empty.

func (*Bucket) DownloadFileByID added in v0.10.0 

func (b *Bucket) DownloadFileByID(ctx context.Context, id string, keys ...*SSECKey) (io.ReadCloser, error)

DownloadFileByID returns a reader for a file identified by its B2 file ID. It makes one download request; use Object.NewReader for chunked downloads by file name. Supply an SSE-C key for a customer-key-encrypted version; the key is used only on this request and is not retained.

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 B2 bucket ID reported when the bucket was created or listed. It makes no network call. Use it to populate ReplicationRules.DestinationBucketID when configuring replication.

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. A nil or empty slice clears every rule. To add or modify one rule, callers must first read the existing set, preserve the other rules, and write the complete result. B2 ignores the server-managed suspension fields on set. Suspended rules can only be deleted, not edited.

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

	// ReplicationConfig configures bucket replication. NewBucket uses the service
	// default when nil; Update leaves replication unchanged when nil.
	// Creation and updates reject empty configurations. Replication changes require
	// writeBucketReplications and normal bucket-update permissions. An Update that
	// preserves an unspecified role also requires readBucketReplications; provide
	// both roles explicitly to replace a configuration that cannot be read.
	// B2 requires a verified email and payment history before first configuration.
	ReplicationConfig *ReplicationConfiguration
	// contains filtered or unexported fields
}

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. An explicitly empty BucketIDs scope or any empty ID returns ErrInvalidBucketIDs before sending a create-key request.

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 applies the given options once to each initialized writer during NewWriter, before its explicit options. Custom callbacks do not run during NewClient or authorization. Pass WriterOptionFunc for a custom callback. Explicit options passed to NewWriter can override defaults. WithSSECKey cannot be a default, including with a nil key; NewClient rejects it before authorization. A nil WriterOption interface or WriterOptionFunc(nil) passed as a default makes NewClient return an error before authorization.

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>)".

func WithAccountInfo added in v0.10.0 

func WithAccountInfo(ai AccountInfo) ClientOption

WithAccountInfo uses the given session store. By default NewClient uses an InMemoryAccountInfo; NewAccountInfoFile opts in to persistence. The store must satisfy AccountInfo's concurrent-call and optional Err contract. A cache miss (ok=false with nil Err or an error matching ErrInvalidAccountInfo) triggers reauthorization. The sentinel does not invalidate ok=true data; otherwise complete sessions for the requested key may still be reused. Other read errors and errors observed after Set or Clear are returned. Err reflects the most recent operation from any caller; when a store is shared across clients, another call can overwrite an error or expose it to a different client before it is checked. Use separate stores for per-client error isolation.

type ComposeOption added in v0.10.0 

type ComposeOption func(*composeOptions)

ComposeOption configures metadata or Object Lock for Compose. Encryption is not currently supported; this variadic option slot permits adding it later without changing Compose's signature.

func ComposeFileRetention added in v0.10.0 

func ComposeFileRetention(retention *FileRetention) ComposeOption

ComposeFileRetention sets Object Lock retention on the composed file. A nil retention returns an error before a request is made.

func ComposeLegalHold added in v0.10.0 

func ComposeLegalHold(legalHold LegalHold) ComposeOption

ComposeLegalHold sets Object Lock legal hold on the composed file.

func ComposeWithAttrs added in v0.10.0 

func ComposeWithAttrs(attrs *Attrs) ComposeOption

ComposeWithAttrs sets the composed file's content type, file info, SHA1 and last-modified time. SHA1 and LastModified are always stored as large_file_sha1 and src_last_modified_millis when set; file-info size limits are left to the server. An empty ContentType keeps application/octet-stream. A nil Attrs returns an error before a request is made. It does not copy Attrs.Retention or Attrs.LegalHold; use ComposeFileRetention and ComposeLegalHold.

type ComposePart added in v0.10.0 

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

ComposePart describes one part of a composed large file. Parts are used in the order given to Compose.

func PartFromCopy added in v0.10.0 

func PartFromCopy(sourceFileID, byteRange string) ComposePart

PartFromCopy copies byteRange from sourceFileID as one part. The range has the form "bytes=0-4999999". An empty range copies the entire source and is allowed only for the final part. Its size is not looked up before Compose starts; B2 enforces its size limits after the large file has started.

func PartFromReader added in v0.10.0 

func PartFromReader(r io.Reader, size int64) ComposePart

PartFromReader uploads size bytes from r as one part.

type CopyOption added in v0.9.0 

type CopyOption func(*copyOptions)

CopyOption configures a Copy operation.

func CopyDestinationSSECKey added in v0.10.0 

func CopyDestinationSSECKey(key *SSECKey) CopyOption

CopyDestinationSSECKey encrypts the copied file with the supplied customer-managed key. Without this option, the destination bucket's default encryption applies. If the key has a caller-supplied ID, Copy stores that ID as sse_c_key_id in the destination's file info. A source key ID is not copied when the destination key has no ID.

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

func CopySourceSSECKey(key *SSECKey) CopyOption

CopySourceSSECKey supplies the customer-managed key used to decrypt an SSE-C source file during the server-side copy.

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. Passing nil makes Copy return an error before sending any request.

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

type Event struct {
	AccountID       string `json:"accountId"`
	BucketID        string `json:"bucketId"`
	BucketName      string `json:"bucketName"`
	EventID         string `json:"eventId"`
	EventTimestamp  int64  `json:"eventTimestamp"`
	EventType       string `json:"eventType"`
	EventVersion    int    `json:"eventVersion"`
	MatchedRuleName string `json:"matchedRuleName"`
	ObjectName      string `json:"objectName"`
	ObjectSize      *int64 `json:"objectSize,omitempty"`
	ObjectVersionID string `json:"objectVersionId,omitempty"`
}

Event is one event in a B2 webhook event-notification payload.

type EventNotification added in v0.10.0 

type EventNotification struct {
	Events []Event `json:"events"`
}

EventNotification is a B2 webhook event-notification payload.

func ParseEvent added in v0.10.0 

func ParseEvent(body []byte) (*EventNotification, error)

ParseEvent parses a B2 webhook event-notification payload. Call VerifySignature on the same raw body first; a valid JSON payload alone is not evidence that it came from B2.

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

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

InMemoryAccountInfo is the default, concurrency-safe session store.

func (*InMemoryAccountInfo) AuthData added in v0.10.0 

func (a *InMemoryAccountInfo) AuthData() (AuthData, bool)

AuthData returns a detached snapshot of the stored session.

func (*InMemoryAccountInfo) Clear added in v0.10.0 

func (a *InMemoryAccountInfo) Clear()

Clear removes the stored session.

func (*InMemoryAccountInfo) Set added in v0.10.0 

func (a *InMemoryAccountInfo) Set(data AuthData)

Set replaces the in-memory session.

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) BucketIDs added in v0.10.0 

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

BucketIDs returns the IDs of the buckets this application key is restricted to, or nil if the key is not restricted to any bucket. A key created with a single bucket reports one ID. The returned slice is a copy.

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, or the zero time if the key does not expire.

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) Prefix added in v0.10.0 

func (k *Key) Prefix() string

Prefix returns the file-name prefix this application key is restricted to, or "" if it has none.

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. The combined scope must contain at least one ID and no empty IDs, or Client.CreateKey returns ErrInvalidBucketIDs. Omit this option to create an account-wide key.

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. The duration from the time Deadline is called must satisfy Lifetime's bounds; CreateKey rejects past deadlines and deadlines less than one second away.

func Lifetime added in v0.5.0 

func Lifetime(d time.Duration) KeyOption

Lifetime requests a key with the given lifetime. A zero lifetime creates a non-expiring key. Otherwise the lifetime must be at least one second and below 1000 days; longer fractional durations truncate to whole seconds. CreateKey returns base.ErrInvalidDuration if invalid.

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. With no ListPageSize, or ListPageSize(0), object and version listings send maxFileCount 0, so B2 uses its default of 100. Unfinished large-file listings omit maxFileCount, and B2 likewise uses its default of 100.

The SDK limits object and version listings to 1000 objects, and unfinished large-file listings to 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 server-managed: B2 returns them when applicable and ignores them in SetNotificationRules.

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, keys ...*SSECKey) (*Attrs, error)

Attrs returns an object's attributes. Pass an SSE-C key to authorize the HEAD request used for an SSE-C object; the key is not retained.

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. Negative, sub-second or excessive lifetimes return base.ErrInvalidDuration. Longer fractional durations truncate to whole seconds. Pass at least one second; the server rejects zero for download authorization.

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. A nil DeleteOption returns an error before any request is sent. For the v0.9.0 method-type migration, see https://github.com/Backblaze/blazer/blob/main/docs/delete-options.md.

Example (Callbacks) 
package main

import (
	"context"

	"github.com/Backblaze/blazer/b2"
	"github.com/Backblaze/blazer/base"
)

// Compile the updated method-type declarations from docs/delete-options.md in CI.
var _ interface {
	Delete(context.Context, ...b2.DeleteOption) error
} = (*b2.Object)(nil)
var _ interface {
	DeleteFileVersion(context.Context, ...bool) error
} = (*base.File)(nil)
var _ func(context.Context, ...b2.DeleteOption) error = (*b2.Object)(nil).Delete
var _ func(context.Context, ...bool) error = (*base.File)(nil).DeleteFileVersion

func deleteCallback(object *b2.Object) func(context.Context) error {
	return func(ctx context.Context) error { return object.Delete(ctx) }
}

func deleteFileCallback(file *base.File) func(context.Context) error {
	return func(ctx context.Context) error { return file.DeleteFileVersion(ctx) }
}

func main() {
	var object *b2.Object // Supply the object whose version should be deleted.
	var file *base.File   // Or the low-level file version.
	objectCallback := deleteCallback(object)
	fileCallback := deleteFileCallback(file)
	_ = objectCallback
	_ = fileCallback
}

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, keys ...*SSECKey) *Reader

NewRangeReader returns a reader for the given object, reading up to length bytes. A zero length returns no bytes and makes no download request. If length is negative, the rest of the object is read. With a Progress callback, a finite range reports the available byte count when a HEAD request can determine it; otherwise the progress total is -1.

func (*Object) NewReader 

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

NewReader returns a reader for the given object. Pass an SSE-C key when the object was encrypted with a customer-managed key; the key is not retained by the Object, Bucket or Client.

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. Default options and then opts are applied synchronously to the initialized writer before NewWriter returns.

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

	// Progress receives cumulative downloaded bytes. It runs on one owner
	// goroutine, never under a transfer lock; values are monotonic non-decreasing
	// and end with a final call at the bytes downloaded before Close returns.
	// Updates may be coalesced, so an intermediate value is not guaranteed.
	// Neither reaching total nor receiving a terminal callback indicates success;
	// always check read errors.
	// For a finite range, total is the actual available byte count (not the
	// requested upper bound) when a HEAD request can determine it; otherwise
	// total is -1. Set Progress before the first Read. Calling Close from this
	// callback is unsupported because Close waits for the callback to finish.
	Progress func(bytesComplete, bytesTotal int64)
	// 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 is unspecified when its key ID is empty and it has no rules.
	AsReplicationSource AsReplicationSource
	// AsReplicationDestination specifies the destination key mapping. When nil
	// in a source-only Update, the known destination mapping is preserved.
	AsReplicationDestination *AsReplicationDestination
}

ReplicationConfiguration describes a bucket's source and destination roles. Both roles may be present. Creation and replication updates require a non-empty configuration. In an Update, an unspecified role is preserved and requires a readable existing configuration. Providing both roles replaces them without a merge. A nil BucketAttrs.ReplicationConfig leaves even unreadable settings alone. Clearing replication is not supported by this high-level representation.

type ReplicationOption added in v0.10.0 

type ReplicationOption func(*replicationOptions)

ReplicationOption configures SetupReplication.

func WithFileNamePrefix added in v0.10.0 

func WithFileNamePrefix(prefix string) ReplicationOption

WithFileNamePrefix limits the rule to files whose names begin with prefix.

func WithIncludeExistingFiles added in v0.10.0 

func WithIncludeExistingFiles(include bool) ReplicationOption

WithIncludeExistingFiles includes files already in the source bucket.

func WithRuleName added in v0.10.0 

func WithRuleName(name string) ReplicationOption

WithRuleName names the new replication rule.

func WithRulePriority added in v0.10.0 

func WithRulePriority(priority int) ReplicationOption

WithRulePriority sets the new rule's priority, from 1 through 2147483647 inclusive.

type ReplicationRuleStatus added in v0.10.0 

type ReplicationRuleStatus struct{ ReplicationRules }

ReplicationRuleStatus describes one configured rule and its enabled state. It does not report per-file replication progress.

func ReplicationStatus added in v0.10.0 

func ReplicationStatus(ctx context.Context, src *Bucket) ([]ReplicationRuleStatus, error)

ReplicationStatus returns all of the source bucket's configured replication rules, including disabled rules. It reports an error if the configuration cannot be read. It does not scan files or report per-file replication progress. The bucket client's key needs listBuckets and readBucketReplications.

type ReplicationRules added in v0.7.0 

type ReplicationRules struct {
	// DestinationBucketID is the B2 bucket ID of the destination bucket.
	// Use destination.ID(), not destination.Name().
	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 SSECKey added in v0.10.0 

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

SSECKey is a caller-provided AES-256 key for server-side encryption with customer-managed keys. It is used only for the request on which it is passed; Client and Bucket never retain it.

SSECKey's formatted representation is always redacted.

func NewSSECKey added in v0.10.0 

func NewSSECKey(key []byte) (*SSECKey, error)

NewSSECKey validates and copies a raw 32-byte AES-256 key. The caller remains responsible for retaining the key; Backblaze cannot recover it.

func NewSSECKeyWithID added in v0.10.0 

func NewSSECKeyWithID(key []byte, id string) (*SSECKey, error)

NewSSECKeyWithID attaches a caller-chosen identifier to an SSE-C key. The identifier is saved as sse_c_key_id in file info for every SSE-C upload, visible to file-info readers, and must uniquely identify the key for safe large-file resume. Choose an opaque stable ID, not the key or a key-derived value. An empty ID behaves like NewSSECKey and cannot resume an SSE-C large file. The key and ID remain per-request, not Client defaults.

func (SSECKey) Format added in v0.10.0 

func (k SSECKey) Format(state fmt.State, _ rune)

Format redacts the key for every formatting verb.

func (SSECKey) GoString added in v0.10.0 

func (k SSECKey) GoString() string

func (SSECKey) String added in v0.10.0 

func (k SSECKey) String() 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. SSE-C resume
	// requires a matching caller-supplied key ID (NewSSECKeyWithID) saved as
	// sse_c_key_id in file info; missing or different IDs are rejected. The ID
	// must uniquely identify the key: B2 rejects wrong keys on uploaded parts,
	// but receives no key if every existing part is skipped.
	// WithFileRetention and WithLegalHold must match the unfinished file when
	// supplied. Unspecified lock settings keep the unfinished file's settings;
	// omitting the options does not request removal of existing protection.
	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: an upload of at most ChunkSize bytes is
	// sent as a single file.  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 waits for in-flight part uploads and, when WithCancelOnError is set, for the b2_cancel_large_file call and errf to finish before it returns. Give the context returned by ctxf a deadline to bound the cancellation RPC's wait. errf must return promptly and must not call Close or wait on the goroutine calling Close, or they will deadlock. The context deadline does not bound errf. It is critical to check Close's return value.

func (*Writer) ReadFrom added in v0.2.0 

func (w *Writer) ReadFrom(r io.Reader) (n int64, err 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.

On every path, ReadFrom returns the Writer's error when it cancels itself; caller cancellation returns context.Canceled or context.DeadlineExceeded, even if the caller supplied a custom cause. If the Writer's context is cancelled while copying from a non-seekable r, ReadFrom returns without waiting for a Read on r that is already in progress. When the Writer cancels itself, ReadFrom returns the same first recorded error as Close, so errors.Is and errors.As work and io.Copy sees it rather than context.Canceled. Once ReadFrom has returned, nothing more from r is written to w; data read before cancellation may already have been written. That pending Read may still finish later, so do not reuse r until it has returned (for example, close r first if it supports it).

With Resume, ReadFrom uses the ordinary buffered path; if r is seekable, its remaining length supplies the progress total.

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 interface {
	// contains filtered or unexported methods
}

A WriterOption sets Writer-specific behavior when NewWriter constructs a writer. Use WriterOptionFunc to adapt a custom callback. Options are not callable; compose them in a []WriterOption passed to NewWriter or DefaultWriterOptions.

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 fresh context with which to cancel the file; give that context a deadline to bound the cancellation RPC's wait. If errf is non-nil, it receives the (possibly nil) output of b2_cancel_large_file. The errf callback may run on a background goroutine, and Close waits for it to finish. The context deadline does not bound errf: it must return promptly and must not call Close or wait on the goroutine that calls Close, or they will deadlock.

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.

func WithProgress added in v0.10.0 

func WithProgress(cb func(bytesComplete, bytesTotal int64)) WriterOption

WithProgress sets a callback that receives cumulative upload payload progress. New bytes are counted as they are read for upload; resuming also credits bytes in completed parts already present in B2. Bytes read again for retries are not counted twice. Progress does not indicate B2 acceptance: complete may equal total even when the upload fails. Always check Close's error for success.

The callback runs on one owner goroutine, never under a transfer lock. Values are monotonic non-decreasing and end with a final call before Close returns. Updates may be coalesced, so an intermediate value is not guaranteed. The total is known for ReadFrom readers that implement io.Seeker (including resume), and is -1 otherwise. Calling Close from this callback is unsupported because Close waits for the callback to finish.

func WithSSEB2 added in v0.10.0 

func WithSSEB2(algorithm string) WriterOption

WithSSEB2 encrypts this upload with a B2-managed key using algorithm. It overrides the bucket's default for this upload only; the setting is used for a simple upload request or the large-file start request. It carries no customer-managed key material. Only "AES256" is supported. Invalid values cause the operation that starts the upload (Write for multipart uploads or Close for simple uploads) to return an error before sending an upload request. An explicit writer encryption option overrides inherited client defaults. Combining WithSSEB2 and WithSSECKey in one NewWriter call causes a non-empty Write and Close to return an error.

func WithSSECKey added in v0.10.0 

func WithSSECKey(key *SSECKey) WriterOption

WithSSECKey encrypts this upload with a caller-provided AES-256 key. The key is used for the simple upload request or for the large-file start request and every part upload; it is never retained by the Object, Bucket or Client. A caller-supplied ID from NewSSECKeyWithID is saved as sse_c_key_id in file info for every SSE-C upload. For large files, it permits resume. Without an ID, resume fails closed. B2 rejects a wrong key on uploaded parts, but cannot check it when all existing parts are skipped, so callers must not reuse an ID for another key. This option adds neither the key nor a key-derived value to file info. Before any request, uploads reject caller file info with a conflicting sse_c_key_id in any letter case, an ID for a key without one, or more than 10 entries after adding the key ID. It cannot be used with DefaultWriterOptions, including with a nil key.

type WriterOptionFunc added in v0.10.0 

type WriterOptionFunc func(*Writer)

WriterOptionFunc adapts a custom callback to a WriterOption. NewWriter calls it synchronously on the initialized writer. As a default, it runs once per writer, never during NewClient or authorization. The callback must not be nil.

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

Directories

Path Synopsis
Package sync pushes a local directory tree into a B2 bucket prefix.
 Package sync pushes a local directory tree into a B2 bucket prefix.

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.