Struct s3::bucket::Bucket

pub struct Bucket {
    pub name: String,
    pub region: Region,
    pub credentials: Credentials,
    pub extra_headers: HashMap<String, String>,
    pub extra_query: HashMap<String, String>,
    // some fields omitted
}

Example

use s3::bucket::Bucket;
use awscreds::Credentials;

let bucket_name = "rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default().unwrap();

let bucket = Bucket::new(bucket_name, region, credentials);

Fields

name: String

region: Region

credentials: Credentials

extra_headers: HashMap<String, String>

extra_query: HashMap<String, String>

Implementations

impl Bucket

pub fn presign_get<S: AsRef<str>>(
    &self,
    path: S,
    expiry_secs: u32
) -> Result<String>

Get a presigned url for getting object on a given path

Example:

use s3::bucket::Bucket;
use awscreds::Credentials;

let bucket_name = "rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default().unwrap();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let url = bucket.presign_get("/test.file", 86400).unwrap();
println!("Presigned url: {}", url);

pub fn presign_put<S: AsRef<str>>(
    &self,
    path: S,
    expiry_secs: u32
) -> Result<String>

Get a presigned url for putting object to a given path

Example:

use s3::bucket::Bucket;
use awscreds::Credentials;

let bucket_name = "rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default().unwrap();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let url = bucket.presign_put("/test.file", 86400).unwrap();
println!("Presigned url: {}", url);

pub fn new(
    name: &str,
    region: Region,
    credentials: Credentials
) -> Result<Bucket>

Instantiate a new Bucket.

Example

use s3::bucket::Bucket;
use awscreds::Credentials;

let bucket_name = "rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default().unwrap();

let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

pub fn new_public(name: &str, region: Region) -> Result<Bucket>

pub fn new_with_path_style(
    name: &str,
    region: Region,
    credentials: Credentials
) -> Result<Bucket>

pub fn new_public_with_path_style(name: &str, region: Region) -> Result<Bucket>

pub fn get_object_blocking<S: AsRef<str>>(
    &self,
    path: S
) -> Result<(Vec<u8>, u16)>

Gets file from an S3 path, blocks.

Example:

use s3::bucket::Bucket;
use awscreds::Credentials;

let bucket_name = "rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default().unwrap();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let (data, code) = bucket.get_object_blocking("/test.file").unwrap();
println!("Code: {}\nData: {:?}", code, data);

pub async fn get_object<'_, S: AsRef<str>>(
    &'_ self,
    path: S
) -> Result<(Vec<u8>, u16)>

Gets file from an S3 path, async.

Example:

use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;

#[tokio::main]
async fn main() -> Result<(), S3Error> {

    let bucket_name = "rust-s3-test";
    let region = "us-east-1".parse()?;
    let credentials = Credentials::default()?;
    let bucket = Bucket::new(bucket_name, region, credentials)?;

    let (data, code) = bucket.get_object("/test.file").await?;
    println!("Code: {}", code);
    println!("{:?}", data);
    Ok(())
}

pub fn get_object_stream_blocking<T: Write>(
    &self,
    path: &str,
    writer: &mut T
) -> Result<u16>

Stream file from S3 path to a local file, generic over T: Write, blocks.

Example:

use s3::bucket::Bucket;
use awscreds::Credentials;
use std::fs::File;

let bucket_name = "rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default().unwrap();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();
let mut output_file = File::create("output_file").expect("Unable to create file");

let code = bucket.get_object_stream_blocking("/test.file", &mut output_file).unwrap();
println!("Code: {}", code);

pub async fn get_object_stream<'_, '_, T: Write, S: AsRef<str>>(
    &'_ self,
    path: S,
    writer: &'_ mut T
) -> Result<u16>

Stream file from S3 path to a local file, generic over T: Write, async.

Example:

use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;
use std::fs::File;

