rework errors

[aajtodd]

Issue #, if available:
#13

Description of changes:

Refactor our error representation into a single struct with an ErrorKind.

Rationale

Smithy errors are designed based on whether they are “informative” or “actionable” (see RFC-0022).

Below are the actual modeled SDK errors for the operations the S3 transfer manager is expected to invoke:

pub enum ListObjectsV2Error {
    NoSuchBucket(NoSuchBucket),
    Unhandled(Unhandled),
}

pub enum HeadObjectError {
    NotFound(NotFound),
    Unhandled(Unhandled),
}

pub enum GetObjectError {
    InvalidObjectState(InvalidObjectState),
    NoSuchKey(NoSuchKey),
    Unhandled(Unhandled),
}

pub enum PutObjectError {
    Unhandled(Unhandled),
}

pub enum UploadPartError {
    Unhandled(Unhandled),
}

pub enum CreateMultipartUploadError {
    Unhandled(Unhandled),
}

pub enum CompleteMultipartUploadError {
    Unhandled(Unhandled),
}

pub enum AbortMultipartUploadError {
    NoSuchUpload(NoSuchUpload),
    Unhandled(Unhandled),
}

There are not many variants here worth propagating up or that a user would find actionable. As such it makes little sense to expose them directly. The exception to this would be to access the raw HTTP response and/or metadata (e.g. request ID) but we should be able to capture that and expose it more conveniently for users without resorting to exposing the raw error.

The rest of our errors are more informative or bugs (e.g. invalid user input, runtime errors from poisoned mutex, join errors, etc).

This lead us to settle on a single struct with ErrorKind enum similar to std::io::Error.

Open Questions/Future

1. Error representation for when an error is encountered while already processing an error (e.g. upload of a single part fails; failure policy is to abort, we invoke AbortMutlipartUpload and that fails for some reason.) Do we make the secondary error available somehow or somehow expose that "cleanup" failed?
2. Metadata and raw HTTP response headers
   • We should be able to capture this and expose it fairly easily from the underlying SdkError

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[ysaito1001]

I like how this rework of errors came out!

Error representation for when an error is encountered while already processing an error

Yeah, maybe some sort of chain of errors so customers can trace the reasons of failures, but I'm not sure. Will certainly iterate on this.

[ysaito1001]

Nit: In smithy-rs, we have two patterns for the signature:

    pub fn kind(&self) -> ErrorKind

    pub fn kind(&self) -> &ErrorKind

I'd prefer the latter since it leaves the option to callers whether they want to clone ErrorKind or not, whereas the former always pays the cost of cloning the kind even when callers just need reference at the end of the day (cloning the kind could become more expensive depending on a new variant in the future). I'll leave it up to you, though.

[ysaito1001]

At some point, we probably want to re-export of BuildError in this library and use it here, reducing exposure of types from a different crate.

[ysaito1001]

Suggested change

	Some("NotFound") | Some("NoSuchKey") | Some("NoSuchUpload") | Some("NoSuchBucket") => {
	Some("NotFound" | "NoSuchKey" | "NoSuchUpload" | "NoSuchBucket") => {

I think this works with MSRV >= 1.76

[Velfi]

I wish error reporters were farther along so we could be specific here. Is noting "or similar" helpful? Will people understand what that means?

[Velfi]

With the way that these are defined, we can't add context to them later. That may be fine. Otherwise, we should define them like so:

/// General categories of transfer errors.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum ErrorKind {
    /// Operation input validation issues
    InputInvalid(InputInvalid),
}

pub struct InputInvalid {} 

[graebm]

👍