From 613ada88280062e889093a559f1105ce274f955b Mon Sep 17 00:00:00 2001 From: Aram Grigoryan <132480+aram356@users.noreply.github.com> Date: Tue, 20 Jan 2026 10:02:18 -0800 Subject: [PATCH 1/4] Onboarding documenation --- .agents/rules/git-commit-conventions.mdc | 5 +- AGENTS.md | 2 +- CONTRIBUTING.md | 71 ++- docs/ONBOARDING.md | 643 +++++++++++++++++++++++ fastly.toml | 2 - 5 files changed, 683 insertions(+), 40 deletions(-) create mode 100644 docs/ONBOARDING.md diff --git a/.agents/rules/git-commit-conventions.mdc b/.agents/rules/git-commit-conventions.mdc index 03471e8..0be93cb 100644 --- a/.agents/rules/git-commit-conventions.mdc +++ b/.agents/rules/git-commit-conventions.mdc @@ -15,6 +15,7 @@ Commit messages should: 2. Use sentence case (capitalize first word) 3. Describe the change in an imperative, present-tense style 4. Not use semantic prefixes (like "fix:", "feat:", "chore:") +5. Not use bracketed tags (like "[Docs]" or "[Fix]") ## Examples @@ -27,7 +28,7 @@ Fix PostgreSQL integration type reference issues Improve error handling in token validation ``` -### Avoid semantic prefixes: +### Avoid semantic prefixes and tags: ```text // Don't use these formats @@ -35,4 +36,6 @@ fix: add feature flags to tests feat: implement new logging system chore: update dependencies docs: update README +[Docs] Update README +[Fix] Handle empty payload ``` diff --git a/AGENTS.md b/AGENTS.md index 91b53a5..7d3a8a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,4 +114,4 @@ cargo check - Relies on Fastly KV stores for persistence. - Uses Handlebars templates for dynamic responses. - Emits detailed logs for edge debugging. -- Follow conventional commit format (see `CONTRIBUTING.md`). +- Follow the commit message format in `CONTRIBUTING.md`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c78c86e..46536a7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,9 +14,9 @@ We **love** pull requests! Before [forking the repo](https://help.github.com/en/ For most contributions, after your first pull request is accepted and merged, you will be [invited to the project](https://help.github.com/en/github/setting-up-and-managing-your-github-user-account/inviting-collaborators-to-a-personal-repository) and given **push access**. :tada: -*Note: All contributions will be licensed under the project's license.* +_Note: All contributions will be licensed under the project's license._ -- **Smaller is better.** Submit **one** pull request per bug fix or feature. A pull request should contain isolated changes pertaining to a single bug fix or feature implementation. **Do not** refactor or reformat code that is unrelated to your change. It is better to **submit many small pull requests** rather than a single large one. Enormous pull requests will take enormous amounts of time to review, or may be rejected altogether. +- **Smaller is better.** Submit **one** pull request per bug fix or feature. A pull request should contain isolated changes pertaining to a single bug fix or feature implementation. **Do not** refactor or reformat code that is unrelated to your change. It is better to **submit many small pull requests** rather than a single large one. Enormous pull requests will take enormous amounts of time to review, or may be rejected altogether. - **Coordinate bigger changes.** For large and non-trivial changes, open an issue to discuss a strategy with the maintainers. Otherwise, you risk doing a lot of work for nothing! @@ -30,9 +30,9 @@ For most contributions, after your first pull request is accepted and merged, yo - **[Resolve any merge conflicts](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github)** that occur. -- **Keep PR in Draft** until ready for review. When PR ready for review assign PR to ourself and assing at least one reviewer +- **Keep PR in Draft** until ready for review. When it is ready, assign the PR to yourself and request at least one reviewer. -- **Promptly address any CI failures**. If your pull request fails to build or pass tests, please push another commit to fix it. +- **Promptly address any CI failures**. If your pull request fails to build or pass tests, please push another commit to fix it. - When writing comments, use properly constructed sentences, including punctuation. @@ -44,32 +44,32 @@ Please [write a great commit message](https://chris.beams.io/posts/git-commit/). 1. Separate subject from body with a blank line 1. Limit the subject line to 50 characters -1. Capitalize the subject line -1. Add [Draft] prefix for PR not ready for review +1. Use sentence case (capitalize the first word) 1. Do not end the subject line with a period 1. Use the imperative mood in the subject line (example: "Fix networking issue") 1. Wrap the body at about 72 characters -1. Use the body to explain **why**, *not what and how* (the code shows that!) -1. If applicable, prefix the title with the relevant component name. (examples: "[Docs] Fix typo", "[Profile] Fix missing avatar") +1. Use the body to explain **why**, _not what and how_ (the code shows that!) +1. Do not use semantic prefixes or tags (examples: `fix:`, `feat:`, `[Docs]`) +1. Keep PR state out of commit messages; use GitHub Draft PRs instead ``` -[TAG] Short summary of changes in 50 chars or less +Short summary of changes in 50 chars or less -Add a more detailed explanation here, if necessary. Possibly give -some background about the issue being fixed, etc. The body of the -commit message can be several paragraphs. Further paragraphs come +Add a more detailed explanation here, if necessary. Possibly give +some background about the issue being fixed, etc. The body of the +commit message can be several paragraphs. Further paragraphs come after blank lines and please do proper word-wrap. -Wrap it to about 72 characters or so. In some contexts, -the first line is treated as the subject of the commit and the -rest of the text as the body. The blank line separating the summary -from the body is critical (unless you omit the body entirely); -various tools like `log`, `shortlog` and `rebase` can get confused +Wrap it to about 72 characters or so. In some contexts, +the first line is treated as the subject of the commit and the +rest of the text as the body. The blank line separating the summary +from the body is critical (unless you omit the body entirely); +various tools like `log`, `shortlog` and `rebase` can get confused if you run the two together. Explain the problem that this commit is solving. Focus on why you -are making this change as opposed to how or what. The code explains -how or what. Reviewers and your future self can read the patch, +are making this change as opposed to how or what. The code explains +how or what. Reviewers and your future self can read the patch, but might not understand why a particular solution was implemented. Are there side effects or other unintuitive consequences of this change? Here's the place to explain them. @@ -93,33 +93,32 @@ See also: #456, #789 - **Always do your best.** No one writes bugs on purpose. Do your best, and learn from your mistakes. -- Kindly note any violations to the guidelines specified in this document. +- Kindly note any violations to the guidelines specified in this document. -- **Use CREG (Code Review Emoji Guide)** to give the reviewee added context and clarity to follow up on code review. +- **Use CREG (Code Review Emoji Guide)** to give the reviewee added context and clarity to follow up on code review. ### Emoji Legend -| | `:code:` | Meaning | -| :-: | :----------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| πŸ˜ƒπŸ‘πŸ’― | `:smiley:` `:+1:` `:100:` | I like this...

