Feat: Improved error handling and response status availability (#2303)

* Add response data to route object
* Display error status and description on content fetch error
* Fix issue where initial site render was incomplete on content fetch error
* Fix issue where empty markdown pages/routes were handled as 404 errors
* Fix incorrect `notFoundPage` default value

Author: jhildenbiddle

docs/configuration.md

@@ -534,7 +534,7 @@ To disable emoji parsing of individual shorthand codes, replace `:` characters w
 - Type: `Boolean` | `String` | `Object`
 - Default: `false`
 
-Display default "404 - Not found" message:
+Display default "404 - Not Found" message:
 
 ```js
 window.$docsify = {

src/core/config.js

@@ -30,7 +30,7 @@ export default function (vm) {
       nativeEmoji: false,
       noCompileLinks: [],
       noEmoji: false,
-      notFoundPage: true,
+      notFoundPage: false,
       plugins: [],
       relativePath: false,
       repo: '',

src/core/fetch/index.js

@@ -102,7 +102,8 @@ export function Fetch(Base) {
         this.isHTML = /\.html$/g.test(file);
 
         // create a handler that should be called if content was fetched successfully
-        const contentFetched = (text, opt) => {
+        const contentFetched = (text, opt, response) => {
+          this.route.response = response;
           this._renderMain(
             text,
             opt,
@@ -111,7 +112,8 @@ export function Fetch(Base) {
         };
 
         // and a handler that is called if content failed to fetch
-        const contentFailedToFetch = _error => {
+        const contentFailedToFetch = (_error, response) => {
+          this.route.response = response;
           this._fetchFallbackPage(path, qs, cb) || this._fetch404(file, qs, cb);
         };
 

src/core/render/index.js

@@ -60,10 +60,6 @@ export function Render(Base) {
         return isVue2 || isVue3;
       };
 
-      if (!html) {
-        html = /* html */ `<h1>404 - Not found</h1>`;
-      }
-
       if ('Vue' in window) {
         const mountedElms = dom
           .findAll('.markdown-section > *')
@@ -310,8 +306,12 @@ export function Render(Base) {
     }
 
     _renderMain(text, opt = {}, next) {
-      if (!text) {
-        return this.#renderMain(text);
+      const { response } = this.route;
+
+      // Note: It is possible for the response to be undefined in environments
+      // where XMLHttpRequest has been modified or mocked
+      if (response && !response.ok && (!text || response.status !== 404)) {
+        text = `# ${response.status} - ${response.statusText}`;
       }
 
       this.callHook('beforeEach', text, result => {

src/core/router/history/hash.js

@@ -92,6 +92,7 @@ export class HashHistory extends History {
       path,
       file: this.getFile(path, true),
       query: parseQuery(query),
+      response: {},
     };
   }
 

src/core/router/history/html5.js

@@ -59,6 +59,7 @@ export class HTML5History extends History {
       path,
       file: this.getFile(path),
       query: parseQuery(query),
+      response: {},
     };
   }
 }

src/core/util/ajax.js

@@ -4,10 +4,10 @@ import progressbar from '../render/progressbar.js';
 import { noop } from './core.js';
 
 /** @typedef {{updatedAt: string}} CacheOpt */
-
 /** @typedef {{content: string, opt: CacheOpt}} CacheItem */
-
+/** @typedef {{ok: boolean, status: number, statusText: string}} ResponseStatus */
 /** @type {Record<string, CacheItem>} */
+
 const cache = {};
 
 /**
@@ -37,10 +37,16 @@ export function get(url, hasBar = false, headers = {}) {
 
   return {
     /**
-     * @param {(text: string, opt: CacheOpt) => void} success
-     * @param {(event: ProgressEvent<XMLHttpRequestEventTarget>) => void} error
+     * @param {(text: string, opt: CacheOpt, response: ResponseStatus) => void} success
+     * @param {(event: ProgressEvent<XMLHttpRequestEventTarget>, response: ResponseStatus) => void} error
      */
     then(success, error = noop) {
+      const getResponseStatus = event => ({
+        ok: event.target.status >= 200 && event.target.status < 300,
+        status: event.target.status,
+        statusText: event.target.statusText,
+      });
+
       if (hasBar) {
         const id = setInterval(
           _ =>
@@ -57,11 +63,15 @@ export function get(url, hasBar = false, headers = {}) {
         });
       }
 
-      xhr.addEventListener('error', error);
+      xhr.addEventListener('error', event => {
+        error(event, getResponseStatus(event));
+      });
+
       xhr.addEventListener('load', event => {
         const target = /** @type {XMLHttpRequest} */ (event.target);
+
         if (target.status >= 400) {
-          error(event);
+          error(event, getResponseStatus(event));
         } else {
           if (typeof target.response !== 'string') {
             throw new TypeError('Unsupported content type.');
@@ -74,7 +84,7 @@ export function get(url, hasBar = false, headers = {}) {
             },
           });
 
-          success(result.content, result.opt);
+          success(result.content, result.opt, getResponseStatus(event));
         }
       });
     },

test/e2e/configuration.test.js

