br-etag-cache

better-route: ETag conditional reads

Use ETags on read routes to let clients revalidate a representation. They do not prevent duplicate writes; use idempotency for that.

use BetterRoute\Middleware\Cache\ETagMiddleware;

$router->get('/catalog', $handler)
    ->publicRoute()
    ->middleware([new ETagMiddleware()]);

The default validator is a quoted SHA-1 of the JSON-encoded response body. It applies only to GET/HEAD results with status 200–299 except 204.

1.1 behavior

The middleware preserves Better Route Response and WP_REST_Response status/data. It adds the ETag through the appropriate response API instead of flattening the WordPress response.

It skips:

• returned WP_Error;
• non-2xx responses;
• 204 No Content;
• non-GET/HEAD methods.

If-None-Match accepts:

• a single validator;
• a comma-separated validator list;
• weak or strong forms of the same opaque tag;
• *.

On a match, 1.1 returns 304 with no body and preserves cache-relevant source headers: Cache-Control, Content-Location, Expires, and Vary, plus the ETag.

The middleware computes and controls the final ETag header; do not rely on an existing handler ETag remaining unchanged.

Cheap custom validators

For large responses, derive a validator from a stable version instead of hashing the full body:

use BetterRoute\Http\RequestContext;

$etag = new ETagMiddleware(
    weak: false,
    etagResolver: static function (mixed $response, RequestContext $context): string {
        return (string) get_option('myapp_catalog_version', 0);
    },
);

Return the opaque value; the middleware quotes it. A returned already-quoted or W/ value is normalized. Invalid quote/control bytes are replaced with a safe hash rather than reaching an HTTP header.

Use weak: true when byte differences may represent the same semantic representation:

new ETagMiddleware(weak: true); // W/"..."

The default JSON hash follows array order. Deeply sort associative data before returning it, or use a stable version resolver, when construction order is nondeterministic.