Crate s3_wire

Expand description

Async, streaming S3-compatible client with explicit resource bounds.

s3-wire provides typed object operations, SigV4 signing, replay-aware retries, streaming downloads, and primitive or managed multipart uploads. A client is configured for one endpoint, region, and bucket.

§Quick start

The default credential provider reads AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optional AWS_SESSION_TOKEN.

use s3_wire::{
    ByteStream, Endpoint, GetObjectRequest, ObjectKey, PutObjectRequest, S3Client, S3Config,
};

let region = "us-east-1";
let config = S3Config::builder()
    .endpoint(Endpoint::for_aws_region(region)?)
    .region(region)
    .bucket("artifact-bucket")
    .build()?;
let client = S3Client::new(config)?;

let key = ObjectKey::new("reports/latest.json")?;
client
    .put_object(PutObjectRequest::new(
        key.clone(),
        ByteStream::from_bytes(br#"{"status":"complete"}"#.as_slice()),
    ))
    .await?;

let download = client.get_object(GetObjectRequest::new(key)).await?;
let mut destination = tokio::io::sink();
download.body.write_to(&mut destination).await?;

§Upload and download behavior

ByteStream::from_bytes and ByteStream::from_path are replayable.
ByteStream::from_stream is one-shot and requires an exact length and SHA-256 digest.
ResponseStream applies backpressure and validates declared length, configured deadlines, and supported checksums while the body is consumed.
S3Client::multipart_upload bounds concurrent part buffers and owns abort cleanup after S3 creates an upload.

§Errors

S3Error exposes a stable ErrorCategory, service status and code, request identifiers, retry classification, timeout phase, and any multipart cleanup failure. Formatting remains redacted by default.

§More documentation

Structs§

AbortMultipartUploadRequest: Request to abort an in-progress multipart upload.
ByteStream: An upload body with explicit length, integrity, and replay semantics.
CachedCredentialsProvider: Expiration-aware provider that coalesces concurrent refresh requests.
Checksum: Base64-encoded checksums returned by S3.
CompleteMultipartUploadOutput: Result of completing a multipart upload.
CompleteMultipartUploadRequest: Request to complete a multipart upload.
CompletedPart: A validated completed-part descriptor.
Conditions: Conditional headers shared by object operations.
CopyObjectOutput: Result of a server-side copy.
CopyObjectRequest: Request to copy an object within S3.
CopySource: Source of a server-side object copy.
CreateMultipartUploadOutput: Result of initiating a multipart upload.
CreateMultipartUploadRequest: Request to initiate a multipart upload.
Credentials: AWS-compatible credentials and optional expiration.
DeleteError: Per-object failure returned from a multi-object delete.
DeleteObjectOutput: Result of deleting one object.
DeleteObjectRequest: Request to delete one object.
DeleteObjectsOutput: Result of a multi-object delete request.
DeleteObjectsRequest: A validated multi-object delete request.
DeletedObject: One successfully deleted object.
Endpoint: A validated S3 service endpoint.
EnvironmentCredentialsProvider: Provider for the conventional AWS credential environment variables.
GetObjectOutput: A streaming object download and its response metadata.
GetObjectRequest: Request to download one object.
HeadObjectRequest: Request to inspect object metadata without retrieving the body.
ListMultipartUploadsOutput: One page of in-progress multipart uploads.
ListMultipartUploadsRequest: Request for one page of in-progress multipart uploads.
ListObjectsV2Output: One parsed ListObjectsV2 page.
ListObjectsV2Request: Request for one ListObjectsV2 page.
ListedObject: One object returned by ListObjectsV2.
ManagedMultipartUploadRequest: Request for a bounded, automatically cleaned-up multipart upload.
MultipartOptions: Validated resource and time bounds for one managed multipart upload.
MultipartUpload: Explicit state needed to resume or clean up an in-progress multipart upload.
MultipartUploadEntry: One in-progress multipart upload returned by the service.
ObjectKey: A validated UTF-8 S3 object key.
ObjectMetadata: Metadata common to object retrieval and inspection responses.
PageSize: Validated S3 listing page size in the range 1 through 1,000.
PartNumber: A validated multipart part number in the range 1 through 10,000.
PresignedUrl: A presigned URL whose standard formatting is always redacted.
PutObjectOutput: Result of uploading one object.
PutObjectRequest: Request to upload one object.
RangeError: Invalid inclusive byte range.
RequestIds: Identifiers supplied by an S3-compatible service for diagnostics.
ResponseStream: A download stream that enforces idle timeout, content length, and any supported full-object checksum returned by S3.
RetryPolicy: Bounded exponential-backoff policy with full jitter.
S3Client: An async S3-compatible client.
S3Config: Validated configuration used to construct an S3 client.
S3ConfigBuilder: Builder for S3Config.
S3Error: A structured S3 client error.
StaticCredentialsProvider: Provider backed by an immutable credential value.
UploadId: An opaque, validated multipart upload identifier issued by an S3 service.
UploadPartOutput: Result of uploading one multipart part.
UploadPartRequest: Request to upload one multipart part.

Enums§

AddressingStyle: How a bucket name is represented in request URLs.
ByteRange: A byte range for a GET request.
ChecksumAlgorithm: Checksum algorithm understood by S3 checksum headers.
DeleteObjectsError: Invalid multi-object delete batch.
ErrorCategory: Broad category suitable for programmatic error handling.
MultipartError: Invalid multipart state or descriptor.
ObjectKeyError: Validation failure for an ObjectKey.
RetryClassification: Whether an operation may be retried after an error.
TimeoutPhase: The phase in which a timeout occurred.
UploadIdError: Why a service-issued multipart upload identifier was rejected.

Traits§

CredentialsProvider: Asynchronous source of AWS-compatible credentials.

Type Aliases§

HeadObjectOutput: Result of inspecting an object.

Crate s3_wire

Crate s3_wire Copy item path

§Quick start

§Upload and download behavior

§Errors

§More documentation

Structs§

Enums§

Traits§

Type Aliases§

Crate s3_wire