Checksums in S3 example updates

Added a SHA256 checksum to the multipart upload example. Added a new basic
example showing the use of a checksum while doing a basic PutObject.
Other cleanup.

Author: shepazon

swift/example_code/s3/checksums/Package.swift

@@ -0,0 +1,40 @@
+// swift-tools-version: 5.9
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+//
+// The swift-tools-version declares the minimum version of Swift required to
+// build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "checksums",
+    // Let Xcode know the minimum Apple platforms supported.
+    platforms: [
+        .macOS(.v13),
+        .iOS(.v15)
+    ],
+    dependencies: [
+        // Dependencies declare other packages that this package depends on.
+        .package(
+            url: "https://github.com/awslabs/aws-sdk-swift",
+            from: "1.0.0"),
+        .package(
+            url: "https://github.com/apple/swift-argument-parser.git",
+            branch: "main"
+        )
+    ],
+    targets: [
+        // Targets are the basic building blocks of a package, defining a module or a test suite.
+        // Targets can depend on other targets in this package and products
+        // from dependencies.
+        .executableTarget(
+            name: "checksums",
+            dependencies: [
+                .product(name: "AWSS3", package: "aws-sdk-swift"),
+                .product(name: "ArgumentParser", package: "swift-argument-parser")
+            ],
+            path: "Sources")
+
+    ]
+)

swift/example_code/s3/checksums/Sources/TransferError.swift

@@ -0,0 +1,47 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/// Errors thrown by the example's functions.
+enum TransferError: Error {
+    /// The destination directory for a download is missing or inaccessible.
+    case directoryError
+    /// An error occurred while downloading a file from Amazon S3.
+    case downloadError(_ message: String = "")
+    /// An error occurred moving the file to its final destination.
+    case fileMoveError
+    /// An error occurred when completing a multi-part upload to Amazon S3.
+    case multipartFinishError
+    /// An error occurred when starting a multi-part upload to Amazon S3.
+    case multipartStartError
+    /// An error occurred while uploading a file to Amazon S3.
+    case uploadError(_ message: String = "")
+    /// An error occurred while reading the file's contents.
+    case readError
+    /// An error occurred while presigning the URL.
+    case signingError
+    /// An error occurred while writing the file's contents.
+    case writeError
+
+    var errorDescription: String? {
+        switch self {
+        case .directoryError:
+            return "The destination directory could not be located or created"
+        case .downloadError(message: let message):
+            return "An error occurred attempting to download the file: \(message)"
+        case .fileMoveError:
+            return "The file couldn't be moved to the destination directory"
+        case .multipartFinishError:
+            return "An error occurred when completing a multi-part upload to Amazon S3."
+        case .multipartStartError:
+            return "An error occurred when starting a multi-part upload to Amazon S3."
+        case .uploadError(message: let message):
+            return "An error occurred attempting to upload the file: \(message)"
+        case .readError:
+            return "An error occurred while reading the file data"
+        case .signingError:
+            return "An error occurred while pre-signing the URL"
+        case .writeError:
+            return "An error occurred while writing the file data"
+        }
+    }
+}

swift/example_code/s3/checksums/Sources/entry.swift

@@ -0,0 +1,107 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+//
+/// An example demonstrating how to configure checksums when uploading to
+/// Amazon S3.
+
+// snippet-start:[swift.s3.checksums-upload.imports]
+import ArgumentParser
+import AWSClientRuntime
+import AWSS3
+import Foundation
+import Smithy
+// snippet-end:[swift.s3.checksums-upload.imports]
+
+// -MARK: - Async command line tool
+
+struct ExampleCommand: ParsableCommand {
+    // -MARK: Command arguments
+    @Option(help: "Path of local file to upload to Amazon S3")
+    var source: String
+    @Option(help: "Name of the Amazon S3 bucket to upload to")
+    var bucket: String
+    @Option(help: "Destination file path within the bucket")
+    var dest: String?
+    @Option(help: "Name of the Amazon S3 Region to use (default: us-east-1)")
+    var region = "us-east-1"
+
+    static var configuration = CommandConfiguration(
+        commandName: "checksums",
+        abstract: """
+        This example shows how to configure checksums when uploading to Amazon S3.
+        """,
+        discussion: """
+        """
+    )
+
+    // -MARK: - File upload
+    
+    func uploadFile(sourcePath: String, bucket: String, key: String?) async throws {
+        let fileURL = URL(fileURLWithPath: sourcePath)
+        let fileName: String
+
+        // If no key was provided, use the last component of the filename.
+        
+        if key == nil {
+            fileName = fileURL.lastPathComponent
+        } else {
+            fileName = key!
+        }
+        
+        // Create an Amazon S3 client in the desired Region.
+
+        let config = try await S3Client.S3ClientConfiguration(region: region)
+        let s3Client = S3Client(config: config)
+    
+        print("Uploading file from \(fileURL.path) to \(bucket)/\(fileName).")
+
+        let fileData = try Data(contentsOf: fileURL)
+        let dataStream = ByteStream.data(fileData)
+
+        // Use PutObject to send the file to Amazon S3. The checksum is
+        // specified by setting the `checksumAlgorithm` property. In this
+        // example, SHA256 is used.
+        
+        do {
+            // snippet-start:[swift.s3.checksums.upload-file]
+            _ = try await s3Client.putObject(
+                input: PutObjectInput(
+                    body: dataStream,
+                    bucket: bucket,
+                    checksumAlgorithm: .sha256,                                                                                                                                                                                                                                                                                                                                                                             
+                    key: fileName
+                )
+            )
+            // snippet-end:[swift.s3.checksums.upload-file]
+        } catch {
+            throw TransferError.uploadError("Error uploading file: \(error.localizedDescription)")
+        }
+        print("Uploaded \(sourcePath) to \(bucket)/\(fileName).")
+    }
+
+    // -MARK: - Asynchronous main code
+    
+    /// Called by ``main()`` to run the bulk of the example.
+    func runAsync() async throws {
+        try await uploadFile(sourcePath: source, bucket: bucket, key: dest)
+    }
+}
+
+// -MARK: - Entry point
+
+/// The program's asynchronous entry point.
+@main
+struct Main {
+    static func main() async {
+        let args = Array(CommandLine.arguments.dropFirst())
+
+        do {
+            let command = try ExampleCommand.parse(args)
+            try await command.runAsync()
+        } catch let error as TransferError {
+            print("ERROR: \(error.errorDescription ?? "Unknown error")")
+        } catch {
+            ExampleCommand.exit(withError: error)
+        }
+    }    
+}

