B2-client - Backend-agnostic Backblaze B2 API Client

B2-client provides a Rust API to Backblaze B2 cloud storage service, backed by any async HTTP client utilizing any async runtime.

Support for Hyper, Isahc, and Surf are implemented out of the box.

The official repository for B2-client is on SourceHut at https://git.sr.ht/~rjframe/b2-client, with a mirror at Github on https://github.com/rjframe/b2-client. Patches/pull requests from both are accepted; all other activity takes place at SourceHut.

• Issues: https://todo.sr.ht/~rjframe/b2-client
• Discussions: https://lists.sr.ht/~rjframe/public

Table of Contents

• Introduction
  • License
• Getting Started
  • Install
  • Testing
  • Known Issues
• Contributing
• Contact
• Related Projects

Introduction

B2-client is an async runtime-agnostic, HTTP client-agnostic interface to the Backblaze B2 API. The full B2 API is supported.

Note that most of these functions can incur charges to your account.

License

All library source code is licensed under the terms of the MPL 2.0 license.

The source code of examples is licensed under the terms of the MIT license.

Getting Started

Installation

To use a pre-packaged HTTP client, choose the backend via the relevant feature. Supported features are:

• with_hyper
• with_surf
• with_isahc

This list will eventually use the lower-level client libraries instead (e.g., h1 instead of hyper).

Add b2-client as a dependency via cargo; for example, to use the Surf HTTP client:

cargo add b2-client --features with_surf

There is no default client, so you must choose one of the above features or use a custom HTTP client. To use your own HTTP backend, simply implement the HttpClient trait then pass the struct to account::authorize_account.

Testing

API calls are faked via pre-recorded sessions using the surf backend, so to run all tests run cargo test --features=with_surf. No test runs against the live B2 service by default.

To run a test against the live B2 API, set the environment variables B2_CLIENT_TEST_KEY and B2_CLIENT_TEST_KEY_ID to a key/id pair capable of performing the task you wish to test, and change the test's VcrMode to Record. Although there will be no major-destructive tests (like deleting all buckets), don't run a test against the live API unless you know what it's doing, especially if you have production keys or buckets on your account.

A few tests will need minor modifications or setup to run against the B2 API (e.g., deleting a bucket, changing the bucket ID), and a few tests will not pass their pre-recorded sessions if the environment variables are set.

Known Issues

• Error handling is bifurcated a bit; for example, uploading a file without the WriteFiles capability will return Error::Unauthorized, but uploading to a private bucket without the ReadFiles capabillity returns Error::B2Error.

  This is due to the fact that we can validate authorization to write prior to making the API call, but cannot pre-validate the authorization to read. This is solveable; it just requires determining the best method to merge them.

Contributing

Patches and pull requests are welcome. For major features or breaking changes, please open a ticket or start a discussion first so we can discuss what you would like to do.

See CONTRIBUTING.md for pointers on getting set up. If you'd like guidance on anything feel free to ask in a discussion or ticket, or submit a draft PR.

Contact

• Email: code@ryanjframe.com
• Website: www.ryanjframe.com
• diaspora*: rjframe@diasp.org

Related Projects

• b2_backblaze: Uses reqwest
• raze: Uses reqwest
• backblaze-b2: Uses Hyper. Probably unmaintained