Skip to content

FreshTrace v0.1.0 — Cache headers, clear answers

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 14 Oct 14:05
· 4 commits to main since this release
v0.1.0
201066e

Live lab · Source repository

FreshTrace v0.1.0

FreshTrace turns HTTP cache response headers into an interactive timeline. Compare two policies under the same scenario and inspect why a private or shared cache can reuse a response, needs validation, or must fetch from the origin.

Included in this release

  • An offline browser workbench with English and Simplified Chinese interfaces, A/B policies, elapsed-time controls, private/shared timelines, and decision explanations.
  • Presets and scenario controls for origin failure, authenticated requests, and Vary matching.
  • JSON scenario download/import and Markdown report export.
  • A zero-dependency Node.js CLI that reads local header text, a bare Cache-Control value, or a JSON header object; accepts optional capture clocks; and outputs Markdown or JSON.
  • A shared deterministic analysis engine for response caching directives, explicit freshness, Age, validation, supported stale windows, authentication permission, and variant matching.
  • Runnable examples in samples/, bilingual setup documentation, model documentation with RFC references, contribution and security guidance, and an MIT license.
  • A static build, release packaging script, CI workflow, and configurable GitHub Pages workflow.

Try the examples

From the repository directory with Node.js 20 or later:

npm start
node bin/freshtrace.js samples/cdn-response.json --elapsed 30
node bin/freshtrace.js samples/origin-outage.json --elapsed 150 --origin-error

Import browser-vs-cdn.scenario.json in the browser for a complete A/B comparison.

Validation

The automated suite covers 42 checks across core analysis, timeline behavior, scenario validation, and CLI integration. Coverage includes time boundaries, malformed input, private/shared differences, and file-handling behavior. Desktop and mobile screenshots of the actual interface are included in docs/images/.

The shared engine and CLI use the same model; a browser result and a CLI result should be compared using identical headers and scenario options. The repository's CI workflow is configured to test Node.js 20, 22, and 24; this is a configured matrix, not a claim that remote CI has already run.

Model limits

This release evaluates a complete GET 200 response with a matching URL and unchanged stored representation. Non-200 pasted status lines are rejected. It does not make live requests, infer a heuristic TTL, apply request-side cache directives, or predict provider-specific overrides.

Absent capture clocks, a valid response Date is treated as receipt with zero transit delay. Stale-serving windows represent permission under the stated model; they do not guarantee that a particular browser or CDN implements or chooses that behavior. See MODEL.md for the complete assumptions and conservative choices.

Scenario and CLI JSON exports include supplied headers. Markdown omits the full header block, but warnings can contain input-derived snippets. Review an export before sharing it.

Distribution

npm run build writes the static app to dist/. npm run package:release creates release/freshtrace-v0.1.0.zip using the system zip command. Source distribution does not require npm registry publication; the package is marked private to prevent accidental publication.

Package verification

This ZIP was built from the existing v0.1.0 tag after its tests passed in the release workflow. It includes source and the static dist/ build. Verify the download against the attached SHA256SUMS.txt.

Assets 4
Loading