Skip to content

Commit 378ffa5

Browse files
ChristianPavilonisChristianPavilonis
committed
basic docs site setup with some ai docs
1 parent 68ebba4 commit 378ffa5

19 files changed

+4337
-0
lines changed

‎.github/workflows/deploy-docs.yml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
name: Deploy VitePress Docs
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
- '.github/workflows/deploy-docs.yml'
9+
workflow_dispatch: # Allow manual triggers
10+
11+
# Sets permissions for GitHub Pages deployment
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
# Prevent concurrent deployments
18+
concurrency:
19+
group: pages
20+
cancel-in-progress: false
21+
22+
jobs:
23+
build:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 0 # For lastUpdated feature
30+
31+
- name: Retrieve Node.js version
32+
id: node-version
33+
run: echo "node-version=$(grep '^nodejs ' .tool-versions | awk '{print $2}')" >> $GITHUB_OUTPUT
34+
35+
- name: Setup Node.js
36+
uses: actions/setup-node@v4
37+
with:
38+
node-version: ${{ steps.node-version.outputs.node-version }}
39+
cache: 'npm'
40+
cache-dependency-path: docs/package-lock.json
41+
42+
- name: Setup Pages
43+
uses: actions/configure-pages@v4
44+
45+
- name: Install dependencies
46+
working-directory: docs
47+
run: npm ci
48+
49+
- name: Build with VitePress
50+
working-directory: docs
51+
run: npm run build
52+
53+
- name: Upload artifact
54+
uses: actions/upload-pages-artifact@v3
55+
with:
56+
path: docs/.vitepress/dist
57+
58+
deploy:
59+
environment:
60+
name: github-pages
61+
url: ${{ steps.deployment.outputs.page_url }}
62+
needs: build
63+
runs-on: ubuntu-latest
64+
steps:
65+
- name: Deploy to GitHub Pages
66+
id: deployment
67+
uses: actions/deploy-pages@v4

‎docs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules
2+
.vitepress/dist
3+
.vitepress/cache

‎docs/.vitepress/config.mts‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
// https://vitepress.dev/reference/site-config
4+
export default defineConfig({
5+
title: "Trusted Server",
6+
description: "Privacy-preserving edge computing for ad serving and synthetic ID generation",
7+
themeConfig: {
8+
// https://vitepress.dev/reference/default-theme-config
9+
nav: [
10+
{ text: 'Home', link: '/' },
11+
{ text: 'Guide', link: '/guide/getting-started' },
12+
],
13+
14+
sidebar: [
15+
{
16+
text: 'Introduction',
17+
items: [
18+
{ text: 'What is Trusted Server?', link: '/guide/what-is-trusted-server' },
19+
{ text: 'Getting Started', link: '/guide/getting-started' }
20+
]
21+
},
22+
{
23+
text: 'Core Concepts',
24+
items: [
25+
{ text: 'Synthetic IDs', link: '/guide/synthetic-ids' },
26+
{ text: 'GDPR Compliance', link: '/guide/gdpr-compliance' },
27+
{ text: 'Ad Serving', link: '/guide/ad-serving' }
28+
]
29+
},
30+
{
31+
text: 'Security',
32+
items: [
33+
{ text: 'Request Signing', link: '/guide/request-signing' },
34+
{ text: 'Key Rotation', link: '/guide/key-rotation' }
35+
]
36+
},
37+
{
38+
text: 'Development',
39+
items: [
40+
{ text: 'Architecture', link: '/guide/architecture' },
41+
{ text: 'Configuration', link: '/guide/configuration' },
42+
{ text: 'Testing', link: '/guide/testing' }
43+
]
44+
}
45+
],
46+
47+
socialLinks: [
48+
{ icon: 'github', link: 'https://github.com/IABTechLab/trusted-server' }
49+
],
50+
51+
footer: {
52+
message: 'Released under the Apache License 2.0.',
53+
copyright: 'Copyright © 2018-present IAB Technology Laboratory'
54+
}
55+
}
56+
})

