Add idTokenChanges async stream to Auth

peterfriese · peterfriese · commit 69d2f3063366 · 2025-09-30T10:47:16.000+02:00
This commit introduces an `AsyncStream`-based API for observing ID token changes, aligning the Firebase Auth SDK with modern Swift concurrency patterns.

The new `idTokenChanges` computed property on `Auth` returns an `AsyncStream&lt;User?&gt;` that emits the current user whenever the ID token changes. This provides a more ergonomic alternative to the traditional closure-based `addIDTokenDidChangeListener`.

Key changes include:
- The implementation of `idTokenChanges` in `Auth+Async.swift`.
- Comprehensive unit tests in `IdTokenChangesAsyncTests.swift` covering the stream's behavior.
- Renamed `AuthAsyncTests.swift` to `AuthStateChangesAsyncTests.swift` to better reflect its content.
diff --git a/FirebaseAuth/Sources/Swift/Auth/Auth+Async.swift b/FirebaseAuth/Sources/Swift/Auth/Auth+Async.swift
@@ -1,4 +1,4 @@
-// Copyright 2024 Google LLC
+// Copyright 2025 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -58,5 +58,46 @@ import Foundation
         }
       }
     }
+
+    /// An asynchronous stream of ID token changes.
+    ///
+    /// This stream provides a modern, `async/await`-compatible way to monitor changes to the
+    /// current user's ID token. It emits a new `User?` value whenever the ID token changes.
+    ///
+    /// The stream's underlying listener is automatically managed. It is added to the `Auth`
+    /// instance when you begin iterating over the stream and is removed when the iteration
+    /// is cancelled or terminates.
+    ///
+    /// - Important: The first value emitted by this stream is always the *current* authentication
+    ///   state, which may be `nil` if no user is signed in.
+    ///
+    /// ### Example Usage
+    ///
+    /// You can use a `for await` loop to handle ID token changes:
+    ///
+    /// ```swift
+    /// func monitorIDTokenChanges() async {
+    ///   for await user in Auth.auth().idTokenChanges {
+    ///     if let user = user {
+    ///       print("ID token changed for user: \(user.uid)")
+    ///       // Update UI or perform actions for a signed-in user.
+    ///     } else {
+    ///       print("User signed out.")
+    ///       // Update UI or perform actions for a signed-out state.
+    ///     }
+    ///   }
+    /// }
+    /// ```
+    var idTokenChanges: AsyncStream<User?> {
+      return AsyncStream { continuation in
+        let listenerHandle = addIDTokenDidChangeListener { _, user in
+          continuation.yield(user)
+        }
+
+        continuation.onTermination = { @Sendable _ in
+          self.removeStateDidChangeListener(listenerHandle)
+        }
+      }
+    }
   }
 #endif // swift(>=5.5.2)
diff --git a/FirebaseAuth/Tests/Unit/AuthStateChangesAsyncTests.swift b/FirebaseAuth/Tests/Unit/AuthStateChangesAsyncTests.swift
@@ -1,4 +1,4 @@
-// Copyright 2024 Google LLC
+// Copyright 2025 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -17,7 +17,7 @@ import FirebaseCore
 import XCTest
 
 @available(iOS 13.0, macOS 10.15, macCatalyst 13.0, tvOS 13.0, watchOS 7.0, *)