#[tokio::main]
async fn main() -> Result<(), S3Error> {

    let bucket_name = "rust-s3-test";
    let region = "us-east-1".parse()?;
    let credentials = Credentials::default()?;
    let bucket = Bucket::new(bucket_name, region, credentials)?;
    let mut output_file = File::create("output_file").expect("Unable to create file");

    let status_code = bucket.get_object_stream("/test.file", &mut output_file).await?;
    println!("Code: {}", status_code);
    Ok(())
}

pub async fn tokio_get_object_stream<'_, '_, T: AsyncWriteExt + Unpin, S: AsRef<str>>(
    &'_ self,
    path: S,
    writer: &'_ mut T
) -> Result<u16>

Stream file from S3 path to a local file, generic over T: Write, async.

Example:

use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;
use std::fs::File;

#[tokio::main]
async fn main() -> Result<(), S3Error> {

    let bucket_name = "rust-s3-test";
    let region = "us-east-1".parse()?;
    let credentials = Credentials::default()?;
    let bucket = Bucket::new(bucket_name, region, credentials)?;
    let mut output_file = File::create("output_file").expect("Unable to create file");

    let status_code = bucket.get_object_stream("/test.file", &mut output_file).await?;
    println!("Code: {}", status_code);
    Ok(())
}

pub async fn put_object_stream<'_, '_, R: Read, S: AsRef<str>>(
    &'_ self,
    reader: &'_ mut R,
    s3_path: S
) -> Result<u16>

Stream file from local path to s3, async.

Example:

use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;
use std::fs::File;

#[tokio::main]
async fn main() -> Result<(), S3Error> {

    let bucket_name = "rust-s3-test";
    let region = "us-east-1".parse()?;
    let credentials = Credentials::default()?;
    let bucket = Bucket::new(bucket_name, region, credentials)?;
    let mut file = File::open("foo.txt")?;

    let status_code = bucket.put_object_stream(&mut file, "/test_file").await?;
    println!("Code: {}", status_code);
    Ok(())
}

pub async fn tokio_put_object_stream<'_, '_, R: AsyncReadExt + Unpin, S: AsRef<str>>(
    &'_ self,
    reader: &'_ mut R,
    s3_path: S
) -> Result<u16>

Stream file from local path to s3 using tokio::io, async.

Example:

use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;
use std::fs::File;

#[tokio::main]
async fn main() -> Result<(), S3Error> {

    let bucket_name = "rust-s3-test";
    let region = "us-east-1".parse()?;
    let credentials = Credentials::default()?;
    let bucket = Bucket::new(bucket_name, region, credentials)?;
    let mut file = File::open("foo.txt")?;

    let status_code = bucket.put_object_stream(&mut file, "/test_file").await?;
    println!("Code: {}", status_code);
    Ok(())
}

pub fn put_object_stream_blocking<R: Read, S: AsRef<str>>(
    &self,
    reader: &mut R,
    s3_path: S
) -> Result<u16>

Stream file from local path to s3, blockIng.

Example:

use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;
use std::fs::File;

fn main() -> Result<(), S3Error> {

    let bucket_name = "rust-s3-test";
    let region = "us-east-1".parse()?;
    let credentials = Credentials::default()?;
    let bucket = Bucket::new(bucket_name, region, credentials)?;
    let mut file = File::open("foo.txt")?;

    let status_code = bucket.put_object_stream_blocking(&mut file, "/test_file")?;
    println!("Code: {}", status_code);
    Ok(())
}

pub async fn location<'_>(&'_ self) -> Result<(Region, u16)>

Example

use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;

#[tokio::main]
async fn main() -> Result<(), S3Error> {

    let bucket_name = "rust-s3-test";
    let region = "eu-central-1".parse()?;
    let credentials = Credentials::default()?;

    let bucket = Bucket::new(bucket_name, region, credentials)?;
    println!("{}", bucket.location().await?.0);
    Ok(())
}

pub fn location_blocking(&self) -> Result<(Region, u16)>

Example