‎docs/guide/ad-serving.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Ad Serving
2+
3+
Learn how Trusted Server handles privacy-compliant ad serving.
4+
5+
## Overview
6+
7+
Trusted Server provides edge-based ad serving with built-in GDPR compliance and real-time bidding support.
8+
9+
## Supported Integrations
10+
11+
### Equativ
12+
13+
Primary ad server integration with support for:
14+
- Direct ad requests
15+
- Creative proxying
16+
- Click tracking
17+
- Impression tracking
18+
19+
### Prebid
20+
21+
Real-time bidding integration:
22+
- Header bidding support
23+
- Bid caching
24+
- Timeout management
25+
- Winner selection
26+
27+
## Ad Request Flow
28+
29+
1. Request validation
30+
2. GDPR consent check
31+
3. Synthetic ID generation (if consented)
32+
4. Ad server request
33+
5. Response processing
34+
6. Creative delivery
35+
36+
## Configuration
37+
38+
Configure ad servers in `trusted-server.toml`:
39+
40+
```toml
41+
[ad_servers.equativ]
42+
endpoint = "https://ad-server.example.com"
43+
timeout_ms = 1000
44+
enabled = true
45+
46+
[prebid]
47+
timeout_ms = 1500
48+
cache_ttl = 300
49+
```
50+
51+
## Creative Handling
52+
53+
### Proxy Mode
54+
55+
Creatives can be proxied through Trusted Server for:
56+
- Security scanning
57+
- Content modification
58+
- Click tracking injection
59+
- GDPR compliance
60+
61+
### Direct Mode
62+
63+
Creatives served directly from ad server:
64+
- Lower latency
65+
- Reduced edge load
66+
- Less control over content
67+
68+
## Tracking
69+
70+
### Impression Tracking
71+
72+
```javascript
73+
// Placeholder example
74+
trustedServer.trackImpression({
75+
adId: 'ad-123',
76+
syntheticId: 'synthetic-xyz',
77+
consent: true
78+
});
79+
```
80+
81+
### Click Tracking
82+
83+
Click tracking with privacy preservation:
84+
- No PII in URLs
85+
- Synthetic ID only (with consent)
86+
- Encrypted parameters
87+
88+
## Performance
89+
90+
### Edge Caching
91+
92+
- Bid responses cached at edge
93+
- Creative assets cached
94+
- Configuration cached
95+
- Reduced origin requests
96+
97+
### Timeouts
98+
99+
Configurable timeouts for:
100+
- Ad server requests
101+
- Prebid auctions
102+
- Creative fetching
103+
104+
## Best Practices
105+
106+
1. Set appropriate timeouts for your use case
107+
2. Enable caching for frequently requested ads
108+
3. Monitor ad server response times
109+
4. Use proxy mode for security-sensitive content
110+
5. Implement fallback ads
111+
112+
## Next Steps
113+
114+
- Review [Architecture](/guide/architecture)
115+
- Configure [Testing](/guide/testing)

‎docs/guide/architecture.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Architecture
2+
3+
Understanding the architecture of Trusted Server.
4+
5+
## High-Level Overview
6+
7+
Trusted Server is built as a Rust-based edge computing application that runs on Fastly Compute platform.
8+
9+
```
10+
┌─────────────┐
11+
│ Browser │
12+
└──────┬──────┘
13+
│
14+
▼
15+
┌─────────────────────┐
16+
│ Trusted Server │
17+
│ (Fastly Edge) │
18+
│ ┌───────────────┐ │
19+
│ │ GDPR Check │ │
20+
│ │ Synthetic IDs │ │
21+
│ │ Ad Serving │ │
22+
│ └───────────────┘ │
23+
└──────┬──────────────┘
24+
│
25+
▼
26+
┌─────────────────────┐
27+
│ Ad Servers │
28+
│ KV Stores │
29+
│ External APIs │
30+
└─────────────────────┘
31+
```
32+
33+
## Core Components
34+
35+
### trusted-server-common
36+
37+
Core library containing shared functionality:
38+
- Synthetic ID generation
39+
- Cookie handling
40+
- HTTP abstractions
41+
- GDPR consent management
42+
- Ad server integrations
43+
44+
### trusted-server-fastly
45+
46+
Fastly-specific implementation:
47+
- Main application entry point
48+
- Fastly SDK integration
49+
- Request/response handling
50+
- KV store access
51+
52+
## Design Patterns
53+
54+
### RequestWrapper Trait
55+
56+
Abstracts HTTP request handling to support different backends:
57+
58+
```rust
59+
// Placeholder example
60+
pub trait RequestWrapper {
61+
fn get_header(&self, name: &str) -> Option<String>;
62+
fn get_cookie(&self, name: &str) -> Option<String>;
63+
// ...
64+
}
65+
```
66+
67+
### Settings-Driven Configuration
68+
69+
External configuration via `trusted-server.toml` allows deployment-time customization without code changes.
70+
71+
### Privacy-First Design
72+
73+
All tracking operations require explicit GDPR consent checks before execution.
74+
75+
## Data Flow
76+
77+
1. **Request Ingress** - Request arrives at Fastly edge
78+
2. **Consent Validation** - GDPR consent checked
79+
3. **ID Generation** - Synthetic ID generated (if consented)
80+
4. **Ad Request** - Backend ad server called
81+
5. **Response Processing** - Creative processed and modified
82+
6. **Response Egress** - Response sent to browser
83+
84+
## Storage
85+
86+
### Fastly KV Store
87+
88+
Used for:
89+
- Counter storage
90+
- Domain mappings
91+
- Configuration cache
92+
- Synthetic ID state
93+
94+
### No User Data Persistence
95+
96+
User data is not persisted in storage - only processed in-flight at the edge.
97+
98+
## Performance Characteristics
99+
100+
- **Low Latency** - Edge execution near users
101+
- **High Throughput** - Parallel request processing
102+
- **Global Distribution** - Fastly's global network
103+
- **Caching** - Aggressive edge caching
104+
105+
## Security
106+
107+
- **HMAC-based IDs** - Cryptographically secure identifiers
108+
- **No PII Storage** - Privacy by design
109+
- **Request Signing** - Optional request authentication
110+
- **Content Security** - Creative scanning and modification
111+
112+
## WebAssembly Target
113+
114+
Compiled to `wasm32-wasip1` for Fastly Compute:
115+
- Sandboxed execution
116+
- Fast cold starts
117+
- Efficient resource usage
118+
119+
## Next Steps
120+
121+
- Learn about [Configuration](/guide/configuration)
122+
- Set up [Testing](/guide/testing)

0 commit comments

Comments
 (0)