Fixed stale Ghost(Pro) load errors (TryGhost#28108)

aileen · web-flow · commit 5bb46e4875b2 · 2026-05-25T04:31:57.000-04:00
ref [INC-284](https://app.incident.io/ghost/incidents/284) Hidden Billing iframe preload timeouts could set the same failure state and Sentry signal used for visible Ghost(Pro) opens, causing users to see a stale error before Admin made a fresh visible attempt. Split preload diagnostics from visible load failures, restart the monitor with a new attempt id when a user opens Billing, and pass `bmaAttemptId` through the iframe URL so future Billing lifecycle messages can be correlated without treating post-shell loading as an Admin failure.
diff --git a/ghost/admin/app/services/billing.js b/ghost/admin/app/services/billing.js
@@ -6,6 +6,9 @@ import {tracked} from '@glimmer/tracking';
 const BILLING_APP_LOAD_TIMEOUT_MS = 10_000;
 const BILLING_APP_LOAD_RETRY_DELAYS_MS = [1_000];
 const BILLING_APP_LOAD_FAILURE_MESSAGE = 'Billing app failed to become ready';
+const BILLING_APP_ATTEMPT_SOURCE_PRELOAD = 'preload';
+const BILLING_APP_ATTEMPT_SOURCE_USER_OPEN = 'user_open';
+const BILLING_APP_ATTEMPT_SOURCE_RETRY = 'retry';
 
 export default class BillingService extends Service {
     @service ghostPaths;
@@ -29,12 +32,17 @@ export default class BillingService extends Service {
     @tracked billingAppLastPreReadyMessageType = null;
     @tracked billingAppReadyReceivedAt = null;
     @tracked billingAppReadyPayload = null;
+    @tracked billingAppPreloadFailure = null;
 
     billingAppLoadTimeout = null;
     billingAppRetryTimeout = null;
     billingAppLoadAttempts = 0;
     billingAppLoadTimeoutMs = BILLING_APP_LOAD_TIMEOUT_MS;
     billingAppLoadRetryDelaysMs = BILLING_APP_LOAD_RETRY_DELAYS_MS;
+    billingAppLoadAttemptId = null;
+    billingAppLoadAttemptSource = BILLING_APP_ATTEMPT_SOURCE_PRELOAD;
+    billingAppIframeReloadReason = null;
+    billingAppLoadAttemptSequence = 0;
     billingAppIframeSrcSetAt = null;
     billingAppIframeLoadFired = false;
 
@@ -63,8 +71,11 @@ export default class BillingService extends Service {
         return this.getBillingIframe() !== null && this.getBillingIframe().contentWindow;
     }
 
-    startBillingAppLoadMonitor() {
+    startBillingAppLoadMonitor(options = {}) {
+        const {source = this.billingAppLoadAttemptSource} = options;
+
         if (this.billingAppLoadTimeout || this.billingAppRetryTimeout) {
+            this.billingAppLoadAttemptSource = source;
             return;
         }
 
@@ -75,6 +86,7 @@ export default class BillingService extends Service {
             this.resetBillingAppLoadDiagnostics();
         }
 
+        this.billingAppLoadAttemptSource = source;
         this.billingAppLoadAttempts += 1;
         this.billingAppLoadTimeout = setTimeout(() => {
             this.billingAppLoadTimeout = null;
@@ -88,45 +100,58 @@ export default class BillingService extends Service {
         if (retryDelay !== undefined) {
             this.billingAppRetryTimeout = setTimeout(() => {
                 this.billingAppRetryTimeout = null;
-                this.reloadBillingIframe();
-                this.startBillingAppLoadMonitor();
+                const source = this.billingWindowOpen ? BILLING_APP_ATTEMPT_SOURCE_RETRY : this.billingAppLoadAttemptSource;
+
+                this.reloadBillingIframe({source, reloadReason: 'timeout_retry'});
+                this.startBillingAppLoadMonitor({source});
             }, retryDelay);
             return;
         }
 
         this.reportBillingAppLoadFailure();
     }
 
-    setBillingIframeSrc() {
+    setBillingIframeSrc(options = {}) {
         const iframe = this.getBillingIframe();
         if (!iframe) {
             return;
         }
+
+        const {
+            source = this.billingAppLoadAttemptSource || BILLING_APP_ATTEMPT_SOURCE_PRELOAD,
+            reloadReason = 'set_src'
+        } = options;
+
         if (this._loadListenerAttachedTo !== iframe && typeof iframe.addEventListener === 'function') {
             iframe.addEventListener('load', () => {
                 this.billingAppIframeLoadFired = true;
             });
             this._loadListenerAttachedTo = iframe;
         }
+        this.billingAppLoadAttemptSequence += 1;
+        this.billingAppLoadAttemptId = `${Date.now()}-${this.billingAppLoadAttemptSequence}`;
+        this.billingAppLoadAttemptSource = source;
+        this.billingAppIframeReloadReason = reloadReason;
         this.billingAppIframeLoadFired = false;
         this.billingAppIframeSrcSetAt = Date.now();
         this.resetBillingAppLoadDiagnostics();
         iframe.src = this.getIframeURL();
     }
 
-    reloadBillingIframe() {
+    reloadBillingIframe(options = {}) {
         const iframe = this.getBillingIframe();
 
         if (!iframe || this.billingAppLoaded) {
             return;
         }
 
-        this.setBillingIframeSrc();
+        this.setBillingIframeSrc(options);
     }
 
     markBillingAppLoaded(payload = null) {
         this.billingAppLoaded = true;
         this.billingAppLoadFailureReported = false;
+        this.billingAppPreloadFailure = null;
         this.billingAppReadyReceivedAt = Date.now();
         this.billingAppReadyPayload = payload;
         this.clearBillingAppLoadMonitor();
@@ -232,11 +257,51 @@ export default class BillingService extends Service {
         }
     }
 
+    ensureBillingAppReadyForVisibleUse() {
+        if (this.billingAppLoaded) {
+            return;
+        }
+
+        const hadPreloadFailure = !!this.billingAppPreloadFailure;
+        const hadVisibleFailure = this.billingAppLoadFailureReported;
+
+        this.billingAppLoadFailureReported = false;
+        this.clearBillingAppLoadMonitor();
+        this.billingAppLoadAttempts = 0;
+
+        if (hadPreloadFailure || hadVisibleFailure) {
+            this.reloadBillingIframe({
+                source: BILLING_APP_ATTEMPT_SOURCE_USER_OPEN,
+                reloadReason: hadPreloadFailure ? 'visible_open_after_preload_failure' : 'visible_open_after_load_failure'
+            });
+        } else {
+            this.billingAppLoadAttemptSource = BILLING_APP_ATTEMPT_SOURCE_USER_OPEN;
+        }
+
+        this.startBillingAppLoadMonitor({source: BILLING_APP_ATTEMPT_SOURCE_USER_OPEN});
+    }
+
+    recordBillingAppPreloadFailure() {
+        this.billingAppPreloadFailure = {
+            attemptId: this.billingAppLoadAttemptId,
+            attempts: this.billingAppLoadAttempts,
+            elapsedMs: this.billingAppIframeSrcSetAt ? Date.now() - this.billingAppIframeSrcSetAt : null,
+            nonReadyMessageCount: this.billingAppPreReadyMessageCount,
+            nonReadyMessageTypes: [...this.billingAppPreReadyMessageTypes],
+            lastNonReadyMessageType: this.billingAppLastPreReadyMessageType
+        };
+    }
+
     reportBillingAppLoadFailure() {
         if (this.billingAppLoadFailureReported) {
             return;
         }
 
+        if (!this.billingWindowOpen) {
+            this.recordBillingAppPreloadFailure();
+            return;
+        }
+
         this.billingAppLoadFailureReported = true;
 
         if (!this.config.sentry_dsn) {
@@ -287,6 +352,10 @@ export default class BillingService extends Service {
                 ghost: {
                     billing_monitor: {
                         attempts: this.billingAppLoadAttempts,
+                        attempt_id: this.billingAppLoadAttemptId,
+                        attempt_source: this.billingAppLoadAttemptSource,
+                        attempt_phase: 'shell_ready',
+                        iframe_reload_reason: this.billingAppIframeReloadReason,
                         has_billing_url: !!this.config.hostSettings?.billing?.url,
                         is_force_upgrade: !!this.config.hostSettings?.forceUpgrade,
                         location_hash: window.location.hash,
@@ -304,6 +373,11 @@ export default class BillingService extends Service {
                         non_ready_message_count: this.billingAppPreReadyMessageCount,
                         non_ready_message_types: this.billingAppPreReadyMessageTypes.join(','),
                         last_non_ready_message_type: this.billingAppLastPreReadyMessageType,
+                        has_preload_failure: !!this.billingAppPreloadFailure,
+                        preload_failure_elapsed_ms: this.billingAppPreloadFailure?.elapsedMs ?? null,
+                        preload_non_ready_message_count: this.billingAppPreloadFailure?.nonReadyMessageCount ?? null,
+                        preload_non_ready_message_types: this.billingAppPreloadFailure?.nonReadyMessageTypes?.join(',') ?? null,
+                        preload_last_non_ready_message_type: this.billingAppPreloadFailure?.lastNonReadyMessageType ?? null,
                         ready_received: false,
                         navigator_online: navigator.onLine,
                         connection_effective_type: navigator.connection?.effectiveType ?? null,
@@ -316,6 +390,8 @@ export default class BillingService extends Service {
             },
             tags: {
                 source: 'billing-app-load-monitor',
+                attempt_source: this.billingAppLoadAttemptSource,
+                attempt_phase: 'shell_ready',
                 route: this.router.currentRouteName,
                 path: window.location.hash
             }
@@ -340,7 +416,21 @@ export default class BillingService extends Service {
             }
         }
 
-        return url;
+        return this.addBillingAppAttemptIdToURL(url);
+    }
+
+    addBillingAppAttemptIdToURL(url) {
+        if (!url || !this.billingAppLoadAttemptId) {
+            return url;
+        }
+
+        try {
+            const billingUrl = new URL(url);
+            billingUrl.searchParams.set('bmaAttemptId', this.billingAppLoadAttemptId);
+            return billingUrl.toString();
+        } catch (e) {
+            return url;
+        }
     }
 
     async getOwnerUser() {
@@ -398,6 +488,10 @@ export default class BillingService extends Service {
         this.sendRouteUpdate();
 
         this.billingWindowOpen = value;
+
+        if (value) {
+            this.ensureBillingAppReadyForVisibleUse();
+        }
     }
 
     // Controls navigation to billing window modal which is triggered from the application UI.
diff --git a/ghost/admin/tests/integration/components/gh-billing-modal-test.js b/ghost/admin/tests/integration/components/gh-billing-modal-test.js
@@ -102,6 +102,17 @@ describe('Integration: Component: gh-billing-modal', function () {
         expect(find('[data-test-billing-load-error-description] a')).to.have.attribute('href', 'mailto:support@ghost.org');
     });
 
+    it('keeps showing the loading state for hidden preload diagnostics', async function () {
+        billing.billingAppPreloadFailure = {
+            attemptId: 'preload-attempt'
+        };
+
+        await render(hbs`<GhBillingModal @billingWindowOpen={{true}} />`);
+
+        expect(find('[data-test-billing-loading]')).to.exist;
+        expect(find('[data-test-billing-load-error]')).to.not.exist;
+    });
+
     it('clears a reported error when the billing app sends a late message', async function () {
         billing.billingAppLoadFailureReported = true;
 
diff --git a/ghost/admin/tests/unit/services/billing-test.js b/ghost/admin/tests/unit/services/billing-test.js
@@ -101,14 +101,108 @@ describe('Unit: Service: billing', function () {
         expect(iframe.src).to.equal('https://billing.example.test/pro');
     });
 
+    it('adds the active attempt id to the billing iframe URL', function () {
+        const service = this.owner.lookup('service:billing');
+        billingService = service;
+        service.billingAppLoadAttemptId = 'attempt-123';
+
+        expect(service.getIframeURL({fetchOwner: false})).to.equal('https://billing.example.test/?bmaAttemptId=attempt-123');
+    });
+
+    it('records hidden preload timeout without reporting a visible failure', async function () {
+        const service = this.owner.lookup('service:billing');
+        billingService = service;
+        service.billingAppLoadTimeoutMs = 1;
+        service.billingAppLoadRetryDelaysMs = [];
+        service.billingAppIframeSrcSetAt = Date.now() - 100;
+
+        service.startBillingAppLoadMonitor();
+
+        await waitUntil(() => service.billingAppPreloadFailure);
+
+        expect(service.billingAppLoadFailureReported).to.be.false;
+        expect(service.billingAppPreloadFailure).to.deep.include({
+            attempts: 1,
+            nonReadyMessageCount: 0,
+            lastNonReadyMessageType: null
+        });
+        expect(testkit.reports()).to.have.lengthOf(0);
+    });
+
+    it('promotes an in-flight preload attempt when the user opens billing', function () {
+        const service = this.owner.lookup('service:billing');
+        billingService = service;
+        service.billingAppLoadTimeoutMs = 1000;
+        const reloadBillingIframe = sinon.spy(service, 'reloadBillingIframe');
+
+        service.startBillingAppLoadMonitor();
+        service.toggleProWindow(true);
+
+        expect(service.billingWindowOpen).to.be.true;
+        expect(service.billingAppLoadAttemptSource).to.equal('user_open');
+        expect(service.billingAppLoadAttempts).to.equal(1);
+        expect(service.billingAppLoadTimeout).to.not.be.null;
+        expect(reloadBillingIframe.called).to.be.false;
+    });
+
+    it('reloads the iframe for a fresh visible attempt after preload failed', function () {
+        const service = this.owner.lookup('service:billing');
+        billingService = service;
+        const iframe = {src: '', addEventListener: sinon.stub()};
+        sinon.stub(service, 'getBillingIframe').returns(iframe);
+        service.billingAppPreloadFailure = {
+            attemptId: 'preload-attempt',
+            attempts: 2,
+            elapsedMs: 12000,
+            nonReadyMessageCount: 1,
+            nonReadyMessageTypes: ['token']
+        };
+
+        service.toggleProWindow(true);
+
+        expect(service.billingWindowOpen).to.be.true;
+        expect(service.billingAppLoadFailureReported).to.be.false;
+        expect(service.billingAppLoadAttemptSource).to.equal('user_open');
+        expect(service.billingAppIframeReloadReason).to.equal('visible_open_after_preload_failure');
+        expect(service.billingAppLoadTimeout).to.not.be.null;
+        expect(iframe.src).to.match(/^https:\/\/billing\.example\.test\/\?bmaAttemptId=/);
+    });
+
+    it('reloads the iframe for a fresh visible attempt after a previous visible failure', function () {
+        const service = this.owner.lookup('service:billing');
+        billingService = service;
+        const iframe = {src: '', addEventListener: sinon.stub()};
+        sinon.stub(service, 'getBillingIframe').returns(iframe);
+        service.billingAppLoadFailureReported = true;
+
+        service.toggleProWindow(true);
+
+        expect(service.billingWindowOpen).to.be.true;
+        expect(service.billingAppLoadFailureReported).to.be.false;
+        expect(service.billingAppIframeReloadReason).to.equal('visible_open_after_load_failure');
+        expect(service.billingAppLoadTimeout).to.not.be.null;
+        expect(iframe.src).to.match(/^https:\/\/billing\.example\.test\/\?bmaAttemptId=/);
+    });
+
     it('reports to Sentry with diagnostics when the billing app does not become ready', async function () {
         const service = this.owner.lookup('service:billing');
         billingService = service;
         sinon.stub(service, 'getBillingIframe').returns(null);
         service.billingAppLoadAttempts = 2;
+        service.billingAppLoadAttemptId = 'attempt-123';
+        service.billingAppLoadAttemptSource = 'user_open';
+        service.billingAppIframeReloadReason = 'visible_open_after_preload_failure';
         service.billingAppIframeSrcSetAt = Date.now() - 1234;
         service.billingAppIframeLoadFired = true;
         service.billingWindowOpen = true;
+        service.billingAppPreloadFailure = {
+            attemptId: 'preload-attempt',
+            attempts: 2,
+            elapsedMs: 12000,
+            nonReadyMessageCount: 1,
+            nonReadyMessageTypes: ['token'],
+            lastNonReadyMessageType: 'token'
+        };
 
         service.reportBillingAppLoadFailure();
 
@@ -127,12 +221,21 @@ describe('Unit: Service: billing', function () {
         const billingMonitor = report.originalReport.contexts.ghost.billing_monitor;
         expect(billingMonitor).to.deep.include({
             attempts: 2,
+            attempt_id: 'attempt-123',
+            attempt_source: 'user_open',
+            attempt_phase: 'shell_ready',
+            iframe_reload_reason: 'visible_open_after_preload_failure',
             has_billing_url: true,
             is_force_upgrade: false,
             iframe_src: null,
             configured_billing_origin: 'https://billing.example.test',
             iframe_load_fired: true,
             billing_window_open: true,
+            has_preload_failure: true,
+            preload_failure_elapsed_ms: 12000,
+            preload_non_ready_message_count: 1,
+            preload_non_ready_message_types: 'token',
+            preload_last_non_ready_message_type: 'token',
             non_ready_message_count: 0,
             non_ready_message_types: '',
             last_non_ready_message_type: null,
@@ -144,12 +247,18 @@ describe('Unit: Service: billing', function () {
             bma_boot_threw: false
         });
         expect(billingMonitor.ms_since_src_set).to.be.a('number').and.to.be.at.least(1234);
+        expect(report.tags).to.deep.include({
+            attempt_source: 'user_open',
+            attempt_phase: 'shell_ready'
+        });
     });
 
     it('reports pre-ready message diagnostics to Sentry', async function () {
         const service = this.owner.lookup('service:billing');
         billingService = service;
         sinon.stub(service, 'getBillingIframe').returns(null);
+        service.billingWindowOpen = true;
+        service.billingAppLoadAttemptSource = 'user_open';
         service.billingAppLoadAttempts = 2;
         service.billingAppLoadTimeout = setTimeout(() => {}, 10000);
         service.billingAppIframeSrcSetAt = Date.now() - 100;
