closes #832

docs/Reference.md

@@ -417,19 +417,21 @@ The following options are available when adding a route:
                     - `error` - return an Internal Server Error (500) error response. This is the default value.
                     - `log` - log the error but send the response.
 <p></p>
-    - `payload` - determines how the request payload is processed. Defaults to `'parse'` if `validate.payload` is set or when `method` is
-      `'POST'`, `'PUT'` or `'PATCH'`, otherwise `'stream'`. Payload processing is configured using the server [`payload`](#server.config.payload) configuration.
-       Options are:
-        - `'stream'` - the incoming request stream is left untouched, leaving it up to the handler to process the request via `request.raw.req`.
-        - `'raw'` - the payload is read and stored in `request.rawPayload` as a `Buffer` and is not parsed.
-        - `'parse'` - the payload is read and stored in `request.rawPayload` as a `Buffer`, and then parsed (JSON or form-encoded) and stored
-          in `request.payload`. Parsing is performed based on the incoming request 'Content-Type' header. If the parsing is enabled and the
-          format is unknown, a Bad Request (400) error response is sent. The supported mime types are:
-            - application/json
-            - application/x-www-form-urlencoded
-            - multipart/form-data ([formidable](https://npmjs.org/package/formidable) is used for processing this data and is capable of
-              receiving files as well as other form data.  All values are assigned to their respective form names in `request.payload`.
-        - `'try'` - same as `'parse'` but does not return an error on failed parsing. Instead, leaves `request.payload` undefined.
+    - `payload` - determines how the request payload is processed. `payload` can be assigned a string with the parsing mode directly (e.g. `'parse'`)
+      which will use the default values of the other settings, or an object with the following:
+        - `mode` - the parsing mode. Defaults to `'parse'` if `validate.payload` is set or when `method` is
+          `'POST'`, `'PUT'` or `'PATCH'`, otherwise `'stream'`. Payload processing is configured using the server [`payload`](#server.config.payload) configuration.
+          Options are:
+            - `'stream'` - the incoming request stream is left untouched, leaving it up to the handler to process the request via `request.raw.req`.
+            - `'raw'` - the payload is read and stored in `request.rawPayload` as a `Buffer` and is not parsed.
+            - `'parse'` - the payload is read and stored in `request.rawPayload` as a `Buffer`, and then parsed (JSON or form-encoded) and stored
+              in `request.payload`. Parsing is performed based on the incoming request 'Content-Type' header. If the parsing is enabled and the
+              format is unknown, a Bad Request (400) error response is sent. The supported mime types are:
+                - application/json
+                - application/x-www-form-urlencoded
+                - multipart/form-data ([formidable](https://npmjs.org/package/formidable) is used for processing this data and is capable of
+                  receiving files as well as other form data.  All values are assigned to their respective form names in `request.payload`.
+            - `'try'` - same as `'parse'` but does not return an error on failed parsing. Instead, leaves `request.payload` undefined.
 <p></p>
     - `cache` - if the route method is 'GET', the route can be configured to use the cache. The `cache` options are described in
       the [**catbox** module documentation](https://github.com/spumko/catbox#policy) with some additions:

lib/payload.js

@@ -27,7 +27,7 @@ exports.read = function (request, next) {
 
     // Levels are: 'stream', 'raw', 'parse', 'try'
 
-    var level = request.route.payload || (request.route.validate.payload || request.method === 'post' || request.method === 'put'|| request.method === 'patch' ? 'parse' : 'stream');
+    var level = request.route.payload.mode || (request.route.validate.payload || request.method === 'post' || request.method === 'put'|| request.method === 'patch' ? 'parse' : 'stream');
     if (level === 'stream') {
         return next();
     }

lib/route.js

@@ -52,8 +52,14 @@ exports = module.exports = internals.Route = function (options, server, env) {
     // Payload configuration ('stream', 'raw', 'parse')
     // Default is 'parse' for POST and PUT otherwise 'stream'
 
+    if (!this.settings.payload ||
+        typeof this.settings.payload !== 'object') {
+
+        this.settings.payload = { mode: this.settings.payload };
+    }
+
     this.settings.validate = this.settings.validate || {};
-    Utils.assert(!this.settings.validate.payload || !this.settings.payload || this.settings.payload === 'parse', 'Route payload must be set to \'parse\' when payload validation enabled');
+    Utils.assert(!this.settings.validate.payload || !this.settings.payload.mode || this.settings.payload.mode === 'parse', 'Route payload must be set to \'parse\' when payload validation enabled');
     Utils.assert(!this.settings.jsonp || typeof this.settings.jsonp === 'string', 'Bad route JSONP parameter name');
 
     // Authentication configuration

lib/schema.js

@@ -124,7 +124,11 @@ exports.routeConfig = function (config) {
 
 internals.routeConfigSchema = {
     handler: [T.Object(), T.Function(), T.String().valid('notFound')],
-    payload: T.String().valid('stream', 'raw', 'parse', 'try').nullOk(),
+    payload: [T.String().valid('stream', 'raw', 'parse', 'try').nullOk(),
+        T.Object({
+            mode: T.String().valid(['stream', 'raw', 'parse', 'try']).nullOk(),
+        })
+    ],
     auth: [
         T.Object({
             mode: T.String().valid(['required', 'optional', 'try']).nullOk(),

test/integration/payload.js

@@ -316,7 +316,7 @@ describe('Payload', function () {
         server.route({ method: 'POST', path: '/', config: { handler: handler, payload: 'parse' } });
         server.route({ method: 'POST', path: '/text', config: { handler: textHandler } });
         server.route({ method: '*', path: '/any', handler: handler });
-        server.route({ method: 'POST', path: '/try', config: { handler: tryHandler, payload: 'try' } });
+        server.route({ method: 'POST', path: '/try', config: { handler: tryHandler, payload: { mode: 'try' } } });
 
         before(function (done) {