Proposal to standardize integrations

Author: aram356

Cargo.lock

@@ -21,6 +21,7 @@ brotli = "8.0"
 bytes = "1.10"
 chacha20poly1305 = "0.10"
 chrono = "0.4.42"
+async-trait = "0.1"
 config = "0.15.18"
 cookie = "0.18.1"
 derive_more = { version = "2.0", features = ["display", "error"] }

Cargo.toml

@@ -25,7 +25,7 @@ NOT all the capabilities. Tech Lab will build and support core services to enabl
 **Does the Trusteed Server preclude using third party tags?**
 No, it does not. You should be able to begin migrating certain modules and parts of your content and experience as you go, without a forklift upgrade. We plan to support server side tagging capabilities to enable third party support.
 
-**Why are you only using two vendors in the POC?** 
+**Why are you only using two partners in the POC?** 
 Fastly and Equativ volunteered time and resources to us and they fit the technical needs and requirements for Trusted Server. For the sake of getting to market ASAP, we chose to double down on these two partners. We do not play favorites or have any financial incentive with these two companies and will begin implementing on other partners in the near future.  Any ad exchange supporting prebid server requests should already find support. We will prioritize modules for other edge cloud providers based on industry priorities
 
 **How will this project be managed?**
@@ -39,4 +39,3 @@ Yes. As long as your managed service provider can separate the edge from the CMS
 
 **How will this comply with Privacy regulations?**
 The trusted server will have modules to support Consent Management Providers (CMP) and send the GPP or TCF string as required in the ad request.
-

FAQ_POC.md

@@ -21,8 +21,8 @@ At this time, Trusted Server is designed to work with Fastly Compute. Follow the
     - Click Compute and Create Service 
     - Click “Create Empty Service” (below main options) 
     - Add your domain of the website you’ll be testing or using and click update
-    - Click on “Origins” section and add your ad-server / ssp partner information as hostnames (note after you save this information you can select port numbers and TLS on/off) 
-    - IMPORTANT: when you enter the FQDN or IP ADDR information and click Add you need to enter a “Name” in the first field that will be referenced in your code so something like “my_ad_partner_1” 
+    - Click on “Origins” section and add your ad-server / SSP integration information as hostnames (note after you save this information you can select port numbers and TLS on/off) 
+    - IMPORTANT: when you enter the FQDN or IP ADDR information and click Add you need to enter a “Name” in the first field that will be referenced in your code so something like “my_ad_integration_1” 
     - 
 
 :warning: With a dev account, Fastly gives you a test domain by default, but you’re also able to create a CNAME to your own domain when you’re ready, along with 2 free TLS certs (non-wildcard). Note that Fastly Compute ONLY accepts client traffic via TLS, though origins and backends can be non-TLS.
@@ -226,4 +226,8 @@ Once configured, the following endpoints are available:
  Notes
  - Rewriting uses `lol_html`. Only absolute and protocol‑relative URLs are rewritten; relative URLs are left unchanged.
  - For the proxy endpoint, the base URL is carried in `tsurl`, the original query parameters are preserved individually, and `tstoken` authenticates the reconstructed full URL.
- - Synthetic identifiers are generated by `crates/common/src/synthetic.rs` and are surfaced in three places: publisher responses (headers + cookie), creative proxy target URLs (`synthetic_id` query param), and click redirect URLs. This ensures downstream partners can correlate impressions and clicks without direct third-party cookies.
+ - Synthetic identifiers are generated by `crates/common/src/synthetic.rs` and are surfaced in three places: publisher responses (headers + cookie), creative proxy target URLs (`synthetic_id` query param), and click redirect URLs. This ensures downstream integrations can correlate impressions and clicks without direct third-party cookies.
+
+## Integration Modules
+
+- See [`docs/integration_guide.md`](docs/integration_guide.md) for the full integration module guide, covering configuration, proxy routing, HTML shim hooks, and the `starlight` example implementation.

README.md

@@ -14,6 +14,7 @@ brotli = { workspace = true }
 bytes = { workspace = true }
 chacha20poly1305 = { workspace = true }
 chrono = { workspace = true }
+async-trait = { workspace = true }
 config = { workspace = true }
 cookie = { workspace = true }
 derive_more = { workspace = true }

crates/common/Cargo.toml

@@ -50,6 +50,13 @@ pub enum TrustedServerError {
     #[display("Prebid error: {message}")]
     Prebid { message: String },
 
+    /// Integration module error.
+    #[display("Integration error ({integration}): {message}")]
+    Integration {
+        integration: String,
+        message: String,
+    },
+
     /// Proxy error.
     #[display("Proxy error: {message}")]
     Proxy { message: String },
@@ -91,6 +98,7 @@ impl IntoHttpResponse for TrustedServerError {
             Self::InvalidUtf8 { .. } => StatusCode::BAD_REQUEST,
             Self::KvStore { .. } => StatusCode::SERVICE_UNAVAILABLE,
             Self::Prebid { .. } => StatusCode::BAD_GATEWAY,
+            Self::Integration { .. } => StatusCode::BAD_GATEWAY,
             Self::Proxy { .. } => StatusCode::BAD_GATEWAY,
             Self::SyntheticId { .. } => StatusCode::INTERNAL_SERVER_ERROR,
             Self::Template { .. } => StatusCode::INTERNAL_SERVER_ERROR,