# 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](https://crates.io/crates/hyper),
[Isahc](https://crates.io/crates/isahc), and
[Surf](https://crates.io/crates/surf) are implemented out of the box.

The official repository for B2-client is on SourceHut at
[https://git.sr.ht/~rjframe/b2-client](https://git.sr.ht/~rjframe/b2-client),
with a mirror at Github on
[https://github.com/rjframe/b2-client](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](https://todo.sr.ht/~rjframe/b2-client)
* Discussions:
  [https://lists.sr.ht/~rjframe/public](https://lists.sr.ht/~rjframe/public)


## Table of Contents

* [Introduction](#introduction)
    * [License](#license)
* [Getting Started](#getting-started)
    * [Install](#installation)
    * [Testing](#testing)
    * [Known Issues](#known-issues)
* [Contributing](#contributing)
* [Contact](#contact)
* [Related Projects](#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](LICENSE.txt).

The source code of examples is licensed under the terms of the
[MIT license](examples/LICENSE.txt).


## 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](https://crates.io/crates/surf) HTTP client:

```shell
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](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](https://www.ryanjframe.com)
- diaspora*: rjframe@diasp.org


## Related Projects

* [b2_backblaze](https://crates.io/crates/b2_backblaze): Uses reqwest
* [raze](https://crates.io/crates/raze): Uses reqwest
* [backblaze-b2](https://crates.io/crates/backblaze-b2): Uses Hyper. Probably
  unmaintained