alepha@docs:~/framework/docs/reference/primitives$
cat $etag.md | pretty
2 min read

#$etag

#Import

typescript
1import { $etag } from "alepha/server/etag";

#Overview

Middleware that enables ETag-based response caching per-route.

Sets per-request etag options in the ALS context. The global ServerEtagProvider hooks read these to generate ETags, handle 304s, and optionally store responses.

A request is answered 304 Not Modified when its If-None-Match names the response's ETag: a list of validators, a weak one (W/"...") and * all match. A stored response also carries Last-Modified, the time it was stored, and answers If-Modified-Since.

When store is enabled, the middleware also checks the cache before calling the handler, short-circuiting on cache hits.

Route middleware - works inside $action, $page, or any pipeline.

typescript
 1class UserController { 2  // ETag only (no response caching) 3  getUser = $action({ 4    method: "GET", 5    path: "/getUser", 6    use: [$etag()], 7    handler: async ({ params }) => { ... }, 8  }); 9 10  // ETag + response caching (store)11  getProfile = $action({12    method: "GET",13    path: "/getProfile",14    use: [$etag(true)],15    handler: async ({ params }) => { ... },16  });17 18  // Fine-grained control19  getStats = $action({20    method: "GET",21    path: "/getStats",22    use: [$etag({ store: { ttl: [5, "minutes"] }, control: { public: true, maxAge: 300 } })],23    handler: async ({ params }) => { ... },24  });25}

Stored responses are namespaced by caller identity (the authorization and cookie headers), so an authenticated route does not serve one user's body to another. Anonymous callers share a single entry.

#Options

Option Type Required Description
store true | DurationLike | CachePrimitiveOptions No If true, stores the response and answers later requests from the store without running the handler
etag true No Always on: sending an ETag is what $etag is for, and the option accepts no other value.
control true | string | EtagCacheControlOptions No The Cache-Control header of a successful response