Address code review: add documentation for type assertion and no-retry streaming upload

Agent-Logs-Url: https://github.com/microsoft/rushstack/sessions/6212baeb-266c-4823-94df-251c69a8f74c

Co-authored-by: iclanton <5010588+iclanton@users.noreply.github.com>

Author: Copilot

common/reviews/api/rush-amazon-s3-build-cache-plugin.api.md

@@ -28,7 +28,6 @@ export class AmazonS3Client {
     static tryDeserializeCredentials(credentialString: string | undefined): IAmazonS3Credentials | undefined;
     // (undocumented)
     uploadObjectAsync(objectName: string, objectBuffer: Buffer): Promise<void>;
-    // (undocumented)
     uploadObjectStreamAsync(objectName: string, objectStream: Readable): Promise<void>;
     // (undocumented)
     static UriEncode(input: string): string;

rush-plugins/rush-amazon-s3-build-cache-plugin/src/AmazonS3Client.ts

@@ -234,6 +234,11 @@ export class AmazonS3Client {
     });
   }
 
+  /**
+   * Uploads a readable stream to S3. Unlike {@link AmazonS3Client.uploadObjectAsync}, this method
+   * does not use retry logic because the stream is consumed after the first attempt and cannot be
+   * replayed. The caller should handle failures accordingly.
+   */
   public async uploadObjectStreamAsync(objectName: string, objectStream: Readable): Promise<void> {
     if (!this._credentials) {
       throw new Error('Credentials are required to upload objects to S3.');

rush-plugins/rush-azure-storage-build-cache-plugin/src/AzureStorageBuildCacheProvider.ts

@@ -206,6 +206,9 @@ export class AzureStorageBuildCacheProvider
         const readableStreamBody: NodeJS.ReadableStream | undefined =
           downloadResponse.readableStreamBody;
         if (readableStreamBody) {
+          // The Azure SDK types readableStreamBody as NodeJS.ReadableStream, which is a minimal
+          // interface. In practice, the underlying implementation is a Node.js Readable stream
+          // (http.IncomingMessage), so this assertion is safe.
           return readableStreamBody as unknown as Readable;
         }
         return undefined;