undici 5.13.0 → 5.15.0

package/docs/api/Connector.md

@@ -24,8 +24,10 @@ Once you call `buildConnector`, it will return a connector function, which takes
 * **hostname** `string` (required)
 * **host** `string` (optional)
 * **protocol** `string` (required)
-* **port** `number` (required)
+* **port** `string` (required)
 * **servername** `string` (optional)
+* **localAddress** `string | null` (optional) Local address the socket should connect from.
+* **httpSocket** `Socket` (optional) Establish secure connection on a given socket rather than creating a new socket. It can only be sent on TLS update.
 
 ### Basic example
 

package/docs/api/Cookies.md

@@ -0,0 +1,101 @@
+# Cookie Handling
+
+## `Cookie` interface
+
+* **name** `string`
+* **value** `string`
+* **expires** `Date|number` (optional)
+* **maxAge** `number` (optional)
+* **domain** `string` (optional)
+* **path** `string` (optional)
+* **secure** `boolean` (optional)
+* **httpOnly** `boolean` (optional)
+* **sameSite** `'String'|'Lax'|'None'` (optional)
+* **unparsed** `string[]` (optional) Left over attributes that weren't parsed.
+
+## `deleteCookie(headers, name[, attributes])`
+
+Sets the expiry time of the cookie to the unix epoch, causing browsers to delete it when received.
+
+```js
+import { deleteCookie, Headers } from 'undici'
+
+const headers = new Headers()
+deleteCookie(headers, 'name')
+
+console.log(headers.get('set-cookie')) // name=; Expires=Thu, 01 Jan 1970 00:00:00 GMT
+```
+
+Arguments:
+
+* **headers** `Headers`
+* **name** `string`
+* **attributes** `{ path?: string, domain?: string }` (optional)
+
+Returns: `void`
+
+## `getCookies(headers)`
+
+Parses the `Cookie` header and returns a list of attributes and values.
+
+```js
+import { getCookies, Headers } from 'undici'
+
+const headers = new Headers({
+  cookie: 'get=cookies; and=attributes'
+})
+
+console.log(getCookies(headers)) // { get: 'cookies', and: 'attributes' }
+```
+
+Arguments:
+
+* **headers** `Headers`
+
+Returns: `Record<string, string>`
+
+## `getSetCookies(headers)`
+
+Parses all `Set-Cookie` headers.
+
+```js
+import { getSetCookies, Headers } from 'undici'
+
+const headers = new Headers({ 'set-cookie': 'undici=getSetCookies; Secure' })
+
+console.log(getSetCookies(headers))
+// [
+//   {
+//     name: 'undici',
+//     value: 'getSetCookies',
+//     secure: true
+//   }
+// ]
+
+```
+
+Arguments:
+
+* **headers** `Headers`
+
+Returns: `Cookie[]`
+
+## `setCookie(headers, cookie)`
+
+Appends a cookie to the `Set-Cookie` header.
+
+```js
+import { setCookie, Headers } from 'undici'
+
+const headers = new Headers()
+setCookie(headers, { name: 'undici', value: 'setCookie' })
+
+console.log(headers.get('Set-Cookie')) // undici=setCookie
+```
+
+Arguments:
+
+* **headers** `Headers`
+* **cookie** `Cookie`
+
+Returns: `void`

package/docs/api/DiagnosticsChannel.md

