Arminta
/
watermanagement-backend-prod
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '3de4ca38b5'
${ noResults }
watermanagement-backend-prod/node_modules/fastify/docs/Reference/Validation-and-Serializatio...

943 lines
25 KiB
Raw Normal View History Unescape

Removed multer
3 years ago
<h1 align="center">Fastify</h1>
## Validation and Serialization
Fastify uses a schema-based approach, and even if it is not mandatory we
recommend using [JSON Schema](https://json-schema.org/) to validate your routes
and serialize your outputs. Internally, Fastify compiles the schema into a
highly performant function.
Validation will only be attempted if the content type is `application-json`,
as described in the documentation for the [content type parser](./ContentTypeParser.md).
> ## ⚠ Security Notice
> Treat the schema definition as application code. Validation and serialization
> features dynamically evaluate code with `new Function()`, which is not safe to
> use with user-provided schemas. See [Ajv](https://npm.im/ajv) and
> [fast-json-stringify](https://npm.im/fast-json-stringify) for more details.
>
> Moreover, the [`$async` Ajv
> feature](https://ajv.js.org/guide/async-validation.html) should not be used as
> part of the first validation strategy. This option is used to access Databases
> and reading them during the validation process may lead to Denial of Service
> Attacks to your application. If you need to run `async` tasks, use [Fastify's
> hooks](./Hooks.md) instead after validation completes, such as `preHandler`.
### Core concepts
The validation and the serialization tasks are processed by two different, and
customizable, actors:
- [Ajv v6](https://www.npmjs.com/package/ajv/v/6.12.6) for the validation of a
request
- [fast-json-stringify](https://www.npmjs.com/package/fast-json-stringify) for
the serialization of a response's body
These two separate entities share only the JSON schemas added to Fastify's
instance through `.addSchema(schema)`.
#### Adding a shared schema
<a id="shared-schema"></a>
Thanks to the `addSchema` API, you can add multiple schemas to the Fastify
instance and then reuse them in multiple parts of your application. As usual,
this API is encapsulated.
The shared schemas can be reused through the JSON Schema
[**`$ref`**](https://tools.ietf.org/html/draft-handrews-json-schema-01#section-8)
keyword. Here an overview of _how_ references work:
+ `myField: { $ref: '#foo'}` will search for field with `$id: '#foo'` inside the
current schema
+ `myField: { $ref: '#/definitions/foo'}` will search for field
`definitions.foo` inside the current schema
+ `myField: { $ref: 'http://url.com/sh.json#'}` will search for a shared schema
added with `$id: 'http://url.com/sh.json'`
+ `myField: { $ref: 'http://url.com/sh.json#/definitions/foo'}` will search for
a shared schema added with `$id: 'http://url.com/sh.json'` and will use the
field `definitions.foo`
+ `myField: { $ref: 'http://url.com/sh.json#foo'}` will search for a shared
schema added with `$id: 'http://url.com/sh.json'` and it will look inside of
it for object with `$id: '#foo'`
**Simple usage:**
```js
fastify.addSchema({
$id: 'http://example.com/',
type: 'object',
properties: {
hello: { type: 'string' }
}
})
fastify.post('/', {
handler () {},
schema: {
body: {
type: 'array',
items: { $ref: 'http://example.com#/properties/hello' }
}
}
})
```
**`$ref` as root reference:**
```js
fastify.addSchema({
$id: 'commonSchema',
type: 'object',
properties: {
hello: { type: 'string' }
}
})
fastify.post('/', {
handler () {},
schema: {
body: { $ref: 'commonSchema#' },
headers: { $ref: 'commonSchema#' }
}
})
```
#### Retrieving the shared schemas
<a id="get-shared-schema"></a>
If the validator and the serializer are customized, the `.addSchema` method will
not be useful since the actors are no longer controlled by Fastify. To access
the schemas added to the Fastify instance, you can simply use `.getSchemas()`:
```js
fastify.addSchema({
$id: 'schemaId',
type: 'object',
properties: {
hello: { type: 'string' }
}
})
const mySchemas = fastify.getSchemas()
const mySchema = fastify.getSchema('schemaId')
```
As usual, the function `getSchemas` is encapsulated and returns the shared
schemas available in the selected scope:
```js
fastify.addSchema({ $id: 'one', my: 'hello' })
// will return only `one` schema
fastify.get('/', (request, reply) => { reply.send(fastify.getSchemas()) })
fastify.register((instance, opts, done) => {
instance.addSchema({ $id: 'two', my: 'ciao' })
// will return `one` and `two` schemas
instance.get('/sub', (request, reply) => { reply.send(instance.getSchemas()) })
instance.register((subinstance, opts, done) => {
subinstance.addSchema({ $id: 'three', my: 'hola' })
// will return `one`, `two` and `three`
subinstance.get('/deep', (request, reply) => { reply.send(subinstance.getSchemas()) })
done()
})
done()
})
```
### Validation
The route validation internally relies upon [Ajv
v6](https://www.npmjs.com/package/ajv/v/6.12.6) which is a high-performance JSON
Schema validator. Validating the input is very easy: just add the fields that
you need inside the route schema, and you are done!
The supported validations are:
- `body`: validates the body of the request if it is a POST, PUT, or PATCH
method.
- `querystring` or `query`: validates the query string.
- `params`: validates the route params.
- `headers`: validates the request headers.
All the validations can be a complete JSON Schema object (with a `type` property
of `'object'` and a `'properties'` object containing parameters) or a simpler
variation in which the `type` and `properties` attributes are forgone and the
parameters are listed at the top level (see the example below).
> ℹ If you need to use the lastest version of Ajv (v8) you should read how to do
> it in the [`schemaController`](./Server.md#schema-controller) section. It is
> explained the easier way to avoid to implement a custom validator.
Example:
```js
const bodyJsonSchema = {
type: 'object',
required: ['requiredKey'],
properties: {
someKey: { type: 'string' },
someOtherKey: { type: 'number' },
requiredKey: {
type: 'array',
maxItems: 3,
items: { type: 'integer' }
},
nullableKey: { type: ['number', 'null'] }, // or { type: 'number', nullable: true }
multipleTypesKey: { type: ['boolean', 'number'] },
multipleRestrictedTypesKey: {
oneOf: [
{ type: 'string', maxLength: 5 },
{ type: 'number', minimum: 10 }
]
},
enumKey: {
type: 'string',
enum: ['John', 'Foo']
},
notTypeKey: {
not: { type: 'array' }
}
}
}
const queryStringJsonSchema = {
type: 'object',
properties: {
name: { type: 'string' },
excitement: { type: 'integer' }
}
}
const paramsJsonSchema = {
type: 'object',
properties: {
par1: { type: 'string' },
par2: { type: 'number' }
}
}
const headersJsonSchema = {
type: 'object',
properties: {
'x-foo': { type: 'string' }
},
required: ['x-foo']
}
const schema = {
body: bodyJsonSchema,
querystring: queryStringJsonSchema,
params: paramsJsonSchema,
headers: headersJsonSchema
}
fastify.post('/the/url', { schema }, handler)
```
*Note that Ajv will try to
[coerce](https://github.com/epoberezkin/ajv#coercing-data-types) the values to
the types specified in your schema `type` keywords, both to pass the validation
and to use the correctly typed data afterwards.*
The Ajv default configuration in Fastify doesn't support coercing array
parameters in querystring. However, Fastify allows
[`customOptions`](./Server.md#ajv) in Ajv instance. The `coerceTypes: 'array'`
will coerce one parameter to a single element in array. Example:
```js
const opts = {
schema: {
querystring: {
type: 'object',
properties: {
ids: {
type: 'array',
default: []
},
},
}
}
}
fastify.get('/', opts, (request, reply) => {
reply.send({ params: request.query })
})
fastify.listen(3000, (err) => {
if (err) throw err
})
```
Using Fastify defaults the following request will result in `400` status code:
```sh
curl -X GET "http://localhost:3000/?ids=1
{"statusCode":400,"error":"Bad Request","message":"querystring/hello should be array"}
```
Using `coerceTypes` as 'array' will fix it:
```js
const ajv = new Ajv({
removeAdditional: true,
useDefaults: true,
coerceTypes: 'array', // This line
allErrors: true
})
fastify.setValidatorCompiler(({ schema, method, url, httpPart }) => {
return ajv.compile(schema)
})
```
```sh
curl -X GET "http://localhost:3000/?ids=1
{"params":{"hello":["1"]}}
```
You can also specify a custom schema validator for each parameter type (body,
querystring, params, headers).
For example, the following code disable type coercion only for the `body`
parameters, changing the ajv default options:
```js
const schemaCompilers = {
body: new Ajv({
removeAdditional: false,
coerceTypes: false,
allErrors: true
}),
params: new Ajv({
removeAdditional: false,
coerceTypes: true,
allErrors: true
}),
querystring: new Ajv({
removeAdditional: false,
coerceTypes: true,
allErrors: true
}),
headers: new Ajv({
removeAdditional: false,
coerceTypes: true,
allErrors: true
})
}
server.setValidatorCompiler(req => {
if (!req.httpPart) {
throw new Error('Missing httpPart')
}
const compiler = schemaCompilers[req.httpPart]
if (!compiler) {
throw new Error(`Missing compiler for ${req.httpPart}`)
}
return compiler.compile(req.schema)
})
```
For further information see [here](https://ajv.js.org/coercion.html)
#### Ajv Plugins
<a id="ajv-plugins"></a>
You can provide a list of plugins you want to use with the default `ajv`
instance. Note that the plugin must be **compatible with Ajv v6**.
> Refer to [`ajv options`](./Server.md#ajv) to check plugins format
```js
const fastify = require('fastify')({
ajv: {
plugins: [
require('ajv-merge-patch')
]
}
})
fastify.post('/', {
handler (req, reply) { reply.send({ ok: 1 }) },
schema: {
body: {
$patch: {
source: {
type: 'object',
properties: {
q: {
type: 'string'
}
}
},
with: [
{
op: 'add',
path: '/properties/q',
value: { type: 'number' }
}
]
}
}
}
})
fastify.post('/foo', {
handler (req, reply) { reply.send({ ok: 1 }) },
schema: {
body: {
$merge: {
source: {
type: 'object',
properties: {
q: {
type: 'string'
}
}
},
with: {
required: ['q']
}
}
}
}
})
```
#### Validator Compiler
<a id="schema-validator"></a>
The `validatorCompiler` is a function that returns a function that validates the
body, URL parameters, headers, and query string. The default
`validatorCompiler` returns a function that implements the
[ajv](https://ajv.js.org/) validation interface. Fastify uses it internally to
speed the validation up.
Fastify's [baseline ajv
configuration](https://github.com/epoberezkin/ajv#options-to-modify-validated-data)
is:
```js
{
removeAdditional: true, // remove additional properties
useDefaults: true, // replace missing properties and items with the values from corresponding default keyword
coerceTypes: true, // change data type of data to match type keyword
nullable: true // support keyword "nullable" from Open API 3 specification.
}
```
This baseline configuration can be modified by providing
[`ajv.customOptions`](./Server.md#factory-ajv) to your Fastify factory.
If you want to change or set additional config options, you will need to create
your own instance and override the existing one like:
```js
const fastify = require('fastify')()
const Ajv = require('ajv')
const ajv = new Ajv({
// the fastify defaults (if needed)
removeAdditional: true,
useDefaults: true,
coerceTypes: true,
nullable: true,
// any other options
// ...
})
fastify.setValidatorCompiler(({ schema, method, url, httpPart }) => {
return ajv.compile(schema)
})
```
_**Note:** If you use a custom instance of any validator (even Ajv), you have to
add schemas to the validator instead of Fastify, since Fastify's default
validator is no longer used, and Fastify's `addSchema` method has no idea what
validator you are using._
##### Using other validation libraries
<a id="using-other-validation-libraries"></a>
The `setValidatorCompiler` function makes it easy to substitute `ajv` with
almost any Javascript validation library ([joi](https://github.com/hapijs/joi/),
[yup](https://github.com/jquense/yup/), ...) or a custom one:
```js
const Joi = require('@hapi/joi')
fastify.post('/the/url', {
schema: {
body: Joi.object().keys({
hello: Joi.string().required()
}).required()
},
validatorCompiler: ({ schema, method, url, httpPart }) => {
return data => schema.validate(data)
}
}, handler)
```
```js
const yup = require('yup')
// Validation options to match ajv's baseline options used in Fastify
const yupOptions = {
strict: false,
abortEarly: false, // return all errors
stripUnknown: true, // remove additional properties
recursive: true
}
fastify.post('/the/url', {
schema: {
body: yup.object({
age: yup.number().integer().required(),
sub: yup.object().shape({
name: yup.string().required()
}).required()
})
},
validatorCompiler: ({ schema, method, url, httpPart }) => {
return function (data) {
// with option strict = false, yup `validateSync` function returns the coerced value if validation was successful, or throws if validation failed
try {
const result = schema.validateSync(data, yupOptions)
return { value: result }
} catch (e) {
return { error: e }
}
}
}
}, handler)
```
##### Validation messages with other validation libraries
Fastify's validation error messages are tightly coupled to the default
validation engine: errors returned from `ajv` are eventually run through the
`schemaErrorsText` function which is responsible for building human-friendly
error messages. However, the `schemaErrorsText` function is written with `ajv`
in mind : as a result, you may run into odd or incomplete error messages when
using other validation libraries.
To circumvent this issue, you have 2 main options :
1. make sure your validation function (returned by your custom `schemaCompiler`)
returns errors in the exact same structure and format as `ajv` (although this
could prove to be difficult and tricky due to differences between validation
engines)
2. or use a custom `errorHandler` to intercept and format your 'custom'
validation errors
To help you in writing a custom `errorHandler`, Fastify adds 2 properties to all
validation errors:
* validation: the content of the `error` property of the object returned by the
validation function (returned by your custom `schemaCompiler`)
* validationContext: the 'context' (body, params, query, headers) where the
validation error occurred
A very contrived example of such a custom `errorHandler` handling validation
errors is shown below:
```js
const errorHandler = (error, request, reply) => {
const statusCode = error.statusCode
let response
const { validation, validationContext } = error
// check if we have a validation error
if (validation) {
response = {
// validationContext will be 'body' or 'params' or 'headers' or 'query'
message: `A validation error occurred when validating the ${validationContext}...`,
// this is the result of your validation library...
errors: validation
}
} else {
response = {
message: 'An error occurred...'
}
}
// any additional work here, eg. log error
// ...
reply.status(statusCode).send(response)
}
```
### Serialization
<a id="serialization"></a>
Usually, you will send your data to the clients as JSON, and Fastify has a
powerful tool to help you,
[fast-json-stringify](https://www.npmjs.com/package/fast-json-stringify), which
is used if you have provided an output schema in the route options. We encourage
you to use an output schema, as it can drastically increase throughput and help
prevent accidental disclosure of sensitive information.
Example:
```js
const schema = {
response: {
200: {
type: 'object',
properties: {
value: { type: 'string' },
otherValue: { type: 'boolean' }
}
}
}
}
fastify.post('/the/url', { schema }, handler)
```
As you can see, the response schema is based on the status code. If you want to
use the same schema for multiple status codes, you can use `'2xx'`, for example:
```js
const schema = {
response: {
'2xx': {
type: 'object',
properties: {
value: { type: 'string' },
otherValue: { type: 'boolean' }
}
},
201: {
// the contract syntax
value: { type: 'string' }
}
}
}
fastify.post('/the/url', { schema }, handler)
```
#### Serializer Compiler
<a id="schema-serializer"></a>
The `serializerCompiler` is a function that returns a function that must return
a string from an input object. When you define a response JSON Schema, you can
change the default serialization method by providing a function to serialize
every route where you do.
```js
fastify.setSerializerCompiler(({ schema, method, url, httpStatus }) => {
return data => JSON.stringify(data)
})
fastify.get('/user', {
handler (req, reply) {
reply.send({ id: 1, name: 'Foo', image: 'BIG IMAGE' })
},
schema: {
response: {
'2xx': {
id: { type: 'number' },
name: { type: 'string' }
}
}
}
})
```
*If you need a custom serializer in a very specific part of your code, you can
set one with [`reply.serializer(...)`](./Reply.md#serializerfunc).*
### Error Handling
When schema validation fails for a request, Fastify will automatically return a
status 400 response including the result from the validator in the payload. As
an example, if you have the following schema for your route
```js
const schema = {
body: {
type: 'object',
properties: {
name: { type: 'string' }
},
required: ['name']
}
}
```
and fail to satisfy it, the route will immediately return a response with the
following payload
```js
{
"statusCode": 400,
"error": "Bad Request",
"message": "body should have required property 'name'"
}
```
If you want to handle errors inside the route, you can specify the
`attachValidation` option for your route. If there is a _validation error_, the
`validationError` property of the request will contain the `Error` object with
the raw `validation` result as shown below
```js
const fastify = Fastify()
fastify.post('/', { schema, attachValidation: true }, function (req, reply) {
if (req.validationError) {
// `req.validationError.validation` contains the raw validation error
reply.code(400).send(req.validationError)
}
})
```
#### `schemaErrorFormatter`
If you want to format errors yourself, you can provide a sync function that must
return an error as the `schemaErrorFormatter` option to Fastify when
instantiating. The context function will be the Fastify server instance.
`errors` is an array of Fastify schema errors `FastifySchemaValidationError`.
`dataVar` is the currently validated part of the schema. (params | body |
querystring | headers).
```js
const fastify = Fastify({
schemaErrorFormatter: (errors, dataVar) => {
// ... my formatting logic
return new Error(myErrorMessage)
}
})
// or
fastify.setSchemaErrorFormatter(function (errors, dataVar) {
this.log.error({ err: errors }, 'Validation failed')
// ... my formatting logic
return new Error(myErrorMessage)
})
```
You can also use
[setErrorHandler](./Server.md#seterrorhandler) to
define a custom response for validation errors such as
```js
fastify.setErrorHandler(function (error, request, reply) {
if (error.validation) {
reply.status(422).send(new Error('validation failed'))
}
})
```
If you want custom error response in schema without headaches and quickly, you
can take a look at [`ajv-errors`](https://github.com/epoberezkin/ajv-errors).
Check out the
[example](https://github.com/fastify/example/blob/HEAD/validation-messages/custom-errors-messages.js)
usage.
> Make sure to install version 1.0.1 of `ajv-errors`, because later versions of
> it are not compatible with AJV v6 (the version shipped by Fastify v3).
Below is an example showing how to add **custom error messages for each
property** of a schema by supplying custom AJV options. Inline comments in the
schema below describe how to configure it to show a different error message for
each case:
```js
const fastify = Fastify({
ajv: {
customOptions: {
jsonPointers: true,
allErrors: true // Warning: Enabling this option may lead to this security issue https://www.cvedetails.com/cve/CVE-2020-8192/
},
plugins: [
require('ajv-errors')
]
}
})
const schema = {
body: {
type: 'object',
properties: {
name: {
type: 'string',
errorMessage: {
type: 'Bad name'
}
},
age: {
type: 'number',
errorMessage: {
type: 'Bad age', // specify custom message for
min: 'Too young' // all constraints except required
}
}
},
required: ['name', 'age'],
errorMessage: {
required: {
name: 'Why no name!', // specify error message for when the
age: 'Why no age!' // property is missing from input
}
}
}
}
fastify.post('/', { schema, }, (request, reply) => {
reply.send({
hello: 'world'
})
})
```
If you want to return localized error messages, take a look at
[ajv-i18n](https://github.com/epoberezkin/ajv-i18n)
```js
const localize = require('ajv-i18n')
const fastify = Fastify()
const schema = {
body: {
type: 'object',
properties: {
name: {
type: 'string',
},
age: {
type: 'number',
}
},
required: ['name', 'age'],
}
}
fastify.setErrorHandler(function (error, request, reply) {
if (error.validation) {
localize.ru(error.validation)
reply.status(400).send(error.validation)
return
}
reply.send(error)
})
```
### JSON Schema support
JSON Schema has some type of utilities in order to optimize your schemas that,
in conjunction with Fastify's shared schema, let you reuse all your schemas
easily.
| Use Case | Validator | Serializer |
|-----------------------------------|-----------|------------|
| `$ref` to `$id` | ️️✔️ | ✔️ |
| `$ref` to `/definitions` | ✔️ | ✔️ |
| `$ref` to shared schema `$id` | ✔️ | ✔️ |
| `$ref` to shared schema `/definitions` | ✔️ | ✔️ |
#### Examples
##### Usage of `$ref` to `$id` in same JSON Schema
```js
const refToId = {
type: 'object',
definitions: {
foo: {
$id: '#address',
type: 'object',
properties: {
city: { type: 'string' }
}
}
},
properties: {
home: { $ref: '#address' },
work: { $ref: '#address' }
}
}
```
##### Usage of `$ref` to `/definitions` in same JSON Schema
```js
const refToDefinitions = {
type: 'object',
definitions: {
foo: {
$id: '#address',
type: 'object',
properties: {
city: { type: 'string' }
}
}
},
properties: {
home: { $ref: '#/definitions/foo' },
work: { $ref: '#/definitions/foo' }
}
}
```
##### Usage `$ref` to a shared schema `$id` as external schema
```js
fastify.addSchema({
$id: 'http://foo/common.json',
type: 'object',
definitions: {
foo: {
$id: '#address',
type: 'object',
properties: {
city: { type: 'string' }
}
}
}
})
const refToSharedSchemaId = {
type: 'object',
properties: {
home: { $ref: 'http://foo/common.json#address' },
work: { $ref: 'http://foo/common.json#address' }
}
}
```
##### Usage `$ref` to a shared schema `/definitions` as external schema
```js
fastify.addSchema({
$id: 'http://foo/shared.json',
type: 'object',
definitions: {
foo: {
type: 'object',
properties: {
city: { type: 'string' }
}
}
}
})
const refToSharedSchemaDefinitions = {
type: 'object',
properties: {
home: { $ref: 'http://foo/shared.json#/definitions/foo' },
work: { $ref: 'http://foo/shared.json#/definitions/foo' }
}
}
```
### Resources
<a id="resources"></a>
- [JSON Schema](https://json-schema.org/)
- [Understanding JSON
Schema](https://spacetelescope.github.io/understanding-json-schema/)
- [fast-json-stringify
documentation](https://github.com/fastify/fast-json-stringify)
- [Ajv documentation](https://github.com/epoberezkin/ajv/blob/master/README.md)
- [Ajv i18n](https://github.com/epoberezkin/ajv-i18n)
- [Ajv custom errors](https://github.com/epoberezkin/ajv-errors)
- Custom error handling with core methods with error file dumping
[example](https://github.com/fastify/example/tree/master/validation-messages)