From 61e1b19d46127cb943e04bdc5901970342d0aab6 Mon Sep 17 00:00:00 2001
From: Hannah Wolfe <github.erisds@gmail.com>
Date: Wed, 7 Jul 2021 15:49:45 +0100
Subject: [PATCH] Added comments to all usages of lib/common/events
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- This is a precursor to trying to split apart into:
   - model events + webhooks system which makes sense
   - frontend events which should be independent or removed
   - maybe some concept of a settings manager that we can use in various places to bind logic 🤔
   - other usages of events that should be refactored to not use events
---
 core/bridge.js                                       | 4 +++-
 core/frontend/services/routing/CollectionRouter.js   | 4 +++-
 core/frontend/services/routing/StaticPagesRouter.js  | 2 ++
 core/frontend/services/routing/StaticRoutesRouter.js | 4 +++-
 core/frontend/services/routing/TaxonomyRouter.js     | 4 +++-
 core/frontend/services/routing/bootstrap.js          | 4 +++-
 core/frontend/services/sitemap/manager.js            | 4 +++-
 core/frontend/services/url/Resources.js              | 2 ++
 core/frontend/services/url/UrlService.js             | 4 +++-
 core/frontend/services/url/Urls.js                   | 4 +++-
 core/server/analytics-events.js                      | 2 ++
 core/server/api/canary/slack.js                      | 1 +
 core/server/api/canary/themes.js                     | 4 +++-
 core/server/api/v2/slack.js                          | 1 +
 core/server/api/v2/themes.js                         | 4 +++-
 core/server/api/v3/slack.js                          | 1 +
 core/server/api/v3/themes.js                         | 4 +++-
 core/server/models/base/listeners.js                 | 4 +++-
 core/server/models/base/plugins/events.js            | 4 +++-
 core/server/services/mega/mega.js                    | 4 +++-
 core/server/services/members/service.js              | 4 +++-
 core/server/services/slack.js                        | 4 +++-
 core/server/services/webhooks/listen.js              | 4 +++-
 core/server/services/xmlrpc.js                       | 4 +++-
 core/server/web/parent/middleware/emit-events.js     | 4 +++-
 25 files changed, 66 insertions(+), 19 deletions(-)

diff --git a/core/bridge.js b/core/bridge.js
index 6bc00c51f3..8bcdec9c81 100644
--- a/core/bridge.js
+++ b/core/bridge.js
@@ -13,11 +13,13 @@ const debug = require('@tryghost/debug')('bridge');
 const errors = require('@tryghost/errors');
 const config = require('./shared/config');
 const logging = require('@tryghost/logging');
-const events = require('./server/lib/common/events');
 const tpl = require('@tryghost/tpl');
 const themeEngine = require('./frontend/services/theme-engine');
 const settingsCache = require('./shared/settings-cache');
 
+// Listen to settings.lang.edited, similar to the member service and models/base/listeners
+const events = require('./server/lib/common/events');
+
 const messages = {
     activateFailed: 'Unable to activate the theme "{theme}".'
 };
diff --git a/core/frontend/services/routing/CollectionRouter.js b/core/frontend/services/routing/CollectionRouter.js
index ba6d66d8a8..517f7a0318 100644
--- a/core/frontend/services/routing/CollectionRouter.js
+++ b/core/frontend/services/routing/CollectionRouter.js
@@ -1,5 +1,4 @@
 const debug = require('@tryghost/debug')('routing:collection-router');
-const events = require('../../../server/lib/common/events');
 const urlUtils = require('../../../shared/url-utils');
 const ParentRouter = require('./ParentRouter');
 
@@ -7,6 +6,9 @@ const controllers = require('./controllers');
 const middlewares = require('./middlewares');
 const RSSRouter = require('./RSSRouter');
 
