Struct AmazonS3 

pub struct AmazonS3 { /* private fields */ }

Available on crate feature aws-base only.

Interface for Amazon S3.

Implementations

impl AmazonS3

pub fn credentials(&self) -> &AwsCredentialProvider

Returns the AwsCredentialProvider used by AmazonS3

Trait Implementations

impl Clone for AmazonS3

fn clone(&self) -> AmazonS3

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AmazonS3

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

Formats the value using the given formatter.

impl Display for AmazonS3

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

Formats the value using the given formatter.

impl MultipartStore for AmazonS3

fn create_multipart<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, ) -> Pin<Box<dyn Future<Output = Result<MultipartId>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Create a new multipart upload, returning its MultipartId.

This is the low-level MultipartStore API, which gives direct control over individual parts. See ObjectStoreExt::put_multipart for a higher-level API that handles parts automatically.

Example

Create a multipart upload, upload two parts, and finalize it by calling complete_multipart:

let s3 = AmazonS3Builder::new()
    .with_region("us-east-1")
    .with_bucket_name("my-bucket")
    .with_access_key_id("my-access-key-id")
    .with_secret_access_key("my-secret-access-key")
    .build()?;

let path = Path::from("data/large_file");

// Start the upload, obtaining an id used to reference it in later calls
let id = s3.create_multipart(&path).await?;

// Upload the individual parts. Every part except the last must be at least
// 5 MiB.
let part0 = s3
    .put_part(&path, &id, 0, PutPayload::from(vec![0; 5 * 1024 * 1024]))
    .await?;
let part1 = s3
    .put_part(&path, &id, 1, PutPayload::from("the final part"))
    .await?;

// Finalize the upload. The parts must be provided in `part_idx` order.
s3.complete_multipart(&path, &id, vec![part0, part1]).await?;

Every part except the last must be at least 5 MiB. Parts may be uploaded concurrently and in any order, provided each is given the correct part_idx. See Amazon S3 multipart upload limits for the full set of size and count constraints.

To discard an upload instead of completing it, call abort_multipart with the same id.

Example: presigned multipart upload

The same upload can be driven by a client that holds no credentials. The credential holder starts the upload and presigns an UploadPart URL for each part with Signer::signed_url_opts; the client PUTs its bytes to that URL and returns the ETag from the response; the credential holder then completes the upload with those ETags. This is how you hand out per-part upload URLs without sharing credentials.

let s3 = AmazonS3Builder::new()
    .with_region("us-east-1")
    .with_bucket_name("my-bucket")
    .with_access_key_id("my-access-key-id")
    .with_secret_access_key("my-secret-access-key")
    .build()?;

let path = Path::from("data/large_file");

// Credential holder: start the upload.
let id = s3.create_multipart(&path).await?;

// Credential holder: presign an `UploadPart` URL for each part. `partNumber` and `uploadId`
// must be signed query parameters, or S3 rejects the request.
let mut part_urls = Vec::new();
for part_number in 1..=3 {
    let options = SignedUrlOptions::default().with_query([
        ("partNumber", part_number.to_string()),
        ("uploadId", id.clone()),
    ]);
    let url = s3
        .signed_url_opts(Method::PUT, &path, Duration::from_secs(60 * 60), &options)
        .await?;
    part_urls.push(url);
}

// Client (no credentials): `PUT` each part's bytes to its URL, read the `ETag` response
// header, and return the ETags to the credential holder in part order, e.g. with `reqwest`:
//
//     let resp = reqwest::Client::new().put(url).body(bytes).send().await?;
//     let etag = resp.headers()[http::header::ETAG].to_str()?.to_string();
let etags: Vec<String> = // returned by the client

// Credential holder: complete the upload with the collected ETags.
let parts = etags.into_iter().map(|content_id| PartId { content_id }).collect();
s3.complete_multipart(&path, &id, parts).await?;

fn create_multipart_opts<'life0, 'life1, 'async_trait>( &'life0 self, path: &'life1 Path, opts: PutMultipartOptions, ) -> Pin<Box<dyn Future<Output = Result<MultipartId>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Creates a new multipart upload with the given options, returning the MultipartId

fn put_part<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, path: &'life1 Path, id: &'life2 MultipartId, part_idx: usize, data: PutPayload, ) -> Pin<Box<dyn Future<Output = Result<PartId>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Uploads a new part with index part_idx

fn complete_multipart<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, path: &'life1 Path, id: &'life2 MultipartId, parts: Vec<PartId>, ) -> Pin<Box<dyn Future<Output = Result<PutResult>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Completes a multipart upload

fn abort_multipart<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, path: &'life1 Path, id: &'life2 MultipartId, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Aborts a multipart upload

impl ObjectStore for AmazonS3