use s3::bucket::Bucket;
use awscreds::Credentials;

let bucket_name = "rust-s3-test";
let region = "eu-central-1".parse().unwrap();
let credentials = Credentials::default().unwrap();

let bucket = Bucket::new(bucket_name, region, credentials).unwrap();
println!("{}", bucket.location_blocking().unwrap().0)

pub async fn delete_object<'_, S: AsRef<str>>(
    &'_ self,
    path: S
) -> Result<(Vec<u8>, u16)>

Delete file from an S3 path, async.

Example:

use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;

#[tokio::main]
async fn main() -> Result<(), S3Error> {

    let bucket_name = &"rust-s3-test";
    let region = "us-east-1".parse()?;
    let credentials = Credentials::default()?;
    let bucket = Bucket::new(bucket_name, region, credentials)?;

    let (_, code) = bucket.delete_object("/test.file").await?;
    assert_eq!(204, code);

    Ok(())
}

pub fn delete_object_blocking<S: AsRef<str>>(
    &self,
    path: S
) -> Result<(Vec<u8>, u16)>

Delete file from an S3 path, blocks .

Example:

use s3::bucket::Bucket;
use awscreds::Credentials;

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default().unwrap();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let (_, code) = bucket.delete_object_blocking("/test.file").unwrap();
assert_eq!(204, code);

pub async fn put_object<'_, '_, '_, S: AsRef<str>>(
    &'_ self,
    path: S,
    content: &'_ [u8],
    content_type: &'_ str
) -> Result<(Vec<u8>, u16)>

Put into an S3 bucket, async.

Example

use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;

#[tokio::main]
async fn main() -> Result<(), S3Error> {

    let bucket_name = &"rust-s3-test";
    let aws_access = &"access_key";
    let aws_secret = &"secret_key";

    let bucket_name = &"rust-s3-test";
    let region = "us-east-1".parse().unwrap();
    let credentials = Credentials::default().unwrap();
    let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

    let content = "I want to go to S3".as_bytes();
    let (_, code) = bucket.put_object("/test.file", content, "text/plain").await?;
    assert_eq!(201, code);
    Ok(())
}

pub fn put_object_blocking<S: AsRef<str>>(
    &self,
    path: S,
    content: &[u8],
    content_type: &str
) -> Result<(Vec<u8>, u16)>

Put into an S3 bucket, blocks.

Example

use s3::bucket::Bucket;
use awscreds::Credentials;

let bucket_name = &"rust-s3-test";
let aws_access = &"access_key";
let aws_secret = &"secret_key";

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default().unwrap();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let content = "I want to go to S3".as_bytes();
let (_, code) = bucket.put_object_blocking("/test.file", content, "text/plain").unwrap();
assert_eq!(201, code);

pub async fn put_object_tagging<'_, '_, '_, S: AsRef<str>>(
    &'_ self,
    path: &'_ str,
    tags: &'_ [(S, S)]
) -> Result<(Vec<u8>, u16)>

Tag an S3 object, async.

Example

use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;

#[tokio::main]
async fn main() -> Result<(), S3Error> {

    let bucket_name = &"rust-s3-test";
    let aws_access = &"access_key";
    let aws_secret = &"secret_key";

    let bucket_name = &"rust-s3-test";
    let region = "us-east-1".parse()?;
    let credentials = Credentials::default()?;
    let bucket = Bucket::new(bucket_name, region, credentials)?;

    let (_, code) = bucket.put_object_tagging("/test.file", &[("Tag1", "Value1"), ("Tag2", "Value2")]).await?;
    assert_eq!(201, code);
    Ok(())
}

pub fn put_object_tagging_blocking<S: AsRef<str>>(
    &self,
    path: &str,
    tags: &[(S, S)]
) -> Result<(Vec<u8>, u16)>

Tag an S3 object, blocks.

Example

use s3::bucket::Bucket;
use awscreds::Credentials;

