Merge branch 'main' into update-cpp-style-guide

Author: jonsimantov

Jules.md renamed to AGENTS.md

@@ -1,5 +1,9 @@
 # Introduction
 
+> **Note on Document Formatting:** This document (`AGENTS.md`) should be
+> maintained with lines word-wrapped to a maximum of 80 characters to ensure
+> readability across various editors and terminals.
+
 This document provides context and guidance for AI agents (like Jules) when
 making changes to the Firebase C++ SDK repository. It covers essential
 information about the repository's structure, setup, testing procedures, API
@@ -29,11 +33,11 @@ instructions for your specific platform.
 *   **CMake**: Version 3.7 or newer.
 *   **Python**: Version 3.7 or newer.
 *   **Abseil-py**: Python package.
-*   **OpenSSL**: Required for Realtime Database and Cloud Firestore
-    (especially for desktop builds).
-*   **Android SDK & NDK**: Required for building Android libraries.
-    `sdkmanager` can be used for installation. CMake for Android (version
-    3.10.2 recommended) is also needed.
+*   **OpenSSL**: Required for Realtime Database and Cloud Firestore (especially
+    for desktop builds).
+*   **Android SDK & NDK**: Required for building Android libraries. `sdkmanager`
+    can be used for installation. CMake for Android (version 3.10.2
+    recommended) is also needed.
 *   **(Windows Only) Strings**: From Microsoft Sysinternals, required for
     Android builds on Windows.
 *   **Cocoapods**: Required for building iOS or tvOS libraries.
@@ -79,8 +83,7 @@ When setting up for desktop, if you are using an iOS
 `GoogleService-Info.plist` file, convert it to the required
 `google-services-desktop.json` using the script:
 `python generate_xml_from_google_services_json.py --plist -i GoogleService-Info.plist`
-(run this from the script's directory, ensuring the plist file is
-accessible).
+(run this from the script's directory, ensuring the plist file is accessible).
 
 The desktop SDK searches for configuration files in the current working
 directory, first for `google-services-desktop.json`, then for
@@ -177,10 +180,10 @@ Database).
     *   `firebase::AppOptions` can be used to configure the app with
         specific parameters if not relying on a `google-services.json` or
         `GoogleService-Info.plist` file.
-2.  **Service Instances**: Once `firebase::App` is initialized, you
-    generally obtain instances of specific Firebase services using a static
-    `GetInstance()` method on the service's class, passing the
-    `firebase::App` object.
+2.  **Service Instances**: Once `firebase::App` is initialized, you generally
+    obtain instances of specific Firebase services using a static
+    `GetInstance()` method on the service's class, passing the `firebase::App`
+    object.
     *   Examples for services like Auth, Database, Storage, Firestore:
         *   `firebase::auth::Auth* auth = firebase::auth::Auth::GetAuth(app, &init_result);`
         *   `firebase::database::Database* database = firebase::database::Database::GetInstance(app, &init_result);`
@@ -192,11 +195,11 @@ Database).
         a different pattern. Analytics is typically initialized with
         `firebase::analytics::Initialize(const firebase::App& app)` (often
         handled automatically for the default `App` instance). After this,
-        Analytics functions (e.g., `firebase::analytics::LogEvent(...)`)
-        are called as global functions within the `firebase::analytics`
-        namespace, rather than on an instance object obtained via
-        `GetInstance()`. Refer to the specific product's header file for
-        its exact initialization mechanism if it deviates from the common
+        Analytics functions (e.g., `firebase::analytics::LogEvent(...)`) are
+        called as global functions within the `firebase::analytics` namespace,
+        rather than on an instance object obtained via `GetInstance()`.
+        Refer to the specific product's header file for its exact
+        initialization mechanism if it deviates from the common
         `GetInstance(app, ...)` pattern.
 
 ### Asynchronous Operations: `firebase::Future<T>`
@@ -311,9 +314,15 @@ detailed API documentation.
     [STYLE_GUIDE.md](STYLE_GUIDE.md).
 *   **Google C++ Style Guide**: Adhere to the
     [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)
-    as mentioned in `CONTRIBUTING.md` for general C++ style.
-*   **Formatting**: Use `python3 scripts/format_code.py -git_diff -verbose`
-    to format your code before committing.
+    as mentioned in `CONTRIBUTING.md`.
+*   **Formatting**: Use `python3 scripts/format_code.py -git_diff -verbose` to
+    format your code before committing.
+*   **Naming Precision for Dynamic Systems**: Function names should precisely
+    reflect their behavior, especially in systems with dynamic or asynchronous
+    interactions. For example, a function that processes a list of items should
+    be named differently from one that operates on a single, specific item
+    captured asynchronously. Regularly re-evaluate function names as
+    requirements evolve to maintain clarity.
 
 ## Comments
 
@@ -360,20 +369,26 @@ detailed API documentation.
 *   **Pointers**: Standard C++ smart pointers (`std::unique_ptr`,
     `std::shared_ptr`) should be used where appropriate for managing
     dynamically allocated memory.
