strictQueryParams

Prevents req.urls non-strict key-value query params

The Request-URI is transmitted in the format specified in section 3.2.1.
If the Request-URI is encoded using the “% HEX HEX” encoding [42],
the origin server MUST decode the Request-URI
in order to properly interpret the request.
Servers SHOULD respond to invalid Request-URIs
with an appropriate status code.

userAgentConnection

This basically exists for curl. curl on HEAD requests usually
just sits there and hangs, unless you explicitly set
Connection:close. And in general, you probably want to set
Connection: close to curl anyway.

Also, because curl spits out an annoying message to stderr about
remaining bytes if content-length is set, this plugin also drops
the content-length header (some user agents handle it and want it,
curl does not).

To be slightly more generic, the options block takes a user
agent regexp, however.

server.use() plugins

acceptParser

Parses the Accept header, and ensures that the server can respond to what
the client asked for. In almost all cases passing in server.acceptable is
all that’s required, as that’s an array of content types the server knows
how to respond to (with the formatters you’ve registered). If the request is
for a non-handled type, this plugin will return a NotAcceptableError (406).

Note you can get the set of types allowed from a restify server by doing
server.acceptable.

authorizationParser

Parses out the Authorization header as best restify can.
Currently only HTTP Basic Auth and
HTTP Signature
schemes are supported.

Parameters

optionsObject? an optional options object that is
passed to http-signature

Examples

Subsequent handlers will see req.authorization, which looks like above.req.username will also be set, and defaults to ‘anonymous’. If the scheme
is unrecognized, the only thing available in req.authorization will be
scheme and credentials - it will be up to you to parse out the rest.

dateParser

Parses out the HTTP Date header (if present) and checks for clock skew.
If the header is invalid, a InvalidHeaderError (400) is returned.
If the clock skew exceeds the specified value,
a RequestExpiredError (400) is returned.
Where expired means the request originated at a time
before ($now - $clockSkew).
The default clockSkew allowance is 5m (thanks
Kerberos!)

queryParser

Parses the HTTP query string (i.e., /foo?id=bar&name=mark).
If you use this, the parsed content will always be available in req.query,
additionally params are merged into req.params.
You can disable by passing in mapParams: false in the options object.

Many options correspond directly to option defined for the underlying
qs.parse.

options.plainObjectsBoolean Whether req.query is a
“plain” object – does not inherit from Object.
This can be used to allow query params whose names collide with Object
methods, e.g. ?hasOwnProperty=blah. (optional, default false)

jsonp

Parses the jsonp callback out of the request.
Supports checking the query string for callback or jsonp and ensuring
that the content-type is appropriately set if JSONP params are in place.
There is also a default application/javascript formatter to handle this.

You should set the queryParser plugin to run before this, but if you
don’t this plugin will still parse the query string properly.

bodyParser

Blocks your chain on reading and parsing the HTTP request body. Switches on
Content-Type and does the appropriate logic. application/json,
application/x-www-form-urlencoded and multipart/form-data are currently
supported.

Parses POST bodies to req.body. automatically uses one of the following
parsers based on content type:

options.maxBodySizeNumber? The maximum size in bytes allowed in
the HTTP body. Useful for limiting clients from hogging server memory.

options.mapParamsBoolean? if req.params should be filled with
parsed parameters from HTTP body.

options.mapFilesBoolean? if req.params should be filled with
the contents of files sent through a multipart request.
formidable is used internally
for parsing, and a file is denoted as a multipart part with the filename
option set in its Content-Disposition. This will only be performed if
mapParams is true.

options.overrideParamsBoolean? if an entry in req.params
should be overwritten by the value in the body if the names are the same.
For instance, if you have the route /:someval,
and someone posts an x-www-form-urlencoded
Content-Type with the body someval=happy to /sad, the value will be
happy if overrideParams is true, sad otherwise.

options.multipartHandlerFunction? a callback to handle any
multipart part which is not a file.
If this is omitted, the default handler is invoked which may
or may not map the parts into req.params, depending on
the mapParams-option.

