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; cheap bucket-scoped handles can share its connection pool.

§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, attempt count, retry stop reason, timeout phase, and any multipart cleanup failure. Formatting remains redacted by default.

§More documentation

Structs§

AbortMultipartUploadRequest: Request to abort an in-progress multipart upload.
AwsDefaultCredentialsProvider: Adapter for AWS’s standard renewable credential provider chain.
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.
ChecksumCalculationError: Failure to calculate a requested checksum locally.
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.
CopyPartRange: Inclusive source byte range for one server-side copied part.
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.
DeleteObjectIdentifier: One object selected for a multi-object delete request.
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.
DownloadToPathOutput: Result of an atomic object download to a local path.
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.
ListPartsOutput: One bounded page returned by ListParts.
ListPartsRequest: Request for one page of parts belonging to an in-progress upload.
ListedObject: One object returned by ListObjectsV2.
ListedPart: One uploaded part returned by ListParts.
ManagedMultipartHeaders: Phase-specific headers for a managed multipart upload.
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.
ObjectOwner: Owner information optionally returned for a listed object.
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.
RequestEvent: Sanitized lifecycle event for an S3 request attempt.
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.
UploadPartCopyOutput: Result of copying an existing object or range into one multipart part.
UploadPartCopyRequest: Request to populate a multipart part from an existing S3 object.
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.
AwsEndpointVariant: Standard AWS S3 endpoint variant.
ByteRange: A byte range for a GET request.
ChecksumAlgorithm: Checksum algorithm understood by S3 checksum headers.
ChecksumType: How S3 derives an object checksum from multipart data.
CopyMetadataDirective: Metadata behavior for a server-side copy.
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.
RequestEventKind: Stage of one request attempt.
RetryClassification: Whether an operation may be retried after an error.
RetryStopReason: Why a retryable request stopped without another attempt.
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.
RequestObserver: Receives sanitized request lifecycle events.

Functions§

resolve_aws_region_for_profile: Resolves a signing region through AWS’s standard chain for a named profile.
resolve_default_aws_region: Resolves a signing region through AWS’s standard environment, shared profile, and IMDS region chain.

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§

Functions§

Type Aliases§

Crate s3_wire