initial file based download

update interfaces

Author: GarrettBeatty

generator/.DevConfigs/9d07dc1e-d82d-4f94-8700-c7b57f872043.json

@@ -0,0 +1,11 @@
+{
+  "services": [
+    {
+      "serviceName": "S3",
+      "type": "minor",
+      "changeLogMessages": [
+        "Create DownloadWithResponseAsync API and implement multi part download"
+      ]
+    }
+  ]
+}

sdk/src/Services/S3/Custom/Transfer/Internal/AtomicFileHandler.cs

@@ -0,0 +1,202 @@
+/*******************************************************************************
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *  Licensed under the Apache License, Version 2.0 (the "License"). You may not use
+ *  this file except in compliance with the License. A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ *  or in the "license" file accompanying this file.
+ *  This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ *  CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ *  specific language governing permissions and limitations under the License.
+ * *****************************************************************************
+ *    __  _    _  ___
+ *   (  )( \/\/ )/ __)
+ *   /__\ \    / \__ \
+ *  (_)(_) \/\/  (___/
+ *
+ *  AWS SDK for .NET
+ *  API Version: 2006-03-01
+ *
+ */
+using System;
+using System.IO;
+using System.Security.Cryptography;
+
+namespace Amazon.S3.Transfer.Internal
+{
+    /// <summary>
+    /// Handles atomic file operations for multipart downloads using SEP-compliant temporary file pattern.
+    /// Creates .s3tmp.{uniqueId} files and ensures atomic commits to prevent partial file corruption.
+    /// </summary>
+    internal class AtomicFileHandler : IDisposable
+    {
+        private string _tempFilePath;
+        private readonly object _lockObject = new object();
+        private bool _disposed = false;
+
+        /// <summary>
+        /// Creates a temporary file with unique identifier for atomic operations.
+        /// Pattern: {destinationPath}.s3tmp.{8-char-unique-id}
+        /// </summary>
+        public string CreateTemporaryFile(string destinationPath)
+        {
+            if (string.IsNullOrEmpty(destinationPath))
+                throw new ArgumentException("Destination path cannot be null or empty", nameof(destinationPath));
+
+            // Generate unique 8-character identifier per SEP requirement
+            var uniqueId = GenerateUniqueId(8);
+            var tempPath = $"{destinationPath}.s3tmp.{uniqueId}";
+            
+            // Ensure uniqueness in directory (handle extremely rare collisions)
+            int attempts = 0;
+            while (File.Exists(tempPath) && attempts < 100)
+            {
+                uniqueId = GenerateUniqueId(8);
+                tempPath = $"{destinationPath}.s3tmp.{uniqueId}";
+                attempts++;
+            }
+            
+            if (attempts >= 100)
+                throw new InvalidOperationException("Unable to generate unique temporary file name");
+
+            // Create directory if it doesn't exist (Directory.CreateDirectory is idempotent)
+            var directory = Path.GetDirectoryName(tempPath);
+            if (!string.IsNullOrEmpty(directory))
+            {
+                Directory.CreateDirectory(directory);
+            }
+
+            // Create empty file to reserve the name
+            using (var stream = File.Create(tempPath))
+            {
+                // File created - immediately close it
+            }
+            
+            lock (_lockObject)
+            {
+                _tempFilePath = tempPath;
+            }
+
+            return tempPath;
+        }
+
+        /// <summary>
+        /// Atomically commits the temporary file to the final destination.
+        /// Uses File.Replace for atomic replacement when destination exists, or File.Move for new files.
+        /// This prevents data loss if the process crashes during commit.
+        /// </summary>
+        public void CommitFile(string tempPath, string destinationPath)
+        {
+            if (string.IsNullOrEmpty(tempPath))
+                throw new ArgumentException("Temp path cannot be null or empty", nameof(tempPath));
+            if (string.IsNullOrEmpty(destinationPath))
+                throw new ArgumentException("Destination path cannot be null or empty", nameof(destinationPath));
+            
+            if (!File.Exists(tempPath))
+                throw new FileNotFoundException($"Temporary file not found: {tempPath}");
+
+            try
+            {
+                // Use File.Replace for atomic replacement when overwriting existing file
+                // This prevents data loss if process crashes between delete and move operations
+                // File.Replace is atomic on Windows (ReplaceFile API) and Unix (rename syscall)
+                if (File.Exists(destinationPath))
+                {
+                    File.Replace(tempPath, destinationPath, null);
+                }
+                else
+                {
+                    // For new files, File.Move is sufficient and atomic on same volume
+                    File.Move(tempPath, destinationPath);
+                }
+
+                lock (_lockObject)
+                {
+                    if (_tempFilePath == tempPath)
+                        _tempFilePath = null; // Successfully committed
+                }
+            }
+            catch (Exception ex)
+            {
+                throw new InvalidOperationException($"Failed to commit temporary file {tempPath} to {destinationPath}", ex);
+            }
+        }
+
+        /// <summary>
+        /// Cleans up temporary file in case of failure or cancellation.
+        /// Safe to call multiple times.
+        /// </summary>
+        public void CleanupOnFailure(string tempPath = null)
+        {
+            var pathToClean = tempPath;
+            
+            if (string.IsNullOrEmpty(pathToClean))
+            {
+                lock (_lockObject)
+                {
+                    pathToClean = _tempFilePath;
+                }
+            }
+
+            if (string.IsNullOrEmpty(pathToClean))
+                return;
+
+            try
+            {
+                if (File.Exists(pathToClean))
+                {
+                    File.Delete(pathToClean);
+                }
+
+                lock (_lockObject)
+                {
+                    if (_tempFilePath == pathToClean)
+                        _tempFilePath = null;
+                }
+            }
+            catch (IOException)
+            {
+                // Log warning but don't throw - cleanup is best effort
+                // In production, this would use proper logging infrastructure
+            }
+            catch (UnauthorizedAccessException)
+            {
+                // Log warning but don't throw - cleanup is best effort
+            }
+        }
+
+        /// <summary>
+        /// Generates a cryptographically secure unique identifier of specified length.
+        /// Uses base32 encoding to avoid filesystem-problematic characters.
+        /// </summary>
+        private string GenerateUniqueId(int length)
+        {
+            const string base32Chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"; // RFC 4648 base32
+            
+            using (var rng = RandomNumberGenerator.Create())
+            {
+                var bytes = new byte[length];
+                rng.GetBytes(bytes);
+                
+                var result = new char[length];
+                for (int i = 0; i < length; i++)
+                {
+                    result[i] = base32Chars[bytes[i] % base32Chars.Length];
+                }
+                
+                return new string(result);
+            }
+        }
+
+        public void Dispose()
+        {
+            if (!_disposed)
+            {
+                // Cleanup any remaining temp file
+                CleanupOnFailure();
+                _disposed = true;
+            }
+        }
+    }
+}