+// This emits its own routing events AND listens to settings.timezone.edited :(
+const events = require('../../../server/lib/common/events');
+
 /**
  * @description Collection Router for post resource.
  *
diff --git a/core/frontend/services/routing/StaticPagesRouter.js b/core/frontend/services/routing/StaticPagesRouter.js
index e300415c7f..e283dc52e8 100644
--- a/core/frontend/services/routing/StaticPagesRouter.js
+++ b/core/frontend/services/routing/StaticPagesRouter.js
@@ -2,6 +2,8 @@ const debug = require('@tryghost/debug')('routing:static-pages-router');
 const urlUtils = require('../../../shared/url-utils');
 const ParentRouter = require('./ParentRouter');
 const controllers = require('./controllers');
+
+// This emits its own routing events
 const events = require('../../../server/lib/common/events');
 
 /**
diff --git a/core/frontend/services/routing/StaticRoutesRouter.js b/core/frontend/services/routing/StaticRoutesRouter.js
index 9f68ebd35b..e01ee39588 100644
--- a/core/frontend/services/routing/StaticRoutesRouter.js
+++ b/core/frontend/services/routing/StaticRoutesRouter.js
@@ -1,5 +1,4 @@
 const debug = require('@tryghost/debug')('routing:static-routes-router');
-const events = require('../../../server/lib/common/events');
 const errors = require('@tryghost/errors');
 const urlUtils = require('../../../shared/url-utils');
 const RSSRouter = require('./RSSRouter');
@@ -7,6 +6,9 @@ const controllers = require('./controllers');
 const middlewares = require('./middlewares');
 const ParentRouter = require('./ParentRouter');
 
+// This emits its own routing events
+const events = require('../../../server/lib/common/events');
+
 /**
  * @description Template routes allow you to map individual URLs to specific template files within a Ghost theme
  */
diff --git a/core/frontend/services/routing/TaxonomyRouter.js b/core/frontend/services/routing/TaxonomyRouter.js
index 584793659c..d61a188a36 100644
--- a/core/frontend/services/routing/TaxonomyRouter.js
+++ b/core/frontend/services/routing/TaxonomyRouter.js
@@ -1,12 +1,14 @@
 const debug = require('@tryghost/debug')('routing:taxonomy-router');
 const config = require('../../../shared/config');
-const events = require('../../../server/lib/common/events');
 const ParentRouter = require('./ParentRouter');
 const RSSRouter = require('./RSSRouter');
 const urlUtils = require('../../../shared/url-utils');
 const controllers = require('./controllers');
 const middlewares = require('./middlewares');
 
