Cache Header Audit (cache-header-audit)

Summary

Caching headers on HTML and static assets (Cache-Control, ETag, Vary, etc.).

Classification

• Category: PERFORMANCE
• Plugin id: cache-header-audit
• Version: 1.0.0
• Target types: WEBSITE, API, WEBSHOP
• Weight class: LIGHT
• Risk level: not set on plugin object
• Browser required: No (HTTP / Node / other — see source)
• Tier / group: Tier 1 — HTTP-only

Schedule

• scheduleHints: { defaultInterval: '0 */6 * * *', priority: 6 }
• Prerequisites: None declared on this plugin.

Configurable inputs

Public keys are derived from inputSchema: z.object({ ... }) (underscore-prefixed keys are runtime-only and omitted here).

Field	Notes
timeout	Zod field in inputSchema — see source for defaults, min/max, and .describe().
maxAssets	Zod field in inputSchema — see source for defaults, min/max, and .describe().

Runtime / injected config

• None documented beyond standard worker context (target, config, logger, reportProgress). Underscore-prefixed keys are internal.

Checks that produce findings

These checks run inside this plugin during a single test run. They are not separate tests in the database — each becomes a Finding linked to the Run for cache-header-audit.

Check	Typical severity	Why
HTML document over-cached without revalidation	WARNING	Document max-age >3600s without no-cache/must-revalidate — HTML updates may stay stale in caches.
Static assets with no cache headers	WARNING	Assets lack both Cache-Control and Expires — browsers re-fetch on every page load.
Assets with short max-age (< 86400 s)	INFO	Static asset max-age under 24h — missed opportunity when URLs are fingerprinted.
Problematic Vary on assets	INFO	Vary: * or Vary: User-Agent on static files — fragments CDN cache.

How each check works

1. Document HEAD — HEAD target URL; run analyzeCacheHeaders(..., 'document').
2. HTML over-cache — If max-age > 3600 and no no-cache/must-revalidate in Cache-Control → WARNING.
3. Discover assets — GET+parse HTML; collect up to maxAssets (default 20) from link[rel=stylesheet], script[src], img[src], link[rel=preload][as=font] (same origin resolved).
4. Asset HEAD — Batches of 3 with 200 ms delay; analyze each response.
5. Issue detection — No Cache-Control/Expires; max-age <86400 on non-document; no-store on static; private on static; Vary: * or User-Agent; no-cache without ETag/Last-Modified (internal issue list — aggregated into the findings above).
6. Findings — One WARNING for count of assets with no cache headers; INFO groups for short max-age and Vary issues (up to 10 URLs in evidence).

Caveats and concerns

• Sample not exhaustive — Only first N assets from homepage DOM; CDN paths off-page omitted.
• HEAD failures skipped — Failed asset HEADs excluded from counts silently.
• Third-party assets — Absolute URLs to other hosts are checked but may block monitor IP.
• API target type — Allowed by plugin; asset selectors may be sparse on JSON API responses.
• Document issues in analyzeCacheHeaders — Some per-asset rules in analyzeCacheHeaders are not promoted to separate findings unless they match the three aggregate categories.

Source

packages/test-plugins/src/plugins/cache-header-audit.ts