plugins/validate: update API, test & doc

doc/plugins.markdown

@@ -130,6 +130,31 @@ Uses the `buffer` & `json` plugin.
   - `{Object|string} headers` An existing schema id or a schema definition
   - `{Object|string} body` An existing schema id or a schema definition
 
+Validation results are exported as `response.validate = null` when all validations passed, and an object when a validation failed;
+
+```js
+response.validate = {
+  headers: null,
+  body: [
+    ['hello', 'number', 'type', 'world']
+  ]
+};
+```
+
+**Headers Schema Definition Example**
+
+This example shows how-to validate that the `Content-Type` header equals `'application/json'`.
+
+```js
+{
+  type: 'object',
+  properties: {
+    'content-type': 'application/json'
+  },
+  allowUnknownProperties: true
+}
+```
+
 ### validate.registry
 The [mgl-validate](https://www.npmjs.com/package/mgl-validate) schema registry.
 

lib/plugins/validate.js

@@ -48,19 +48,28 @@ ValidatePlugin.prototype._setup = function() {
 
   rail.on('plugin-response', function(call, options, response) {
     var err;
-    response.validate = true;
+
+    response.validate = {
+      headers: null,
+      body: null
+    };
 
     if (options.validate.headers) {
       err = self._validate(options.validate.headers, response.headers);
 
       if (err) {
-        response.validate = false;
-        call.emit('warn', 'validate', 'error', err.message, err.validation);
+        if (err.validation) {
+          response.validate.headers = err.validation;
+        } else {
+          call.emit('error', err);
+        }
       }
     }
 
     if (options.validate.body) {
       call.__intercept('response', self._intercept);
+    } else if (response.validate.headers === null) {
+      response.validate = null;
     }
   });
 
@@ -77,12 +86,18 @@ ValidatePlugin.prototype._interceptResponse = function(call, options, response)
     err = this._validate(options.validate.body, response.json);
 
     if (err) {
-      response.validate = false;
-      call.emit('warn', 'validate', 'error', err.message, err.validation);
+      if (err.validation) {
+        response.validate.body = err.validation;
+      } else {
+        call.emit('error', err);
+      }
+    }
+
+    if (response.validate.headers === null && response.validate.body === null) {
+      response.validate = null;
     }
   } else {
-    response.validate = false;
-    call.emit('warn', 'validate', 'erro', 'no json data available');
+    response.validate.body = [[null, 'object', 'undefined', null]];
   }
 
   call.__emit('response', response);
@@ -105,6 +120,7 @@ ValidatePlugin.prototype._validate = function(schema, data) {
 
     err = this.registry.test(id, data);
     this.registry.removeSchema(id);
+    return err;
 
   } else {
     return new Error('Invalid schema');

test/test-http-validate.js

@@ -46,15 +46,14 @@ suite('http:validate', function() {
   });
 
 
-  test('call', function(done) {
+  test('OK', function(done) {
     onrequest = function(request, response) {
       response.end(JSON.stringify({
         hello: 'world'
       }));
     };
 
     rail.call({
-      json: true,
       validate: {
         headers: 'headers',
         body: {
@@ -73,11 +72,174 @@ suite('http:validate', function() {
       assert(response.json.hello);
       assert.strictEqual(response.json.hello, 'world');
 
-      assert.strictEqual(response.validate, true);
+      assert.strictEqual(response.validate, null);
 
       done();
-    }).on('warn', function(plugin, status, opt_message, opt_whatever) {
-      console.log(plugin, status, opt_message, opt_whatever);
+    }).end();
+  });
+
+
+  test('failed (body)', function(done) {
+    onrequest = function(request, response) {
+      response.end(JSON.stringify({
+        hello: 'world'
+      }));
+    };
+
+    rail.call({
+      validate: {
+        headers: 'headers',
+        body: {
+          id: 'simple-body',
+          type: 'object',
+          properties: {
+            hello: {
+              type: 'number'
+            }
+          }
+        }
+      }
+    }, function(response) {
+      assert.strictEqual(response.statusCode, 200);
+
+      assert(response.buffer);
+      assert(response.json);
+      assert(response.json.hello);
+      assert.strictEqual(response.json.hello, 'world');
+
+      assert(response.validate);
+      assert.strictEqual(response.validate.headers, null);
+      assert.deepEqual(response.validate.body,
+          [['hello', 'number', 'type', 'world']]);
+
+      done();
+    }).end();
+  });
+
+
+  test('failed (headers)', function(done) {
+    onrequest = function(request, response) {
+      response.end(JSON.stringify({
+        hello: 'world'
+      }));
+    };
+
+    rail.call({
+      validate: {
+        headers: {
+          id: 'failing-headers',
+          type: 'object',
+          properties: {
+            hello: {
+              type: 'number'
+            }
+          },
+          allowUnknownProperties: true
+        }
+      },
+      buffer: true
+    }, function(response) {
+      assert.strictEqual(response.statusCode, 200);
+
+      assert(response.buffer);
+
+      assert(response.validate);
+      assert.strictEqual(response.validate.body, null);
+      assert.deepEqual(response.validate.headers,
+          [[null, 'object', 'undefined', 'hello']]);
+
+      done();
+    }).end();
+  });
+
+
+  test('failed (no-body)', function(done) {
+    onrequest = function(request, response) {
+      response.end();
+    };
+
+    rail.call({
+      validate: {
+        body: {
+          id: 'simple-body',
+          type: 'object',
+          properties: {
+            hello: {
+              type: 'number'
+            }
+          }
+        }
+      }
+    }, function(response) {
+      assert.strictEqual(response.statusCode, 200);
+
+      assert(response.validate);
+      assert.strictEqual(response.validate.headers, null);
+      assert.deepEqual(response.validate.body,
+          [[null, 'object', 'undefined', null]]);
+
+      done();
+    }).end();
+  });
+
+
+  test('invalid schema #1', function(done) {
+    onrequest = function(request, response) {
+      response.end(JSON.stringify({
+        hello: 'world'
+      }));
+    };
+
+    rail.call({
+      validate: {
+        body: 1234
+      }
+    }).on('error', function(err) {
+      assert(err);
+      assert.strictEqual(err.message, 'Invalid schema');
+      done();
+    }).end();
+  });
+
+
+  test('invalid schema #2', function(done) {
+    onrequest = function(request, response) {
+      response.end(JSON.stringify({
+        hello: 'world'
+      }));
+    };
+
+    rail.call({
+      validate: {
+        body: {
+          xyz: 1
+        }
+      }
+    }).on('error', function(err) {
+      assert(err);
+      assert.strictEqual(err.message, 'Invalid schema id');
+      done();
+    }).end();
+  });
+
+
+  test('invalid schema #3', function(done) {
+    onrequest = function(request, response) {
+      response.end(JSON.stringify({
+        hello: 'world'
+      }));
+    };
+
+    rail.call({
+      validate: {
+        body: {
+          id: 'invalid-schema'
+        }
+      }
+    }).on('error', function(err) {
+      assert(err);
+      assert.strictEqual(err.message, 'Invalid type definition');
+      done();
     }).end();
   });