@@ -135,3 +135,70 @@ diagnosticsChannel.channel('undici:client:connectError').subscribe(({ error, soc
   // connector is a function that creates the socket
   console.log(`Connect failed with ${error.message}`)
 })
+```
+
+## `undici:websocket:open`
+
+This message is published after the client has successfully connected to a server.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:websocket:open').subscribe(({ address, protocol, extensions }) => {
+  console.log(address) // address, family, and port
+  console.log(protocol) // negotiated subprotocols
+  console.log(extensions) // negotiated extensions
+})
+```
+
+## `undici:websocket:close`
+
+This message is published after the connection has closed.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:websocket:close').subscribe(({ websocket, code, reason }) => {
+  console.log(websocket) // the WebSocket object
+  console.log(code) // the closing status code
+  console.log(reason) // the closing reason
+})
+```
+
+## `undici:websocket:socket_error`
+
+This message is published if the socket experiences an error.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:websocket:socket_error').subscribe((error) => {
+  console.log(error)
+})
+```
+
+## `undici:websocket:ping`
+
+This message is published after the client receives a ping frame, if the connection is not closing.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:websocket:ping').subscribe(({ payload }) => {
+  // a Buffer or undefined, containing the optional application data of the frame
+  console.log(payload)
+})
+```
+
+## `undici:websocket:pong`
+
+This message is published after the client receives a pong frame.
+
+```js
+import diagnosticsChannel from 'diagnostics_channel'
+
+diagnosticsChannel.channel('undici:websocket:pong').subscribe(({ payload }) => {
+  // a Buffer or undefined, containing the optional application data of the frame
+  console.log(payload)
+})
+```

package/docs/api/Dispatcher.md

@@ -192,6 +192,7 @@ Returns: `Boolean` - `false` if dispatcher is busy and further dispatch calls wo
 * **origin** `string | URL`
 * **path** `string`
 * **method** `string`
+* **reset** `boolean` (optional) - Default: `false` - If `false`, the request will attempt to create a long-living connection by sending the `connection: keep-alive` header,otherwise will attempt to close it immediately after response by sending `connection: close` within the request and closing the socket afterwards.
 * **body** `string | Buffer | Uint8Array | stream.Readable | Iterable | AsyncIterable | null` (optional) - Default: `null`
 * **headers** `UndiciHeaders | string[]` (optional) - Default: `null`.
 * **query** `Record<string, any> | null` (optional) - Default: `null` - Query string params to be embedded in the request URL. Note that both keys and values of query are encoded using `encodeURIComponent`. If for some reason you need to send them unencoded, embed query params into path directly instead.

package/docs/api/Fetch.md

@@ -0,0 +1,25 @@
+# Fetch
+
+Undici exposes a fetch() method starts the process of fetching a resource from the network.
+
+Documentation and examples can be found on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/fetch).
+
+## File
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/File)
+
+## FormData
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
+
+## Response
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Response)
+
+## Request
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Request)
+
+## Header
+
+This API is implemented as per the standard, you can find documentation on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Headers)

package/docs/api/WebSocket.md

@@ -0,0 +1,20 @@
+# Class: WebSocket
+
+> ⚠️ Warning: the WebSocket API is experimental and has known bugs.
+
+Extends: [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)
+
+The WebSocket object provides a way to manage a WebSocket connection to a server, allowing bidirectional communication. The API follows the [WebSocket spec](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).
+
+## `new WebSocket(url[, protocol])`
+
+Arguments:
+
+* **url** `URL | string` - The url's protocol *must* be `ws` or `wss`.
+* **protocol** `string | string[]` (optional) - Subprotocol(s) to request the server use. 
+
+## Read More
+
+- [MDN - WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+- [The WebSocket Specification](https://www.rfc-editor.org/rfc/rfc6455)
+- [The WHATWG WebSocket Specification](https://websockets.spec.whatwg.org/)

package/index.d.ts

@@ -16,11 +16,13 @@ import mockErrors from'./types/mock-errors'
 import ProxyAgent from'./types/proxy-agent'
 import { request, pipeline, stream, connect, upgrade } from './types/api'
 
+export * from './types/cookies'
 export * from './types/fetch'
 export * from './types/file'
 export * from './types/filereader'
 export * from './types/formdata'
 export * from './types/diagnostics-channel'
+export * from './types/websocket'
 export { Interceptable } from './types/mock-interceptor'
 
 export { Dispatcher, BalancedPool, Pool, Client, buildConnector, errors, Agent, request, stream, pipeline, connect, upgrade, setGlobalDispatcher, getGlobalDispatcher, setGlobalOrigin, getGlobalOrigin, MockClient, MockPool, MockAgent, mockErrors, ProxyAgent, RedirectHandler, DecoratorHandler }

package/index.js

@@ -119,6 +119,21 @@ if (nodeMajor > 16 || (nodeMajor === 16 && nodeMinor >= 8)) {
   module.exports.getGlobalOrigin = getGlobalOrigin
 }
 
+if (nodeMajor >= 16) {
+  const { deleteCookie, getCookies, getSetCookies, setCookie } = require('./lib/cookies')
+
+  module.exports.deleteCookie = deleteCookie
+  module.exports.getCookies = getCookies
+  module.exports.getSetCookies = getSetCookies
+  module.exports.setCookie = setCookie
+}
+
+if (nodeMajor >= 18) {
+  const { WebSocket } = require('./lib/websocket/websocket')
+
+  module.exports.WebSocket = WebSocket
+}
+
 module.exports.request = makeDispatcher(api.request)
 module.exports.stream = makeDispatcher(api.stream)
 module.exports.pipeline = makeDispatcher(api.pipeline)

package/lib/client.js

@@ -1295,7 +1295,7 @@ function _resume (client, sync) {
 }
 
 function write (client, request) {
-  const { body, method, path, host, upgrade, headers, blocking } = request
+  const { body, method, path, host, upgrade, headers, blocking, reset } = request
 
   // https://tools.ietf.org/html/rfc7231#section-4.3.1
   // https://tools.ietf.org/html/rfc7231#section-4.3.2
@@ -1363,7 +1363,6 @@ function write (client, request) {
 
   if (method === 'HEAD') {
     // https://github.com/mcollina/undici/issues/258
-
     // Close after a HEAD request to interop with misbehaving servers
     // that may send a body in the response.
 
@@ -1377,6 +1376,10 @@ function write (client, request) {
     socket[kReset] = true
   }
 
+  if (reset) {
+    socket[kReset] = true
+  }
+
   if (client[kMaxRequests] && socket[kCounter]++ >= client[kMaxRequests]) {
     socket[kReset] = true
   }
@@ -1395,7 +1398,7 @@ function write (client, request) {
 
   if (upgrade) {
     header += `connection: upgrade\r\nupgrade: ${upgrade}\r\n`
-  } else if (client[kPipelining]) {
+  } else if (client[kPipelining] && !socket[kReset]) {
     header += 'connection: keep-alive\r\n'
   } else {
     header += 'connection: close\r\n'

package/lib/cookies/constants.js

@@ -0,0 +1,12 @@
+'use strict'
+
+// https://wicg.github.io/cookie-store/#cookie-maximum-attribute-value-size
+const maxAttributeValueSize = 1024
+
+// https://wicg.github.io/cookie-store/#cookie-maximum-name-value-pair-size
+const maxNameValuePairSize = 4096
+
+module.exports = {
+  maxAttributeValueSize,
+  maxNameValuePairSize
+}

package/lib/cookies/index.js

@@ -0,0 +1,183 @@
+'use strict'
+
+const { parseSetCookie } = require('./parse')
+const { stringify, getHeadersList } = require('./util')
+const { webidl } = require('../fetch/webidl')
+const { Headers } = require('../fetch/headers')
+
+/**
+ * @typedef {Object} Cookie
+ * @property {string} name
+ * @property {string} value
+ * @property {Date|number|undefined} expires
+ * @property {number|undefined} maxAge
+ * @property {string|undefined} domain
+ * @property {string|undefined} path
+ * @property {boolean|undefined} secure
+ * @property {boolean|undefined} httpOnly
+ * @property {'Strict'|'Lax'|'None'} sameSite
+ * @property {string[]} unparsed
+ */
+
+/**
+ * @param {Headers} headers
+ * @returns {Record<string, string>}
+ */
+function getCookies (headers) {
+  webidl.argumentLengthCheck(arguments, 1, { header: 'getCookies' })
+
+  webidl.brandCheck(headers, Headers, { strict: false })
+
+  const cookie = headers.get('cookie')
+  const out = {}
+
+  if (!cookie) {
+    return out
+  }
+
+  for (const piece of cookie.split(';')) {
+    const [name, ...value] = piece.split('=')
+
+    out[name.trim()] = value.join('=')
+  }
+
+  return out
+}
+
+/**
+ * @param {Headers} headers
+ * @param {string} name
+ * @param {{ path?: string, domain?: string }|undefined} attributes
+ * @returns {void}
+ */
+function deleteCookie (headers, name, attributes) {
+  webidl.argumentLengthCheck(arguments, 2, { header: 'deleteCookie' })
+
+  webidl.brandCheck(headers, Headers, { strict: false })
+
+  name = webidl.converters.DOMString(name)
+  attributes = webidl.converters.DeleteCookieAttributes(attributes)
+
+  // Matches behavior of
+  // https://github.com/denoland/deno_std/blob/63827b16330b82489a04614027c33b7904e08be5/http/cookie.ts#L278
+  setCookie(headers, {
+    name,
+    value: '',
+    expires: new Date(0),
+    ...attributes
+  })
+}
+
+/**
+ * @param {Headers} headers
+ * @returns {Cookie[]}
+ */
+function getSetCookies (headers) {
+  webidl.argumentLengthCheck(arguments, 1, { header: 'getSetCookies' })
+
+  webidl.brandCheck(headers, Headers, { strict: false })
+
+  const cookies = getHeadersList(headers).cookies
+
+  if (!cookies) {
+    return []
+  }
+
+  return cookies.map((pair) => parseSetCookie(pair[1]))
+}
+
+/**
+ * @param {Headers} headers
+ * @param {Cookie} cookie
+ * @returns {void}
+ */
+function setCookie (headers, cookie) {
+  webidl.argumentLengthCheck(arguments, 2, { header: 'setCookie' })
+
+  webidl.brandCheck(headers, Headers, { strict: false })
+
+  cookie = webidl.converters.Cookie(cookie)
+
+  const str = stringify(cookie)
+
+  if (str) {
+    headers.append('Set-Cookie', stringify(cookie))
+  }
+}
+
+webidl.converters.DeleteCookieAttributes = webidl.dictionaryConverter([
+  {
+    converter: webidl.nullableConverter(webidl.converters.DOMString),
+    key: 'path',
+    defaultValue: null
+  },
+  {
+    converter: webidl.nullableConverter(webidl.converters.DOMString),
+    key: 'domain',
+    defaultValue: null
+  }
+])
+
+webidl.converters.Cookie = webidl.dictionaryConverter([
+  {
+    converter: webidl.converters.DOMString,
+    key: 'name'
+  },
+  {
+    converter: webidl.converters.DOMString,
+    key: 'value'
+  },
+  {
+    converter: webidl.nullableConverter((value) => {
+      if (typeof value === 'number') {
+        return webidl.converters['unsigned long long'](value)
+      }
+
+      return new Date(value)
+    }),
+    key: 'expires',
+    defaultValue: null
+  },
+  {
+    converter: webidl.nullableConverter(webidl.converters['long long']),
+    key: 'maxAge',
+    defaultValue: null
+  },
+  {
+    converter: webidl.nullableConverter(webidl.converters.DOMString),
+    key: 'domain',
+    defaultValue: null
+  },
+  {
+    converter: webidl.nullableConverter(webidl.converters.DOMString),
+    key: 'path',
+    defaultValue: null
+  },
+  {
+    converter: webidl.nullableConverter(webidl.converters.boolean),
+    key: 'secure',
+    defaultValue: null
+  },
+  {
+    converter: webidl.nullableConverter(webidl.converters.boolean),
+    key: 'httpOnly',
+    defaultValue: null
+  },
+  {
+    converter: webidl.converters.USVString,
+    key: 'sameSite',
+    allowedValues: ['Strict', 'Lax', 'None']
+  },
+  {
+    converter: webidl.sequenceConverter(webidl.converters.DOMString),
+    key: 'unparsed',
+    defaultValue: []
+  }
+])
+
+module.exports = {
+  getCookies,
+  deleteCookie,
+  getSetCookies,
+  setCookie
+}