Struct S3Client 

pub struct S3Client { /* private fields */ }

An async S3-compatible client.

Implementations

impl S3Client

pub async fn download_to_path( &self, request: GetObjectRequest, destination: impl AsRef<Path>, ) -> Result<DownloadToPathOutput, S3Error>

Downloads an object into a private temporary file and atomically persists it at destination only after the response body is fully verified.

The temporary file is created in the destination directory, so the final rename cannot cross filesystems. An existing destination is atomically replaced where the platform supports replacement renames. Failed, cancelled, truncated, or checksum-invalid downloads leave the previous destination untouched and remove the temporary file on drop.

Errors

Returns an error when the object request, destination I/O, integrity verification, or atomic persist operation fails.

impl S3Client

pub async fn upload_part_copy( &self, request: UploadPartCopyRequest, ) -> Result<UploadPartCopyOutput, S3Error>

Uploads one multipart part by copying an existing S3 object or range.

Errors

Returns an error for invalid headers, transport or service failures, malformed bounded XML, embedded S3 errors, or a missing part ETag.

impl S3Client

pub async fn list_parts( &self, request: ListPartsRequest, ) -> Result<ListPartsOutput, S3Error>

Lists one bounded page of parts belonging to an in-progress upload.

Errors

Returns an error when signing, transport, or bounded XML parsing fails.

pub async fn list_parts_all( &self, request: ListPartsRequest, maximum_pages: usize, ) -> Result<Vec<ListPartsOutput>, S3Error>

Retrieves at most maximum_pages of parts under one operation deadline.

Missing, non-advancing, or repeated markers are rejected rather than risking an unbounded pagination loop.

Errors

Returns an error for a zero page bound, invalid pagination, exhaustion of the page bound, or any page request failure.

pub async fn list_multipart_uploads_all( &self, request: ListMultipartUploadsRequest, maximum_pages: usize, ) -> Result<Vec<ListMultipartUploadsOutput>, S3Error>

Retrieves at most maximum_pages of in-progress uploads under one deadline.

Errors

Returns an error for a zero page bound, invalid pagination, exhaustion of the page bound, or any page request failure.

impl S3Client

pub async fn create_multipart_upload( &self, request: CreateMultipartUploadRequest, ) -> Result<CreateMultipartUploadOutput, S3Error>

Initiates a multipart upload for an object.

Errors

Returns an error for invalid headers, transport or service failures, or a malformed or oversized service response.

pub async fn upload_part( &self, request: UploadPartRequest, ) -> Result<UploadPartOutput, S3Error>

Uploads one part of an in-progress multipart upload.

Errors

Returns an error for an invalid checksum, body preparation failure, transport or service failure, or malformed response headers.

pub async fn complete_multipart_upload( &self, request: CompleteMultipartUploadRequest, ) -> Result<CompleteMultipartUploadOutput, S3Error>

Completes an in-progress multipart upload.

Errors

Returns an error when the completion document cannot be serialized, the request fails, or S3 returns a malformed, oversized, or embedded error.

pub async fn abort_multipart_upload( &self, request: AbortMultipartUploadRequest, ) -> Result<RequestIds, S3Error>

Aborts an in-progress multipart upload.

Errors

Returns an error when target construction, signing, transport, or the S3 service rejects the abort request.

pub async fn list_multipart_uploads( &self, request: ListMultipartUploadsRequest, ) -> Result<ListMultipartUploadsOutput, S3Error>

Retrieves one bounded page of in-progress multipart uploads.

Errors

Returns an error for inconsistent pagination markers, a failed request, or a malformed or oversized listing response.

impl S3Client

pub async fn multipart_upload( &self, request: ManagedMultipartUploadRequest, ) -> Result<CompleteMultipartUploadOutput, S3Error>

Uploads a replayable bytes or file source using bounded multipart requests.

Part size, concurrency, total in-flight part bytes, and deadlines are derived from the request’s crate::MultipartOptions. File input is snapshotted before an upload is created. Dropping this future cancels outstanding parts and leaves an owned cleanup task to quiesce transmitted requests before aborting the upload. A normal failure waits for cleanup; if cleanup cannot be confirmed, S3Error::cleanup_failure exposes that error while preserving the original failure.

Errors

