fastify 3.27.3 → 4.0.0-alpha.2

package/docs/Reference/Encapsulation.md

@@ -94,7 +94,7 @@ fastify.register(async function publicContext (childServer) {
   })
 })
 
-fastify.listen(8000)
+fastify.listen({ port: 8000 })
 ```
 
 The above server example shows all of the encapsulation concepts outlined in the
@@ -180,7 +180,7 @@ fastify.register(async function publicContext (childServer) {
   }
 })
 
-fastify.listen(8000)
+fastify.listen({ port: 8000 })
 ```
 
 Restarting the server and re-issuing the requests for `/two` and `/three`:

package/docs/Reference/Errors.md

@@ -56,9 +56,19 @@ From the [Hooks documentation](./Hooks.md#manage-errors-from-a-hook):
 > `done()` and Fastify will automatically close the request and send the
 > appropriate error code to the user.
 
-If you have defined a custom error handler for using `setErrorHandler` the error
-will be routed there. otherwise, it will be routed to Fastify’s generic error
-handler.
+When a custom error handler has been defined through
+[`setErrorHandler`](./Server.md#seterrorhandler), the custom error handler will
+receive the error passed to the `done()` callback (or through other supported
+automatic error handling mechanisms). If `setErrorHandler` has been used
+multiple times to define multiple handlers, the error will be routed to the most
+precedent handler defined within the error [encapsulation context](./Encapsulation.md).
+Error handlers are fully encapsulated, so a `setErrorHandler` call within a
+plugin will limit the error handler to that plugin's context.
+
+The root error handler is Fastify's generic error handler. This error handler
+will use the headers and status code in the `Error` object, if they exist. The
+headers and status code will not be automatically set if a custom error handler
+is provided.
 
 Some things to consider in your custom error handler:
 
@@ -70,13 +80,12 @@ Some things to consider in your custom error handler:
     headers (no serialization)
 
 - You can throw a new error in your custom error handler
-  - errors (new error or the received error parameter re-thrown) - will trigger
-    the `onError` lifecycle hook and send the error to the user
+	- errors (new error or the received error parameter re-thrown) - will call the parent `errorHandler`.
+  - `onError` hook will be triggered once only for the first error being thrown.
   - an error will not be triggered twice from a lifecycle hook - Fastify
     internally monitors the error invocation to avoid infinite loops for errors
     thrown in the reply phases of the lifecycle. (those after the route handler)
 
-
 ### Fastify Error Codes
 <a id="fastify-error-codes"></a>
 
@@ -85,6 +94,12 @@ Some things to consider in your custom error handler:
 
 The router received an invalid url.
 
+<a name="FST_ERR_DUPLICATED_ROUTE"></a>
+#### FST_ERR_DUPLICATED_ROUTE
+
+The HTTP method already has a registered controller for that URL
+
+<a name="FST_ERR_CTP_ALREADY_PRESENT"></a>
 #### FST_ERR_CTP_ALREADY_PRESENT
 <a id="FST_ERR_CTP_ALREADY_PRESENT"></a>
 
@@ -199,3 +214,33 @@ You cannot use `send` inside the `onError` hook.
 <a id="FST_ERR_SEND_UNDEFINED_ERR"></a>
 
 Undefined error has occurred.
+
+<a name="FST_ERR_PLUGIN_NOT_VALID"></a>
+#### FST_ERR_PLUGIN_NOT_VALID
+
+Plugin must be a function or a promise.
+
+<a name="FST_ERR_PLUGIN_TIMEOUT"></a>
+#### FST_ERR_PLUGIN_TIMEOUT
+
+Plugin did not start in time. Default timeout (in millis): `10000`
+
+<a name="FST_ERR_HOOK_TIMEOUT"></a>
+#### FST_ERR_HOOK_TIMEOUT
+
+A callback for a hook timed out
+
+<a name="FST_ERR_ROOT_PLG_BOOTED"></a>
+#### FST_ERR_ROOT_PLG_BOOTED
+
+Root plugin has already booted (mapped directly from `avvio`)
+
+<a name="FST_ERR_PARENT_PLUGIN_BOOTED"></a>
+#### FST_ERR_PARENT_PLUGIN_BOOTED
+
+Impossible to load plugin because the parent (mapped directly from `avvio`)
+
+<a name="FST_ERR_PLUGIN_CALLBACK_NOT_FN"></a>
+#### FST_ERR_PLUGIN_CALLBACK_NOT_FN
+
+Callback for a hook is not a function (mapped directly from `avvio`)

package/docs/Reference/HTTP2.md

@@ -31,7 +31,7 @@ fastify.get('/', function (request, reply) {
   reply.code(200).send({ hello: 'world' })
 })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 ALPN negotiation allows support for both HTTPS and HTTP/2 over the same socket.
@@ -59,7 +59,7 @@ fastify.get('/', function (request, reply) {
   reply.code(200).send({ hello: 'world' })
 })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 You can test your new server with:
@@ -84,7 +84,7 @@ fastify.get('/', function (request, reply) {
   reply.code(200).send({ hello: 'world' })
 })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 You can test your new server with:

package/docs/Reference/Hooks.md

@@ -65,7 +65,7 @@ fastify.addHook('onRequest', async (request, reply) => {
 ```
 
 **Notice:** in the [onRequest](#onrequest) hook, `request.body` will always be
-`null`, because the body parsing happens before the
+`undefined`, because the body parsing happens before the
 [preValidation](#prevalidation) hook.
 
 ### preParsing
@@ -95,7 +95,7 @@ fastify.addHook('preParsing', async (request, reply, payload) => {
 ```
 
 **Notice:** in the [preParsing](#preparsing) hook, `request.body` will always be
-`null`, because the body parsing happens before the
+`undefined`, because the body parsing happens before the
 [preValidation](#prevalidation) hook.
 
 **Notice:** you should also add a `receivedEncodedLength` property to the
@@ -103,10 +103,6 @@ returned stream. This property is used to correctly match the request payload
 with the `Content-Length` header value. Ideally, this property should be updated
 on each received chunk.
 
-**Notice**: The old syntaxes `function(request, reply, done)` and `async
-function(request, reply)` for the parser are still supported but they are
-deprecated.
-
 ### preValidation
 
 If you are using the `preValidation` hook, you can change the payload before it
@@ -322,7 +318,7 @@ fastify.addHook('onRequest', (request, reply, done) => {
 fastify.addHook('preHandler', async (request, reply) => {
   await something()
   reply.send({ hello: 'world' })
-  return reply // optional in this case, but it is a good practice
+  return reply // mandatory, so the request is not executed further
 })
 ```
 
@@ -419,6 +415,7 @@ fastify.addHook('onClose', async (instance) => {
 Triggered when a new route is registered. Listeners are passed a `routeOptions`
 object as the sole parameter. The interface is synchronous, and, as such, the
 listeners are not passed a callback. This hook is encapsulated.
+
 ```js
 fastify.addHook('onRoute', (routeOptions) => {
   //Some code

package/docs/Reference/LTS.md

@@ -48,6 +48,7 @@ A "month" is defined as 30 consecutive days.
 | 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   | TBD             | 10, 12, 14, 16       |
+| 4.0.0   | TBD          | TBD             | 14, 16               |
 
 ### CI tested operating systems
 <a id="supported-os"></a>
@@ -60,10 +61,10 @@ YAML workflow labels below:
 
 | OS      | YAML Workflow Label    | Package Manager           | Node.js      |
 |---------|------------------------|---------------------------|--------------|
-| Linux   | `ubuntu-latest`        | npm                       | 10,12,14,16  |
-| Linux   | `ubuntu-18.04`         | yarn,pnpm                 | 10,12        |
-| Windows | `windows-latest`       | npm                       | 10,12,14,16  |
-| MacOS   | `macos-latest`         | npm                       | 10,12,14,16  |
+| Linux   | `ubuntu-latest`        | npm                       | 14,16        |
+| Linux   | `ubuntu-18.04`         | yarn,pnpm                 | 14,16        |
+| Windows | `windows-latest`       | npm                       | 14,16        |
+| MacOS   | `macos-latest`         | npm                       | 14,16        |
 
 Using [yarn](https://yarnpkg.com/) might require passing the `--ignore-engines`
 flag.

package/docs/Reference/Plugins.md

@@ -124,7 +124,7 @@ fastify.ready(err => console.log(err))
 
 // `listen` is a special ready,
 // so it behaves in the same way
-fastify.listen(3000, (err, address) => {
+fastify.listen({ port: 3000 }, (err, address) => {
   if (err) console.log(err)
 })
 ```
@@ -142,7 +142,7 @@ await fastify.after()
 
 await fastify.ready()
 
-await fastify.listen(3000)
+await fastify.listen({ port: 3000 })
 ```
 
 #### ESM support
@@ -158,7 +158,7 @@ const fastify = Fastify()
 
 fastify.register(import('./plugin.mjs'))
 
-fastify.listen(3000, console.log)
+fastify.listen({ port: 3000 }, console.log)
 
 
 // plugin.mjs

package/docs/Reference/Reply.md

@@ -59,12 +59,10 @@ object that exposes the following functions and properties:
   buffer, JSON, stream, or an Error object.
 - `.sent` - A boolean value that you can use if you need to know if `send` has
   already been called.
+- `.hijack()` - interrupt the normal request lifecycle.
 - `.raw` - The
   [`http.ServerResponse`](https://nodejs.org/dist/latest-v14.x/docs/api/http.html#http_class_http_serverresponse)
   from Node core.
-- `.res` *(deprecated, use `.raw` instead)* - The
-  [`http.ServerResponse`](https://nodejs.org/dist/latest-v14.x/docs/api/http.html#http_class_http_serverresponse)
-  from Node core.
 - `.log` - The logger instance of the incoming request.
 - `.request` - The incoming request.
 - `.context` - Access the [Request's context](./Request.md) property.
@@ -125,6 +123,8 @@ fastify.get('/', async function (req, rep) {
 Sets a response header. If the value is omitted or undefined, it is coerced to
 `''`.
 
+> Note: the header's value must be properly encoded using [`encodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI) or similar modules such as [`encodeurl`](https://www.npmjs.com/package/encodeurl). Invalid characters will result in a 500 `TypeError` response.
+
 For more information, see
 [`http.ServerResponse#setHeader`](https://nodejs.org/dist/latest-v14.x/docs/api/http.html#http_response_setheader_name_value).
 
@@ -205,6 +205,8 @@ Returns a boolean indicating if the specified header has been set.
 Redirects a request to the specified URL, the status code is optional, default
 to `302` (if status code is not already set by calling `code`).
 
+> Note: the input URL must be properly encoded using [`encodeURI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI) or similar modules such as [`encodeurl`](https://www.npmjs.com/package/encodeurl). Invalid URLs will result in a 500 `TypeError` response.
+
 Example (no `reply.code()` call) sets status code to `302` and redirects to
 `/home`
 ```js
@@ -315,39 +317,38 @@ Another example of the misuse of `Reply.raw` is explained in
 
 As the name suggests, `.sent` is a property to indicate if a response has been
 sent via `reply.send()`.
+It will also be `true` in case `reply.hijack()` was used.
 
 In case a route handler is defined as an async function or it returns a promise,
-it is possible to set `reply.sent = true` to indicate that the automatic
+it is possible to call `reply.hijack()` to indicate that the automatic
 invocation of `reply.send()` once the handler promise resolve should be skipped.
-By setting `reply.sent = true`, an application claims full responsibility for
+By calling `reply.hijack()`, an application claims full responsibility for
 the low-level request and response. Moreover, hooks will not be invoked.
 
-As an example:
+*Modifying the `.sent` property directly is deprecated. Please use the aformentioned
+`.hijack()` method to achieve the same effect.*
+
+<a name="hijack"></a>
+### .hijack()
+Sometimes you might need to halt the execution of the normal request lifecycle and
+handle sending the response manually.
+
+To achieve this, Fastify provides the `reply.hijack()` method that can be called
+during the request lifecycle (At any point before `reply.send()` is called), and
+allows you to prevent Fastify from sending the response, and from running the
+remaining hooks (and user handler if the reply was hijacked before).
 
 ```js
 app.get('/', (req, reply) => {
-  reply.sent = true
+  reply.hijack()
   reply.raw.end('hello world')
 
   return Promise.resolve('this will be skipped')
 })
 ```
 
-If the handler rejects, the error will be logged.
-
-### .hijack()
-<a id="hijack"></a>
-
-Sometimes you might need to halt the execution of the normal request lifecycle
-and handle sending the response manually.
-
-To achieve this, Fastify provides the `reply.hijack()` method that can be called
-during the request lifecycle (At any point before `reply.send()` is called), and
-allows you to prevent Fastify from sending the response, and from running the
-remaining hooks (and user handler if the reply was hijacked before).
-
-NB (*): If `reply.raw` is used to send a response back to the user, `onResponse`
-hooks will still be executed
+If `reply.raw` is used to send a response back to the user, the `onResponse`
+hooks will still be executed.
 
 ### .send(data)
 <a id="send"></a>

package/docs/Reference/Request.md

@@ -12,10 +12,8 @@ Request is a core Fastify object containing the following fields:
 - `params` - the params matching the URL
 - [`headers`](#headers) - the headers getter and setter
 - `raw` - the incoming HTTP request from Node core
-- `req` *(deprecated, use `.raw` instead)* - the incoming HTTP request from Node
-  core
 - `server` - The Fastify server instance, scoped to the current [encapsulation
-  context](./Encapsulation.md)
+>>>>>>> main:docs/Reference/Request.md
 - `id` - the request ID
 - `log` - the logger instance of the incoming request
 - `ip` - the IP address of the incoming request

package/docs/Reference/Routes.md

@@ -32,7 +32,7 @@ fastify.route(options)
 ### Routes options
 <a id="options"></a>
 
-* `method`: currently it supports `'DELETE'`, `'GET'`, `'HEAD'`, `'PATCH'`,
+*`method`: currently it supports `'DELETE'`, `'GET'`, `'HEAD'`, `'PATCH'`,
   `'POST'`, `'PUT'` and `'OPTIONS'`. It could also be an array of methods.
 * `url`: the path of the URL to match this route (alias: `path`).
 * `schema`: an object containing the schemas for the request and response. They
@@ -54,6 +54,7 @@ fastify.route(options)
   option, make sure to define it before the `GET` route.
 * `attachValidation`: attach `validationError` to request, if there is a schema
   validation error, instead of sending the error to the error handler.
+  The default [error format](https://ajv.js.org/api.html#error-objects) is the Ajv one.
 * `onRequest(request, reply, done)`: a [function](./Hooks.md#onrequest) as soon
   that a request is received, it could also be an array of functions.
 * `preParsing(request, reply, done)`: a [function](./Hooks.md#preparsing) called
@@ -280,11 +281,14 @@ As you can see, we are not calling `reply.send` to send back the data to the
 user. You just need to return the body and you are done!
 
 If you need it you can also send back the data to the user with `reply.send`.
+In this case do not forget to `return reply` or `await reply` in your `async`
+handler or you will introduce a race condition in certain situations.
+
 ```js
 fastify.get('/', options, async function (request, reply) {
   var data = await getData()
   var processed = await processData(data)
-  reply.send(processed)
+  return reply.send(processed)
 })
 ```
 
@@ -316,24 +320,27 @@ fastify.get('/', options, async function (request, reply) {
   first one that happens takes precedence, the second value will be discarded,
   and a *warn* log will also be emitted because you tried to send a response
   twice.
+* Calling `reply.send()` outside of the promise is possible, but requires
+  special attention. For more details read
+  [promise-resolution](#promise-resolution).
 * You cannot return `undefined`. For more details read
   [promise-resolution](#promise-resolution).
 
 ### Promise resolution
 <a id="promise-resolution"></a>
 
-If your handler is an `async` function or returns a promise, you should be aware
-of a special behavior that is necessary to support the callback and promise
-control-flow. If the handler's promise is resolved with `undefined`, it will be
-ignored causing the request to hang and an *error* log to be emitted.
+If your handler is an `async` function or returns a promise, you should be aware of
+a special behaviour which is necessary to support the callback and promise
+control-flow. When the handler's promise is resolved, the reply will be
+automatically sent with its value unless you explicitly await or return `reply`
+in your handler.
 
-1. If you want to use `async/await` or promises but return a value with
-   `reply.send`:
-    - **Do not** `return` any value.
+1. If you want to use `async/await` or promises but respond a value with `reply.send`:
+    - **Do** `return reply` / `await reply`.
     - **Do not** forget to call `reply.send`.
 2. If you want to use `async/await` or promises:
     - **Do not** use `reply.send`.
-    - **Do not** return `undefined`.
+    - **Do** return the value that you want to send.
 
 In this way, we can support both `callback-style` and `async-await`, with the
 minimum trade-off. In spite of so much freedom we highly recommend to go with
@@ -358,7 +365,7 @@ const fastify = require('fastify')()
 fastify.register(require('./routes/v1/users'), { prefix: '/v1' })
 fastify.register(require('./routes/v2/users'), { prefix: '/v2' })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 ```js
@@ -420,7 +427,7 @@ const fastify = require('fastify')({ logger: true })
 fastify.register(require('./routes/user'), { logLevel: 'warn' })
 fastify.register(require('./routes/events'), { logLevel: 'debug' })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 Or you can directly pass it to a route:
@@ -454,7 +461,7 @@ fastify.register(require('./routes/events'), {
   }
 })
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 You can inherit serializers by context:
@@ -492,7 +499,7 @@ async function context1 (fastify, opts) {
   })
 }
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 ### Config
@@ -512,7 +519,7 @@ function handler (req, reply) {
 fastify.get('/en', { config: { output: 'hello world!' } }, handler)
 fastify.get('/it', { config: { output: 'ciao mondo!' } }, handler)
 
-fastify.listen(3000)
+fastify.listen({ port: 3000 })
 ```
 
 ### Constraints