> ## Documentation Index
> Fetch the complete documentation index at: https://docs.37audits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cache Auditor

> Validates cache headers for optimal web performance

<Info>
  **Performance Auditor** — validates cache headers for optimal web performance.
</Info>

<CardGroup cols={2}>
  <Card title="Performance" icon="zap">
    Cache and delivery efficiency for HTML, assets, and APIs.
  </Card>

  <Card title="Resilience" icon="shield">
    Safer cache directives that avoid stale or user-specific content.
  </Card>
</CardGroup>

A comprehensive cache validation checker that analyzes cache headers for different types of web resources according to industry best practices. It validates cache configuration for HTML pages, static assets, and API responses, with platform-specific logic for Liferay environments.

## How it works

The Cache Checker scans web pages and validates cache headers for different types of resources (HTML, versioned static assets, unversioned static assets, APIs) according to industry best practices. It can also use platform-specific checkers when certain software stacks are detected.

1. **Software stack detection** — analyzes the request stack to determine if platform-specific logic should be used
2. **Page loading** — uses Playwright to load the provided URL in a headless browser
3. **Resource discovery** — scans the DOM for resource URLs (`img`, `script`, `link`, `video`, `iframe`)
4. **Resource classification** — categorizes resources as HTML, versioned static, unversioned static, or API
5. **Cache analysis** — for each resource, performs an HTTP HEAD request and analyzes cache headers
6. **Issue detection** — applies validation rules based on resource type and aggregates findings

When Liferay is detected in the software stack, the checker routes to Liferay-specific cache validation (for example, resources under `/documents/`).

## What it checks

The Cache Checker analyzes HTTP cache headers across different types of web resources to ensure optimal caching strategies:

* **HTML Pages**: Validates that HTML responses have appropriate cache directives (`max-age=0`, `must-revalidate`, or `no-cache`) with proper validators (ETag/Last-Modified)
* **Versioned Static Assets**: Ensures versioned resources (JS, CSS, images with version parameters) have long-term caching (`max-age` ≥ 1 year) with `immutable` directive
* **Unversioned Static Assets**: Checks that unversioned resources use short cache times (≤ 1 hour) or revalidation mechanisms
* **API Responses**: Validates API endpoints have appropriate cache strategies with proper validators
* **Platform-Specific Logic**: Automatically routes to Liferay-specific cache validation when Liferay is detected in the software stack

The checker examines `Cache-Control`, `ETag`, `Last-Modified`, `Set-Cookie`, `Vary`, and `Expires` headers to identify caching issues.

## Output documentation

| Status      | Description                                                               | Test logic                                                                                                                                                                                                                                                                                                                              |
| ----------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SUCCESS** | All resources have proper cache configuration according to best practices | HTML: `Cache-Control` `max-age=0` with `must-revalidate`/`no-cache` and has ETag/Last-Modified. Versioned assets: `public`, `max-age`≥31536000, `immutable`, no cookies. Unversioned assets: `max-age`≤3600 or uses revalidation. No `Set-Cookie` on cacheable responses. No problematic `Vary` headers.                                |
| **WARNING** | Some resources have cache configuration issues that should be addressed   | HTML cached >5 minutes without `must-revalidate`/`no-cache`. Versioned assets lack `immutable` or have `max-age` less than 1 year. Unversioned assets cached ≥1 day. Missing ETag/Last-Modified on resources expected to revalidate. Excessive `Vary` headers (>3) that may hurt cache hit rate. `Expires` vs `Cache-Control` mismatch. |
| **FAIL**    | Critical cache configuration problems that prevent effective caching      | `Set-Cookie` header present on publicly cacheable resources. `Vary: *` preventing effective caching. User-specific `Vary` headers on HTML resources. HTML cached >1 day without revalidation. Contradictory cache directives that disable safe caching. Missing `Cache-Control` header entirely.                                        |

## Risks and considerations

### Performance degradation

* Poor cache configuration leads to unnecessary server requests and bandwidth usage
* Users experience slower page load times due to repeated downloads of unchanged resources
* Increased server load and hosting costs from redundant resource serving

### SEO and user experience impact

* Slow loading pages negatively affect search engine rankings
* Poor user experience leads to higher bounce rates and reduced conversions
* Mobile users on slow connections are particularly affected

### Security and privacy concerns

* `Set-Cookie` headers on cacheable resources can expose sensitive user data
* Improper `Vary` headers may cache user-specific content inappropriately
* Long-lived HTML caching without revalidation can serve stale or sensitive content

### Operational issues

* Difficult to deploy updates when resources are cached too aggressively
* Inconsistent cache behavior across different browsers and CDNs
* Debugging becomes complex when cache issues mask other problems