Projektstart
This commit is contained in:
834
backend/node_modules/fastify/docs/Reference/Routes.md
generated
vendored
Normal file
834
backend/node_modules/fastify/docs/Reference/Routes.md
generated
vendored
Normal file
@@ -0,0 +1,834 @@
|
||||
<h1 align="center">Fastify</h1>
|
||||
|
||||
## Routes
|
||||
|
||||
The route methods will configure the endpoints of your application. You have two
|
||||
ways to declare a route with Fastify: the shorthand method and the full
|
||||
declaration.
|
||||
|
||||
- [Full declaration](#full-declaration)
|
||||
- [Routes options](#routes-options)
|
||||
- [Shorthand declaration](#shorthand-declaration)
|
||||
- [Url building](#url-building)
|
||||
- [Async Await](#async-await)
|
||||
- [Promise resolution](#promise-resolution)
|
||||
- [Route Prefixing](#route-prefixing)
|
||||
- [Handling of / route inside prefixed
|
||||
plugins](#handling-of--route-inside-prefixed-plugins)
|
||||
- [Custom Log Level](#custom-log-level)
|
||||
- [Custom Log Serializer](#custom-log-serializer)
|
||||
- [Config](#config)
|
||||
- [Constraints](#constraints)
|
||||
- [Version Constraints](#version-constraints)
|
||||
- [Host Constraints](#host-constraints)
|
||||
|
||||
### Full declaration
|
||||
<a id="full-declaration"></a>
|
||||
|
||||
```js
|
||||
fastify.route(options)
|
||||
```
|
||||
|
||||
### Routes options
|
||||
<a id="options"></a>
|
||||
|
||||
* `method`: currently it supports `'DELETE'`, `'GET'`, `'HEAD'`, `'PATCH'`,
|
||||
`'POST'`, `'PUT'`, `'OPTIONS'`, `'SEARCH'`, `'TRACE'`, `'PROPFIND'`,
|
||||
`'PROPPATCH'`, `'MKCOL'`, `'COPY'`, `'MOVE'`, `'LOCK'`, `'UNLOCK'`,
|
||||
`'REPORT'` and `'MKCALENDAR'`.
|
||||
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
|
||||
need to be in [JSON Schema](https://json-schema.org/) format, check
|
||||
[here](./Validation-and-Serialization.md) for more info.
|
||||
|
||||
* `body`: validates the body of the request if it is a POST, PUT, PATCH,
|
||||
TRACE, SEARCH, PROPFIND, PROPPATCH, COPY, MOVE, MKCOL, REPORT, MKCALENDAR
|
||||
or LOCK method.
|
||||
* `querystring` or `query`: validates the querystring. This can be a complete
|
||||
JSON Schema object, with the property `type` of `object` and `properties`
|
||||
object of parameters, or simply the values of what would be contained in the
|
||||
`properties` object as shown below.
|
||||
* `params`: validates the params.
|
||||
* `response`: filter and generate a schema for the response, setting a schema
|
||||
allows us to have 10-20% more throughput.
|
||||
* `exposeHeadRoute`: creates a sibling `HEAD` route for any `GET` routes.
|
||||
Defaults to the value of [`exposeHeadRoutes`](./Server.md#exposeHeadRoutes)
|
||||
instance option. If you want a custom `HEAD` handler without disabling this
|
||||
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) called
|
||||
as soon as a request is received, it could also be an array of functions.
|
||||
* `preParsing(request, reply, done)`: a [function](./Hooks.md#preparsing) called
|
||||
before parsing the request, it could also be an array of functions.
|
||||
* `preValidation(request, reply, done)`: a [function](./Hooks.md#prevalidation)
|
||||
called after the shared `preValidation` hooks, useful if you need to perform
|
||||
authentication at route level for example, it could also be an array of
|
||||
functions.
|
||||
* `preHandler(request, reply, done)`: a [function](./Hooks.md#prehandler) called
|
||||
just before the request handler, it could also be an array of functions.
|
||||
* `preSerialization(request, reply, payload, done)`: a
|
||||
[function](./Hooks.md#preserialization) called just before the serialization,
|
||||
it could also be an array of functions.
|
||||
* `onSend(request, reply, payload, done)`: a [function](./Hooks.md#route-hooks)
|
||||
called right before a response is sent, it could also be an array of
|
||||
functions.
|
||||
* `onResponse(request, reply, done)`: a [function](./Hooks.md#onresponse) called
|
||||
when a response has been sent, so you will not be able to send more data to
|
||||
the client. It could also be an array of functions.
|
||||
* `onTimeout(request, reply, done)`: a [function](./Hooks.md#ontimeout) called
|
||||
when a request is timed out and the HTTP socket has been hung up.
|
||||
* `onError(request, reply, error, done)`: a [function](./Hooks.md#onerror)
|
||||
called when an Error is thrown or sent to the client by the route handler.
|
||||
* `handler(request, reply)`: the function that will handle this request. The
|
||||
[Fastify server](./Server.md) will be bound to `this` when the handler is
|
||||
called. Note: using an arrow function will break the binding of `this`.
|
||||
* `errorHandler(error, request, reply)`: a custom error handler for the scope of
|
||||
the request. Overrides the default error global handler, and anything set by
|
||||
[`setErrorHandler`](./Server.md#seterrorhandler), for requests to the route.
|
||||
To access the default handler, you can access `instance.errorHandler`. Note
|
||||
that this will point to fastify's default `errorHandler` only if a plugin
|
||||
hasn't overridden it already.
|
||||
* `childLoggerFactory(logger, binding, opts, rawReq)`: a custom factory function
|
||||
that will be called to produce a child logger instance for every request.
|
||||
See [`childLoggerFactory`](./Server.md#childloggerfactory) for more info.
|
||||
Overrides the default logger factory, and anything set by
|
||||
[`setChildLoggerFactory`](./Server.md#setchildloggerfactory), for requests to
|
||||
the route. To access the default factory, you can access
|
||||
`instance.childLoggerFactory`. Note that this will point to Fastify's default
|
||||
`childLoggerFactory` only if a plugin hasn't overridden it already.
|
||||
* `validatorCompiler({ schema, method, url, httpPart })`: function that builds
|
||||
schemas for request validations. See the [Validation and
|
||||
Serialization](./Validation-and-Serialization.md#schema-validator)
|
||||
documentation.
|
||||
* `serializerCompiler({ { schema, method, url, httpStatus, contentType } })`:
|
||||
function that builds schemas for response serialization. See the [Validation and
|
||||
Serialization](./Validation-and-Serialization.md#schema-serializer)
|
||||
documentation.
|
||||
* `schemaErrorFormatter(errors, dataVar)`: function that formats the errors from
|
||||
the validation compiler. See the [Validation and
|
||||
Serialization](./Validation-and-Serialization.md#error-handling)
|
||||
documentation. Overrides the global schema error formatter handler, and
|
||||
anything set by `setSchemaErrorFormatter`, for requests to the route.
|
||||
* `bodyLimit`: prevents the default JSON body parser from parsing request bodies
|
||||
larger than this number of bytes. Must be an integer. You may also set this
|
||||
option globally when first creating the Fastify instance with
|
||||
`fastify(options)`. Defaults to `1048576` (1 MiB).
|
||||
* `logLevel`: set log level for this route. See below.
|
||||
* `logSerializers`: set serializers to log for this route.
|
||||
* `config`: object used to store custom configuration.
|
||||
* `version`: a [semver](https://semver.org/) compatible string that defined the
|
||||
version of the endpoint. [Example](#version-constraints).
|
||||
* `constraints`: defines route restrictions based on request properties or
|
||||
values, enabling customized matching using
|
||||
[find-my-way](https://github.com/delvedor/find-my-way) constraints. Includes
|
||||
built-in `version` and `host` constraints, with support for custom constraint
|
||||
strategies.
|
||||
* `prefixTrailingSlash`: string used to determine how to handle passing `/` as a
|
||||
route with a prefix.
|
||||
* `both` (default): Will register both `/prefix` and `/prefix/`.
|
||||
* `slash`: Will register only `/prefix/`.
|
||||
* `no-slash`: Will register only `/prefix`.
|
||||
|
||||
Note: this option does not override `ignoreTrailingSlash` in
|
||||
[Server](./Server.md) configuration.
|
||||
|
||||
* `request` is defined in [Request](./Request.md).
|
||||
|
||||
* `reply` is defined in [Reply](./Reply.md).
|
||||
|
||||
**Notice:** The documentation of `onRequest`, `preParsing`, `preValidation`,
|
||||
`preHandler`, `preSerialization`, `onSend`, and `onResponse` are described in
|
||||
more detail in [Hooks](./Hooks.md). Additionally, to send a response before the
|
||||
request is handled by the `handler` please refer to [Respond to a request from a
|
||||
hook](./Hooks.md#respond-to-a-request-from-a-hook).
|
||||
|
||||
Example:
|
||||
```js
|
||||
fastify.route({
|
||||
method: 'GET',
|
||||
url: '/',
|
||||
schema: {
|
||||
querystring: {
|
||||
name: { type: 'string' },
|
||||
excitement: { type: 'integer' }
|
||||
},
|
||||
response: {
|
||||
200: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
hello: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
handler: function (request, reply) {
|
||||
reply.send({ hello: 'world' })
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
### Shorthand declaration
|
||||
<a id="shorthand-declaration"></a>
|
||||
|
||||
The above route declaration is more *Hapi*-like, but if you prefer an
|
||||
*Express/Restify* approach, we support it as well:
|
||||
|
||||
`fastify.get(path, [options], handler)`
|
||||
|
||||
`fastify.head(path, [options], handler)`
|
||||
|
||||
`fastify.post(path, [options], handler)`
|
||||
|
||||
`fastify.put(path, [options], handler)`
|
||||
|
||||
`fastify.delete(path, [options], handler)`
|
||||
|
||||
`fastify.options(path, [options], handler)`
|
||||
|
||||
`fastify.patch(path, [options], handler)`
|
||||
|
||||
Example:
|
||||
```js
|
||||
const opts = {
|
||||
schema: {
|
||||
response: {
|
||||
200: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
hello: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
fastify.get('/', opts, (request, reply) => {
|
||||
reply.send({ hello: 'world' })
|
||||
})
|
||||
```
|
||||
|
||||
`fastify.all(path, [options], handler)` will add the same handler to all the
|
||||
supported methods.
|
||||
|
||||
The handler may also be supplied via the `options` object:
|
||||
```js
|
||||
const opts = {
|
||||
schema: {
|
||||
response: {
|
||||
200: {
|
||||
type: 'object',
|
||||
properties: {
|
||||
hello: { type: 'string' }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
handler: function (request, reply) {
|
||||
reply.send({ hello: 'world' })
|
||||
}
|
||||
}
|
||||
fastify.get('/', opts)
|
||||
```
|
||||
|
||||
> Note: if the handler is specified in both the `options` and as the third
|
||||
> parameter to the shortcut method then throws a duplicate `handler` error.
|
||||
|
||||
### Url building
|
||||
<a id="url-building"></a>
|
||||
|
||||
Fastify supports both static and dynamic URLs.
|
||||
|
||||
To register a **parametric** path, use the *colon* before the parameter name.
|
||||
For **wildcard**, use the *star*. *Remember that static routes are always
|
||||
checked before parametric and wildcard.*
|
||||
|
||||
```js
|
||||
// parametric
|
||||
fastify.get('/example/:userId', function (request, reply) {
|
||||
// curl ${app-url}/example/12345
|
||||
// userId === '12345'
|
||||
const { userId } = request.params;
|
||||
// your code here
|
||||
})
|
||||
fastify.get('/example/:userId/:secretToken', function (request, reply) {
|
||||
// curl ${app-url}/example/12345/abc.zHi
|
||||
// userId === '12345'
|
||||
// secretToken === 'abc.zHi'
|
||||
const { userId, secretToken } = request.params;
|
||||
// your code here
|
||||
})
|
||||
|
||||
// wildcard
|
||||
fastify.get('/example/*', function (request, reply) {})
|
||||
```
|
||||
|
||||
Regular expression routes are supported as well, but be aware that you have to
|
||||
escape slashes. Take note that RegExp is also very expensive in terms of
|
||||
performance!
|
||||
```js
|
||||
// parametric with regexp
|
||||
fastify.get('/example/:file(^\\d+).png', function (request, reply) {
|
||||
// curl ${app-url}/example/12345.png
|
||||
// file === '12345'
|
||||
const { file } = request.params;
|
||||
// your code here
|
||||
})
|
||||
```
|
||||
|
||||
It is possible to define more than one parameter within the same couple of slash
|
||||
("/"). Such as:
|
||||
```js
|
||||
fastify.get('/example/near/:lat-:lng/radius/:r', function (request, reply) {
|
||||
// curl ${app-url}/example/near/15°N-30°E/radius/20
|
||||
// lat === "15°N"
|
||||
// lng === "30°E"
|
||||
// r ==="20"
|
||||
const { lat, lng, r } = request.params;
|
||||
// your code here
|
||||
})
|
||||
```
|
||||
*Remember in this case to use the dash ("-") as parameters separator.*
|
||||
|
||||
Finally, it is possible to have multiple parameters with RegExp:
|
||||
```js
|
||||
fastify.get('/example/at/:hour(^\\d{2})h:minute(^\\d{2})m', function (request, reply) {
|
||||
// curl ${app-url}/example/at/08h24m
|
||||
// hour === "08"
|
||||
// minute === "24"
|
||||
const { hour, minute } = request.params;
|
||||
// your code here
|
||||
})
|
||||
```
|
||||
In this case as parameter separator it is possible to use whatever character is
|
||||
not matched by the regular expression.
|
||||
|
||||
The last parameter can be made optional if you add a question mark ("?") to the
|
||||
end of the parameters name.
|
||||
```js
|
||||
fastify.get('/example/posts/:id?', function (request, reply) {
|
||||
const { id } = request.params;
|
||||
// your code here
|
||||
})
|
||||
```
|
||||
In this case you can request `/example/posts` as well as `/example/posts/1`.
|
||||
The optional param will be undefined if not specified.
|
||||
|
||||
Having a route with multiple parameters may negatively affect performance, so
|
||||
prefer a single parameter approach whenever possible, especially on routes that
|
||||
are on the hot path of your application. If you are interested in how we handle
|
||||
the routing, check out [find-my-way](https://github.com/delvedor/find-my-way).
|
||||
|
||||
If you want a path containing a colon without declaring a parameter, use a
|
||||
double colon. For example:
|
||||
```js
|
||||
fastify.post('/name::verb') // will be interpreted as /name:verb
|
||||
```
|
||||
|
||||
### Async Await
|
||||
<a id="async-await"></a>
|
||||
|
||||
Are you an `async/await` user? We have you covered!
|
||||
```js
|
||||
fastify.get('/', options, async function (request, reply) {
|
||||
var data = await getData()
|
||||
var processed = await processData(data)
|
||||
return processed
|
||||
})
|
||||
```
|
||||
|
||||
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)
|
||||
return reply.send(processed)
|
||||
})
|
||||
```
|
||||
|
||||
If the route is wrapping a callback-based API that will call `reply.send()`
|
||||
outside of the promise chain, it is possible to `await reply`:
|
||||
|
||||
```js
|
||||
fastify.get('/', options, async function (request, reply) {
|
||||
setImmediate(() => {
|
||||
reply.send({ hello: 'world' })
|
||||
})
|
||||
await reply
|
||||
})
|
||||
```
|
||||
|
||||
Returning reply also works:
|
||||
|
||||
```js
|
||||
fastify.get('/', options, async function (request, reply) {
|
||||
setImmediate(() => {
|
||||
reply.send({ hello: 'world' })
|
||||
})
|
||||
return reply
|
||||
})
|
||||
```
|
||||
|
||||
**Warning:**
|
||||
* When using both `return value` and `reply.send(value)` at the same time, the
|
||||
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 the special behavior that 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 respond with 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** 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. Despite so much freedom we highly recommend going with only
|
||||
one style because error handling should be handled in a consistent way within
|
||||
your application.
|
||||
|
||||
**Notice**: Every async function returns a promise by itself.
|
||||
|
||||
### Route Prefixing
|
||||
<a id="route-prefixing"></a>
|
||||
|
||||
Sometimes you need to maintain two or more different versions of the same API; a
|
||||
classic approach is to prefix all the routes with the API version number,
|
||||
`/v1/user` for example. Fastify offers you a fast and smart way to create
|
||||
different versions of the same API without changing all the route names by hand,
|
||||
*route prefixing*. Let's see how it works:
|
||||
|
||||
```js
|
||||
// server.js
|
||||
const fastify = require('fastify')()
|
||||
|
||||
fastify.register(require('./routes/v1/users'), { prefix: '/v1' })
|
||||
fastify.register(require('./routes/v2/users'), { prefix: '/v2' })
|
||||
|
||||
fastify.listen({ port: 3000 })
|
||||
```
|
||||
|
||||
```js
|
||||
// routes/v1/users.js
|
||||
module.exports = function (fastify, opts, done) {
|
||||
fastify.get('/user', handler_v1)
|
||||
done()
|
||||
}
|
||||
```
|
||||
|
||||
```js
|
||||
// routes/v2/users.js
|
||||
module.exports = function (fastify, opts, done) {
|
||||
fastify.get('/user', handler_v2)
|
||||
done()
|
||||
}
|
||||
```
|
||||
Fastify will not complain because you are using the same name for two different
|
||||
routes, because at compilation time it will handle the prefix automatically
|
||||
*(this also means that the performance will not be affected at all!)*.
|
||||
|
||||
Now your clients will have access to the following routes:
|
||||
- `/v1/user`
|
||||
- `/v2/user`
|
||||
|
||||
You can do this as many times as you want, it also works for nested `register`,
|
||||
and route parameters are supported as well.
|
||||
|
||||
In case you want to use prefix for all of your routes, you can put them inside a
|
||||
plugin:
|
||||
|
||||
```js
|
||||
const fastify = require('fastify')()
|
||||
|
||||
const route = {
|
||||
method: 'POST',
|
||||
url: '/login',
|
||||
handler: () => {},
|
||||
schema: {},
|
||||
}
|
||||
|
||||
fastify.register(function(app, _, done) {
|
||||
app.get('/users', () => {})
|
||||
app.route(route)
|
||||
|
||||
done()
|
||||
}, { prefix: '/v1' }) // global route prefix
|
||||
|
||||
await fastify.listen({ port: 0 })
|
||||
```
|
||||
|
||||
### Route Prefixing and fastify-plugin
|
||||
<a id="fastify-plugin"></a>
|
||||
|
||||
Be aware that if you use
|
||||
[`fastify-plugin`](https://github.com/fastify/fastify-plugin) for wrapping your
|
||||
routes, this option will not work. You can still make it work by wrapping a
|
||||
plugin in a plugin, e. g.:
|
||||
```js
|
||||
const fp = require('fastify-plugin')
|
||||
const routes = require('./lib/routes')
|
||||
|
||||
module.exports = fp(async function (app, opts) {
|
||||
app.register(routes, {
|
||||
prefix: '/v1',
|
||||
})
|
||||
}, {
|
||||
name: 'my-routes'
|
||||
})
|
||||
```
|
||||
|
||||
#### Handling of / route inside prefixed plugins
|
||||
|
||||
The `/` route has different behavior depending on if the prefix ends with `/` or
|
||||
not. As an example, if we consider a prefix `/something/`, adding a `/` route
|
||||
will only match `/something/`. If we consider a prefix `/something`, adding a
|
||||
`/` route will match both `/something` and `/something/`.
|
||||
|
||||
See the `prefixTrailingSlash` route option above to change this behavior.
|
||||
|
||||
### Custom Log Level
|
||||
<a id="custom-log-level"></a>
|
||||
|
||||
You might need different log levels in your routes; Fastify achieves this in a
|
||||
very straightforward way.
|
||||
|
||||
You just need to pass the option `logLevel` to the plugin option or the route
|
||||
option with the
|
||||
[value](https://github.com/pinojs/pino/blob/master/docs/api.md#level-string)
|
||||
that you need.
|
||||
|
||||
Be aware that if you set the `logLevel` at plugin level, also the
|
||||
[`setNotFoundHandler`](./Server.md#setnotfoundhandler) and
|
||||
[`setErrorHandler`](./Server.md#seterrorhandler) will be affected.
|
||||
|
||||
```js
|
||||
// server.js
|
||||
const fastify = require('fastify')({ logger: true })
|
||||
|
||||
fastify.register(require('./routes/user'), { logLevel: 'warn' })
|
||||
fastify.register(require('./routes/events'), { logLevel: 'debug' })
|
||||
|
||||
fastify.listen({ port: 3000 })
|
||||
```
|
||||
|
||||
Or you can directly pass it to a route:
|
||||
```js
|
||||
fastify.get('/', { logLevel: 'warn' }, (request, reply) => {
|
||||
reply.send({ hello: 'world' })
|
||||
})
|
||||
```
|
||||
*Remember that the custom log level is applied only to the routes, and not to
|
||||
the global Fastify Logger, accessible with `fastify.log`*
|
||||
|
||||
### Custom Log Serializer
|
||||
<a id="custom-log-serializer"></a>
|
||||
|
||||
In some contexts, you may need to log a large object but it could be a waste of
|
||||
resources for some routes. In this case, you can define custom
|
||||
[`serializers`](https://github.com/pinojs/pino/blob/master/docs/api.md#serializers-object)
|
||||
and attach them in the right context!
|
||||
|
||||
```js
|
||||
const fastify = require('fastify')({ logger: true })
|
||||
|
||||
fastify.register(require('./routes/user'), {
|
||||
logSerializers: {
|
||||
user: (value) => `My serializer one - ${value.name}`
|
||||
}
|
||||
})
|
||||
fastify.register(require('./routes/events'), {
|
||||
logSerializers: {
|
||||
user: (value) => `My serializer two - ${value.name} ${value.surname}`
|
||||
}
|
||||
})
|
||||
|
||||
fastify.listen({ port: 3000 })
|
||||
```
|
||||
|
||||
You can inherit serializers by context:
|
||||
|
||||
```js
|
||||
const fastify = Fastify({
|
||||
logger: {
|
||||
level: 'info',
|
||||
serializers: {
|
||||
user (req) {
|
||||
return {
|
||||
method: req.method,
|
||||
url: req.url,
|
||||
headers: req.headers,
|
||||
hostname: req.hostname,
|
||||
remoteAddress: req.ip,
|
||||
remotePort: req.socket.remotePort
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
fastify.register(context1, {
|
||||
logSerializers: {
|
||||
user: value => `My serializer father - ${value}`
|
||||
}
|
||||
})
|
||||
|
||||
async function context1 (fastify, opts) {
|
||||
fastify.get('/', (req, reply) => {
|
||||
req.log.info({ user: 'call father serializer', key: 'another key' })
|
||||
// shows: { user: 'My serializer father - call father serializer', key: 'another key' }
|
||||
reply.send({})
|
||||
})
|
||||
}
|
||||
|
||||
fastify.listen({ port: 3000 })
|
||||
```
|
||||
|
||||
### Config
|
||||
<a id="routes-config"></a>
|
||||
|
||||
Registering a new handler, you can pass a configuration object to it and
|
||||
retrieve it in the handler.
|
||||
|
||||
```js
|
||||
// server.js
|
||||
const fastify = require('fastify')()
|
||||
|
||||
function handler (req, reply) {
|
||||
reply.send(reply.context.config.output)
|
||||
}
|
||||
|
||||
fastify.get('/en', { config: { output: 'hello world!' } }, handler)
|
||||
fastify.get('/it', { config: { output: 'ciao mondo!' } }, handler)
|
||||
|
||||
fastify.listen({ port: 3000 })
|
||||
```
|
||||
|
||||
### Constraints
|
||||
<a id="constraints"></a>
|
||||
|
||||
Fastify supports constraining routes to match only certain requests based on
|
||||
some property of the request, like the `Host` header, or any other value via
|
||||
[`find-my-way`](https://github.com/delvedor/find-my-way) constraints.
|
||||
Constraints are specified in the `constraints` property of the route options.
|
||||
Fastify has two built-in constraints ready for use: the `version` constraint and
|
||||
the `host` constraint, and you can add your own custom constraint strategies to
|
||||
inspect other parts of a request to decide if a route should be executed for a
|
||||
request.
|
||||
|
||||
#### Version Constraints
|
||||
|
||||
You can provide a `version` key in the `constraints` option to a route.
|
||||
Versioned routes allow you to declare multiple handlers for the same HTTP route
|
||||
path, which will then be matched according to each request's `Accept-Version`
|
||||
header. The `Accept-Version` header value should follow the
|
||||
[semver](https://semver.org/) specification, and routes should be declared with
|
||||
exact semver versions for matching.
|
||||
|
||||
Fastify will require a request `Accept-Version` header to be set if the route
|
||||
has a version set, and will prefer a versioned route to a non-versioned route
|
||||
for the same path. Advanced version ranges and pre-releases currently are not
|
||||
supported.
|
||||
|
||||
*Be aware that using this feature will cause a degradation of the overall
|
||||
performances of the router.*
|
||||
|
||||
```js
|
||||
fastify.route({
|
||||
method: 'GET',
|
||||
url: '/',
|
||||
constraints: { version: '1.2.0' },
|
||||
handler: function (request, reply) {
|
||||
reply.send({ hello: 'world' })
|
||||
}
|
||||
})
|
||||
|
||||
fastify.inject({
|
||||
method: 'GET',
|
||||
url: '/',
|
||||
headers: {
|
||||
'Accept-Version': '1.x' // it could also be '1.2.0' or '1.2.x'
|
||||
}
|
||||
}, (err, res) => {
|
||||
// { hello: 'world' }
|
||||
})
|
||||
```
|
||||
|
||||
> ## ⚠ Security Notice
|
||||
> Remember to set a
|
||||
> [`Vary`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary)
|
||||
> header in your responses with the value you are using for defining the
|
||||
> versioning (e.g.: `'Accept-Version'`), to prevent cache poisoning attacks. You
|
||||
> can also configure this as part of your Proxy/CDN.
|
||||
>
|
||||
> ```js
|
||||
> const append = require('vary').append
|
||||
> fastify.addHook('onSend', (req, reply, payload, done) => {
|
||||
> if (req.headers['accept-version']) { // or the custom header you are using
|
||||
> let value = reply.getHeader('Vary') || ''
|
||||
> const header = Array.isArray(value) ? value.join(', ') : String(value)
|
||||
> if ((value = append(header, 'Accept-Version'))) { // or the custom header you are using
|
||||
> reply.header('Vary', value)
|
||||
> }
|
||||
> }
|
||||
> done()
|
||||
> })
|
||||
> ```
|
||||
|
||||
If you declare multiple versions with the same major or minor, Fastify will
|
||||
always choose the highest compatible with the `Accept-Version` header value.
|
||||
|
||||
If the request will not have the `Accept-Version` header, a 404 error will be
|
||||
returned.
|
||||
|
||||
It is possible to define a custom version matching logic. This can be done
|
||||
through the [`constraints`](./Server.md#constraints) configuration when creating
|
||||
a Fastify server instance.
|
||||
|
||||
#### Host Constraints
|
||||
|
||||
You can provide a `host` key in the `constraints` route option for to limit that
|
||||
route to only be matched for certain values of the request `Host` header. `host`
|
||||
constraint values can be specified as strings for exact matches or RegExps for
|
||||
arbitrary host matching.
|
||||
|
||||
```js
|
||||
fastify.route({
|
||||
method: 'GET',
|
||||
url: '/',
|
||||
constraints: { host: 'auth.fastify.dev' },
|
||||
handler: function (request, reply) {
|
||||
reply.send('hello world from auth.fastify.dev')
|
||||
}
|
||||
})
|
||||
|
||||
fastify.inject({
|
||||
method: 'GET',
|
||||
url: '/',
|
||||
headers: {
|
||||
'Host': 'example.com'
|
||||
}
|
||||
}, (err, res) => {
|
||||
// 404 because the host doesn't match the constraint
|
||||
})
|
||||
|
||||
fastify.inject({
|
||||
method: 'GET',
|
||||
url: '/',
|
||||
headers: {
|
||||
'Host': 'auth.fastify.dev'
|
||||
}
|
||||
}, (err, res) => {
|
||||
// => 'hello world from auth.fastify.dev'
|
||||
})
|
||||
```
|
||||
|
||||
RegExp `host` constraints can also be specified allowing constraining to hosts
|
||||
matching wildcard subdomains (or any other pattern):
|
||||
|
||||
```js
|
||||
fastify.route({
|
||||
method: 'GET',
|
||||
url: '/',
|
||||
constraints: { host: /.*\.fastify\.io/ }, // will match any subdomain of fastify.dev
|
||||
handler: function (request, reply) {
|
||||
reply.send('hello world from ' + request.headers.host)
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
#### Asynchronous Custom Constraints
|
||||
|
||||
Custom constraints can be provided and the `constraint` criteria can be
|
||||
fetched from another source such as `database`. The use of asynchronous
|
||||
custom constraints should be a last resort as it impacts router
|
||||
performance.
|
||||
|
||||
```js
|
||||
function databaseOperation(field, done) {
|
||||
done(null, field)
|
||||
}
|
||||
|
||||
const secret = {
|
||||
// strategy name for referencing in the route handler `constraints` options
|
||||
name: 'secret',
|
||||
// storage factory for storing routes in the find-my-way route tree
|
||||
storage: function () {
|
||||
let handlers = {}
|
||||
return {
|
||||
get: (type) => { return handlers[type] || null },
|
||||
set: (type, store) => { handlers[type] = store }
|
||||
}
|
||||
},
|
||||
// function to get the value of the constraint from each incoming request
|
||||
deriveConstraint: (req, ctx, done) => {
|
||||
databaseOperation(req.headers['secret'], done)
|
||||
},
|
||||
// optional flag marking if handlers without constraints can match requests that have a value for this constraint
|
||||
mustMatchWhenDerived: true
|
||||
}
|
||||
```
|
||||
|
||||
> ## ⚠ Security Notice
|
||||
> When using with asynchronous constraint. It is highly recommend never return error
|
||||
> inside the callback. If the error is not preventable, it is recommended to provide
|
||||
> a custom `frameworkErrors` handler to deal with it. Otherwise, you route selection
|
||||
> may break or expose sensitive information to attackers.
|
||||
>
|
||||
> ```js
|
||||
> const Fastify = require('fastify')
|
||||
>
|
||||
> const fastify = Fastify({
|
||||
> frameworkErrors: function(err, res, res) {
|
||||
> if(err instanceof Fastify.errorCodes.FST_ERR_ASYNC_CONSTRAINT) {
|
||||
> res.code(400)
|
||||
> return res.send("Invalid header provided")
|
||||
> } else {
|
||||
> res.send(err)
|
||||
> }
|
||||
> }
|
||||
> })
|
||||
> ```
|
||||
|
||||
|
||||
### ⚠ HTTP version check
|
||||
|
||||
Fastify will check the HTTP version of every request, based on configuration
|
||||
options ([http2](./Server.md#http2), [https](./Server.md#https), and
|
||||
[serverFactory](./Server.md#serverfactory)), to determine if it matches one or
|
||||
all of the > following versions: `2.0`, `1.1`, and `1.0`. If Fastify receives a
|
||||
different HTTP version in the request it will return a `505 HTTP Version Not
|
||||
Supported` error.
|
||||
|
||||
| | 2.0 | 1.1 | 1.0 | skip |
|
||||
|:------------------------:|:---:|:---:|:---:|:----:|
|
||||
| http2 | ✓ | | | |
|
||||
| http2 + https | ✓ | | | |
|
||||
| http2 + https.allowHTTP1 | ✓ | ✓ | ✓ | |
|
||||
| https | | ✓ | ✓ | |
|
||||
| http | | ✓ | ✓ | |
|
||||
| serverFactory | | | | ✓ |
|
||||
|
||||
Note: The internal HTTP version check will be removed in the future when Node
|
||||
implements [this feature](https://github.com/nodejs/node/issues/43115).
|
||||
Reference in New Issue
Block a user