Skip to main content

aws_s3_transfer/
error.rs

1/*
2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3 * SPDX-License-Identifier: Apache-2.0
4 */
5
6use std::fmt;
7use std::ops::RangeInclusive;
8use std::path::PathBuf;
9
10use aws_sdk_s3::operation::abort_multipart_upload::AbortMultipartUploadError;
11use aws_sdk_s3::operation::complete_multipart_upload::CompleteMultipartUploadError;
12use aws_sdk_s3::operation::create_multipart_upload::CreateMultipartUploadError;
13use aws_sdk_s3::operation::get_object::GetObjectError;
14use aws_sdk_s3::operation::head_object::HeadObjectError;
15use aws_sdk_s3::operation::list_objects_v2::ListObjectsV2Error;
16use aws_sdk_s3::operation::put_object::PutObjectError;
17use aws_sdk_s3::operation::upload_part::UploadPartError;
18use aws_sdk_s3::operation::RequestIdExt;
19use aws_smithy_observability::unit_of_work::checksums::{
20    ChecksumOutcome, ResponseChecksumAlgorithm,
21};
22use aws_smithy_runtime_api::client::orchestrator::HttpResponse;
23use aws_smithy_runtime_api::client::result::{ConnectorError, SdkError};
24use aws_smithy_types::error::metadata::ProvideErrorMetadata;
25use aws_smithy_types::retry::ErrorKind as RetryErrorKind;
26use aws_types::request_id::RequestId;
27
28use crate::model::ChecksumAlgorithm;
29use crate::types::{FailedDownload, FailedUpload};
30
31pub use crate::model::UnknownVariantError;
32
33/// A boxed error that is `Send` and `Sync`.
34pub type BoxError = Box<dyn std::error::Error + Send + Sync>;
35
36/// Errors returned by this library.
37///
38/// NOTE: Use [`aws_smithy_types::error::display::DisplayErrorContext`] or similar to display
39/// the entire error cause/source chain.
40#[derive(Debug)]
41pub struct Error {
42    kind: ErrorKind,
43    source: BoxError,
44    /// Optional metadata. `None` unless a builder attached service, chunk,
45    /// local-path, upload, or bulk-failure detail. Boxed to keep [`Error`] small.
46    extra: Option<Box<ErrorExtra>>,
47}
48
49/// Optional metadata attached to an [`Error`].
50#[derive(Debug, Default)]
51struct ErrorExtra {
52    /// Set when the error originated from an S3 service call.
53    service: Option<ServiceMetadata>,
54    /// HTTP status of an unsuccessful service response, including bodyless HEAD errors.
55    http_status: Option<u16>,
56    /// Set when the error is attributable to a specific chunk of an object.
57    location: Option<ChunkRef>,
58    /// Set when a local filesystem operation on a known path failed.
59    local: Option<LocalContext>,
60    /// Set when a failed upload left this multipart upload open in S3.
61    upload_id: Option<String>,
62    /// Per-object upload failures when this error aggregates a bulk upload.
63    failed_uploads: Option<Vec<FailedUpload>>,
64    /// Per-object download failures when this error aggregates a bulk download.
65    failed_downloads: Option<Vec<FailedDownload>>,
66    /// `true` when the underlying `SdkError` was a transient transport failure
67    /// (a connect/read/write IO error or a client-side timeout) rather than a
68    /// service response — a re-issuable failure the SDK's own retry may not have
69    /// recovered (e.g. its shared retry token bucket was exhausted under a
70    /// concurrent burst). Set at conversion from the typed `SdkError`, where the
71    /// distinction is still available before type erasure. Never set for
72    /// throttling/service errors — see `retry::classify_upload_part_retry`.
73    transient_transport: bool,
74}
75
76/// General categories of transfer errors.
77///
78/// The kind classifies where a failure arose. It does not say whether
79/// resubmitting the operation can succeed: failures the transfer manager can
80/// repair, such as throttling responses and interrupted body reads, are retried
81/// internally before an error of any kind is returned.
82#[derive(Clone, Debug, Eq, PartialEq)]
83#[non_exhaustive]
84pub enum ErrorKind {
85    /// The operation's input was rejected: a required field is missing, a value
86    /// is out of range, settings conflict, or the source cannot be transferred as
87    /// requested, such as a stream that produces more parts than a multipart
88    /// upload allows or an object key that resolves outside the download
89    /// destination or to the destination itself. Conditions visible in the
90    /// input are reported before any request is sent; conditions that depend
91    /// on the source data are reported when the transfer encounters them.
92    InputInvalid,
93
94    /// An I/O operation failed. This covers both local filesystem failures
95    /// (opening, reading, writing, or renaming a file) and transport failures
96    /// while reading an object body from S3, such as a reset connection or a
97    /// truncated response. The source error identifies which.
98    ///
99    /// Because the kind spans local and remote failures, it does not indicate
100    /// whether resubmitting the operation can succeed. When a body read fails
101    /// for a specific chunk, [`Error::chunk`] identifies it.
102    IOError,
103
104    /// The transfer manager could not continue for an internal reason that is
105    /// not an input, I/O or service failure.
106    RuntimeError,
107
108    /// Object discovery failed for a reason that is not a service-call error, such
109    /// as a response missing required metadata.
110    ObjectNotDiscoverable,
111
112    /// A request to S3 failed, or S3 answered with a response the transfer
113    /// cannot use, such as an UploadPart response without an ETag or a ranged
114    /// GetObject or HeadObject response whose `Content-Range` doesn't match the
115    /// requested range. The
116    /// originating operation, service error code (when S3 reported one),
117    /// message, and request ids are available via the accessors on [`Error`]
118    /// ([`Error::operation_name`], [`Error::code`], [`Error::request_id`]).
119    ///
120    /// Service-specific outcomes are identified by their code rather than by a
121    /// kind of their own. A conditional write whose precondition did not hold
122    /// (`if_match` / `if_none_match` on an upload) arrives here with
123    /// [`Error::code`] of `"PreconditionFailed"`; S3 reports that code in the
124    /// response body, so it is available whatever HTTP status carries it.
125    ///
126    /// A whole-object download with checksum validation enabled, or a download of an
127    /// open-ended or suffix range, discovers the object with HeadObject. S3 answers a
128    /// failed HeadObject without a body, so the error carries the HTTP status and
129    /// request ids but no message, and a code only where the status identifies one:
130    /// `"PreconditionFailed"` for 412, `"NotModified"` for 304, `"InvalidRange"` for
131    /// 416, and the SDK's `"NotFound"` for 404. A missing key is `"NotFound"`, not
132    /// `"NoSuchKey"` as a failed GetObject reports.
133    ServiceError,
134
135    /// Object integrity validation failed: the received bytes did not match the
136    /// expected checksum. See the wrapped [`IntegrityError`] for detail.
137    IntegrityError(IntegrityError),
138
139    /// A child of a bulk transfer (`upload_objects` / `download_objects`) failed.
140    /// The individual failures are available via [`Error::failed_uploads`] /
141    /// [`Error::failed_downloads`].
142    ///
143    /// The error's [`source`](std::error::Error::source) is the error of the
144    /// first failed object. Under
145    /// [`FailedTransferPolicy::Abort`](crate::types::FailedTransferPolicy::Abort)
146    /// that is the failure that stopped the transfer.
147    ChildOperationFailed,
148
149    /// The operation was cancelled, either because the user called `.abort()` on the
150    /// handle, or a child operation failed under the abort policy.
151    OperationCancelled,
152}
153
154/// Detail about an integrity (checksum) validation failure.
155///
156/// [`algorithm`](Self::algorithm), [`expected`](Self::expected) and
157/// [`computed`](Self::computed) are all `Some` for a mismatch the SDK reported. The
158/// body error that ended the read is available via [`std::error::Error::source`].
159#[derive(Clone, Debug, Eq, PartialEq)]
160#[non_exhaustive]
161pub struct IntegrityError {
162    algorithm: Option<ChecksumAlgorithm>,
163    expected: Option<String>,
164    computed: Option<String>,
165}
166
167impl IntegrityError {
168    /// The checksum algorithm that failed validation, if known.
169    pub fn algorithm(&self) -> Option<&ChecksumAlgorithm> {
170        self.algorithm.as_ref()
171    }
172
173    /// The checksum S3 reported for the object, base64-encoded, if known.
174    pub fn expected(&self) -> Option<&str> {
175        self.expected.as_deref()
176    }
177
178    /// The checksum computed over the received bytes, base64-encoded, if known.
179    pub fn computed(&self) -> Option<&str> {
180        self.computed.as_deref()
181    }
182}
183
184/// Identifies the chunk of an object a failure is attributable to.
185#[derive(Clone, Debug, Eq, PartialEq)]
186#[non_exhaustive]
187pub struct ChunkRef {
188    seq: u64,
189    range: Option<RangeInclusive<u64>>,
190}
191
192impl ChunkRef {
193    pub(crate) fn new(seq: u64, range: Option<RangeInclusive<u64>>) -> Self {
194        Self { seq, range }
195    }
196
197    /// Sequence number of the chunk within the transfer.
198    pub fn seq(&self) -> u64 {
199        self.seq
200    }
201
202    /// Byte range of the chunk within the object, if known.
203    pub fn byte_range(&self) -> Option<&RangeInclusive<u64>> {
204        self.range.as_ref()
205    }
206}
207
208/// A failed local filesystem operation and the path it acted on.
209///
210/// `action` is a lowercase gerund phrase whose object is `path`, such as
211/// `"opening"` or `"creating temporary file for"`, so that `Display` reads
212/// `I/O error opening "/data/a.bin"`.
213#[derive(Debug)]
214struct LocalContext {
215    action: &'static str,
216    path: PathBuf,
217    /// The object key the operation was for, when there is one.
218    key: Option<String>,
219}
220
221/// Service-call detail, read from the concrete `SdkError` of a failed request, or from the output
222/// of a successful response the transfer cannot use.
223#[derive(Debug)]
224struct ServiceMetadata {
225    operation: &'static str,
226    code: Option<String>,
227    message: Option<String>,
228    request_id: Option<String>,
229    extended_request_id: Option<String>,
230}
231
232impl Error {
233    /// Creates a new transfer [`Error`] from a known kind and an arbitrary source.
234    pub fn new<E>(kind: ErrorKind, err: E) -> Error
235    where
236        E: Into<BoxError>,
237    {
238        Error {
239            kind,
240            source: err.into(),
241            extra: None,
242        }
243    }
244
245    /// Returns the corresponding [`ErrorKind`] for this error.
246    pub fn kind(&self) -> &ErrorKind {
247        &self.kind
248    }
249
250    /// Test-only: a `ServiceError` flagged as transient transport, mirroring what
251    /// `service_error` produces for an IO `DispatchFailure` (which cannot be
252    /// constructed directly in a unit test).
253    #[cfg(test)]
254    pub(crate) fn test_transient_transport() -> Error {
255        Error {
256            kind: ErrorKind::ServiceError,
257            source: "injected transient transport".into(),
258            extra: Some(Box::new(ErrorExtra {
259                transient_transport: true,
260                ..Default::default()
261            })),
262        }
263    }
264
265    /// Test-only: a `ServiceError` carrying the given service error code,
266    /// mirroring what `service_error` produces from an `SdkError` (which cannot
267    /// be constructed directly in a unit test). Lets retry classifiers be tested
268    /// against a code (e.g. throttle detection) without a live wire error.
269    #[cfg(test)]
270    pub(crate) fn test_service_error(code: &str) -> Error {
271        Error {
272            kind: ErrorKind::ServiceError,
273            source: "injected service error".into(),
274            extra: Some(Box::new(ErrorExtra {
275                service: Some(ServiceMetadata {
276                    operation: "TestOperation",
277                    code: Some(code.to_owned()),
278                    message: None,
279                    request_id: None,
280                    extended_request_id: None,
281                }),
282                ..Default::default()
283            })),
284        }
285    }
286
287    fn service(&self) -> Option<&ServiceMetadata> {
288        self.extra.as_ref().and_then(|e| e.service.as_ref())
289    }
290
291    /// Lazily get a mutable reference to the boxed extra, allocating it on first use.
292    fn extra_mut(&mut self) -> &mut ErrorExtra {
293        self.extra
294            .get_or_insert_with(|| Box::new(ErrorExtra::default()))
295    }
296
297    /// The S3 operation that produced this error, if it originated from a service
298    /// call (e.g. `"GetObject"`, `"HeadObject"`, `"PutObject"`).
299    pub fn operation_name(&self) -> Option<&str> {
300        self.service().map(|m| m.operation)
301    }
302
303    /// The service error code, if any (e.g. `"NoSuchKey"`, `"AccessDenied"`).
304    pub fn code(&self) -> Option<&str> {
305        self.service().and_then(|m| m.code.as_deref())
306    }
307
308    /// HTTP status of the service response, if the error has one.
309    pub(crate) fn http_status(&self) -> Option<u16> {
310        self.extra.as_ref().and_then(|e| e.http_status)
311    }
312
313    /// The service error message, if any.
314    pub fn message(&self) -> Option<&str> {
315        self.service().and_then(|m| m.message.as_deref())
316    }
317
318    /// The AWS request id of the failed call, if any.
319    pub fn request_id(&self) -> Option<&str> {
320        self.service().and_then(|m| m.request_id.as_deref())
321    }
322
323    /// The AWS extended request id of the failed call, if any.
324    pub fn extended_request_id(&self) -> Option<&str> {
325        self.service()
326            .and_then(|m| m.extended_request_id.as_deref())
327    }
328
329    /// Whether the service error code denotes a missing bucket, key, or
330    /// multipart upload.
331    pub fn is_not_found(&self) -> bool {
332        matches!(
333            self.code(),
334            Some("NotFound" | "NoSuchKey" | "NoSuchUpload" | "NoSuchBucket")
335        )
336    }
337
338    /// Whether this error was a transient transport failure (connection IO error
339    /// or client-side timeout) as opposed to a service response. Such failures
340    /// are safe to re-issue and may not have been recovered by the SDK's own
341    /// retry (e.g. its shared retry token bucket was exhausted under a concurrent
342    /// burst). Always `false` for throttling and modeled service errors.
343    pub(crate) fn is_transient_transport(&self) -> bool {
344        self.extra.as_ref().is_some_and(|e| e.transient_transport)
345    }
346
347    /// The chunk this failure is attributable to, if known.
348    pub fn chunk(&self) -> Option<&ChunkRef> {
349        self.extra.as_ref().and_then(|e| e.location.as_ref())
350    }
351
352    /// The ID of a multipart upload that the failed upload left open in S3.
353    ///
354    /// Set on the error an upload's [`join`](crate::operation::upload::UploadHandle::join) or
355    /// [`abort`](crate::operation::upload::UploadHandle::abort) returns when the upload created a
356    /// multipart upload that was neither completed nor aborted: the
357    /// [`FailedMultipartUploadPolicy::Retain`](crate::types::FailedMultipartUploadPolicy::Retain)
358    /// policy kept it, the AbortMultipartUpload request failed, or a worker panicked while
359    /// executing the upload, as when the caller's [`PartStream`](crate::io::PartStream) panics,
360    /// which ends it with [`ErrorKind::RuntimeError`] without sending AbortMultipartUpload. S3
361    /// keeps, and bills for, the uploaded parts until the multipart upload is completed or
362    /// aborted with this ID.
363    ///
364    /// A panic that ends the upload while CompleteMultipartUpload or AbortMultipartUpload is in
365    /// flight also sets the ID, although that request may still close the multipart upload.
366    ///
367    /// `None` when no multipart upload was created, when AbortMultipartUpload removed it, and on
368    /// errors from other operations.
369    pub fn upload_id(&self) -> Option<&str> {
370        self.extra.as_ref().and_then(|e| e.upload_id.as_deref())
371    }
372
373    /// Per-object upload failures, when this error aggregates a bulk upload.
374    pub fn failed_uploads(&self) -> Option<&[FailedUpload]> {
375        self.extra
376            .as_ref()
377            .and_then(|e| e.failed_uploads.as_deref())
378    }
379
380    /// Per-object download failures, when this error aggregates a bulk download.
381    pub fn failed_downloads(&self) -> Option<&[FailedDownload]> {
382        self.extra
383            .as_ref()
384            .and_then(|e| e.failed_downloads.as_deref())
385    }
386
387    /// Attaches chunk location, preserving kind and source.
388    pub(crate) fn with_chunk(mut self, location: ChunkRef) -> Self {
389        self.extra_mut().location = Some(location);
390        self
391    }
392
393    /// Attaches the local operation that failed and the path it acted on,
394    /// preserving kind and source. See [`io_at`] for `action`.
395    pub(crate) fn with_local(mut self, action: &'static str, path: impl Into<PathBuf>) -> Self {
396        self.extra_mut().local = Some(LocalContext {
397            action,
398            path: path.into(),
399            key: None,
400        });
401        self
402    }
403
404    /// Names the object key a local operation attached with
405    /// [`with_local`](Self::with_local) was for. No effect without one.
406    pub(crate) fn with_local_key(mut self, key: impl Into<String>) -> Self {
407        if let Some(local) = self.extra.as_mut().and_then(|e| e.local.as_mut()) {
408            local.key = Some(key.into());
409        }
410        self
411    }
412
413    /// Attaches the ID of a multipart upload the failed upload left open,
414    /// preserving kind and source.
415    pub(crate) fn with_upload_id(mut self, upload_id: String) -> Self {
416        self.extra_mut().upload_id = Some(upload_id);
417        self
418    }
419
420    /// Attaches per-object upload failures, preserving kind and source.
421    pub(crate) fn with_failed_uploads(mut self, failed: Vec<FailedUpload>) -> Self {
422        self.extra_mut().failed_uploads = Some(failed);
423        self
424    }
425
426    /// Attaches per-object download failures, preserving kind and source.
427    pub(crate) fn with_failed_downloads(mut self, failed: Vec<FailedDownload>) -> Self {
428        self.extra_mut().failed_downloads = Some(failed);
429        self
430    }
431}
432
433impl fmt::Display for Error {
434    // Renders this error's own context only. Source detail (the underlying
435    // SdkError message, checksum values) is reached through
436    // [`std::error::Error::source`], e.g. via `DisplayErrorContext`.
437    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
438        match &self.kind {
439            ErrorKind::InputInvalid => write!(f, "invalid input")?,
440            ErrorKind::IOError => write!(f, "I/O error")?,
441            ErrorKind::RuntimeError => write!(f, "runtime error")?,
442            ErrorKind::ObjectNotDiscoverable => write!(f, "object discovery failed")?,
443            ErrorKind::ChildOperationFailed => {
444                write!(f, "child operation failed")?;
445                // A bulk transfer failed on one or more objects. Name the first
446                // failure and the total so the top-level message is actionable;
447                // the full per-object detail (including each object's own error)
448                // is reached via `failed_uploads` / `failed_downloads`.
449                let first_and_count = self
450                    .failed_uploads()
451                    .map(|f| {
452                        let id = f
453                            .first()
454                            .and_then(|u| u.source_path())
455                            .map(|p| p.display().to_string());
456                        (id, f.len())
457                    })
458                    .or_else(|| {
459                        self.failed_downloads().map(|f| {
460                            let id = f.first().and_then(|d| d.input().key()).map(str::to_owned);
461                            (id, f.len())
462                        })
463                    });
464                if let Some((id, n)) = first_and_count {
465                    match id {
466                        Some(id) => write!(f, ": {id}")?,
467                        None => write!(f, ": 1 object")?,
468                    }
469                    if n > 1 {
470                        write!(f, " (and {} more)", n - 1)?;
471                    }
472                }
473            }
474            ErrorKind::OperationCancelled => write!(f, "operation cancelled")?,
475            ErrorKind::ServiceError => {
476                write!(f, "service error")?;
477                if let Some(m) = self.service() {
478                    write!(f, " calling {}", m.operation)?;
479                    if let Some(c) = &m.code {
480                        write!(f, " ({c})")?;
481                    }
482                }
483            }
484            ErrorKind::IntegrityError(ie) => {
485                write!(f, "integrity error")?;
486                if let Some(a) = &ie.algorithm {
487                    write!(f, " ({a})")?;
488                }
489            }
490        }
491
492        if let Some(local) = self.extra.as_ref().and_then(|e| e.local.as_ref()) {
493            write!(f, " {} \"{}\"", local.action, local.path.display())?;
494            if let Some(key) = &local.key {
495                write!(f, " (key \"{key}\")")?;
496            }
497        }
498
499        if let Some(loc) = self.chunk() {
500            match &loc.range {
501                Some(r) => write!(f, " [chunk {}, bytes {}-{}]", loc.seq, r.start(), r.end())?,
502                None => write!(f, " [chunk {}]", loc.seq)?,
503            }
504        }
505
506        // Request ids are not part of the underlying SdkError's own Display, so
507        // include them here to keep a logged error traceable.
508        if let Some(m) = self.service() {
509            match (&m.request_id, &m.extended_request_id) {
510                (Some(rid), Some(ext)) => {
511                    write!(f, " (request id: {rid}, extended request id: {ext})")?
512                }
513                (Some(rid), None) => write!(f, " (request id: {rid})")?,
514                _ => {}
515            }
516        }
517        Ok(())
518    }
519}
520
521impl std::error::Error for Error {
522    /// The underlying cause.
523    ///
524    /// For [`ErrorKind::ChildOperationFailed`] carrying per-object failures,
525    /// this is the first failed object's error, so the source chain reaches
526    /// the child's own cause. Otherwise it is the error this one was created
527    /// from.
528    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
529        if matches!(self.kind, ErrorKind::ChildOperationFailed) {
530            let first_child = self
531                .failed_uploads()
532                .and_then(<[FailedUpload]>::first)
533                .map(FailedUpload::error)
534                .or_else(|| {
535                    self.failed_downloads()
536                        .and_then(<[FailedDownload]>::first)
537                        .map(FailedDownload::error)
538                });
539            if let Some(child) = first_child {
540                return Some(child);
541            }
542        }
543        Some(self.source.as_ref())
544    }
545}
546
547impl From<std::io::Error> for Error {
548    fn from(value: std::io::Error) -> Self {
549        Self::new(ErrorKind::IOError, value)
550    }
551}
552
553impl From<aws_smithy_types::error::operation::BuildError> for Error {
554    fn from(value: aws_smithy_types::error::operation::BuildError) -> Self {
555        Self::new(ErrorKind::InputInvalid, value)
556    }
557}
558
559pub(crate) fn invalid_input<E>(err: E) -> Error
560where
561    E: Into<BoxError>,
562{
563    Error::new(ErrorKind::InputInvalid, err)
564}
565
566/// An [`ErrorKind::IOError`] for a local filesystem operation on `path` that
567/// failed with `err`.
568///
569/// `action` is a lowercase gerund phrase whose object is `path`, such as
570/// `"opening"`, `"reading"`, or `"renaming temporary file to"`. `Display`
571/// renders `I/O error {action} "{path}"`; `err` is the source.
572pub(crate) fn io_at(action: &'static str, path: impl Into<PathBuf>, err: std::io::Error) -> Error {
573    Error::new(ErrorKind::IOError, err).with_local(action, path)
574}
575
576/// Object discovery failed for a non-service reason (e.g. a response missing
577/// required metadata). Service-call failures during discovery convert from their
578/// `SdkError` and become [`ErrorKind::ServiceError`].
579pub(crate) fn discovery_failed<E>(err: E) -> Error
580where
581    E: Into<BoxError>,
582{
583    Error::new(ErrorKind::ObjectNotDiscoverable, err)
584}
585
586pub(crate) fn from_kind<E>(kind: ErrorKind) -> impl FnOnce(E) -> Error
587where
588    E: Into<BoxError>,
589{
590    |err| Error::new(kind, err)
591}
592
593/// Maps a body-stream error to an [`Error`].
594///
595/// `checksum` is the response's checksum outcome when `err` was read. A
596/// [`ChecksumOutcome::Mismatch`] makes it an [`ErrorKind::IntegrityError`] carrying the
597/// algorithm and the expected and computed checksums. Any other outcome, or none,
598/// makes it an [`ErrorKind::IOError`].
599pub(crate) fn body_read_error<E>(err: E, checksum: Option<ChecksumOutcome>) -> Error
600where
601    E: Into<BoxError>,
602{
603    match checksum {
604        Some(ChecksumOutcome::Mismatch {
605            algorithm,
606            expected,
607            computed,
608        }) => Error {
609            kind: ErrorKind::IntegrityError(IntegrityError {
610                algorithm: Some(checksum_algorithm(algorithm)),
611                expected: Some(expected),
612                computed: Some(computed),
613            }),
614            source: err.into(),
615            extra: None,
616        },
617        _ => Error::new(ErrorKind::IOError, err),
618    }
619}
620
621/// Returns an integrity error carrying the algorithm and stored/calculated S3 header values.
622///
623/// `expected` and `computed` are base64 checksum encodings for the same algorithm.
624pub(crate) fn integrity_mismatch(
625    algorithm: ChecksumAlgorithm,
626    expected: String,
627    computed: String,
628) -> Error {
629    Error::new(
630        ErrorKind::IntegrityError(IntegrityError {
631            algorithm: Some(algorithm),
632            expected: Some(expected),
633            computed: Some(computed),
634        }),
635        "calculated object checksum does not match its stored value",
636    )
637}
638
639/// The [`ChecksumAlgorithm`] named like a response checksum algorithm: its variant
640/// for that name, or `Unknown` for a name it has no variant for. It maps by name so
641/// an algorithm a newer SDK validates, which observability has no variant for yet,
642/// still reads `Validated`.
643pub(crate) fn checksum_algorithm(algorithm: ResponseChecksumAlgorithm) -> ChecksumAlgorithm {
644    ChecksumAlgorithm::from(algorithm.as_str().to_ascii_uppercase().as_str())
645}
646
647/// Reads the operation name and service code/message/request ids into a
648/// [`ServiceMetadata`].
649fn service_metadata<E, R>(operation: &'static str, e: &SdkError<E, R>) -> ServiceMetadata
650where
651    E: ProvideErrorMetadata,
652    SdkError<E, R>: RequestId + RequestIdExt,
653{
654    ServiceMetadata {
655        operation,
656        code: e.code().map(str::to_owned),
657        message: e.message().map(str::to_owned),
658        request_id: e.request_id().map(str::to_owned),
659        extended_request_id: e.extended_request_id().map(str::to_owned),
660    }
661}
662
663/// Whether a single [`ConnectorError`] frame denotes a transient transport
664/// failure: an IO error, a client-side timeout, or one the http client tagged
665/// [`RetryErrorKind::TransientError`] (an incomplete/truncated response, TLS
666/// negotiation timeout, and similar). A bare `Other(None)` connector error
667/// carries no marker and is not transient on its own.
668fn connector_error_is_transient(conn: &ConnectorError) -> bool {
669    conn.is_io() || conn.is_timeout() || conn.as_other() == Some(RetryErrorKind::TransientError)
670}
671
672/// Whether an `SdkError` is a transient transport failure — a connection-level
673/// IO error, a client-side timeout, or a connector error the http client tagged
674/// [`RetryErrorKind::TransientError`] (e.g. an incomplete/truncated HTTP
675/// response) — rather than a service response. Captured here because the
676/// flattening into [`ErrorKind::ServiceError`] erases the `SdkError` variant.
677///
678/// Walks the error source chain rather than inspecting only the outermost
679/// [`ConnectorError`]. A nested dispatch can re-wrap a fully-classified inner
680/// connector error inside an outer `ConnectorError::Other(None)`, which carries
681/// no transient marker; the SDK's own `TransientErrorClassifier` inspects only
682/// that outer frame and misclassifies the error as non-retryable. Scanning every
683/// `ConnectorError` in the chain recovers the inner classification.
684///
685/// Deliberately excludes service responses: a 503 `SlowDown` arrives as a
686/// `ServiceError`, not a `DispatchFailure`, so throttling is never classified
687/// transient here (see `retry::classify_upload_part_retry` for why that matters).
688fn is_sdk_transient_transport<E, R>(e: &SdkError<E, R>) -> bool {
689    if let SdkError::TimeoutError(_) = e {
690        return true;
691    }
692    // A DispatchFailure carries a ConnectorError; scan it and every nested
693    // ConnectorError in the source chain for a transient classification.
694    let conn = match e {
695        SdkError::DispatchFailure(df) => df.as_connector_error(),
696        _ => return false,
697    };
698    let Some(conn) = conn else { return false };
699    if connector_error_is_transient(conn) {
700        return true;
701    }
702    let mut source = std::error::Error::source(conn);
703    while let Some(err) = source {
704        if let Some(conn) = err.downcast_ref::<ConnectorError>() {
705            if connector_error_is_transient(conn) {
706                return true;
707            }
708        }
709        source = err.source();
710    }
711    false
712}
713
714/// Associates an SDK service error type with its originating S3 operation.
715pub(crate) trait SdkOperationError:
716    ProvideErrorMetadata + std::error::Error + Send + Sync + 'static
717{
718    const OPERATION_NAME: &'static str;
719}
720
721/// Converts an `SdkError` into an [`ErrorKind::ServiceError`], capturing the
722/// operation name, service metadata, and whether it was a transient transport
723/// failure.
724pub(crate) fn service_error<E: SdkOperationError>(e: SdkError<E, HttpResponse>) -> Error {
725    let service = service_metadata(E::OPERATION_NAME, &e);
726    let http_status = e.raw_response().map(|response| response.status().as_u16());
727    let transient_transport = is_sdk_transient_transport(&e);
728    Error {
729        kind: ErrorKind::ServiceError,
730        source: Box::new(e),
731        extra: Some(Box::new(ErrorExtra {
732            service: Some(service),
733            http_status,
734            transient_transport,
735            ..Default::default()
736        })),
737    }
738}
739
740/// Converts a failed HeadObject into an [`ErrorKind::ServiceError`].
741///
742/// S3 answers a failed HEAD with the status and request ids only. A HEAD response has
743/// no body, so it carries no error code or message. Where the status identifies a
744/// single S3 code, the code is filled in: 412 is `PreconditionFailed`, 304 is
745/// `NotModified`, and 416 is `InvalidRange`. Any other status keeps the code the SDK
746/// reported: `NotFound` for 404, and none otherwise.
747pub(crate) fn head_object_error(e: SdkError<HeadObjectError, HttpResponse>) -> Error {
748    let mut error = service_error(e);
749    let code = error
750        .extra
751        .as_ref()
752        .and_then(|extra| extra.http_status)
753        .and_then(head_status_code);
754    if let (Some(code), Some(service)) = (
755        code,
756        error
757            .extra
758            .as_mut()
759            .and_then(|extra| extra.service.as_mut()),
760    ) {
761        service.code.get_or_insert_with(|| code.to_owned());
762    }
763    error
764}
765
766/// The S3 error code a failed HEAD's `status` alone identifies, if there is exactly one.
767fn head_status_code(status: u16) -> Option<&'static str> {
768    match status {
769        304 => Some("NotModified"),
770        412 => Some("PreconditionFailed"),
771        416 => Some("InvalidRange"),
772        _ => None,
773    }
774}
775
776/// Converts a successful S3 response that the transfer cannot use, such as one missing a field
777/// the transfer requires, into an [`ErrorKind::ServiceError`].
778///
779/// The error carries the same service metadata as one converted from a failed request:
780/// `operation`, `message`, and the request ids read from `output`. `code` is `None` because S3
781/// reported no error. `message` is also the error's source, so it appears in the error chain.
782pub(crate) fn invalid_service_response<O>(
783    operation: &'static str,
784    output: &O,
785    message: impl Into<String>,
786) -> Error
787where
788    O: RequestId + RequestIdExt,
789{
790    invalid_service_response_ids(
791        operation,
792        output.request_id(),
793        output.extended_request_id(),
794        message,
795    )
796}
797
798/// [`invalid_service_response`] for a response already converted to transfer manager
799/// metadata, which carries the request ids but not the SDK's request id traits.
800pub(crate) fn invalid_service_response_ids(
801    operation: &'static str,
802    request_id: Option<&str>,
803    extended_request_id: Option<&str>,
804    message: impl Into<String>,
805) -> Error {
806    let message = message.into();
807    Error {
808        kind: ErrorKind::ServiceError,
809        source: message.clone().into(),
810        extra: Some(Box::new(ErrorExtra {
811            service: Some(ServiceMetadata {
812                operation,
813                code: None,
814                message: Some(message),
815                request_id: request_id.map(str::to_owned),
816                extended_request_id: extended_request_id.map(str::to_owned),
817            }),
818            ..Default::default()
819        })),
820    }
821}
822
823macro_rules! sdk_operation_error {
824    ($err:ty, $op:literal) => {
825        impl SdkOperationError for $err {
826            const OPERATION_NAME: &'static str = $op;
827        }
828    };
829}
830
831sdk_operation_error!(GetObjectError, "GetObject");
832sdk_operation_error!(HeadObjectError, "HeadObject");
833sdk_operation_error!(PutObjectError, "PutObject");
834sdk_operation_error!(UploadPartError, "UploadPart");
835sdk_operation_error!(CreateMultipartUploadError, "CreateMultipartUpload");
836sdk_operation_error!(CompleteMultipartUploadError, "CompleteMultipartUpload");
837sdk_operation_error!(AbortMultipartUploadError, "AbortMultipartUpload");
838sdk_operation_error!(ListObjectsV2Error, "ListObjectsV2");
839
840impl From<crate::io::walk::WalkError> for Error {
841    /// Maps a directory-walk failure to a transfer error, preserving the
842    /// `WalkError` as the source so its classification and path remain reachable
843    /// via [`std::error::Error::source`].
844    ///
845    /// A `ListObjectsV2` service failure is recovered to a full
846    /// [`ErrorKind::ServiceError`] (with operation, code, and request ids); an
847    /// unreadable or non-directory source root is [`ErrorKind::InputInvalid`];
848    /// per-entry filesystem failures are [`ErrorKind::IOError`].
849    fn from(e: crate::io::walk::WalkError) -> Self {
850        use crate::io::walk::WalkErrorKind;
851        let path = e.path().map(std::path::Path::to_path_buf);
852        let local = |err: Error| match path {
853            Some(path) => err.with_local("walking", path),
854            None => err,
855        };
856        match e.kind() {
857            WalkErrorKind::Service => {
858                // The S3 walker's only service call is ListObjectsV2, so the
859                // boxed source downcasts to that SdkError.
860                match e
861                    .into_source()
862                    .downcast::<SdkError<ListObjectsV2Error, HttpResponse>>()
863                {
864                    Ok(sdk) => service_error(*sdk),
865                    Err(src) => Error::new(ErrorKind::ObjectNotDiscoverable, src),
866                }
867            }
868            WalkErrorKind::SourceUnreadable | WalkErrorKind::NotADirectory => {
869                local(Error::new(ErrorKind::InputInvalid, e))
870            }
871            WalkErrorKind::Io
872            | WalkErrorKind::PermissionDenied
873            | WalkErrorKind::BrokenSymlink
874            | WalkErrorKind::SymlinkCycle => local(Error::new(ErrorKind::IOError, e)),
875        }
876    }
877}
878
879#[cfg(test)]
880mod tests {
881    use super::*;
882
883    /// Build a ServiceError with the given metadata for Display tests.
884    fn service(
885        operation: &'static str,
886        code: Option<&str>,
887        request_id: Option<&str>,
888        extended_request_id: Option<&str>,
889    ) -> Error {
890        Error {
891            kind: ErrorKind::ServiceError,
892            source: "boom".into(),
893            extra: Some(Box::new(ErrorExtra {
894                service: Some(ServiceMetadata {
895                    operation,
896                    code: code.map(str::to_owned),
897                    message: Some("the message".to_owned()),
898                    request_id: request_id.map(str::to_owned),
899                    extended_request_id: extended_request_id.map(str::to_owned),
900                }),
901                ..Default::default()
902            })),
903        }
904    }
905
906    #[test]
907    fn display_plain_kind() {
908        let e = Error::new(ErrorKind::OperationCancelled, "x");
909        assert_eq!(e.to_string(), "operation cancelled");
910    }
911
912    /// A mismatch is classified from the response's checksum outcome, not from the
913    /// body error's type, so it holds when the body error carries no checksum error
914    /// type, as when two copies of `aws-smithy-checksums` are linked.
915    #[test]
916    fn body_read_error_classifies_mismatch_from_checksum_outcome() {
917        let outcome = ChecksumOutcome::Mismatch {
918            algorithm: ResponseChecksumAlgorithm::Crc32,
919            expected: "AAAAAA==".to_owned(),
920            computed: "BBBBBB==".to_owned(),
921        };
922        let e = body_read_error("opaque body error", Some(outcome));
923        let ErrorKind::IntegrityError(ie) = e.kind() else {
924            panic!("expected IntegrityError, got {:?}", e.kind());
925        };
926        assert_eq!(ie.algorithm(), Some(&ChecksumAlgorithm::Crc32));
927        assert_eq!(ie.expected(), Some("AAAAAA=="));
928        assert_eq!(ie.computed(), Some("BBBBBB=="));
929    }
930
931    /// Every algorithm the response outcome names maps to the variant of the same
932    /// name.
933    #[test]
934    fn checksum_algorithm_maps_each_known_name() {
935        for (algorithm, expected) in [
936            (ResponseChecksumAlgorithm::Crc32, ChecksumAlgorithm::Crc32),
937            (ResponseChecksumAlgorithm::Crc32c, ChecksumAlgorithm::Crc32C),
938            (
939                ResponseChecksumAlgorithm::Crc64Nvme,
940                ChecksumAlgorithm::Crc64Nvme,
941            ),
942            (ResponseChecksumAlgorithm::Sha1, ChecksumAlgorithm::Sha1),
943            (ResponseChecksumAlgorithm::Sha256, ChecksumAlgorithm::Sha256),
944        ] {
945            assert_eq!(checksum_algorithm(algorithm), expected);
946        }
947    }
948
949    #[test]
950    fn display_service_error_full() {
951        let e = service(
952            "GetObject",
953            Some("NoSuchKey"),
954            Some("REQ123"),
955            Some("EXT456"),
956        );
957        assert_eq!(
958            e.to_string(),
959            "service error calling GetObject (NoSuchKey) (request id: REQ123, extended request id: EXT456)"
960        );
961    }
962
963    #[test]
964    fn display_service_error_request_id_only() {
965        let e = service("PutObject", Some("AccessDenied"), Some("REQ123"), None);
966        assert_eq!(
967            e.to_string(),
968            "service error calling PutObject (AccessDenied) (request id: REQ123)"
969        );
970    }
971
972    #[test]
973    fn display_service_error_no_metadata() {
974        let e = service("HeadObject", None, None, None);
975        assert_eq!(e.to_string(), "service error calling HeadObject");
976    }
977
978    #[test]
979    fn display_omits_source_message() {
980        // The underlying message is reached via source(), not Display.
981        let e = service("GetObject", Some("NoSuchKey"), None, None);
982        assert!(!e.to_string().contains("the message"));
983    }
984
985    #[test]
986    fn display_integrity_error() {
987        let e = Error {
988            kind: ErrorKind::IntegrityError(IntegrityError {
989                algorithm: Some(ChecksumAlgorithm::Crc32),
990                expected: Some("AAAA".to_owned()),
991                computed: Some("BBBB".to_owned()),
992            }),
993            source: "mismatch".into(),
994            extra: None,
995        };
996        // Algorithm is shown; expected/computed are reached via accessors/source.
997        assert_eq!(e.to_string(), "integrity error (CRC32)");
998    }
999
1000    #[test]
1001    fn display_with_chunk() {
1002        let e = Error::new(ErrorKind::IOError, "x").with_chunk(ChunkRef::new(3, Some(0..=1023)));
1003        assert_eq!(e.to_string(), "I/O error [chunk 3, bytes 0-1023]");
1004    }
1005
1006    #[test]
1007    fn display_chunk_no_range() {
1008        let e = Error::new(ErrorKind::IOError, "x").with_chunk(ChunkRef::new(7, None));
1009        assert_eq!(e.to_string(), "I/O error [chunk 7]");
1010    }
1011
1012    #[test]
1013    fn is_not_found_matches_codes() {
1014        assert!(service("GetObject", Some("NoSuchKey"), None, None).is_not_found());
1015        assert!(!service("GetObject", Some("AccessDenied"), None, None).is_not_found());
1016    }
1017
1018    #[test]
1019    fn display_child_operation_failed_bare() {
1020        // No attached failure list: the bare kind message, no trailing detail.
1021        let e = Error::new(ErrorKind::ChildOperationFailed, "x");
1022        assert_eq!(e.to_string(), "child operation failed");
1023    }
1024
1025    #[test]
1026    fn display_child_operation_failed_names_first_and_count() {
1027        let failed = vec![
1028            FailedUpload {
1029                input: None,
1030                error: Error::new(ErrorKind::ServiceError, "boom"),
1031                source_path: Some(std::path::PathBuf::from("/data/a.bin")),
1032            },
1033            FailedUpload {
1034                input: None,
1035                error: Error::new(ErrorKind::ServiceError, "boom"),
1036                source_path: Some(std::path::PathBuf::from("/data/b.bin")),
1037            },
1038        ];
1039        let e = Error::new(ErrorKind::ChildOperationFailed, "aborted").with_failed_uploads(failed);
1040        assert_eq!(
1041            e.to_string(),
1042            "child operation failed: /data/a.bin (and 1 more)"
1043        );
1044    }
1045
1046    #[test]
1047    fn display_child_operation_failed_single_no_path() {
1048        // A failure list carrying no source path still reports a count.
1049        let failed = vec![FailedUpload {
1050            input: None,
1051            error: Error::new(ErrorKind::ServiceError, "boom"),
1052            source_path: None,
1053        }];
1054        let e = Error::new(ErrorKind::ChildOperationFailed, "aborted").with_failed_uploads(failed);
1055        assert_eq!(e.to_string(), "child operation failed: 1 object");
1056    }
1057
1058    #[test]
1059    fn display_local_context_names_action_and_path() {
1060        let e = io_at(
1061            "creating temporary file for",
1062            "out/logs/a.log",
1063            std::io::Error::from(std::io::ErrorKind::NotFound),
1064        );
1065        assert_eq!(
1066            e.to_string(),
1067            "I/O error creating temporary file for \"out/logs/a.log\""
1068        );
1069        // The OS error is the source, not part of the message.
1070        let source = std::error::Error::source(&e)
1071            .and_then(|s| s.downcast_ref::<std::io::Error>())
1072            .expect("the io::Error is the direct source");
1073        assert_eq!(source.kind(), std::io::ErrorKind::NotFound);
1074
1075        let e = io_at(
1076            "creating directory",
1077            "out/logs",
1078            std::io::Error::from(std::io::ErrorKind::PermissionDenied),
1079        )
1080        .with_local_key("logs/a.log");
1081        assert_eq!(
1082            e.to_string(),
1083            "I/O error creating directory \"out/logs\" (key \"logs/a.log\")"
1084        );
1085        // A key without a local operation adds nothing.
1086        let e = Error::new(ErrorKind::IOError, "x").with_local_key("logs/a.log");
1087        assert_eq!(e.to_string(), "I/O error");
1088    }
1089
1090    #[test]
1091    fn display_walker_error_names_path() {
1092        use crate::io::walk::{WalkError, WalkErrorKind};
1093        let e = Error::from(WalkError::new(
1094            Some(std::path::PathBuf::from("/data/sub")),
1095            WalkErrorKind::PermissionDenied,
1096            Box::new(std::io::Error::from(std::io::ErrorKind::PermissionDenied)),
1097        ));
1098        assert_eq!(e.kind(), &ErrorKind::IOError);
1099        assert_eq!(e.to_string(), "I/O error walking \"/data/sub\"");
1100
1101        let root = Error::from(WalkError::new(
1102            Some(std::path::PathBuf::from("/data/missing")),
1103            WalkErrorKind::SourceUnreadable,
1104            Box::new(std::io::Error::from(std::io::ErrorKind::NotFound)),
1105        ));
1106        assert_eq!(root.kind(), &ErrorKind::InputInvalid);
1107        assert_eq!(root.to_string(), "invalid input walking \"/data/missing\"");
1108    }
1109
1110    #[test]
1111    fn child_operation_failed_source_is_first_failed_child() {
1112        let failed = vec![
1113            FailedUpload {
1114                input: None,
1115                error: Error::new(ErrorKind::ServiceError, "first"),
1116                source_path: None,
1117            },
1118            FailedUpload {
1119                input: None,
1120                error: Error::new(ErrorKind::ServiceError, "second"),
1121                source_path: None,
1122            },
1123        ];
1124        let e = Error::new(ErrorKind::ChildOperationFailed, "aborted").with_failed_uploads(failed);
1125        let source = std::error::Error::source(&e)
1126            .and_then(|s| s.downcast_ref::<Error>())
1127            .expect("the source is a child's error");
1128        assert!(std::ptr::eq(source, e.failed_uploads().unwrap()[0].error()));
1129
1130        // Without per-object failures, the stored source is reported.
1131        let bare = Error::new(ErrorKind::ChildOperationFailed, "aborted");
1132        assert_eq!(
1133            std::error::Error::source(&bare).map(|s| s.to_string()),
1134            Some("aborted".to_owned())
1135        );
1136    }
1137
1138    #[test]
1139    fn upload_id_is_none_unless_attached() {
1140        let e = Error::new(ErrorKind::ServiceError, "x");
1141        assert_eq!(e.upload_id(), None);
1142        let e = e.with_upload_id("abc".to_owned());
1143        assert_eq!(e.upload_id(), Some("abc"));
1144        // The upload ID is not part of the message.
1145        assert_eq!(e.to_string(), "service error");
1146    }
1147
1148    // --- transient-transport classification -----------------------------------
1149
1150    use aws_sdk_s3::operation::get_object::GetObjectError;
1151
1152    fn dispatch(conn: ConnectorError) -> SdkError<GetObjectError, HttpResponse> {
1153        SdkError::dispatch_failure(conn)
1154    }
1155
1156    #[test]
1157    fn transient_nested_transient_marker_under_other_none_is_transient() {
1158        // The Windows failure shape: the http client classified an incomplete
1159        // response as ConnectorError::Other(TransientError), but a nested dispatch
1160        // re-wrapped it inside an outer ConnectorError::Other(None). The outer
1161        // frame carries no marker; the classifier must walk the chain to the inner
1162        // marker. Inspecting only the outer frame (the previous behavior) would
1163        // classify this non-transient and abort a retryable error.
1164        let inner = ConnectorError::other(
1165            "incomplete message".into(),
1166            Some(RetryErrorKind::TransientError),
1167        );
1168        let inner_sdk: SdkError<GetObjectError, HttpResponse> = SdkError::dispatch_failure(inner);
1169        let outer = ConnectorError::other(Box::new(inner_sdk), None);
1170        assert!(
1171            is_sdk_transient_transport(&dispatch(outer)),
1172            "a TransientError marker nested under an outer Other(None) must classify transient"
1173        );
1174    }
1175
1176    #[test]
1177    fn transient_outer_io_is_transient() {
1178        assert!(is_sdk_transient_transport(&dispatch(ConnectorError::io(
1179            "reset".into()
1180        ))));
1181    }
1182
1183    #[test]
1184    fn transient_outer_timeout_is_transient() {
1185        assert!(is_sdk_transient_transport(&dispatch(
1186            ConnectorError::timeout("connect".into())
1187        )));
1188    }
1189
1190    #[test]
1191    fn transient_bare_other_none_is_not_transient() {
1192        // A connector Other(None) with no transient marker anywhere in the chain
1193        // is not transient — the fix must not blanket-retry every Other error.
1194        assert!(!is_sdk_transient_transport(&dispatch(
1195            ConnectorError::other("unclassified".into(), None)
1196        )));
1197    }
1198
1199    #[test]
1200    fn transient_user_error_is_not_transient() {
1201        // A user error (e.g. malformed request) must never be treated transient.
1202        assert!(!is_sdk_transient_transport(&dispatch(
1203            ConnectorError::user("bad request".into())
1204        )));
1205    }
1206
1207    // --- conditional-write precondition failures ------------------------------
1208
1209    use aws_smithy_runtime_api::http::StatusCode;
1210    use aws_smithy_types::body::SdkBody;
1211
1212    #[test]
1213    fn precondition_failure_surfaces_as_service_error_with_code() {
1214        // A failed `If-Match` / `If-None-Match` gets no kind of its own: callers
1215        // identify it by the service code. S3 supplies that in the response body,
1216        // so it is reachable whatever status the failure arrives with.
1217        let sdk: SdkError<PutObjectError, HttpResponse> = SdkError::service_error(
1218            PutObjectError::generic(
1219                aws_smithy_types::error::ErrorMetadata::builder()
1220                    .code("PreconditionFailed")
1221                    .build(),
1222            ),
1223            HttpResponse::new(StatusCode::try_from(412).unwrap(), SdkBody::empty()),
1224        );
1225        let err = service_error(sdk);
1226        assert!(matches!(err.kind(), ErrorKind::ServiceError));
1227        assert_eq!(err.code(), Some("PreconditionFailed"));
1228        assert_eq!(err.operation_name(), Some("PutObject"));
1229        // The underlying SdkError is preserved as the source.
1230        assert!(std::error::Error::source(&err)
1231            .and_then(|s| s.downcast_ref::<SdkError<PutObjectError, HttpResponse>>())
1232            .is_some());
1233    }
1234}