Provide cover for unhandled rejections

API.md

@@ -2871,6 +2871,30 @@ const handler = function (request, reply) {
 };
 ```
 
+If the handler returns a Promise then Hapi will register a `catch` handler on the promise object to catch unhandled promise rejections. The handler will `reply` with the rejected value, wrapped in a [`Boom`](https://github.com/hapijs/boom) error:
+
+```js
+const handler = function (request, reply) {
+
+    const badPromise = () => {
+
+        new Promise((resolve, reject) => {
+
+            // Hapi catches this...
+            throw new Error();
+
+            // ...and this...
+            return reject(new Error());
+        }
+    }
+
+    // ...if you don't provide a 'catch'. The rejection will be wrapped in a Boom error.
+    return badPromise().then(reply);
+}
+```
+
+This provides a safety net for unhandled promise rejections.
+
 ### Route prerequisites
 
 It is often necessary to perform prerequisite actions before the handler is called (e.g. load

lib/handler.js

@@ -3,8 +3,10 @@
 // Load modules
 
 const Hoek = require('hoek');
+const Boom = require('boom');
 const Items = require('items');
 const Methods = require('./methods');
+const Promises = require('./promises');
 const Response = require('./response');
 
 
@@ -96,7 +98,23 @@ internals.handler = function (request, callback) {
 
     // Execute handler
 
-    request.route.settings.handler.call(bind, request, reply);
+    const handlerResult = request.route.settings.handler.call(bind, request, reply);
+
+    // Give hapi a fighting chance to deal with uncaught rejections.
+    if (Promises.isThennable(handlerResult)) {
+
+        handlerResult.then(null, (error) => {
+
+            //  Unhandled rejections are always Boom-ified, just like uncaught exceptions.
+            if (error instanceof Error) {
+                return reply(Boom.wrap(error));
+            }
+
+            const err = new Error('Rejected promise');
+            err.data = error;
+            return reply(Boom.wrap(err));
+        });
+    }
 };
 
 

lib/promises.js

@@ -24,3 +24,9 @@ exports.wrap = function (bind, method, args) {
         method.apply(bind, args ? args.concat(callback) : [callback]);
     });
 };
+
+exports.isThennable = function (candidate) {
+
+    return candidate && (typeof candidate.then === 'function') ? true : false;
+
+};

test/handler.js

@@ -169,6 +169,107 @@ describe('handler', () => {
                 done();
             });
         });
+
+        it('catches asynchronous exceptions in promise constructors via the standard \'protect\' mechanism', (done) => {
+
+            const server = new Hapi.Server({ debug: false });
+            server.connection();
+
+            const asyncOperation = function () {
+
+                return new Promise((resolve, reject) => {
+
+                    setTimeout(() => {
+
+                        throw new Error('This should be caught...');
+                    }, 100);
+                });
+            };
+
+            const handler = function (request, reply) {
+
+                return asyncOperation()
+                  .then(reply);
+            };
+
+            server.route({ method: 'GET', path: '/', handler });
+
+            server.inject('/', (res) => {
+
+                expect(res.statusCode).to.equal(500);
+                expect(res.result.error).to.equal('Internal Server Error');
+                done();
+            });
+        });
+
+        it('catches synchronous exceptions which lead to unhandled promise rejections when then promise is returned', (done) => {
+
+            const server = new Hapi.Server();
+            server.connection();
+
+            const asyncOperation = function () {
+
+                return new Promise((resolve, reject) => {
+
+                    throw new Error('This should be rejected...');
+                });
+            };
+
+            const handler = function (request, reply) {
+
+                return asyncOperation()
+                  .then(reply);
+            };
+
+            server.route({ method: 'GET', path: '/', handler });
+
+            server.inject('/', (res) => {
+
+                expect(res.statusCode).to.equal(500);
+                expect(res.result.error).to.equal('Internal Server Error');
+                done();
+            });
+        });
+
+        it('catches unhandled promise rejections when a promise is returned', (done) => {
+
+            const server = new Hapi.Server();
+            server.connection();
+
+            const handler = function (request, reply) {
+
+                return Promise.reject(new Error('This should be caught.'));
+            };
+
+            server.route({ method: 'GET', path: '/', handler });
+
+            server.inject('/', (res) => {
+
+                expect(res.statusCode).to.equal(500);
+                expect(res.result.error).to.equal('Internal Server Error');
+                done();
+            });
+        });
+
+        it('wraps unhandled promise rejections in an error if needed', (done) => {
+
+            const server = new Hapi.Server();
+            server.connection();
+
+            const handler = function (request, reply) {
+
+                return Promise.reject('this should be wrapped in an error');
+            };
+
+            server.route({ method: 'GET', path: '/', handler });
+
+            server.inject('/', (res) => {
+
+                expect(res.statusCode).to.equal(500);
+                expect(res.result.error).to.equal('Internal Server Error');
+                done();
+            });
+        });
     });
 
     describe('register()', () => {

test/promises.js

@@ -0,0 +1,43 @@
+'use strict';
+
+// Load modules
+
+const Code = require('code');
+const Lab = require('lab');
+const Promises = require('../lib/promises');
+
+// Declare internals
+
+const internals = {};
+
+
+// Test shortcuts
+
+const lab = exports.lab = Lab.script();
+const describe = lab.describe;
+const it = lab.it;
+const expect = Code.expect;
+
+
+describe('promise', () => {
+
+    it('recognises a promise as thennable', (done) => {
+
+        const promise = new Promise(() => {});
+        expect(Promises.isThennable(promise)).to.equal(true);
+
+        done();
+
+    });
+
+    it('recognises invalid input as not thennable', (done) => {
+
+        expect(Promises.isThennable(undefined)).to.equal(false);
+        expect(Promises.isThennable(null)).to.equal(false);
+        expect(Promises.isThennable({ })).to.equal(false);
+        expect(Promises.isThennable({ then: true })).to.equal(false);
+
+        done();
+
+    });
+});