Skip to content

lan-nguyen91/fleek-validator

BranchesTags
 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

37 Commits
lib
lib
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
errors.json
errors.json
 
 
package.json
package.json
 
 

Repository files navigation

Fleek Validator

Middleware router that validates request against swagger doc specifications.

Quick reference:

  • Best used in tandem with the fleek-router
  • Validations are based on the swagger parameter specifications, but many additional validations have been added that are not supported by swagger directly
  • A request may pass erroneously pass validation if the route is not recognized or the configuration is not correct. if no validation is run this.validated will be false
  • The validate object/helper will be added to the request context and can be accessed during request handling. eg: this.validate.one(foo, {/* parameter decription*/})
  • if koa-router is not used, paths will be mapped to swager docs using the koa-router module. If another routing module is used in the stack, unexpected results may appear (you have been warned!)
  • A full list of errors an codes can be found in error.json

Key

Usage

Basic

  • Swagger docs will be retrieved from ./api.json, /swagger.json, /config/api.json, or /config/swagger.json in that order
  • TODO Full example
var koa            = require('koa');
var router         = require('koa-router')();
var fleekValidator = require('fleek-validator');
var app = koa();

fleekValidator(app);

router.get('/', function *() {
  console.log('I passed validation!')
});

app.listen(3000);

Fully Custom (paths)

  • Swagger docs are pulled from ./custom/docs.json
  • error is run on validation failure
  • success is run on validation pass (before next middlware)
  • TODO Full example
var koa            = require('koa');
var router         = require('koa-router')();
var fleekValidator = require('fleek-validator');
var app = koa();

fleekValidator(app, {
  swagger : './custom/docs.json',
  strict  : true, // fail any route not in the swagger docs
  success : function *(next) {
    console.log('Passed validation!')
  },
  error  : function *(err, next) {
    console.log('Failed Validation :(');
    this.body = err;
  }
});

router.get('/', function *() {
  console.log('hello from root')
});

app.listen(3000);

Fully custom (objects)

  • Swagger docs are parsed from the object provided
  • error is run on validation failure
  • success is run on validation pass (before next middlware)
  • TODO Full example
var koa            = require('koa');
var router         = require('koa-router')();
var fleekValidator = require('fleek-validator');
var app = koa();

fleekValidator(app, {
  swagger      : require('./some/swagger/generator')(),
  strict  : true, // fail any route not in the swagger docs
  success : function *(next) {
    console.log('Passed validation!')
  },
  error  : function *(err, next) {
    console.log('Failed Validation :(');
    this.body = err;
  }
});

router.get('/', function *() {
  console.log('hello from root')
});

app.listen(3000);

Koa on fleek

  • Controllers are pulled from the ./controllers directory
  • Swagger docs will be retrieved from ./api.json, /swagger.json, /config/api.json, or /config/swagger.json in that order
  • routes wil be generated by fleek-router
  • TODO Full example
var koa         = require('koa');
var fleekRouter = require('fleek-router');
var app = koa();

fleekRouter(app, {
  authenicate : true,
  validate    : {
    error : function *(err, next) {
      console.log('oh no! Returning default errors');
    }
  }
});

app.listen(3000);

Response Structure

  • The following structure will be followed in errors passed to the error handler specified
  • If no error handler is specified, the error will be sent to the client with the status 400
  • A full list of errors an codes can be found in error.json
{
  "error": "Validation Failed",
  "error_name": "VALIDATION_FAILED",
  "details": [{
    "name": "VALUE.FOO",
    "code": 204,
    "message": "Must be a valid foo string",
    "parameter": {
      "name": "some_val",
      "in": "body",
      "description": "fooget about it",
      "required": true,
      "type": "string",
      "foo": true
    }
  }]
}

Static Utilities

validator.validate

  • A collection of static utilities
var val    = require('fleek-validator').validate;
var errors = val.one(foo, {/* swagger parameter object foo must match */})

// OR - if using fleek-validor as middleware
function *(next) {
  var errors = this.validate.one(foo, {/* swagger parameter object foo must match */});
}

