@fastify/caching 7.0.0

package/.editorconfig

@@ -0,0 +1,13 @@
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+# [*.md]
+# trim_trailing_whitespace = false

package/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 10
+
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10

package/.github/stale.yml

@@ -0,0 +1,21 @@
+# Number of days of inactivity before an issue becomes stale
+daysUntilStale: 15
+# Number of days of inactivity before a stale issue is closed
+daysUntilClose: 7
+# Issues with these labels will never be considered stale
+exemptLabels:
+  - "discussion"
+  - "feature request"
+  - "bug"
+  - "help wanted"
+  - "plugin suggestion"
+  - "good first issue"
+# Label to use when marking an issue as stale
+staleLabel: stale
+# Comment to post when marking an issue as stale. Set to `false` to disable
+markComment: >
+  This issue has been automatically marked as stale because it has not had
+  recent activity. It will be closed if no further activity occurs. Thank you
+  for your contributions.
+# Comment to post when closing a stale issue. Set to `false` to disable
+closeComment: false

package/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+'on':
+  push:
+    paths-ignore:
+      - docs/**
+      - '*.md'
+  pull_request:
+    paths-ignore:
+      - docs/**
+      - '*.md'
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        node-version:
+          - 10
+          - 12
+          - 14
+          - 16
+          - 17
+        os:
+          - macos-latest
+          - ubuntu-latest
+          - windows-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Install Dependencies
+        run: |
+          npm install --ignore-scripts
+      - name: Lint
+        run: |
+          npm run lint:ci
+      - name: Run Tests
+        run: |
+          npm test
+  automerge:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: write
+    steps:
+      - uses: fastify/github-action-merge-dependabot@v3
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 James Sumners <james.sumners@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Readme.md

@@ -0,0 +1,153 @@
+# fastify-caching
+
+![CI](https://github.com/fastify/fastify-caching/workflows/CI/badge.svg)
+[![NPM version](https://img.shields.io/npm/v/fastify-caching.svg?style=flat)](https://www.npmjs.com/package/fastify-caching)
+[![Known Vulnerabilities](https://snyk.io/test/github/fastify/fastify-caching/badge.svg)](https://snyk.io/test/github/fastify/fastify-caching)
+[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
+
+*fastify-caching* is a plugin for the [Fastify](http://fastify.io/) framework
+that provides mechanisms for manipulating HTTP cache headers according to
+[RFC 2616 §14.9](https://tools.ietf.org/html/rfc2616#section-14.9).
+
+Supports Fastify versions ^3.0.0. Version v5.x supports Fastify ^3.0.0 in
+the [`v5.x` branch](https://github.com/fastify/fastify-caching/tree/v5.x).
+
+This plugin fully supports Fastify's encapsulation. Therefore, routes that
+should have differing cache settings should be registered within different
+contexts.
+
+In addition to providing header manipulation, the plugin also decorates the
+server instance with an object that can be used for caching items. **Note:**
+the default cache should not be used in a "production" environment. It is
+an LRU, in-memory cache that is capped at 100,000 items. It is *highly*
+recommended that a full featured cache object be supplied, e.g.
+[abstract-cache-redis][acache-redis].
+
+[acache-redis]: https://www.npmjs.com/package/abstract-cache-redis
+
+## Example
+
+This example shows using the plugin to disable client side caching of all
+routes.
+
+```js
+const http = require('http')
+const fastify = require('fastify')()
+const fastifyCaching = require('fastify-caching')
+
+fastify.register(
+  fastifyCaching,
+  {privacy: fastifyCaching.privacy.NOCACHE},
+  (err) => { if (err) throw err }
+)
+
+fastify.get('/', (req, reply) => {
+  reply.send({hello: 'world'})
+})
+
+fastify.listen(3000, (err) => {
+  if (err) throw err
+
+  http.get('http://127.0.0.1:3000/', (res) => {
+    console.log(res.headers['cache-control'])
+  })
+})
+```
+
+This example shows how to register the plugin such that it only provides
+a server-local cache. It will not set any cache control headers on responses.
+It also shows how to retain a reference to the cache object so that it can
+be re-used.
+
+```js
+const IORedis = require('ioredis')
+const redis = new IORedis({host: '127.0.0.1'})
+const abcache = require('abstract-cache')({
+  useAwait: false,
+  driver: {
+    name: 'abstract-cache-redis', // must be installed via `npm install`
+    options: {client: redis}
+  }
+})
+
+const fastify = require('fastify')()
+fastify
+  .register(require('fastify-redis'), {client: redis})
+  .register(require('fastify-caching'), {cache: abcache})
+
+fastify.get('/', (req, reply) => {
+  fastify.cache.set('hello', {hello: 'world'}, 10000, (err) => {
+    if (err) return reply.send(err)
+    reply.send({hello: 'world'})
+  })
+})
+
+fastify.listen(3000, (err) => {
+  if (err) throw err
+})
+```
+
+## API
+
+### Options
+
+*fastify-caching* accepts the options object:
+
+```js
+{
+  privacy: 'value',
+  expiresIn: 300,
+  cache: {get, set},
+  cacheSegment: 'segment-name'
+}
+```
+
++ `privacy` (Default: `undefined`): can be set to any string that is valid
+for a *cache-response-directive* as defined by RFC 2616.
++ `expiresIn` (Default: `undefined`): a value, in seconds, for the *max-age* the
+resource may be cached. When this is set, and `privacy` is not set to `no-cache`,
+then `', max-age=<value>'` will be appended to the `cache-control` header. 
++ `cache` (Default: `abstract-cache.memclient`): an [abstract-cache][acache]
+protocol compliant cache object. Note: the plugin requires a cache instance to
+properly support the ETag mechanism. Therefore, if a falsy value is supplied
+the default will be used.
++ `cacheSegment` (Default: `'fastify-caching'`): segment identifier to use when
+communicating with the cache.
++ `serverExpiresIn` (Default: `undefined`): a value, in seconds, for the length of time the resource is fresh and may be held in a shared cache (e.g. a CDN). Shared caches will ignore max-age when this is specified, though browsers will continue to use max-age. Should be used with expiresIn, not in place of it. When this is set, and `privacy` is set to `public`,  then `', s-maxage=<value>'` will be appended to the `cache-control` header.  
+
+[acache]: https://www.npmjs.com/package/abstract-cache
+
+### `reply.etag(string, number)`
+
+This method allows setting of the `etag` header. It accepts any arbitrary
+string. Be sure to supply a string that is valid for HTTP headers.
+
+If a tag string is not supplied then [uid-safe][uid-safe] will be used to
+generate a tag. This operation will be performed ***synchronously***. It is
+recommended to always supply a value to this method to avoid this operation.
+
+All incoming requests to paths affected by this plugin will be inspected for
+the `if-none-match` header. If the header is present, the value will be used
+to lookup the tag within the cache associated with this plugin. If the tag is
+found, then the response will be ended with a 304 status code sent to
+the client.
+
+Tags will be cached according to the second parameter. If the second parameter
+is supplied, and it is an integer, then it will be used as the time to cache
+the etag for generating 304 responses. The time must be specified in
+milliseconds. The default lifetime, when the parameter is not specified, is
+`3600000`.
+
+[uid-safe]: https://www.npmjs.com/package/uid-safe
+
+### `reply.expires(date)`
+
+This method allows setting of the `expires` header. It accepts a regular `Date`
+object, or a string that is a valid date string according to
+[RFC 2616 §14.21][sec14.21].
+
+[sec14.21]: https://tools.ietf.org/html/rfc2616#section-14.21
+
+## License
+
+[MIT License](https://jsumners.mit-license.org/)

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@fastify/caching",
+  "version": "7.0.0",
+  "description": "A plugin for Fastify to enable management of cache control headers",
+  "main": "plugin.js",
+  "types": "plugin.d.ts",
+  "scripts": {
+    "lint": "standard --verbose | snazzy",
+    "lint:ci": "standard",
+    "test": "npm run unit && npm run test:types",
+    "test:types": "tsd",
+    "unit": "tap -J \"test/*.test.js\"",
+    "unit:report": "npm run unit -- --coverage-report=html",
+    "unit:verbose": "npm run unit -- -Rspec"
+  },
+  "precommit": [
+    "lint",
+    "test"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/fastify/fastify-caching.git"
+  },
+  "keywords": [
+    "fastify",
+    "cache",
+    "caching"
+  ],
+  "author": "James Sumners <james.sumners@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/fastify/fastify-caching/issues"
+  },
+  "homepage": "https://github.com/fastify/fastify-caching#readme",
+  "devDependencies": {
+    "@types/node": "^17.0.21",
+    "fastify": "^3.27.2",
+    "pre-commit": "^1.2.2",
+    "snazzy": "^9.0.0",
+    "standard": "^17.0.0",
+    "tap": "^16.0.0",
+    "tsd": "^0.20.0"
+  },
+  "dependencies": {
+    "abstract-cache": "^1.0.1",
+    "fastify-plugin": "^3.0.1",
+    "uid-safe": "^2.1.5"
+  },
+  "tsd": {
+    "directory": "test/types"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.d.ts

@@ -0,0 +1,124 @@
+/// <reference types='node' />
+
+import { FastifyPluginCallback } from 'fastify';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    cache: AbstractCacheCompliantObject;
+    cacheSegment: string;
+    etagMaxLife: number | undefined;
+  }
+
+  interface FastifyReply {
+    /**
+     * This method allows setting of the `expires` header.
+     *
+     * @link [reply.expires() documentation](https://github.com/fastify/fastify-caching#replyexpiresdate)
+     *
+     * @param date A regular `Date` object, or a valid date string according to [RFC 2616 section 14.21](https://datatracker.ietf.org/doc/html/rfc2616#section-14.21).
+     */
+    expires(date?: Date): this;
+
+    /**
+     * This method allows setting of the `etag` header.
+     *
+     * @link [reply.etag() documentation](https://github.com/fastify/fastify-caching#replyetagstring-number)
+     *
+     * @param tag Any arbitrary string that is valid for HTTP headers.
+     * @param timeToLive The time must be specified in milliseconds. The default lifetime, when the parameter is not specified, is `3600000`.
+     */
+    etag(tag?: string, timeToLive?: number): this;
+  }
+}
+
+/**
+ * @link [`abstract-cache` protocol documentation](https://github.com/jsumners/abstract-cache#protocol)
+ */
+export interface AbstractCacheCompliantObject {
+  get(
+    key: string | { id: string; segment: string },
+    callback?: (error: unknown, result: unknown) => void
+  ): void;
+  set(
+    key: string | { id: string; segment: string },
+    value: unknown,
+    timeToLive: number,
+    callback?: (error: unknown, result: unknown) => void
+  ): void;
+}
+
+export interface Privacy {
+  NOCACHE: 'no-cache';
+  PRIVATE: 'private';
+  PUBLIC: 'public';
+}
+
+/**
+ * @link [`fastify-caching` options documentation](https://github.com/fastify/fastify-caching#options)
+ */
+export interface FastifyCachingPluginOptions {
+  /**
+   * An [abstract-cache](https://www.npmjs.com/package/abstract-cache) protocol compliant cache object.
+   * Note: the plugin requires a cache instance to properly support the ETag mechanism.
+   * Therefore, if a falsy value is supplied the default will be used.
+   *
+   * - Default value: `abstract-cache.memclient`
+   */
+  cache?: AbstractCacheCompliantObject;
+
+  /**
+   * The segment identifier to use when communicating with the cache.
+   *
+   * - Default value: `fastify-caching`
+   */
+  cacheSegment?: string;
+
+  etagMaxLife?: number;
+
+  /**
+   * A value, in seconds, for the max-age the resource may be cached.
+   * When this is set, and privacy is not set to no-cache, then ', max-age=<value>'
+   * will be appended to the cache-control header.
+   *
+   * - Default value: `undefined`
+   */
+  expiresIn?: number;
+
+  /**
+   * It can be set to any string that is valid for a cache-response-directive as
+   * defined by [RFC 2616](https://datatracker.ietf.org/doc/html/rfc2616#section-14.9).
+   *
+   * - Default value: `undefined`
+   *
+   * @link [MDN Cache-Control - Response Directives](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#response_directives)
+   *
+   * @example
+   * const fastifyCaching = require('fastify-caching');
+   *
+   * // Disabling client side caching of all routes.
+   * fastify.register(fastifyCaching, { privacy: fastifyCaching.privacy.NOCACHE });
+   */
+  privacy?: string;
+
+  /**
+   * A value, in seconds, for the length of time the resource is fresh and may be
+   * held in a shared cache (e.g. a CDN). Shared caches will ignore max-age when
+   * this is specified, though browsers will continue to use max-age. Should be
+   * used with expiresIn, not in place of it. When this is set, and privacy is set
+   * to public, then ', s-maxage=<value>' will be appended to the cache-control header.
+   *
+   * - Default value: `undefined`
+   */
+  serverExpiresIn?: number;
+}
+
+declare const fastifyCaching: FastifyPluginCallback<FastifyCachingPluginOptions> & {
+  privacy: Privacy;
+};
+
+declare const privacy: {
+  privacy: Privacy;
+};
+
+export default fastifyCaching;
+export { fastifyCaching, privacy };

