@fastify/cookie 9.2.0 → 9.3.1

package/README.md

@@ -4,13 +4,15 @@
 [![NPM version](https://img.shields.io/npm/v/@fastify/cookie.svg?style=flat)](https://www.npmjs.com/package/@fastify/cookie)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
 
-A plugin for [Fastify](http://fastify.io/) that adds support for reading and
+A plugin for [Fastify](http://fastify.dev/) that adds support for reading and
 setting cookies.
 
 This plugin's cookie parsing works via Fastify's `onRequest` hook. Therefore,
 you should register it prior to any other `onRequest` hooks that will depend
 upon this plugin's actions.
 
+It is also possible to [import the low-level cookie parsing and serialization functions](#importing-serialize-and-parse).
+
 `@fastify/cookie` [v2.x](https://github.com/fastify/fastify-cookie/tree/v2.x)
 supports both Fastify@1 and Fastify@2.
 `@fastify/cookie` v3 only supports Fastify@2.
@@ -70,6 +72,23 @@ app.register(cookie, {
 } as FastifyCookieOptions)
 ```
 
+## Importing `serialize` and `parse`
+
+```js
+const { serialize, parse } = require('@fastify/cookie')
+const fastify = require('fastify')()
+
+fastify.get('/', (req, reply) => {
+  const cookie = serialize('lang', 'en', {
+    maxAge: 60_000,
+  })
+
+  reply.header('Set-Cookie', cookie)
+
+  reply.send('Language set!')
+})
+```
+
 ## Options
 
 - `secret` (`String` | `Array` | `Buffer` | `Object`):
@@ -132,6 +151,20 @@ attribute. When truthy, the `Partitioned` attribute is set, otherwise it is not.
 
 More information about can be found in [the proposal](https://github.com/privacycg/CHIPS).
 
+
+##### priority
+
+Specifies the `string` to be the value for the [`Priority` `Set-Cookie` attribute](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).
+
+  - `'low'` will set the `Priority` attribute to `Low`.
+  - `'medium'` will set the `Priority` attribute to `Medium`, the default priority when not set.
+  - `'high'` will set the `Priority` attribute to `High`.
+
+More information about the different priority levels can be found in
+[the specification](https://tools.ietf.org/html/draft-west-cookie-priority-00#section-4.1).
+
+⚠️ **Warning:** This is an attribute that has not yet been fully standardized, and may change in the future without reflecting the semver versioning. This also means many clients may ignore the attribute until they understand it.
+
 ##### path
 
 Specifies the value for the [`Path` `Set-Cookie` attribute](https://datatracker.ietf.org/doc/html/rfc6265#section-5.2.4). By default, the path

package/cookie.js

@@ -28,22 +28,6 @@
 
 'use strict'
 
-/**
- * Module exports.
- * @public
- */
-
-exports.parse = parse
-exports.serialize = serialize
-
-/**
- * Module variables.
- * @private
- */
-
-const decode = decodeURIComponent
-const encode = encodeURIComponent
-
 /**
  * RegExp to match field-content in RFC 7230 sec 3.2
  *
@@ -61,51 +45,49 @@ const fieldContentRegExp = /^[\u0009\u0020-\u007e\u0080-\u00ff]+$/ // eslint-dis
  * The object has the various cookies as keys(names) => values
  *
  * @param {string} str
- * @param {object} [options]
+ * @param {object} [opt]
  * @return {object}
  * @public
  */
 
-function parse (str, options) {
+function parse (str, opt) {
   if (typeof str !== 'string') {
     throw new TypeError('argument str must be a string')
   }
 
+  const dec = opt?.decode || decodeURIComponent
   const result = {}
-  const dec = (options && options.decode) || decode
 
+  const strLen = str.length
   let pos = 0
   let terminatorPos = 0
-  let eqIdx = 0
-
   while (true) {
-    if (terminatorPos === str.length) {
-      break
-    }
+    if (terminatorPos === strLen) break
     terminatorPos = str.indexOf(';', pos)
-    terminatorPos = (terminatorPos === -1) ? str.length : terminatorPos
-    eqIdx = str.indexOf('=', pos)
+    if (terminatorPos === -1) terminatorPos = strLen // This is the last pair
 
-    // skip things that don't look like key=value
-    if (eqIdx === -1 || eqIdx > terminatorPos) {
+    let eqIdx = str.indexOf('=', pos)
+    if (eqIdx === -1) break // No key-value pairs left
+    if (eqIdx > terminatorPos) {
+      // Malformed key-value pair
       pos = terminatorPos + 1
       continue
     }
 
     const key = str.substring(pos, eqIdx++).trim()
-
-    // only assign once
     if (result[key] === undefined) {
-      const val = (str.charCodeAt(eqIdx) === 0x22)
+      const val = str.charCodeAt(eqIdx) === 0x22
         ? str.substring(eqIdx + 1, terminatorPos - 1).trim()
         : str.substring(eqIdx, terminatorPos).trim()
 
-      result[key] = (dec !== decode || val.indexOf('%') !== -1)
+      result[key] = !(dec === decodeURIComponent && val.indexOf('%') === -1)
         ? tryDecode(val, dec)
         : val
     }
+
     pos = terminatorPos + 1
   }
+
   return result
 }
 
@@ -120,19 +102,18 @@ function parse (str, options) {
  *
  * @param {string} name
  * @param {string} val
- * @param {object} [options]
+ * @param {object} [opt]
  * @return {string}
  * @public
  */
 
-function serialize (name, val, options) {
-  const opt = options || {}
-  const enc = opt.encode || encode
+function serialize (name, val, opt) {
+  const enc = opt?.encode || encodeURIComponent
   if (typeof enc !== 'function') {
     throw new TypeError('option encode is invalid')
   }
 
-  if (!fieldContentRegExp.test(name)) {
+  if (name && !fieldContentRegExp.test(name)) {
     throw new TypeError('argument name is invalid')
   }
 
@@ -142,13 +123,17 @@ function serialize (name, val, options) {
   }
 
   let str = name + '=' + value
+
+  if (opt == null) return str
+
   if (opt.maxAge != null) {
-    const maxAge = opt.maxAge - 0
-    if (isNaN(maxAge) || !isFinite(maxAge)) {
+    const maxAge = +opt.maxAge
+
+    if (!isFinite(maxAge)) {
       throw new TypeError('option maxAge is invalid')
     }
 
-    str += '; Max-Age=' + Math.floor(maxAge)
+    str += '; Max-Age=' + Math.trunc(maxAge)
   }
 
   if (opt.domain) {
@@ -167,6 +152,26 @@ function serialize (name, val, options) {
     str += '; Path=' + opt.path
   }
 
+  if (opt.priority) {
+    const priority = typeof opt.priority === 'string'
+      ? opt.priority.toLowerCase()
+      : opt.priority
+
+    switch (priority) {
+      case 'low':
+        str += '; Priority=Low'
+        break
+      case 'medium':
+        str += '; Priority=Medium'
+        break
+      case 'high':
+        str += '; Priority=High'
+        break
+      default:
+        throw new TypeError('option priority is invalid')
+    }
+  }
+
   if (opt.expires) {
     if (typeof opt.expires.toUTCString !== 'function') {
       throw new TypeError('option expires is invalid')
@@ -193,6 +198,7 @@ function serialize (name, val, options) {
     const sameSite = typeof opt.sameSite === 'string'
       ? opt.sameSite.toLowerCase()
       : opt.sameSite
+
     switch (sameSite) {
       case true:
         str += '; SameSite=Strict'
@@ -219,13 +225,23 @@ function serialize (name, val, options) {
  *
  * @param {string} str
  * @param {function} decode
+ * @returns {string}
  * @private
  */
-
 function tryDecode (str, decode) {
   try {
     return decode(str)
-  } catch (e) {
+  } catch {
     return str
   }
 }
+
+/**
+ * Module exports.
+ * @public
+ */
+
+module.exports = {
+  parse,
+  serialize
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastify/cookie",
-  "version": "9.2.0",
+  "version": "9.3.1",
   "description": "Plugin for fastify to add support for cookies",
   "main": "plugin.js",
   "type": "commonjs",
@@ -48,7 +48,7 @@
     "snazzy": "^9.0.0",
     "standard": "^17.0.0",
     "tap": "^16.0.0",
-    "tsd": "^0.29.0"
+    "tsd": "^0.30.0"
   },
   "dependencies": {
     "fastify-plugin": "^4.0.0",

package/plugin.js

@@ -70,32 +70,31 @@ function onReqHandlerWrapper (fastify, hook) {
 }
 
 function setCookies (reply) {
-  let setCookie = reply.getHeader('Set-Cookie')
-  const setCookieIsUndefined = setCookie === undefined
+  const setCookieHeaderValue = reply.getHeader('Set-Cookie')
+  let cookieValue
 
-  /* istanbul ignore else */
-  if (setCookieIsUndefined) {
+  if (setCookieHeaderValue === undefined) {
     if (reply[kReplySetCookies].size === 1) {
-      for (const c of reply[kReplySetCookies].values()) {
-        reply.header('Set-Cookie', cookie.serialize(c.name, c.value, c.opts))
-      }
-
+      // Fast path for single cookie
+      const c = reply[kReplySetCookies].values().next().value
+      reply.header('Set-Cookie', cookie.serialize(c.name, c.value, c.opts))
       reply[kReplySetCookies].clear()
-
       return
     }
 
-    setCookie = []
-  } else if (typeof setCookie === 'string') {
-    setCookie = [setCookie]
+    cookieValue = []
+  } else if (typeof setCookieHeaderValue === 'string') {
+    cookieValue = [setCookieHeaderValue]
+  } else {
+    cookieValue = setCookieHeaderValue
   }
 
   for (const c of reply[kReplySetCookies].values()) {
-    setCookie.push(cookie.serialize(c.name, c.value, c.opts))
+    cookieValue.push(cookie.serialize(c.name, c.value, c.opts))
   }
 
-  if (!setCookieIsUndefined) reply.removeHeader('Set-Cookie')
-  reply.header('Set-Cookie', setCookie)
+  reply.removeHeader('Set-Cookie')
+  reply.header('Set-Cookie', cookieValue)
   reply[kReplySetCookies].clear()
 }
 
@@ -214,6 +213,9 @@ module.exports = fastifyCookie
 module.exports.default = fastifyCookie // supersedes fastifyCookie.default = fastifyCookie
 module.exports.fastifyCookie = fastifyCookie // supersedes fastifyCookie.fastifyCookie = fastifyCookie
 
+module.exports.serialize = cookie.serialize
+module.exports.parse = cookie.parse
+
 module.exports.signerFactory = Signer
 module.exports.Signer = Signer
 module.exports.sign = sign

package/test/cookie-module.test.js

@@ -3,7 +3,7 @@
 const tap = require('tap')
 const test = tap.test
 
-const cookie = require('../cookie')
+const cookie = require('..')
 
 test('parse: argument validation', (t) => {
   t.plan(2)
@@ -203,3 +203,21 @@ test('unencoded', (t) => {
   }), /argument val is invalid/)
   t.end()
 })
+
+test('serializer: priority', (t) => {
+  t.plan(8)
+  t.same(cookie.serialize('foo', 'bar', { priority: 'Low' }), 'foo=bar; Priority=Low')
+  t.same(cookie.serialize('foo', 'bar', { priority: 'low' }), 'foo=bar; Priority=Low')
+  t.same(cookie.serialize('foo', 'bar', { priority: 'Medium' }), 'foo=bar; Priority=Medium')
+  t.same(cookie.serialize('foo', 'bar', { priority: 'medium' }), 'foo=bar; Priority=Medium')
+  t.same(cookie.serialize('foo', 'bar', { priority: 'High' }), 'foo=bar; Priority=High')
+  t.same(cookie.serialize('foo', 'bar', { priority: 'high' }), 'foo=bar; Priority=High')
+
+  t.throws(cookie.serialize.bind(cookie, 'foo', 'bar', {
+    priority: 'foo'
+  }), /option priority is invalid/)
+  t.throws(cookie.serialize.bind(cookie, 'foo', 'bar', {
+    priority: true
+  }), /option priority is invalid/)
+  t.end()
+})

package/test/cookie.test.js

@@ -132,6 +132,39 @@ test('should set multiple cookies', (t) => {
   })
 })
 
+test('should set multiple cookies (an array already exists)', (t) => {
+  t.plan(10)
+  const fastify = Fastify()
+  fastify.register(plugin)
+
+  fastify.get('/test1', (req, reply) => {
+    reply
+      .header('Set-Cookie', ['bar=bar'])
+      .setCookie('foo', 'foo', { path: '/' })
+      .setCookie('foo', 'foo', { path: '/path' })
+      .send({ hello: 'world' })
+  })
+
+  fastify.inject({
+    method: 'GET',
+    url: '/test1'
+  }, (err, res) => {
+    t.error(err)
+    t.equal(res.statusCode, 200)
+    t.same(JSON.parse(res.body), { hello: 'world' })
+
+    const cookies = res.cookies
+    t.equal(cookies.length, 3)
+    t.equal(cookies[0].name, 'bar')
+    t.equal(cookies[0].value, 'bar')
+    t.equal(cookies[0].path, undefined)
+
+    t.equal(cookies[1].name, 'foo')
+    t.equal(cookies[1].value, 'foo')
+    t.equal(cookies[2].path, '/path')
+  })
+})
+
 test('cookies get set correctly with millisecond dates', (t) => {
   t.plan(8)
   const fastify = Fastify()

package/types/plugin.d.ts

@@ -65,11 +65,7 @@ declare module "fastify" {
      * @param value Cookie value
      * @param options Serialize options
      */
-    setCookie(
-      name: string,
-      value: string,
-      options?: fastifyCookie.CookieSerializeOptions
-    ): this;
+    setCookie: setCookieWrapper;
 
     /**
      * @alias setCookie
@@ -119,18 +115,21 @@ declare namespace fastifyCookie {
     domain?: string;
     /** Specifies a function that will be used to encode a cookie's value. Since value of a cookie has a limited character set (and must be a simple string), this function can be used to encode a value into a string suited for a cookie's value. */
     encode?(val: string): string;
-    /**  The expiration `date` used for the `Expires` attribute. If both `expires` and `maxAge` are set, then `expires` is used. */
+    /** The expiration `date` used for the `Expires` attribute. If both `expires` and `maxAge` are set, then `expires` is used. */
     expires?: Date;
-    /**  The `boolean` value of the `HttpOnly` attribute. Defaults to true. */
+    /** The `boolean` value of the `HttpOnly` attribute. Defaults to true. */
     httpOnly?: boolean;
-    /**  A `number` in seconds that specifies the `Expires` attribute by adding the specified seconds to the current date. If both `expires` and `maxAge` are set, then `expires` is used. */
+    /** A `number` in seconds that specifies the `Expires` attribute by adding the specified seconds to the current date. If both `expires` and `maxAge` are set, then `expires` is used. */
     maxAge?: number;
+    /** A `boolean` indicating whether the cookie is tied to the top-level site where it's initially set and cannot be accessed from elsewhere. */
     partitioned?: boolean;
-    /**  The `Path` attribute. Defaults to `/` (the root path).  */
+    /** The `Path` attribute. Defaults to `/` (the root path).  */
     path?: string;
     /** A `boolean` or one of the `SameSite` string attributes. E.g.: `lax`, `none` or `strict`.  */
     sameSite?: 'lax' | 'none' | 'strict' | boolean;
-    /**  The `boolean` value of the `Secure` attribute. Set this option to false when communicating over an unencrypted (HTTP) connection. Value can be set to `auto`; in this case the `Secure` attribute will be set to false for HTTP request, in case of HTTPS it will be set to true.  Defaults to true. */
+    /** One of the `Priority` string attributes (`low`, `medium` or `high`) specifying a retention priority for HTTP cookies that will be respected by user agents during cookie eviction. */
+    priority?: 'low' | 'medium' | 'high';
+    /** The `boolean` value of the `Secure` attribute. Set this option to false when communicating over an unencrypted (HTTP) connection. Value can be set to `auto`; in this case the `Secure` attribute will be set to false for HTTP request, in case of HTTPS it will be set to true.  Defaults to true. */
     secure?: boolean;
   }
 
@@ -139,6 +138,10 @@ declare namespace fastifyCookie {
     signed?: boolean;
   }
 
+  export interface ParseOptions {
+    decode?: (encodedURIComponent: string) => string;
+  }
+
   type HookType = 'onRequest' | 'preParsing' | 'preValidation' | 'preHandler'  | 'preSerialization';
 
   export interface FastifyCookieOptions {
@@ -162,6 +165,8 @@ declare namespace fastifyCookie {
   export const unsign: Unsign;
 
   export interface FastifyCookie extends FastifyCookiePlugin {
+    parse: (cookieHeader: string, opts?: ParseOptions) => { [key: string]: string };
+    serialize: (name: string, value: string, opts?: SerializeOptions) => string;
     signerFactory: SignerFactory;
     Signer: Signer;
     sign: Sign;

package/types/plugin.test-d.ts

@@ -232,3 +232,6 @@ appWithHook.register(cookie, { hook: 'preSerialization' });
 appWithHook.register(cookie, { hook: 'preValidation' });
 expectError(appWithHook.register(cookie, { hook: true }));
 expectError(appWithHook.register(cookie, { hook: 'false' }));
+
+expectType<(cookieHeader: string, opts?: fastifyCookieStar.ParseOptions) => { [key: string]: string }>(fastifyCookieDefault.parse);
+expectType<(name: string, value: string, opts?: fastifyCookieStar.SerializeOptions) => string>(fastifyCookieDefault.serialize);