validate.one

  • validate a single object against a swagger parameter object
var error = validator.validate.one(fooEmail, {
  type  : 'string',
  email : true
})

validate.object

  • validate an object of values against an array of swagger parameter objects
  • also accepts accepts definition property objects
    • eg:
      definitions : {
        UserModel : {
          parameters : {
            name : {
              type    : "string",
              required: true
            }
          }
        }
      }

parameters

  • subject [String] - . delimited error property chain to identify which error.json error to generate
  • parameters [Object] - swagger parameter description which failed
  • options [object] (optional)
    • trim [Boolean] - if true, trim properties from the result that aren't in the the parameters array
    • defaults [Boolean] - if true, apply any defaultValue's from the parameters array
    • partial [Boolean] - if true, allow required parameters to pass through undefined (useful for partial updates)

returns

  • [Array] - array of validation errors
  • [Object] - the object which passed validation, after options are applied
var parameters = [
  {
    name  : 'user_email',
    type  : 'string',
    email : true
  }, {
    name    : 'user_password',
    type    : 'string',
    pattern : passwordRegexp
  }, {
    name         : 'confirmed',
    defaultValue : false
  }
];

var subject = {
  user_email    : fooEmail,
  user_password : fooPwd,
  injection     : someMaliciousInjection
};

var result = validator.validate.object(subject, parameters, {
  trim     : true,
  defaults : true,
});
// result -> {
//   user_email    : fooEmail,
//   user_password : fooPwd,
//   confirmed     : false
// }

validate.ctx

  • validate a request context against a set of swagger params
var errors = validator.validate.ctx(ctx, [
  {
    name  : 'user_email',
    type  : 'string',
    email : true
  }, {
    name    : 'user_password',
    type    : 'string',
    pattern : passwordRegexp
  }
])

validate.error

  • An error class for validation errors [ValidationError]

parameters

  • errorName [String] - . delimited error property chain to identify which error.json error to generate
  • parameter [Object] - swagger parameter description which failed
  • expected [String] (optional) - expected value for the parameter (replaces instances of ${expected} in the message)
var someError = new validator.validate.error('TYPE.STRING', someParameter, 'alphanumeric');

validate.isError

  • detects whether or not the object is a validation error

parameters

  • result [Mixed] - result object to test for validation failure

alias

  • isErr
  • isValidationError
  • isValidationErr
  • isValError
  • isValErr
var failedValidationResult = validator.validate.isError(resultOfValidation);

Configuration

config.swagger

[optional]

summary

  • sets the swagger documentation source for compiling routes.

accepts

  • Object - javascript object mapping to the swagger doc format exactly
  • String - path to the swagger json file (relative or absolute)
  • Undefined - attempts to find the config in the following places ./api.json, ./swagger.json, ./config/api.json, and ./config/swagger.json
config.swagger = undefined; // attempts to resolve internally
// OR
config.swagger = './some/relative/swag.json';
// OR
config.swagger = '/some/absolute/swagger.json';
// OR
config.swagger = require('./a/function/returning/swag')();

config.success

[optional]

summary

  • Success handler to run if validation succeeds (before the next middleware)
  • The next middlewre funciton is provided

accepts

  • Function - executed on validation success
config.succcess = function *(next) {
  console.log('woo! validation passed!');
  yield next();
}

config.catch

[optional]

summary

  • Error handler to run if validation fails
  • The validation error and the next middleware function are provided
  • If not provided, the default validation error structure is returned to the client

accepts

  • Function - executed on validation failure
config.catch = function *(err, next) {
  console.log('oh no! Returning default errors');
}

config.strict

[optional]

summary

  • Determines whether or not to reject undocumented routes

accepts

  • Boolean - if true, undocumented routes will fail validation
config.strict = true;

Validation

Validates params based on configuration. Can be used in either the parameters structure in a path or the properties structure of a definition

Path Parameters

Paramer validation will occur during middleware execution

