From e6bca66cf938386cb8a640b9130129ad8b941ac0 Mon Sep 17 00:00:00 2001 From: Tommaso Allevi Date: Mon, 27 Aug 2018 00:52:28 +0200 Subject: [PATCH] Move Server-Methods into Factory (#1101) * Move Server-Methods into Factory * Rename to Server.md * Update Readme.md --- README.md | 3 +- docs/ContentTypeParser.md | 4 +- docs/Factory.md | 196 ------------------------- docs/Logging.md | 2 +- docs/Reply.md | 4 +- docs/Routes.md | 2 +- docs/{Server-Methods.md => Server.md} | 203 +++++++++++++++++++++++++- 7 files changed, 207 insertions(+), 207 deletions(-) delete mode 100644 docs/Factory.md rename docs/{Server-Methods.md => Server.md} (52%) diff --git a/README.md b/README.md index 11ee18e3fb..63c26c72ed 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,7 @@ matters to you. ## Documentation * Getting Started -* Server Methods +* Server * Routes * Logging * Middlewares @@ -147,7 +147,6 @@ matters to you. * Reply * Request * Content Type Parser -* Factory * Plugins * Testing * Benchmarking diff --git a/docs/ContentTypeParser.md b/docs/ContentTypeParser.md index 7d71a96b35..d4670d70b0 100644 --- a/docs/ContentTypeParser.md +++ b/docs/ContentTypeParser.md @@ -38,7 +38,7 @@ if (!fastify.hasContentTypeParser('application/jsoff')){ ``` #### Body Parser -You can parse the body of the request in two ways. The first one is shown above: you add a custom content type parser and handle the request stream. In the second one you should pass a `parseAs` option to the `addContentTypeParser` API, where you declare how you want to get the body, it could be `'string'` or `'buffer'`. If you use the `parseAs` option Fastify will internally handle the stream and perform some checks, such as the [maximum size](https://github.com/fastify/fastify/blob/master/docs/Factory.md#factory-body-limit) of the body and the content length. If the limit is exceeded the custom parser will not be invoked. +You can parse the body of the request in two ways. The first one is shown above: you add a custom content type parser and handle the request stream. In the second one you should pass a `parseAs` option to the `addContentTypeParser` API, where you declare how you want to get the body, it could be `'string'` or `'buffer'`. If you use the `parseAs` option Fastify will internally handle the stream and perform some checks, such as the [maximum size](https://github.com/fastify/fastify/blob/master/docs/Server.md#factory-body-limit) of the body and the content length. If the limit is exceeded the custom parser will not be invoked. ```js fastify.addContentTypeParser('application/json', { parseAs: 'string' }, function (req, body, done) { try { @@ -56,7 +56,7 @@ See [`example/parser.js`](https://github.com/fastify/fastify/blob/master/example ##### Custom Parser Options + `parseAs` (string): Either `'string'` or `'buffer'` to designate how the incoming data should be collected. Default: `'buffer'`. -+ `bodyLimit` (number): The maximum payload size, in bytes, that the custom parser will accept. Defaults to the global body limit passed to the [`Fastify factory function`](https://github.com/fastify/fastify/blob/master/docs/Factory.md#bodylimit). ++ `bodyLimit` (number): The maximum payload size, in bytes, that the custom parser will accept. Defaults to the global body limit passed to the [`Fastify factory function`](https://github.com/fastify/fastify/blob/master/docs/Server.md#bodylimit). #### Catch All There are some cases where you need to catch all requests regardless of their content type. With Fastify, you just need to add the `'*'` content type. diff --git a/docs/Factory.md b/docs/Factory.md deleted file mode 100644 index 8b209ef18a..0000000000 --- a/docs/Factory.md +++ /dev/null @@ -1,196 +0,0 @@ -

Fastify

- - -## Factory - -The Fastify module exports a factory function that is used to create new -Fastify server -instances. This factory function accepts an options object which is used to -customize the resulting instance. This document describes the properties -available in that options object. - - -### `http2` (Status: experimental) - -If `true` Node.js core's [HTTP/2](https://nodejs.org/dist/latest-v8.x/docs/api/http2.html) module is used for binding the socket. - -+ Default: `false` - - -### `https` - -An object used to configure the server's listening socket for TLS. The options -are the same as the Node.js core -[`createServer` method](https://nodejs.org/dist/latest-v8.x/docs/api/https.html#https_https_createserver_options_requestlistener). -When this property is `null`, the socket will not be configured for TLS. - -This option also applies when the - -http2 - option is set. - -+ Default: `null` - - -### `ignoreTrailingSlash` - -Fastify uses [find-my-way](https://github.com/delvedor/find-my-way) to handle -routing. This option may be set to `true` to ignore trailing slashes in routes. -This option applies to *all* route registrations for the resulting server -instance. - -+ Default: `false` - -```js -const fastify = require('fastify')({ - ignoreTrailingSlash: true -}) - -// registers both "/foo" and "/foo/" -fastify.get('/foo/', function (req, reply) { - res.send('foo') -}) - -// registers both "/bar" and "/bar/" -fastify.get('/bar', function (req, reply) { - res.send('bar') -}) -``` - - -### `maxParamLength` -You can set a custom length for parameters in parametric (standard, regex and multi) routes by using `maxParamLength` option, the default value is 100 characters.
-This can be useful especially if you have some regex based route, protecting you against [DoS attacks](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS).
-*If the maximum length limit is reached, the not found route will be invoked.* - - -### `bodyLimit` - -Defines the maximum payload, in bytes, the server is allowed to accept. - -+ Default: `1048576` (1MiB) - - -### `logger` - -Fastify includes built-in logging via the [Pino](https://getpino.io/) logger. -This property is used to configure the internal logger instance. - -The possible values this property may have are: - -+ Default: `false`. The logger is disabled. All logging methods will point to a -null logger [abstract-logging](https://npm.im/abstract-logging) instance. - -+ `pinoInstance`: a previously instantiated instance of Pino. The internal -logger will point to this instance. - -+ `object`: a standard Pino [options object](https://github.com/pinojs/pino/blob/c77d8ec5ce/docs/API.md#constructor). -This will be passed directly to the Pino constructor. If the following properties -are not present on the object, they will be added accordingly: - * `genReqId`: a synchronous function that will be used to generate identifiers - for incoming requests. The default function generates sequential identifiers. - * `level`: the minimum logging level. If not set, it will be set to `'info'`. - * `serializers`: a hash of serialization functions. By default, serializers - are added for `req` (incoming request objects), `res` (outgoing repsonse - objets), and `err` (standard `Error` objects). When a log method receives - an object with any of these properties then the respective serializer will - be used for that property. For example: - ```js - fastify.get('/foo', function (req, res) { - req.log.info({req}) // log the serialized request object - res.send('foo') - }) - ``` - Any user supplied serializer will override the default serializer of the - corresponding property. - - -### `serverFactory` -You can pass a custom http server to Fastify by using the `serverFactory` option.
-`serverFactory` is a function that takes an `handler` parameter, which takes the `request` and `response` objects as parameters, and an options object, which is the same you have passed to Fastify. - -```js -const serverFactory = (handler, opts) => { - const server = http.createServer((req, res) => { - handler(req, res) - }) - - return server -} - -const fastify = Fastify({ serverFactory }) - -fastify.get('/', (req, reply) => { - reply.send({ hello: 'world' }) -}) - -fastify.listen(3000) -``` - -Internally Fastify uses the API of Node core http server, so if you are using a custom server you must be sure to have the same API exposed. If not, you can enhance the server instance inside the `serverFactory` function before the `return` statement. - - -### `caseSensitive` - -By default, value equal to `true`, routes are registered as case sensitive. That is, `/foo` is not equivalent to `/Foo`. When set to `false`, routes are registered in a fashion such that `/foo` is equivalent to `/Foo` which is equivalent to `/FOO`. - -Setting `caseSensitive` to `false` will also result in -all params (and all value matched by regexps) to be lowercased as well. - -```js -fastify.get('/user/:username', (request, reply) => { - // Given the URL: /user/NodeJS - console.log(request.params.username) // -> 'nodejs' -}) -``` - -Please note this setting this option to `false` goes against -[RFC3986](https://tools.ietf.org/html/rfc3986#section-6.2.2.1). - - -### `requestIdHeader` - -The header name used to know the request id. See [the request id](https://github.com/fastify/fastify/blob/master/docs/Logging.md#logging-request-id) section. - -+ Default: `'request-id'` - - -### `trustProxy` - -By enabling the `trustProxy` option, Fastify will have knowledge that it's sitting behind a proxy and that the `X-Forwarded-*` header fields may be trusted, which otherwise may be easily spoofed. - -```js -const fastify = Fastify({ trustProxy: true }) -``` - -+ Default: `false` -+ `true/false`: Trust all proxies (`true`) or do not trust any proxies (`false`). -+ `string`: Trust only given IP/CIDR (e.g. `'127.0.0.1'`). May be a list of comma separated values (e.g. `'127.0.0.1,192.168.1.1/24'`). -+ `Array`: Trust only given IP/CIDR list (e.g. `['127.0.0.1']`). -+ `number`: Trust the nth hop from the front-facing proxy server as the client. -+ `Function`: Custom trust function that takes `address` as first arg - ```js - function myTrustFn(address, hop) { - return address === '1.2.3.4' || hop === 1 - } - ``` - -For more examples refer to [proxy-addr](https://www.npmjs.com/package/proxy-addr) package. - -You may also access `ip` and `hostname` values from raw `request`. - -```js -fastify.get('/', (request, reply) => { - console.log(request.raw.ip) - console.log(request.raw.hostname) -}) -``` - - -### `pluginTimeout` - -The maximum amount of time in milliseconds in which a plugin can load. -If not, [`ready`](https://github.com/fastify/fastify/blob/master/docs/Server-Methods.md#ready) -will complete with an `Error` with code `'ERR_AVVIO_PLUGIN_TIMEOUT'`. - -+ Default: `0` (disabled) diff --git a/docs/Logging.md b/docs/Logging.md index cf3a60beee..593e967d45 100644 --- a/docs/Logging.md +++ b/docs/Logging.md @@ -46,7 +46,7 @@ fastify.get('/', options, function (request, reply) { -By default fastify adds an id to every request for easier tracking. If the "request-id" header is present its value is used, otherwise a new incremental id is generated. See Fastify Factory [`requestIdHeader`](https://github.com/fastify/fastify/blob/master/docs/Factory.md#factory-request-id-header) options for customizing that header name. +By default fastify adds an id to every request for easier tracking. If the "request-id" header is present its value is used, otherwise a new incremental id is generated. See Fastify Factory [`requestIdHeader`](https://github.com/fastify/fastify/blob/master/docs/Server.md#factory-request-id-header) options for customizing that header name. Additionally, `genReqId` option can be used for generating the request id by yourself. It will received the incoming request as a parameter. ```js diff --git a/docs/Reply.md b/docs/Reply.md index 651555ada3..0e1f508f6f 100644 --- a/docs/Reply.md +++ b/docs/Reply.md @@ -170,10 +170,10 @@ fastify.get('/', function (request, reply) { }) ``` -If you want to completely customize the error response, checkout [`setErrorHandler`](https://github.com/fastify/fastify/blob/master/docs/Server-Methods.md#seterrorhandler) API. +If you want to completely customize the error response, checkout [`setErrorHandler`](https://github.com/fastify/fastify/blob/master/docs/Server.md#seterrorhandler) API. Errors with a `status` or `statusCode` property equal to `404` will be routed to the not found handler. -See [`server.setNotFoundHandler`](https://github.com/fastify/fastify/blob/master/docs/Server-Methods.md#setnotfoundhandler) +See [`server.setNotFoundHandler`](https://github.com/fastify/fastify/blob/master/docs/Server.md#setnotfoundhandler) API to learn more about handling such cases: ```js diff --git a/docs/Routes.md b/docs/Routes.md index 9434689874..d4b9ad5d59 100644 --- a/docs/Routes.md +++ b/docs/Routes.md @@ -234,7 +234,7 @@ Be aware that if you use [`fastify-plugin`](https://github.com/fastify/fastify-p It could happen that you need different log levels in your routes, with Fastify achieve this is very straightforward.
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#discussion-3) that you need. -Be aware that if you set the `logLevel` at plugin level, also the [`setNotFoundHandler`](https://github.com/fastify/fastify/blob/master/docs/Server-Methods.md#setnotfoundhandler) and [`setErrorHandler`](https://github.com/fastify/fastify/blob/master/docs/Server-Methods.md#seterrorhandler) will be affected. +Be aware that if you set the `logLevel` at plugin level, also the [`setNotFoundHandler`](https://github.com/fastify/fastify/blob/master/docs/Server.md#setnotfoundhandler) and [`setErrorHandler`](https://github.com/fastify/fastify/blob/master/docs/Server.md#seterrorhandler) will be affected. ```js // server.js diff --git a/docs/Server-Methods.md b/docs/Server.md similarity index 52% rename from docs/Server-Methods.md rename to docs/Server.md index daec005c76..6c9b9b102f 100644 --- a/docs/Server-Methods.md +++ b/docs/Server.md @@ -1,10 +1,207 @@

Fastify

-## Server Methods + +## Factory + +The Fastify module exports a factory function that is used to create new +Fastify server +instances. This factory function accepts an options object which is used to +customize the resulting instance. This document describes the properties +available in that options object. + + +### `http2` (Status: experimental) + +If `true` Node.js core's [HTTP/2](https://nodejs.org/dist/latest-v8.x/docs/api/http2.html) module is used for binding the socket. + ++ Default: `false` + + +### `https` + +An object used to configure the server's listening socket for TLS. The options +are the same as the Node.js core +[`createServer` method](https://nodejs.org/dist/latest-v8.x/docs/api/https.html#https_https_createserver_options_requestlistener). +When this property is `null`, the socket will not be configured for TLS. + +This option also applies when the + +http2 + option is set. + ++ Default: `null` + + +### `ignoreTrailingSlash` + +Fastify uses [find-my-way](https://github.com/delvedor/find-my-way) to handle +routing. This option may be set to `true` to ignore trailing slashes in routes. +This option applies to *all* route registrations for the resulting server +instance. + ++ Default: `false` + +```js +const fastify = require('fastify')({ + ignoreTrailingSlash: true +}) + +// registers both "/foo" and "/foo/" +fastify.get('/foo/', function (req, reply) { + res.send('foo') +}) + +// registers both "/bar" and "/bar/" +fastify.get('/bar', function (req, reply) { + res.send('bar') +}) +``` + + +### `maxParamLength` +You can set a custom length for parameters in parametric (standard, regex and multi) routes by using `maxParamLength` option, the default value is 100 characters.
+This can be useful especially if you have some regex based route, protecting you against [DoS attacks](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS).
+*If the maximum length limit is reached, the not found route will be invoked.* + + +### `bodyLimit` + +Defines the maximum payload, in bytes, the server is allowed to accept. + ++ Default: `1048576` (1MiB) + + +### `logger` + +Fastify includes built-in logging via the [Pino](https://getpino.io/) logger. +This property is used to configure the internal logger instance. + +The possible values this property may have are: + ++ Default: `false`. The logger is disabled. All logging methods will point to a +null logger [abstract-logging](https://npm.im/abstract-logging) instance. + ++ `pinoInstance`: a previously instantiated instance of Pino. The internal +logger will point to this instance. + ++ `object`: a standard Pino [options object](https://github.com/pinojs/pino/blob/c77d8ec5ce/docs/API.md#constructor). +This will be passed directly to the Pino constructor. If the following properties +are not present on the object, they will be added accordingly: + * `genReqId`: a synchronous function that will be used to generate identifiers + for incoming requests. The default function generates sequential identifiers. + * `level`: the minimum logging level. If not set, it will be set to `'info'`. + * `serializers`: a hash of serialization functions. By default, serializers + are added for `req` (incoming request objects), `res` (outgoing repsonse + objets), and `err` (standard `Error` objects). When a log method receives + an object with any of these properties then the respective serializer will + be used for that property. For example: + ```js + fastify.get('/foo', function (req, res) { + req.log.info({req}) // log the serialized request object + res.send('foo') + }) + ``` + Any user supplied serializer will override the default serializer of the + corresponding property. + + +### `serverFactory` +You can pass a custom http server to Fastify by using the `serverFactory` option.
+`serverFactory` is a function that takes an `handler` parameter, which takes the `request` and `response` objects as parameters, and an options object, which is the same you have passed to Fastify. + +```js +const serverFactory = (handler, opts) => { + const server = http.createServer((req, res) => { + handler(req, res) + }) + + return server +} + +const fastify = Fastify({ serverFactory }) + +fastify.get('/', (req, reply) => { + reply.send({ hello: 'world' }) +}) + +fastify.listen(3000) +``` + +Internally Fastify uses the API of Node core http server, so if you are using a custom server you must be sure to have the same API exposed. If not, you can enhance the server instance inside the `serverFactory` function before the `return` statement. + + +### `caseSensitive` + +By default, value equal to `true`, routes are registered as case sensitive. That is, `/foo` is not equivalent to `/Foo`. When set to `false`, routes are registered in a fashion such that `/foo` is equivalent to `/Foo` which is equivalent to `/FOO`. + +Setting `caseSensitive` to `false` will also result in +all params (and all value matched by regexps) to be lowercased as well. + +```js +fastify.get('/user/:username', (request, reply) => { + // Given the URL: /user/NodeJS + console.log(request.params.username) // -> 'nodejs' +}) +``` + +Please note this setting this option to `false` goes against +[RFC3986](https://tools.ietf.org/html/rfc3986#section-6.2.2.1). + + +### `requestIdHeader` + +The header name used to know the request id. See [the request id](https://github.com/fastify/fastify/blob/master/docs/Logging.md#logging-request-id) section. + ++ Default: `'request-id'` + + +### `trustProxy` + +By enabling the `trustProxy` option, Fastify will have knowledge that it's sitting behind a proxy and that the `X-Forwarded-*` header fields may be trusted, which otherwise may be easily spoofed. + +```js +const fastify = Fastify({ trustProxy: true }) +``` + ++ Default: `false` ++ `true/false`: Trust all proxies (`true`) or do not trust any proxies (`false`). ++ `string`: Trust only given IP/CIDR (e.g. `'127.0.0.1'`). May be a list of comma separated values (e.g. `'127.0.0.1,192.168.1.1/24'`). ++ `Array`: Trust only given IP/CIDR list (e.g. `['127.0.0.1']`). ++ `number`: Trust the nth hop from the front-facing proxy server as the client. ++ `Function`: Custom trust function that takes `address` as first arg + ```js + function myTrustFn(address, hop) { + return address === '1.2.3.4' || hop === 1 + } + ``` + +For more examples refer to [proxy-addr](https://www.npmjs.com/package/proxy-addr) package. + +You may also access `ip` and `hostname` values from raw `request`. + +```js +fastify.get('/', (request, reply) => { + console.log(request.raw.ip) + console.log(request.raw.hostname) +}) +``` + + +### `pluginTimeout` + +The maximum amount of time in milliseconds in which a plugin can load. +If not, [`ready`](https://github.com/fastify/fastify/blob/master/docs/Server.md#ready) +will complete with an `Error` with code `'ERR_AVVIO_PLUGIN_TIMEOUT'`. + ++ Default: `0` (disabled) + +## Instance + +### Server Methods #### server -`fastify.server`: The Node core [server](https://nodejs.org/api/http.html#http_class_http_server) object as returned by the [**`Fastify factory function`**](https://github.com/fastify/fastify/blob/master/docs/Factory.md). +`fastify.server`: The Node core [server](https://nodejs.org/api/http.html#http_class_http_server) object as returned by the [**`Fastify factory function`**](https://github.com/fastify/fastify/blob/master/docs/Server.md). #### after @@ -193,7 +390,7 @@ Set the schema compiler for all routes [here](https://github.com/fastify/fastify `fastify.setNotFoundHandler(handler(request, reply))`: set the 404 handler. This call is encapsulated by prefix, so different plugins can set different not found handlers if a different [`prefix` option](https://github.com/fastify/fastify/blob/master/docs/Plugins.md#route-prefixing-option) is passed to `fastify.register()`. The handler is treated like a regular route handler so requests will go through the full [Fastify lifecycle](https://github.com/fastify/fastify/blob/master/docs/Lifecycle.md#lifecycle). -You can also register [beforeHandler](https://www.fastify.io/docs/latest/Hooks/#beforehandler) hook for the 404 handler. +You can also register [beforeHandler](https://www.fastify.io/docs/latest/Hooks/#beforehandler) hook for the 404 handler. ```js fastify.setNotFoundHandler({