Blazer

Blazer is a Golang client library for Backblaze B2 Cloud Object Storage.

import "github.com/Backblaze/blazer/b2"

Blazer targets the Backblaze B2 Native API. Unless you specifically need to access Backblaze B2 via its Native API, you should use the MinIO Go Client SDK with Backblaze B2's S3 Compatible SDK.

Many thanks to Toby Burress (kurin) for creating and maintaining Blazer for its first six years.

Examples

Getting started

import "os"

id := os.Getenv("B2_APPLICATION_KEY_ID")
key := os.Getenv("B2_APPLICATION_KEY")

ctx := context.Background()

// b2_authorize_account
b2, err := b2.NewClient(ctx, id, key)
if err != nil {
	log.Fatalln(err)
}

buckets, err := b2.ListBuckets(ctx)
if err != nil {
	log.Fatalln(err)
}

Copy a file into B2

func copyFile(ctx context.Context, bucket *b2.Bucket, src, dst string) error {
	f, err := os.Open(src)
	if err != nil {
		return err
	}
	defer f.Close()

	obj := bucket.Object(dst)
	w := obj.NewWriter(ctx)
	if _, err := io.Copy(w, f); err != nil {
		w.Close()
		return err
	}
	return w.Close()
}

If the file is less than 100MB, Blazer will simply buffer the file and use the b2_upload_file API to send the file to Backblaze. If the file is greater than 100MB, Blazer will use B2's large file support to upload the file in 100MB chunks.

Copy a file into B2, with multiple concurrent uploads

Uploading a large file with multiple HTTP connections is simple:

func copyFile(ctx context.Context, bucket *b2.Bucket, writers int, src, dst string) error {
	f, err := os.Open(src)
	if err != nil {
		return err
	}
	defer f.Close()

	w := bucket.Object(dst).NewWriter(ctx)
	w.ConcurrentUploads = writers
	if _, err := io.Copy(w, f); err != nil {
		w.Close()
		return err
	}
	return w.Close()
}

This will automatically split the file into writers chunks of 100MB uploads. Note that 100MB is the smallest chunk size that B2 supports.

Download a file from B2

Downloading is as simple as uploading:

func downloadFile(ctx context.Context, bucket *b2.Bucket, downloads int, src, dst string) error {
	r := bucket.Object(src).NewReader(ctx)
	defer r.Close()

	f, err := os.Create(dst)
	if err != nil {
		return err
	}
	r.ConcurrentDownloads = downloads
	if _, err := io.Copy(f, r); err != nil {
		f.Close()
		return err
	}
	return f.Close()
}

List all objects in a bucket

func printObjects(ctx context.Context, bucket *b2.Bucket) error {
	iterator := bucket.List(ctx)
	for iterator.Next() {
		fmt.Println(iterator.Object())
	}
	return iterator.Err()
}

Grant temporary auth to a file

Say you have a number of files in a private bucket, and you want to allow other people to download some files. This is possible to do by issuing a temporary authorization token for the prefix of the files you want to share.

token, err := bucket.AuthToken(ctx, "photos", time.Hour)

If successful, token is then an authorization token valid for one hour, which can be set in HTTP GET requests.

The hostname to use when downloading files via HTTP is account-specific and can be found via the BaseURL method:

base := bucket.BaseURL()

Testing resilience with B2 test mode

B2 provides documented "test mode" hooks (sent as the X-Bz-Test-Mode request header) that ask the service to inject controlled failures, so you can exercise your retry and error-handling paths without waiting for real faults. blazer exposes each one as a client option:

// Ask B2 to fail some uploads so you can verify your upload retries.
client, err := b2.NewClient(ctx, id, key, b2.FailSomeUploads())

Option	X-Bz-Test-Mode value	Effect
b2.FailSomeUploads()	fail_some_uploads	B2 fails some uploads, exercising upload retries.
b2.ExpireSomeAuthTokens()	expire_some_account_authorization_tokens	B2 expires account authorization tokens frequently, exercising re-authentication.
b2.ForceCapExceeded()	force_cap_exceeded	B2 behaves as if the account storage cap were exceeded. Backblaze documents it for upload- and download-related calls.

Backblaze documents each value on its own and does not say whether several can be combined. Enabling more than one option sends one X-Bz-Test-Mode header line per option. blazer's live integration tests combine b2.FailSomeUploads() and b2.ExpireSomeAuthTokens(), but that does not establish that every combination is supported by the B2 service, so prefer one option per client unless you have verified the combination you need.

The header is set when the client is created and sent with every request that client makes, including authorization and downloads. There is no way to turn it off afterwards, so create a separate client for tests and leave these options off in production. See Backblaze's Integration Checklist for the authoritative behavior.

Licenses

The b2 package currently does not consume any third party packages and entirely depends on imports of the Go stdlib or from sources provided within the blazer repository itself. A report of used licenses can be found at ./b2/licenses.csv which was generated with https://github.com/google/go-licenses . Please double check yourself if this is a concern as this may change over time and the licenses report could become stale