ghost 6.55.0 → 6.57.0

package/core/frontend/services/routing/controllers/rss.js

@@ -1,52 +1,47 @@
-const _ = require('lodash');
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rssController = rssController;
+const lodash_1 = __importDefault(require("lodash"));
+const node_url_1 = __importDefault(require("node:url"));
 const debug = require('@tryghost/debug')('services:routing:controllers:rss');
-const url = require('url');
 const security = require('@tryghost/security');
 const settingsCache = require('../../../../shared/settings-cache');
 const rssService = require('../../rss');
 const renderer = require('../../rendering');
 const dataService = require('../../data');
-
-// @TODO: is this really correct? Should we be using meta data title?
+/**
+ * Generates the title for the RSS feed based on author, tag, or publication settings.
+ */
 function getTitle(relatedData) {
-    relatedData = relatedData || {};
-    let titleStart = _.get(relatedData, 'author[0].name') || _.get(relatedData, 'tag[0].name') || '';
-
+    const data = relatedData || {};
+    let titleStart = lodash_1.default.get(data, 'author[0].name') || lodash_1.default.get(data, 'tag[0].name') || '';
     titleStart += titleStart ? ' - ' : '';
     return titleStart + settingsCache.get('title');
 }
-
 /**
- * @description RSS controller.
- *
- * @TODO: The collection controller does almost the same. Merge!
- * @param {Object} req
- * @param {Object} res
- * @param {Function} next
+ * RSS routing controller.
+ * Fetches posts/meta data and delegates rendering to `rssService`.
  */
-module.exports = function rssController(req, res, next) {
+function rssController(req, res, next) {
     debug('rssController');
-
     const pathOptions = {
         page: 1, // required for fetchData
         slug: req.params.slug ? security.string.safe(req.params.slug) : undefined
     };
-
     // CASE: Ghost is using an rss cache - normalize the URL for use as a key
-    // @TODO: This belongs to the rss service O_o
-    const baseUrl = url.parse(req.originalUrl).pathname;
-
-    dataService.fetchData(pathOptions, res.routerOptions, res.locals)
+    const baseUrl = node_url_1.default.parse(req.originalUrl).pathname;
+    return dataService.fetchData(pathOptions, res.routerOptions, res.locals)
         .then(function formatResult(result) {
-            const response = _.pick(result, ['posts', 'meta']);
-
-            response.title = getTitle(result.data);
-            response.description = settingsCache.get('description');
-
-            return response;
-        })
+        const response = lodash_1.default.pick(result, ['posts', 'meta']);
+        response.title = getTitle(result.data);
+        response.description = settingsCache.get('description');
+        return response;
+    })
         .then(function (data) {
-            return rssService.render(res, baseUrl, data);
-        })
+        return rssService.render(res, baseUrl, data);
+    })
         .catch(renderer.handleError(next));
-};
+}

package/core/frontend/services/routing/controllers/rss.ts

@@ -0,0 +1,66 @@
+import type {Request, Response, NextFunction} from 'express';
+import _ from 'lodash';
+import url from 'node:url';
+
+const debug = require('@tryghost/debug')('services:routing:controllers:rss');
+const security = require('@tryghost/security');
+const settingsCache = require('../../../../shared/settings-cache');
+const rssService = require('../../rss');
+const renderer = require('../../rendering');
+const dataService = require('../../data');
+
+export interface RSSPathOptions {
+    page: number;
+    slug?: string;
+}
+
+export interface RSSResponse extends Response {
+    routerOptions: Record<string, unknown>;
+}
+
+export interface RelatedData {
+    author?: Array<{name: string}>;
+    tag?: Array<{name: string}>;
+    [key: string]: unknown;
+}
+
+/**
+ * Generates the title for the RSS feed based on author, tag, or publication settings.
+ */
+function getTitle(relatedData?: RelatedData): string {
+    const data = relatedData || {};
+    let titleStart = _.get(data, 'author[0].name') || _.get(data, 'tag[0].name') || '';
+
+    titleStart += titleStart ? ' - ' : '';
+    return titleStart + settingsCache.get('title');
+}
+
+/**
+ * RSS routing controller.
+ * Fetches posts/meta data and delegates rendering to `rssService`.
+ */
+export function rssController(req: Request, res: RSSResponse, next: NextFunction): Promise<void> {
+    debug('rssController');
+
+    const pathOptions: RSSPathOptions = {
+        page: 1, // required for fetchData
+        slug: req.params.slug ? security.string.safe(req.params.slug) : undefined
+    };
+
+    // CASE: Ghost is using an rss cache - normalize the URL for use as a key
+    const baseUrl = url.parse(req.originalUrl).pathname;
+
+    return dataService.fetchData(pathOptions, res.routerOptions, res.locals)
+        .then(function formatResult(result: {posts?: unknown[]; meta?: unknown; data?: RelatedData}) {
+            const response = _.pick(result, ['posts', 'meta']) as Record<string, unknown>;
+
+            response.title = getTitle(result.data);
+            response.description = settingsCache.get('description');
+
+            return response;
+        })
+        .then(function (data: Record<string, unknown>) {
+            return rssService.render(res, baseUrl, data);
+        })
+        .catch(renderer.handleError(next));
+}