Returns an error if the source cannot be prepared, exceeds S3’s 10,000 part limit, a part fails, cancellation occurs, completion fails, or abort cleanup fails after another error.

impl S3Client

pub async fn list_objects_v2( &self, request: ListObjectsV2Request, ) -> Result<ListObjectsV2Output, S3Error>

Retrieves one page from S3’s version-two object listing API.

Errors

Returns an error when signing, transport, or response parsing fails.

pub async fn list_objects_v2_all( &self, request: ListObjectsV2Request, maximum_pages: usize, ) -> Result<Vec<ListObjectsV2Output>, S3Error>

Retrieves at most maximum_pages, rejecting missing or repeating page tokens.

Errors

Returns an error for a zero page bound, a malformed pagination sequence, an exhausted page bound, or any page request failure.

impl S3Client

pub async fn put_object( &self, request: PutObjectRequest, ) -> Result<PutObjectOutput, S3Error>

Uploads one object to the configured bucket.

Errors

Returns an error when request preparation, signing, transport, or response parsing fails.

pub async fn get_object( &self, request: GetObjectRequest, ) -> Result<GetObjectOutput, S3Error>

Downloads one object as a bounded, cancellation-safe response stream.

Errors

Returns an error when request validation, signing, transport, or header parsing fails.

pub async fn head_object( &self, request: HeadObjectRequest, ) -> Result<HeadObjectOutput, S3Error>

Retrieves one object’s metadata without downloading its body.

Errors

Returns an error when signing, transport, or response parsing fails.

pub async fn delete_object( &self, request: DeleteObjectRequest, ) -> Result<DeleteObjectOutput, S3Error>

Deletes one object or object version.

Errors

Returns an error when signing, transport, or response parsing fails.

pub async fn delete_objects( &self, request: DeleteObjectsRequest, ) -> Result<DeleteObjectsOutput, S3Error>

Deletes a validated batch of objects in one request.

Errors

Returns an error when XML serialization, signing, transport, or response parsing fails.

pub async fn copy_object( &self, request: CopyObjectRequest, ) -> Result<CopyObjectOutput, S3Error>

Copies an object entirely within S3.

Errors

Returns an error when request validation, signing, transport, or response parsing fails.

impl S3Client

pub async fn presigned_get( &self, key: &ObjectKey, expires: Duration, ) -> Result<PresignedUrl, S3Error>

Generates a presigned GET URL whose standard formatting is redacted.

pub async fn presigned_put( &self, key: &ObjectKey, expires: Duration, ) -> Result<PresignedUrl, S3Error>

Generates a presigned PUT URL whose standard formatting is redacted.

pub async fn presigned_head( &self, key: &ObjectKey, expires: Duration, ) -> Result<PresignedUrl, S3Error>

Generates a presigned HEAD URL whose standard formatting is redacted.

pub async fn presigned_delete( &self, key: &ObjectKey, expires: Duration, ) -> Result<PresignedUrl, S3Error>

Generates a presigned DELETE URL whose standard formatting is redacted.

pub async fn presigned_create_multipart_upload( &self, key: &ObjectKey, expires: Duration, ) -> Result<PresignedUrl, S3Error>

Generates a presigned request that initiates a multipart upload.

pub async fn presigned_upload_part( &self, key: &ObjectKey, upload_id: &UploadId, part_number: PartNumber, expires: Duration, ) -> Result<PresignedUrl, S3Error>

Generates a presigned multipart part-upload URL.

pub async fn presigned_abort_multipart_upload( &self, key: &ObjectKey, upload_id: &UploadId, expires: Duration, ) -> Result<PresignedUrl, S3Error>

Generates a presigned multipart abort URL.

impl S3Client

pub fn new(config: S3Config) -> Result<Self, S3Error>

Constructs a client from validated configuration.

pub fn config(&self) -> &S3Config

Returns this client’s validated configuration.

pub fn for_bucket(&self, bucket: impl Into<String>) -> Result<Self, S3Error>

Creates a cheap bucket-scoped client that shares this client’s HTTP connection pool and credential provider.

Errors

Returns an error when bucket is invalid for the configured addressing style.

Trait Implementations

impl Clone for S3Client

fn clone(&self) -> S3Client

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for S3Client

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

Formats the value using the given formatter.