@@ -3,64 +3,146 @@ import docsifyInit from '../helpers/docsify-init.js';
 import { test, expect } from './fixtures/docsify-init-fixture.js';
 
 test.describe('Configuration options', () => {
-  test('catchPluginErrors:true (handles uncaught errors)', async ({ page }) => {
-    let consoleMsg, errorMsg;
-
-    page.on('console', msg => (consoleMsg = msg.text()));
-    page.on('pageerror', err => (errorMsg = err.message));
-
-    await docsifyInit({
-      config: {
-        catchPluginErrors: true,
-        plugins: [
-          function (hook, vm) {
-            hook.init(function () {
-              fail();
-            });
-            hook.beforeEach(markdown => {
-              return `${markdown}\n\nbeforeEach`;
-            });
-          },
-        ],
-      },
-      markdown: {
-        homepage: '# Hello World',
-      },
-      // _logHTML: true,
+  test.describe('catchPluginErrors', () => {
+    test('true (handles uncaught errors)', async ({ page }) => {
+      let consoleMsg, errorMsg;
+
+      page.on('console', msg => (consoleMsg = msg.text()));
+      page.on('pageerror', err => (errorMsg = err.message));
+
+      await docsifyInit({
+        config: {
+          catchPluginErrors: true,
+          plugins: [
+            function (hook, vm) {
+              hook.init(function () {
+                fail();
+              });
+              hook.beforeEach(markdown => {
+                return `${markdown}\n\nbeforeEach`;
+              });
+            },
+          ],
+        },
+        markdown: {
+          homepage: '# Hello World',
+        },
+        // _logHTML: true,
+      });
+
+      const mainElm = page.locator('#main');
+
+      expect(errorMsg).toBeUndefined();
+      expect(consoleMsg).toContain('Docsify plugin error');
+      await expect(mainElm).toContainText('Hello World');
+      await expect(mainElm).toContainText('beforeEach');
     });
 
-    const mainElm = page.locator('#main');
+    test('false (throws uncaught errors)', async ({ page }) => {
+      let consoleMsg, errorMsg;
+
+      page.on('console', msg => (consoleMsg = msg.text()));
+      page.on('pageerror', err => (errorMsg = err.message));
 
-    expect(errorMsg).toBeUndefined();
-    expect(consoleMsg).toContain('Docsify plugin error');
-    await expect(mainElm).toContainText('Hello World');
-    await expect(mainElm).toContainText('beforeEach');
+      await docsifyInit({
+        config: {
+          catchPluginErrors: false,
+          plugins: [
+            function (hook, vm) {
+              hook.ready(function () {
+                fail();
+              });
+            },
+          ],
+        },
+        markdown: {
+          homepage: '# Hello World',
+        },
+        // _logHTML: true,
+      });
+
+      expect(consoleMsg).toBeUndefined();
+      expect(errorMsg).toContain('fail');
+    });
   });
 
-  test('catchPluginErrors:false (throws uncaught errors)', async ({ page }) => {
-    let consoleMsg, errorMsg;
+  test.describe('notFoundPage', () => {
+    test.describe('renders default error content', () => {
+      test.beforeEach(async ({ page }) => {
+        await page.route('README.md', async route => {
+          await route.fulfill({
+            status: 500,
+          });
+        });
+      });
+
+      test('false', async ({ page }) => {
+        await docsifyInit({
+          config: {
+            notFoundPage: false,
+          },
+        });
 
-    page.on('console', msg => (consoleMsg = msg.text()));
-    page.on('pageerror', err => (errorMsg = err.message));
+        await expect(page.locator('#main')).toContainText('500');
+      });
 
-    await docsifyInit({
-      config: {
-        catchPluginErrors: false,
-        plugins: [
-          function (hook, vm) {
-            hook.ready(function () {
-              fail();
-            });
+      test('true with non-404 error', async ({ page }) => {
+        await docsifyInit({
+          config: {
+            notFoundPage: true,
+          },
+          routes: {
+            '_404.md': '',
           },
-        ],
-      },
-      markdown: {
-        homepage: '# Hello World',
-      },
-      // _logHTML: true,
+        });
+
+        await expect(page.locator('#main')).toContainText('500');
+      });
+
+      test('string with non-404 error', async ({ page }) => {
+        await docsifyInit({
+          config: {
+            notFoundPage: '404.md',
+          },
+          routes: {
+            '404.md': '',
+          },
+        });
+
+        await expect(page.locator('#main')).toContainText('500');
+      });
     });
 
-    expect(consoleMsg).toBeUndefined();
-    expect(errorMsg).toContain('fail');
+    test('true: renders _404.md page', async ({ page }) => {
+      const expectText = 'Pass';
+
+      await docsifyInit({
+        config: {
+          notFoundPage: true,
+        },
+        routes: {
+          '_404.md': expectText,
+        },
+      });
+
+      await page.evaluate(() => (window.location.hash = '#/fail'));
+      await expect(page.locator('#main')).toContainText(expectText);
+    });
+
+    test('string: renders specified 404 page', async ({ page }) => {
+      const expectText = 'Pass';
+
+      await docsifyInit({
+        config: {
+          notFoundPage: '404.md',
+        },
+        routes: {
+          '404.md': expectText,
+        },
+      });
+
+      await page.evaluate(() => (window.location.hash = '#/fail'));
+      await expect(page.locator('#main')).toContainText(expectText);
+    });
   });
 });