package/core/frontend/services/routing/controllers/static.js

@@ -1,6 +1,7 @@
 const _ = require('lodash');
 const debug = require('@tryghost/debug')('services:routing:controllers:static');
 const renderer = require('../../rendering');
+const {resolveRouteData} = require('../api-adapter');
 
 function processQuery(query, locals) {
     const api = require('../../proxy').api;
@@ -35,10 +36,10 @@ function processQuery(query, locals) {
 module.exports = function staticController(req, res, next) {
     debug('staticController', res.routerOptions);
 
-    let promises = [];
+    const apiCalls = resolveRouteData(res.routerOptions.data);
 
-    _.each(res.routerOptions.data, function (query) {
-        promises.push(processQuery(query, res.locals));
+    const promises = _.map(apiCalls, function (apiCall) {
+        return processQuery(apiCall, res.locals);
     });
 
     return Promise.all(promises)
@@ -49,13 +50,13 @@ module.exports = function staticController(req, res, next) {
                 response.data = {};
 
                 let resultIndex = 0;
-                _.each(res.routerOptions.data, function (config, name) {
-                    response.data[name] = result[resultIndex][config.resource];
+                _.each(apiCalls, function (apiCall, name) {
+                    response.data[name] = result[resultIndex][apiCall.resource];
 
-                    if (config.type === 'browse') {
+                    if (apiCall.type === 'browse') {
                         response.data[name].meta = result[resultIndex].meta;
                         // @TODO: remove in Ghost 3.0 (see https://github.com/TryGhost/Ghost/issues/10434)
-                        response.data[name][config.resource] = result[resultIndex][config.resource];
+                        response.data[name][apiCall.resource] = result[resultIndex][apiCall.resource];
                     }
 
                     resultIndex = resultIndex + 1;

package/core/frontend/services/routing/events.js

@@ -1,12 +1,26 @@
 const EventEmitter = require('events').EventEmitter;
 
 /**
- * Frontend-internal routing events.
+ * Raised for each router mounted during activation.
  *
- * Carries `router.created` and `routers.reset`, which are emitted by the
- * router manager and consumed only inside the frontend (the sitemap keeps
- * its route entries in sync from them). They used to ride the server's
- * shared event bus purely for historical reasons — nothing server-side
- * listens to them.
+ * @typedef {Object} RouteRegistered
+ * @property {string|null} path - route in domain notation, e.g. `/about/`.
+ *   Null for routers with no route of their own: the static pages router,
+ *   and taxonomies, which have no index route (`/tag/` does not exist).
+ * @property {string} type - the kind of router, e.g. `CollectionRouter`
+ * @property {string} id - the router's identifier
+ */
+
+/**
+ * Frontend-internal routing domain events.
+ *
+ * Carries `RouteRegistered` and `RoutesReset` — the latter has no payload and
+ * is raised before a reload clears the routers. Both are emitted by the router
+ * manager and consumed only inside the frontend (the sitemap keeps its route
+ * entries in sync from them). They used to ride the server's shared event bus
+ * purely for historical reasons — nothing server-side listens to them.
+ *
+ * The payloads are plain data, so a consumer never depends on the internals
+ * of the Express-backed router that happened to raise the event.
  */
 module.exports = new EventEmitter();

package/core/frontend/services/routing/parent-router.js

@@ -13,6 +13,7 @@ const express = require('../../../shared/express');
 const _ = require('lodash');
 const url = require('url');
 const security = require('@tryghost/security');
+const {resolveResourceRead} = require('./api-adapter');
 const urlUtils = require('../../../shared/url-utils').default;
 const registry = require('./registry');
 
@@ -197,6 +198,11 @@ class ParentRouter {
 
     /**
      * @description Figure out if the router has a redirect enabled.
+     *
+     * A route claims a resource by reading it: `data: tag.bacon` on this router
+     * means /tag/bacon/ should redirect here from wherever else it lives. Only
+     * `read` entries claim a slug, and an entry can opt out with `redirect: false`.
+     *
      * @param {string} routerType
      * @param {string} slug
      * @returns {boolean}
@@ -204,14 +210,21 @@ class ParentRouter {
     isRedirectEnabled(routerType, slug) {
         debug('isRedirectEnabled', this.name, this.route && this.route.value, routerType, slug);
 
-        if (!this.data || !Object.keys(this.data.router)) {
+        if (!this.data) {
             return false;
         }
 
-        return _.find(this.data.router, function (entries, type) {
-            if (routerType === type) {
-                return _.find(entries, {redirect: true, slug: slug});
+        // Top-level shorthand (`data: tag.bacon`) is a single unnamed entry.
+        const entries = typeof this.data === 'string' ? [this.data] : Object.values(this.data);
+
+        return entries.some((entry) => {
+            if (typeof entry !== 'string' && entry.redirect === false) {
+                return false;
             }
+
+            const read = resolveResourceRead(entry);
+
+            return !!read && read.resource === routerType && read.slug === slug;
         });
     }
 

package/core/frontend/services/routing/permalink-adapter.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toExpressNotation = toExpressNotation;
+/**
+ * Convert a domain-model permalink into Express / URL-service notation.
+ *
+ * @example toExpressNotation('/{slug}/')               // => '/:slug/'
+ * @example toExpressNotation('/{primary_tag}/{slug}/') // => '/:primary_tag/:slug/'
+ * @example toExpressNotation('/:slug/')                // => '/:slug/' (idempotent)
+ */
+function toExpressNotation(permalink) {
+    return permalink.replace(/{(\w+)}/g, ':$1');
+}

package/core/frontend/services/routing/permalink-adapter.ts

@@ -0,0 +1,10 @@
+/**
+ * Convert a domain-model permalink into Express / URL-service notation.
+ *
+ * @example toExpressNotation('/{slug}/')               // => '/:slug/'
+ * @example toExpressNotation('/{primary_tag}/{slug}/') // => '/:primary_tag/:slug/'
+ * @example toExpressNotation('/:slug/')                // => '/:slug/' (idempotent)
+ */
+export function toExpressNotation(permalink: string): string {
+    return permalink.replace(/{(\w+)}/g, ':$1');
+}

package/core/frontend/services/routing/registry.js

@@ -1,58 +1,82 @@
 const _ = require('lodash');
-let routes = [];
-let routers = {};
 
 /**
- * @description The router registry is helpful for debugging purposes and let's you search existing routes and routers.
+ * Every registered router is a Ghost router — `ParentRouter` itself (the site
+ * and apps routers) or one of its subclasses (Collection, StaticRoutes,
+ * Taxonomy, StaticPages, Preview, Email, Unsubscribe). They wrap an Express
+ * router, reachable via `.router()`, but are not one themselves: the registry's
+ * own lookups read Ghost-side members (`.name`, `.routerName`, `.reset()`,
+ * `.getRssUrl()`) that an Express router does not have.
+ *
+ * Type-only import — no runtime require, so this does not close a cycle with
+ * `parent-router.js`, which requires this module.
+ *
+ * @typedef {import('./parent-router')} ParentRouter
  */
-module.exports = {
+
+/**
+ * @description The router registry is helpful for debugging purposes and lets you search existing routes and routers.
+ *
+ * Exported as a single shared instance so that every consumer
+ * (`routing/index.js`, `parent-router.js`) operates on the same registry, the
+ * same way the previous module-level state did — just held on an instance
+ * rather than in module-scoped `let` variables.
+ */
+class Registry {
+    constructor() {
+        /** @type {Array<{route: string, from: string}>} */
+        this.routes = [];
+        /** @type {Object<string, ParentRouter>} */
+        this.routers = {};
+    }
+
     /**
-     * @description Get's called if you register a url pattern in express.
+     * @description Gets called if you register a url pattern in express.
      * @param {string} routerName
      * @param {string} route
      */
     setRoute(routerName, route) {
-        routes.push({route: route, from: routerName});
-    },
+        this.routes.push({route: route, from: routerName});
+    }
 
     /**
-     * @description Get's called if you register a router in express.
+     * @description Gets called if you register a router in express.
      * @param {string} name
-     * @param {import('express').Router} router
+     * @param {ParentRouter} router
      */
     setRouter(name, router) {
-        routers[name] = router;
-    },
+        this.routers[name] = router;
+    }
 
     /**
      * @description Get all registered routes.
-     * @returns {Array}
+     * @returns {Array<{route: string, from: string}>}
      */
     getAllRoutes() {
-        return _.cloneDeep(routes);
-    },
+        return _.cloneDeep(this.routes);
+    }
 
     /**
      * @description Get router by name.
      * @param {string} name
-     * @returns {import('express').Router}
+     * @returns {ParentRouter|undefined}
      */
     getRouter(name) {
-        return routers[name];
-    },
+        return this.routers[name];
+    }
 
     /**
-     * Gets a router by it's internal router name
+     * Gets a router by its internal router name
      * @param {string} name internal router name
-     * @returns {import('express').Router}
+     * @returns {ParentRouter|undefined}
      */
     getRouterByName(name) {
-        for (let routerKey in routers) {
-            if (routers[routerKey].name === name) {
-                return routers[routerKey];
+        for (let routerKey in this.routers) {
+            if (this.routers[routerKey].name === name) {
+                return this.routers[routerKey];
             }
         }
-    },
+    }
 
     /**
      *
@@ -77,7 +101,7 @@ module.exports = {
     getRssUrl(options) {
         let rssUrl = null;
 
-        const collectionIndexRouter = _.find(routers, {name: 'CollectionRouter', routerName: 'index'});
+        const collectionIndexRouter = _.find(this.routers, {name: 'CollectionRouter', routerName: 'index'});
 
         if (collectionIndexRouter) {
             rssUrl = collectionIndexRouter.getRssUrl(options);
@@ -88,7 +112,7 @@ module.exports = {
             }
         }
 
-        const collectionRouters = _.filter(routers, {name: 'CollectionRouter'});
+        const collectionRouters = _.filter(this.routers, {name: 'CollectionRouter'});
 
         if (collectionRouters && collectionRouters.length === 1) {
             rssUrl = collectionRouters[0].getRssUrl(options);
@@ -108,32 +132,34 @@ module.exports = {
         }
 
         return rssUrl;
-    },
+    }
 
     /**
      * @description Reset all routes.
      */
     resetAllRoutes() {
-        routes = [];
-    },
+        this.routes = [];
+    }
 
     /**
      * @description Reset all routers.
      */
     resetAllRouters() {
-        _.each(routers, (value) => {
+        _.each(this.routers, (value) => {
             if (value && typeof value.reset === 'function') {
                 value.reset();
             }
         });
 
-        routers = {};
-    },
+        this.routers = {};
+    }
 
     /**
      * @description Clear all routers (for testing).
      */
     clearAllRouters() {
-        routers = {};
+        this.routers = {};
     }
-};
+}
+
+module.exports = new Registry();

package/core/frontend/services/routing/router-manager.js

@@ -8,7 +8,7 @@ const ParentRouter = require('./parent-router');
 const EmailRouter = require('./email-router');
 const UnsubscribeRouter = require('./unsubscribe-router');
 
-// Frontend-internal routing events (router.created / routers.reset)
+// Frontend-internal routing domain events (RouteRegistered / RoutesReset)
 const routingEvents = require('./events');
 
 class RouterManager {
@@ -16,7 +16,7 @@ class RouterManager {
         this.registry = registry;
         this.siteRouter = null;
         /**
-         * @type {URLServiceFacade}
+         * @type {UrlService}
          */
         this.urlService = null;
     }
@@ -30,11 +30,17 @@ class RouterManager {
     }
 
     routerCreated(router) {
-        routingEvents.emit('router.created', router);
+        routingEvents.emit('RouteRegistered', {
+            // Not every router owns a route: the static pages router has none,
+            // and taxonomies have no index route (`/tag/` does not exist).
+            path: router.route ? router.route.value : null,
+            type: router.name,
+            id: router.identifier
+        });
 
         // CASE: there are router types which do not generate resource urls
-        //       e.g. static route router, in this case we don't want ot notify the URL service
-        if (!router || !router.getPermalinks()) {
+        //       e.g. static route router, in this case we don't want to notify the URL service
+        if (!router.getPermalinks()) {
             return;
         }
 
@@ -65,7 +71,7 @@ class RouterManager {
         this.registry.resetAllRouters();
         this.registry.resetAllRoutes();
 
-        routingEvents.emit('routers.reset');
+        routingEvents.emit('RoutesReset');
 
         this.siteRouter = new ParentRouter('SiteRouter');
         this.registry.setRouter('siteRouter', this.siteRouter);
@@ -90,10 +96,10 @@ class RouterManager {
      * 5. Static Pages: Weaker than collections, because we first try to find a post slug and fallback to lookup a static page.
      * 6. Internal Apps: Weakest
      *
-     * @param {object} routerSettings
+     * @param {RouteSettings} routeSettings
      */
-    start(routerSettings) {
-        debug('routing start', routerSettings);
+    start(routeSettings) {
+        debug('routing start', routeSettings);
         const RESOURCE_CONFIG = require(`./config`);
 
         const unsubscribeRouter = new UnsubscribeRouter();
@@ -110,14 +116,14 @@ class RouterManager {
         this.siteRouter.mountRouter(previewRouter.router());
         this.registry.setRouter('previewRouter', previewRouter);
 
-        for (const route of routerSettings.routes) {
+        for (const route of routeSettings.routes) {
             const staticRoutesRouter = new StaticRoutesRouter(route.path, route, this.routerCreated.bind(this));
             this.siteRouter.mountRouter(staticRoutesRouter.router());
 
             this.registry.setRouter(staticRoutesRouter.identifier, staticRoutesRouter);
         }
 
-        for (const collection of routerSettings.collections) {
+        for (const collection of routeSettings.collections) {
             const collectionRouter = new CollectionRouter(collection.path, collection, RESOURCE_CONFIG, this.routerCreated.bind(this));
             this.siteRouter.mountRouter(collectionRouter.router());
             this.registry.setRouter(collectionRouter.identifier, collectionRouter);
@@ -128,8 +134,8 @@ class RouterManager {
 
         this.registry.setRouter('staticPagesRouter', staticPagesRouter);
 
-        for (const taxonomy of routerSettings.taxonomies) {
-            const taxonomyRouter = new TaxonomyRouter(taxonomy.key, taxonomy.permalink, RESOURCE_CONFIG, this.routerCreated.bind(this));
+        for (const [key, permalink] of Object.entries(routeSettings.taxonomies)) {
+            const taxonomyRouter = new TaxonomyRouter(key, permalink, RESOURCE_CONFIG, this.routerCreated.bind(this));
             this.siteRouter.mountRouter(taxonomyRouter.router());
 
             this.registry.setRouter(taxonomyRouter.identifier, taxonomyRouter);
@@ -171,7 +177,7 @@ class RouterManager {
         if (collectionRouter && collectionRouter.getPermalinks().getValue().match(/:year|:month|:day/)) {
             debug('handleTimezoneEdit: trigger regeneration');
 
-            this.urlService.onRouterUpdated(collectionRouter.identifier);
+            this.urlService.onRouterUpdated();
         }
     }
 }
@@ -180,20 +186,16 @@ module.exports = RouterManager;
 
 /**
  * @typedef {Object} RouterConfig
- * @property {RouteSettings} [routeSettings] - JSON config representing routes
- * @property {URLServiceFacade} urlService - resource-based URL service facade
+ * @property {RouteSettings} [routeSettings] - parsed route settings domain model
+ * @property {UrlService} urlService - resource-based URL service
  */
 
 /**
- * The shape RouterManager consumes — produced by the activation bridge. This is
- * a temporary reference into server code; when the bridge is removed (HKG-1898)
- * it becomes the domain `RouteSettings` from @tryghost/adapter-base-route-settings.
- *
- * @typedef {import('../../../server/services/route-settings/activation-bridge').RouterSettings} RouteSettings
+ * @typedef {import('@tryghost/adapter-base-route-settings').RouteSettings} RouteSettings
  */
 
 /**
- * @typedef {Object} URLServiceFacade
+ * @typedef {Object} UrlService
  * @property {Function} getUrlForResource
  * @property {Function} ownsResource
  * @property {Function} resolveUrl

package/core/frontend/services/routing/static-routes-router.js

@@ -15,7 +15,7 @@ class StaticRoutesRouter extends ParentRouter {
 
         this.route = {value: mainRoute};
         this.templates = object.templates || [];
-        this.data = object.data || {query: {}, router: {}};
+        this.data = object.data || {};
         this.routerName = mainRoute === '/' ? 'index' : mainRoute.replace(/\//g, '');
         this.routerCreated = routerCreated;
 
@@ -80,7 +80,7 @@ class StaticRoutesRouter extends ParentRouter {
             filter: this.filter,
             limit: this.limit,
             order: this.order,
-            data: this.data.query,
+            data: this.data,
             templates: this.templates
         };
 
@@ -117,7 +117,7 @@ class StaticRoutesRouter extends ParentRouter {
                     message: `Missing template ${res.routerOptions.templates.map(x => `${x}.hbs`).join(', ')} for route "${req.originalUrl}".`
                 });
             },
-            data: this.data.query,
+            data: this.data,
             context: [this.routerName],
             contentType: this.contentType
         };
@@ -131,7 +131,7 @@ class StaticRoutesRouter extends ParentRouter {
      * @returns {boolean}
      */
     isChannel(object) {
-        // buildRouterSettings always sets `type` ('channel' | 'template') on
+        // parseRouteSettings always sets `type` ('channel' | 'template') on
         // every route, so a channel is simply `type === 'channel'`.
         return object?.type === 'channel';
     }

package/core/frontend/services/routing/taxonomy-router.js

@@ -5,6 +5,7 @@ const RSSRouter = require('./rss-router');
 const urlUtils = require('../../../shared/url-utils').default;
 const controllers = require('./controllers');
 const middleware = require('./middleware');
+const {toExpressNotation} = require('./permalink-adapter');
 
 /**
  * @description Taxonomies are groupings of posts based on a common relation.
@@ -17,8 +18,9 @@ class TaxonomyRouter extends ParentRouter {
         this.taxonomyKey = key;
         this.RESOURCE_CONFIG = RESOURCE_CONFIG;
 
+        // convert domain `{slug}` -> Express/URL-service `:slug` at this boundary
         this.permalinks = {
-            value: permalinks
+            value: toExpressNotation(permalinks)
         };
 
         this.permalinks.getValue = () => {
@@ -74,7 +76,9 @@ class TaxonomyRouter extends ParentRouter {
             type: 'channel',
             name: this.taxonomyKey,
             permalinks: this.permalinks.getValue(),
-            data: {[this.taxonomyKey]: this.RESOURCE_CONFIG.QUERY[this.taxonomyKey]},
+            // Route data in domain form — the API adapter resolves it to a
+            // controller call, and fetch-data fills `%s` in from the request.
+            data: {[this.taxonomyKey]: {type: 'read', resource: this.getResourceType(), slug: '%s'}},
             filter: this.RESOURCE_CONFIG.TAXONOMIES[this.taxonomyKey].filter,
             resourceType: this.getResourceType(),
             context: [this.taxonomyKey],