feat: emit Cache-Control headers on cached responses

docs/guide/reference/api/classes/CacheControlConfig.md

@@ -0,0 +1,55 @@
+# Class: CacheControlConfig
+
+Defined in: CacheControlConfig.ts:29
+
+What `Cache-Control` to put on a response this plugin cached.
+
+Design and original implementation by `@pinkasey` in
+https://github.com/strapi-community/plugin-rest-cache/pull/96, which targeted
+Strapi 4 and can no longer be rebased. Carried forward by
+https://github.com/strapi-community/plugin-rest-cache/issues/175.
+
+Simplified from #96's two nested types - a `CacheControlHeaderConfig`
+wrapping a `CacheControlResponseHeaderConfig` - into the one flat block
+below, because only the response direction is implemented here. Honouring an
+incoming request `Cache-Control` is still open, and a wrapper whose only
+member today is `response` buys nothing while making every user write
+`cacheControl.response.maxAge`. Should the request direction land, it can add
+a `cacheControl.request` block without changing any of these names.
+
+#96's `CacheControlResponseMaxAge` enum - NONE / CONFIG / a number - is kept,
+as the union on `maxAge`. That is the part carrying the meaning: "say
+nothing", "say what the route is actually cached for", or "say this instead".
+
+Off by default and meant to stay opt-in: the header moves caching to browsers
+and CDNs, where a purge cannot reach it, so every emitted `max-age` is a
+window of guaranteed staleness that an operator has to choose knowingly.
+
+## Constructors
+
+### Constructor
+
+```ts
+new CacheControlConfig(options?): CacheControlConfig;
+```
+
+Defined in: CacheControlConfig.ts:65
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `options` | [`CacheControlConfigInput`](../interfaces/CacheControlConfigInput.md) |
+
+#### Returns
+
+`CacheControlConfig`
+
+## Properties
+
+| Property | Type | Default value | Description | Defined in |
+| ------ | ------ | ------ | ------ | ------ |
+| <a id="enabled"></a> `enabled` | `boolean` | `false` | Emit the header at all. | CacheControlConfig.ts:31 |
+| <a id="maxage"></a> `maxAge` | `"none"` \| [`Milliseconds`](../type-aliases/Milliseconds.md) \| `"config"` | `'config'` | `none` omits the `max-age` directive, `config` takes the route's resolved `maxAge`, and a number overrides it. That number is MILLISECONDS, like every other duration in this plugin, even though the directive it ends up in is seconds. A single field that meant seconds while `maxAge`, `ttl` and `staleWhileRevalidate` meant milliseconds is precisely the ambiguity behind https://github.com/strapi-community/plugin-rest-cache/issues/126. The one conversion lives in buildCacheControl. | CacheControlConfig.ts:44 |
+| <a id="scope"></a> `scope` | `"public"` \| `"private"` | `'private'` | `private` means only the end client may store the response; `public` also allows shared caches such as a CDN. Defaults to `private`, the answer that cannot leak: a wrongly-public response is served to the wrong person by a cache the server does not own. `public` is downgraded to `private` on any route whose keys identify the caller - see buildCacheControl. | CacheControlConfig.ts:55 |
+| <a id="stalewhilerevalidate"></a> `staleWhileRevalidate` | [`Milliseconds`](../type-aliases/Milliseconds.md) | `null` | How long a cache may keep serving the stale response while it refreshes, or null to omit the directive. Milliseconds, for the same reason as `maxAge` above. | CacheControlConfig.ts:63 |

docs/guide/reference/api/classes/CachePluginStrategy.md

@@ -1,6 +1,6 @@
 # Class: CachePluginStrategy
 
-Defined in: [CachePluginStrategy.ts:7](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L7)
+Defined in: [CachePluginStrategy.ts:8](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L8)
 
 ## Constructors
 
