Crate cloud_storage

This crate aims to simplify interacting with the Google Cloud Storage JSON API. Use it until Google releases a Cloud Storage Client Library for Rust. Shoutout to MyEmma for funding this free and open source project.

Google Cloud Storage is a product by Google that allows for cheap file storage, with a relatively sophisticated API. The idea is that storage happens in Buckets, which are filesystems with a globally unique name. You can make as many of these Buckets as you like!

This project talks to Google using a Service Account. A service account is an account that you must create in the cloud storage console. When the account is created, you can download the file service-account-********.json. Store this file somewhere on your machine, and place the path to this file in the environment parameter SERVICE_ACCOUNT. Environment parameters declared in the .env file are also registered. The service account can then be granted Roles in the cloud storage console. The roles required for this project to function are Service Account Token Creator and Storage Object Admin.

Quickstart

Add the following line to your Cargo.toml

[dependencies]
cloud-storage = "0.10"

The two most important concepts are Buckets, which represent file systems, and Objects, which represent files.

Examples:

Creating a new Bucket in Google Cloud Storage:

let client = Client::default();
let bucket = client.bucket().create(&NewBucket {
    name: "doctest-bucket".to_string(),
    ..Default::default()
}).await?;

Connecting to an existing Bucket in Google Cloud Storage:

let client = Client::default();
let bucket = client.bucket().read("mybucket").await?;

Read a file from disk and store it on googles server:

let mut bytes: Vec<u8> = Vec::new();
for byte in File::open("myfile.txt")?.bytes() {
    bytes.push(byte?)
}
let client = Client::default();
client.object().create("mybucket", bytes, "myfile.txt", "text/plain").await?;

Renaming/moving a file

let client = Client::default();
let mut object = client.object().read("mybucket", "myfile").await?;
object.content_type = Some("application/xml".to_string());
client.object().update(&object).await?;

Removing a file

let client = Client::default();
client.object().delete("mybucket", "myfile").await?;

Re-exports

pub use crate::client::Client;

Modules

bucket

This complex object represents a Bucket that can be used to store and read files in Google Cloud Storage.

bucket_access_control

A Bucket Access Control object can be used to configure access on a bucket-wide level.

client

Clients for Google Cloud Storage endpoints.

common

Commonly used types.

default_object_access_control

Default Object Access Control objects can be used the configure access that is used as a fallback in the abscence of more specific data.

hmac_key

An Hmac key is a secret key stored in Cloud Storage.

object

A file

object_access_control

Contains data about to access specific files.

service_account

A deserialized version of the service-account-********.json file. Used to authenticate requests.

sync

Synchronous clients for Google Cloud Storage endpoints.

Structs

Bucket

The Buckets resource represents a bucket in Google Cloud Storage. There is a single global namespace shared by all buckets. For more information, see Bucket Name Requirements.

DownloadOptions

A set of parameters that can be used to customise signed urls.

ErrorList

A container for the error information.

GoogleError

Google Error structure

GoogleErrorResponse

The structure of a error response returned by Google.

ListRequest

The request that is supplied to perform Object::list. See the Google Cloud Storage API reference for more details.

NewBucket

A model that can be used to insert new buckets into Google Cloud Storage.

Object

A resource representing a file in Google Cloud Storage.

SERVICE_ACCOUNT

The struct is the parsed service account json file. It is publicly exported to enable easier debugging of which service account is currently used. It is of the type ServiceAccount.

Token

This struct contains a token, an expiry, and an access scope.

Enums

Error

Represents any of the ways storing something in Google Cloud Storage can fail.

Reason

Google provides a list of codes, but testing indicates that this list is not exhaustive.

Traits

TokenCache

Trait that refreshes a token when it is expired

Type Aliases

Result

A type alias where the error is set to be cloud_storage::Error.