node-fastify 5.8.3

package/docs/Reference/Index.md

@@ -0,0 +1,73 @@
+<h1 align="center">Fastify</h1>
+
+## Core Documents
+<a id="reference-core-docs"></a>
+
+For the full table of contents (TOC), see [below](#reference-toc). The following
+list is a subset of the full TOC that detail core Fastify APIs and concepts in
+order of most likely importance to the reader:
+
++ [Server](./Server.md): Documents the core Fastify API. Includes documentation
+  for the factory function and the object returned by the factory function.
++ [Lifecycle](./Lifecycle.md): Explains the Fastify request lifecycle and
+  illustrates where [Hooks](./Hooks.md) are available for integrating with it.
++ [Routes](./Routes.md): Details how to register routes with Fastify and how
+  Fastify builds and evaluates the routing trie.
++ [Request](./Request.md): Details Fastify's request object that is passed into
+  each request handler.
++ [Reply](./Reply.md): Details Fastify's response object available to each
+  request handler.
++ [Validation and Serialization](./Validation-and-Serialization.md): Details
+  Fastify's support for validating incoming data and how Fastify serializes data
+  for responses.
++ [Plugins](./Plugins.md): Explains Fastify's plugin architecture and API.
++ [Encapsulation](./Encapsulation.md): Explains a core concept upon which all
+  Fastify plugins are built.
++ [Decorators](./Decorators.md): Explains the server, request, and response
+  decorator APIs.
++ [Hooks](./Hooks.md): Details the API by which Fastify plugins can inject
+  themselves into Fastify's handling of the request lifecycle.
+
+
+## Reference Documentation Table Of Contents
+<a id="reference-toc"></a>
+
+This table of contents is in alphabetical order.
+
++ [Content Type Parser](./ContentTypeParser.md): Documents Fastify's default
+  content type parser and how to add support for new content types.
++ [Decorators](./Decorators.md): Explains the server, request, and response
+  decorator APIs.
++ [Encapsulation](./Encapsulation.md): Explains a core concept upon which all
+  Fastify plugins are built.
++ [Errors](./Errors.md): Details how Fastify handles errors and lists the
+  standard set of errors Fastify generates.
++ [Hooks](./Hooks.md): Details the API by which Fastify plugins can inject
+  themselves into Fastify's handling of the request lifecycle.
++ [HTTP2](./HTTP2.md): Details Fastify's HTTP2 support.
++ [Lifecycle](./Lifecycle.md): Explains the Fastify request lifecycle and
+  illustrates where [Hooks](./Hooks.md) are available for integrating with it.
++ [Logging](./Logging.md): Details Fastify's included logging and how to
+  customize it.
++ [Long Term Support](./LTS.md): Explains Fastify's long term support (LTS)
+  guarantee and the exceptions possible to the [semver](https://semver.org)
+  contract.
++ [Middleware](./Middleware.md): Details Fastify's support for Express.js style
+  middleware.
++ [Plugins](./Plugins.md): Explains Fastify's plugin architecture and API.
++ [Reply](./Reply.md): Details Fastify's response object available to each
+  request handler.
++ [Request](./Request.md): Details Fastify's request object that is passed into
+  each request handler.
++ [Routes](./Routes.md): Details how to register routes with Fastify and how
+  Fastify builds and evaluates the routing trie.
++ [Server](./Server.md): Documents the core Fastify API. Includes documentation
+  for the factory function and the object returned by the factory function.
++ [TypeScript](./TypeScript.md): Documents Fastify's TypeScript support and
+  provides recommendations for writing applications in TypeScript that utilize
+  Fastify.
++ [Validation and Serialization](./Validation-and-Serialization.md): Details
+  Fastify's support for validating incoming data and how Fastify serializes data
+  for responses.
++ [Warnings](./Warnings.md): Details the warnings Fastify emits and how to
+  solve them.

package/docs/Reference/LTS.md

@@ -0,0 +1,86 @@
+<h1 align="center">Fastify</h1>
+
+## Long Term Support
+<a id="lts"></a>
+
+Fastify's Long Term Support (LTS) is provided according to the schedule laid out
+in this document:
+
+1. Major releases, "X" release of [semantic versioning][semver] X.Y.Z release
+   versions, are supported for a minimum period of six months from their release
+   date. The release date of any specific version can be found at
+   [https://github.com/fastify/fastify/releases](https://github.com/fastify/fastify/releases).
+2. Major releases will receive security updates for an additional six months
+   from the release of the next major release. After this period we will still
+   review and release security fixes as long as they are provided by the
+   community and they do not violate other constraints, e.g. minimum supported
+   Node.js version.
+3. Major releases will be tested and verified against all Node.js release lines
+   that are supported by the [Node.js LTS
+   policy](https://github.com/nodejs/Release) within the LTS period of that
+   given Fastify release line. This implies that only the latest Node.js release
+   of a given line is supported.
+4. In addition to Node.js runtime, major releases of Fastify will also be tested
+   and verified against alternative runtimes that are compatible with Node.js.
+   The maintenance teams of these alternative runtimes are responsible for ensuring
+   and guaranteeing these tests work properly.
+   1. [N|Solid](https://docs.nodesource.com/docs/product_suite) tests and
+      verifies each Fastify major release against current N|Solid LTS versions.
+      NodeSource ensures Fastify compatibility with N|Solid, aligning with the
+      support scope of N|Solid LTS versions at the time of the Fastify release.
+      This guarantees N|Solid users can confidently use Fastify.
+
+A "month" is defined as 30 consecutive days.
+
+> ## Security Releases and Semver
+>
+> As a consequence of providing long-term support for major releases, there are
+> occasions where we need to release breaking changes as a _minor_ version
+> release. Such changes will _always_ be noted in the [release
+> notes](https://github.com/fastify/fastify/releases).
+>
+> To avoid automatically receiving breaking security updates it is possible to
+> use the tilde (`~`) range qualifier. For example, to get patches for the 3.15
+> release, and avoid automatically updating to the 3.16 release, specify the
+> dependency as `"fastify": "~3.15.x"`. This will leave your application
+> vulnerable, so please use it with caution.
+
+### Security Support Beyond LTS
+
+Fastify's partner, HeroDevs, provides commercial security support through the
+OpenJS Ecosystem Sustainability Program for versions of Fastify that are EOL.
+For more information, see their [Never Ending Support][hd-link] service.
+
+### Schedule
+<a id="lts-schedule"></a>
+
+| Version | Release Date | End Of LTS Date | Node.js            | Nsolid(Node)   |
+| :------ | :----------- | :-------------- | :----------------- | :------------- |
+| 1.0.0   | 2018-03-06   | 2019-09-01      | 6, 8, 9, 10, 11    |                |
+| 2.0.0   | 2019-02-25   | 2021-01-31      | 6, 8, 10, 12, 14   |                |
+| 3.0.0   | 2020-07-07   | 2023-06-30      | 10, 12, 14, 16, 18 | v5(18)         |
+| 4.0.0   | 2022-06-08   | 2025-06-30      | 14, 16, 18, 20, 22 | v5(18), v5(20) |
+| 5.0.0   | 2024-09-17   | TBD             | 20, 22             | v5(20)         |
+
+### CI tested operating systems
+<a id="supported-os"></a>
+
+Fastify uses GitHub Actions for CI testing, please refer to [GitHub&#39;s
+documentation regarding workflow
+runners](https://docs.github.com/en/actions/reference/runners/github-hosted-runners#supported-runners-and-hardware-resources)
+for further details on what the latest virtual environment is in relation to the
+YAML workflow labels below:
+
+| OS      | YAML Workflow Label | Package Manager | Node.js     | Nsolid(Node)  |
+| ------- | ------------------- | --------------- | ----------- | ------------- |
+| Linux   | `ubuntu-latest`     | npm             | 20          | v5(20)        |
+| Linux   | `ubuntu-latest`     | yarn,pnpm       | 20          | v5(20)        |
+| Windows | `windows-latest`    | npm             | 20          | v5(20)        |
+| MacOS   | `macos-latest`      | npm             | 20          | v5(20)        |
+
+Using [yarn](https://yarnpkg.com/) might require passing the `--ignore-engines`
+flag.
+
+[semver]: https://semver.org/
+
+[hd-link]: https://www.herodevs.com/support/fastify-nes?utm_source=fastify&utm_medium=link&utm_campaign=eol_support_fastify

package/docs/Reference/Lifecycle.md

@@ -0,0 +1,99 @@
+<h1 align="center">Fastify</h1>
+
+## Lifecycle
+<a id="lifecycle"></a>
+
+This schema shows the internal lifecycle of Fastify.
+
+The right branch of each section shows the next phase of the lifecycle. The left
+branch shows the corresponding error code generated if the parent throws an
+error. All errors are automatically handled by Fastify.
+
+```
+Incoming Request
+  │
+  └─▶ Routing
+        │
+        └─▶ Instance Logger
+             │
+   4**/5** ◀─┴─▶ onRequest Hook
+                  │
+        4**/5** ◀─┴─▶ preParsing Hook
+                        │
+              4**/5** ◀─┴─▶ Parsing
+                             │
+                   4**/5** ◀─┴─▶ preValidation Hook
+                                  │
+                            400 ◀─┴─▶ Validation
+                                        │
+                              4**/5** ◀─┴─▶ preHandler Hook
+                                              │
+                                    4**/5** ◀─┴─▶ User Handler
+                                                    │
+                                                    └─▶ Reply
+                                                          │
+                                                4**/5** ◀─┴─▶ preSerialization Hook
+                                                                │
+                                                                └─▶ onSend Hook
+                                                                      │
+                                                            4**/5** ◀─┴─▶ Outgoing Response
+                                                                            │
+                                                                            └─▶ onResponse Hook
+```
+
+When `handlerTimeout` is configured, a timer starts after routing. If the
+response is not sent within the allowed time, `request.signal` is aborted and
+a 503 error is sent. The timer is cleared when the response finishes or when
+`reply.hijack()` is called. See [`handlerTimeout`](./Server.md#factory-handler-timeout).
+
+Before or during the `User Handler`, `reply.hijack()` can be called to:
+- Prevent Fastify from running subsequent hooks and the user handler
+- Prevent Fastify from sending the response automatically
+
+If `reply.raw` is used to send a response, `onResponse` hooks will still
+be executed.
+
+## Reply Lifecycle
+<a id="reply-lifecycle"></a>
+
+When the user handles the request, the result may be:
+
+- In an async handler: it returns a payload or throws an `Error`
+- In a sync handler: it sends a payload or an `Error` instance
+
+If the reply was hijacked, all subsequent steps are skipped. Otherwise, when
+submitted, the data flow is as follows:
+
+```
+                        ★ schema validation Error
+                                    │
+                                    └─▶ schemaErrorFormatter
+                                               │
+                          reply sent ◀── JSON ─┴─ Error instance
+                                                      │
+                                                      │         ★ throw an Error
+                     ★ send or return                 │                 │
+                            │                         │                 │
+                            │                         ▼                 │
+       reply sent ◀── JSON ─┴─ Error instance ──▶ onError Hook ◀───────┘
+                                                      │
+                                 reply sent ◀── JSON ─┴─ Error instance ──▶ setErrorHandler
+                                                                                │
+                                                                                └─▶ reply sent
+```
+
+`reply sent` means the JSON payload will be serialized by one of the following:
+- The [reply serializer](./Server.md#setreplyserializer) if set
+- The [serializer compiler](./Server.md#setserializercompiler) if a JSON schema
+  is set for the HTTP status code
+- The default `JSON.stringify` function
+
+## Shutdown Lifecycle
+<a id="shutdown-lifecycle"></a>
+
+When [`fastify.close()`](./Server.md#close) is called, the server goes through a
+graceful shutdown sequence involving
+[`preClose`](./Hooks.md#pre-close) hooks, connection draining, and
+[`onClose`](./Hooks.md#on-close) hooks. See the
+[`close`](./Server.md#close) method documentation for the full step-by-step
+lifecycle.

package/docs/Reference/Logging.md

@@ -0,0 +1,268 @@
+<h1 align="center">Fastify</h1>
+
+## Logging
+
+### Enable Logging
+Logging is disabled by default. Enable it by passing `{ logger: true }` or
+`{ logger: { level: 'info' } }` when creating a Fastify instance. Note that if
+the logger is disabled, it cannot be enabled at runtime.
+[abstract-logging](https://www.npmjs.com/package/abstract-logging) is used for
+this purpose.
+
+As Fastify is focused on performance, it uses
+[pino](https://github.com/pinojs/pino) as its logger, with the default log
+level set to `'info'` when enabled.
+
+#### Basic logging setup
+Enabling the production JSON logger:
+
+```js
+const fastify = require('fastify')({
+  logger: true
+})
+```
+
+#### Environment-Specific Configuration
+Enabling the logger with appropriate configuration for local development,
+production, and test environments requires more configuration:
+
+```js
+const envToLogger = {
+  development: {
+    transport: {
+      target: 'pino-pretty',
+      options: {
+        translateTime: 'HH:MM:ss Z',
+        ignore: 'pid,hostname',
+      },
+    },
+  },
+  production: true,
+  test: false,
+}
+const fastify = require('fastify')({
+  logger: envToLogger[environment] ?? true // defaults to true if no entry matches in the map
+})
+```
+⚠️ `pino-pretty` needs to be installed as a dev dependency. It is not included
+by default for performance reasons.
+
+### Usage
+The logger can be used in route handlers as follows:
+
+```js
+fastify.get('/', options, function (request, reply) {
+  request.log.info('Some info about the current request')
+  reply.send({ hello: 'world' })
+})
+```
+
+Trigger new logs outside route handlers using the Pino instance from the Fastify
+instance:
+```js
+fastify.log.info('Something important happened!');
+```
+
+#### Passing Logger Options
+To pass options to the logger, provide them to Fastify. See the
+[Pino documentation](https://github.com/pinojs/pino/blob/main/docs/api.md#options)
+for available options. To specify a file destination, use:
+
+```js
+const fastify = require('fastify')({
+  logger: {
+    level: 'info',
+    file: '/path/to/file' // Will use pino.destination()
+  }
+})
+
+fastify.get('/', options, function (request, reply) {
+  request.log.info('Some info about the current request')
+  reply.send({ hello: 'world' })
+})
+```
+
+To pass a custom stream to the Pino instance, add a `stream` field to the logger
+object:
+
+```js
+const split = require('split2')
+const stream = split(JSON.parse)
+
+const fastify = require('fastify')({
+  logger: {
+    level: 'info',
+    stream: stream
+  }
+})
+```
+
+### Advanced Logger Configuration
+
+<a id="logging-request-id"></a>
+#### Request ID Tracking
+By default, Fastify adds an ID to every request for easier tracking. If the
+`requestIdHeader` option is set and the corresponding header is present, its
+value is used; otherwise, a new incremental ID is generated. See Fastify Factory
+[`requestIdHeader`](./Server.md#factory-request-id-header) and Fastify Factory
+[`genReqId`](./Server.md#genreqid) for customization options.
+
+> ⚠ Warning:
+> Enabling `requestIdHeader` allows any callers to set `reqId` to a
+> value of their choosing.
+> No validation is performed on `requestIdHeader`.
+
+#### Serializers
+The default logger uses standard serializers for objects with `req`, `res`, and
+`err` properties. The `req` object is the Fastify [`Request`](./Request.md)
+object, and the `res` object is the Fastify [`Reply`](./Reply.md) object. This
+behavior can be customized with custom serializers.
+
+```js
+const fastify = require('fastify')({
+  logger: {
+    serializers: {
+      req (request) {
+        return { url: request.url }
+      }
+    }
+  }
+})
+```
+For example, the response payload and headers could be logged using the approach
+below (not recommended):
+
+```js
+const fastify = require('fastify')({
+  logger: {
+    transport: {
+      target: 'pino-pretty'
+    },
+    serializers: {
+      res (reply) {
+        // The default
+        return {
+          statusCode: reply.statusCode
+        }
+      },
+      req (request) {
+        return {
+          method: request.method,
+          url: request.url,
+          path: request.routeOptions.url,
+          parameters: request.params,
+          // Including headers in the log could violate privacy laws,
+          // e.g., GDPR. Use the "redact" option to remove sensitive
+          // fields. It could also leak authentication data in the logs.
+          headers: request.headers
+        };
+      }
+    }
+  }
+});
+```
+
+> ℹ️ Note:
+> In some cases, the [`Reply`](./Reply.md) object passed to the `res`
+> serializer cannot be fully constructed. When writing a custom `res`
+> serializer, check for the existence of any properties on `reply` aside from
+> `statusCode`, which is always present. For example, verify the existence of
+> `getHeaders` before calling it:
+
+```js
+const fastify = require('fastify')({
+  logger: {
+    transport: {
+      target: 'pino-pretty'
+    },
+    serializers: {
+      res (reply) {
+        // The default
+        return {
+          statusCode: reply.statusCode,
+          headers: typeof reply.getHeaders === 'function'
+            ? reply.getHeaders()
+            : {}
+        }
+      },
+    }
+  }
+});
+```
+
+> ℹ️ Note:
+> The body cannot be serialized inside a `req` method because the
+> request is serialized when the child logger is created. At that time, the body
+> is not yet parsed.
+
+See the following approach to log `req.body`:
+
+```js
+app.addHook('preHandler', function (req, reply, done) {
+  if (req.body) {
+    req.log.info({ body: req.body }, 'parsed body')
+  }
+  done()
+})
+```
+
+> ℹ️ Note:
+> Ensure serializers never throw errors, as this can cause the Node
+> process to exit. See the
+> [Pino documentation](https://getpino.io/#/docs/api?id=opt-serializers) for more
+> information.
+
+*Any logger other than Pino will ignore this option.*
+
+### Using Custom Loggers
+A custom logger instance can be supplied by passing it as `loggerInstance`. The
+logger must conform to the Pino interface, with methods: `info`, `error`,
+`debug`, `fatal`, `warn`, `trace`, `silent`, `child`, and a string property
+`level`.
+
+Example:
+
+```js
+const log = require('pino')({ level: 'info' })
+const fastify = require('fastify')({ loggerInstance: log })
+
+log.info('does not have request information')
+
+fastify.get('/', function (request, reply) {
+  request.log.info('includes request information, but is the same logger instance as `log`')
+  reply.send({ hello: 'world' })
+})
+```
+
+*The logger instance for the current request is available in every part of the
+[lifecycle](./Lifecycle.md).*
+
+### Log Redaction
+
+[Pino](https://getpino.io) supports low-overhead log redaction for obscuring
+values of specific properties in recorded logs. For example, log all HTTP
+headers except the `Authorization` header for security:
+
+```js
+const fastify = Fastify({
+  logger: {
+    stream: stream,
+    redact: ['req.headers.authorization'],
+    level: 'info',
+    serializers: {
+      req (request) {
+        return {
+          method: request.method,
+          url: request.url,
+          headers: request.headers,
+          host: request.host,
+          remoteAddress: request.ip,
+          remotePort: request.socket.remotePort
+        }
+      }
+    }
+  }
+})
+```
+
+See https://getpino.io/#/docs/redaction for more details.

package/docs/Reference/Middleware.md

@@ -0,0 +1,79 @@
+<h1 align="center">Fastify</h1>
+
+## Middleware
+
+Starting with Fastify v3.0.0, middleware is not supported out of the box and
+requires an external plugin such as
+[`@fastify/express`](https://github.com/fastify/fastify-express) or
+[`@fastify/middie`](https://github.com/fastify/middie).
+
+
+An example of registering the
+[`@fastify/express`](https://github.com/fastify/fastify-express) plugin to `use`
+Express middleware:
+
+```js
+await fastify.register(require('@fastify/express'))
+fastify.use(require('cors')())
+fastify.use(require('dns-prefetch-control')())
+fastify.use(require('frameguard')())
+fastify.use(require('hsts')())
+fastify.use(require('ienoopen')())
+fastify.use(require('x-xss-protection')())
+```
+
+[`@fastify/middie`](https://github.com/fastify/middie) can also be used,
+which provides support for simple Express-style middleware with improved
+performance:
+
+```js
+await fastify.register(require('@fastify/middie'))
+fastify.use(require('cors')())
+```
+
+Middleware can be encapsulated, allowing control over where it runs using
+`register` as explained in the [plugins guide](../Guides/Plugins-Guide.md).
+
+Fastify middleware does not expose the `send` method or other methods specific
+to the Fastify [Reply](./Reply.md#reply) instance. This is because Fastify wraps
+the incoming `req` and `res` Node instances using the
+[Request](./Request.md#request) and [Reply](./Reply.md#reply) objects
+internally, but this is done after the middleware phase. To create middleware,
+use the Node `req` and `res` instances. Alternatively, use the `preHandler` hook
+that already has the Fastify [Request](./Request.md#request) and
+[Reply](./Reply.md#reply) instances. For more information, see
+[Hooks](./Hooks.md#hooks).
+
+#### Restrict middleware execution to certain paths
+<a id="restrict-usage"></a>
+
+To run middleware under certain paths, pass the path as the first parameter to
+`use`.
+
+> ℹ️ Note:
+> This does not support routes with parameters
+> (e.g. `/user/:id/comments`) and wildcards are not supported in multiple paths.
+
+```js
+const path = require('node:path')
+const serveStatic = require('serve-static')
+
+// Single path
+fastify.use('/css', serveStatic(path.join(__dirname, '/assets')))
+
+// Wildcard path
+fastify.use('/css/(.*)', serveStatic(path.join(__dirname, '/assets')))
+
+// Multiple paths
+fastify.use(['/css', '/js'], serveStatic(path.join(__dirname, '/assets')))
+```
+
+### Alternatives
+
+Fastify offers alternatives to commonly used middleware, such as
+[`@fastify/helmet`](https://github.com/fastify/fastify-helmet) for
+[`helmet`](https://github.com/helmetjs/helmet),
+[`@fastify/cors`](https://github.com/fastify/fastify-cors) for
+[`cors`](https://github.com/expressjs/cors), and
+[`@fastify/static`](https://github.com/fastify/fastify-static) for
+[`serve-static`](https://github.com/expressjs/serve-static).