...and I want the author to know it! This is a way to highlight positive parts of a code review. | -| πŸ”§ | `:wrench:` | I think this needs to be changed.

This is a concern or suggested change/refactor that I feel is worth addressing. | -| ❓ | `:question:` | I have a question.

This should be a fully formed question with sufficient information and context that requires a response. | -| πŸ€”πŸ’­ | `:thinking:` `:thought_balloon:` | Let me think out loud here for a minute.

I might express concern, suggest an alternative solution, or walk through the code in my own words to make sure I understand. | -| 🌱 | `:seedling:` | Planting a seed for future.

An observation or suggestion that is not a change request, but may have larger implications. Generally something to keep in mind for the future. | -| πŸ“ | `:memo:` | This is an explanatory note, fun fact, or relevant commentary that does not require any action. | -| ⛏ | `:pick:` | This is a nitpick.

This does not require any changes and is often better left unsaid. This may include stylistic, formatting, or organization suggestions and should likely be prevented/enforced by linting if they really matter | -| ♻️ | `:recycle:` | Suggestion for refactoring.

Should include enough context to be actionable and not be considered a nitpick. | -| πŸ• | `:camping:` | Here is an opportunity, not directly related to your changes, for us to leave the campground [code] cleaner than we found it. | -| πŸ“Œ | `:pushpin:` | This is a concern that is _out of scope_ and should be staged appropriately for follow up. | - +| | `:code:` | Meaning | +| :----: | :------------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| πŸ˜ƒπŸ‘πŸ’― | `:smiley:` `:+1:` `:100:` | I like this...

...and I want the author to know it! This is a way to highlight positive parts of a code review. | +| πŸ”§ | `:wrench:` | I think this needs to be changed.

This is a concern or suggested change/refactor that I feel is worth addressing. | +| ❓ | `:question:` | I have a question.

