Add Progress listeners for initiated, complete, and failed for simple upload

update docs and function namse

update comments

add tests/update comments

remove response from progressargs

add missing properties

update test

Refactor test

rearrange test

update tests

add commented out tests

comments

comments

update comments

fix spelling

use interlocked read and fix build

dev config

update comment

fix internals

Author: GarrettBeatty

generator/.DevConfigs/433a9a6d-b8ea-4676-b763-70711e8288e2.json

@@ -0,0 +1,12 @@
+{
+  "services": [
+    {
+      "serviceName": "S3",
+      "type": "patch",
+      "changeLogMessages": [
+        "Added progress tracking events to simple upload",
+        "Added PutObjectResponse to TransferUtilityUploadResponse mapping"
+      ]
+    }
+  ]
+}

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

@@ -41,6 +41,7 @@ internal partial class SimpleUploadCommand : BaseCommand
         IAmazonS3 _s3Client;
         TransferUtilityConfig _config;
         TransferUtilityUploadRequest _fileTransporterRequest;
+        long _totalTransferredBytes;
 
         internal SimpleUploadCommand(IAmazonS3 s3Client, TransferUtilityConfig config, TransferUtilityUploadRequest fileTransporterRequest)
         {
@@ -103,9 +104,48 @@ private PutObjectRequest ConstructRequest()
 
         private void PutObjectProgressEventCallback(object sender, UploadProgressArgs e)
         {
-            var progressArgs = new UploadProgressArgs(e.IncrementTransferred, e.TransferredBytes, e.TotalBytes, 
-                e.CompensationForRetry, _fileTransporterRequest.FilePath);
+            // Keep track of the total transferred bytes so that we can also return this value in case of failure
+            long transferredBytes = Interlocked.Add(ref _totalTransferredBytes, e.IncrementTransferred - e.CompensationForRetry);
+            
+            var progressArgs = new UploadProgressArgs(e.IncrementTransferred, transferredBytes, e.TotalBytes, 
+                e.CompensationForRetry, _fileTransporterRequest.FilePath, _fileTransporterRequest);
             this._fileTransporterRequest.OnRaiseProgressEvent(progressArgs);
         }
+
+        private void FireTransferInitiatedEvent()
+        {
+            var initiatedArgs = new UploadInitiatedEventArgs(
+                request: _fileTransporterRequest,
+                filePath: _fileTransporterRequest.FilePath,
+                totalBytes: _fileTransporterRequest.ContentLength
+            );
+            
+            _fileTransporterRequest.OnRaiseTransferInitiatedEvent(initiatedArgs);
+        }
+
+        private void FireTransferCompletedEvent(TransferUtilityUploadResponse response)
+        {
+            var completedArgs = new UploadCompletedEventArgs(
+                request: _fileTransporterRequest,
+                response: response,
+                filePath: _fileTransporterRequest.FilePath,
+                transferredBytes: Interlocked.Read(ref _totalTransferredBytes),
+                totalBytes: _fileTransporterRequest.ContentLength
+            );
+            
+            _fileTransporterRequest.OnRaiseTransferCompletedEvent(completedArgs);
+        }
+
+        private void FireTransferFailedEvent()
+        {
+            var failedArgs = new UploadFailedEventArgs(
+                request: _fileTransporterRequest,
+                filePath: _fileTransporterRequest.FilePath,
+                transferredBytes: Interlocked.Read(ref _totalTransferredBytes),
+                totalBytes: _fileTransporterRequest.ContentLength
+            );
+            
+            _fileTransporterRequest.OnRaiseTransferFailedEvent(failedArgs);
+        }
     }
 }

sdk/src/Services/S3/Custom/Transfer/Internal/_async/SimpleUploadCommand.async.cs

@@ -38,9 +38,20 @@ await this.AsyncThrottler.WaitAsync(cancellationToken)
                         .ConfigureAwait(continueOnCapturedContext: false);
                 }
 
+                FireTransferInitiatedEvent();
+
                 var putRequest = ConstructRequest();
-                await _s3Client.PutObjectAsync(putRequest, cancellationToken)
+                var response = await _s3Client.PutObjectAsync(putRequest, cancellationToken)
                     .ConfigureAwait(continueOnCapturedContext: false);
