Validators are the first stage
of the extension pipeline,
called before filters, mappers and forwarders.
Their purpose is to check
the request,
then signal whether
to continue processing or fail.
A common reason
to define your own validator
is to implement nonce validation,
as a preventative measure
against denial-of-service attacks.
If the validator returns true,
processing continues
and the remaining extensions
are invoked.
If it returns false,
processing is terminated
and the request fails
with HTTP status 400.
The choice of validator
can be specified on the command line
with the -v option.
One validator is available
by default,
permissive,
which always returns true
without performing any checks
on the data.
Defining custom validators is simple. The basic pattern is to export an interface that looks like this:
{
initialise: function (options) {
}
}Where initialise is a function
that takes an options object
and returns the validator function,
bound to any pertinent options.
The signature for
the returned validator function
should look like this:
function (/* bound options, ... */ data, referer, userAgent, remoteAddress) {
}The remaining/unbound arguments passed to the mapper are, in order:
-
data: Request data, parsed into an object. -
referer: URL of the page that sent the beacon request. -
userAgent: User agent string of the client that sent the beacon request. -
remoteAddress: IP address of the client that sent the beacon request.
The validator function
should return true
if the request is okay,
false otherwise.