swift/example_code/s3/multipart-upload/Sources/TransferError.swift

@@ -3,6 +3,8 @@
 
 /// Errors thrown by the example's functions.
 enum TransferError: Error {
+    /// The checksum is missing or erroneous.
+    case checksumError
     /// An error occurred when completing a multi-part upload to Amazon S3.
     case multipartFinishError(_ message: String = "")
     /// An error occurred when starting a multi-part upload to Amazon S3.
@@ -14,6 +16,8 @@ enum TransferError: Error {
 
     var errorDescription: String? {
         switch self {
+        case .checksumError:
+            return "The checksum is missing or incorrect"
         case .multipartFinishError(message: let message):
             return "An error occurred when completing a multi-part upload to Amazon S3. \(message)"
         case .multipartStartError:

swift/example_code/s3/multipart-upload/Sources/entry.swift

@@ -126,12 +126,13 @@ struct ExampleCommand: ParsableCommand {
     func startMultipartUpload(client: S3Client, bucket: String, key: String) async throws -> String {
         let multiPartUploadOutput: CreateMultipartUploadOutput
 
-        // First, create the multi-part upload.
+        // First, create the multi-part upload, using SHA256 checksums.
 
         do {
             multiPartUploadOutput = try await client.createMultipartUpload(
                 input: CreateMultipartUploadInput(
                     bucket: bucket,
+                    checksumAlgorithm: .sha256,
                     key: key
                 )
             )
@@ -170,18 +171,28 @@ struct ExampleCommand: ParsableCommand {
         let uploadPartInput = UploadPartInput(
             body: ByteStream.data(data),
             bucket: bucket,
+            checksumAlgorithm: .sha256,
             key: key,
             partNumber: partNumber,
             uploadId: uploadID
         )
 
+        // Upload the part with a SHA256 checksum.
         do {
-        let uploadPartOutput = try await client.uploadPart(input: uploadPartInput)
+            let uploadPartOutput = try await client.uploadPart(input: uploadPartInput)
+
             guard let eTag = uploadPartOutput.eTag else {
                 throw TransferError.uploadError("Missing eTag")
             } 
+            guard let checksum = uploadPartOutput.checksumSHA256 else {
+                throw TransferError.checksumError
+            }
 
-            return S3ClientTypes.CompletedPart(eTag: eTag, partNumber: partNumber)
+            return S3ClientTypes.CompletedPart(
+                checksumSHA256: checksum,
+                eTag: eTag,
+                partNumber: partNumber
+            )
         } catch {
             throw TransferError.uploadError(error.localizedDescription)
         }

swift/example_code/s3/presigned-urls/Sources/presigned-upload/TransferError.swift

@@ -3,45 +3,17 @@
 
 /// Errors thrown by the example's functions.
 enum TransferError: Error {
-    /// The destination directory for a download is missing or inaccessible.
-    case directoryError
-    /// An error occurred while downloading a file from Amazon S3.
-    case downloadError(_ message: String = "")
-    /// An error occurred moving the file to its final destination.
-    case fileMoveError
-    /// An error occurred when completing a multi-part upload to Amazon S3.
-    case multipartFinishError
-    /// An error occurred when starting a multi-part upload to Amazon S3.
-    case multipartStartError
     /// An error occurred while uploading a file to Amazon S3.
     case uploadError(_ message: String = "")
     /// An error occurred while reading the file's contents.
     case readError
-    /// An error occurred while presigning the URL.
-    case signingError
-    /// An error occurred while writing the file's contents.
-    case writeError
 
     var errorDescription: String? {
         switch self {
-        case .directoryError:
-            return "The destination directory could not be located or created"
-        case .downloadError(message: let message):
-            return "An error occurred attempting to download the file: \(message)"
-        case .fileMoveError:
-            return "The file couldn't be moved to the destination directory"
-        case .multipartFinishError:
-            return "An error occurred when completing a multi-part upload to Amazon S3."
-        case .multipartStartError:
-            return "An error occurred when starting a multi-part upload to Amazon S3."
         case .uploadError(message: let message):
             return "An error occurred attempting to upload the file: \(message)"
         case .readError:
             return "An error occurred while reading the file data"
-        case .signingError:
-            return "An error occurred while pre-signing the URL"
-        case .writeError:
-            return "An error occurred while writing the file data"
         }
     }
 }