fastify-simple-form

Fastify plugin that adds content type parser for the application/x-www-form-urlencoded and/or multipart/form-data types.

Description

Essentially a tiny wrapper around busboy, that parses application/x-www-form-urlencoded and/or multipart/form-data content types and attaches associated fields to request.body.

NB! This plugin does not handle files, these get simply discarded as described here.

Install

npm install fastify-simple-form

TypeScript

Although this package includes typings for the plugin itself, you must install ones for node.js and busboy manually:

npm install @types/node @types/busboy --save-dev

Usage & Options

Selectively enable content types to parse

1fastify.register(require('fastify-simple-form'), {
2  multipart: true,   // Enable parsing for `multipart/form-data`, default: true
3  urlencoded: false, // Disable parsing for `application/x-www-form-urlencoded`, default: true
4});

This plugin has no effect when both options above are set to false.

Options for busboy

Options for busboy can be passed in using busboyOptions property which has identical shape to busboy constructor, e.g.:

1fastify.register(require('fastify-simple-form'), {
2  busboyOptions: {
3    defCharset: 'utf8',
4    limits: {
5      fieldNameSize: 100, // Max field name size (in bytes), default: 100
6      fieldSize: 1000000, // Max field value size (in bytes), default: 1MB
7      fields: 10,         // Max number of non-file fields, default: Infinity
8      // ...
9    },
10  },
11});

Prototype poisoning protection

1fastify.register(require('fastify-simple-form'), {
2  onConstructorPoisoning: 'ignore', // Possible values are 'error', 'remove' and 'ignore'
3  onProtoPoisoning: 'error'         // Possible values are 'error', 'remove' and 'ignore'
4});

• onConstructorPoisoning:
  • error - throws SyntaxError when a constructor key is found
  • remove - field will not be attached to request.body
  • ignore - field be be attached to request.body
• onProtoPoisoning:
  • error - throw SyntaxError when a key matching any property name of Object.prototype (besides constructor) is found
  • remove - field will not be attached to request.body
  • ignore - field be be attached to request.body

Both options will default to what is defined on Fastify root instance (or Fastify own defaults) for safe parsing of JSON objects. See onConstructorPoisoning and onProtoPoisoning.

Example

Given server & handler:

1import Fastify from 'fastify';
2import SimpleFormPlugin from 'fastify-simple-form';
3
4const fastify = Fastify();
5
6fastify.register(SimpleFormPlugin);
7
8fastify.post(
9  '/token',
10  {
11    schema: {
12      body: {
13        type: 'object',
14        properties: {
15          username: {
16            type: 'string',
17          },
18          password: {
19            type: 'string',
20          },
21          grant_type: {
22            type: 'string',
23            enum: ['password'],
24          },
25        },
26        required: ['grant_type'],
27      },
28    },
29  },
30  (request, reply) => {
31    reply.send(request.body);
32  },
33);
34
35fastify.listen(3000);

These requests would succeed:

1curl -F "username=jon" -F "password=snow" -F "grant_type=password" \
2  localhost:3000/token

1curl -d "username=jon" -d "password=snow" -d "grant_type=password" \
2  localhost:3000/token

Response:

1{
2  "username": "jon",
3  "password": "snow",
4  "grant_type": "password"
5}

While these won't pass the schema validation

1curl -F "username=jon" -F "password=snow" -F "grant_type=refresh_token" \
2  localhost:3000/token

1curl -d "username=jon" -d "password=snow" -d "grant_type=refresh_token" \
2  localhost:3000/token

Response

1{
2  "statusCode": 400,
3  "error": "Bad Request",
4  "message": "body.grant_type should be equal to one of the allowed values"
5}