package/plugin.js

@@ -0,0 +1,104 @@
+'use strict'
+
+/* eslint no-prototype-builtins: 0 */
+
+const fp = require('fastify-plugin')
+const uidSafe = require('uid-safe')
+const abstractCache = require('abstract-cache')
+
+const defaultOptions = {
+  expiresIn: undefined,
+  serverExpiresIn: undefined,
+  privacy: undefined,
+  cache: undefined,
+  cacheSegment: 'fastify-caching'
+}
+
+function cachingExpires (date) {
+  if (!date) return this
+  this.header('Expires', (Date.prototype.isPrototypeOf(date)) ? date.toUTCString() : date)
+  return this
+}
+
+function etag (value, lifetime) {
+  if (value) {
+    this.header('ETag', value)
+  } else {
+    this.header('ETag', uidSafe.sync(18))
+  }
+  this._etagLife = Number.isInteger(lifetime) ? lifetime : 3600000
+  return this
+}
+
+function etagHandleRequest (req, res, next) {
+  if (!req.headers['if-none-match']) return next()
+  const etag = req.headers['if-none-match']
+  this.cache.get({ id: etag, segment: this.cacheSegment }, (err, cached) => {
+    if (err) return next(err)
+    if (cached && cached.item) {
+      return res.status(304).send()
+    }
+    next()
+  })
+}
+
+function etagOnSend (req, res, payload, next) {
+  const etag = res.getHeader('etag')
+  if (!etag || !res._etagLife) return next()
+  this.cache.set(
+    { id: etag, segment: this.cacheSegment },
+    true,
+    res._etagLife,
+    (err) => next(err, payload)
+  )
+}
+
+function fastifyCachingPlugin (instance, options, next) {
+  let _options
+  if (Function.prototype.isPrototypeOf(options)) {
+    _options = Object.assign({}, defaultOptions)
+  } else {
+    _options = Object.assign({}, defaultOptions, options)
+  }
+
+  if (!_options.cache) _options.cache = abstractCache()
+
+  if (_options.privacy) {
+    // https://tools.ietf.org/html/rfc2616#section-14.9.4
+    let value = _options.privacy
+    if (_options.privacy.toLowerCase() !== 'no-cache' && _options.expiresIn) {
+      value = `${_options.privacy}, max-age=${_options.expiresIn}`
+    }
+
+    if (_options.privacy !== undefined && _options.privacy.toLowerCase() === 'public' && _options.serverExpiresIn) {
+      value += `, s-maxage=${_options.serverExpiresIn}`
+    }
+
+    instance.addHook('onRequest', (req, res, next) => {
+      res.header('Cache-control', value)
+      next()
+    })
+  }
+
+  instance.decorate('cache', _options.cache)
+  instance.decorate('cacheSegment', _options.cacheSegment)
+  instance.decorate('etagMaxLife', _options.etagMaxLife)
+  instance.decorateReply('etag', etag)
+  instance.decorateReply('expires', cachingExpires)
+  instance.addHook('onRequest', etagHandleRequest)
+  instance.addHook('onSend', etagOnSend)
+
+  instance[Symbol.for('fastify-caching.registered')] = true
+  next()
+}
+
+module.exports = fp(fastifyCachingPlugin, {
+  fastify: '^3.0.0',
+  name: 'fastify-caching'
+})
+
+module.exports.privacy = {
+  NOCACHE: 'no-cache',
+  PUBLIC: 'public',
+  PRIVATE: 'private'
+}