+// This emits its own routing events
+const events = require('../../../server/lib/common/events');
+
 /**
  * @description Taxonomies are groupings of posts based on a common relation.
  * Taxonomies do not change the url of a resource.
diff --git a/core/frontend/services/routing/bootstrap.js b/core/frontend/services/routing/bootstrap.js
index 1dc43dcd1b..f0eab8d0b5 100644
--- a/core/frontend/services/routing/bootstrap.js
+++ b/core/frontend/services/routing/bootstrap.js
@@ -1,6 +1,5 @@
 const debug = require('@tryghost/debug')('routing');
 const _ = require('lodash');
-const events = require('../../../server/lib/common/events');
 const StaticRoutesRouter = require('./StaticRoutesRouter');
 const StaticPagesRouter = require('./StaticPagesRouter');
 const CollectionRouter = require('./CollectionRouter');
@@ -9,6 +8,9 @@ const PreviewRouter = require('./PreviewRouter');
 const ParentRouter = require('./ParentRouter');
 const UnsubscribeRouter = require('./UnsubscribeRouter');
 
+// This emits its own routing events
+const events = require('../../../server/lib/common/events');
+
 const defaultApiVersion = 'v4';
 
 const registry = require('./registry');
diff --git a/core/frontend/services/sitemap/manager.js b/core/frontend/services/sitemap/manager.js
index 0164d69cc0..1bb21c7977 100644
--- a/core/frontend/services/sitemap/manager.js
+++ b/core/frontend/services/sitemap/manager.js
@@ -1,10 +1,12 @@
-const events = require('../../../server/lib/common/events');
 const IndexMapGenerator = require('./index-generator');
 const PagesMapGenerator = require('./page-generator');
 const PostsMapGenerator = require('./post-generator');
 const UsersMapGenerator = require('./user-generator');
 const TagsMapGenerator = require('./tag-generator');
 
+// This uses events from the routing service and the URL service
+const events = require('../../../server/lib/common/events');
+
 class SiteMapManager {
     constructor(options) {
         options = options || {};
diff --git a/core/frontend/services/url/Resources.js b/core/frontend/services/url/Resources.js
index 8112ce5e52..5573a89f93 100644
--- a/core/frontend/services/url/Resources.js
+++ b/core/frontend/services/url/Resources.js
@@ -4,6 +4,8 @@ const debug = require('@tryghost/debug')('services:url:resources');
 const Resource = require('./Resource');
 const config = require('../../../shared/config');
 const models = require('../../../server/models');
+
+// This listens to all manner of model events to find new content that needs a URL...
 const events = require('../../../server/lib/common/events');
 
 /**
diff --git a/core/frontend/services/url/UrlService.js b/core/frontend/services/url/UrlService.js
index 23f83823d9..60cba21695 100644
--- a/core/frontend/services/url/UrlService.js
+++ b/core/frontend/services/url/UrlService.js
@@ -1,7 +1,6 @@
 const _debug = require('@tryghost/debug')._base;
 const debug = _debug('ghost:services:url:service');
 const _ = require('lodash');
-const events = require('../../../server/lib/common/events');
 const errors = require('@tryghost/errors');
 const UrlGenerator = require('./UrlGenerator');
 const Queue = require('./Queue');
@@ -9,6 +8,9 @@ const Urls = require('./Urls');
 const Resources = require('./Resources');
 const urlUtils = require('../../../shared/url-utils');
 
+// This listens to services.themes.api.changed, routing events, and it's own queue events
+const events = require('../../../server/lib/common/events');
+
 /**
  * The url service class holds all instances in a centralised place.
  * It's the public API you can talk to.
diff --git a/core/frontend/services/url/Urls.js b/core/frontend/services/url/Urls.js
index 99b5816d88..470f539991 100644
--- a/core/frontend/services/url/Urls.js
+++ b/core/frontend/services/url/Urls.js
@@ -1,10 +1,12 @@
 const _ = require('lodash');
 const debug = require('@tryghost/debug')('services:url:urls');
-const events = require('../../../server/lib/common/events');
 const urlUtils = require('../../../shared/url-utils');
 const logging = require('@tryghost/logging');
 const errors = require('@tryghost/errors');
 
+// This emits its own url added/removed events
+const events = require('../../../server/lib/common/events');
+
 /**
  * This class keeps track of all urls in the system.
  * Each resource has exactly one url. Each url is owned by exactly one url generator id.
diff --git a/core/server/analytics-events.js b/core/server/analytics-events.js
index 502809c32c..add20bb078 100644
--- a/core/server/analytics-events.js
+++ b/core/server/analytics-events.js
@@ -3,6 +3,8 @@ const Analytics = require('analytics-node');
 const config = require('../shared/config');
 const logging = require('@tryghost/logging');
 const sentry = require('../shared/sentry');
+
+// Listens to model events to layer on analytics - also uses the "fake" theme.uploaded event from the theme API
 const events = require('./lib/common/events');
 
 module.exports.init = function () {
diff --git a/core/server/api/canary/slack.js b/core/server/api/canary/slack.js
index 8b0a64466c..b1e664eea6 100644
--- a/core/server/api/canary/slack.js
+++ b/core/server/api/canary/slack.js
@@ -1,3 +1,4 @@
+// Used to call the slack ping service, iirc this was done to avoid circular deps a long time ago
 const events = require('../../lib/common/events');
 
 module.exports = {
diff --git a/core/server/api/canary/themes.js b/core/server/api/canary/themes.js
index 8d142e2eb3..6e3f6c66a8 100644
--- a/core/server/api/canary/themes.js
+++ b/core/server/api/canary/themes.js
@@ -2,7 +2,6 @@ const fs = require('fs-extra');
 const os = require('os');
 const path = require('path');
 const security = require('@tryghost/security');
-const events = require('../../lib/common/events');
 const themeService = require('../../services/themes');
 const limitService = require('../../services/limits');
 const models = require('../../models');
@@ -10,6 +9,9 @@ const request = require('@tryghost/request');
 const errors = require('@tryghost/errors/lib/errors');
 const i18n = require('../../../shared/i18n');
 
+// Used to emit theme.uploaded which is used in core/server/analytics-events
+const events = require('../../lib/common/events');
+
 module.exports = {
     docName: 'themes',
 
diff --git a/core/server/api/v2/slack.js b/core/server/api/v2/slack.js
index 8b0a64466c..b1e664eea6 100644
--- a/core/server/api/v2/slack.js
+++ b/core/server/api/v2/slack.js
@@ -1,3 +1,4 @@
+// Used to call the slack ping service, iirc this was done to avoid circular deps a long time ago
 const events = require('../../lib/common/events');
 
 module.exports = {
diff --git a/core/server/api/v2/themes.js b/core/server/api/v2/themes.js
index 6ccacfa7ae..7ea2a230c5 100644
--- a/core/server/api/v2/themes.js
+++ b/core/server/api/v2/themes.js
@@ -1,8 +1,10 @@
-const events = require('../../lib/common/events');
 const themeService = require('../../services/themes');
 const limitService = require('../../services/limits');
 const models = require('../../models');
 
+// Used to emit theme.uploaded which is used in core/server/analytics-events
+const events = require('../../lib/common/events');
+
 module.exports = {
     docName: 'themes',
 
diff --git a/core/server/api/v3/slack.js b/core/server/api/v3/slack.js
index 8b0a64466c..b1e664eea6 100644
--- a/core/server/api/v3/slack.js
+++ b/core/server/api/v3/slack.js
@@ -1,3 +1,4 @@
+// Used to call the slack ping service, iirc this was done to avoid circular deps a long time ago
 const events = require('../../lib/common/events');
 
 module.exports = {
diff --git a/core/server/api/v3/themes.js b/core/server/api/v3/themes.js
index 1df8d85117..972e7237c0 100644
--- a/core/server/api/v3/themes.js
+++ b/core/server/api/v3/themes.js
@@ -1,8 +1,10 @@
-const events = require('../../lib/common/events');
 const themeService = require('../../services/themes');
 const limitService = require('../../services/limits');
 const models = require('../../models');
 
+// Used to emit theme.uploaded which is used in core/server/analytics-events
+const events = require('../../lib/common/events');
+
 module.exports = {
     docName: 'themes',
 
diff --git a/core/server/models/base/listeners.js b/core/server/models/base/listeners.js
index fa256f8ca7..3e357d908c 100644
--- a/core/server/models/base/listeners.js
+++ b/core/server/models/base/listeners.js
@@ -1,11 +1,13 @@
 const moment = require('moment-timezone');
 const _ = require('lodash');
 const models = require('../../models');
-const events = require('../../lib/common/events');
 const logging = require('@tryghost/logging');
 const errors = require('@tryghost/errors');
 const Promise = require('bluebird');
 
+// Listen to settings.timezone.edited and settings.notifications.edited to bind extra logic to settings, similar to the bridge and member service
+const events = require('../../lib/common/events');
+
 /**
  * WHEN timezone changes, we will:
  * - reschedule all scheduled posts
diff --git a/core/server/models/base/plugins/events.js b/core/server/models/base/plugins/events.js
index 1d7835f037..c416bc3a25 100644
--- a/core/server/models/base/plugins/events.js
+++ b/core/server/models/base/plugins/events.js
@@ -2,9 +2,11 @@ const _ = require('lodash');
 const debug = require('@tryghost/debug')('models:base:model-events');
 const ObjectId = require('bson-objectid');
 
-const events = require('../../../lib/common/events');
 const schema = require('../../../data/schema');
 
+// This wires up our model event system
+const events = require('../../../lib/common/events');
+
 module.exports = function (Bookshelf) {
     Bookshelf.Model = Bookshelf.Model.extend({
         initializeEvents: function () {
diff --git a/core/server/services/mega/mega.js b/core/server/services/mega/mega.js
index a245312208..260e48f667 100644
--- a/core/server/services/mega/mega.js
+++ b/core/server/services/mega/mega.js
@@ -6,7 +6,6 @@ const url = require('url');
 const moment = require('moment');
 const ObjectID = require('bson-objectid');
 const errors = require('@tryghost/errors');
-const events = require('../../lib/common/events');
 const i18n = require('../../../shared/i18n');
 const logging = require('@tryghost/logging');
 const settingsCache = require('../../../shared/settings-cache');
@@ -20,6 +19,9 @@ const postEmailSerializer = require('./post-email-serializer');
 const {getSegmentsFromHtml} = require('./segment-parser');
 const labs = require('../labs');
 
+// Used to listen to email.added and email.edited model events originally, I think to offload this - ideally would just use jobs now if possible
+const events = require('../../lib/common/events');
+
 const messages = {
     invalidSegment: 'Invalid segment value. Use one of the valid:"status:free" or "status:-free" values.'
 };
diff --git a/core/server/services/members/service.js b/core/server/services/members/service.js
index bd6846c8c9..03bd5f4861 100644
--- a/core/server/services/members/service.js
+++ b/core/server/services/members/service.js
@@ -5,7 +5,6 @@ const MembersCSVImporter = require('./importer');
 const MembersStats = require('./stats');
 const createMembersApiInstance = require('./api');
 const createMembersSettingsInstance = require('./settings');
-const events = require('../../lib/common/events');
 const logging = require('@tryghost/logging');
 const urlUtils = require('../../../shared/url-utils');
 const settingsCache = require('../../../shared/settings-cache');
@@ -13,6 +12,9 @@ const config = require('../../../shared/config');
 const ghostVersion = require('@tryghost/version');
 const _ = require('lodash');
 
+// Bind to settings.edited to update systems based on settings changes, similar to the bridge and models/base/listeners
+const events = require('../../lib/common/events');
+
 const membersConfig = new MembersConfigProvider({
     config,
     settingsCache,
diff --git a/core/server/services/slack.js b/core/server/services/slack.js
index 20f04ef10e..b1874b2120 100644
--- a/core/server/services/slack.js
+++ b/core/server/services/slack.js
@@ -1,5 +1,4 @@
 const errors = require('@tryghost/errors');
-const events = require('../lib/common/events');
 const tpl = require('@tryghost/tpl');
 const logging = require('@tryghost/logging');
 const request = require('@tryghost/request');
@@ -10,6 +9,9 @@ const settingsCache = require('../../shared/settings-cache');
 const schema = require('../data/schema').checks;
 const moment = require('moment');
 
+// Used to receive post.published model event, but also the slack.test event from the API which iirc this was done to avoid circular deps a long time ago
+const events = require('../lib/common/events');
+
 const messages = {
     requestFailedError: 'The {service} service was unable to send a ping request, your site will continue to function.',
     requestFailedHelp: 'If you get this error repeatedly, please seek help on {url}.'
diff --git a/core/server/services/webhooks/listen.js b/core/server/services/webhooks/listen.js
index 1bcdd29ec5..5fa5e19e05 100644
--- a/core/server/services/webhooks/listen.js
+++ b/core/server/services/webhooks/listen.js
@@ -1,9 +1,11 @@
 const _ = require('lodash');
 const limitService = require('../../services/limits');
-const events = require('../../lib/common/events');
 const logging = require('@tryghost/logging');
 const trigger = require('./trigger');
 
+// The webhook system is fundamentally built on top of our model event system
+const events = require('../../lib/common/events');
+
 const WEBHOOKS = [
     'site.changed',
 
diff --git a/core/server/services/xmlrpc.js b/core/server/services/xmlrpc.js
index 541b749bff..8dbb4c99ce 100644
--- a/core/server/services/xmlrpc.js
+++ b/core/server/services/xmlrpc.js
@@ -3,13 +3,15 @@ const xml = require('xml');
 const config = require('../../shared/config');
 const urlService = require('../../frontend/services/url');
 const errors = require('@tryghost/errors');
-const events = require('../lib/common/events');
 const tpl = require('@tryghost/tpl');
 const logging = require('@tryghost/logging');
 const request = require('@tryghost/request');
 const settingsCache = require('../../shared/settings-cache');
 const sentry = require('../../shared/sentry');
 
+// Used to receive post.published model event
+const events = require('../lib/common/events');
+
 const messages = {
     requestFailedError: 'The {service} service was unable to send a ping request, your site will continue to function.',
     requestFailedHelp: 'If you get this error repeatedly, please seek help on {url}.'
diff --git a/core/server/web/parent/middleware/emit-events.js b/core/server/web/parent/middleware/emit-events.js
index 0c8baae3e3..318bd32612 100644
--- a/core/server/web/parent/middleware/emit-events.js
+++ b/core/server/web/parent/middleware/emit-events.js
@@ -1,6 +1,8 @@
-const events = require('../../../lib/common/events');
 const INVALIDATE_ALL = '/*';
 
+// Emit the site.changed event, a special model event used for webhooks
+const events = require('../../../lib/common/events');
+
 module.exports = function emitEvents(req, res, next) {
     res.on('finish', function triggerEvents() {
         if (res.get('X-Cache-Invalidate') === INVALIDATE_ALL) {