let bucket_name = &"rust-s3-test";
let aws_access = &"access_key";
let aws_secret = &"secret_key";

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default().unwrap();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let (_, code) = bucket.put_object_tagging_blocking("/test.file", &[("Tag1", "Value1"), ("Tag2", "Value2")]).unwrap();
assert_eq!(201, code);

pub async fn delete_object_tagging<'_, S: AsRef<str>>(
    &'_ self,
    path: S
) -> Result<(Vec<u8>, u16)>

Delete tags from an S3 object, async.

Example

use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;

#[tokio::main]
async fn main() -> Result<(), S3Error> {

    let bucket_name = &"rust-s3-test";
    let aws_access = &"access_key";
    let aws_secret = &"secret_key";

    let bucket_name = &"rust-s3-test";
    let region = "us-east-1".parse()?;
    let credentials = Credentials::default()?;
    let bucket = Bucket::new(bucket_name, region, credentials)?;

    let (_, code) = bucket.delete_object_tagging("/test.file").await?;
    assert_eq!(201, code);
    Ok(())
}

pub fn delete_object_tagging_blocking<S: AsRef<str>>(
    &self,
    path: S
) -> Result<(Vec<u8>, u16)>

Delete tags from an S3 object, blocks.

Example

use s3::bucket::Bucket;
use awscreds::Credentials;

let bucket_name = &"rust-s3-test";
let aws_access = &"access_key";
let aws_secret = &"secret_key";

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default().unwrap();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let (_, code) = bucket.delete_object_tagging_blocking("/test.file").unwrap();
assert_eq!(201, code);

pub async fn get_object_tagging<'_, S: AsRef<str>>(
    &'_ self,
    path: S
) -> Result<(Option<Tagging>, u16)>

Retrieve an S3 object list of tags, async.

Example

use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;

#[tokio::main]
async fn main() -> Result<(), S3Error> {

    let bucket_name = &"rust-s3-test";
    let aws_access = &"access_key";
    let aws_secret = &"secret_key";

    let bucket_name = &"rust-s3-test";
    let region = "us-east-1".parse()?;
    let credentials = Credentials::default()?;
    let bucket = Bucket::new(bucket_name, region, credentials)?;

    let (tags, code) = bucket.get_object_tagging("/test.file").await?;
    if code == 200 {
        for tag in tags.expect("No tags found").tag_set {
            println!("{}={}", tag.key(), tag.value());
        }
    }
    Ok(())
}

pub fn get_object_tagging_blocking<S: AsRef<str>>(
    &self,
    path: S
) -> Result<(Option<Tagging>, u16)>

Retrieve an S3 object list of tags, blocks.

Example

use s3::bucket::Bucket;
use awscreds::Credentials;

let bucket_name = &"rust-s3-test";
let aws_access = &"access_key";
let aws_secret = &"secret_key";

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default().unwrap();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let (tags, code) = bucket.get_object_tagging_blocking("/test.file").unwrap();
if code == 200 {
    for tag in tags.expect("No tags found").tag_set {
        println!("{}={}", tag.key(), tag.value());
    }
}

pub fn list_page_blocking(
    &self,
    prefix: String,
    delimiter: Option<String>,
    continuation_token: Option<String>,
    start_after: Option<String>,
    max_keys: Option<usize>
) -> Result<(ListBucketResult, u16)>

pub async fn list_page<'_>(
    &'_ self,
    prefix: String,
    delimiter: Option<String>,
    continuation_token: Option<String>,
    start_after: Option<String>,
    max_keys: Option<usize>
) -> Result<(ListBucketResult, u16)>

pub fn list_blocking(
    &self,
    prefix: String,
    delimiter: Option<String>
) -> Result<Vec<(ListBucketResult, u16)>>

List the contents of an S3 bucket, blocks.

Example

use std::str;
use s3::bucket::Bucket;
use awscreds::Credentials;

let bucket_name = &"rust-s3-test";
let aws_access = &"access_key";
let aws_secret = &"secret_key";