package/test/cache.test.js

@@ -0,0 +1,256 @@
+'use strict'
+
+const { test } = require('tap')
+const plugin = require('../plugin')
+
+const Fastify = require('fastify')
+
+test('cache property gets added to instance', async (t) => {
+  t.plan(2)
+
+  const fastify = Fastify()
+  await fastify.register(plugin)
+  await fastify.ready()
+
+  t.ok(fastify.cache)
+  t.ok(fastify.cache.set)
+})
+
+test('cache is usable', async (t) => {
+  t.plan(4)
+
+  const fastify = Fastify()
+  await fastify.register(async (instance, options) => {
+    instance.addHook('onRequest', async function (req, reply) {
+      t.notOk(instance[Symbol.for('fastify-caching.registered')])
+    })
+  })
+  await fastify.register(plugin)
+
+  fastify.addHook('onRequest', async function (req, reply) {
+    t.equal(this[Symbol.for('fastify-caching.registered')], true)
+  })
+
+  fastify.get('/one', (req, reply) => {
+    fastify.cache.set('one', { one: true }, 1000, (err) => {
+      if (err) return reply.send(err)
+      reply.redirect('/two')
+    })
+  })
+
+  fastify.get('/two', (req, reply) => {
+    fastify.cache.get('one', (err, obj) => {
+      t.error(err)
+      t.same(obj.item, { one: true })
+
+      reply.send()
+    })
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/one'
+  })
+
+  if (
+    response.statusCode > 300 &&
+    response.statusCode < 400 &&
+    response.headers.location
+  ) {
+    await fastify.inject({
+      method: 'GET',
+      path: response.headers.location
+    })
+  }
+})
+
+test('cache is usable with function as plugin default options input', async (t) => {
+  t.plan(4)
+
+  const fastify = Fastify()
+  await fastify.register(async (instance, options) => {
+    instance.addHook('onRequest', async function (req, reply) {
+      t.notOk(instance[Symbol.for('fastify-caching.registered')])
+    })
+  })
+  await fastify.register(plugin, () => () => { })
+
+  fastify.addHook('onRequest', async function (req, reply) {
+    t.equal(this[Symbol.for('fastify-caching.registered')], true)
+  })
+
+  fastify.get('/one', (req, reply) => {
+    fastify.cache.set('one', { one: true }, 1000, (err) => {
+      if (err) return reply.send(err)
+      reply.redirect('/two')
+    })
+  })
+
+  fastify.get('/two', (req, reply) => {
+    fastify.cache.get('one', (err, obj) => {
+      t.error(err)
+      t.same(obj.item, { one: true })
+
+      reply.send()
+    })
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/one'
+  })
+
+  if (
+    response.statusCode > 300 &&
+    response.statusCode < 400 &&
+    response.headers.location
+  ) {
+    await fastify.inject({
+      method: 'GET',
+      path: response.headers.location
+    })
+  }
+})
+
+test('getting cache item with error returns error', async (t) => {
+  t.plan(1)
+
+  const mockCache = {
+    get: (info, callback) => callback(new Error('cache.get always errors')),
+    set: (key, value, ttl, callback) => callback()
+  }
+
+  const fastify = Fastify()
+  await fastify.register(plugin, { cache: mockCache })
+
+  fastify.get('/one', (req, reply) => {
+    fastify.cache.set('one', { one: true }, 1000, (err) => {
+      if (err) return reply.send(err)
+      return reply
+        .etag('123456')
+        .send({ hello: 'world' })
+    })
+  })
+
+  fastify.get('/two', (req, reply) => {
+    fastify.cache.get('one', (err, obj) => {
+      t.notOk(err)
+      t.notOk(obj)
+    })
+  })
+
+  await fastify.ready()
+
+  await fastify.inject({
+    method: 'GET',
+    path: '/one'
+  })
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/two',
+    headers: {
+      'if-none-match': '123456'
+    }
+  })
+  t.equal(response.statusCode, 500)
+})
+
+test('etags get stored in cache', async (t) => {
+  t.plan(1)
+
+  const fastify = Fastify()
+  await fastify.register(plugin)
+
+  fastify.get('/one', (req, reply) => {
+    reply
+      .etag('123456')
+      .send({ hello: 'world' })
+  })
+
+  await fastify.ready()
+
+  await fastify.inject({
+    method: 'GET',
+    path: '/one'
+  })
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/one',
+    headers: {
+      'if-none-match': '123456'
+    }
+  })
+  t.equal(response.statusCode, 304)
+})
+
+test('etag cache life is customizable', (t) => {
+  t.plan(4)
+
+  const fastify = Fastify()
+  fastify.register(plugin)
+
+  fastify.get('/one', function (req, reply) {
+    reply
+      // We set a cache lifetime of 50 milliseconds
+      .etag('123456', 50)
+      .send({ hello: 'world' })
+  })
+
+  fastify.ready((err) => {
+    t.error(err)
+
+    fastify.inject({
+      method: 'GET',
+      path: '/one'
+    }, (err, _response) => {
+      t.error(err)
+
+      // We wait 70 milliseconds that the cache expires
+      setTimeout(() => {
+        fastify.inject({
+          method: 'GET',
+          path: '/one',
+          headers: {
+            'if-none-match': '123456'
+          }
+        }, (err, response) => {
+          t.error(err)
+          t.equal(response.statusCode, 200)
+        })
+      }, 70)
+    })
+  })
+})
+
+test('returns response payload', async (t) => {
+  t.plan(1)
+
+  const fastify = Fastify()
+  await fastify.register(plugin)
+
+  fastify.get('/one', (req, reply) => {
+    reply
+      .etag('123456', 300)
+      .send({ hello: 'world' })
+  })
+
+  await fastify.ready()
+
+  await fastify.inject({
+    method: 'GET',
+    path: '/one'
+  })
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/one'
+  })
+
+  t.same(JSON.parse(response.payload), { hello: 'world' })
+})

