Support per-section GAM ad unit paths via gam_unit_path templates

[prk-Jr]

Summary

• creative_opportunities.slot.gam_unit_path is now a template with {network_id}, {section}, and {slot_id} placeholders, so a publisher whose GAM ad unit varies by site section expresses that in one slot rule instead of one rule per (slot × section).
• {section} is derived from the request path (first segment, sanitized), with a required section_root for / — the URL→section convention lives in config, not core.
• Server-only change: gam_unit_path reaches googletag.defineSlot client-side but is not in the OpenRTB request, so the wire shape is unchanged and there is no JS change.

Changes

File	Change
crates/trusted-server-core/src/creative_opportunities.rs	Add UnitTemplatePart, parse_unit_template, sanitize_section, derive_section; slot compiled_unit cache + compile_unit_template/render_gam_unit_path/template_uses_section; config section_root + compile_unit_templates; validate_runtime now enforces section_root when {section} is used and drops the render-time emptiness check
crates/trusted-server-core/src/publisher.rs	build_slot_json/build_ad_slots_script take request_path; render the template on both the initial-render and handle_page_bids (SPA) paths
crates/trusted-server-core/src/settings.rs	prepare_runtime parses templates via compile_unit_templates before validation, surfacing parse errors as Configuration errors
docs/guide/configuration.md	New "Creative Opportunities Configuration" section documenting templating, {section} derivation, the no-decode rule, and unmatched-route behavior
trusted-server.example.toml	Document section_root and a templated-slot example
docs/superpowers/specs/, docs/superpowers/plans/	Design spec and implementation plan

Closes

Closes#954

Test plan

• cargo test-fastly && cargo test-axum (also test-cloudflare, test-spin — all pass)
• cargo fmt --all -- --check
• cargo clippy-fastly (remaining clippy targets left to CI)
• Docs format: cd docs && npm run format
• JS tests / JS format — no JS change in this PR; left to CI
• clippy-axum / clippy-cloudflare* / clippy-spin* — left to CI

New tests: template parsing (unknown placeholder, unmatched/nested brace, empty), section derivation (/, single/multi-segment, unsafe/undecoded segment new%20s → new_20s), render_gam_unit_path (template, default, verbatim), startup validation (missing/invalid section_root, parse error), and initial-render/SPA equivalence for the same path.

Hardening note

Template parsing and section_root validation are config-derived and run at startup in Settings::prepare_runtime. Invalid enabled config fails startup via Report<TrustedServerError::Configuration> — no panic!, unwrap(), or expect() on the config path. compile_unit_templates rejects malformed templates (unknown placeholder, unmatched/nested brace, empty); validate_runtime rejects a {section} template with a missing or non-[A-Za-z0-9_-]section_root. Regression coverage: compile_unit_templates_surfaces_parse_error, validate_runtime_requires_section_root_when_template_uses_section, validate_runtime_rejects_invalid_section_root, and settings_rejects_creative_opportunity_slot_with_empty_gam_unit_path. Existing static gam_unit_path configs are unaffected (verbatim when no placeholders; /{network_id}/{slot_id} when absent).

Checklist

• Changes follow CLAUDE.md conventions
• No unwrap() in production code — use expect("should ...")
• Uses log macros (not println!)
• New code has tests
• No secrets or credentials committed

[ChristianPavilonis]

Summary

The implementation is generally well-tested and CI is green, but the current change has important configuration-compatibility and inventory-routing risks. In particular, config blobs can break deployment rollback, the template cache can silently discard explicit GAM paths outside the finalized-settings path, and the section derivation policy remains hardcoded despite the originating requirement.

[ChristianPavilonis]

Summary

Reviewed the current head after the previous feedback round. The request-path threading, parser, sanitization, initial/SPA consistency, and prior fixes are generally sound, and CI is green. I found one high rollback-compatibility risk, two medium correctness/resource risks, and one low documentation inconsistency; details are inline.

[aram356]

Summary

Reviewed the current head against main. The core design — startup-compiled templates, fail-loud validation, and the raw-path no-decode contract — is sound, and the initial-render and SPA paths cannot diverge: both share build_slot_json, and the SPA path parameter round-trips percent-encoding correctly (encodeURIComponent → form_urlencoded decode) before the same normalization. Two documentation corrections are required (both cheap): the placeholder table still describes pre-section_segment behavior, and the rollback note affirmatively claims a clean rollback for configs that would silently render placeholder braces literally on an older binary. Six non-blocking suggestions are inline.

CI Status

• fmt: PASS
• clippy (all targets): PASS
• rust tests (fastly/axum/cloudflare/spin/parity/CLI): PASS
• js tests (vitest): PASS
• integration + browser tests, CodeQL: PASS

[aram356]

Summary

Re-reviewed the head after the previous feedback round. All prior findings are addressed with regression tests: the rollback marker (section_segment materialized during typed/startup finalization) is verified against the actual ts config push path (TrustedServerAppConfig deserialize → finalize_deserialized → prepare_runtime → compile_unit_templates) and pinned by the legacy-schema tests; network-id validation is scoped to consumption; dynamic rendering is byte-bounded with startup validation of configured values and byte-boundary tests; the case-preservation guidance matches Google's documentation. Three non-blocking suggestions are inline.

CI Status

All checks PASS on 52630418b (fmt, clippy targets, all adapter tests, parity, vitest, integration + browser tests, CodeQL).