chore: kickoff release

Author: harsh62

AGENTS.md

@@ -98,7 +98,10 @@ swift test --filter AWSCognitoAuthPluginUnitTests    # Specific target
 - **Unit tests**: XCTest, defined in Package.swift (19 test targets)
 - **Integration tests**: Xcode host app projects under `AmplifyPlugins/<Category>/Tests/<Category>HostApp/`
 - **Conventions**: Mock via behavior protocols, use `AmplifyTestCommon` for shared utilities, `AmplifyAsyncTesting` for async helpers
-- **Test documentation**: Use Given/When/Then doc comments on all test methods:
+- **Test documentation (MANDATORY)**: Every new or modified test method
+  **must** have a Given/When/Then doc comment. No exceptions — this applies
+  to unit tests, integration tests, and regression tests alike. Reviewers
+  should reject PRs that add tests without this structure.
   ```swift
   /// Test description
   ///

Amplify/Categories/Storage/Operation/Request/StorageUploadDataRequest.swift

@@ -92,50 +92,59 @@ public extension StorageUploadDataRequest {
         /// - Tag: StorageUploadDataRequestOptions.pluginOptions
         public let pluginOptions: Any?
 
+        /// Override plugin default progress stall timeout for this upload only. `nil` uses the plugin default.
+        public let progressStallTimeout: ProgressStallTimeout?
+
         /// - Tag: StorageUploadDataRequestOptions.init
         @available(*, deprecated, message: "Use init(metadata:contentType:options)")
         public init(
             accessLevel: StorageAccessLevel = .guest,
             targetIdentityId: String? = nil,
             metadata: [String: String]? = nil,
             contentType: String? = nil,
-            pluginOptions: Any? = nil
+            pluginOptions: Any? = nil,
+            progressStallTimeout: ProgressStallTimeout? = nil
         ) {
             self.accessLevel = accessLevel
             self.targetIdentityId = targetIdentityId
             self.metadata = metadata
             self.bucket = nil
             self.contentType = contentType
             self.pluginOptions = pluginOptions
+            self.progressStallTimeout = progressStallTimeout
         }
 
         /// - Tag: StorageUploadDataRequestOptions.init
         public init(
             metadata: [String: String]? = nil,
             contentType: String? = nil,
-            pluginOptions: Any? = nil
+            pluginOptions: Any? = nil,
+            progressStallTimeout: ProgressStallTimeout? = nil
         ) {
             self.accessLevel = .guest
             self.targetIdentityId = nil
             self.metadata = metadata
             self.bucket = nil
             self.contentType = contentType
             self.pluginOptions = pluginOptions
+            self.progressStallTimeout = progressStallTimeout
         }
 
         /// - Tag: StorageUploadDataRequestOptions.init
         public init(
             metadata: [String: String]? = nil,
             bucket: some StorageBucket,
             contentType: String? = nil,
-            pluginOptions: Any? = nil
+            pluginOptions: Any? = nil,
+            progressStallTimeout: ProgressStallTimeout? = nil
         ) {
             self.accessLevel = .guest
             self.targetIdentityId = nil
             self.metadata = metadata
             self.bucket = bucket
             self.contentType = contentType
             self.pluginOptions = pluginOptions
+            self.progressStallTimeout = progressStallTimeout
         }
     }
 }

Amplify/Categories/Storage/Operation/Request/StorageUploadFileRequest.swift

@@ -89,50 +89,59 @@ public extension StorageUploadFileRequest {
         /// - Tag: StorageUploadFileRequestOptions.pluginOptions
         public let pluginOptions: Any?
 
+        /// Override the storage plugin's default progress stall timeout for this upload only. `nil` uses the plugin default.
+        public let progressStallTimeout: ProgressStallTimeout?
+
         /// - Tag: StorageUploadFileRequestOptions.init
         @available(*, deprecated, message: "Use init(metadata:contentType:pluginOptions)")
         public init(
             accessLevel: StorageAccessLevel = .guest,
             targetIdentityId: String? = nil,
             metadata: [String: String]? = nil,
             contentType: String? = nil,
-            pluginOptions: Any? = nil
+            pluginOptions: Any? = nil,
+            progressStallTimeout: ProgressStallTimeout? = nil
         ) {
             self.accessLevel = accessLevel
             self.targetIdentityId = targetIdentityId
             self.metadata = metadata
             self.bucket = nil
             self.contentType = contentType
             self.pluginOptions = pluginOptions
+            self.progressStallTimeout = progressStallTimeout
         }
 
         /// - Tag: StorageUploadFileRequestOptions.init
         public init(
             metadata: [String: String]? = nil,
             contentType: String? = nil,
-            pluginOptions: Any? = nil
+            pluginOptions: Any? = nil,
+            progressStallTimeout: ProgressStallTimeout? = nil
         ) {
             self.accessLevel = .guest
             self.targetIdentityId = nil
             self.metadata = metadata
             self.bucket = nil
             self.contentType = contentType
             self.pluginOptions = pluginOptions
+            self.progressStallTimeout = progressStallTimeout
         }
 
         /// - Tag: StorageUploadFileRequestOptions.init
         public init(
             metadata: [String: String]? = nil,
             bucket: some StorageBucket,
             contentType: String? = nil,
-            pluginOptions: Any? = nil
+            pluginOptions: Any? = nil,
+            progressStallTimeout: ProgressStallTimeout? = nil
         ) {
             self.accessLevel = .guest
             self.targetIdentityId = nil
             self.metadata = metadata
             self.bucket = bucket
             self.contentType = contentType
             self.pluginOptions = pluginOptions
+            self.progressStallTimeout = progressStallTimeout
         }
     }
 }

Amplify/Categories/Storage/ProgressStallTimeout.swift

@@ -0,0 +1,35 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+
+/// Strategy for cancelling uploads when progress stops advancing.
+///
+/// Aligns with the pattern used by other Amplify clients (for example flush intervals in the Kinesis client).
+/// Configure a default on the S3 storage plugin and optionally override per upload using
+/// ``StorageUploadFileRequest/Options`` or ``StorageUploadDataRequest/Options``.
+///
+/// - Tag: ProgressStallTimeout
+public enum ProgressStallTimeout: Sendable, Equatable {
+    /// Do not cancel uploads when progress stalls.
+    /// Named `disabled` (not `none`) so it does not collide with `Optional.none` when used as `ProgressStallTimeout?`.
+    case disabled
+    /// Cancel the upload if progress does not advance within this interval (seconds).
+    case interval(TimeInterval)
+}
+
+public extension ProgressStallTimeout {
+    /// Duration in seconds used by the stall timer, or `0` when disabled.
+    var secondsForStallTimer: TimeInterval {
+        switch self {
+        case .disabled:
+            return 0
+        case .interval(let seconds):
+            return max(0, seconds)
+        }
+    }
+}

AmplifyPlugins/API/Sources/AWSAPIPlugin/AppSyncRealTimeClient/AppSyncRealTimeClient.swift

@@ -251,8 +251,13 @@ actor AppSyncRealTimeClient: AppSyncRealTimeClientProtocol {
 
     private func resumeExistingSubscriptions() {
         log.debug("[AppSyncRealTimeClient] Resuming existing subscriptions")
-        for (id, _) in subscriptions {
+        for (id, subscription) in subscriptions {
             Task { [weak self] in
+                // Reset local state so subscribe() re-sends .start to the
+                // server. After a reconnect, the server has no memory of
+                // prior subscriptions, so stale local .subscribed state must
+                // not short-circuit the resubscription.
+                await subscription.prepareForResubscribe()
                 do {
                     if let cancellable = try await self?.startSubscription(id) {
                         await self?.storeInConnectionCancellables(cancellable)

AmplifyPlugins/API/Sources/AWSAPIPlugin/AppSyncRealTimeClient/AppSyncRealTimeSubscription.swift

@@ -84,6 +84,15 @@ actor AppSyncRealTimeSubscription {
         state.send(.subscribed)
     }
 
+    /// Reset local subscription state so `subscribe()` will actually resend
+    /// the `.start` request after a WebSocket reconnect. The server drops
+    /// subscription state when the connection dies, so local `.subscribed`
+    /// state is stale and must not short-circuit the resubscription path.
+    /// Fix for https://github.com/aws-amplify/amplify-swift/issues/3976
+    func prepareForResubscribe() {
+        state.send(.none)
+    }
+
     func unsubscribe() async throws {
         guard state.value == .subscribed else {
             log.debug("[AppSyncRealTimeSubscription-\(id)] Subscription should be subscribed to be unsubscribed")

AmplifyPlugins/API/Tests/APIHostApp/AWSAPIPluginFunctionalTests/AppSyncRealTimeClientTests.swift

@@ -169,6 +169,100 @@ class AppSyncRealTimeClientTests: XCTestCase {
         withExtendedLifetime(cancellables) { }
     }
 
+    /// End-to-end regression test for https://github.com/aws-amplify/amplify-swift/issues/3976
+    /// against a real AppSync backend. Simulates the scenePhase-triggered
+    /// NWPath recycle by driving two .online states through an injected
+    /// AmplifyNetworkMonitor and asserts that the subscription is actually
+    /// re-established (server issues a second start_ack).
+    ///
+    /// - Given:
+    ///    - An AppSyncRealTimeClient wired to a real AmplifyNetworkMonitor
+    ///      and a real AppSync endpoint from the bundled config.
+    ///    - A live subscription that has already received .subscribed from
+    ///      the server (first start_ack confirmed).
+    /// - When:
+    ///    - After the WebSocketClient's internal sink has attached (200ms),
+    ///      updateState(.online) is called twice on the network monitor,
+    ///      producing the (.online, .online) tuple from issue #3976.
+    /// - Then:
+    ///    - The WebSocket is recycled, AppSyncRealTimeClient reconnects,
+    ///      resumeExistingSubscriptions() re-sends `start`, and the server
+    ///      returns a second start_ack — causing a second .subscribed event.
+    func testSubscribe_afterOnlineToOnlinePathChange_shouldRecycleAndResubscribe() async throws {
+        var cancellables = Set<AnyCancellable>()
+
+        let data = try TestConfigHelper.retrieve(
+            forResource: GraphQLModelBasedTests.amplifyConfiguration
+        )
+        let amplifyConfig = try JSONDecoder().decode(JSONValue.self, from: data)
+        let (endpoint, apiKey) = (amplifyConfig.api?.plugins?.awsAPIPlugin?.asObject?.values
+            .map { ($0.endpoint?.stringValue, $0.apiKey?.stringValue) }
+            .first { $0.0 != nil && $0.1 != nil }
+            .map { ($0.0!, $0.1!) })!
+
+        // Inject a real AmplifyNetworkMonitor we can drive directly.
+        let networkMonitor = AmplifyNetworkMonitor()
+
+        let webSocketClient = WebSocketClient(
+            url: AppSyncRealTimeClientFactory.appSyncRealTimeEndpoint(URL(string: endpoint)!),
+            handshakeHttpHeaders: [
+                URLRequestConstants.Header.webSocketSubprotocols: "graphql-ws",
+                URLRequestConstants.Header.userAgent: AmplifyAWSServiceConfiguration.userAgentLib + " (intg-test-3976)"
+            ],
+            interceptor: APIKeyAuthInterceptor(apiKey: apiKey),
+            networkMonitor: networkMonitor
+        )
+        let client = AppSyncRealTimeClient(
+            endpoint: URL(string: endpoint)!,
+            requestInterceptor: APIKeyAuthInterceptor(apiKey: apiKey),
+            webSocketClient: webSocketClient
+        )
+        defer { Task { await client.reset() } }
+
+        // Wait for WebSocketClient's internal sink to attach to the monitor's
+        // publisher (it's kicked off via a Task in init). Prime with .online
+        // AFTER the subscriber is attached so the PassthroughSubject actually
+        // delivers the event. This gets the scan to (.none, .online) —
+        // WebSocketClient will ignore it because autoConnect is still false.
+        try await Task.sleep(nanoseconds: 200_000_000)
+        await networkMonitor.updateState(.online)
+
+        let firstSubscribed = expectation(description: "Initial subscription established")
+        let resubscribedAfterPathChange = expectation(description: "Subscription re-established after (.online, .online)")
+        resubscribedAfterPathChange.assertForOverFulfill = false
+
+        let id = UUID().uuidString
+        let subscribedCount = AtomicInt()
+        let subscription = try await client.subscribe(
+            id: id,
+            query: Self.appSyncQuery(with: subscriptionRequest)
+        ).sink { event in
+            if case .subscribed = event {
+                let count = subscribedCount.increment()
+                if count == 1 {
+                    firstSubscribed.fulfill()
+                } else {
+                    resubscribedAfterPathChange.fulfill()
+                }
+            }
+        }
+        cancellables.insert(subscription)
+
+        try await client.connect()
+        await fulfillment(of: [firstSubscribed], timeout: 10)
+
+        // Simulate the path-recycle: second .online emission produces
+        // (.online, .online) through the scan — the exact bug tuple.
+        // In the buggy code, nothing happens; WebSocketClient keeps the
+        // zombie connection. With the fix, it should tear down and reconnect,
+        // and AppSyncRealTimeClient.resumeExistingSubscriptions() should
+        // re-subscribe.
+        await networkMonitor.updateState(.online)
+
+        await fulfillment(of: [resubscribedAfterPathChange], timeout: 15)
+        withExtendedLifetime(cancellables) { }
+    }
+
     private func makeOneSubscription(
         id: String = UUID().uuidString,
         onSubscriptionEvents: ((AppSyncSubscriptionEvent) -> Void)?
@@ -201,3 +295,14 @@ class AppSyncRealTimeClientTests: XCTestCase {
     }
 
 }
+
+private final class AtomicInt: @unchecked Sendable {
+    private var value: Int = 0
+    private let lock = NSLock()
+    func increment() -> Int {
+        lock.lock()
+        defer { lock.unlock() }
+        value += 1
+        return value
+    }
+}

AmplifyPlugins/Auth/Sources/AWSCognitoAuthPlugin/Actions/RefreshAuthorizationSession/UserPool/RefreshUserPoolTokens.swift

@@ -33,7 +33,7 @@ struct RefreshUserPoolTokens: Action {
             let existingTokens = existingSignedIndata.cognitoUserPoolTokens
 
             let deviceMetadata = await DeviceMetadataHelper.getDeviceMetadata(
-                for: existingSignedIndata.username,
+                for: existingSignedIndata.inputUsername ?? existingSignedIndata.username,
                 with: environment
             )
 
@@ -82,7 +82,8 @@ struct RefreshUserPoolTokens: Action {
             let signedInData = SignedInData(
                 signedInDate: existingSignedIndata.signedInDate,
                 signInMethod: existingSignedIndata.signInMethod,
-                cognitoUserPoolTokens: userPoolTokens
+                cognitoUserPoolTokens: userPoolTokens,
+                inputUsername: existingSignedIndata.inputUsername
             )
             let event: RefreshSessionEvent
 

AmplifyPlugins/Core/AWSPluginsCore/WebSocket/WebSocketClient.swift

@@ -292,6 +292,23 @@ extension WebSocketClient {
         case (.offline, .online):
             log.debug("[WebSocketClient] NetworkMonitor - Device back online")
             await createConnectionAndRead()
+        case (.online, .online):
+            // NWPathMonitor's pathUpdateHandler only fires on real path
+            // changes, so a second .satisfied emission while we were already
+            // online means the underlying path was swapped (e.g., iOS recycled
+            // the TCP route during a scenePhase transition). The existing
+            // URLSessionWebSocketTask is now bound to a stale route and any
+            // further reads/writes will silently fail, leaving the client in
+            // a zombie state that cached consumers can't recover from.
+            // Fix for https://github.com/aws-amplify/amplify-swift/issues/3976
+            guard connection?.state == .running else {
+                log.debug("[WebSocketClient] NetworkMonitor - Path changed but connection is not running, skipping recycle")
+                break
+            }
+            log.debug("[WebSocketClient] NetworkMonitor - Network path changed while online, recycling connection")
+            connection?.cancel(with: .invalid, reason: nil)
+            subject.send(.disconnected(.invalid, nil))
+            await createConnectionAndRead()
         default:
             break
         }