fn put_opts<'life0, 'life1, 'async_trait>( &'life0 self, location: &'life1 Path, payload: PutPayload, opts: PutOptions, ) -> Pin<Box<dyn Future<Output = Result<PutResult>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Save the provided payload to location with the given options

fn put_multipart_opts<'life0, 'life1, 'async_trait>( &'life0 self, location: &'life1 Path, opts: PutMultipartOptions, ) -> Pin<Box<dyn Future<Output = Result<Box<dyn MultipartUpload>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Perform a multipart upload with options

fn get_opts<'life0, 'life1, 'async_trait>( &'life0 self, location: &'life1 Path, options: GetOptions, ) -> Pin<Box<dyn Future<Output = Result<GetResult>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Perform a get request with options

fn delete_stream( &self, locations: BoxStream<'static, Result<Path>>, ) -> BoxStream<'static, Result<Path>>

Delete all the objects at the specified locations

fn list(&self, prefix: Option<&Path>) -> BoxStream<'static, Result<ObjectMeta>>

List all the objects with the given prefix.

fn list_with_offset( &self, prefix: Option<&Path>, offset: &Path, ) -> BoxStream<'static, Result<ObjectMeta>>

List all the objects with the given prefix and a location greater than offset

fn list_with_delimiter<'life0, 'life1, 'async_trait>( &'life0 self, prefix: Option<&'life1 Path>, ) -> Pin<Box<dyn Future<Output = Result<ListResult>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

List objects with the given prefix and an implementation specific delimiter. Returns common prefixes (directories) in addition to object metadata.

fn copy_opts<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, from: &'life1 Path, to: &'life2 Path, options: CopyOptions, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Copy an object from one path to another in the same object store.

fn get_ranges<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, location: &'life1 Path, ranges: &'life2 [Range<u64>], ) -> Pin<Box<dyn Future<Output = Result<Vec<Bytes>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Return the bytes that are stored at the specified location in the given byte ranges

fn rename_opts<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, from: &'life1 Path, to: &'life2 Path, options: RenameOptions, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Move an object from one path to another in the same object store.

impl PaginatedListStore for AmazonS3

fn list_paginated<'life0, 'life1, 'async_trait>( &'life0 self, prefix: Option<&'life1 str>, opts: PaginatedListOptions, ) -> Pin<Box<dyn Future<Output = Result<PaginatedListResult>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Perform a paginated list request

impl Signer for AmazonS3

fn signed_url<'life0, 'life1, 'async_trait>( &'life0 self, method: Method, path: &'life1 Path, expires_in: Duration, ) -> Pin<Box<dyn Future<Output = Result<Url>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Available on crate feature cloud-base only.

Create a URL containing the relevant AWS SigV4 query parameters that authorize a request via method to the resource at path valid for the duration specified in expires_in.

Example

This example returns a URL that will enable a user to upload a file to “some-folder/some-file.txt” in the next hour.

let region = "us-east-1";
let s3 = AmazonS3Builder::new()
    .with_region(region)
    .with_bucket_name("my-bucket")
    .with_access_key_id("my-access-key-id")
    .with_secret_access_key("my-secret-access-key")
    .build()?;

let url = s3.signed_url(
    Method::PUT,
    &Path::from("some-folder/some-file.txt"),
    Duration::from_secs(60 * 60)
).await?;

fn signed_url_opts<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, method: Method, path: &'life1 Path, expires_in: Duration, options: &'life2 SignedUrlOptions, ) -> Pin<Box<dyn Future<Output = Result<Url>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Available on crate feature cloud-base only.

Create a signed URL, additionally folding the query parameters and headers in options into the SigV4 signature.

extra_query lets callers sign query parameters that the recipient must send, such as partNumber and uploadId for a multipart UploadPart, or a versionId. signed_headers binds specific request headers (e.g. x-amz-checksum-sha256, content-type, SSE headers) to the signature; the recipient must send exactly these headers and values.

Example

let s3 = AmazonS3Builder::new()
    .with_region("us-east-1")
    .with_bucket_name("my-bucket")
    .with_access_key_id("my-access-key-id")
    .with_secret_access_key("my-secret-access-key")
    .build()?;

// Presign a multipart UploadPart request.
let options = SignedUrlOptions::default()
    .with_query([("partNumber", "1"), ("uploadId", "abc123")]);
let url = s3.signed_url_opts(
    Method::PUT,
    &Path::from("some-folder/some-file.txt"),
    Duration::from_secs(60 * 60),
    &options,
).await?;

See AmazonS3::create_multipart for a complete end-to-end example that presigns every part of a multipart upload so a credential-less client can upload them.

fn signed_urls<'life0, 'life1, 'async_trait>( &'life0 self, method: Method, paths: &'life1 [Path], expires_in: Duration, ) -> Pin<Box<dyn Future<Output = Result<Vec<Url>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Available on crate feature cloud-base only.

Generate signed urls for multiple paths.