options.multipartFileHandlerFunction? a callback to handle any
multipart file.
It will be a file if the part has a Content-Disposition with the
filename parameter set. This typically happens when a browser sends a
form and there is a parameter similar to <input type="file" />.
If this is not provided, the default behaviour is to map the contents
into req.params.

options.keepExtensionsBoolean? if you want the uploaded
files to include the extensions of the original files
(multipart uploads only).
Does nothing if multipartFileHandler is defined.

options.uploadDirString? Where uploaded files are
intermediately stored during transfer before the contents is mapped
into req.params.
Does nothing if multipartFileHandler is defined.

options.multiplesBoolean? if you want to support html5 multiple
attribute in upload fields.

options.hashString? If you want checksums calculated for
incoming files, set this to either sha1 or md5.

options.rejectUnknownBoolean? Set to true if you want to end
the request with a UnsupportedMediaTypeError when none of
the supported content types was given.

options.requestBodyOnGetBoolean Parse body of a GET
request. (optional, default false)

options.reviverFunction?jsonParser only. If a function,
this prescribes how the value originally produced by parsing is transformed,
before being returned. For more information check out
JSON.parse(text[, reviver]).

server.use(restify.plugins.bodyParser({maxBodySize:0,mapParams:true,mapFiles:false,overrideParams:false,multipartHandler:function(part){part.on('data',function(data){// do something with the multipart data});},multipartFileHandler:function(part){part.on('data',function(data){// do something with the multipart file data});},keepExtensions:false,uploadDir:os.tmpdir(),multiples:true,hash:'sha1',rejectUnknown:true,requestBodyOnGet:false,reviver:undefined,maxFieldsSize:2*1024*1024}));

requestLogger

Sets up a child bunyan logger with
the current request id filled in, along with any other parameters you define.

You can pass in no options to this, in which case only the request id will be
appended, and no serializers appended (this is also the most performant); the
logger created at server creation time will be used as the parent logger.
This logger can be used normally, with req.log.

This plugin does not log each individual request. Use the Audit Logging
plugin or a custom middleware for that use.

gzipResponse

If the client sends an accept-encoding: gzip header (or one with an
appropriate q-val), then the server will automatically gzip all
response data.
Note that only gzip is supported, as this is most widely supported by
clients in the wild.
This plugin will overwrite some of the internal streams, so any
calls to res.send, res.write, etc., will be compressed. A side effect is
that the content-length header cannot be known, and so
transfer-encoding: chunked will always be set when this is in effect.
This plugin has no impact if the client does not send
accept-encoding: gzip.

The above route and directory combination will serve a file located in
./documentation/v1/docs/current/index.html when you attempt to hit
http://localhost:8080/docs/current/. If you want the serveStatic module to
serve files directly from the /documentation/v1 directory
(and not append the request path /docs/current/),
you can set the appendRequestPath option to false, and the served file
would be ./documentation/v1/index.html, in the previous example.The plugin will enforce that all files under directory are served.
The directory served is relative to the process working directory.
You can also provide a default parameter such as index.html for any
directory that lacks a direct file match.
You can specify additional restrictions by passing in a match parameter,
which is just a RegExp to check against the requested file name.
Additionally, you may set the charSet parameter, which will append a
character set to the content-type detected by the plugin.
For example, charSet: 'utf-8' will result in HTML being served with a
Content-Type of text/html; charset=utf-8.
Lastly, you can pass in a maxAge numeric, which will set the
Cache-Control header. Default is 3600 (1 hour).An additional option for serving a static file is to pass file in to the
serveStatic method as an option. The following will serve index.html from
the documentation/v1/ directory anytime a client requests /home/.

throttle

Creates an API rate limiter that can be plugged into the standard
restify request handling pipeline.

restify ships with a fairly comprehensive implementation of
Token bucket, with the ability
to throttle on IP (or x-forwarded-for) and username (from req.username).
You define “global” request rate and burst rate, and you can define
overrides for specific keys.
Note that you can always place this on per-URL routes to enable
different request rates to different resources (if for example, one route,
like /my/slow/database is much easier to overwhlem
than /my/fast/memcache).

If a client has consumed all of their available rate/burst, an HTTP response
code of 429Too Many Requests
is returned.

This throttle gives you three options on which to throttle:
username, IP address and ‘X-Forwarded-For’. IP/XFF is a /32 match,
so keep that in mind if using it. Username takes the user specified
on req.username (which gets automagically set for supported Authorization
types; otherwise set it yourself with a filter that runs before this).

In both cases, you can set a burst and a rate (in requests/seconds),
as an integer/float. Those really translate to the TokenBucket
algorithm, so read up on that (or see the comments above…).

In either case, the top level options burst/rate set a blanket throttling
rate, and then you can pass in an overrides object with rates for
specific users/IPs. You should use overrides sparingly, as we make a new
TokenBucket to track each.

options.tokensTableObject a storage engine this plugin will
use to store throttling keys -> bucket mappings.
If you don’t specify this, the default is to
use an in-memory O(1) LRU, with 10k distinct
keys. Any implementation just needs to support
put/get.

options.maxKeysNumber If using the default
implementation, you can specify how large you
want the table to be. (optional, default 10000)

requestExpiry

Request Expiry can be used to throttle requests that have already exceeded
their client timeouts. Requests can be sent with a configurable client
timeout header, e.g. ‘x-request-expiry-time’, which gives in absolute ms
since epoch, when this request will be timed out by the client.

This plugin will throttle all incoming requests via a 504 where
‘x-request-expiry-time’ less than Date.now() – since these incoming requests
have already been timed out by the client. This prevents the server from
processing unnecessary requests.

Request expiry will use headers to tell if the incoming request has expired.
There are two options for this plugin:
1. Absolute Time
_ Time in Milliseconds since Epoch when this request should be
considered expired
2. 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 expired

Using an external storage mechanism for key/bucket mappings.

By default, the restify throttling plugin uses an in-memory LRU to store
mappings between throttling keys (i.e., IP address) to the actual bucket that
key is consuming. If this suits you, you can tune the maximum number of keys
to store in memory with options.maxKeys; the default is 10000.

In some circumstances, you want to offload this into a shared system, such as
Redis, if you have a fleet of API servers and you’re not getting steady
and/or uniform request distribution. To enable this, you can pass in
options.tokensTable, which is simply any Object that supports put and
get with a String key, and an Object value.

inflightRequestThrottle

The inflightRequestThrottle module allows you to specify an upper limit to
the maximum number of inflight requests your server is able to handle. This
is a simple heuristic for protecting against event loop contention between
requests causing unacceptable latencies.

The custom error is optional, and allows you to specify your own response
and status code when rejecting incoming requests due to too many inflight
requests. It defaults to 503 ServiceUnavailableError.

This plugin should be registered as early as possibly in the middleware stack
using pre to avoid performing unnecessary work.

cpuUsageThrottle

cpuUsageThrottle is a middleware that rejects a variable number of requests
(between 0% and 100%) based on a historical view of CPU utilization of a
Node.js process. Essentially, this plugin allows you to define what
constitutes a saturated Node.js process via CPU utilization and it will
handle dropping a % of requests based on that definiton. This is useful when
you would like to keep CPU bound tasks from piling up causing an increased
per-request latency.

The algorithm asks you for a maximum CPU utilization rate, which it uses to
determine at what point it should be rejecting 100% of traffic. For a normal
Node.js service, this is 1 since Node is single threaded. It uses this,
paired with a limit that you provide to determine the total % of traffic it
should be rejecting. For example, if you specify a limit of .5 and a max of
1, and the current EWMA (next paragraph) value reads .75, this plugin will
reject approximately 50% of all requests.

When looking at the process’ CPU usage, this algorithm will take a load
average over a user specified interval. example, if given an interval of
250ms, this plugin will attempt to record the average CPU utilization over
250ms intervals. Due to contention for resources, the duration of each
average may be wider or narrower than 250ms. To compensate for this, we use
an exponentially weighted moving average. The EWMA algorithm is provided by
the ewma module. The parameter for configuring the EWMA is halfLife. This
value controls how quickly each load average measurment decays to half it’s
value when being represented in the current average. For example, if you
have an interval of 250, and a halfLife of 250, you will take the previous
ewma value multiplied by 0.5 and add it to the new CPU utilization average
measurement multiplied by 0.5. The previous value and the new measurement
would each represent 50% of the new value. A good way of thinking about the
halfLife is in terms of how responsive this plugin will be to spikes in CPU
utilization. The higher the halfLife, the longer CPU utilization will have
to remain above your defined limit before this plugin begins rejecting
requests and, converserly, the longer it will have to drop below your limit
before the plugin begins accepting requests again. This is a knob you will
want to with play when trying to determine the ideal value for your use
case.

For a better understanding of the EWMA algorithn, refer to the documentation
for the ewma module.

opts.limitNumber? The point at which restify will begin
rejecting a % of all requests at the front door.
This value is a percentage.
For example 0.8 === 80% average CPU utilization. Defaults to 0.75.

opts.maxNumber? The point at which restify will reject 100% of
all requests at the front door. This is used in conjunction with limit to
determine what % of traffic restify needs to reject when attempting to
bring the average load back to the user requested values. Since Node.js is
single threaded, the default for this is 1. In some rare cases, a Node.js
process can exceed 100% CPU usage and you will want to update this value.

opts.intervalNumber? How frequently we calculate the average CPU
utilization. When we calculate an average CPU utilization, we calculate it
over this interval, and this drives whether or not we should be shedding
load. This can be thought of as a “resolution” where the lower this value,
the higher the resolution our load average will be and the more frequently
we will recalculate the % of traffic we should be shedding. This check
is rather lightweight, while the default is 250ms, you should be able to
decrease this value without seeing a significant impact to performance.

opts.halfLifeNumber? When we sample the CPU usage on an
interval, we create a series of data points.
We take these points and calculate a
moving average. The halfLife indicates how quickly a point “decays” to
half it’s value in the moving average. The lower the halfLife, the more
impact newer data points have on the average. If you want to be extremely
responsive to spikes in CPU usage, set this to a lower value. If you want
your process to put more emphasis on recent historical CPU usage when
determininng whether it should shed load, set this to a higher value. The
unit is in ms. Defaults to 250.

conditionalRequest

Returns a set of plugins that will compare an already set ETag header with
the client’s If-Match and If-None-Match header, and an already set
Last-Modified header with the client’s If-Modified-Since and
If-Unmodified-Since header.

You can use this handler to let clients do nice HTTP semantics with the
“match” headers. Specifically, with this plugin in place, you would set
res.etag=$yourhashhere, and then this plugin will do one of:

auditLogger

opts.eventString The event from the server which initiates the
log, one of ‘pre’, ‘routed’, or ‘after’

opts.contextFunction? The optional context function of signature
f(req, res, route, err). Invoked each time an audit log is generated. This
function can return an object that customizes the format of anything off the
req, res, route, and err objects. The output of this function will be
available on the context key in the audit object.

opts.serverObject? The restify server, used to emit
the audit log object programmatically

You pass in the auditor a bunyan logger, optionally server object,
Ringbuffer and a flag printLog indicate if log needs to be print out at info
level or not. By default, without specify printLog flag, it will write out
record lookling like this:

The timers field shows the time each handler took to run in microseconds.
Restify by default will record this information for every handler for each
route. However, if you decide to include nested handlers, you can track the
timing yourself by utilizing the Request
startHandlerTimer and
endHandlerTimer API.
You can also listen to auditlog event and get same above log object when
log event emits. For example

metrics.connectionStateString can be either 'close',
'aborted', or undefined. If this value is set, err will be a
corresponding RequestCloseError or RequestAbortedError.
If connectionState is either
'close' or 'aborted', then the statusCode is not applicable since the
connection was severed before a response was written.