namespace routes helpers

Author: ChristianPavilonis

crates/common/src/integrations/prebid.rs

@@ -26,6 +26,8 @@ use crate::settings::{IntegrationConfig, Settings};
 use crate::synthetic::{generate_synthetic_id, get_or_generate_synthetic_id};
 
 const PREBID_INTEGRATION_ID: &str = "prebid";
+
+// Legacy route paths (kept for backwards compatibility)
 const ROUTE_FIRST_PARTY_AD: &str = "/first-party/ad";
 const ROUTE_THIRD_PARTY_AD: &str = "/third-party/ad";
 
@@ -136,7 +138,11 @@ impl PrebidIntegration {
             },
         )?;
 
-        log::info!("/third-party/ad: received {} adUnits", body.ad_units.len());
+        log::info!(
+            "{}: received {} adUnits",
+            ROUTE_THIRD_PARTY_AD,
+            body.ad_units.len()
+        );
         for unit in &body.ad_units {
             if let Some(mt) = &unit.media_types {
                 if let Some(banner) = &mt.banner {
@@ -264,6 +270,10 @@ pub fn register(settings: &Settings) -> Option<IntegrationRegistration> {
 
 #[async_trait(?Send)]
 impl IntegrationProxy for PrebidIntegration {
+    fn integration_name(&self) -> &'static str {
+        PREBID_INTEGRATION_ID
+    }
+
     fn routes(&self) -> Vec<IntegrationEndpoint> {
         let mut routes = vec![
             IntegrationEndpoint::get(ROUTE_FIRST_PARTY_AD),

crates/common/src/integrations/registry.rs

@@ -121,7 +121,13 @@ impl IntegrationEndpoint {
 /// Trait implemented by integration proxies that expose HTTP endpoints.
 #[async_trait(?Send)]
 pub trait IntegrationProxy: Send + Sync {
-    /// Routes handled by this integration (e.g. `/integrations/example/auction`).
+    /// Integration identifier used for logging and optional URL namespace.
+    /// Use this with the `namespaced_*` helper methods to automatically prefix routes.
+    fn integration_name(&self) -> &'static str;
+
+    /// Routes handled by this integration.
+    /// to automatically namespace routes under `/integrations/{integration_name()}/`,
+    /// or define routes manually for backwards compatibility.
     fn routes(&self) -> Vec<IntegrationEndpoint>;
 
     /// Handle the proxied request.
@@ -130,6 +136,30 @@ pub trait IntegrationProxy: Send + Sync {
         settings: &Settings,
         req: Request,
     ) -> Result<Response, Report<TrustedServerError>>;
+
+    /// Helper to create a namespaced GET endpoint.
+    /// Automatically prefixes the path with `/integrations/{integration_name()}`.
+    ///
+    /// # Example
+    /// ```ignore
+    /// self.namespaced_get("/auction")  // becomes /integrations/my_integration/auction
+    /// ```
+    fn get(&self, path: &str) -> IntegrationEndpoint {
+        let full_path = format!("/integrations/{}{}", self.integration_name(), path);
+        IntegrationEndpoint::get(Box::leak(full_path.into_boxed_str()))
+    }
+
+    /// Helper to create a namespaced POST endpoint.
+    /// Automatically prefixes the path with `/integrations/{integration_name()}`.
+    ///
+    /// # Example
+    /// ```ignore
+    /// self.namespaced_post("/auction")  // becomes /integrations/my_integration/auction
+    /// ```
+    fn post(&self, path: &str) -> IntegrationEndpoint {
+        let full_path = format!("/integrations/{}{}", self.integration_name(), path);
+        IntegrationEndpoint::post(Box::leak(full_path.into_boxed_str()))
+    }
 }
 
 /// Trait for integration-provided HTML attribute rewrite hooks.
@@ -443,6 +473,10 @@ mod tests {
 
     #[async_trait(?Send)]
     impl IntegrationProxy for MockProxy {
+        fn integration_name(&self) -> &'static str {
+            "test"
+        }
+
         fn routes(&self) -> Vec<IntegrationEndpoint> {
             vec![]
         }

crates/common/src/integrations/testlight.rs

@@ -121,8 +121,12 @@ pub fn register(settings: &Settings) -> Option<IntegrationRegistration> {
 
 #[async_trait(?Send)]
 impl IntegrationProxy for TestlightIntegration {
+    fn integration_name(&self) -> &'static str {
+        TESTLIGHT_INTEGRATION_ID
+    }
+
     fn routes(&self) -> Vec<IntegrationEndpoint> {
-        vec![IntegrationEndpoint::post("/integrations/testlight/auction")]
+        vec![self.post("/auction")]
     }
 
     async fn handle(

docs/integration_guide.md

@@ -112,10 +112,14 @@ Implement the trait from `registry.rs` when your integration needs its own HTTP
 ```rust
 #[async_trait(?Send)]
 impl IntegrationProxy for MyIntegration {
+    fn integration_name(&self) -> &'static str {
+        "my_integration"
+    }
+
     fn routes(&self) -> Vec<IntegrationEndpoint> {
         vec![
-            IntegrationEndpoint::post("/integrations/my-integration/auction"),
-            IntegrationEndpoint::get("/integrations/my-integration/status"),
+            self.post("/auction"),
+            self.get("/status"),
         ]
     }
 
@@ -129,11 +133,20 @@ impl IntegrationProxy for MyIntegration {
 }
 ```
 
-Routes are matched verbatim in `crates/fastly/src/main.rs`, so stick to stable paths
-(`/integrations/<id>/…`) and register whichever HTTP methods you need. The shared context
-already injects Trusted Server logging, headers, and error handling; the handler only
-needs to deserialize the request, call the upstream endpoint, and stamp integration-specific
-headers.
+**Recommended:** Use the provided helper methods `get()` or `post()` 
+to automatically namespace your routes under `/integrations/{integration_name()}/`.
+This lets you define routes with just their relative paths (e.g., `self.post("/auction")` becomes 
+`"/integrations/my_integration/auction"`). You can also define routes manually using
+`IntegrationEndpoint::get()` / `IntegrationEndpoint::post()` for backwards compatibility or 
+special cases.
+
+Routes are matched verbatim in `crates/fastly/src/main.rs`, so stick to stable paths and 
+register whichever HTTP methods you need. **New integrations should namespace their routes under
+`/integrations/{INTEGRATION_NAME}/`** using the helper methods (`self.get()` or `self.post()`)
+for consistency, but you can define routes manually if needed (e.g., for backwards compatibility).
+The shared context already injects Trusted Server logging, headers, 
+and error handling; the handler only needs to deserialize the request, call the upstream endpoint,
+and stamp integration-specific headers.
 
 #### Proxying upstream requests
 
@@ -308,10 +321,12 @@ Prebid applies the same steps outlined above with a few notable patterns:
    `settings.integrations.insert_config("prebid", &serde_json::json!({...}))`, the same helper that
    other integrations use.
 
-2. **Routes owned by the integration** – `IntegrationProxy::routes` declares the legacy
-   `/first-party/ad` (GET) and `/third-party/ad` (POST) endpoints. Both handlers share helpers that
-   shape OpenRTB payloads, inject synthetic IDs + geo/request-signing context, forward requests via
-   `ensure_backend_from_url`, and run the HTML creative rewrites before responding.
+2. **Routes owned by the integration** – `IntegrationProxy::routes` declares the
+   `/integrations/prebid/first-party/ad` (GET) and `/integrations/prebid/third-party/ad` (POST)
+   endpoints. Both handlers share helpers that shape OpenRTB payloads, inject synthetic IDs +
+   geo/request-signing context, forward requests via `ensure_backend_from_url`, and run the HTML
+   creative rewrites before responding. All routes are properly namespaced under
+   `/integrations/prebid/` to follow the integration routing pattern.
 
 3. **HTML rewrites through the registry** – When `auto_configure` is enabled, the integration’s
    `IntegrationAttributeRewriter` removes any `<script src="prebid*.js">` or `<link href=…>`