Expose edge geo data and modularize injection

Third-party geo lookups add avoidable latency and introduce privacy
and compliance risk. This change exposes edge-derived location data
via a first-party endpoint, enabling the trusted server to supply
targeting information without relying on browser-side APIs.

Decouples geo handling from dependencies to improve reliability and
modularity. Refactors Prebid injection to utilize the internal JS
library, ensuring consistent initialization and reducing
client-side complexity.

Author: prk-Jr

crates/common/src/geo.rs

@@ -4,7 +4,6 @@
 //! information from incoming requests, particularly DMA (Designated Market Area) codes.
 
 use fastly::geo::geo_lookup;
-use fastly::Request;
 
 use crate::constants::{
     HEADER_X_GEO_CITY, HEADER_X_GEO_CONTINENT, HEADER_X_GEO_COORDINATES, HEADER_X_GEO_COUNTRY,
@@ -33,6 +32,14 @@ pub struct GeoInfo {
     pub region: Option<String>,
 }
 
+use core::result::Result;
+use error_stack::Report;
+use fastly::http::StatusCode;
+use fastly::{Request, Response};
+
+use crate::error::TrustedServerError;
+use crate::settings::Settings;
+
 impl GeoInfo {
     /// Creates a new `GeoInfo` from a request by performing a geo lookup.
     ///
@@ -150,3 +157,20 @@ pub fn get_dma_code(req: &mut Request) -> Option<String> {
 
     None
 }
+
+/// Handles requests to `/first-party/geo` and returns the geo information as JSON.
+pub fn handle_first_party_geo(
+    _settings: &Settings,
+    req: Request,
+) -> Result<Response, Report<TrustedServerError>> {
+    let geo_info = GeoInfo::from_request(&req);
+
+    Response::from_status(StatusCode::OK)
+        .with_body_json(&geo_info)
+        .map_err(|_| {
+            Report::new(TrustedServerError::Integration {
+                integration: "geo".to_string(),
+                message: "Failed to serialize response".to_string(),
+            })
+        })
+}

crates/common/src/html_processor.rs

@@ -8,6 +8,7 @@ use std::sync::Arc;
 
 use lol_html::{element, html_content::ContentType, text, Settings as RewriterSettings};
 
+use crate::geo::GeoInfo;
 use crate::integrations::{
     AttributeRewriteOutcome, IntegrationAttributeContext, IntegrationDocumentState,
     IntegrationHtmlContext, IntegrationHtmlPostProcessor, IntegrationRegistry,
@@ -24,6 +25,7 @@ struct HtmlWithPostProcessing {
     request_host: String,
     request_scheme: String,
     document_state: IntegrationDocumentState,
+    geo: Option<GeoInfo>,
 }
 
 impl StreamProcessor for HtmlWithPostProcessing {
@@ -42,6 +44,7 @@ impl StreamProcessor for HtmlWithPostProcessing {
             request_scheme: &self.request_scheme,
             origin_host: &self.origin_host,
             document_state: &self.document_state,
+            geo: self.geo.as_ref(),
         };
 
         // Preflight to avoid allocating a `String` unless at least one post-processor wants to run.
@@ -90,6 +93,7 @@ pub struct HtmlProcessorConfig {
     pub request_host: String,
     pub request_scheme: String,
     pub integrations: IntegrationRegistry,
+    pub geo: Option<GeoInfo>,
 }
 
 impl HtmlProcessorConfig {
@@ -107,6 +111,7 @@ impl HtmlProcessorConfig {
             request_host: request_host.to_string(),
             request_scheme: request_scheme.to_string(),
             integrations: integrations.clone(),
+            geo: None,
         }
     }
 }
@@ -194,6 +199,7 @@ pub fn create_html_processor(config: HtmlProcessorConfig) -> impl StreamProcesso
             let integrations = integration_registry.clone();
             let patterns = patterns.clone();
             let document_state = document_state.clone();
+            let geo = config.geo.clone();
             move |el| {
                 if !injected_tsjs.get() {
                     let mut snippet = String::new();
@@ -202,6 +208,7 @@ pub fn create_html_processor(config: HtmlProcessorConfig) -> impl StreamProcesso
                         request_scheme: &patterns.request_scheme,
                         origin_host: &patterns.origin_host,
                         document_state: &document_state,
+                        geo: geo.as_ref(),
                     };
                     // First inject the TSJS bundle (defines tsjs.setConfig, etc.)
                     let module_ids = integrations.js_module_ids();
@@ -467,6 +474,7 @@ pub fn create_html_processor(config: HtmlProcessorConfig) -> impl StreamProcesso
         request_host: config.request_host,
         request_scheme: config.request_scheme,
         document_state,
+        geo: config.geo,
     }
 }
 
@@ -489,6 +497,7 @@ mod tests {
             request_host: "test.example.com".to_string(),
             request_scheme: "https".to_string(),
             integrations: IntegrationRegistry::default(),
+            geo: None,
         }
     }
 

crates/common/src/integrations/geo.rs

@@ -0,0 +1,156 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use error_stack::Report;
+
+use crate::error::TrustedServerError;
+use crate::integrations::{
+    IntegrationEndpoint, IntegrationHeadInjector, IntegrationHtmlContext, IntegrationProxy,
+    IntegrationRegistration,
+};
+use crate::settings::{GeoConfig, Settings};
+
+const GEO_INTEGRATION_ID: &str = "geo";
+
+pub struct GeoIntegration {
+    config: GeoConfig,
+}
+
+impl GeoIntegration {
+    pub fn new(config: GeoConfig) -> Self {
+        Self { config }
+    }
+}
+
+pub fn build(settings: &Settings) -> Option<Arc<GeoIntegration>> {
+    if !settings.geo.inject {
+        return None;
+    }
+    Some(Arc::new(GeoIntegration::new(settings.geo.clone())))
+}
+
+#[must_use]
+pub fn register(settings: &Settings) -> Option<IntegrationRegistration> {
+    let integration = build(settings)?;
+    Some(
+        IntegrationRegistration::builder(GEO_INTEGRATION_ID)
+            .with_head_injector(integration)
+            .build(),
+    )
+}
+
+#[async_trait(?Send)]
+impl IntegrationProxy for GeoIntegration {
+    fn integration_name(&self) -> &'static str {
+        GEO_INTEGRATION_ID
+    }
+
+    fn routes(&self) -> Vec<IntegrationEndpoint> {
+        vec![]
+    }
+
+    async fn handle(
+        &self,
+        _settings: &Settings,
+        _req: fastly::Request,
+    ) -> Result<fastly::Response, Report<TrustedServerError>> {
+        // This integration doesn't handle any routes, but we must implement the trait method.
+        // Since we return empty routes(), this should arguably never be called.
+        // However, if it is, returning a 404 or logging an error is appropriate.
+        // For now, let's return a generic 404.
+        Ok(fastly::Response::from_status(
+            fastly::http::StatusCode::NOT_FOUND,
+        ))
+    }
+}
+
+#[async_trait(?Send)]
+impl IntegrationHeadInjector for GeoIntegration {
+    fn integration_id(&self) -> &'static str {
+        GEO_INTEGRATION_ID
+    }
+
+    fn head_inserts(&self, context: &IntegrationHtmlContext) -> Vec<String> {
+        let mut inserts = Vec::new();
+
+        if let Some(geo) = &context.geo {
+            let geo_json = serde_json::to_string(geo).unwrap_or_else(|_| "null".to_string());
+            let cache_key = &self.config.cache_key;
+
+            // Script to inject geo info into localStorage for client-side access
+            let script = format!(
+                r#"<script>
+                (function() {{
+                    try {{
+                        var geo = {geo_json};
+                        if (geo) {{
+                            window._tudeGeo = geo;
+                            localStorage.setItem('{cache_key}', JSON.stringify(geo));
+                        }}
+                    }} catch (e) {{
+                        console.error('Error injecting geo info:', e);
+                    }}
+                }})();
+                </script>"#
+            );
+            inserts.push(script);
+        }
+
+        inserts
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::geo::GeoInfo;
+    use crate::integrations::IntegrationHtmlContext;
+
+    #[test]
+    fn test_geo_injection() {
+        let config = GeoConfig {
+            inject: true,
+            cache_key: "test-cache-key".to_string(),
+        };
+        let integration = GeoIntegration::new(config);
+
+        // Test with GeoInfo present
+        let geo_info = GeoInfo {
+            country: "US".to_string(),
+            region: Some("NY".to_string()),
+            city: "New York".to_string(),
+            continent: "North America".to_string(),
+            latitude: 40.71,
+            longitude: -74.00,
+            metro_code: 501,
+        };
+
+        let context = IntegrationHtmlContext {
+            request_host: "example.com",
+            request_scheme: "https",
+            origin_host: "origin.example.com",
+            document_state: &Default::default(),
+            geo: Some(&geo_info),
+        };
+
+        let inserts = integration.head_inserts(&context);
+        assert_eq!(inserts.len(), 1);
+        assert!(inserts[0].contains("window._tudeGeo ="));
+        assert!(
+            inserts[0].contains(r#"localStorage.setItem('test-cache-key', JSON.stringify(geo))"#)
+        );
+        assert!(inserts[0].contains(r#""country":"US""#));
+
+        // Test with GeoInfo missing
+        let context_no_geo = IntegrationHtmlContext {
+            request_host: "example.com",
+            request_scheme: "https",
+            origin_host: "origin.example.com",
+            document_state: &Default::default(),
+            geo: None,
+        };
+
+        let inserts_no_geo = integration.head_inserts(&context_no_geo);
+        assert!(inserts_no_geo.is_empty());
+    }
+}

crates/common/src/integrations/mod.rs

@@ -6,6 +6,7 @@ pub mod adserver_mock;
 pub mod aps;
 pub mod datadome;
 pub mod didomi;
+pub mod geo;
 pub mod lockr;
 pub mod nextjs;
 pub mod permutive;
@@ -25,6 +26,7 @@ type IntegrationBuilder = fn(&Settings) -> Option<IntegrationRegistration>;
 
 pub(crate) fn builders() -> &'static [IntegrationBuilder] {
     &[
+        geo::register,
         prebid::register,
         testlight::register,
         nextjs::register,