restify-plugins
A collection of core restify plugins
Getting Started
Install the module with: npm install restify-plugins
Usage
This is the core set of plugins that restify ships with. These include lots of header parsing handlers, data parsing handlers, as well as other useful logging/metrics handlers.
This module includes the follow pre
plugins, which are intended to be used
prior to the routing of a request:
-
sanitizePath()
- cleans up duplicate or trailing / on the URL -
context()
- Provide req.set(key, val) and req.get(key) methods for setting and retrieving context to a specific request. -
userAgent(options)
- used to support edge cases for HEAD requests when using curl-
options.userAgentRegExp
{RegExp} regexp to capture curl user-agents
-
-
strictQueryParams()
- checks req.urls query params with strict key/val format and rejects non-strict requests with status code 400.-
options.message
{String} response body message string
-
This module includes the following header parser plugins:
-
acceptParser(accepts)
- Accept header-
accepts
{Array} an array of acceptable types
-
-
authorizationParser(options)
- Authorization header-
options
{Object} options object passed to http-signature module
-
-
conditionalRequest()
- Conditional headers (If-*) -
fullResponse()
- handles disappeared CORS headers
This module includes the following data parsing plugins:
-
bodyParser(options)
- parses POST bodies toreq.body
. automatically uses one of the following parsers based on content type:-
urlEncodedBodyParser(options)
- parses url encoded form bodies -
jsonBodyParser(options)
- parses JSON POST bodies -
multipartBodyParser(options)
- parses multipart form bodies - All bodyParsers support the following options:
-
options.mapParams
- default false. copies parsed post body values onto req.params -
options.overrideParams
- default false. only applies when if mapParams true. when true, will stomp on req.params value when existing value is found.
-
-
-
jsonp()
- parses JSONP callback -
queryParser()
- Parses URL query paramters intoreq.query
. Many options correspond directly to option defined for the underlyingqs.parse
.-
options.mapParams
- Default false. Copies parsed query parameters intoreq.params
. -
options.overrideParams
- Default false. Only applies when if mapParams true. When true, will stomp on req.params field when existing value is found. -
options.allowDots
- Default false. Transform?foo.bar=baz
to a nested object:{foo: {bar: 'baz'}}
. -
options.arrayLimit
- Default 20. Only transform?a[$index]=b
to an array if$index
is less thanarrayLimit
. -
options.depth
- Default 5. The depth limit for parsing nested objects, e.g.?a[b][c][d][e][f][g][h][i]=j
. -
options.parameterLimit
- Default 1000. Maximum number of query params parsed. Additional params are silently dropped. -
options.parseArrays
- Default true. Whether to parse?a[]=b&a[1]=c
to an array, e.g.{a: ['b', 'c']}
. -
options.plainObjects
- Default false. Whetherreq.query
is a "plain" object -- does not inherit fromObject
. This can be used to allow query params whose names collide with Object methods, e.g.?hasOwnProperty=blah
. -
options.strictNullHandling
- Default false. If true,?a&b=
results in{a: null, b: ''}
. Otherwise,{a: '', b: ''}
.
-
-
requestLogger(options)
- adds timers for each handler in your request chain-
options.properties
{Object} properties to pass to bunyan'slog.child()
method
-
The module includes the following request plugins:
-
reqIdHeaders(options)
- a plugin that lets you use incoming request header values to set the request id (5.x compatible only)-
options.headers
{Array} an array of header names to use. lookup precedence is left to right (lowest index first)
-
The module includes the following response plugins:
-
dateParser(delta)
- expires requests based on current time + delta-
delta
{Number} age in seconds
-
-
gzip(options)
- gzips the response if client accepts it-
options
{Object} options to pass to zlib
-
-
serveStatic()
- used to serve static files -
throttle(options)
- throttles responses-
options.burst
{Number} -
options.rate
{Number} -
options.ip
{Boolean} -
options.username
{Boolean} -
options.xff
{Boolean} -
options.overrides
{Object}
-
-
requestExpiry(options)
- A request expiry will use headers to tell if the incoming request has expired or not. There are two options for this plugin:- Absolute Time
- Time in Milliseconds since the Epoch when this request should be considered expired
- Timeout
- The request start time is supplied
- A timeout, in milliseconds, is given
- The timeout is added to the request start time to arrive at the absolute time in which the request is considered expires
-
options.absoluteHeader
{String} header name of the absolute time for request expiration -
options.startHeader
{String} header name for the start time of the request -
options.timeoutHeader
{String} The header name for the time in milliseconds that should ellapse before the request is considered expired.
- Absolute Time
The module includes the following plugins to be used with restify's after
event, e.g., server.on('after', plugins.auditLogger());
:
-
auditLogger(options)
- an audit logger for recording all handled requests-
options.log
{Object} bunyan logger -
[options.server]
{Object} restify server. if passed in, causes server to emit 'auditlog' event after audit logs are flushed -
[options.logBuffer]
{Object} optional ringbuffer which is written to if passed in -
[options.printLog]
{Boolean} when true, prints audit logs. default true.
-
-
metrics(callback)
- a metrics plugin which will invoke callback with the the following parameters (5.x compatible only):-
err
{Object} an error if the request had an error -
metrics
{Object} - metrics about the request -
metrics.statusCode
{Number} status code of the response. can be undefined in the case of an uncaughtException -
metrics.method
{String} http request verb -
metrics.latency
{Number} request latency -
metrics.path
{String} req.path() value -
metrics.inflightRequests
{Number} Number of inflight requests pending in restify. -
metrics.unifinishedRequests
{Number} Same asinflightRequests
-
metrics.connectionState
{String} can be either 'close', 'aborted', or undefined. If this value is set, err will be a correspondingRequestCloseError
orRequestAbortedError
. If connectionState is either 'close' or 'aborted', then the statusCode is not applicable since the connection was severed before a response was written. -
req
{Object} the request obj -
res
{Object} the response obj -
route
{Object} the route obj that serviced the request
-
Contributing
Add unit tests for any new or changed functionality. Ensure that lint and style checks pass.
To start contributing, install the git pre-push hooks:
make githooks
Before committing, run the prepush hook:
make prepush
If you have style errors, you can auto fix whitespace issues by running:
make codestyle-fix
License
Copyright (c) 2015 Alex Liu
Licensed under the MIT license.