sdk/src/Services/S3/Custom/Transfer/Internal/BufferedPartDataHandler.cs

@@ -44,6 +44,12 @@ public BufferedPartDataHandler(
             _config = config ?? throw new ArgumentNullException(nameof(config));
         }
 
+        public Task PrepareAsync(DownloadDiscoveryResult discoveryResult, CancellationToken cancellationToken)
+        {
+            // No preparation needed for buffered handler - buffers are created on demand
+            return Task.CompletedTask;
+        }
+        
         public async Task ProcessPartAsync(
             int partNumber,
             GetObjectResponse response, 

sdk/src/Services/S3/Custom/Transfer/Internal/FileDownloadConfiguration.cs

@@ -0,0 +1,67 @@
+/*******************************************************************************
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *  Licensed under the Apache License, Version 2.0 (the "License"). You may not use
+ *  this file except in compliance with the License. A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ *  or in the "license" file accompanying this file.
+ *  This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ *  CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ *  specific language governing permissions and limitations under the License.
+ * *****************************************************************************
+ *    __  _    _  ___
+ *   (  )( \/\/ )/ __)
+ *   /__\ \    / \__ \
+ *  (_)(_) \/\/  (___/
+ *
+ *  AWS SDK for .NET
+ *  API Version: 2006-03-01
+ *
+ */
+using System;
+
+namespace Amazon.S3.Transfer.Internal
+{
+    /// <summary>
+    /// Configuration settings for file-based multipart downloads.
+    /// Extends base coordinator settings with file-specific parameters.
+    /// </summary>
+    internal class FileDownloadConfiguration : DownloadCoordinatorConfiguration
+    {
+        /// <summary>
+        /// Buffer size for file I/O operations.
+        /// </summary>
+        public int BufferSize { get; set; }
+        
+        /// <summary>
+        /// Destination file path for the download.
+        /// </summary>
+        public string DestinationFilePath { get; set; }
+        
+        /// <summary>
+        /// Creates a FileDownloadConfiguration with the specified configuration values.
+        /// </summary>
+        /// <param name="concurrentServiceRequests">Maximum concurrent HTTP requests for downloading parts.</param>
+        /// <param name="bufferSize">Buffer size used for file I/O operations.</param>
+        /// <param name="targetPartSizeBytes">Target size for each part in bytes.</param>
+        /// <param name="destinationFilePath">Destination file path for the download.</param>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown when any numeric parameter is less than or equal to 0.</exception>
+        /// <exception cref="ArgumentException">Thrown when destinationFilePath is null or empty.</exception>
+        public FileDownloadConfiguration(
+            int concurrentServiceRequests,
+            int bufferSize,
+            long targetPartSizeBytes,
+            string destinationFilePath)
+            : base(concurrentServiceRequests, targetPartSizeBytes)
+        {
+            if (bufferSize <= 0)
+                throw new ArgumentOutOfRangeException(nameof(bufferSize), "Must be greater than 0");
+            if (string.IsNullOrWhiteSpace(destinationFilePath))
+                throw new ArgumentException("Destination file path cannot be null or empty", nameof(destinationFilePath));
+            
+            BufferSize = bufferSize;
+            DestinationFilePath = destinationFilePath;
+        }
+    }
+}