-*   **`Future` Lifecycle**: Ensure `Future` objects returned from API
-    calls are properly managed. While `Future`s handle their own internal
-    memory for the result, the asynchronous operations they represent
-    need to complete to reliably free all associated operational
-    resources or to ensure actions (like writes to a database) are
-    definitely finalized. Abandoning a `Future` (letting it go out of
-    scope without checking its result, attaching an `OnCompletion`
-    callback, or explicitly `Wait()`ing for it) can sometimes lead to
-    operations not completing as expected or resources not being cleaned
-    up promptly by the underlying services, especially if the `Future` is
-    the only handle to that operation. Prefer using `OnCompletion` or
-    otherwise ensuring the `Future` completes its course, particularly
-    for operations with side effects or those that allocate significant
-    backend resources.
+*   **`Future` Lifecycle**: Ensure `Future` objects returned from API calls are
+    properly managed. While `Future`s handle their own internal memory for the
+    result, the asynchronous operations they represent need to complete to
+    reliably free all associated operational resources or to ensure actions
+    (like writes to a database) are definitely finalized. Abandoning a `Future`
+    (letting it go out of scope without checking its result, attaching an
+    `OnCompletion` callback, or explicitly `Wait()`ing for it) can sometimes
+    lead to operations not completing as expected or resources not being
+    cleaned up promptly by the underlying services, especially if the `Future`
+    is the only handle to that operation. Prefer using `OnCompletion` or
+    otherwise ensuring the `Future` completes its course, particularly for
+    operations with side effects or those that allocate significant backend
+    resources.
+*   **Lifecycle of Queued Callbacks/Blocks**: If blocks or callbacks are queued
+    to be run upon an asynchronous event (e.g., an App Delegate class being set
+    or a Future completing), clearly define and document their lifecycle.
+    Determine if they are one-shot (cleared after first execution) or
+    persistent (intended to run for multiple or future events). This impacts
+    how associated data and the blocks themselves are stored and cleared,
+    preventing memory leaks or unexpected multiple executions.
 
 ## Immutability
 
@@ -406,10 +421,33 @@ detailed API documentation.
     indexes, queries may fail or not return expected results.
 *   **iOS Method Swizzling**: Be aware that some Firebase products on iOS
     (e.g., Dynamic Links, Cloud Messaging) use method swizzling to
-    automatically attach handlers to your `AppDelegate`. While this
-    simplifies integration, it can occasionally be a factor to consider
-    when debugging app delegate behavior or integrating with other
-    libraries that also perform swizzling.
+    automatically attach handlers to your `AppDelegate`. While this simplifies
+    integration, it can occasionally be a factor to consider when debugging app
+    delegate behavior or integrating with other libraries that also perform
+    swizzling.
+    When implementing or interacting with swizzling, especially for App Delegate
+    methods like `[UIApplication setDelegate:]`:
+        *   Be highly aware that `setDelegate:` can be called multiple times
+            with different delegate class instances, including proxy classes
+            from other libraries (e.g., GUL - Google Utilities). Swizzling
+            logic must be robust against being invoked multiple times for the
+            same effective method on the same class or on classes in a
+            hierarchy. An idempotency check (i.e., if the method's current IMP
+            is already the target swizzled IMP, do nothing more for that
+            specific swizzle attempt) in any swizzling utility can prevent
+            issues like recursion.
+        *   When tracking unique App Delegate classes (e.g., for applying hooks
+            or callbacks via swizzling), consider the class hierarchy. If a
+            superclass has already been processed, processing a subclass for
+            the same inherited methods might be redundant or problematic. A
+            strategy to check if a newly set delegate is a subclass of an
+            already processed delegate can prevent such issues.
+        *   For code that runs very early in the application lifecycle on
+            iOS/macOS (e.g., `+load` methods, static initializers involved in
+            swizzling), prefer using `NSLog` directly over custom logging
+            frameworks if there's any uncertainty about whether the custom
+            framework is fully initialized, to avoid crashes during logging
+            itself.
 
 ## Class and File Structure
 
@@ -548,11 +586,11 @@ prevent memory leaks, dangling pointers, or double deletions.
 
 # Updating This Document
 
-This document is a living guide. As the Firebase C++ SDK evolves, new
-patterns may emerge, or existing practices might change. If you introduce
-a new common pattern, significantly alter a build process, or establish a
-new best practice during your work, please take a moment to update this
-`Jules.md` file accordingly.
+This document is a living guide. As the Firebase C++ SDK evolves, new patterns
+may emerge, or existing practices might change. If you introduce a new common
+pattern, significantly alter a build process, or establish a new best practice
+during your work, please take a moment to update this `AGENTS.md` file
+accordingly.
 
 Keeping this document current will greatly benefit future AI agents and
 human developers working on this repository.
@@ -561,41 +599,43 @@ human developers working on this repository.
 
 ## Recommended General Prompt Instruction
 
