Crate cloud_storage

source ·
Expand description

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.

Structs

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.