~rjframe/b2-client

Backend-agnostic Backblaze B2 client for Rust
Validate capabilities before making API call
Add and fix documentation comments
Add copy_file function

refs

main
browse  log 

clone

read-only
https://git.sr.ht/~rjframe/b2-client
read/write
git@git.sr.ht:~rjframe/b2-client

You can also use your local clone with git send-email.

#b2-client - Backend-agnostic Backblaze B2 API Client

b2-client provides a Rust API to Backblaze B2 services, backed by any HTTP client.

Support for Hyper, Isahc (soon), 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.

#Table of Contents

#Introduction

I wanted a type-safe, backend-agnostic interface to the B2 API; I don't want to potentially end up with two HTTP clients linked into my applications, and I don't want the B2 library I use to be determined by the HTTP client (or async runtime) I happen to be using.

I intend to support the full API.

Note that most (if not all) of these functions can incur charges to your account. You will want to mock the B2 servers in your code's tests.

#License

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

#Getting Started

#Installation

I will not be registering b2-client on crates.io until I've implemented enough that I believe the library can be useful. To use this library now, you'll need to clone the git repository and add it as a path-based dependency.

[dependencies]
b2-client = { path = "../b2-client" }

If using a pre-packaged HTTP client, choose the backend via the relevant feature. Supported features are

  • with_surf
  • with_hyper
  • with_isahc (soon)

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

Surf is currently selected by default. To use a different backend, supply the --no-default-features flag as well as the feature for the backend you desire.

To use your own HTTP backend, implement the HttpClient trait and build with the --no-default-features flag.

#Testing

Run cargo test to run all tests; the surf backend is used to test fake (pre-recorded) responses against the B2 API, so by default no tests are making real API calls.

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 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), and a few tests will not pass their pre-recorded sessions with the environment variables set.

#Known Issues

#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