+
+                var mappedResponse = ResponseMapper.MapPutObjectResponse(response);
+
+                FireTransferCompletedEvent(mappedResponse);
+            }
+            catch (Exception)
+            {
+                FireTransferFailedEvent();
+                throw;
             }
             finally
             {

sdk/src/Services/S3/Custom/Transfer/TransferUtilityUploadRequest.cs

@@ -25,6 +25,7 @@
 using System.IO;
 using System.Text;
 
+using Amazon.Runtime;
 using Amazon.Runtime.Internal;
 using Amazon.S3.Model;
 using Amazon.Util;
@@ -411,6 +412,132 @@ public List<Tag> TagSet
         /// </remarks>
         public event EventHandler<UploadProgressArgs> UploadProgressEvent;
 
+        /// <summary>
+        /// The event for UploadInitiatedEvent notifications. All
+        /// subscribers will be notified when a transfer operation
+        /// starts.
+        /// <para>
+        /// The UploadInitiatedEvent is fired exactly once when 
+        /// a transfer operation begins. The delegates attached to the event 
+        /// will be passed information about the upload request and 
+        /// total file size, but no progress information.
+        /// </para>
+        /// </summary>
+        /// <remarks>
+        /// Subscribe to this event if you want to receive
+        /// UploadInitiatedEvent notifications. Here is how:<br />
+        /// 1. Define a method with a signature similar to this one:
+        /// <code>
+        /// private void uploadStarted(object sender, UploadInitiatedEventArgs args)
+        /// {
+        ///     Console.WriteLine($"Upload started: {args.FilePath}");
+        ///     Console.WriteLine($"Total size: {args.TotalBytes} bytes");
+        ///     Console.WriteLine($"Bucket: {args.Request.BucketName}");
+        ///     Console.WriteLine($"Key: {args.Request.Key}");
+        /// }
+        /// </code>
+        /// 2. Add this method to the UploadInitiatedEvent delegate's invocation list
+        /// <code>
+        /// TransferUtilityUploadRequest request = new TransferUtilityUploadRequest();
+        /// request.UploadInitiatedEvent += uploadStarted;
+        /// </code>
+        /// </remarks>
+        public event EventHandler<UploadInitiatedEventArgs> UploadInitiatedEvent;
+
+        /// <summary>
+        /// The event for UploadCompletedEvent notifications. All
+        /// subscribers will be notified when a transfer operation
+        /// completes successfully.
+        /// <para>
+        /// The UploadCompletedEvent is fired exactly once when 
+        /// a transfer operation completes successfully. The delegates attached to the event 
+        /// will be passed information about the completed upload including
+        /// the final response from S3 with ETag, VersionId, and other metadata.
+        /// </para>
+        /// </summary>
+        /// <remarks>
+        /// Subscribe to this event if you want to receive
+        /// UploadCompletedEvent notifications. Here is how:<br />
+        /// 1. Define a method with a signature similar to this one:
+        /// <code>
+        /// private void uploadCompleted(object sender, UploadCompletedEventArgs args)
+        /// {
+        ///     Console.WriteLine($"Upload completed: {args.FilePath}");
+        ///     Console.WriteLine($"Transferred: {args.TransferredBytes} bytes");
+        ///     Console.WriteLine($"ETag: {args.Response.ETag}");
+        ///     Console.WriteLine($"S3 Key: {args.Response.Key}");
+        ///     Console.WriteLine($"Version ID: {args.Response.VersionId}");
+        /// }
+        /// </code>
+        /// 2. Add this method to the UploadCompletedEvent delegate's invocation list
+        /// <code>
+        /// TransferUtilityUploadRequest request = new TransferUtilityUploadRequest();
+        /// request.UploadCompletedEvent += uploadCompleted;
+        /// </code>
+        /// </remarks>
+        public event EventHandler<UploadCompletedEventArgs> UploadCompletedEvent;
+
+        /// <summary>
+        /// The event for UploadFailedEvent notifications. All
+        /// subscribers will be notified when a transfer operation
+        /// fails.
+        /// <para>
+        /// The UploadFailedEvent is fired exactly once when 
+        /// a transfer operation fails. The delegates attached to the event 
+        /// will be passed information about the failed upload including
+        /// partial progress information, but no response data since the upload failed.
+        /// </para>
+        /// </summary>
+        /// <remarks>
+        /// Subscribe to this event if you want to receive
+        /// UploadFailedEvent notifications. Here is how:<br />
+        /// 1. Define a method with a signature similar to this one:
+        /// <code>
+        /// private void uploadFailed(object sender, UploadFailedEventArgs args)
+        /// {
+        ///     Console.WriteLine($"Upload failed: {args.FilePath}");
+        ///     Console.WriteLine($"Partial progress: {args.TransferredBytes} / {args.TotalBytes} bytes");
+        ///     var percent = (double)args.TransferredBytes / args.TotalBytes * 100;
+        ///     Console.WriteLine($"Completion: {percent:F1}%");
+        ///     Console.WriteLine($"Bucket: {args.Request.BucketName}");
+        ///     Console.WriteLine($"Key: {args.Request.Key}");
+        /// }
+        /// </code>
+        /// 2. Add this method to the UploadFailedEvent delegate's invocation list
+        /// <code>
+        /// TransferUtilityUploadRequest request = new TransferUtilityUploadRequest();
+        /// request.UploadFailedEvent += uploadFailed;
+        /// </code>
+        /// </remarks>
+        public event EventHandler<UploadFailedEventArgs> UploadFailedEvent;
+
+        /// <summary>
+        /// Causes the UploadInitiatedEvent event to be fired.
+        /// </summary>
+        /// <param name="args">UploadInitiatedEventArgs args</param>
+        internal void OnRaiseTransferInitiatedEvent(UploadInitiatedEventArgs args)
+        {
+            AWSSDKUtils.InvokeInBackground(UploadInitiatedEvent, args, this);
+        }
+
+        /// <summary>
+        /// Causes the UploadCompletedEvent event to be fired.
+        /// </summary>
+        /// <param name="args">UploadCompletedEventArgs args</param>
+        internal void OnRaiseTransferCompletedEvent(UploadCompletedEventArgs args)
+        {
+            AWSSDKUtils.InvokeInBackground(UploadCompletedEvent, args, this);
+        }
+
+        /// <summary>
+        /// Causes the UploadFailedEvent event to be fired.
+        /// </summary>
+        /// <param name="args">UploadFailedEventArgs args</param>
+        internal void OnRaiseTransferFailedEvent(UploadFailedEventArgs args)
+        {
+            AWSSDKUtils.InvokeInBackground(UploadFailedEvent, args, this);
+        }
+
 
         /// <summary>
         /// Causes the UploadProgressEvent event to be fired.
@@ -835,11 +962,164 @@ internal UploadProgressArgs(long incrementTransferred, long transferred, long to
             this.CompensationForRetry = compensationForRetry;
         }
 
+        /// <summary>
+        /// Constructor for upload progress with request
+        /// </summary>
+        /// <param name="incrementTransferred">The how many bytes were transferred since last event.</param>
+        /// <param name="transferred">The number of bytes transferred</param>
+        /// <param name="total">The total number of bytes to be transferred</param>
+        /// <param name="compensationForRetry">A compensation for any upstream aggregators if this event to correct their totalTransferred count,
+        /// in case the underlying request is retried.</param>
+        /// <param name="filePath">The file being uploaded</param>
+        /// <param name="request">The original TransferUtilityUploadRequest created by the user</param>
+        internal UploadProgressArgs(long incrementTransferred, long transferred, long total, long compensationForRetry, string filePath, TransferUtilityUploadRequest request)
+            : base(incrementTransferred, transferred, total)
+        {
+            this.FilePath = filePath;
+            this.CompensationForRetry = compensationForRetry;
+            this.Request = request;
+        }
+
         /// <summary>
         /// Gets the FilePath.
         /// </summary>
         public string FilePath { get; private set; }
 
         internal long CompensationForRetry { get; set; }
+
+        /// <summary>
+        /// The original TransferUtilityUploadRequest created by the user.
+        /// </summary>
+        public TransferUtilityUploadRequest Request { get; internal set; }
+    }
+
+    /// <summary>
+    /// Encapsulates the information needed when a transfer operation is initiated.
+    /// Provides access to the original request and total file size without any progress information.
+    /// </summary>
+    public class UploadInitiatedEventArgs : EventArgs
+    {
+        /// <summary>
+        /// Initializes a new instance of the UploadInitiatedEventArgs class.
+        /// </summary>
+        /// <param name="request">The original TransferUtilityUploadRequest created by the user</param>
+        /// <param name="filePath">The file being uploaded</param>
+        /// <param name="totalBytes">The total number of bytes to be transferred</param>
+        internal UploadInitiatedEventArgs(TransferUtilityUploadRequest request, string filePath, long totalBytes)
+        {
+            Request = request;
+            FilePath = filePath;
+            TotalBytes = totalBytes;
+        }
+
+        /// <summary>
+        /// The original TransferUtilityUploadRequest created by the user.
+        /// Contains all the upload parameters and configuration.
+        /// </summary>
+        public TransferUtilityUploadRequest Request { get; private set; }
+
+        /// <summary>
+        /// Gets the file path being uploaded.
+        /// </summary>
+        public string FilePath { get; private set; }
+
+        /// <summary>
+        /// Gets the total number of bytes to be transferred.
+        /// </summary>
+        public long TotalBytes { get; private set; }
+    }
+
+    /// <summary>
+    /// Encapsulates the information needed when a transfer operation completes successfully.
+    /// Provides access to the original request, final response, and completion details.
+    /// </summary>
+    public class UploadCompletedEventArgs : EventArgs
+    {
+        /// <summary>
+        /// Initializes a new instance of the UploadCompletedEventArgs class.
+        /// </summary>
+        /// <param name="request">The original TransferUtilityUploadRequest created by the user</param>
+        /// <param name="response">The unified response from Transfer Utility</param>
+        /// <param name="filePath">The file that was uploaded</param>
+        /// <param name="transferredBytes">The total number of bytes transferred</param>
+        /// <param name="totalBytes">The total number of bytes that were transferred</param>
+        internal UploadCompletedEventArgs(TransferUtilityUploadRequest request, TransferUtilityUploadResponse response, string filePath, long transferredBytes, long totalBytes)
+        {
+            Request = request;
+            Response = response; 
+            FilePath = filePath;
+            TransferredBytes = transferredBytes;
+            TotalBytes = totalBytes;
+        }
+
+        /// <summary>
+        /// The original TransferUtilityUploadRequest created by the user.
+        /// Contains all the upload parameters and configuration.
+        /// </summary>
+        public TransferUtilityUploadRequest Request { get; private set; }
+
+        /// <summary>
+        /// The unified response from Transfer Utility after successful upload completion.
+        /// Contains mapped fields from either PutObjectResponse (simple uploads) or CompleteMultipartUploadResponse (multipart uploads).
+        /// </summary>
+        public TransferUtilityUploadResponse Response { get; private set; }
+
+        /// <summary>
+        /// Gets the file path that was uploaded.
+        /// </summary>
+        public string FilePath { get; private set; }
+
+        /// <summary>
+        /// Gets the total number of bytes that were successfully transferred.
+        /// </summary>
+        public long TransferredBytes { get; private set; }
+
+        /// <summary>
+        /// Gets the total number of bytes that were transferred (should equal TransferredBytes for successful uploads).
+        /// </summary>
+        public long TotalBytes { get; private set; }
+    }
+
+    /// <summary>
+    /// Encapsulates the information needed when a transfer operation fails.
+    /// Provides access to the original request and partial progress information.
+    /// </summary>
+    public class UploadFailedEventArgs : EventArgs
+    {
+        /// <summary>
+        /// Initializes a new instance of the UploadFailedEventArgs class.
+        /// </summary>
+        /// <param name="request">The original TransferUtilityUploadRequest created by the user</param>
+        /// <param name="filePath">The file that was being uploaded</param>
+        /// <param name="transferredBytes">The number of bytes transferred before failure</param>
+        /// <param name="totalBytes">The total number of bytes that should have been transferred</param>
+        internal UploadFailedEventArgs(TransferUtilityUploadRequest request, string filePath, long transferredBytes, long totalBytes)
+        {
+            Request = request;
+            FilePath = filePath;
+            TransferredBytes = transferredBytes;
+            TotalBytes = totalBytes;
+        }
+
+        /// <summary>
+        /// The original TransferUtilityUploadRequest created by the user.
+        /// Contains all the upload parameters and configuration.
+        /// </summary>
+        public TransferUtilityUploadRequest Request { get; private set; }
+
+        /// <summary>
+        /// Gets the file path that was being uploaded.
+        /// </summary>
+        public string FilePath { get; private set; }
+
+        /// <summary>
+        /// Gets the number of bytes that were transferred before the failure occurred.
+        /// </summary>
+        public long TransferredBytes { get; private set; }
+
+        /// <summary>
+        /// Gets the total number of bytes that should have been transferred.
+        /// </summary>
+        public long TotalBytes { get; private set; }
     }
 }