feat(storage): add progress stall timeout for S3 uploads

[burak-initialcode]

Issue

#3302

Description

Adds a configurable progress stall timeout to S3 storage uploads. When upload progress does not advance for the configured interval (e.g. due to network issues), the upload is automatically cancelled and the operation's onError consumer receives an error instead of hanging indefinitely.

Problem: On poor or unstable networks, S3 uploads can stall indefinitely without the client receiving any progress updates.

Solution:

• New public ProgressStallTimeout sealed class in :core (Disabled / Interval(seconds)), mirroring the iOS API.
• New public ProgressStallTimeoutException (AmplifyException subclass) in :core so consumers can pattern-match on the cause of the surfaced StorageException.
• The plugin-wide default is set on AWSS3StoragePluginConfiguration.progressStallTimeout and can be overridden per upload via AWSS3StorageUploadFileOptions / AWSS3StorageUploadInputStreamOptions (null defers to the plugin default; Disabled explicitly opts out for that operation).
• The resolved interval is threaded through the upload pipeline into WorkData. SinglePartUploadWorker and PartUploadTransferWorker decorate their ProgressListeners with a coroutine-based StallDetectingProgressListener. On stall, the worker cancels the upload job, marks the transfer FAILED (workers explicitly skip retry for ProgressStallTimeoutException), and surfaces the typed cause via Throwable.toStorageUploadException(...).
• Default: Disabled (opt-in). Existing behavior is preserved.

Configuration:

// Plugin default: 30 seconds
Amplify.addPlugin(
    AWSS3StoragePlugin(
        AWSS3StoragePluginConfiguration {
            progressStallTimeout = ProgressStallTimeout.Interval(30)
        }
    )
)

// Override for a large upload: 120 seconds
val options = AWSS3StorageUploadFileOptions.builder()
    .progressStallTimeout(ProgressStallTimeout.Interval(120))
    .build()

Amplify.Storage.uploadFile(StoragePath.fromString("public/big.zip"), file, options)

How did you test these changes?

• New unit tests:
  • StallDetectingProgressListenerTest — coroutine-based timer logic (no progress, progress resets timer, close cancels, disabled threshold no-op, etc.) using kotlinx-coroutines-test (StandardTestDispatcher + advanceTimeBy).
  • StorageExceptionExtensionsTest — verifies toStorageUploadException preserves the typed ProgressStallTimeoutException cause (direct and nested) and falls back to the default message for unrelated throwables.
  • AWSS3StoragePluginConfigurationTest — defaults, builder, and override semantics for progressStallTimeout.
  • AWSS3StorageUploadFileOptionsTest / AWSS3StorageUploadInputStreamOptionsTest — option propagation, null-defers-to-plugin semantics, builder + Java interop.
• Updated existing operation/component unit tests for the new 6-arg StorageService.uploadFile / uploadInputStream overloads.
• New instrumentation tests in AWSS3StoragePathUploadTest (mirrors the iOS PR coverage retained after reviewer feedback):
  • testUploadSmallFileWithProgressStallTimeoutOptionCompletesSuccessfully — single-part happy path with the stall timer set.
  • testUploadLargeFileWithProgressStallTimeoutOptionCompletesSuccessfully — multipart happy path with the stall timer set.
• ./gradlew :core:test :aws-storage-s3:test — all passing locally.
• ./gradlew ktlintCheck checkstyle apiDump — all passing; API dump shows additive-only changes (minor bump).

Documentation update required?

• No
• Yes (Please include a PR link for the documentation update)

General Checklist

• Added Unit Tests
• Added Integration Tests
• Security oriented best practices and standards are followed (e.g. using input sanitization, principle of least privilege, etc)
• Ensure commit message has the appropriate scope (e.g fix(storage): message, feat(auth): message, chore(all): message)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[burak-initialcode]

@harsh62 any progress on this one?

[jvh-aws]

@burak-initialcode I am currently looking into the PR. Will let you know once I have an update.

[codecov]

Codecov Report

❌ Patch coverage is 41.26394% with 158 lines in your changes missing coverage. Please review.
✅ Project coverage is 56.03%. Comparing base (d6d9f52) to head (c2ae0e3).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3306      +/-   ##
==========================================
+ Coverage   55.91%   56.03%   +0.12%     
==========================================
  Files        1083     1087       +4     
  Lines       31932    32126     +194     
  Branches     4760     4803      +43     
==========================================
+ Hits        17854    18003     +149     
- Misses      12222    12241      +19     
- Partials     1856     1882      +26     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[burak-pensa]

@jvh-aws, any progress?

[jvh-aws]

Thanks for the contribution. I am still testing this on my end. Otherwise, there are two small comments I had

[burak-initialcode]

@jvh-aws Thanks for the review — both comments are addressed in 98a75d59.

1. Resume path + plugin default (Swift #4162 parity)

TransferOperations.resume() was calling start(..., progressStallTimeoutSeconds = 0L), so resumed uploads always lost stall detection even when the plugin had a default configured. That didn’t match the Swift behavior in aws-amplify/amplify-swift#4162, where resolvedProgressStallTimeoutSeconds falls back to the plugin configuration when there’s no per-upload override.

The plugin-level default from AWSS3StoragePluginConfiguration.progressStallTimeout is now threaded through AWSS3StoragePlugin → AWSS3StorageService.Factory / AWSS3StorageService → TransferManager → TransferOperations.resume(), so resumed work is enqueued with that default in WorkData (PROGRESS_STALL_TIMEOUT_SECONDS). Per-upload overrides on the initial start() path are unchanged; only resume uses the plugin default, since the per-upload value isn’t persisted across pause/resume.

Added TransferOperationsResumeTest to assert the stall timeout is propagated into the resumed worker’s work data (configured default vs. legacy 0 fallback).

2. MockK for AWSS3StoragePluginProgressStallTimeoutTest

Migrated AWSS3StoragePluginProgressStallTimeoutTest from Mockito to MockK (mockk, every, verify(timeout = …), slot) to match the project convention for new Kotlin tests.

Verification

Locally: :aws-storage-s3:testDebugUnitTest, targeted progress-stall tests, :core:testDebugUnitTest (ProgressStallTimeout*), and :aws-storage-s3:ktlintCheck — all green.