Measure and offload SSAT HTML compression from the Compute guest

[ChristianPavilonis]

Summary

Measure and, if justified, offload SSAT HTML compression work from the Compute guest.

The current SSAT HTML rewrite path mirrors origin content encoding, which means gzip/deflate/brotli responses are decompressed and recompressed inside the guest. That CPU work is paid on every SSAT pageview because assembled HTML is private and not shared-cacheable.

Problem

For large publisher documents, in-guest decompression/recompression can become a major vCPU cost and may increase risk of hitting Compute CPU limits. Fastly supports delivery compression via X-Compress-Hint: on, but using it with an Accept-Encoding: identity origin fetch changes wire-size behavior and needs measurement before becoming default.

Proposed scope

• Measure current SSAT HTML compression CPU and wire sizes on representative pages.
• Test origin behavior for Accept-Encoding: identity.
• Test Fastly delivery compression with X-Compress-Hint: on.
• Compare current gzip/br-in + gzip/br-out behavior against identity-origin + delivery compression.
• Add a config flag or rollout guard if implementation proceeds.

Measurement plan

For representative large and normal pages:

• Fetch origin with Accept-Encoding: identity, gzip, and br.
• Verify identity body equivalence after decompression.
• Run a flagged Fastly path using identity-origin + X-Compress-Hint: on.
• Compare:
  • Content-Encoding
  • transfer size
  • TTFB/FCP if available
  • guest CPU / vCPU-ms
  • error/truncation behavior

Acceptance criteria

• Measurement compares current compression behavior vs identity-origin + delivery compression.
• Origin support for Accept-Encoding: identity is confirmed or failure modes are documented.
• Fastly X-Compress-Hint: on behavior is measured for representative HTML pages.
• Decision recorded: keep current behavior, enable offload by default, or expose as path/config-specific opt-in.
• If implemented, SSAT privacy behavior remains private, max-age=0 and no shared cacheability is introduced.
• In-guest Brotli is not introduced as the default SSAT HTML path.

Out of scope

• Origin-template caching.
• Parser-safe streaming/body-close hold.
• Static asset compression policy.

Reference

See docs/superpowers/specs/2026-07-06-cache-control-header-design.md for why this is deferred from the initial cache-header PR.

[ChristianPavilonis]

Local measurement update from a native release-mode fixture test.

I added an ignored local fixture harness at crates/trusted-server-core/tests/ssat_compression_fixtures.rs. It reads representative local HTML fixtures, runs them through the existing StreamingPipeline + HtmlProcessor, and verifies that:

• gzip origin mirror output decompresses to the same bytes as identity-origin processed output;
• gzip decode-to-identity output matches identity-origin processed output;
• brotli origin mirror output decompresses to the same bytes as identity-origin processed output;
• brotli decode-to-identity output matches identity-origin processed output.

Command used:

cargo test -p trusted-server-core \
  --target aarch64-apple-darwin \
  --release \
  --test ssat_compression_fixtures \
  -- --ignored --nocapture

Representative local results:

Fixture	Identity input	Origin gzip	Origin br	Identity process	gzip mirror	br mirror	gzip decode→identity	br decode→identity
Home page	1,330,005 B	181,161 B	112,086 B	0.772 ms	15.463 ms	7.425 ms	2.654 ms	2.260 ms
Article page	668,249 B	100,129 B	69,891 B	0.512 ms	8.624 ms	4.641 ms	1.538 ms	1.495 ms

Local interpretation:

• The existing mirror-compression path is materially more expensive than identity-origin processing on these representative pages.
• Decode-to-identity is much closer to identity processing than mirror recompression, which points to in-guest recompression as the main local cost.
• These tests also give us a reusable local regression/measurement harness while keeping the large representative HTML fixtures out of the repo and out of default CI.

Caveats:

• These are native local release timings, not Fastly Compute vCPU-ms.
• Local/Viceroy cannot validate Fastly dynamic delivery compression from X-Compress-Hint: on.
• The delivery-compressed sizes in this local harness are only approximations; the final decision still needs a Fastly staging/canary measurement for real Content-Encoding, transfer size, and Compute vCPU-ms.

[ChristianPavilonis]

Measurement update from the SSAT compression experiment branch:

Tested the guarded query parameter modes:

• ?__ts_ssat_compression=identity
• ?__ts_ssat_compression=mirror

Observed headers for identity mode:

content-encoding: br
x-ts-ssat-compression-mode: identity
x-ts-ssat-delivery-compression: fastly-dynamic
x-ts-ssat-fastly-vcpu-ms: 19
x-ts-ssat-origin-accept-encoding: identity
x-ts-ssat-origin-content-encoding: identity
x-ts-ssat-output-content-encoding: identity
x-ts-ssat-processed-bytes: 1365106
x-ts-ssat-processing-ms: 9.045

Observed headers for mirror mode:

x-ts-ssat-compression-mode: mirror
x-ts-ssat-delivery-compression: in-guest
x-ts-ssat-fastly-vcpu-ms: 47
x-ts-ssat-origin-accept-encoding: gzip, deflate, br
x-ts-ssat-origin-content-encoding: gzip
x-ts-ssat-output-content-encoding: gzip
x-ts-ssat-processed-bytes: 178351
x-ts-ssat-processing-ms: 44.630

Initial finding: identity mode is materially better for Compute-side processing on this page:

• Processing wall time: ~9 ms vs ~45 ms (identity is about 5x faster)
• Fastly vCPU: 19 ms vs 47 ms
• Final browser delivery is still compressed with Brotli (content-encoding: br) via Fastly dynamic compression

x-ts-ssat-processed-bytes is larger in identity mode because it measures the uncompressed body handled by the guest before Fastly delivery compression. It does not represent final wire size.

Also noted: x-compress-hint was not visible in the browser response, but the response had:

x-ts-ssat-delivery-compression: fastly-dynamic
content-encoding: br

So Fastly delivery compression appears to have been applied successfully despite the control hint not being exposed back to the client.

[ChristianPavilonis]

Final decision: proceed with compression offload as a publisher-level Fastly opt-in, not as the global default yet.

PR: #884

The implementation adds:

[publisher]
ssat_compression_offload_enabled = true

When enabled on Fastly and the existing SSAT eligibility gates pass, Trusted Server requests Accept-Encoding: identity, emits processed identity HTML with X-Compress-Hint: on, and lets Fastly dynamically compress delivery. Origins that ignore the identity request and return gzip, deflate, or Brotli are decoded safely to identity output.

Axum, Cloudflare, and Spin explicitly declare the capability unavailable and keep the current mirrored compression behavior. The feature defaults to false everywhere.

Rationale:

• measured guest processing improved from ~44.6 ms to ~9.0 ms;
• measured Fastly vCPU improved from 47 ms to 19 ms;
• browser delivery remained Brotli-compressed;
• identity origin bodies are larger and count against the current 10 MiB raw origin-response limit, so an opt-in rollout is safer than changing the global default.

The PR removes the temporary measurement query parameters and diagnostic headers; those findings remain recorded in this issue.