feat(ads-client): add OHTTP support (AC-94)

- Route ad requests through an OHTTP relay via `ohttp: bool` in `MozAdsRequestOptions`
- Channel is configured once at startup via `viaduct::ohttp::configure_ohttp_channel("ads-client", ...)`
- Refactored `RequestCachePolicy` into an enum with `Duration` TTL fields
- Renamed `send_with_policy` → `send_with_options`, `use_ohttp` → `ohttp`
- `build()` is infallible again (OHTTP config moved out of builder)
- Documented OHTTP usage with JavaScript (HNT), Kotlin, and Swift examples

Author: Almaju

CHANGELOG.md

@@ -7,6 +7,10 @@
 
 ## ✨ What's New ✨
 
+### Ads Client
+- Add OHTTP support via `enable_ohttp(relay_url, gateway_config_url)` builder method on `MozAdsClientBuilder`. ([AC-94](https://mozilla-hub.atlassian.net/browse/AC-94))
+- Add `try_build()` method on `MozAdsClientBuilder` returning a `Result` for proper error handling. The existing `build()` method is now deprecated.
+
 ### Logins
 - New `allow_empty_passwords` feature flag to allow storing logins with empty passwords. This feature is intended to be enabled on desktop during the migration.
 - Add `ignore_form_action_origin_validation_errors` feature flag that allows logins with non-URL `form_action_origin` values (e.g. "email", "UserCode") to be imported without error. URL normalization for valid URLs is still applied.

components/ads-client/Cargo.toml

@@ -27,7 +27,7 @@ once_cell = "1.5"
 uniffi = { version = "0.31" }
 url = { version = "2", features = ["serde"] }
 uuid = { version = "1.3", features = ["v4"] }
-viaduct = { path = "../viaduct" }
+viaduct = { path = "../viaduct", features = ["ohttp"] }
 sql-support = { path = "../support/sql" }
 
 [dev-dependencies]

components/ads-client/README.md

@@ -44,4 +44,8 @@ cargo test -p ads-client-integration-tests --test mars test_contract_image_stagi
 
 ## Usage
 
-Please refer to `./docs/usage.md` for information on using the component.
+Language-specific usage guides are available in `./docs/`:
+
+- [JavaScript (HNT)](./docs/usage-javascript.md)
+- [Kotlin](./docs/usage-kotlin.md)
+- [Swift](./docs/usage-swift.md)

components/ads-client/docs/usage-javascript.md

@@ -12,6 +12,6 @@ ads-client = { path = ".." }
 serde_json = "1"
 url = "2"
 mockito = { version = "0.31", default-features = false }
-viaduct = { path = "../../../components/viaduct" }
+viaduct = { path = "../../../components/viaduct", features = ["ohttp"] }
 viaduct-dev = { path = "../../../components/support/viaduct-dev" }
 viaduct-hyper = { path = "../../../components/support/viaduct-hyper" }

components/ads-client/docs/usage-kotlin.md

@@ -7,7 +7,7 @@ use std::sync::Arc;
 
 use ads_client::{
     MozAdsClientBuilder, MozAdsEnvironment, MozAdsPlacementRequest,
-    MozAdsPlacementRequestWithCount, MozAdsReportReason,
+    MozAdsPlacementRequestWithCount, MozAdsReportReason, MozAdsRequestOptions,
 };
 
 fn init_backend() {
@@ -171,3 +171,31 @@ fn test_report_ad() {
     let result = client.report_ad(report_url.to_string(), MozAdsReportReason::NotInterested);
     assert!(result.is_ok(), "report_ad failed: {:?}", result.err());
 }
+
+#[test]
+#[ignore = "integration test: run manually with -- --ignored"]
+fn test_contract_tile_ohttp_prod() {
+    init_backend();
+    viaduct::ohttp::configure_ohttp_channel(
+        "ads-client".to_string(),
+        viaduct::ohttp::OhttpConfig {
+            relay_url: "https://mozilla-ohttp.fastly-edge.com/".to_string(),
+            gateway_host: "prod.ohttp-gateway.prod.webservices.mozgcp.net".to_string(),
+        },
+    )
+    .expect("OHTTP channel configuration should succeed");
+    let client = prod_client();
+    let placements = client
+        .request_tile_ads(
+            vec![MozAdsPlacementRequest {
+                placement_id: "mock_tile_1".to_string(),
+                iab_content: None,
+            }],
+            Some(MozAdsRequestOptions {
+                ohttp: true,
+                cache_policy: None,
+            }),
+        )
+        .expect("tile ad request over OHTTP should succeed");
+    assert!(placements.contains_key("mock_tile_1"));
+}

components/ads-client/docs/usage-swift.md

@@ -26,7 +26,7 @@ impl ReportReason {
         }
     }
 }
-use crate::http_cache::{HttpCache, RequestCachePolicy};
+use crate::http_cache::{HttpCache, RequestOptions};
 use crate::mars::MARSClient;
 use crate::telemetry::Telemetry;
 use ad_request::{AdPlacementRequest, AdRequest};
@@ -96,9 +96,9 @@ where
 
             let client = MARSClient::new(http_cache, telemetry.clone());
             let client = Self {
-                environment,
-                context_id_component,
                 client,
+                context_id_component,
+                environment,
                 telemetry: telemetry.clone(),
                 rotation_days,
             };
@@ -108,9 +108,9 @@ where
 
         let client = MARSClient::new(None, telemetry.clone());
         let client = Self {
-            environment,
-            context_id_component,
             client,
+            context_id_component,
+            environment,
             telemetry: telemetry.clone(),
             rotation_days,
         };
@@ -121,16 +121,16 @@ where
     fn request_ads<A>(
         &self,
         ad_placement_requests: Vec<AdPlacementRequest>,
-        options: Option<RequestCachePolicy>,
+        options: Option<RequestOptions>,
     ) -> Result<AdResponse<A>, RequestAdsError>
     where
         A: AdResponseValue,
     {
         let context_id = self.get_context_id()?;
         let url = self.environment.into_url("ads");
         let ad_request = AdRequest::try_new(context_id, ad_placement_requests, url)?;
-        let cache_policy = options.unwrap_or_default();
-        let (mut response, request_hash) = self.client.fetch_ads::<A>(ad_request, &cache_policy)?;
+        let options = options.unwrap_or_default();
+        let (mut response, request_hash) = self.client.fetch_ads::<A>(ad_request, &options)?;
         response.add_request_hash_to_callbacks(&request_hash);
         response.add_placement_info_to_report_callbacks();
         Ok(response)
@@ -139,7 +139,7 @@ where
     pub fn request_image_ads(
         &self,
         ad_placement_requests: Vec<AdPlacementRequest>,
-        options: Option<RequestCachePolicy>,
+        options: Option<RequestOptions>,
     ) -> Result<HashMap<String, AdImage>, RequestAdsError> {
         let response = self
             .request_ads::<AdImage>(ad_placement_requests, options)
@@ -153,7 +153,7 @@ where
     pub fn request_spoc_ads(
         &self,
         ad_placement_requests: Vec<AdPlacementRequest>,
-        options: Option<RequestCachePolicy>,
+        options: Option<RequestOptions>,
     ) -> Result<HashMap<String, Vec<AdSpoc>>, RequestAdsError> {
         let result = self.request_ads::<AdSpoc>(ad_placement_requests, options);
         result
@@ -169,7 +169,7 @@ where
     pub fn request_tile_ads(
         &self,
         ad_placement_requests: Vec<AdPlacementRequest>,
-        options: Option<RequestCachePolicy>,
+        options: Option<RequestOptions>,
     ) -> Result<HashMap<String, AdTile>, RequestAdsError> {
         let result = self.request_ads::<AdTile>(ad_placement_requests, options);
         result
@@ -268,21 +268,21 @@ mod tests {
             Box::new(DefaultContextIdCallback),
         );
         AdsClient {
-            environment: Environment::Test,
-            context_id_component,
             client,
-            telemetry: MozAdsTelemetryWrapper::noop(),
+            context_id_component,
+            environment: Environment::Test,
             rotation_days: DEFAULT_ROTATION_DAYS,
+            telemetry: MozAdsTelemetryWrapper::noop(),
         }
     }
 
     #[test]
     fn test_get_context_id() {
         let config = AdsClientConfig {
-            environment: Environment::Test,
             cache_config: None,
-            telemetry: MozAdsTelemetryWrapper::noop(),
+            environment: Environment::Test,
             rotation_days: None,
+            telemetry: MozAdsTelemetryWrapper::noop(),
         };
         let client = AdsClient::new(config);
         let context_id = client.get_context_id().unwrap();
@@ -394,7 +394,7 @@ mod tests {
         ads_client
             .request_ads::<AdImage>(
                 make_happy_placement_requests(),
-                Some(RequestCachePolicy::default()),
+                Some(RequestOptions::default()),
             )
             .unwrap();
     }