Osprey Method Handler

Middleware for validating requests and responses based on a RAML method object.

Installation

npm install osprey-method-handler --save

Features

• Supports RAML 0.8 and RAML 1.0
• Header validation (ignores undocumented headers)
• Query validation (ignores undocumented parameters)
• Request body validation
  • JSON schemas
  • XML schemas
  • URL-encoded formParameters (ignores undocumented parameters)
  • Multipart form data formParameters (ignores undocumented parameters)
  • Discards unknown bodies
• Accept content type negotiation (based on defined success response bodies)
• Automatically parsed request bodies
  • JSON (req.body)
  • URL-encoded (req.body)
  • XML (req.xml)
  • Form Data (req.form using Busboy, but you need to pipe the request into it - req.pipe(req.form))

Please note: Due to the build time of libxmljs, it does not come bundled. If you need XML validation, please install libxmljs as a dependency of your own project.

Usage

const express = require('express')
const handler = require('osprey-method-handler')
const utils = require('./utils')
 
const app = express()
 
// webapi-parser.Operation
const methodObj = utils.getMethodObj()
const options = {}
 
app.post(
  '/users',
  handler(methodObj, '/users', 'POST', options),
  function (req, res) {
    res.send('success')
  }
)

Accepts webapi-parser Operation object as first argument, path string as second argument, method name as third and options object as final argument.

Options

• ajv Custom Ajv instance to be used to validate query strings, request headers and request bodied (url-encoded, form-data, json)
• discardUnknownBodies Discard undefined request streams (default: true)
• discardUnknownQueryParameters Discard undefined query parameters (default: true)
• discardUnknownHeaders Discard undefined header parameters (always includes known headers) (default: true)
• parseBodiesOnWildcard Toggle parsing bodies on wildcard body support (default: false)
• reviver The reviver passed to JSON.parse for JSON endpoints
• limit The maximum bytes for XML, JSON and URL-encoded endpoints (default: '100kb')
• parameterLimit The maximum number of URL-encoded parameters (default: 1000)
• busboyLimits The multipart limits defined by Busboy

Adding JSON schemas

If you are using external JSON schemas with $ref, you can add them to the module before you compile the middleware. Use handler.addJsonSchema(schema, key) to compile automatically when used.

handler.addJsonSchema() accepts a third (optional) options argument. Supported options are:

• ajv Custom Ajv instance. E.g. handler.addJsonSchema(schema, key, {ajv: myAjvInstance}). The provided ajv instance can later be passed as an option to the handler to perform validation.

Validation Errors

The library intercepts incoming requests and does validation. It will respond with 400, 406 or 415 error instances from http-errors. Validation errors are attached to 400 instances and noted using ramlValidation = true and requestErrors = [] (an array of errors that were found, compatible with request-error-handler).

See the code for a complete list of errors formats.

Please note: XML validation does not have a way to get the keyword, dataPath, data or schema. Instead, it has a meta object that contains information from libxmljs (domain, code, level, column, line).

To render the error messages for your application, look into error handling for Express, Connect, Router or any other middleware error handler. If you want a pre-built error handler, try using request-error-handler, which provides a pre-defined error formatter.

License

MIT license