@@ -10,7 +10,7 @@ Defined in: [CachePluginStrategy.ts:7](https://github.com/strapi-community/plugi
 new CachePluginStrategy(options?): CachePluginStrategy;
 ```
 
-Defined in: [CachePluginStrategy.ts:34](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L34)
+Defined in: [CachePluginStrategy.ts:42](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L42)
 
 #### Parameters
 
@@ -26,15 +26,16 @@ Defined in: [CachePluginStrategy.ts:34](https://github.com/strapi-community/plug
 
 | Property | Type | Default value | Description | Defined in |
 | ------ | ------ | ------ | ------ | ------ |
-| <a id="clearrelatedcache"></a> `clearRelatedCache` | `boolean` | `true` | - | [CachePluginStrategy.ts:23](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L23) |
-| <a id="contenttypes"></a> `contentTypes` | [`CacheContentTypeConfig`](CacheContentTypeConfig.md)[] | `[]` | - | [CachePluginStrategy.ts:30](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L30) |
-| <a id="debug"></a> `debug` | `boolean` | `false` | - | [CachePluginStrategy.ts:8](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L8) |
-| <a id="enableadminctbmiddleware"></a> `enableAdminCTBMiddleware` | `boolean` | `true` | - | [CachePluginStrategy.ts:14](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L14) |
-| <a id="enablecontentapipurge"></a> `enableContentApiPurge` | `boolean` | `false` | - | [CachePluginStrategy.ts:18](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L18) |
-| <a id="enabledocumentservicemiddleware"></a> `enableDocumentServiceMiddleware` | `boolean` | `true` | - | [CachePluginStrategy.ts:16](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L16) |
-| <a id="enableetag"></a> `enableEtag` | `boolean` | `false` | - | [CachePluginStrategy.ts:10](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L10) |
-| <a id="enablexcacheheaders"></a> `enableXCacheHeaders` | `boolean` | `false` | - | [CachePluginStrategy.ts:12](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L12) |
-| <a id="keys"></a> `keys` | [`CacheKeysConfig`](CacheKeysConfig.md) | `undefined` | - | [CachePluginStrategy.ts:32](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L32) |
-| <a id="keysprefix"></a> `keysPrefix` | `string` | `''` | - | [CachePluginStrategy.ts:28](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L28) |
-| <a id="maxage"></a> `maxAge` | [`Milliseconds`](../type-aliases/Milliseconds.md) | `undefined` | Milliseconds. | [CachePluginStrategy.ts:26](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L26) |
-| <a id="resetonstartup"></a> `resetOnStartup` | `boolean` | `false` | - | [CachePluginStrategy.ts:20](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L20) |
+| <a id="cachecontrol"></a> `cacheControl` | [`CacheControlConfig`](CacheControlConfig.md) | `undefined` | Whether cached responses advertise their caching downstream. **See** https://github.com/strapi-community/plugin-rest-cache/issues/175 | [CachePluginStrategy.ts:40](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L40) |
+| <a id="clearrelatedcache"></a> `clearRelatedCache` | `boolean` | `true` | - | [CachePluginStrategy.ts:24](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L24) |
+| <a id="contenttypes"></a> `contentTypes` | [`CacheContentTypeConfig`](CacheContentTypeConfig.md)[] | `[]` | - | [CachePluginStrategy.ts:31](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L31) |
+| <a id="debug"></a> `debug` | `boolean` | `false` | - | [CachePluginStrategy.ts:9](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L9) |
+| <a id="enableadminctbmiddleware"></a> `enableAdminCTBMiddleware` | `boolean` | `true` | - | [CachePluginStrategy.ts:15](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L15) |
+| <a id="enablecontentapipurge"></a> `enableContentApiPurge` | `boolean` | `false` | - | [CachePluginStrategy.ts:19](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L19) |
+| <a id="enabledocumentservicemiddleware"></a> `enableDocumentServiceMiddleware` | `boolean` | `true` | - | [CachePluginStrategy.ts:17](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L17) |
+| <a id="enableetag"></a> `enableEtag` | `boolean` | `false` | - | [CachePluginStrategy.ts:11](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L11) |
+| <a id="enablexcacheheaders"></a> `enableXCacheHeaders` | `boolean` | `false` | - | [CachePluginStrategy.ts:13](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L13) |
+| <a id="keys"></a> `keys` | [`CacheKeysConfig`](CacheKeysConfig.md) | `undefined` | - | [CachePluginStrategy.ts:33](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L33) |
+| <a id="keysprefix"></a> `keysPrefix` | `string` | `''` | - | [CachePluginStrategy.ts:29](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L29) |
+| <a id="maxage"></a> `maxAge` | [`Milliseconds`](../type-aliases/Milliseconds.md) | `undefined` | Milliseconds. | [CachePluginStrategy.ts:27](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L27) |
+| <a id="resetonstartup"></a> `resetOnStartup` | `boolean` | `false` | - | [CachePluginStrategy.ts:21](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/CachePluginStrategy.ts#L21) |

docs/guide/reference/api/index.md

@@ -3,6 +3,7 @@
 ## Classes
 
 - [CacheContentTypeConfig](classes/CacheContentTypeConfig.md)
+- [CacheControlConfig](classes/CacheControlConfig.md)
 - [CacheKeysConfig](classes/CacheKeysConfig.md)
 - [CachePluginStrategy](classes/CachePluginStrategy.md)
 - [CacheProvider](classes/CacheProvider.md)
@@ -11,6 +12,7 @@
 ## Interfaces
 
 - [CacheContentTypeConfigInput](interfaces/CacheContentTypeConfigInput.md)
+- [CacheControlConfigInput](interfaces/CacheControlConfigInput.md)
 - [CacheKeysConfigInput](interfaces/CacheKeysConfigInput.md)
 - [CachePluginStrategyInput](interfaces/CachePluginStrategyInput.md)
 - [CacheProviderConfig](interfaces/CacheProviderConfig.md)

docs/guide/reference/api/interfaces/CacheContentTypeConfigInput.md

@@ -1,17 +1,17 @@
 # Interface: CacheContentTypeConfigInput
 
-Defined in: [inputs.ts:35](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L35)
+Defined in: [inputs.ts:48](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L48)
 
 ## Properties
 
 | Property | Type | Defined in |
 | ------ | ------ | ------ |
-| <a id="contenttype"></a> `contentType?` | `string` | [inputs.ts:36](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L36) |
-| <a id="hitpass"></a> `hitpass?` | `boolean` \| [`CachePluginHitpass`](../type-aliases/CachePluginHitpass.md) | [inputs.ts:40](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L40) |
-| <a id="injectdefaultroutes"></a> `injectDefaultRoutes?` | `boolean` | [inputs.ts:38](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L38) |
-| <a id="keys"></a> `keys?` | \| [`CacheKeysConfig`](../classes/CacheKeysConfig.md) \| [`CacheKeysConfigInput`](CacheKeysConfigInput.md) | [inputs.ts:41](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L41) |
-| <a id="maxage"></a> `maxAge?` | `number` \| [`Milliseconds`](../type-aliases/Milliseconds.md) | [inputs.ts:39](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L39) |
-| <a id="plugin"></a> `plugin?` | `string` | [inputs.ts:44](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L44) |
-| <a id="relatedcontenttypeuid"></a> `relatedContentTypeUid?` | `string`[] | [inputs.ts:43](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L43) |
-| <a id="routes"></a> `routes?` | \| [`CacheRouteConfig`](../classes/CacheRouteConfig.md)[] \| [`CacheRouteConfigInput`](CacheRouteConfigInput.md)[] | [inputs.ts:42](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L42) |
-| <a id="singletype"></a> `singleType?` | `boolean` | [inputs.ts:37](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L37) |
+| <a id="contenttype"></a> `contentType?` | `string` | [inputs.ts:49](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L49) |
+| <a id="hitpass"></a> `hitpass?` | `boolean` \| [`CachePluginHitpass`](../type-aliases/CachePluginHitpass.md) | [inputs.ts:53](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L53) |
+| <a id="injectdefaultroutes"></a> `injectDefaultRoutes?` | `boolean` | [inputs.ts:51](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L51) |
+| <a id="keys"></a> `keys?` | \| [`CacheKeysConfig`](../classes/CacheKeysConfig.md) \| [`CacheKeysConfigInput`](CacheKeysConfigInput.md) | [inputs.ts:54](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L54) |
+| <a id="maxage"></a> `maxAge?` | `number` \| [`Milliseconds`](../type-aliases/Milliseconds.md) | [inputs.ts:52](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L52) |
+| <a id="plugin"></a> `plugin?` | `string` | [inputs.ts:57](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L57) |
+| <a id="relatedcontenttypeuid"></a> `relatedContentTypeUid?` | `string`[] | [inputs.ts:56](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L56) |
+| <a id="routes"></a> `routes?` | \| [`CacheRouteConfig`](../classes/CacheRouteConfig.md)[] \| [`CacheRouteConfigInput`](CacheRouteConfigInput.md)[] | [inputs.ts:55](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L55) |
+| <a id="singletype"></a> `singleType?` | `boolean` | [inputs.ts:50](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L50) |

docs/guide/reference/api/interfaces/CacheControlConfigInput.md

@@ -0,0 +1,19 @@
+# Interface: CacheControlConfigInput
+
+Defined in: [inputs.ts:21](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L21)
+
+The shapes a user may write in config/plugins.
+
+Deliberately separate from the resolved classes: what someone writes is
+partial and loosely typed, what the plugin runs on is complete. Conflating
+the two is how `maxAge` ended up defaulting to the boolean `true` in one
+constructor while being documented as milliseconds everywhere else.
+
+## Properties
+
+| Property | Type | Description | Defined in |
+| ------ | ------ | ------ | ------ |
+| <a id="enabled"></a> `enabled?` | `boolean` | - | [inputs.ts:22](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L22) |
+| <a id="maxage"></a> `maxAge?` | \| `number` \| `"none"` \| [`Milliseconds`](../type-aliases/Milliseconds.md) \| `"config"` | 'none' omits max-age, 'config' uses the route's maxAge, a number overrides it. The number is milliseconds - see CacheControlConfig. | [inputs.ts:27](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L27) |
+| <a id="scope"></a> `scope?` | `"public"` \| `"private"` | - | [inputs.ts:28](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L28) |
+| <a id="stalewhilerevalidate"></a> `staleWhileRevalidate?` | `number` \| [`Milliseconds`](../type-aliases/Milliseconds.md) | Milliseconds, or null/undefined to omit the directive. | [inputs.ts:30](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L30) |

docs/guide/reference/api/interfaces/CacheKeysConfigInput.md

@@ -1,18 +1,11 @@
 # Interface: CacheKeysConfigInput
 
-Defined in: [inputs.ts:20](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L20)
-
-The shapes a user may write in config/plugins.
-
-Deliberately separate from the resolved classes: what someone writes is
-partial and loosely typed, what the plugin runs on is complete. Conflating
-the two is how `maxAge` ended up defaulting to the boolean `true` in one
-constructor while being documented as milliseconds everywhere else.
+Defined in: [inputs.ts:33](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L33)
 
 ## Properties
 
 | Property | Type | Defined in |
 | ------ | ------ | ------ |
-| <a id="useauth"></a> `useAuth?` | `boolean` | [inputs.ts:23](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L23) |
-| <a id="useheaders"></a> `useHeaders?` | `string`[] | [inputs.ts:21](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L21) |
-| <a id="usequeryparams"></a> `useQueryParams?` | `boolean` \| `string`[] | [inputs.ts:22](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L22) |
+| <a id="useauth"></a> `useAuth?` | `boolean` | [inputs.ts:36](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L36) |
+| <a id="useheaders"></a> `useHeaders?` | `string`[] | [inputs.ts:34](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L34) |
+| <a id="usequeryparams"></a> `useQueryParams?` | `boolean` \| `string`[] | [inputs.ts:35](https://github.com/strapi-community/plugin-rest-cache/blob/main/packages/plugin-rest-cache/server/src/types/inputs.ts#L35) |