let bucket_name = &"rust-s3-test";
let region = "us-east-1".parse().unwrap();
let credentials = Credentials::default().unwrap();
let bucket = Bucket::new(bucket_name, region, credentials).unwrap();

let results = bucket.list_blocking("/".to_string(), Some("/".to_string())).unwrap();
for (list, code) in results {
    assert_eq!(200, code);
    println!("{:?}", list);
}

pub async fn list<'_>(
    &'_ self,
    prefix: String,
    delimiter: Option<String>
) -> Result<Vec<ListBucketResult>>

List the contents of an S3 bucket, async.

Example

extern crate futures;
use std::str;
use s3::bucket::Bucket;
use awscreds::Credentials;
use s3::S3Error;

#[tokio::main]
async fn main() -> Result<(), S3Error> {

    let bucket_name = &"rust-s3-test";
    let aws_access = &"access_key";
    let aws_secret = &"secret_key";

    let bucket_name = &"rust-s3-test";
    let region = "us-east-1".parse()?;
    let credentials = Credentials::default()?;
    let bucket = Bucket::new(bucket_name, region, credentials)?;

    let results = bucket.list("/".to_string(), Some("/".to_string())).await?;
    println!("{:?}", results);

    Ok(())
}

pub fn is_path_style(&self) -> bool

Get path_style field of the Bucket struct

pub fn is_subdomain_style(&self) -> bool

pub fn set_path_style(&mut self)

Configure bucket to use path-style urls and headers

pub fn set_subdomain_style(&mut self)

Configure bucket to use subdomain style urls and headers [default]

pub fn name(&self) -> String

Get a reference to the name of the S3 bucket.

pub fn host(&self) -> String

pub fn url(&self) -> String

pub fn path_style_host(&self) -> String

Get a paths-style reference to the hostname of the S3 API endpoint.

pub fn subdomain_style_host(&self) -> String

pub fn scheme(&self) -> String

pub fn region(&self) -> Region

Get the region this object will connect to.

pub fn access_key(&self) -> Option<String>

Get a reference to the AWS access key.

pub fn secret_key(&self) -> Option<String>

Get a reference to the AWS secret key.

pub fn security_token(&self) -> Option<&str>

Get a reference to the AWS security token.

pub fn session_token(&self) -> Option<&str>

Get a reference to the AWS session token.

pub fn credentials(&self) -> &Credentials

Get a reference to the full Credentials object used by this Bucket.

pub fn set_credentials(&mut self, credentials: Credentials) -> Credentials

Change the credentials used by the Bucket, returning the existing credentials.

pub fn add_header(&mut self, key: &str, value: &str)

Add an extra header to send with requests to S3.

Add an extra header to send with requests. Note that the library already sets a number of headers - headers set with this method will be overridden by the library headers:

• Host
• Content-Type
• Date
• Content-Length
• Authorization
• X-Amz-Content-Sha256
• X-Amz-Date

pub fn extra_headers(&self) -> &HashMap<String, String>

Get a reference to the extra headers to be passed to the S3 API.

pub fn extra_headers_mut(&mut self) -> &mut HashMap<String, String>

Get a mutable reference to the extra headers to be passed to the S3 API.

pub fn add_query(&mut self, key: &str, value: &str)

Add an extra query pair to the URL used for S3 API access.

pub fn extra_query(&self) -> &HashMap<String, String>

Get a reference to the extra query pairs to be passed to the S3 API.

pub fn extra_query_mut(&mut self) -> &mut HashMap<String, String>

Get a mutable reference to the extra query pairs to be passed to the S3 API.

Trait Implementations

impl Clone for Bucket

fn clone(&self) -> Bucket

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Bucket

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Eq for Bucket

impl PartialEq<Bucket> for Bucket

fn eq(&self, other: &Bucket) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Bucket) -> bool

This method tests for !=.

impl StructuralEq for Bucket

impl StructuralPartialEq for Bucket