fix: recover API when startup notification is missed

KristjanESPERANTO · KristjanESPERANTO · commit 46a27f70dc6c · 2026-07-03T16:10:48.000+02:00
Previously the remote API could get stuck as "Not initialized" if the browser's startup signal was missed, breaking every request until a manual refresh. It now fetches the current state on demand and answers the request as soon as the mirror responds. Ref Jopyth#412
diff --git a/API/api.js b/API/api.js
@@ -149,8 +149,7 @@ module.exports = {
     // Route for testing the api at http://mirror:8080/api/test
     this.expressRouter.route(["/test", "/"]). // Test without apiKey
       get((request, response) => {
-        if (!this.checkInitialized(response)) { return; }
-        response.json({success: true});
+        response.json({success: true, initialized: Boolean(this.initialized)});
       });
 
     /*
@@ -400,7 +399,10 @@ module.exports = {
   },
 
   answerModuleApi (request, response) {
-    if (!this.checkInitialized(response)) { return; }
+    this.requireLiveState(response, () => this.resolveModuleApi(request, response));
+  },
+
+  resolveModuleApi (request, response) {
     const dataMerged = this.mergeData().data;
 
     if (!request.params.moduleName) {
@@ -568,14 +570,6 @@ module.exports = {
 
   },
 
-  checkInitialized (response) {
-    if (!this.initialized) {
-      this.sendResponse(response, "Not initialized, have you opened or refreshed your browser since the last time you started MagicMirror²?");
-      return false;
-    }
-    return true;
-  },
-
   updateModuleApiMenu () {
     if (!this.thisConfig.showModuleApiMenu) { return; }
 
diff --git a/node_helper.js b/node_helper.js
@@ -508,43 +508,37 @@ module.exports = NodeHelper.create({
   },
 
   handleGetModules (query, response) {
-    if (!this.checkInitialized(response)) { return; }
-    this.callAfterUpdate(() => {
+    this.requireLiveState(response, () => {
       this.sendResponse(response, undefined, {query, data: this.configData.moduleData});
     });
   },
 
   handleGetBrightness (query, response) {
-    if (!this.checkInitialized(response)) { return; }
-    this.callAfterUpdate(() => {
+    this.requireLiveState(response, () => {
       this.sendResponse(response, undefined, {query, result: this.configData.brightness});
     });
   },
 
   handleGetTemp (query, response) {
-    if (!this.checkInitialized(response)) { return; }
-    this.callAfterUpdate(() => {
+    this.requireLiveState(response, () => {
       this.sendResponse(response, undefined, {query, result: this.configData.temp});
     });
   },
 
   handleGetZoom (query, response) {
-    if (!this.checkInitialized(response)) { return; }
-    this.callAfterUpdate(() => {
+    this.requireLiveState(response, () => {
       this.sendResponse(response, undefined, {query, result: this.configData.zoom});
     });
   },
 
   handleGetBackgroundColor (query, response) {
-    if (!this.checkInitialized(response)) { return; }
-    this.callAfterUpdate(() => {
+    this.requireLiveState(response, () => {
       this.sendResponse(response, undefined, {query, result: this.configData.backgroundColor});
     });
   },
 
   handleGetFontColor (query, response) {
-    if (!this.checkInitialized(response)) { return; }
-    this.callAfterUpdate(() => {
+    this.requireLiveState(response, () => {
       this.sendResponse(response, undefined, {query, result: this.configData.fontColor});
     });
   },
@@ -604,14 +598,36 @@ module.exports = NodeHelper.create({
 
   callAfterUpdate (callback, timeout = 3000) {
     let isDone = false;
-    const once = () => {
+    const once = (didUpdate) => {
       if (isDone) { return; }
       isDone = true;
-      callback();
+      callback(didUpdate);
     };
-    this.waiting.push({run: once});
+    this.waiting.push({run: () => once(true)});
     this.sendSocketNotification("UPDATE");
-    setTimeout(once, timeout);
+    setTimeout(() => once(false), timeout);
+  },
+
+  /**
+   * Serve a request that depends on live frontend state.
+   *
+   * Instead of relying on a boot-time notification having been received, this
+   * actively pulls a fresh CURRENT_STATUS from the frontend (via callAfterUpdate).
+   * It is self-healing: even if the frontend missed DOM_OBJECTS_CREATED at
+   * startup, the triggered UPDATE makes it resend its state. An error is only
+   * returned when no state can be obtained at all (no browser connected).
+   * @param {object} response - Express or socket response object
+   * @param {() => void} callback - Invoked once live state is available
+   * @returns {void}
+   */
+  requireLiveState (response, callback) {
+    this.callAfterUpdate((didUpdate) => {
+      if (didUpdate || this.initialized) {
+        callback();
+      } else {
+        this.sendResponse(response, "Not connected to the MagicMirror² frontend. Open or refresh a browser pointing at the mirror.");
+      }
+    });
   },
 
   delayedQuery (query, response) {
@@ -1058,13 +1074,14 @@ module.exports = NodeHelper.create({
       case "CURRENT_STATUS":
         this.configData = payload;
         this.thisConfig = payload.remoteConfig;
-        if (this.initialized) {
-          for (const o of this.waiting) { o.run(); }
-          this.waiting = [];
-        } else {
-        // Do anything else required to initialize
-          this.initialized = true;
-        }
+        this.initialized = true;
+
+        /*
+         * Always drain requests waiting for fresh frontend state. The pull is
+         * idempotent, so a missed boot-time notification is no longer fatal.
+         */
+        for (const o of this.waiting) { o.run(); }
+        this.waiting = [];
 
         break;
       case "REQUEST_DEFAULT_SETTINGS":
diff --git a/tests/integration/api.multi-instance.test.js b/tests/integration/api.multi-instance.test.js
@@ -93,7 +93,8 @@ function createMockContext (app, notifications) {
     handleGetModuleInstalled: helperModule.handleGetModuleInstalled,
     getDataHandlers: helperModule.getDataHandlers,
     sendResponse: helperModule.sendResponse,
-    checkInitialized: helperModule.checkInitialized,
+    requireLiveState: (_res, cb) => cb(),
+    resolveModuleApi: apiModule.resolveModuleApi,
     getActionHandlers: helperModule.getActionHandlers,
     executeQuery: helperModule.executeQuery,
     handleSimpleSocketNotification: helperModule.handleSimpleSocketNotification,
@@ -129,7 +130,6 @@ function createMockContext (app, notifications) {
   mockContext.handleGetModuleInstalled = mockContext.handleGetModuleInstalled.bind(mockContext);
   mockContext.getDataHandlers = mockContext.getDataHandlers.bind(mockContext);
   mockContext.sendResponse = mockContext.sendResponse.bind(mockContext);
-  mockContext.checkInitialized = mockContext.checkInitialized.bind(mockContext);
   mockContext.getActionHandlers = mockContext.getActionHandlers.bind(mockContext);
   mockContext.executeQuery = mockContext.executeQuery.bind(mockContext);
   mockContext.handleSimpleSocketNotification = mockContext.handleSimpleSocketNotification.bind(mockContext);
@@ -138,6 +138,7 @@ function createMockContext (app, notifications) {
   mockContext.checkDelay = mockContext.checkDelay.bind(mockContext);
   mockContext.answerNotifyApi = mockContext.answerNotifyApi.bind(mockContext);
   mockContext.answerModuleApi = mockContext.answerModuleApi.bind(mockContext);
+  mockContext.resolveModuleApi = mockContext.resolveModuleApi.bind(mockContext);
   mockContext.mergeData = mockContext.mergeData.bind(mockContext);
 
   return mockContext;
diff --git a/tests/integration/api.smoke.test.js b/tests/integration/api.smoke.test.js
@@ -121,12 +121,12 @@ describe("API HTTP-Layer Smoke Tests", () => {
         return !error;
       },
 
-      checkInitialized (res) {
-        if (!mockContext.initialized) {
-          mockContext.sendResponse(res, new Error("System not initialized"));
-          return false;
+      requireLiveState (res, cb) {
+        if (mockContext.initialized) {
+          cb();
+        } else {
+          mockContext.sendResponse(res, new Error("Not connected to frontend"));
         }
-        return true;
       },
 
       getApiKey () {
@@ -159,7 +159,8 @@ describe("API HTTP-Layer Smoke Tests", () => {
 
       // Bind API methods
       answerNotifyApi: apiModule.answerNotifyApi,
-      answerModuleApi: apiModule.answerModuleApi
+      answerModuleApi: apiModule.answerModuleApi,
+      resolveModuleApi: apiModule.resolveModuleApi
     };
 
     // Bind all methods to context
@@ -169,6 +170,7 @@ describe("API HTTP-Layer Smoke Tests", () => {
     mockContext.getDataHandlers = mockContext.getDataHandlers.bind(mockContext);
     mockContext.answerNotifyApi = mockContext.answerNotifyApi.bind(mockContext);
     mockContext.answerModuleApi = mockContext.answerModuleApi.bind(mockContext);
+    mockContext.resolveModuleApi = mockContext.resolveModuleApi.bind(mockContext);
 
     // Bind API methods to context
     apiModule.createApiRoutes.call(mockContext);
diff --git a/tests/unit/answerGet.contract.test.js b/tests/unit/answerGet.contract.test.js
@@ -22,7 +22,7 @@ function freshHelper (overrides = {}) {
   helper.configOnHd = {language: "en", modules: []};
   helper.configData = {moduleData: []};
   helper.sendSocketNotification = () => {};
-  helper.checkInitialized = () => true;
+  helper.initialized = true;
   helper.callAfterUpdate = (function_) => function_();
   helper.removeDefaultValues = (config) => config;
   helper.answerGet = helperFactory.answerGet.bind(helper);
diff --git a/tests/unit/api.answerModuleApi.test.js b/tests/unit/api.answerModuleApi.test.js
@@ -13,7 +13,8 @@ function makeContext (overrides = {}) {
     mergeData: () => ({success: true, data: context.configData.moduleData}),
     sendSocketNotification: () => {},
     sendResponse: () => {},
-    checkInitialized: () => true,
+    requireLiveState: (_res, cb) => cb(),
+    resolveModuleApi: apiModule.resolveModuleApi,
     translate: (s) => s,
     thisConfig: {},
     ...overrides
diff --git a/tests/unit/api.delayedFlow.test.js b/tests/unit/api.delayedFlow.test.js
@@ -11,7 +11,6 @@ function makeContext (overrides = {}) {
     translation: {},
     sendSocketNotification: () => {},
     sendResponse: () => {},
-    checkInitialized: () => true,
     checkDelay: apiModule.checkDelay,
     translate: (s) => s,
     delayedQuery: () => {},
diff --git a/tests/unit/api.helpers.test.js b/tests/unit/api.helpers.test.js
@@ -12,7 +12,6 @@ function makeContext (overrides = {}) {
     translation: {},
     sendSocketNotification: () => {},
     sendResponse: () => {},
-    checkInitialized: () => true,
     translate: (s) => s,
     thisConfig: {},
     ...overrides
@@ -152,22 +151,4 @@ describe("API helpers", () => {
       assert.deepEqual(captured.payload.payload, {param: "raw-value", foo: "bar"});
     });
   });
-
-  describe("checkInitialized", () => {
-    test("returns false and sends response when helper is not initialized", () => {
-      let capturedError;
-      const context = makeContext({
-        initialized: false,
-        sendResponse: (_res, error) => {
-          capturedError = error;
-        }
-      });
-
-      const result = apiModule.checkInitialized.call(context, {status: () => ({json: () => {}})});
-
-      assert.equal(result, false);
-      assert.equal(typeof capturedError, "string");
-      assert.ok(capturedError.includes("Not initialized"));
-    });
-  });
 });
diff --git a/tests/unit/executeQuery.error.test.js b/tests/unit/executeQuery.error.test.js
@@ -24,7 +24,6 @@ function freshHelper (overrides = {}) {
   helper.thisConfig = {classes: {}};
   helper.configOnHd = {};
   helper.configData = {moduleData: []};
-  helper.checkInitialized = () => true;
   helper.executeQuery = helperFactory.executeQuery.bind(helper);
   helper.handleNotification = helperFactory.handleNotification.bind(helper);
   helper.handleSimpleSocketNotification = helperFactory.handleSimpleSocketNotification.bind(helper);
diff --git a/tests/unit/executeQuery.handlers.test.js b/tests/unit/executeQuery.handlers.test.js
@@ -80,6 +80,47 @@ describe("callAfterUpdate", () => {
   });
 });
 
+describe("requireLiveState", () => {
+  test("serves fresh state when frontend responds to the pull", () => {
+    const helper = freshHelper();
+    helper.initialized = false;
+    helper.callAfterUpdate = (cb) => cb(true);
+    helper.requireLiveState = helperFactory.requireLiveState.bind(helper);
+
+    let isServed = false;
+    helper.requireLiveState({}, () => { isServed = true; });
+
+    assert.ok(isServed);
+    assert.equal(helper.__responses.length, 0);
+  });
+
+  test("serves existing state when the pull times out but state is present", () => {
+    const helper = freshHelper();
+    helper.initialized = true;
+    helper.callAfterUpdate = (cb) => cb(false);
+    helper.requireLiveState = helperFactory.requireLiveState.bind(helper);
+
+    let isServed = false;
+    helper.requireLiveState({}, () => { isServed = true; });
+
+    assert.ok(isServed);
+  });
+
+  test("responds with an error when no state can be obtained at all", () => {
+    const helper = freshHelper();
+    helper.initialized = false;
+    helper.callAfterUpdate = (cb) => cb(false);
+    helper.requireLiveState = helperFactory.requireLiveState.bind(helper);
+
+    let isServed = false;
+    helper.requireLiveState({}, () => { isServed = true; });
+
+    assert.equal(isServed, false);
+    assert.equal(helper.__responses.length, 1);
+    assert.ok(String(helper.__responses[0].err).includes("Not connected"));
+  });
+});
+
 describe("getActionHandlers", () => {
   test("returns object with all action handlers", () => {
     const helper = freshHelper();
diff --git a/tests/unit/executeQuery.notifications.test.js b/tests/unit/executeQuery.notifications.test.js
@@ -18,7 +18,6 @@ function freshHelper () {
     h.__socketNotifications.push({action, payload});
   };
   h.sendResponse = (_res, error, data) => { h.__responses.push({err: error, data}); };
-  h.checkInitialized = () => true;
   h.thisConfig = {};
   return h;
 }
diff --git a/tests/unit/socketNotification.test.js b/tests/unit/socketNotification.test.js
@@ -10,6 +10,27 @@ if (typeof ModuleLib._initPaths === "function") ModuleLib._initPaths();
 
 const helperFactory = require("../../node_helper.js");
 
+function wiredHelper () {
+  const helper = Object.create(helperFactory);
+  helper.__socketNotifications = [];
+  helper.__responses = [];
+  helper.waiting = [];
+  helper.initialized = false;
+  helper.configData = {};
+  helper.sendSocketNotification = (action, payload) => {
+    helper.__socketNotifications.push({action, payload});
+  };
+  helper.sendResponse = (_res, error, data) => {
+    helper.__responses.push({error, data});
+    return !error;
+  };
+  helper.callAfterUpdate = helperFactory.callAfterUpdate.bind(helper);
+  helper.requireLiveState = helperFactory.requireLiveState.bind(helper);
+  helper.handleGetBrightness = helperFactory.handleGetBrightness.bind(helper);
+  helper.socketNotificationReceived = helperFactory.socketNotificationReceived.bind(helper);
+  return helper;
+}
+
 function freshHelper () {
   const h = Object.create(helperFactory);
   h.__socketNotifications = [];
@@ -262,3 +283,23 @@ describe("socketNotificationReceived", () => {
     assert.ok(errorNotification.payload.includes("forced qrcode failure"));
   });
 });
+
+describe("self-healing initialization (regression)", () => {
+  test("an API request that arrives before any boot notification is served once the frontend answers the pull", () => {
+    const helper = wiredHelper();
+
+    // No DOM_OBJECTS_CREATED / CURRENT_STATUS has ever been received.
+    helper.handleGetBrightness({data: "brightness"}, {});
+
+    // The request must not fail permanently while state is still missing.
+    assert.equal(helper.__responses.length, 0, "request must not be answered before state arrives");
+
+    // The frontend answers the pull (even though it missed the boot broadcast).
+    helper.socketNotificationReceived("CURRENT_STATUS", {remoteConfig: {}, brightness: 42});
+
+    // The parked request is now served with the freshly pulled value.
+    assert.equal(helper.__responses.length, 1);
+    assert.equal(helper.__responses[0].error, undefined);
+    assert.equal(helper.__responses[0].data.result, 42);
+  });
+});