package/test/headers.test.js

@@ -0,0 +1,278 @@
+'use strict'
+
+const { test } = require('tap')
+const Fastify = require('fastify')
+const plugin = require('../plugin')
+
+test('decorators get added', async (t) => {
+  t.plan(1)
+
+  const fastify = Fastify()
+  await fastify.register(plugin)
+
+  fastify.get('/', (req, reply) => {
+    t.ok(reply.etag)
+    reply.send()
+  })
+
+  await fastify.ready()
+
+  await fastify.inject({
+    method: 'GET',
+    path: '/'
+  })
+})
+
+test('decorators add headers', async (t) => {
+  t.plan(2)
+
+  const tag = '123456'
+
+  const fastify = Fastify()
+  await fastify.register(plugin)
+
+  fastify.get('/', (req, reply) => {
+    reply
+      .etag(tag)
+      .send()
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/'
+  })
+  t.ok(response.headers.etag)
+  t.equal(response.headers.etag, tag)
+})
+
+test('sets etag header for falsy argument', async (t) => {
+  t.plan(1)
+
+  const fastify = Fastify()
+  await fastify.register(plugin)
+
+  fastify.get('/', (req, reply) => {
+    reply
+      .etag()
+      .send()
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/'
+  })
+  t.ok(response.headers.etag)
+})
+
+test('sets no-cache header', async (t) => {
+  t.plan(2)
+
+  const fastify = Fastify()
+  await fastify.register(plugin, { privacy: plugin.privacy.NOCACHE })
+
+  fastify.get('/', (req, reply) => {
+    reply.send({ hello: 'world' })
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/'
+  })
+  t.ok(response.headers['cache-control'])
+  t.equal(response.headers['cache-control'], 'no-cache')
+})
+
+test('sets private with max-age header', async (t) => {
+  t.plan(2)
+
+  const opts = {
+    privacy: plugin.privacy.PRIVATE,
+    expiresIn: 300
+  }
+
+  const fastify = Fastify()
+  await fastify.register(plugin, opts)
+
+  fastify.get('/', (req, reply) => {
+    reply.send({ hello: 'world' })
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/'
+  })
+  t.ok(response.headers['cache-control'])
+  t.equal(response.headers['cache-control'], 'private, max-age=300')
+})
+
+test('sets public with max-age and s-maxage header', async (t) => {
+  t.plan(2)
+
+  const opts = {
+    privacy: plugin.privacy.PUBLIC,
+    expiresIn: 300,
+    serverExpiresIn: 12345
+  }
+
+  const fastify = Fastify()
+  await fastify.register(plugin, opts)
+
+  fastify.get('/', (req, reply) => {
+    reply.send({ hello: 'world' })
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/'
+  })
+  t.ok(response.headers['cache-control'])
+  t.equal(response.headers['cache-control'], 'public, max-age=300, s-maxage=12345')
+})
+
+test('only sets max-age and ignores s-maxage with private header', async (t) => {
+  t.plan(2)
+
+  const opts = {
+    privacy: plugin.privacy.PRIVATE,
+    expiresIn: 300,
+    serverExpiresIn: 12345
+  }
+
+  const fastify = Fastify()
+  await fastify.register(plugin, opts)
+
+  fastify.get('/', (req, reply) => {
+    reply.send({ hello: 'world' })
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/'
+  })
+  t.ok(response.headers['cache-control'])
+  t.equal(response.headers['cache-control'], 'private, max-age=300')
+})
+
+test('s-maxage is optional with public header', async (t) => {
+  t.plan(2)
+
+  const opts = {
+    privacy: plugin.privacy.PUBLIC,
+    expiresIn: 300
+  }
+
+  const fastify = Fastify()
+  await fastify.register(plugin, opts)
+
+  fastify.get('/', (req, reply) => {
+    reply.send({ hello: 'world' })
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/'
+  })
+  t.ok(response.headers['cache-control'])
+  t.equal(response.headers['cache-control'], 'public, max-age=300')
+})
+
+test('sets no-store with max-age header', async (t) => {
+  t.plan(2)
+
+  const fastify = Fastify()
+  await fastify.register(plugin, { privacy: 'no-store', expiresIn: 300 })
+
+  fastify.get('/', (req, reply) => {
+    reply.send({ hello: 'world' })
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/'
+  })
+  t.ok(response.headers['cache-control'])
+  t.equal(response.headers['cache-control'], 'no-store, max-age=300')
+})
+
+test('sets the expires header', async (t) => {
+  t.plan(2)
+
+  const now = new Date()
+
+  const fastify = Fastify()
+  await fastify.register(plugin, { privacy: plugin.privacy.NOCACHE })
+
+  fastify.get('/', (req, reply) => {
+    reply
+      .expires(now)
+      .send({ hello: 'world' })
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/'
+  })
+  t.ok(response.headers.expires)
+  t.equal(response.headers.expires, now.toUTCString())
+})
+
+test('sets the expires header to a falsy value', async (t) => {
+  t.plan(1)
+
+  const fastify = Fastify()
+  await fastify.register(plugin, { privacy: plugin.privacy.NOCACHE })
+
+  fastify.get('/', (req, reply) => {
+    reply
+      .expires()
+      .send({ hello: 'world' })
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/'
+  })
+  t.notOk(response.headers.expires)
+})
+
+test('sets the expires header to a custom value', async (t) => {
+  t.plan(2)
+
+  const fastify = Fastify()
+  await fastify.register(plugin, { privacy: plugin.privacy.NOCACHE })
+
+  fastify.get('/', (req, reply) => {
+    reply
+      .expires('foobar')
+      .send({ hello: 'world' })
+  })
+
+  await fastify.ready()
+
+  const response = await fastify.inject({
+    method: 'GET',
+    path: '/'
+  })
+  t.ok(response.headers.expires)
+  t.equal(response.headers.expires, 'foobar')
+})

