Added comments to all usages of lib/common/events

- 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

@@ -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}".'
 };

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.
  *

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');
 
 /**

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
  */

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.

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');

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 || {};

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');
 
 /**

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.

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.

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 () {

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 = {

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',
 

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 = {

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',
 

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 = {

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',
 

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

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 () {

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.'
 };

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,

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}.'

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',
 

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}.'

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) {