{
  "paths" : {
    "/foo" : {
      "post" : {
        "parameters" : [{
          "name"         : "someFormParam",
          "in"           : "body",
          "description"  : "An arbitrary date",
          "type"         : "date",
          "defaultValue" : "01/01/1990"
        }, {
          "name"         : "someQueryParam",
          "in"           : "query",
          "description"  : "An arbitrary required string",
          "required"     : true,
          "type"         : "string",
          "alphaNumeric" : true
        }]
      }
    }
  }
}

Definition Parameters

Definition validation must be called explicitly with a static function

{
  "definitions" : {
    "someDefinition" : {
      "properties": {
        "someFormParam" : {
          "description"  : "An arbitrary date",
          "type"         : "date",
          "defaultValue" : "01/01/1990"
        },
        "someQueryParam" : {
          "description"  : "An arbitrary required string",
          "type"         : "string",
          "required"     : true,
          "alphaNumeric" : true
        }
      }
    }
  }
}

Types

string

Accept any String value

"parameters": [{
  "name" : "foo",
  "type" : "string",
  "in"   : "body"
}]

integer

Accept any integer value

"parameters": [{
  "name" : "foo",
  "type" : "integer",
  "in"   : "body"
}]

long

Accept any long value

"parameters": [{
  "name" : "foo",
  "type" : "long",
  "in"   : "body"
}]

float

Accept any float value

"parameters": [{
  "name" : "foo",
  "type" : "float",
  "in"   : "body"
}]

double

Accept any double value

"parameters": [{
  "name" : "foo",
  "type" : "double",
  "in"   : "body"
}]

byte

Accept any byte value

"parameters": [{
  "name" : "foo",
  "type" : "byte",
  "in"   : "body"
}]

dateTime

Accept any dateTime value

"parameters": [{
  "name" : "foo",
  "type" : "dateTime",
  "in"   : "body"
}]

date

Accept any date value of form MM/DD/YY. see format for custom format. using "strict": true

"parameters": [{
  "name" : "foo",
  "type" : "date",
  "in"   : "body"
}]

boolean

Accept any boolean value

"parameters": [{
  "name" : "foo",
  "type" : "boolean",
  "in"   : "body"
}]

Restrictions

multipleOf

  • Required Type: Number
  • Description: Reject any number not a multiple of the config value
  • Expects: Number to compare
"parameters": [{
  "name"       : "foo",
  "in"         : "body",
  "type"       : "integer",
  "multipleOf" : 10
}]

maximum

  • Required Type: Number
  • Description: Reject any number greater than the config value
  • Expects: Number maximum
"parameters": [{
  "name"    : "foo",
  "type"    : "integer",
  "in"      : "body",
  "maximum" : 10
}]

exclusiveMaximum

  • Required Type: Number
  • Description: Reject any number greater than or equal to the config value
  • Expects: Number maximum
"parameters": [{
  "name"             : "foo",
  "type"             : "integer",
  "in"               : "body",
  "exclusiveMaximum" : 10
}]

minimum

  • Required Type: Number
  • Description: Reject any number less than the config value
  • Expects: Number minimum
"parameters": [{
  "name"    : "foo",
  "type"    : "integer",
  "in"      : "body",
  "minimum" : 10
}]

exclusiveMinimum

  • Required Type: Number
  • Description: Reject any number less than or equal to the config value
  • Expects: Number maximum
"parameters": [{
  "name"             : "foo",
  "type"             : "integer",
  "in"               : "body",
  "exclusiveMinimum" : 10
}]

maxLength

maxItems

  • Required Type: Array
  • Description: Reject any array containing more than the number the config value
  • Expects: Maximum number of properties allowed
"parameters": [{
  "name"      : "foo",
  "type"      : "array",
  "in"        : "body",
  "maxLength" : 10,
  "maxItems"  : 10
}]

minLength

minItems

  • Required Type: Array
  • Description: Reject any array containing fewer than the number the config value
  • Expects: Minimum number of properties allowed
"parameters": [{
  "name"      : "foo",
  "type"      : "array",
  "in"        : "body",
  "minLength" : 10,
  "minItems"  : 10
}]

pattern

  • Required Type: String
  • Description: Reject any pattern not matching the config value
  • Expects: RegExp string
