feat(nimbus): fetch targeting contexts directly from each firefox app source code (#14936)

Because

- We plan to add automated validation for Experimenter targeting configs
by checking JEXL field references against the upstream targeting context
definitions in the Desktop, Fenix, and iOS source code
- Manifesttool already fetches app manifests per ref/version, but it was
not downloading the targeting context source files that external config
updates depend on.

This commit

- Adds `targeting_files` to app config and configures it for
firefox-desktop, fenix, and ios
- Stores the files by version in each app's feature manifest as well as
an unversioned copy in the root

Fixes #14922

Author: moibra05

experimenter/experimenter/features/manifests/apps.yaml

@@ -18,6 +18,8 @@ fenix:
           - "main"
           - "beta"
           - "release"
+  targeting_files:
+    - "mobile/android/fenix/app/src/main/java/org/mozilla/fenix/experiments/RecordedNimbusContext.kt"
 
 firefox_ios:
   slug: "ios"
@@ -42,6 +44,8 @@ firefox_ios:
         branch_re: 'release/v(?P<major>\d+)(?:\.(?P<minor>\d+))?'
         tag_re: 'firefox-v(?P<major>\d+)\.(?P<minor>\d+)'
       - type: "branched"
+  targeting_files:
+    - "firefox-ios/Client/Experiments/RecordedNimbusContext.swift"
 
 monitor_cirrus:
   slug: "monitor-web"
@@ -85,6 +89,8 @@ firefox_desktop:
           - "esr115"
           - "esr128"
           - "esr140"
+  targeting_files:
+    - "toolkit/components/nimbus/lib/TargetingContextRecorder.sys.mjs"
 
 experimenter_cirrus:
   slug: "experimenter"

experimenter/manifesttool/appconfig.py

@@ -150,6 +150,7 @@ class AppConfig(BaseModel):
     fml_path: str | list[str] | None = None
     experimenter_yaml_path: str | None = None
     release_discovery: ReleaseDiscovery | None = None
+    targeting_files: list[str] | None = None
 
     @model_validator(mode="before")
     @classmethod

experimenter/manifesttool/fetch.py

@@ -35,6 +35,24 @@ def __str__(self):  # pragma: no cover
         return as_str
 
 
+def fetch_targeting_files(
+    save_path: Path,
+    logging_msg: str,
+    app_config: AppConfig,
+    ref: Ref,
+) -> None:
+    targeting_files_path = app_config.targeting_files
+    if targeting_files_path:
+        print(logging_msg)
+
+        github_api.fetch_file(
+            app_config.repo.name,
+            targeting_files_path[0],
+            ref.target,
+            save_path / Path(targeting_files_path[0]).name,
+        )
+
+
 def fetch_fml_app(
     manifest_dir: Path,
     app_name: str,
@@ -107,6 +125,13 @@ def fetch_fml_app(
                 version,
             )
 
+        fetch_targeting_files(
+            manifest_dir / app_config.slug / f"v{version}",
+            f"fetch: {app_name} at {ref} version {version} downloading targeting files",
+            app_config,
+            ref,
+        )
+
         print(f"fetch: {app_name}: generate experimenter.yaml")
         # The single-file fml file for each channel will generate the same
         # experimenter.yaml, so we can pick any here.
@@ -169,6 +194,13 @@ def fetch_legacy_app(
             manifest_path,
         )
 
+        fetch_targeting_files(
+            manifest_dir / app_config.slug / f"v{version}",
+            f"fetch: {app_name} at {ref} version {version} downloading targeting files",
+            app_config,
+            ref,
+        )
+
         with manifest_path.open() as f:
             raw_manifest = yaml.safe_load(f)
             manifest = DesktopFeatureManifest.parse_obj(raw_manifest)
@@ -252,6 +284,12 @@ def fetch_releases(
 
         results.append(result)
 
+    fetch_targeting_files(
+        manifest_dir / app_config.slug,
+        f"fetch: {app_name} at {ref.name} downloading targeting files ",
+        app_config,
+        ref,
+    )
     return results
 
 

experimenter/manifesttool/github_api.py

@@ -96,7 +96,9 @@ def _get_refs(repo: str, kind: str) -> list[Ref]:
 
 
 @overload
-def fetch_file(repo: str, file_path: str, rev: str) -> str: ...  # pragma: no cover
+def fetch_file(
+    repo: str, file_path: str, rev: str
+) -> Optional[str]: ...  # pragma: no cover
 
 
 @overload

experimenter/manifesttool/tests/test_fetch.py

@@ -101,6 +101,7 @@ def mock_download_single_file(
     version: Optional[Version],
 ):
     """A mock version of `nimbus fml -- single file`."""
+    (manifest_dir / app_config.slug).mkdir(exist_ok=True)
     filename = _get_fml_path(manifest_dir, app_config, channel, version)
     with filename.open("w") as f:
         yaml.dump(generate_fml(app_config, channel), f)
@@ -880,6 +881,42 @@ def test_fetch_legacy_unresolved_ref(self):
             ):
                 fetch_legacy_app(manifest_dir, "repo", LEGACY_APP_CONFIG, Ref("foo"))
 
+    @patch.object(
+        manifesttool.fetch.github_api,
+        "fetch_file",
+        side_effect=make_mock_fetch_file(
+            paths_by_ref={
+                "foo": {
+                    "experimenter.yaml": LEGACY_MANIFEST,
+                    "targeting_files.txt": {"context": "data"},
+                }
+            }
+        ),
+    )
+    def test_fetch_legacy_targeting_files(self, fetch_file):
+        targeting_files_path = "targeting_files.txt"
+        app_config = AppConfig(
+            slug="legacy-app",
+            repo=Repository(
+                type=RepositoryType.GITHUB,
+                name="legacy-repo",
+                default_branch="tip",
+            ),
+            experimenter_yaml_path="experimenter.yaml",
+            targeting_files=[targeting_files_path],
+        )
+
+        with TemporaryDirectory() as tmp:
+            manifest_dir = Path(tmp)
+            manifest_dir.joinpath("legacy-app").mkdir()
+            fetch_legacy_app(
+                manifest_dir, "app", app_config, Ref("tip", "foo"), Version(1, 0, 0)
+            )
+
+            self.assertTrue(
+                (manifest_dir / "legacy-app" / "v1.0.0" / "targeting_files.txt").exists()
+            )
+
     def test_fetch_releases_unsupported_apps(self):
         """Testing fetch_releases with unsupported apps."""
         app_config = AppConfig(
@@ -1082,6 +1119,73 @@ def test_fetch_releases_cached(self, fetch_fml_app):
             ),
         )
 
+    @patch.object(
+        manifesttool.fetch,
+        "discover_branched_releases",
+        lambda *args: {
+            Version(1): Ref("branch", "foo"),
+            Version(1, 2, 3): Ref("tag", "bar"),
+        },
+    )
+    @patch.object(
+        manifesttool.fetch.github_api,
+        "fetch_file",
+        side_effect=make_mock_fetch_file(
+            paths_by_ref={
+                "foo": {"targeting-contexts.yaml": {"context": "v1.0.0"}},
+                "bar": {"targeting-contexts.yaml": {"context": "v1.2.3"}},
+            }
+        ),
+    )
+    @patch.object(
+        manifesttool.fetch.nimbus_cli,
+        "download_single_file",
+        side_effect=mock_download_single_file,
+    )
+    @patch.object(
+        manifesttool.fetch.nimbus_cli,
+        "get_channels",
+        side_effect=lambda *args: ["release", "beta"],
+    )
+    def test_fetch_releases_targeting_contexts(
+        self,
+        get_channels,
+        download_single_file,
+        fetch_file,
+    ):
+        app_config = AppConfig(
+            slug="fml-app",
+            repo=Repository(
+                type=RepositoryType.GITHUB,
+                name="fml-repo",
+            ),
+            fml_path="nimbus.fml.yaml",
+            release_discovery=ReleaseDiscovery(
+                version_file=VersionFile.create_plain_text("version.txt"),
+                strategies=[DiscoveryStrategy.create_branched()],
+            ),
+            targeting_files=["targeting-contexts.yaml"],
+        )
+
+        cache = RefCache()
+
+        with TemporaryDirectory() as tmp:
+            manifest_dir = Path(tmp)
+
+            fetch_releases(manifest_dir, "fml_app", app_config, cache)
+
+            self.assertTrue(
+                (manifest_dir / "fml-app" / "v1.0.0" / "targeting-contexts.yaml").exists()
+            )
+            self.assertTrue(
+                (manifest_dir / "fml-app" / "v1.2.3" / "targeting-contexts.yaml").exists()
+            )
+            self.assertTrue(
+                (manifest_dir / "fml-app" / "targeting-contexts.yaml").exists()
+            )
+
+            self.assertEqual(fetch_file.call_count, 3)
+
     def test_summarize_results(self):
         buffer = StringIO()