Add policy event (hapijs#4219)

* Add support for policy event

* Update policy event docs to include server methods

* Add policy event tests when used with server.method()

* Rename policy event to cachePolicy

Author: jonathansamines

API.md

@@ -480,6 +480,23 @@ The internally generated events are (identified by their `tags`):
 - `connection` `client` `error` - a `clientError` event was received from the HTTP or HTTPS
   listener. The event data is the error object received.
 
+##### <a name="server.events.cachePolicy" /> `'cachePolicy'` Event
+
+The `'cachePolicy'` event type is emitted when a server [cache policy](https://hapi.dev/module/catbox/api#policy)
+is created via [`server.cache()`](#server.cache()) or a [`server.method()`](#server.method()) with caching enabled is registered.
+The `'cachePolicy'` event handler uses the function signature `function(cachePolicy, cache, segment)` where:
+
+- `cachePolicy` - the catbox [cache policy](https://hapi.dev/module/catbox/api#policy).
+- `cache` - the [cache provision](#server.options.cache) name used when the policy was created or `undefined` if the default cache was used.
+- `segment` - the segment name used when the policy was created.
+
+```js
+server.events.on('cachePolicy', (cachePolicy, cache, segment) => {
+
+    console.log(`New cache policy created using cache: ${cache === undefined ? 'default' : cache} and segment: ${segment}`);
+});
+```
+
 ##### <a name="server.events.request" /> `'request'` Event
 
 The `'request'` event type emits internal request events generated by the framework as well as

lib/core.js

@@ -36,6 +36,7 @@ const internals = {
         max: 99999
     },
     events: [
+        { name: 'cachePolicy', spread: true },
         { name: 'log', channels: ['app', 'internal'], tags: true },
         { name: 'request', channels: ['app', 'internal', 'error'], tags: true, spread: true },
         'response',
@@ -613,7 +614,10 @@ exports = module.exports = internals.Core = class {
         Hoek.assert(!cache.segments[segment] || cache.shared || options.shared, 'Cannot provision the same cache segment more than once');
         cache.segments[segment] = true;
 
-        return new Catbox.Policy(options, cache.client, segment);
+        const policy = new Catbox.Policy(options, cache.client, segment);
+        this.events.emit('cachePolicy', [policy, options.cache, segment]);
+
+        return policy;
     }
 
     log(tags, data) {

test/methods.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const Catbox = require('@hapi/catbox');
 const CatboxMemory = require('@hapi/catbox-memory');
 const Code = require('@hapi/code');
 const Hapi = require('..');
@@ -208,6 +209,43 @@ describe('Methods', () => {
         expect(result2.gen).to.equal(0);
     });
 
+    it('emits a cache policy event on cached methods with default cache provision', async () => {
+
+        const method = function (id) {
+
+            return { id };
+        };
+
+        const server = Hapi.server();
+        const cachePolicyEvent = server.events.once('cachePolicy');
+
+        server.method('test', method, { cache: { expiresIn: 1000, generateTimeout: 10 } });
+
+        const [policy, cacheName, segment] = await cachePolicyEvent;
+        expect(policy).to.be.instanceOf(Catbox.Policy);
+        expect(cacheName).to.equal(undefined);
+        expect(segment).to.equal('#test');
+    });
+
+    it('emits a cache policy event on cached methods with named cache provision', async () => {
+
+        const method = function (id) {
+
+            return { id };
+        };
+
+        const server = Hapi.server();
+        await server.cache.provision({ provider: CatboxMemory, name: 'named' });
+        const cachePolicyEvent = server.events.once('cachePolicy');
+
+        server.method('test', method, { cache: { cache: 'named', expiresIn: 1000, generateTimeout: 10 } });
+
+        const [policy, cacheName, segment] = await cachePolicyEvent;
+        expect(policy).to.be.instanceOf(Catbox.Policy);
+        expect(cacheName).to.equal('named');
+        expect(segment).to.equal('#test');
+    });
+
     it('caches method value (async)', async () => {
 
         let gen = 0;

test/server.js

@@ -193,6 +193,33 @@ describe('Server', () => {
             const value2 = await server.plugins.test.get('a');
             expect(value2).to.equal(null);
         });
+
+        it('emits a cache policy event with default cache provision', async () => {
+
+            const server = Hapi.server();
+            const cachePolicyEvent = server.events.once('cachePolicy');
+
+            const cache = server.cache({ segment: 'test', expiresIn: 1000 });
+
+            const [policy, cacheName, segment] = await cachePolicyEvent;
+            expect(policy).to.shallow.equal(cache);
+            expect(cacheName).to.equal(undefined);
+            expect(segment).to.equal('test');
+        });
+
+        it('emits a cache policy event with named cache provision', async () => {
+
+            const server = Hapi.server();
+            await server.cache.provision({ provider: CatboxMemory, name: 'named' });
+            const cachePolicyEvent = server.events.once('cachePolicy');
+
+            const cache = server.cache({ cache: 'named', segment: 'test', expiresIn: 1000 });
+
+            const [policy, cacheName, segment] = await cachePolicyEvent;
+            expect(policy).to.shallow.equal(cache);
+            expect(cacheName).to.equal('named');
+            expect(segment).to.equal('test');
+        });
     });
 
     describe('cache.provision()', () => {