148 lines
4.0 KiB
Markdown
148 lines
4.0 KiB
Markdown
|
# finalhandler
|
||
|
|
|
||
|
|
[![NPM Version][npm-image]][npm-url]
|
||
|
|
[![NPM Downloads][downloads-image]][downloads-url]
|
||
|
|
[![Node.js Version][node-image]][node-url]
|
||
|
|
[![Build Status][github-actions-ci-image]][github-actions-ci-url]
|
||
|
|
[![Test Coverage][coveralls-image]][coveralls-url]
|
||
|
|
|
||
|
|
Node.js function to invoke as the final step to respond to HTTP request.
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
This is a [Node.js](https://nodejs.org/en/) module available through the
|
||
|
|
[npm registry](https://www.npmjs.com/). Installation is done using the
|
||
|
|
[`npm install` command](https://docs.npmjs.com/getting-started/installing-npm-packages-locally):
|
||
|
|
|
||
|
|
```sh
|
||
|
|
$ npm install finalhandler
|
||
|
|
```
|
||
|
|
|
||
|
|
## API
|
||
|
|
|
||
|
|
```js
|
||
|
|
var finalhandler = require('finalhandler')
|
||
|
|
```
|
||
|
|
|
||
|
|
### finalhandler(req, res, [options])
|
||
|
|
|
||
|
|
Returns function to be invoked as the final step for the given `req` and `res`.
|
||
|
|
This function is to be invoked as `fn(err)`. If `err` is falsy, the handler will
|
||
|
|
write out a 404 response to the `res`. If it is truthy, an error response will
|
||
|
|
be written out to the `res` or `res` will be terminated if a response has already
|
||
|
|
started.
|
||
|
|
|
||
|
|
When an error is written, the following information is added to the response:
|
||
|
|
|
||
|
|
* The `res.statusCode` is set from `err.status` (or `err.statusCode`). If
|
||
|
|
this value is outside the 4xx or 5xx range, it will be set to 500.
|
||
|
|
* The `res.statusMessage` is set according to the status code.
|
||
|
|
* The body will be the HTML of the status code message if `env` is
|
||
|
|
`'production'`, otherwise will be `err.stack`.
|
||
|
|
* Any headers specified in an `err.headers` object.
|
||
|
|
|
||
|
|
The final handler will also unpipe anything from `req` when it is invoked.
|
||
|
|
|
||
|
|
#### options.env
|
||
|
|
|
||
|
|
By default, the environment is determined by `NODE_ENV` variable, but it can be
|
||
|
|
overridden by this option.
|
||
|
|
|
||
|
|
#### options.onerror
|
||
|
|
|
||
|
|
Provide a function to be called with the `err` when it exists. Can be used for
|
||
|
|
writing errors to a central location without excessive function generation. Called
|
||
|
|
as `onerror(err, req, res)`.
|
||
|
|
|
||
|
|
## Examples
|
||
|
|
|
||
|
|
### always 404
|
||
|
|
|
||
|
|
```js
|
||
|
|
var finalhandler = require('finalhandler')
|
||
|
|
var http = require('http')
|
||
|
|
|
||
|
|
var server = http.createServer(function (req, res) {
|
||
|
|
var done = finalhandler(req, res)
|
||
|
|
done()
|
||
|
|
})
|
||
|
|
|
||
|
|
server.listen(3000)
|
||
|
|
```
|
||
|
|
|
||
|
|
### perform simple action
|
||
|
|
|
||
|
|
```js
|
||
|
|
var finalhandler = require('finalhandler')
|
||
|
|
var fs = require('fs')
|
||
|
|
var http = require('http')
|
||
|
|
|
||
|
|
var server = http.createServer(function (req, res) {
|
||
|
|
var done = finalhandler(req, res)
|
||
|
|
|
||
|
|
fs.readFile('index.html', function (err, buf) {
|
||
|
|
if (err) return done(err)
|
||
|
|
res.setHeader('Content-Type', 'text/html')
|
||
|
|
res.end(buf)
|
||
|
|
})
|
||
|
|
})
|
||
|
|
|
||
|
|
server.listen(3000)
|
||
|
|
```
|
||
|
|
|
||
|
|
### use with middleware-style functions
|
||
|
|
|
||
|
|
```js
|
||
|
|
var finalhandler = require('finalhandler')
|
||
|
|
var http = require('http')
|
||
|
|
var serveStatic = require('serve-static')
|
||
|
|
|
||
|
|
var serve = serveStatic('public')
|
||
|
|
|
||
|
|
var server = http.createServer(function (req, res) {
|
||
|
|
var done = finalhandler(req, res)
|
||
|
|
serve(req, res, done)
|
||
|
|
})
|
||
|
|
|
||
|
|
server.listen(3000)
|
||
|
|
```
|
||
|
|
|
||
|
|
### keep log of all errors
|
||
|
|
|
||
|
|
```js
|
||
|
|
var finalhandler = require('finalhandler')
|
||
|
|
var fs = require('fs')
|
||
|
|
var http = require('http')
|
||
|
|
|
||
|
|
var server = http.createServer(function (req, res) {
|
||
|
|
var done = finalhandler(req, res, { onerror: logerror })
|
||
|
|
|
||
|
|
fs.readFile('index.html', function (err, buf) {
|
||
|
|
if (err) return done(err)
|
||
|
|
res.setHeader('Content-Type', 'text/html')
|
||
|
|
res.end(buf)
|
||
|
|
})
|
||
|
|
})
|
||
|
|
|
||
|
|
server.listen(3000)
|
||
|
|
|
||
|
|
function logerror (err) {
|
||
|
|
console.error(err.stack || err.toString())
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
[MIT](LICENSE)
|
||
|
|
|
||
|
|
[npm-image]: https://img.shields.io/npm/v/finalhandler.svg
|
||
|
|
[npm-url]: https://npmjs.org/package/finalhandler
|
||
|
|
[node-image]: https://img.shields.io/node/v/finalhandler.svg
|
||
|
|
[node-url]: https://nodejs.org/en/download
|
||
|
|
[coveralls-image]: https://img.shields.io/coveralls/pillarjs/finalhandler.svg
|
||
|
|
[coveralls-url]: https://coveralls.io/r/pillarjs/finalhandler?branch=master
|
||
|
|
[downloads-image]: https://img.shields.io/npm/dm/finalhandler.svg
|
||
|
|
[downloads-url]: https://npmjs.org/package/finalhandler
|
||
|
|
[github-actions-ci-image]: https://img.shields.io/github/workflow/status/pillarjs/finalhandler/ci/master?label=ci
|
||
|
|
[github-actions-ci-url]: https://github.com/jshttp/pillarjs/finalhandler?query=workflow%3Aci
|