@tryghost/url-utils 4.4.15 → 5.0.0-rc.1

package/lib/UrlUtils.js

@@ -2,6 +2,24 @@
 const _ = require('lodash');
 const utils = require('./utils');
 
+const STATIC_IMAGE_URL_PREFIX = 'content/images';
+const STATIC_FILES_URL_PREFIX = 'content/files';
+const STATIC_MEDIA_URL_PREFIX = 'content/media';
+
+/**
+ * @typedef {Object} AssetBaseUrls
+ * @property {string} [image] Absolute base URL for images
+ * @property {string} [files] Absolute base URL for files
+ * @property {string} [media] Absolute base URL for media
+ */
+
+function trimTrailingSlash(url) {
+    if (!url) {
+        return url;
+    }
+    return url.replace(/\/+$/, '');
+}
+
 // similar to Object.assign but will not override defaults if a source value is undefined
 function assignOptions(target, ...sources) {
     const options = sources.map((x) => {
@@ -22,24 +40,49 @@ module.exports = class UrlUtils {
     * @param {('content' | 'admin')} [options.defaultApiType='content'] default API type to be used
      * @param {Object} [options.slugs] object with 2 properties reserved and protected containing arrays of special case slugs
      * @param {Number} [options.redirectCacheMaxAge]
-     * @param {String} [options.staticImageUrlPrefix='content/images'] static prefix for serving images. Should not be passed in, unless customizing ghost instance image storage
-     */
+     * @param {AssetBaseUrls} [options.assetBaseUrls] asset CDN base URLs
+    */
     constructor(options = {}) {
         const defaultOptions = {
             slugs: null,
             redirectCacheMaxAge: null,
             baseApiPath: '/ghost/api',
-            defaultApiType: 'content',
-            staticImageUrlPrefix: 'content/images'
+            defaultApiType: 'content'
         };
 
         this._config = assignOptions({}, defaultOptions, options);
+        this._config.staticImageUrlPrefix = STATIC_IMAGE_URL_PREFIX;
+        this._config.staticFilesUrlPrefix = STATIC_FILES_URL_PREFIX;
+        this._config.staticMediaUrlPrefix = STATIC_MEDIA_URL_PREFIX;
+
+        const assetBaseUrls = options.assetBaseUrls || {};
+        this._assetBaseUrls = {
+            image: trimTrailingSlash(assetBaseUrls.image || null),
+            files: trimTrailingSlash(assetBaseUrls.files || null),
+            media: trimTrailingSlash(assetBaseUrls.media || null)
+        };
 
         this.getSubdir = options.getSubdir;
         this.getSiteUrl = options.getSiteUrl;
         this.getAdminUrl = options.getAdminUrl;
     }
 
+    _assetOptionDefaults() {
+        const siteBase = trimTrailingSlash(this.getSiteUrl ? this.getSiteUrl() : null);
+        return {
+            staticImageUrlPrefix: this._config.staticImageUrlPrefix,
+            staticFilesUrlPrefix: this._config.staticFilesUrlPrefix,
+            staticMediaUrlPrefix: this._config.staticMediaUrlPrefix,
+            imageBaseUrl: this._assetBaseUrls.image || siteBase,
+            filesBaseUrl: this._assetBaseUrls.files || null,
+            mediaBaseUrl: this._assetBaseUrls.media || null
+        };
+    }
+
+    _buildAssetOptions(additionalDefaults = {}, options) {
+        return assignOptions({}, this._assetOptionDefaults(), additionalDefaults, options || {});
+    }
+
     getProtectedSlugs() {
         let subDir = this.getSubdir();
 
@@ -234,23 +277,28 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        return utils.toTransformReady(url, this.getSiteUrl(), itemPath, options);
+        const _options = this._buildAssetOptions({}, options);
+        return utils.toTransformReady(url, this.getSiteUrl(), itemPath, _options);
     }
 
     absoluteToTransformReady(url, options) {
-        return utils.absoluteToTransformReady(url, this.getSiteUrl(), options);
+        const _options = this._buildAssetOptions({}, options);
+        return utils.absoluteToTransformReady(url, this.getSiteUrl(), _options);
     }
 
     relativeToTransformReady(url, options) {
-        return utils.relativeToTransformReady(url, this.getSiteUrl(), options);
+        const _options = this._buildAssetOptions({}, options);
+        return utils.relativeToTransformReady(url, this.getSiteUrl(), _options);
     }
 
     transformReadyToAbsolute(url, options) {
-        return utils.transformReadyToAbsolute(url, this.getSiteUrl(), options);
+        const _options = this._buildAssetOptions({}, options);
+        return utils.transformReadyToAbsolute(url, this.getSiteUrl(), _options);
     }
 
     transformReadyToRelative(url, options) {
-        return utils.transformReadyToRelative(url, this.getSiteUrl(), options);
+        const _options = this._buildAssetOptions({}, options);
+        return utils.transformReadyToRelative(url, this.getSiteUrl(), _options);
     }
 
     htmlToTransformReady(html, itemPath, options) {
@@ -258,7 +306,8 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        return utils.htmlToTransformReady(html, this.getSiteUrl(), itemPath, options);
+        const _options = this._buildAssetOptions({}, options);
+        return utils.htmlToTransformReady(html, this.getSiteUrl(), itemPath, _options);
     }
 
     /**
@@ -276,11 +325,9 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        const defaultOptions = {
-            assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix
-        };
-        const _options = assignOptions({}, defaultOptions, options || {});
+        const _options = this._buildAssetOptions({
+            assetsOnly: false
+        }, options);
         return utils.htmlRelativeToAbsolute(html, this.getSiteUrl(), itemPath, _options);
     }
 
@@ -289,29 +336,23 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        const defaultOptions = {
-            assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix
-        };
-        const _options = assignOptions({}, defaultOptions, options || {});
+        const _options = this._buildAssetOptions({
+            assetsOnly: false
+        }, options);
         return utils.htmlRelativeToTransformReady(html, this.getSiteUrl(), itemPath, _options);
     }
 
     htmlAbsoluteToRelative(html, options = {}) {
-        const defaultOptions = {
-            assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix
-        };
-        const _options = assignOptions({}, defaultOptions, options);
+        const _options = this._buildAssetOptions({
+            assetsOnly: false
+        }, options);
         return utils.htmlAbsoluteToRelative(html, this.getSiteUrl(), _options);
     }
 
     htmlAbsoluteToTransformReady(html, options = {}) {
-        const defaultOptions = {
-            assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix
-        };
-        const _options = assignOptions({}, defaultOptions, options);
+        const _options = this._buildAssetOptions({
+            assetsOnly: false
+        }, options);
         return utils.htmlAbsoluteToTransformReady(html, this.getSiteUrl(), _options);
     }
 
@@ -320,7 +361,8 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        return utils.markdownToTransformReady(markdown, this.getSiteUrl(), itemPath, options);
+        const _options = this._buildAssetOptions({}, options);
+        return utils.markdownToTransformReady(markdown, this.getSiteUrl(), itemPath, _options);
     }
 
     markdownRelativeToAbsolute(markdown, itemPath, options) {
@@ -328,11 +370,9 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        const defaultOptions = {
-            assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix
-        };
-        const _options = assignOptions({}, defaultOptions, options || {});
+        const _options = this._buildAssetOptions({
+            assetsOnly: false
+        }, options);
         return utils.markdownRelativeToAbsolute(markdown, this.getSiteUrl(), itemPath, _options);
     }
 
@@ -341,29 +381,23 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        const defaultOptions = {
-            assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix
-        };
-        const _options = assignOptions({}, defaultOptions, options || {});
+        const _options = this._buildAssetOptions({
+            assetsOnly: false
+        }, options);
         return utils.markdownRelativeToTransformReady(markdown, this.getSiteUrl(), itemPath, _options);
     }
 
     markdownAbsoluteToRelative(markdown, options = {}) {
-        const defaultOptions = {
-            assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix
-        };
-        const _options = assignOptions({}, defaultOptions, options);
+        const _options = this._buildAssetOptions({
+            assetsOnly: false
+        }, options);
         return utils.markdownAbsoluteToRelative(markdown, this.getSiteUrl(), _options);
     }
 
     markdownAbsoluteToTransformReady(markdown, options) {
-        const defaultOptions = {
-            assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix
-        };
-        const _options = assignOptions({}, defaultOptions, options);
+        const _options = this._buildAssetOptions({
+            assetsOnly: false
+        }, options);
         return utils.markdownAbsoluteToTransformReady(markdown, this.getSiteUrl(), _options);
     }
 
@@ -372,10 +406,9 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        const defaultOptions = {
+        const _options = this._buildAssetOptions({
             cardTransformers: this._config.cardTransformers
-        };
-        const _options = assignOptions({}, defaultOptions, options || {});
+        }, options);
         return utils.mobiledocToTransformReady(serializedMobiledoc, this.getSiteUrl(), itemPath, _options);
     }
 
@@ -384,12 +417,10 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        const defaultOptions = {
+        const _options = this._buildAssetOptions({
             assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix,
             cardTransformers: this._config.cardTransformers
-        };
-        const _options = assignOptions({}, defaultOptions, options || {});
+        }, options);
         return utils.mobiledocRelativeToAbsolute(serializedMobiledoc, this.getSiteUrl(), itemPath, _options);
     }
 
@@ -398,32 +429,26 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        const defaultOptions = {
+        const _options = this._buildAssetOptions({
             assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix,
             cardTransformers: this._config.cardTransformers
-        };
-        const _options = assignOptions({}, defaultOptions, options || {});
+        }, options);
         return utils.mobiledocRelativeToTransformReady(serializedMobiledoc, this.getSiteUrl(), itemPath, _options);
     }
 
     mobiledocAbsoluteToRelative(serializedMobiledoc, options = {}) {
-        const defaultOptions = {
+        const _options = this._buildAssetOptions({
             assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix,
             cardTransformers: this._config.cardTransformers
-        };
-        const _options = assignOptions({}, defaultOptions, options);
+        }, options);
         return utils.mobiledocAbsoluteToRelative(serializedMobiledoc, this.getSiteUrl(), _options);
     }
 
     mobiledocAbsoluteToTransformReady(serializedMobiledoc, options = {}) {
-        const defaultOptions = {
+        const _options = this._buildAssetOptions({
             assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix,
             cardTransformers: this._config.cardTransformers
-        };
-        const _options = assignOptions({}, defaultOptions, options);
+        }, options);
         return utils.mobiledocAbsoluteToTransformReady(serializedMobiledoc, this.getSiteUrl(), _options);
     }
 
@@ -432,10 +457,9 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        const defaultOptions = {
+        const _options = this._buildAssetOptions({
             cardTransformers: this._config.cardTransformers
-        };
-        const _options = assignOptions({}, defaultOptions, options || {});
+        }, options);
         return utils.lexicalToTransformReady(serializedLexical, this.getSiteUrl(), itemPath, _options);
     }
 
@@ -444,12 +468,10 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        const defaultOptions = {
+        const _options = this._buildAssetOptions({
             assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix,
             cardTransformers: this._config.cardTransformers
-        };
-        const _options = assignOptions({}, defaultOptions, options || {});
+        }, options);
         return utils.lexicalRelativeToAbsolute(serializedLexical, this.getSiteUrl(), itemPath, _options);
     }
 
@@ -458,40 +480,31 @@ module.exports = class UrlUtils {
             options = itemPath;
             itemPath = null;
         }
-        const defaultOptions = {
+        const _options = this._buildAssetOptions({
             assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix,
             cardTransformers: this._config.cardTransformers
-        };
-        const _options = assignOptions({}, defaultOptions, options || {});
+        }, options);
         return utils.lexicalRelativeToTransformReady(serializedLexical, this.getSiteUrl(), itemPath, _options);
     }
 
     lexicalAbsoluteToRelative(serializedLexical, options = {}) {
-        const defaultOptions = {
+        const _options = this._buildAssetOptions({
             assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix,
             cardTransformers: this._config.cardTransformers
-        };
-        const _options = assignOptions({}, defaultOptions, options);
+        }, options);
         return utils.lexicalAbsoluteToRelative(serializedLexical, this.getSiteUrl(), _options);
     }
 
     lexicalAbsoluteToTransformReady(serializedLexical, options = {}) {
-        const defaultOptions = {
+        const _options = this._buildAssetOptions({
             assetsOnly: false,
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix,
             cardTransformers: this._config.cardTransformers
-        };
-        const _options = assignOptions({}, defaultOptions, options);
+        }, options);
         return utils.lexicalAbsoluteToTransformReady(serializedLexical, this.getSiteUrl(), _options);
     }
 
     plaintextToTransformReady(plaintext, options = {}) {
-        const defaultOptions = {
-            staticImageUrlPrefix: this._config.staticImageUrlPrefix
-        };
-        const _options = assignOptions({}, defaultOptions, options);
+        const _options = this._buildAssetOptions({}, options);
         return utils.plaintextToTransformReady(plaintext, this.getSiteUrl(), _options);
     }
 
@@ -534,7 +547,15 @@ module.exports = class UrlUtils {
      * my-content/another-dir/images/2017/01/02/author.png
      */
     get STATIC_IMAGE_URL_PREFIX() {
-        return this._config.staticImageUrlPrefix;
+        return STATIC_IMAGE_URL_PREFIX;
+    }
+
+    get STATIC_FILES_URL_PREFIX() {
+        return STATIC_FILES_URL_PREFIX;
+    }
+
+    get STATIC_MEDIA_URL_PREFIX() {
+        return STATIC_MEDIA_URL_PREFIX;
     }
 
     // expose underlying functions to ease testing

package/lib/utils/absolute-to-transform-ready.js

@@ -1,23 +1,101 @@
+const {URL} = require('url');
 const absoluteToRelative = require('./absolute-to-relative');
 
-const absoluteToTransformReady = function (url, root, _options) {
+function normalizeBaseUrl(baseUrl) {
+    if (!baseUrl) {
+        return null;
+    }
+
+    try {
+        const parsed = new URL(baseUrl);
+        let pathname = parsed.pathname.replace(/\/$/, '');
+        if (pathname === '/') {
+            pathname = '';
+        }
+
+        return {
+            origin: parsed.origin,
+            pathname
+        };
+    } catch (e) {
+        return null;
+    }
+}
+
+function matchCdnBase(parsedUrl, options) {
+    const candidates = [
+        {base: normalizeBaseUrl(options.mediaBaseUrl), prefix: options.staticMediaUrlPrefix},
+        {base: normalizeBaseUrl(options.filesBaseUrl), prefix: options.staticFilesUrlPrefix}
+    ];
+
+    for (const candidate of candidates) {
+        if (!candidate.base || !candidate.prefix) {
+            continue;
+        }
+
+        if (parsedUrl.origin !== candidate.base.origin) {
+            continue;
+        }
+
+        let pathname = parsedUrl.pathname;
+        const basePath = candidate.base.pathname;
+
+        if (basePath) {
+            if (pathname === basePath) {
+                pathname = '/';
+            } else if (pathname.startsWith(basePath + '/')) {
+                pathname = pathname.slice(basePath.length);
+            } else {
+                continue;
+            }
+        }
+
+        if (!pathname.startsWith('/')) {
+            pathname = `/${pathname}`;
+        }
+
+        if (!pathname.startsWith(`/${candidate.prefix}`)) {
+            continue;
+        }
+
+        return `${pathname}${parsedUrl.search}${parsedUrl.hash}`;
+    }
+
+    return null;
+}
+
+const absoluteToTransformReady = function (url, root, _options = {}) {
     const defaultOptions = {
         replacementStr: '__GHOST_URL__',
-        withoutSubdirectory: true
+        withoutSubdirectory: true,
+        staticImageUrlPrefix: 'content/images',
+        staticFilesUrlPrefix: 'content/files',
+        staticMediaUrlPrefix: 'content/media',
+        imageBaseUrl: null,
+        filesBaseUrl: null,
+        mediaBaseUrl: null
     };
     const options = Object.assign({}, defaultOptions, _options);
 
-    // return relative urls as-is
+    let parsedInput;
     try {
-        const parsedURL = new URL(url, 'http://relative');
-        if (parsedURL.origin === 'http://relative') {
-            return url;
-        }
+        parsedInput = new URL(url, 'http://relative');
     } catch (e) {
         // url was unparseable
         return url;
     }
 
+    if (parsedInput.origin !== 'http://relative') {
+        const cdnMatch = matchCdnBase(parsedInput, options);
+        if (cdnMatch) {
+            return `${options.replacementStr}${cdnMatch}`;
+        }
+    }
+
+    if (parsedInput.origin === 'http://relative') {
+        return url;
+    }
+
     // convert to relative with stripped subdir
     // always returns root-relative starting with forward slash
     const relativeUrl = absoluteToRelative(url, root, options);

package/lib/utils/html-absolute-to-transform-ready.js

@@ -1,13 +1,37 @@
 const htmlTransform = require('./html-transform');
 const absoluteToTransformReady = require('./absolute-to-transform-ready');
 
+function escapeRegExp(string) {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function buildEarlyExitMatch(siteUrl, options) {
+    const candidates = [siteUrl, options.imageBaseUrl, options.filesBaseUrl, options.mediaBaseUrl]
+        .filter(Boolean)
+        .map((value) => {
+            let normalized = options.ignoreProtocol ? value.replace(/http:|https:/, '') : value;
+            return normalized.replace(/\/$/, '');
+        })
+        .filter(Boolean)
+        .map(escapeRegExp);
+
+    if (!candidates.length) {
+        return null;
+    }
+
+    if (candidates.length === 1) {
+        return candidates[0];
+    }
+
+    return `(?:${candidates.join('|')})`;
+}
+
 const htmlAbsoluteToTransformReady = function (html = '', siteUrl, _options) {
     const defaultOptions = {assetsOnly: false, ignoreProtocol: true};
     const options = Object.assign({}, defaultOptions, _options || {});
 
-    // exit early and avoid parsing if the content does not contain the siteUrl
-    options.earlyExitMatchStr = options.ignoreProtocol ? siteUrl.replace(/http:|https:/, '') : siteUrl;
-    options.earlyExitMatchStr = options.earlyExitMatchStr.replace(/\/$/, '');
+    // exit early and avoid parsing if the content does not contain the siteUrl or configured asset bases
+    options.earlyExitMatchStr = buildEarlyExitMatch(siteUrl, options);
 
     // need to ignore itemPath because absoluteToRelative doesn't take that option
     const transformFunction = function (_url, _siteUrl, _itemPath, __options) {

package/lib/utils/transform-ready-to-absolute.js

@@ -2,9 +2,22 @@ function escapeRegExp(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+function trimTrailingSlash(url) {
+    if (!url) {
+        return url;
+    }
+    return url.replace(/\/+$/, '');
+}
+
 const transformReadyToAbsolute = function (str = '', root, _options = {}) {
     const defaultOptions = {
-        replacementStr: '__GHOST_URL__'
+        replacementStr: '__GHOST_URL__',
+        staticImageUrlPrefix: 'content/images',
+        staticFilesUrlPrefix: 'content/files',
+        staticMediaUrlPrefix: 'content/media',
+        imageBaseUrl: null,
+        filesBaseUrl: null,
+        mediaBaseUrl: null
     };
     const options = Object.assign({}, defaultOptions, _options);
 
@@ -13,8 +26,28 @@ const transformReadyToAbsolute = function (str = '', root, _options = {}) {
     }
 
     const replacementRegex = new RegExp(escapeRegExp(options.replacementStr), 'g');
+    const fallbackBase = trimTrailingSlash(options.imageBaseUrl || root);
+    const mediaBase = trimTrailingSlash(options.mediaBaseUrl);
+    const filesBase = trimTrailingSlash(options.filesBaseUrl);
+    const imageBase = trimTrailingSlash(options.imageBaseUrl) || fallbackBase;
+
+    return str.replace(replacementRegex, (match, offset) => {
+        const remainder = str.slice(offset + match.length);
+
+        if (options.staticMediaUrlPrefix && remainder.startsWith(`/${options.staticMediaUrlPrefix}`) && mediaBase) {
+            return mediaBase;
+        }
+
+        if (options.staticFilesUrlPrefix && remainder.startsWith(`/${options.staticFilesUrlPrefix}`) && filesBase) {
+            return filesBase;
+        }
+
+        if (options.staticImageUrlPrefix && remainder.startsWith(`/${options.staticImageUrlPrefix}`) && imageBase) {
+            return imageBase;
+        }
 
-    return str.replace(replacementRegex, root.replace(/\/$/, ''));
+        return fallbackBase;
+    });
 };
 
 module.exports = transformReadyToAbsolute;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryghost/url-utils",
-  "version": "4.4.15",
+  "version": "5.0.0-rc.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/TryGhost/SDK.git",
@@ -25,8 +25,8 @@
   "devDependencies": {
     "@tryghost/config-url-helpers": "^1.0.17",
     "c8": "10.1.3",
-    "mocha": "11.2.2",
-    "rewire": "9.0.0",
+    "mocha": "11.7.4",
+    "rewire": "9.0.1",
     "should": "13.2.3",
     "sinon": "21.0.0"
   },
@@ -38,6 +38,5 @@
     "remark": "^11.0.2",
     "remark-footnotes": "^1.0.0",
     "unist-util-visit": "^2.0.0"
-  },
-  "gitHead": "860707f032864400017b0f176cbabf181f99b764"
+  }
 }