File Explorer

1# Cache Store2 3A Cache Store is responsible for storing and retrieving cached responses.4It is also responsible for deciding which specific response to use based off of5a response's `Vary` header (if present). It is expected to be compliant with6[RFC-9111](https://www.rfc-editor.org/rfc/rfc9111.html).7 8## Pre-built Cache Stores9 10### `MemoryCacheStore`11 12The `MemoryCacheStore` stores the responses in-memory.13 14**Options**15 16- `maxSize` - The maximum total size in bytes of all stored responses. Default `104857600` (100MB).17- `maxCount` - The maximum amount of responses to store. Default `1024`.18- `maxEntrySize` - The maximum size in bytes that a response's body can be. If a response's body is greater than or equal to this, the response will not be cached. Default `5242880` (5MB).19 20### Getters21 22#### `MemoryCacheStore.size`23 24Returns the current total size in bytes of all stored responses.25 26### Methods27 28#### `MemoryCacheStore.isFull()`29 30Returns a boolean indicating whether the cache has reached its maximum size or count.31 32### Events33 34#### `'maxSizeExceeded'`35 36Emitted when the cache exceeds its maximum size or count limits. The event payload contains `size`, `maxSize`, `count`, and `maxCount` properties.37 38 39### `SqliteCacheStore`40 41The `SqliteCacheStore` stores the responses in a SQLite database.42Under the hood, it uses Node.js' [`node:sqlite`](https://nodejs.org/api/sqlite.html) api.43The `SqliteCacheStore` is only exposed if the `node:sqlite` api is present.44 45**Options**46 47- `location` - The location of the SQLite database to use. Default `:memory:`.48- `maxCount` - The maximum number of entries to store in the database. Default `Infinity`.49- `maxEntrySize` - The maximum size in bytes that a response's body can be. If a response's body is greater than or equal to this, the response will not be cached. Default `Infinity`.50 51## Defining a Custom Cache Store52 53The store must implement the following functions:54 55### Getter: `isFull`56 57Optional. This tells the cache interceptor if the store is full or not. If this is true,58the cache interceptor will not attempt to cache the response.59 60### Function: `get`61 62Parameters:63 64* **req** `Dispatcher.RequestOptions` - Incoming request65 66Returns: `GetResult | Promise<GetResult | undefined> | undefined` - If the request is cached, the cached response is returned. If the request's method is anything other than HEAD, the response is also returned.67If the request isn't cached, `undefined` is returned.68 69The `get` method may return a `Promise` for async cache stores (e.g. Redis-backed or remote stores). The cache interceptor handles both synchronous and asynchronous return values, including in revalidation paths (304 Not Modified handling and stale-while-revalidate background revalidation).70 71Response properties:72 73* **response** `CacheValue` - The cached response data.74* **body** `Readable | Iterable<Buffer> | undefined` - The response's body. This can be an array of `Buffer` chunks (with a `.values()` method) or a `Readable` stream. Both formats are supported in all code paths, including 304 revalidation.75 76### Function: `createWriteStream`77 78Parameters:79 80* **req** `Dispatcher.RequestOptions` - Incoming request81* **value** `CacheValue` - Response to store82 83Returns: `Writable | undefined` - If the store is full, return `undefined`. Otherwise, return a writable so that the cache interceptor can stream the body and trailers to the store.84 85## `CacheValue`86 87This is an interface containing the majority of a response's data (minus the body).88 89### Property `statusCode`90 91`number` - The response's HTTP status code.92 93### Property `statusMessage`94 95`string` - The response's HTTP status message.96 97### Property `rawHeaders`98 99`Buffer[]` - The response's headers.100 101### Property `vary`102 103`Record<string, string | string[] | null> | undefined` - The headers defined by the response's `Vary` header104and their respective values for later comparison. Values are `null` when the105header specified in `Vary` was not present in the original request. These `null`106values are automatically filtered out during revalidation so they are not sent107as request headers.108 109For example, for a response like110```111Vary: content-encoding, accepts112content-encoding: utf8113accepts: application/json114```115 116This would be117```js118{119  'content-encoding': 'utf8',120  accepts: 'application/json'121}122```123 124If the original request did not include the `accepts` header:125```js126{127  'content-encoding': 'utf8',128  accepts: null129}130```131 132### Property `cachedAt`133 134`number` - Time in millis that this value was cached.135 136### Property `staleAt`137 138`number` - Time in millis that this value is considered stale.139 140### Property `deleteAt`141 142`number` - Time in millis that this value is to be deleted from the cache. This143is either the same sa staleAt or the `max-stale` caching directive.144 145The store must not return a response after the time defined in this property.146 147## `CacheStoreReadable`148 149This extends Node's [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable)150and defines extra properties relevant to the cache interceptor.151 152### Getter: `value`153 154The response's [`CacheStoreValue`](/docs/docs/api/CacheStore.md#cachestorevalue)155 156## `CacheStoreWriteable`157 158This extends Node's [`Writable`](https://nodejs.org/api/stream.html#class-streamwritable)159and defines extra properties relevant to the cache interceptor.160 161### Setter: `rawTrailers`162 163If the response has trailers, the cache interceptor will pass them to the cache164interceptor through this method.165