-class AuthAsyncTests: RPCBaseTests {
+class AuthStateChangesAsyncTests: RPCBaseTests {
   var auth: Auth!
   static var testNum = 0
 
@@ -27,8 +27,8 @@ class AuthAsyncTests: RPCBaseTests {
                                   gcmSenderID: "00000000000000000-00000000000-000000000")
     options.apiKey = "FAKE_API_KEY"
     options.projectID = "myProjectID"
-    let name = "test-AuthAsyncTests\(AuthAsyncTests.testNum)"
-    AuthAsyncTests.testNum += 1
+    let name = "test-AuthStateChangesAsyncTests\(AuthStateChangesAsyncTests.testNum)"
+    AuthStateChangesAsyncTests.testNum += 1
 
     FirebaseApp.configure(name: name, options: options)
     let app = FirebaseApp.app(name: name)!
diff --git a/FirebaseAuth/Tests/Unit/IdTokenChangesAsyncTests.swift b/FirebaseAuth/Tests/Unit/IdTokenChangesAsyncTests.swift
@@ -0,0 +1,196 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License 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.
+
+@testable import FirebaseAuth
+import FirebaseCore
+import XCTest
+
+@available(iOS 13.0, macOS 10.15, macCatalyst 13.0, tvOS 13.0, watchOS 7.0, *)
+class IdTokenChangesAsyncTests: RPCBaseTests {
+  var auth: Auth!
+  static var testNum = 0
+
+  override func setUp() {
+    super.setUp()
+    let options = FirebaseOptions(googleAppID: "0:0000000000000:ios:0000000000000000",
+                                  gcmSenderID: "00000000000000000-00000000000-000000000")
+    options.apiKey = "FAKE_API_KEY"
+    options.projectID = "myProjectID"
+    let name = "test-IdTokenChangesAsyncTests\(IdTokenChangesAsyncTests.testNum)"
+    IdTokenChangesAsyncTests.testNum += 1
+
+    FirebaseApp.configure(name: name, options: options)
+    let app = FirebaseApp.app(name: name)!
+
+    #if (os(macOS) && !FIREBASE_AUTH_TESTING_USE_MACOS_KEYCHAIN) || SWIFT_PACKAGE
+      let keychainStorageProvider = FakeAuthKeychainStorage()
+    #else
+      let keychainStorageProvider = AuthKeychainStorageReal.shared
+    #endif
+
+    auth = Auth(
+      app: app,
+      keychainStorageProvider: keychainStorageProvider,
+      backend: authBackend
+    )
+
+    waitForAuthGlobalWorkQueueDrain()
+  }
+
+  override func tearDown() {
+    auth = nil
+    FirebaseApp.resetApps()
+    super.tearDown()
+  }
+
+  private func waitForAuthGlobalWorkQueueDrain() {
+    let workerSemaphore = DispatchSemaphore(value: 0)
+    kAuthGlobalWorkQueue.async {
+      workerSemaphore.signal()
+    }
+    _ = workerSemaphore.wait(timeout: DispatchTime.distantFuture)
+  }
+
+  func testIdTokenChangesStreamYieldsUserOnSignIn() async throws {
+    // Given
+    let initialNilExpectation = expectation(description: "Stream should emit initial nil user")
+    let signInExpectation = expectation(description: "Stream should emit signed-in user")
+    try? auth.signOut()
+
+    var iteration = 0
+    let task = Task {
+      for await user in auth.idTokenChanges {
+        if iteration == 0 {
+          XCTAssertNil(user, "The initial user should be nil")
+          initialNilExpectation.fulfill()
+        } else if iteration == 1 {
+          XCTAssertNotNil(user, "The stream should yield the new user")
+          XCTAssertEqual(user?.uid, kLocalID)
+          signInExpectation.fulfill()
+        }
+        iteration += 1
+      }
+    }
+
+    // Wait for the initial nil value to be emitted before proceeding.
+    await fulfillment(of: [initialNilExpectation], timeout: 1.0)
+
+    // When
+    // A user is signed in.
+    setFakeGetAccountProviderAnonymous()
+    setFakeSecureTokenService()
+    rpcIssuer.respondBlock = {
+      try self.rpcIssuer.respond(withJSON: ["idToken": "TEST_ACCESS_TOKEN",
+                                            "refreshToken": self.kRefreshToken,
+                                            "isNewUser": true])
+    }
+    _ = try await auth.signInAnonymously()
+
+    // Then
+    // The stream should emit the new, signed-in user.
+    await fulfillment(of: [signInExpectation], timeout: 2.0)
+    task.cancel()
+  }
+
+  func testIdTokenChangesStreamIsCancelled() async throws {
+    // Given: An inverted expectation that will fail the test if it's fulfilled.
+    let streamCancelledExpectation =
+      expectation(description: "Stream should not emit a value after cancellation")
+    streamCancelledExpectation.isInverted = true
+    try? auth.signOut()
+
+    var iteration = 0
+    let task = Task {
+      for await _ in auth.idTokenChanges {
+        if iteration > 0 {
+          // This line should not be reached. If it is, the inverted expectation will be
+          // fulfilled, and the test will fail as intended.
+          streamCancelledExpectation.fulfill()
+        }
+        iteration += 1
+      }
+    }
+
+    // Let the stream emit its initial `nil` value.
+    try await Task.sleep(nanoseconds: 200_000_000)
+
+    // When: The listening task is cancelled.
+    task.cancel()
+
+    // And an attempt is made to trigger another update.
+    setFakeGetAccountProviderAnonymous()
+    setFakeSecureTokenService()
+    rpcIssuer.respondBlock = {
+      try self.rpcIssuer.respond(withJSON: ["idToken": "TEST_ACCESS_TOKEN",
+                                            "refreshToken": self.kRefreshToken,
+                                            "isNewUser": true])
+    }
+    _ = try? await auth.signInAnonymously()
+
+    // Then: Wait for a period to ensure the inverted expectation is not fulfilled.
+    await fulfillment(of: [streamCancelledExpectation], timeout: 1.0)
+
+    // And explicitly check that the loop only ever ran once.
+    XCTAssertEqual(iteration, 1, "The stream should have only emitted its initial value.")
+  }
+
+  func testIdTokenChangesStreamYieldsNilOnSignOut() async throws {
+    // Given
+    let initialNilExpectation = expectation(description: "Stream should emit initial nil user")
+    let signInExpectation = expectation(description: "Stream should emit signed-in user")
+    let signOutExpectation = expectation(description: "Stream should emit nil after sign-out")
+    try? auth.signOut()
+
+    var iteration = 0
+    let task = Task {
+      for await user in auth.idTokenChanges {
+        switch iteration {
+        case 0:
+          XCTAssertNil(user, "The initial user should be nil")
+          initialNilExpectation.fulfill()
+        case 1:
+          XCTAssertNotNil(user, "The stream should yield the signed-in user")
+          signInExpectation.fulfill()
+        case 2:
+          XCTAssertNil(user, "The stream should yield nil after sign-out")
+          signOutExpectation.fulfill()
+        default:
+          XCTFail("The stream should not have emitted more than three values.")
+        }
+        iteration += 1
+      }
+    }
+
+    // Wait for the initial nil value.
+    await fulfillment(of: [initialNilExpectation], timeout: 1.0)
+
+    // Sign in a user.
+    setFakeGetAccountProviderAnonymous()
+    setFakeSecureTokenService()
+    rpcIssuer.respondBlock = {
+      try self.rpcIssuer.respond(withJSON: ["idToken": "TEST_ACCESS_TOKEN",
+                                            "refreshToken": self.kRefreshToken,
+                                            "isNewUser": true])
+    }
+    _ = try await auth.signInAnonymously()
+    await fulfillment(of: [signInExpectation], timeout: 2.0)
+
+    // When
+    try auth.signOut()
+
+    // Then
+    await fulfillment(of: [signOutExpectation], timeout: 2.0)
+    task.cancel()
+  }
+}
