node-fastify 5.8.3

package/docs/Reference/Decorators.md

@@ -0,0 +1,436 @@
+<h1 align="center">Fastify</h1>
+
+## Decorators
+
+The decorators API customizes core Fastify objects, such as the server instance
+and any request and reply objects used during the HTTP request lifecycle. It
+can attach any type of property to core objects, e.g., functions, plain
+objects, or native types.
+
+This API is *synchronous*. Defining a decoration asynchronously could result in
+the Fastify instance booting before the decoration completes. To register an
+asynchronous decoration, use the `register` API with `fastify-plugin`. See the
+[Plugins](./Plugins.md) documentation for more details.
+
+Decorating core objects with this API allows the underlying JavaScript engine to
+optimize the handling of server, request, and reply objects. This is
+accomplished by defining the shape of all such object instances before they are
+instantiated and used. As an example, the following is not recommended because
+it will change the shape of objects during their lifecycle:
+
+```js
+// Bad example! Continue reading.
+
+// Attach a user property to the incoming request before the request
+// handler is invoked.
+fastify.addHook('preHandler', function (req, reply, done) {
+  req.user = 'Bob Dylan'
+  done()
+})
+
+// Use the attached user property in the request handler.
+fastify.get('/', function (req, reply) {
+  reply.send(`Hello, ${req.user}`)
+})
+```
+
+The above example mutates the request object after instantiation, causing the
+JavaScript engine to deoptimize access. Using the decoration API avoids this
+deoptimization:
+
+```js
+// Decorate request with a 'user' property
+fastify.decorateRequest('user', '')
+
+// Update our property
+fastify.addHook('preHandler', (req, reply, done) => {
+  req.user = 'Bob Dylan'
+  done()
+})
+// And finally access it
+fastify.get('/', (req, reply) => {
+  reply.send(`Hello, ${req.user}!`)
+})
+```
+
+Keep the initial shape of a decorated field close to its future dynamic value.
+Initialize a decorator as `''` for strings and `null` for objects or functions.
+This works only with value types; reference types will throw an error during
+Fastify startup. See [decorateRequest](#decorate-request) and
+[JavaScript engine fundamentals: Shapes
+and Inline Caches](https://mathiasbynens.be/notes/shapes-ics)
+for more information.
+
+### Usage
+<a id="usage"></a>
+
+#### `decorate(name, value, [dependencies])`
+<a id="decorate"></a>
+
+This method customizes the Fastify [server](./Server.md) instance.
+
+For example, to attach a new method to the server instance:
+
+```js
+fastify.decorate('utility', function () {
+  // Something very useful
+})
+```
+
+Non-function values can also be attached to the server instance:
+
+```js
+fastify.decorate('conf', {
+  db: 'some.db',
+  port: 3000
+})
+```
+
+To access decorated properties, use the name provided to the decoration API:
+
+```js
+fastify.utility()
+
+console.log(fastify.conf.db)
+```
+
+The decorated [Fastify server](./Server.md) is bound to `this` in
+[route](./Routes.md) handlers:
+
+```js
+fastify.decorate('db', new DbConnection())
+
+fastify.get('/', async function (request, reply) {
+  // using return
+  return { hello: await this.db.query('world') }
+
+  // or
+  // using reply.send()
+  reply.send({ hello: await this.db.query('world') })
+  await reply
+})
+```
+
+The `dependencies` parameter is an optional list of decorators that the
+decorator being defined relies upon. This list contains the names of other
+decorators. In the following example, the "utility" decorator depends on the
+"greet" and "hi" decorators:
+
+```js
+async function greetDecorator (fastify, opts) {
+  fastify.decorate('greet', () => {
+    return 'greet message'
+  })
+}
+
+async function hiDecorator (fastify, opts) {
+  fastify.decorate('hi', () => {
+    return 'hi message'
+  })
+}
+
+async function utilityDecorator (fastify, opts) {
+  fastify.decorate('utility', () => {
+    return `${fastify.greet()} | ${fastify.hi()}`
+  })
+}
+
+fastify.register(fastifyPlugin(greetDecorator, { name: 'greet' }))
+fastify.register(fastifyPlugin(hiDecorator, { name: 'hi' }))
+fastify.register(fastifyPlugin(utilityDecorator, { dependencies: ['greet', 'hi'] }))
+
+fastify.get('/', function (req, reply) {
+  // Response: {"hello":"greet message | hi message"}
+  reply.send({ hello: fastify.utility() })
+})
+
+fastify.listen({ port: 3000 }, (err, address) => {
+  if (err) throw err
+})
+```
+
+Using an arrow function breaks the binding of `this` to
+the `FastifyInstance`.
+
+If a dependency is not satisfied, the `decorate` method throws an exception.
+The dependency check occurs before the server instance boots, not during
+runtime.
+
+#### `decorateReply(name, value, [dependencies])`
+<a id="decorate-reply"></a>
+
+This API adds new methods/properties to the core `Reply` object:
+
+```js
+fastify.decorateReply('utility', function () {
+  // Something very useful
+})
+```
+
+Using an arrow function will break the binding of `this` to the Fastify
+`Reply` instance.
+
+Using `decorateReply` will throw and error if used with a reference type:
+
+```js
+// Don't do this
+fastify.decorateReply('foo', { bar: 'fizz'})
+```
+In this example, the object reference would be shared with all requests, and
+**any mutation will impact all requests, potentially creating security
+vulnerabilities or memory leaks**. Fastify blocks this.
+
+To achieve proper encapsulation across requests configure a new value for each
+incoming request in the [`'onRequest'` hook](./Hooks.md#onrequest).
+
+```js
+const fp = require('fastify-plugin')
+
+async function myPlugin (app) {
+  app.decorateReply('foo')
+  app.addHook('onRequest', async (req, reply) => {
+    reply.foo = { bar: 42 }
+  })
+}
+
+module.exports = fp(myPlugin)
+```
+
+See [`decorate`](#decorate) for information about the `dependencies` parameter.
+
+#### `decorateRequest(name, value, [dependencies])`
+<a id="decorate-request"></a>
+
+As with [`decorateReply`](#decorate-reply), this API adds new methods/properties
+to the core `Request` object:
+
+```js
+fastify.decorateRequest('utility', function () {
+  // something very useful
+})
+```
+
+Using an arrow function will break the binding of `this` to the Fastify
+`Request` instance.
+
+Using `decorateRequest` will emit an error if used with a reference type:
+
+```js
+// Don't do this
+fastify.decorateRequest('foo', { bar: 'fizz'})
+```
+In this example, the object reference would be shared with all requests, and
+**any mutation will impact all requests, potentially creating security
+vulnerabilities or memory leaks**. Fastify blocks this.
+
+To achieve proper encapsulation across requests configure a new value for each
+incoming request in the [`'onRequest'` hook](./Hooks.md#onrequest).
+
+Example:
+
+```js
+const fp = require('fastify-plugin')
+
+async function myPlugin (app) {
+  app.decorateRequest('foo')
+  app.addHook('onRequest', async (req, reply) => {
+    req.foo = { bar: 42 }
+  })
+}
+
+module.exports = fp(myPlugin)
+```
+
+The hook solution is more flexible and allows for more complex initialization
+because more logic can be added to the `onRequest` hook.
+
+Another approach is to use the getter/setter pattern, but it requires 2 decorators:
+
+```js
+fastify.decorateRequest('my_decorator_holder') // define the holder
+fastify.decorateRequest('user', {
+  getter () {
+    this.my_decorator_holder ??= {} // initialize the holder
+    return this.my_decorator_holder
+  }
+})
+
+fastify.get('/', async function (req, reply) {
+  req.user.access = 'granted'
+  // other code
+})
+```
+
+This ensures that the `user` property is always unique for each request.
+
+See [`decorate`](#decorate) for information about the `dependencies` parameter.
+
+#### `hasDecorator(name)`
+<a id="has-decorator"></a>
+
+Used to check for the existence of a server instance decoration:
+
+```js
+fastify.hasDecorator('utility')
+```
+
+#### hasRequestDecorator
+<a id="has-request-decorator"></a>
+
+Used to check for the existence of a Request decoration:
+
+```js
+fastify.hasRequestDecorator('utility')
+```
+
+#### hasReplyDecorator
+<a id="has-reply-decorator"></a>
+
+Used to check for the existence of a Reply decoration:
+
+```js
+fastify.hasReplyDecorator('utility')
+```
+
+### Decorators and Encapsulation
+<a id="decorators-encapsulation"></a>
+
+Defining a decorator (using `decorate`, `decorateRequest`, or `decorateReply`)
+with the same name more than once in the same **encapsulated** context will
+throw an exception. For example, the following will throw:
+
+```js
+const server = require('fastify')()
+
+server.decorateReply('view', function (template, args) {
+  // Amazing view rendering engine
+})
+
+server.get('/', (req, reply) => {
+  reply.view('/index.html', { hello: 'world' })
+})
+
+// Somewhere else in our codebase, we define another
+// view decorator. This throws.
+server.decorateReply('view', function (template, args) {
+  // Another rendering engine
+})
+
+server.listen({ port: 3000 })
+```
+
+
+But this will not:
+
+```js
+const server = require('fastify')()
+
+server.decorateReply('view', function (template, args) {
+  // Amazing view rendering engine.
+})
+
+server.register(async function (server, opts) {
+  // We add a view decorator to the current encapsulated
+  // plugin. This will not throw as outside of this encapsulated
+  // plugin view is the old one, while inside it is the new one.
+  server.decorateReply('view', function (template, args) {
+    // Another rendering engine
+  })
+
+  server.get('/', (req, reply) => {
+    reply.view('/index.page', { hello: 'world' })
+  })
+}, { prefix: '/bar' })
+
+server.listen({ port: 3000 })
+```
+
+### Getters and Setters
+<a id="getters-setters"></a>
+
+Decorators accept special "getter/setter" objects with `getter` and optional
+`setter` functions. This allows defining properties via decorators,
+for example:
+
+```js
+fastify.decorate('foo', {
+  getter () {
+    return 'a getter'
+  }
+})
+```
+
+Will define the `foo` property on the Fastify instance:
+
+```js
+console.log(fastify.foo) // 'a getter'
+```
+
+#### `getDecorator(name)`
+<a id="get-decorator"></a>
+
+Used to retrieve an existing decorator from the Fastify instance, `Request`,
+or `Reply`.
+If the decorator is not defined, an `FST_ERR_DEC_UNDECLARED` error is thrown.
+
+```js
+// Get a decorator from the Fastify instance
+const utility = fastify.getDecorator('utility')
+
+// Get a decorator from the request object
+const user = request.getDecorator('user')
+
+// Get a decorator from the reply object
+const helper = reply.getDecorator('helper')
+```
+
+The `getDecorator` method is useful for dependency validation - it can be used to
+check for required decorators at registration time. If any are missing, it fails
+at boot, ensuring dependencies are available during the request lifecycle.
+
+```js
+fastify.register(async function (fastify) {
+  // Verify the decorator exists before using it
+  const usersRepository = fastify.getDecorator('usersRepository')
+
+  fastify.get('/users', async function (request, reply) {
+    return usersRepository.findAll()
+  })
+})
+```
+
+> ℹ️ Note:
+> For TypeScript users, `getDecorator` supports generic type parameters.
+> See the [TypeScript documentation](./TypeScript.md) for
+> advanced typing examples.
+
+#### `setDecorator(name, value)`
+<a id="set-decorator"></a>
+
+Used to safely update the value of a `Request` decorator.
+If the decorator does not exist, a `FST_ERR_DEC_UNDECLARED` error is thrown.
+
+```js
+fastify.decorateRequest('user', null)
+
+fastify.addHook('preHandler', async (req, reply) => {
+  // Safely set the decorator value
+  req.setDecorator('user', 'Bob Dylan')
+})
+```
+
+The `setDecorator` method provides runtime safety by ensuring the decorator exists
+before setting its value, preventing errors from typos in decorator names.
+
+```js
+fastify.decorateRequest('account', null)
+fastify.addHook('preHandler', async (req, reply) => {
+  // This will throw FST_ERR_DEC_UNDECLARED due to typo in decorator name
+  req.setDecorator('acount', { id: 123 })
+})
+```
+
+> ℹ️ Note:
+> For TypeScript users, see the
+> [TypeScript documentation](./TypeScript.md) for advanced
+> typing examples using `setDecorator<T>`.

package/docs/Reference/Encapsulation.md

@@ -0,0 +1,194 @@
+<h1 align="center">Fastify</h1>
+
+## Encapsulation
+<a id="encapsulation"></a>
+
+A fundamental feature of Fastify is the "encapsulation context." It governs
+which [decorators](./Decorators.md), registered [hooks](./Hooks.md), and
+[plugins](./Plugins.md) are available to [routes](./Routes.md). A visual
+representation of the encapsulation context is shown in the following figure:
+
+![Figure 1](../resources/encapsulation_context.svg)
+
+In the figure above, there are several entities:
+
+1. The _root context_
+2. Three _root plugins_
+3. Two _child contexts_, each with:
+    * Two _child plugins_
+    * One _grandchild context_, each with:
+        - Three _child plugins_
+
+Every _child context_ and _grandchild context_ has access to the _root plugins_.
+Within each _child context_, the _grandchild contexts_ have access to the
+_child plugins_ registered within the containing _child context_, but the
+containing _child context_ **does not** have access to the _child plugins_
+registered within its _grandchild context_.
+
+Given that everything in Fastify is a [plugin](./Plugins.md) except for the
+_root context_, every "context" and "plugin" in this example is a plugin
+that can consist of decorators, hooks, plugins, and routes. As plugins, they
+must still signal completion either by returning a Promise (e.g., using `async`
+functions) or by calling the `done` function if using the callback style.
+
+To put this
+example into concrete terms, consider a basic scenario of a REST API server
+with three routes: the first route (`/one`) requires authentication, the
+second route (`/two`) does not, and the third route (`/three`) has access to
+the same context as the second route. Using [@fastify/bearer-auth][bearer] to
+provide authentication, the code for this example is as follows:
+
+```js
+'use strict'
+
+const fastify = require('fastify')()
+
+fastify.decorateRequest('answer', 42)
+
+fastify.register(async function authenticatedContext (childServer) {
+  childServer.register(require('@fastify/bearer-auth'), { keys: ['abc123'] })
+
+  childServer.route({
+    path: '/one',
+    method: 'GET',
+    handler (request, response) {
+      response.send({
+        answer: request.answer,
+        // request.foo will be undefined as it is only defined in publicContext
+        foo: request.foo,
+        // request.bar will be undefined as it is only defined in grandchildContext
+        bar: request.bar
+      })
+    }
+  })
+})
+
+fastify.register(async function publicContext (childServer) {
+  childServer.decorateRequest('foo', 'foo')
+
+  childServer.route({
+    path: '/two',
+    method: 'GET',
+    handler (request, response) {
+      response.send({
+        answer: request.answer,
+        foo: request.foo,
+        // request.bar will be undefined as it is only defined in grandchildContext
+        bar: request.bar
+      })
+    }
+  })
+
+  childServer.register(async function grandchildContext (grandchildServer) {
+    grandchildServer.decorateRequest('bar', 'bar')
+
+    grandchildServer.route({
+      path: '/three',
+      method: 'GET',
+      handler (request, response) {
+        response.send({
+          answer: request.answer,
+          foo: request.foo,
+          bar: request.bar
+        })
+      }
+    })
+  })
+})
+
+fastify.listen({ port: 8000 })
+```
+
+The server example above demonstrates the encapsulation concepts from the
+original diagram:
+
+1. Each _child context_ (`authenticatedContext`, `publicContext`, and
+   `grandchildContext`) has access to the `answer` request decorator defined in
+   the _root context_.
+2. Only the `authenticatedContext` has access to the `@fastify/bearer-auth`
+   plugin.
+3. Both the `publicContext` and `grandchildContext` have access to the `foo`
+   request decorator.
+4. Only the `grandchildContext` has access to the `bar` request decorator.
+
+To see this, start the server and issue requests:
+
+```sh
+# curl -H 'authorization: Bearer abc123' http://127.0.0.1:8000/one
+{"answer":42}
+# curl http://127.0.0.1:8000/two
+{"answer":42,"foo":"foo"}
+# curl http://127.0.0.1:8000/three
+{"answer":42,"foo":"foo","bar":"bar"}
+```
+
+[bearer]: https://github.com/fastify/fastify-bearer-auth
+
+## Sharing Between Contexts
+<a id="shared-context"></a>
+
+Each context in the prior example inherits _only_ from its parent contexts. Parent
+contexts cannot access entities within their descendant contexts. If needed,
+encapsulation can be broken using [fastify-plugin][fastify-plugin], making
+anything registered in a descendant context available to the parent context.
+
+To allow `publicContext` access to the `bar` decorator in `grandchildContext`,
+rewrite the code as follows:
+
+```js
+'use strict'
+
+const fastify = require('fastify')()
+const fastifyPlugin = require('fastify-plugin')
+
+fastify.decorateRequest('answer', 42)
+
+// `authenticatedContext` omitted for clarity
+
+fastify.register(async function publicContext (childServer) {
+  childServer.decorateRequest('foo', 'foo')
+
+  childServer.route({
+    path: '/two',
+    method: 'GET',
+    handler (request, response) {
+      response.send({
+        answer: request.answer,
+        foo: request.foo,
+        bar: request.bar
+      })
+    }
+  })
+
+  childServer.register(fastifyPlugin(grandchildContext))
+
+  async function grandchildContext (grandchildServer) {
+    grandchildServer.decorateRequest('bar', 'bar')
+
+    grandchildServer.route({
+      path: '/three',
+      method: 'GET',
+      handler (request, response) {
+        response.send({
+          answer: request.answer,
+          foo: request.foo,
+          bar: request.bar
+        })
+      }
+    })
+  }
+})
+
+fastify.listen({ port: 8000 })
+```
+
+Restarting the server and re-issuing the requests for `/two` and `/three`:
+
+```sh
+# curl http://127.0.0.1:8000/two
+{"answer":42,"foo":"foo","bar":"bar"}
+# curl http://127.0.0.1:8000/three
+{"answer":42,"foo":"foo","bar":"bar"}
+```
+
+[fastify-plugin]: https://github.com/fastify/fastify-plugin