Add ability to make the FE trigger automatic dashboard refresh by RobertJoonas · Pull Request #6442 · plausible/analytics

RobertJoonas · 2026-06-10T13:35:24Z

Changes

Resurrecting what was started in #5362.

Adds a new plug in the :internal_stats_api pipeline that adds an x-api-version response header. Incrementing the value will trigger an automatic refresh. The version string is defined in the plug itself, and the same value is also passed into the FE via a <meta> tag. Without the meta tag in the DOM, the frontend defaults to EXPECTED_API_VERSION = 0, which:

keeps the FE test suite working without having to worry about the api version
makes sure that dashboard does not refresh when this PR itself is deployed

Tests

Automated tests have been added

Changelog

This PR does not make a user-facing change

Documentation

This change does not need a documentation update

Dark mode

This PR does not change the UI

- extract fetchSuggestions into a separate module to break circular dependency - handle headers not existing in API response (no headers in tests)

github-actions · 2026-06-10T14:57:44Z

Preview environment👷🏼‍♀️🏗️
PR-6442

apata · 2026-06-11T08:19:18Z

+  def call(conn, _opts \\ nil) do
+    put_resp_header(conn, "x-api-version", @api_version)


suggestion, non-blocking: let's test that it's added to an internal stats endpoint like /query

apata · 2026-06-11T08:24:31Z

 }

 async function handleApiResponse(response: Response) {
+  const currentApiVersion = response.headers?.get('x-api-version')


nitpick, non-blocking: I think a separate utility like getCurrentApiVersion would be appropriate, next to other code related to this feature.

apata · 2026-06-11T08:25:05Z

 }

 async function handleApiResponse(response: Response) {
+  const currentApiVersion = response.headers?.get('x-api-version')


nitpick, non-blocking: when are response headers not defined?

In Jest tests. I figured the tests shouldn't have to worry about providing empty response headers just in order to make this work.

apata · 2026-06-11T08:26:08Z

+    currentApiVersion
+  )
+
+  console.log('API version mismatch detected, reloading...')


nitpick, non-blocking: the other redirect is notifying with console.warn

apata · 2026-06-11T08:27:32Z

 async function handleApiResponse(response: Response) {
+  const currentApiVersion = response.headers?.get('x-api-version')
+
+  if (currentApiVersion && currentApiVersion !== EXPECTED_API_VERSION) {


suggestion, non-blocking: if we move the checks into maybeReloadForApiVersion, it can be better unit tested. The args for it can be windowLocation and responseHeaders

apata · 2026-06-11T08:29:37Z

+  const currentApiVersion = response.headers?.get('x-api-version')
+
+  if (currentApiVersion && currentApiVersion !== EXPECTED_API_VERSION) {
+    maybeReloadForApiVersion(window.location, currentApiVersion)


issue, non-blocking: I think we should reload on idempotent requests only, not when updating segments etc.

apata · 2026-06-11T08:31:46Z

  getLabel,
  formattedFilters
 } from '../../util/filters'
+import { fetchSuggestions } from '../../util/fetch-suggestions'


question, blocking: is this change connected with the new feature?

Kind of. In api.ts, importing from url-search-params.ts created a circular dependency:

filters.js imports from api.ts

api.ts imports from url-search-params.ts (added in this PR)

url-search-params.ts imports from url-search-params-v1.ts

url-search-params-v1.ts imports from filters.js

This gets rid of it by eliminating the first -- make filters.js not rely on api.ts

apata · 2026-06-11T08:42:31Z

+ *
+ * BE: lib/plausible_web/plugs/internal_stats_api_version.ex
+ */
+export function maybeReloadForApiVersion(


issue, blocking: I think this must be unit tested quite extensively.

The FE makes multiple requests for data concurrently. The requests may hit different instances of the BE. During rolling deploys, the BE instances may report different API versions. What should happen?

I suggest we spec it out with a jest test suite that includes the concurrent requests during rolling deploys scenario.

I suspect we may need to set a flag that we're about to update to have deterministic behavior, e.g. at module level, let reloadingDueToApiVersionChange

During rolling deploys, the BE instances may report different API versions. What should happen?

Uff, yeah good catch! I feel like this is now turning into an infrastructure problem. So basically, a dashboard reload is useless until there's old code still around on at least one app server. We definitely don't want the dashboard to keep reloading itself until our deployment finishes.

I guess the version bump should happen separate from the code change then. I'm now thinking about storing the version in Postgres and bumping it via remote shell once all deployments have finished, maybe?

apata · 2026-06-11T08:52:54Z

+  )
+}
+
+function addOrReplaceSearch(


issue, blocking: This regex-based function is not encoding the value, so as a utility with such a general name, it's actually quite risky. Can we use the utils parseSearch and stringifySearch to create the new link?

RobertJoonas added 5 commits June 10, 2026 15:57

implement automatic reload

5ccbded

single source of truth: pass meta tag from the BE

39daaf1

improve naming

ea4de8d

add test

e4605f4

fix FE tests

a9a3686

- extract fetchSuggestions into a separate module to break circular dependency - handle headers not existing in API response (no headers in tests)

RobertJoonas added the preview label Jun 10, 2026

RobertJoonas requested a review from apata June 10, 2026 14:57

RobertJoonas changed the title ~~Add ability to trigger automatic dashboard refresh when api version gets outdated~~ Add ability to make the FE trigger automatic dashboard refresh Jun 10, 2026

RobertJoonas added 2 commits June 10, 2026 21:21

increase version to test on staging

a7dc873

works, revert version increase

b127ccf

zoldar reviewed Jun 11, 2026

View reviewed changes

Comment thread lib/plausible_web/plugs/internal_stats_api_version.ex

apata reviewed Jun 11, 2026

View reviewed changes

		def call(conn, _opts \\ nil) do
		put_resp_header(conn, "x-api-version", @api_version)

Uh oh!

Conversation

RobertJoonas commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Tests

Changelog

Documentation

Dark mode

Uh oh!

github-actions Bot commented Jun 10, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apata Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RobertJoonas Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

RobertJoonas commented Jun 10, 2026 •

edited

Loading

apata Jun 11, 2026 •

edited

Loading

RobertJoonas Jun 11, 2026 •

edited

Loading