-When working on this task, please consistently refer to the `Jules.md`
-guide for all repository-specific conventions, including setup
-procedures, coding style, common architectural patterns, and API usage.
-Pay close attention to the testing strategies outlined, ensuring your
-implementation includes comprehensive integration tests with detailed test
-cases in your plan. Implement robust error handling for any new or
-modified public API methods, following the patterns for `firebase::Future`
-error reporting. If the feature involves platform-specific code, ensure
-the public API remains consistent across all platforms, as discussed in
-`Jules.md`. Write clear, maintainable code, adhering to the commenting
-guidelines, and if you need to add new third-party dependencies, document
-the rationale and update build configurations according to the established
-practices. Ensure your changes align with the overall best practices
-detailed in `Jules.md`.
+When working on this task, please consistently refer to the `AGENTS.md` guide
+for all repository-specific conventions, including setup procedures, coding
+style, common architectural patterns, and API usage. Pay close attention to the
+testing strategies outlined, ensuring your implementation includes
+comprehensive integration tests with detailed test cases in your plan. Implement
+robust error handling for any new or modified public API methods, following the
+patterns for `firebase::Future` error reporting. If the feature involves
+platform-specific code, ensure the public API remains consistent across all
+platforms, as discussed in `AGENTS.md`. Write clear, maintainable code,
+adhering to the commenting guidelines, and if you need to add new third-party
+dependencies, document the rationale and update build configurations according
+to the established practices. Ensure your changes align with the overall best
+practices detailed in `AGENTS.md`.
 
 ## Key Directives for Jules AI
 
-*   **Prioritize `Jules.md`**: This document (`Jules.md`) contains
-    repository-specific guidelines. Prioritize this information when
-    making decisions about coding style, testing procedures,
-    architectural patterns, and API usage.
-*   **Adherence to Patterns**: Strive to follow the common patterns and
-    best practices outlined here. This ensures consistency across the
-    codebase.
-*   **Clarification for Deviations**: If the existing patterns in
-    `Jules.md` do not seem suitable for a specific task, or if a
-    deviation is necessary, please explicitly state this in your plan or
-    request clarification before proceeding with implementation.
-*   **Updating `Jules.md`**: If you introduce a new, broadly applicable
-    pattern, or if a significant change to the build process or best
-    practices occurs as part of your task, please include a step in your
-    plan to update `Jules.md` to reflect these changes.
+*   **Prioritize `AGENTS.md`**: This document (`AGENTS.md`) contains
+    repository-specific guidelines. Prioritize this information when making
+    decisions about coding style, testing procedures, architectural patterns,
+    and API usage.
+*   **Adherence to Patterns**: Strive to follow the common patterns and best
+    practices outlined here. This ensures consistency across the codebase.
+*   **Clarification for Deviations**: If the existing patterns in `AGENTS.md` do
+    not seem suitable for a specific task, or if a deviation is necessary,
+    please explicitly state this in your plan or request clarification before
+    proceeding with implementation.
+*   **Updating `AGENTS.md`**: If you introduce a new, broadly applicable
+    pattern, or if a significant change to the build process or best practices
+    occurs as part of your task, please include a step in your plan to update
+    `AGENTS.md` to reflect these changes.
 *   **Testing**: Remember that integration tests are the primary method of
-    testing. Ensure new features are accompanied by corresponding
-    integration tests as described in the 'Testing' section of
-    `Jules.md`.
+    testing. Ensure new features are accompanied by corresponding integration
+    tests as described in the 'Testing' section of `AGENTS.md`.
 *   **Commit Messages**: Follow standard commit message guidelines. A brief
     summary line, followed by a more detailed explanation if necessary.
+*   **Tool Limitations & Path Specificity**: If codebase search tools (like
+    `grep` or recursive `ls`) are limited or unavailable, and initial attempts
+    to locate files/modules based on common directory structures are
+    unsuccessful, explicitly ask for more specific paths rather than assuming a
+    module doesn't exist or contains no relevant code.

app/src/invites/ios/invites_ios_startup.mm

@@ -286,7 +286,7 @@ @implementation UIApplication (FIRFBI)
 + (void)load {
   // C++ constructors may not be called yet so call NSLog rather than LogDebug.
   NSLog(@"Loading UIApplication category for Firebase App");
-  ::firebase::util::ForEachAppDelegateClass(^(Class clazz) {
+  ::firebase::util::RunOnAppDelegateClasses(^(Class clazz) {
     ::firebase::invites::HookAppDelegateMethods(clazz);
   });
 }

app/src/util_ios.h

@@ -185,10 +185,12 @@ typedef BOOL (
     id self, SEL selector_value, UIApplication *application,
     NSUserActivity *user_activity, void (^restoration_handler)(NSArray *));
 
-// Call the given block once for every Objective-C class that exists that
-// implements the UIApplicationDelegate protocol (except for those in a
-// blacklist we keep).
-void ForEachAppDelegateClass(void (^block)(Class));
+// Calls the given block for each unique Objective-C class that has been
+// previously passed to [UIApplication setDelegate:]. The block is executed
+// immediately for all currently known unique delegate classes.
+// Additionally, the block is queued to be executed if any new, unique
+// Objective-C class is passed to [UIApplication setDelegate:] in the future.
+void RunOnAppDelegateClasses(void (^block)(Class));
 
 // Convert a string array into an NSMutableArray.
 NSMutableArray *StringVectorToNSMutableArray(