Unofficial Cloudflare R2 SDK

This is the "Unofficial Cloudflare R2 SDK".

It can upload, download, and delete binary data or files to Cloudflare R2.

This crate is based on cloudflare-r2-rs (License: Apache-2.0, Owner: milen-denev) and r2sync (License: MIT, Owner: Songmu).

[!TIP] date: 2025-01-18

This crates is solved this problem by adding the following S3Client config.

requestChecksumCalculation: "WHEN_REQUIRED",
responseChecksumValidation: "WHEN_REQUIRED",

Reference: https://developers.cloudflare.com/r2/examples/aws/aws-sdk-js-v3/

News

• 2025-3-2 (JST): ver. 3.1.0 Release!

  Release Summary

• 2025-2-25 (JST): ver. 3.0.3 Release!

  Release Summary

• 2025-2-19 (JST): ver. 3.0.0 Release!

  Release Summary

Documentation

https://docs.rs/cf-r2-sdk/latest/cf_r2_sdk/

Article (Japanese)

https://qiita.com/Yuuki-Osada/items/10734e3d701a519b3d5f

DeepWiki

[!WARNING] The accuracy of the contents of generated deepwiki has not been verified by me.

I recommend that you look at the documentation at docs.rs.

https://deepwiki.com/Myxogastria0808/cf-r2-sdk

How to use

1. Create a aws_sdk_s3::Client object

Set the "bucket name", "access key id", "secret access key", "endpoint url", and "region".

Default value of region is "auto" (region is option field).

// create a client object
let object: Result<cf_r2_sdk::operator::Operator, cf_r2_sdk::error::Error> = Builder::new()
    .set_bucket_name("bucket_name")
    .set_access_key_id("access_key_id")
    .set_secret_access_key("secret_access_key")
    .set_endpoint("endpoint_url")
    .set_region("region")
    .create_client_result();

2. Operate R2 object strage

upload binary data

let _ = object
    .upload_binary("<file name (key)> as &str", "<mime type> as &str", "<binary data> as &[u8]", "<cache> as Option<&str> (None is 'no-cache')")
    .await.unwrap();

upload file

let _ = object
    .upload_file("<file name (key)> as &str", "<mime type> as &str", "<file path> as &str", "<cache> as Option<&str> (None is "no-cache")")
    .await.unwrap();

download binary data

let binany: Vec<u8> = object.download("<file name (key)> as &str").await.unwrap();

delete file

let _ = object.delete("<file name (key)> as &str").await.unwrap();

get file names vector (max get file names is 10)

let file_names_list:Vec<String> = object.list_objects().await.unwrap();

Example

https://github.com/Myxogastria0808/cf-r2-sdk/blob/main/examples/simple.rs

use cf_r2_sdk::builder::Builder;
use cf_r2_sdk::error::Error;
use dotenvy::dotenv;
use std::env;

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Error> {
    // load .env file
    dotenv().expect(".env file not found.");
    // insert a environment variable
    let bucket_name = env::var("BUCKET_NAME").expect("BUCKET_NAME not found in .env file.");
    let endpoint_url: String =
        env::var("ENDPOINT_URL").expect("ENDPOINT_URL not found in .env file.");
    let access_key_id: String =
        env::var("ACCESS_KEY_ID").expect("ACCESS_KEY_ID not found in .env file.");
    let secret_access_key: String =
        env::var("SECRET_ACCESS_KEY").expect("SECRET_ACCESS_KEY not found in .env file.");
    let region: String = env::var("REGION").expect("REGION not found in .env file.");

    let object: cf_r2_sdk::operator::Operator = Builder::new()
        .set_bucket_name(bucket_name)
        .set_access_key_id(access_key_id)
        .set_secret_access_key(secret_access_key)
        .set_endpoint(endpoint_url)
        .set_region(region)
        .create_client_result()?;

    // upload binary data
    object
        .upload_binary("simple.txt", "test/plain", b"Hello, World!", None)
        .await?;
    Ok(())
}