package/test/types/plugin.test-d.ts

@@ -0,0 +1,52 @@
+import Fastify, { FastifyReply } from 'fastify';
+import { expectAssignable, expectError, expectType } from 'tsd';
+import fastifyCaching, {
+  AbstractCacheCompliantObject,
+  FastifyCachingPluginOptions,
+} from '../..';
+
+const fastify = Fastify({ logger: true });
+
+const cachingOptions: FastifyCachingPluginOptions = {
+  privacy: fastifyCaching.privacy.PUBLIC,
+  expiresIn: 300,
+  cacheSegment: 'fastify-caching',
+};
+expectAssignable<FastifyCachingPluginOptions>(cachingOptions);
+
+fastify.register(fastifyCaching, cachingOptions);
+
+expectType<AbstractCacheCompliantObject>(fastify.cache);
+expectType<AbstractCacheCompliantObject['get']>(fastify.cache.get);
+expectType<AbstractCacheCompliantObject['set']>(fastify.cache.set);
+expectType<string>(fastify.cacheSegment);
+// expectType<number>(fastify.etagMaxLife);
+
+fastify.get('/one', async (request, reply) => {
+  expectType<(tag?: string, timeToLive?: number) => FastifyReply>(reply.etag);
+  expectType<(date?: Date) => FastifyReply>(reply.expires);
+
+  expectType<FastifyReply>(reply.etag('hello', 6000));
+  expectType<FastifyReply>(reply.expires(new Date(Date.now() + 6000)));
+
+  return { message: 'one' };
+});
+
+fastify.get('/two', async (request, reply) => {
+  expectType<FastifyReply>(
+    reply.etag('hello', 6000).expires(new Date(Date.now() + 6000))
+  );
+
+  return { message: 'two' };
+});
+
+// We register a new instance that should trigger a typescript error.
+const shouldErrorApp = Fastify({ logger: true });
+
+const badCachingOptions = {
+  privacy: fastifyCaching.privacy.PRIVATE,
+  expiresIn: 'a string instead of a number of second',
+  cacheSegment: 'fastify-caching',
+};
+
+expectError(shouldErrorApp.register(fastifyCaching, badCachingOptions));