This should be a fully formed question with sufficient information and context that requires a response. | +| πŸ€”πŸ’­ | `:thinking:` `:thought_balloon:` | Let me think out loud here for a minute.

I might express concern, suggest an alternative solution, or walk through the code in my own words to make sure I understand. | +| 🌱 | `:seedling:` | Planting a seed for future.

An observation or suggestion that is not a change request, but may have larger implications. Generally something to keep in mind for the future. | +| πŸ“ | `:memo:` | This is an explanatory note, fun fact, or relevant commentary that does not require any action. | +| ⛏ | `:pick:` | This is a nitpick.

This does not require any changes and is often better left unsaid. This may include stylistic, formatting, or organization suggestions and should likely be prevented/enforced by linting if they really matter | +| ♻️ | `:recycle:` | Suggestion for refactoring.

Should include enough context to be actionable and not be considered a nitpick. | +| πŸ• | `:camping:` | Here is an opportunity, not directly related to your changes, for us to leave the campground [code] cleaner than we found it. | +| πŸ“Œ | `:pushpin:` | This is a concern that is _out of scope_ and should be staged appropriately for follow up. | ## :nail_care: Coding Style Consistency is the most important. Following the existing Rust style, formatting, and naming conventions of the file you are modifying and of the overall project. Failure to do so will result in a prolonged review process that has to focus on updating the superficial aspects of your code, rather than improving its functionality and performance. -Style and format will be enforced with a linter when PR is crated. +Style and format will be enforced with a linter when the PR is created. ## :pray: Credits - https://github.com/jessesquires/.github/blob/main/CONTRIBUTING.md -- https://github.com/erikthedeveloper/code-review-emoji-guide \ No newline at end of file +- https://github.com/erikthedeveloper/code-review-emoji-guide diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md new file mode 100644 index 0000000..f16ebd9 --- /dev/null +++ b/docs/ONBOARDING.md @@ -0,0 +1,643 @@ +# New Engineer Onboarding Guide + +Welcome to the Trusted Server project! This guide will help you get up to speed quickly and start contributing effectively. + +## Table of Contents + +1. [Project Overview](#project-overview) +2. [Architecture at a Glance](#architecture-at-a-glance) +3. [Development Environment Setup](#development-environment-setup) +4. [Codebase Structure](#codebase-structure) +5. [Key Concepts](#key-concepts) +6. [Development Workflow](#development-workflow) +7. [Testing](#testing) +8. [Common Tasks](#common-tasks) +9. [Debugging & Troubleshooting](#debugging--troubleshooting) +10. [Team & Governance](#team--governance) +11. [Resources & Getting Help](#resources--getting-help) +12. [Onboarding Checklist](#onboarding-checklist) + +--- + +## Project Overview + +### What is Trusted Server? + +Trusted Server is an **open-source, edge computing framework** developed by IAB Tech Lab that moves advertising operations from third-party JavaScript in browsers to secure WebAssembly (WASM) binaries running on edge platforms (currently Fastly Compute). + +### The Problem It Solves + +- **Privacy restrictions**: Browser privacy initiatives (3rd-party cookie deprecation, tracking prevention) are limiting traditional advertising +- **Third-party dependency**: Publishers have little control over third-party scripts running on their pages +- **Performance**: Multiple third-party scripts slow down page load times +- **Data control**: Publishers need better control over how and with whom they share data + +### Key Benefits + +- **First-party context**: Serve ads and assets from the publisher's domain +- **Privacy compliance**: GDPR-compliant with built-in consent management +- **Better performance**: Server-side processing reduces client-side JavaScript +- **Data control**: Publishers control data sharing and user identification + +### Current Status + +This is a **proof of concept (POC)** - not production-ready. The goal is to demonstrate technical feasibility and invite industry collaboration to build toward an MVP. + +--- + +## Architecture at a Glance + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ User's Browser β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Fastly Edge (Trusted Server) β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Request Router (main.rs) β”‚ β”‚ +β”‚ β”‚ β€’ Route matching β”‚ β”‚ +β”‚ β”‚ β€’ Authentication β”‚ β”‚ +β”‚ β”‚ β€’ Handler delegation β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β–Ό β–Ό β–Ό β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Proxy β”‚ β”‚ Publisher β”‚ β”‚ Integrationsβ”‚ β”‚ +β”‚ β”‚ Handlers β”‚ β”‚ Origin β”‚ β”‚ (Prebid, β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ Handler β”‚ β”‚ Lockr, β”‚ β”‚ +β”‚ β”‚ β€’ /first- β”‚ β”‚ β”‚ β”‚ etc.) β”‚ β”‚ +β”‚ β”‚ party/* β”‚ β”‚ β€’ Synthetic β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β€’ Creative β”‚ β”‚ ID inject β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ rewriting β”‚ β”‚ β€’ HTML β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ processingβ”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Storage Layer β”‚ β”‚ +β”‚ β”‚ β€’ KV Stores (counters, domain mappings) β”‚ β”‚ +β”‚ β”‚ β€’ Config Stores (public keys, settings) β”‚ β”‚ +β”‚ β”‚ β€’ Secret Stores (private signing keys) β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β–Ό β–Ό + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Publisher β”‚ β”‚ Ad Server β”‚ + β”‚ Origin β”‚ β”‚ / Prebid β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Technology Stack + +| Layer | Technology | +| -------------- | --------------------------- | +| Language | Rust (1.91.1) | +| Runtime | WebAssembly (wasm32-wasip1) | +| Edge Platform | Fastly Compute | +| Client Library | TypeScript (TSJS) | +| Build Tools | Cargo, Vite | + +--- + +## Development Environment Setup + +### Prerequisites + +Install the following tools (we recommend using `asdf` for version management): + +```bash +# Install asdf (if not already installed) +brew install asdf + +# Add plugins +asdf plugin add rust +asdf plugin add nodejs +asdf plugin add fastly + +# Install required versions (from .tool-versions) +asdf install rust 1.91.1 +asdf install nodejs 24.10.0 +asdf install fastly 13.1.0 + +# Reshim to ensure binaries are available +asdf reshim + +# Add the WASM target for Fastly builds +rustup target add wasm32-wasip1 +``` + +**Configure your shell PATH** (required for asdf to work): + +For **Bash** (`~/.bash_profile`): + +```bash +export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH" +``` + +For **Zsh** (`~/.zshrc`): + +```bash +export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH" +``` + +Then restart your terminal or run `source ~/.zshrc` (or `~/.bash_profile`). + +### Clone and Build + +```bash +# Clone the repository +git clone git@github.com:IABTechLab/trusted-server.git +cd trusted-server + +# Build the Rust project +cargo build + +# Install viceroy (Fastly local simulator) for testing +cargo install viceroy + +# Run Rust tests to verify setup +cargo test + +# Build the TypeScript client library (TSJS) +cd crates/js/lib +npm install +npm run build +npm test +cd ../../.. +``` + +### IDE Setup + +We recommend **VS Code** with these extensions: + +- rust-analyzer (Rust language support) +- Even Better TOML (TOML file support) +- CodeLLDB (debugging) + +--- + +## Codebase Structure + +``` +trusted-server/ +β”œβ”€β”€ crates/ # Rust workspace +β”‚ β”œβ”€β”€ common/ # Core library (shared code) +β”‚ β”‚ └── src/ +β”‚ β”‚ β”œβ”€β”€ proxy.rs # First-party proxy handlers +β”‚ β”‚ β”œβ”€β”€ publisher.rs # Publisher origin handling +β”‚ β”‚ β”œβ”€β”€ creative.rs # HTML/creative rewriting +β”‚ β”‚ β”œβ”€β”€ synthetic.rs # Synthetic ID generation +β”‚ β”‚ β”œβ”€β”€ settings.rs # Configuration management +β”‚ β”‚ β”œβ”€β”€ integrations/ # Partner integrations +β”‚ β”‚ β”‚ β”œβ”€β”€ prebid.rs # Prebid Server RTB +β”‚ β”‚ β”‚ β”œβ”€β”€ lockr.rs # Lockr ID solution +β”‚ β”‚ β”‚ └── ... +β”‚ β”‚ └── request_signing/ # Ed25519 signing +β”‚ β”‚ +β”‚ β”œβ”€β”€ fastly/ # Fastly-specific implementation +β”‚ β”‚ └── src/ +β”‚ β”‚ └── main.rs # Entry point & routing +β”‚ β”‚ +β”‚ └── js/ # TypeScript client library (TSJS) +β”‚ └── src/ +β”‚ +β”œβ”€β”€ docs/ # VitePress documentation +β”œβ”€β”€ static/ # Static assets +β”‚ +β”œβ”€β”€ Cargo.toml # Workspace manifest +β”œβ”€β”€ fastly.toml # Fastly service config +β”œβ”€β”€ trusted-server.toml # Application settings +β”œβ”€β”€ rust-toolchain.toml # Pinned Rust version +└── .tool-versions # Tool versions (asdf) +``` + +### Key Files to Understand First + +| File | Purpose | +| ------------------------------------------------------------------------------------------- | ----------------------------------------- | +| [crates/fastly/src/main.rs](../crates/fastly/src/main.rs) | Request routing entry point - start here! | +| [crates/common/src/publisher.rs](../crates/common/src/publisher.rs) | Publisher origin handling | +| [crates/common/src/proxy.rs](../crates/common/src/proxy.rs) | First-party proxy implementation | +| [crates/common/src/synthetic.rs](../crates/common/src/synthetic.rs) | Synthetic ID generation | +| [crates/common/src/integrations/registry.rs](../crates/common/src/integrations/registry.rs) | Integration module pattern | +| [trusted-server.toml](../trusted-server.toml) | Application configuration | + +--- + +## Key Concepts + +### 1. First-Party Proxying + +Instead of loading ad creatives directly from third-party domains, Trusted Server proxies them through first-party endpoints: + +``` +Before: Browser β†’ ad-server.com/creative.html +After: Browser β†’ publisher.com/first-party/proxy?tsurl=ad-server.com/creative.html +``` + +This keeps all requests under the publisher's domain, avoiding third-party cookie restrictions. + +### 2. Synthetic ID Generation + +Privacy-preserving user identification using HMAC-SHA256: + +```rust +// Configurable template combining signals +template: "{{ip}}-{{user_agent}}-{{secret}}" + +// Produces deterministic, non-reversible ID +synthetic_id: "a1b2c3d4e5f6..." +``` + +The ID is: + +- Deterministic (same inputs = same output) +- Non-reversible (can't extract original signals) +- Publisher-controlled (configurable template) + +### 3. Integration Modules + +Extensible pattern for adding new partners (ad servers, ID solutions, consent providers): + +```rust +// Each integration implements standard traits +pub struct PrebidIntegration { ... } + +impl Integration for PrebidIntegration { + fn handle_request(&self, req: Request) -> Response { ... } +} +``` + +### 4. Request Signing + +Ed25519 cryptographic signing for authenticated API requests: + +- Public keys published at `/.well-known/trusted-server.json` +- Key rotation supported with graceful transitions +- Used for OpenRTB bid requests + +--- + +## Development Workflow + +### Building + +```bash +# Development build +cargo build + +# Production WASM build +cargo build --bin trusted-server-fastly --release --target wasm32-wasip1 +``` + +### Running Locally + +```bash +# Load environment variables +set -a +source .env.dev +set +a + +# Use the shared origin for local testing +export TRUSTED_SERVER__PUBLISHER__ORIGIN_URL=https://origin.getpurpose.ai + +# Start local Fastly simulator +fastly compute serve + +# Server runs at http://127.0.0.1:7676 +``` + +### Local Origin Stub and Smoke Test + +If you want a fully local origin instead of `origin.getpurpose.ai`, set the origin URL to `http://localhost:9090` and use this stub to validate a first-party proxy flow end-to-end. + +```bash +# Terminal 1: start a simple origin server on port 9090 +export TRUSTED_SERVER__PUBLISHER__ORIGIN_URL=http://localhost:9090 +mkdir -p /tmp/ts-origin +printf 'hello from origin\n' > /tmp/ts-origin/hello.txt +python3 -m http.server 9090 --directory /tmp/ts-origin +``` + +```bash +# Terminal 2: with `fastly compute serve` running, sign and proxy the asset +signed_path=$( + curl -s "http://127.0.0.1:7676/first-party/sign?url=http://localhost:9090/hello.txt" \ + | python3 - <<'PY' +import json, sys +print(json.load(sys.stdin)["href"]) +PY +) +curl -i "http://127.0.0.1:7676${signed_path}" +``` + +You should see `hello from origin` in the response body. + +### Code Quality + +Before committing, always run: + +```bash +# Format code +cargo fmt + +# Lint with clippy +cargo clippy --all-targets --all-features --workspace --no-deps + +# Run tests +cargo test +``` + +### Making Changes + +1. Create a feature branch from `main` +2. Make your changes +3. Run `cargo fmt`, `cargo clippy`, and `cargo test` +4. Commit using the guidelines in [CONTRIBUTING.md](../CONTRIBUTING.md#memo-writing-commit-messages) +5. Open a Pull Request + +### Commit Message Format + +Follow the guidelines in [CONTRIBUTING.md](../CONTRIBUTING.md#memo-writing-commit-messages). In short: + +- Use sentence case and imperative mood +- Do not use semantic prefixes or bracketed tags (examples: `fix:`, `[Docs]`) +- Keep PR state out of commit messages; use GitHub Draft PRs instead + +``` +Short summary in 50 chars or less + +Optional longer description explaining the "why" +not the "what" (the code shows that). + +Resolves: #123 +``` + +--- + +## Testing + +### Running Tests + +```bash +# Run all Rust tests +cargo test + +# Run with more details (useful when tests fail) +cargo test -- --nocapture + +# Run TypeScript tests +cd crates/js/lib && npm test +``` + +### Writing Tests + +Tests live alongside source code in `#[cfg(test)]` modules: + +```rust +// src/synthetic.rs + +pub fn generate_id(template: &str) -> String { + // implementation +} + +#[cfg(test)] +mod tests { + use super::generate_id; + + #[test_log::test] + fn generates_id_for_template() { + let id = generate_id("test-template"); + assert!(!id.is_empty(), "should generate a non-empty ID"); + } +} +``` + +### Local Integration Testing + +Use the Fastly local simulator (viceroy) to test full request flows: + +```bash +fastly compute serve +# Then make requests to http://127.0.0.1:7676 +``` + +--- + +## Common Tasks + +### Adding a New Integration + +1. Create a new file in `crates/common/src/integrations/` +2. Implement the integration trait +3. Register in `registry.rs` +4. Add configuration in `trusted-server.toml` +5. Write tests + +See [testlight.rs](../crates/common/src/integrations/testlight.rs) for an example. + +### Modifying Request Routing + +Edit [crates/fastly/src/main.rs](../crates/fastly/src/main.rs) to add new routes or modify existing ones. + +### Updating Configuration + +1. Add new settings to `crates/common/src/settings.rs` +2. Update `trusted-server.toml` with defaults +3. Document the new setting + +### Deploying to Fastly + +```bash +# Build and publish +fastly compute publish + +# Or build separately +cargo build --bin trusted-server-fastly --release --target wasm32-wasip1 +fastly compute publish --package pkg/trusted-server-fastly.tar.gz +``` + +--- + +## Debugging & Troubleshooting + +### Viewing Logs Locally + +When running with `fastly compute serve`, logs are printed to stdout. Use the `log` macros in Rust: + +```rust +use log::{debug, error, info, warn}; + +info!("Processing request for path: {}", path); +debug!("Request headers: {:?}", headers); +``` + +### Common Issues + +| Issue | Solution | +| ------------------------------------- | -------------------------------------------------------------- | +| `cargo test` fails with viceroy error | Run `cargo install viceroy` to install/update the test runtime | +| `asdf` commands not found | Ensure PATH is configured (see Prerequisites section) | +| `fastly compute serve` fails | Check that `.env.dev` exists and `fastly.toml` is configured | +| TypeScript build fails | Run `npm install` in `crates/js/lib` first | +| Tests pass locally but fail in CI | Ensure `cargo fmt` and `cargo clippy` pass without warnings | + +### Debugging Tips + +- Use `cargo test -- --nocapture` to see println/log output during tests +- For failed tests, viceroy doesn't show line numbers - check test output carefully +- Use `RUST_LOG=debug fastly compute serve` for verbose logging locally +- Check `.env.dev` for environment variable overrides + +--- + +## Team & Governance + +### Project Structure + +The project follows IAB Tech Lab's open-source governance model: + +- **Trusted Server Task Force**: Defines requirements and roadmap (meets biweekly) +- **Development Team**: Handles engineering implementation and releases + +### Team Roles + +| Role | Responsibility | +| ----------------------- | ----------------------------------------------------- | +| Project Release Manager | Overall project development, write access to repo | +| Committer | Implements final changes, write access to repo | +| Developer | Contributes code/docs, may take on project management | + +See [ProjectGovernance.md](../ProjectGovernance.md) for full details. + +### Key Contacts + + + +| Role | GitHub Handle | +| ------------ | ------------------------------------------------------------ | +| Project Lead | [@jevansnyc](https://github.com/jevansnyc) | +| Engineer | [@aram356](https://github.com/aram356) | +| Engineer | [@ChristianPavilonis](https://github.com/ChristianPavilonis) | + +### Meetings + + + +- **Task Force Meeting**: Biweekly (check calendar for schedule) +- **Development Team Standup**: Weekly (check calendar for schedule) + +Ask your manager or onboarding buddy for calendar invites to relevant meetings. + +--- + +## Resources & Getting Help + +### Documentation + +| Resource | Description | +| ------------------------------------- | --------------------------------------------- | +| [README.md](../README.md) | Project overview and setup | +| [CONTRIBUTING.md](../CONTRIBUTING.md) | Contribution guidelines | +| [AGENTS.md](../AGENTS.md) | AI assistant guidance / architecture overview | +| [SEQUENCE.md](../SEQUENCE.md) | Request flow diagrams | +| [FAQ_POC.md](../FAQ_POC.md) | Frequently asked questions | + +### VitePress Documentation Site + +The `docs/` folder contains a full documentation site with detailed guides: + +To run the docs site locally: + +```bash +cd docs +npm install +npm run dev +``` + +See [docs/README.md](README.md) for deployment details. + +| Guide | Description | +| ----------------------------------------------- | -------------------------------- | +| [Getting Started](guide/getting-started.md) | Quick start guide | +| [Architecture](guide/architecture.md) | System architecture overview | +| [Configuration](guide/configuration.md) | Configuration options | +| [Synthetic IDs](guide/synthetic-ids.md) | Privacy-preserving ID generation | +| [First-Party Proxy](guide/first-party-proxy.md) | Proxy endpoint documentation | +| [Request Signing](guide/request-signing.md) | Ed25519 signing setup | +| [GDPR Compliance](guide/gdpr-compliance.md) | Privacy and consent handling | + +### Integration Guides + +| Integration | Description | +| -------------------------------------------- | ----------------------------- | +| [Prebid](guide/integrations/prebid.md) | Prebid Server RTB integration | +| [Lockr](guide/integrations/lockr.md) | Lockr ID solution | +| [Didomi](guide/integrations/didomi.md) | Didomi consent management | +| [Permutive](guide/integrations/permutive.md) | Permutive audience segments | +| [Next.js](guide/integrations/nextjs.md) | Next.js RSC integration | +| [GAM](guide/integrations/gam.md) | Google Ad Manager | +| [APS](guide/integrations/aps.md) | Amazon Publisher Services | + +### Coding Standards + +Review the coding standards in `.agents/rules/`: + +- `rust-coding-style.mdc` - Naming, organization, patterns +- `rust-error-handling.mdc` - Error handling patterns +- `rust-testing-strategy.mdc` - Testing approach +- `git-commit-conventions.mdc` - Commit message format + +### Getting Help + +- **GitHub Issues**: For bugs, feature requests, and questions +- **Task Force Meetings**: Biweekly meetings for roadmap discussions +- **Code Review**: Submit PRs for feedback from maintainers + +### External Resources + +- [Fastly Compute Documentation](https://developer.fastly.com/learning/compute/) +- [Rust Book](https://doc.rust-lang.org/book/) +- [WebAssembly Overview](https://webassembly.org/) +- [OpenRTB Specification](https://iabtechlab.com/standards/openrtb/) + +--- + +## Onboarding Checklist + +Use this checklist to track your onboarding progress: + +### Access & Accounts + +- [ ] Get GitHub access to [IABTechLab/trusted-server](https://github.com/IABTechLab/trusted-server) +- [ ] Get access to the [Trusted Server project board](https://github.com/orgs/IABTechLab/projects/3) +- [ ] Create a [Fastly account](https://manage.fastly.com) and obtain an API token +- [ ] Join the Slack workspace and `#trusted-server` channel +- [ ] Get calendar invites for Task Force and Development Team meetings + +### Environment Setup + +- [ ] Clone the repository and build successfully +- [ ] Run tests locally (`cargo test`) +- [ ] Start the local server (`fastly compute serve`) + +### Codebase Exploration + +- [ ] Read through `main.rs` to understand request routing +- [ ] Trace a request through `publisher.rs` and `proxy.rs` +- [ ] Understand synthetic ID generation in `synthetic.rs` +- [ ] Review an existing integration (e.g., `prebid.rs`) + +### Documentation & Contribution + +- [ ] Read `CONTRIBUTING.md` for PR guidelines +- [ ] Browse the [documentation site guides](guide/index.md) +- [ ] Make a small contribution (fix a typo, add a test, etc.) + +--- + +Welcome aboard! Don't hesitate to ask questions - we're here to help you succeed. diff --git a/fastly.toml b/fastly.toml index a80fea4..0a41bb3 100644 --- a/fastly.toml +++ b/fastly.toml @@ -19,8 +19,6 @@ build = """ [local_server] address = "127.0.0.1:7676" - tls_cert_path = "./localhost+2.pem" - tls_key_path = "./localhost+2-key.pem" [local_server.backends] From 04e871a5e112a3770eb27e13cebbae5f44368b3c Mon Sep 17 00:00:00 2001 From: Aram Grigoryan <132480+aram356@users.noreply.github.com> Date: Tue, 20 Jan 2026 10:16:55 -0800 Subject: [PATCH 2/4] Clarify roles --- docs/ONBOARDING.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md index f16ebd9..552ca14 100644 --- a/docs/ONBOARDING.md +++ b/docs/ONBOARDING.md @@ -506,11 +506,10 @@ The project follows IAB Tech Lab's open-source governance model: ### Team Roles -| Role | Responsibility | -| ----------------------- | ----------------------------------------------------- | -| Project Release Manager | Overall project development, write access to repo | -| Committer | Implements final changes, write access to repo | -| Developer | Contributes code/docs, may take on project management | +| Role | Responsibility | +| ------------ | ------------------------------------ | +| Project Lead | Overall project vision and direction | +| Developer | Contributes code/docs | See [ProjectGovernance.md](../ProjectGovernance.md) for full details. @@ -521,8 +520,8 @@ See [ProjectGovernance.md](../ProjectGovernance.md) for full details. | Role | GitHub Handle | | ------------ | ------------------------------------------------------------ | | Project Lead | [@jevansnyc](https://github.com/jevansnyc) | -| Engineer | [@aram356](https://github.com/aram356) | -| Engineer | [@ChristianPavilonis](https://github.com/ChristianPavilonis) | +| Developer | [@aram356](https://github.com/aram356) | +| Developer | [@ChristianPavilonis](https://github.com/ChristianPavilonis) | ### Meetings From 5dd460fa0cadcb21ed408a86c1b01781f4dcca35 Mon Sep 17 00:00:00 2001 From: prk-Jr Date: Wed, 21 Jan 2026 00:19:21 +0530 Subject: [PATCH 3/4] Correct Slack channel name in ONBOARDING.md --- docs/ONBOARDING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md index 552ca14..e80523d 100644 --- a/docs/ONBOARDING.md +++ b/docs/ONBOARDING.md @@ -615,7 +615,7 @@ Use this checklist to track your onboarding progress: - [ ] Get GitHub access to [IABTechLab/trusted-server](https://github.com/IABTechLab/trusted-server) - [ ] Get access to the [Trusted Server project board](https://github.com/orgs/IABTechLab/projects/3) - [ ] Create a [Fastly account](https://manage.fastly.com) and obtain an API token -- [ ] Join the Slack workspace and `#trusted-server` channel +- [ ] Join the Slack workspace and `#trusted-server-internal` channel - [ ] Get calendar invites for Task Force and Development Team meetings ### Environment Setup From a2bbca2717720fbeb9a5dded1f376cf006b3bdeb Mon Sep 17 00:00:00 2001 From: prk-Jr Date: Wed, 21 Jan 2026 16:16:04 +0530 Subject: [PATCH 4/4] Fix broken documentation link in onboarding checklist The link to guide/index.md was pointing to an empty file. Updated to point to guide/getting-started.md which has actual content. --- docs/ONBOARDING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md index e80523d..9dbefc2 100644 --- a/docs/ONBOARDING.md +++ b/docs/ONBOARDING.md @@ -634,7 +634,7 @@ Use this checklist to track your onboarding progress: ### Documentation & Contribution - [ ] Read `CONTRIBUTING.md` for PR guidelines -- [ ] Browse the [documentation site guides](guide/index.md) +- [ ] Browse the [documentation site guides](guide/getting-started.md) - [ ] Make a small contribution (fix a typo, add a test, etc.) ---