"parameters": [{
  "name"    : "foo",
  "type"    : "string",
  "in"      : "body",
  "pattern" : "\\s*foo\\s*"
}]

maxProperties

  • Required Type: Object
  • Description: Reject any object with fewer than number specified
  • Expects: Number maximum
"parameters": [{
  "name"          : "foo",
  "type"          : "object",
  "in"            : "body",
  "maxProperties" : 10
}]

minProperties

  • Required Type: Object
  • Description: Reject any object with greater than number specified
  • Expects: Number minimum
"parameters": [{
  "name"          : "foo",
  "type"          : "object",
  "in"            : "body",
  "minProperties" : 10
}]

enum

  • Required Type: Mixed
  • Description: Reject any value not in the config array
  • Expects: array
"parameters": [{
  "name" : "foo",
  "type" : "string",
  "in"   : "body",
  "enum" : ["accepted", "values"]
}]

email

  • Required Type: String
  • Description: Reject any invalid email address
  • Expects: Boolean
"parameters": [{
  "name"  : "foo",
  "type"  : "string",
  "in"    : "body",
  "email" : true
}]

alphaNumeric

  • Required Type: String
  • Description: Reject any non alpha-numeric value
  • Expects: Boolean
"parameters": [{
  "name"         : "foo",
  "type"         : "string",
  "in"           : "body",
  "alphaNumeric" : true
}]

lowercase

  • Required Type: String
  • Description: Reject any value with uppercase values
  • Expects: Boolean
"parameters": [{
  "name"      : "foo",
  "type"      : "string",
  "in"        : "body",
  "lowercase" : true
}]

uppercase

  • Required Type: String
  • Description: Reject any value with lowercase values
  • Expects: Boolean
"parameters": [{
  "name"      : "foo",
  "type"      : "string",
  "in"        : "body",
  "uppercase" : true
}]

format

  • Required Type: Date
  • Description: Reject any string not fitting the date format
  • Expects: String following Moment formatting
"parameters": [{
  "name"   : "foo",
  "type"   : "date",
  "in"     : "body",
  "format" : "MM-DD-YYYY"
}]

past

  • Required Type: Date
  • Description: Reject any date that is not in the past
  • Expects: Boolean
"parameters": [{
  "name" : "foo",
  "type" : "date",
  "in"   : "body",
  "past" : true
}]

future

  • Required Type: Date
  • Description: Reject any date not in the future
  • Expects: boolean
"parameters": [{
  "name"   : "foo",
  "type"   : "date",
  "in"     : "body",
  "future" : true
}]

Hygiene

trim

  • Required Type: String
  • Description: Trims leading and trailing whitespace
  • Expects: Boolean
"parameters": [{
  "name" : "foo",
  "type" : "date",
  "in"   : "body",
  "trim" : true
}]

toUpperCase

  • Required Type: String
  • Description: perform a toUpperCase operation on the parameter
  • Expects: Boolean
"parameters": [{
  "name"        : "foo",
  "type"        : "date",
  "in"          : "body",
  "toUpperCase" : true
}]

toLowerCase

  • Required Type: String
  • Description: perform a toLowerCase operation on the parameter
  • Expects: Boolean
"parameters": [{
  "name"        : "foo",
  "type"        : "date",
  "in"          : "body",
  "toLowerCase" : true
}]

Miscellaneous

defaultValue

  • Required Type: Mixed
  • Description: Sets the parameter if none is provided
  • Expects: Mixed
"parameters": [{
  "name"         : "foo",
  "type"         : "date",
  "in"           : "body",
  "defaultValue" : "Hello World."
}]

required

  • Required Type: Mixed
  • Description: Rejects any request not containing a value for the parameter. Performed before validation, but after defaults
  • Expects: boolean
"parameters": [{
  "name"     : "foo",
  "type"     : "date",
  "in"       : "body",
  "required" : true
}]

Authors

About

Validation for the fleek framework

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

2 watching

Forks

0 forks
Report repository

Releases 1

change context to .fleek.validate Latest
Sep 29, 2015

Packages

No packages published

Languages

  • JavaScript 100.0%