Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Improved Data App dev plugin to handle buildId to prevent diagnostic endpoint poisoning of data frop previous HMR builds (#79447)

Timofey Kachalovb918b9e5f45e
diff --git a/e2e/test-host-app/data-apps/data-app-dev-diagnostics.cy.spec.ts b/e2e/test-host-app/data-apps/data-app-dev-diagnostics.cy.spec.ts
index 9e1550b83b8..f411c7719f2 100644
--- a/e2e/test-host-app/data-apps/data-app-dev-diagnostics.cy.spec.ts
+++ b/e2e/test-host-app/data-apps/data-app-dev-diagnostics.cy.spec.ts
@@ -135,6 +135,16 @@ describe("Embedding SDK: data-app dev diagnostics", () => {
(report) =>
report.entries.some((entry) => entry.kind === "blocked-network"),
).then((before) => {
+ // The first page goes on reporting past this snapshot — its reporter
+ // batches, and the blocked entry waited for above lands while the app's
+ // requests are still in flight. So "the buffer grew" does not mean the
+ // reloaded page has said anything yet; a batch from the page about to
+ // be replaced grows it too. Wait for a session this snapshot has never
+ // seen instead.
+ const sessionsBefore = new Set(
+ before.entries.map((entry) => entry.sessionId),
+ );
+
cy.reload();
cy.findByTestId("dev-app-content", { timeout: TIMEOUT_MS }).should(
"exist",
@@ -146,8 +156,11 @@ describe("Embedding SDK: data-app dev diagnostics", () => {
// consumed up to N never skips or re-reads anything.
readDiagnosticsUntil(
DIAGNOSTICS_URL,
- "the reloaded page's events appended after the first session's",
- (report) => report.entries.length > before.entries.length,
+ "the reloaded page's own events appended after the first session's",
+ (report) =>
+ report.entries.some(
+ (entry) => !sessionsBefore.has(entry.sessionId),
+ ),
).then((after) => {
const beforeIds = before.entries.map((entry) => entry.eventId);
const afterIds = after.entries.map((entry) => entry.eventId);
@@ -333,5 +346,51 @@ describe("Embedding SDK: data-app dev diagnostics", () => {
);
});
});
+
+ it("withholds what a build reported once a rebuild has replaced it", () => {
+ visitDataAppDevApp(CLIENT_HOST);
+
+ cy.findByTestId("dev-app-error-probe").click();
+ readDiagnosticsUntil(
+ DIAGNOSTICS_URL,
+ "the probe error under the build that is running",
+ (report) =>
+ report.entries.some(
+ (entry) => entry.summary === "dev-app probe error",
+ ),
+ );
+
+ cy.writeFile(
+ DATA_APP_DEV_APP_SRC_PATH,
+ originalAppSrc.replace("Vite 6 data app", "Vite 6 data app — rebuilt"),
+ );
+ cy.findByTestId("dev-app-content")
+ .findByText("Vite 6 data app — rebuilt", { timeout: TIMEOUT_MS })
+ .should("be.visible");
+
+ // A mid-edit save is how the buffer fills with failures of code the
+ // preview has already dropped. The rebuild re-ran the app from scratch
+ // and nothing re-reported the probe error, so the default read is about
+ // the bundle that is actually running.
+ readDiagnosticsUntil(
+ DIAGNOSTICS_URL,
+ "the previous build's entries withheld",
+ (report) =>
+ report.staleEntries > 0 &&
+ report.entries.every(
+ (entry) => entry.summary !== "dev-app probe error",
+ ),
+ );
+
+ // Withheld, not dropped: a reader comparing what a change fixed asks for
+ // them and gets them back.
+ cy.request(`${DIAGNOSTICS_URL}?includeStale=true`)
+ .its("body.entries")
+ .then((entries: { summary: string }[]) => {
+ expect(entries.map((entry) => entry.summary)).to.include(
+ "dev-app probe error",
+ );
+ });
+ });
});
});
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev-entry.tsx b/enterprise/frontend/src/embedding-sdk-package/data-app-dev-entry.tsx
index a9f324bc841..92519883551 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev-entry.tsx
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev-entry.tsx
@@ -18,6 +18,7 @@ import {
import {
allowedHosts,
appSlug,
+ buildIdHeader,
bundleUrl,
diagnosticsChangedEvent,
rebuiltEvent,
@@ -98,6 +99,12 @@ async function loadAndRender() {
}
const code = await res.text();
+
+ // From here on, everything the app reports belongs to this bundle generation.
+ // Without the stamp a reader can't tell a live failure from one an earlier,
+ // half-finished edit left in the dev server's buffer.
+ devDiagnostics.setBuildId(Number(res.headers.get(buildIdHeader)));
+
const { component: Component, providerProps } = sandbox.evaluate(code)();
const rawProviderProps = providerProps ?? {};
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/DevToolbar.unit.spec.tsx b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/DevToolbar.unit.spec.tsx
index da84fe973bf..e5b649b4d9b 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/DevToolbar.unit.spec.tsx
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/DevToolbar.unit.spec.tsx
@@ -23,6 +23,7 @@ const entry = (
eventId: 1,
sessionId: DEV_SESSION_ID,
time: Date.parse("2026-01-01T10:00:00Z"),
+ buildId: 1,
kind: "error",
summary: "boom",
detail: null,
@@ -42,6 +43,8 @@ const serve = (
clients: 1,
lastReportAt: 1,
lastRebuildAt: 1,
+ buildId: 1,
+ staleEntries: 0,
nextEventId: (entries.at(-1)?.eventId ?? 0) + 1,
sessionId: "page-1",
...overrides,
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.ts
index 07989090b69..11f65e61c93 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.ts
@@ -19,6 +19,7 @@ export class DevDiagnosticsCollector {
private entries: DevDiagnosticEntry[] = [];
private connectionStatus: InstanceConnectionStatus | null = null;
private nextEntryId = 1;
+ private buildId: number | null = null;
private uncapturedConsoleError: typeof console.error | null = null;
private readonly listeners = new Set<() => void>();
@@ -63,10 +64,15 @@ export class DevDiagnosticsCollector {
});
}
+ setBuildId(buildId: number): void {
+ this.buildId = Number.isFinite(buildId) && buildId > 0 ? buildId : null;
+ }
+
record(event: DevDiagnosticEvent): void {
const newEntry = {
id: this.nextEntryId++,
time: Date.now(),
+ buildId: this.buildId,
...this.truncateEventText(event),
};
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.unit.spec.ts
index eacd45e04a6..da6f9e40694 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.unit.spec.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/components/DevToolbar/diagnostics.unit.spec.ts
@@ -316,3 +316,50 @@ describe("bounded entry size", () => {
expect(message).toContain("truncated");
});
});
+
+describe("build stamping", () => {
+ // The collector is a singleton, so an id set here would follow the module
+ // into every later test.
+ afterEach(() => devDiagnostics.setBuildId(0));
+
+ it("stamps entries with the bundle generation that was loaded", () => {
+ devDiagnostics.setBuildId(2);
+ console.error("from build two");
+
+ // What lets a reader drop errors an earlier, half-finished edit produced
+ // without dropping the ones the app is failing with now.
+ expect(getLastEntry(devDiagnostics.getEntries()).buildId).toBe(2);
+ });
+
+ it("re-stamps as the preview rebuilds", () => {
+ devDiagnostics.setBuildId(2);
+ console.error("from build two");
+ devDiagnostics.setBuildId(3);
+ console.error("from build three");
+
+ expect(devDiagnostics.getEntries().map((entry) => entry.buildId)).toEqual([
+ 2, 3,
+ ]);
+ });
+
+ it("leaves entries unstamped until a bundle has loaded", () => {
+ console.error("thrown by the preview page itself");
+
+ // Nothing about the app's own code, so no build owns it: it stays visible
+ // however many times the bundle is rebuilt.
+ expect(getLastEntry(devDiagnostics.getEntries()).buildId).toBeNull();
+ });
+
+ it("treats a missing or unbuilt id as no build at all", () => {
+ // `Number(null)` for an absent response header, and 0 from a dev server
+ // that has not finished a build — neither may pass as a real generation,
+ // or every entry would be filtered as stale.
+ devDiagnostics.setBuildId(Number.NaN);
+ console.error("no header");
+ expect(getLastEntry(devDiagnostics.getEntries()).buildId).toBeNull();
+
+ devDiagnostics.setBuildId(0);
+ console.error("nothing built yet");
+ expect(getLastEntry(devDiagnostics.getEntries()).buildId).toBeNull();
+ });
+});
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/bundle.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/bundle.ts
index a7f85b8fdb0..2406596247b 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/bundle.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/bundle.ts
@@ -10,3 +10,5 @@ export const DATA_APP_ENTRY = "src/index.tsx";
export const DATA_APP_BUNDLE_URL = "/@data-app-bundle.js";
export const DATA_APP_REBUILT_EVENT = "data-app:rebuilt";
+
+export const DATA_APP_BUILD_ID_HEADER = "x-data-app-build-id";
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/diagnostics-channel.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/diagnostics-channel.ts
index b82426c12d1..b14966d353d 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/diagnostics-channel.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/constants/diagnostics-channel.ts
@@ -7,6 +7,8 @@ export const DATA_APP_DIAGNOSTICS_URL = "/__data-app/diagnostics";
export const START_EVENT_ID_PARAM = "startEventId";
+export const INCLUDE_STALE_PARAM = "includeStale";
+
export const DATA_APP_DIAGNOSTICS_LIMIT = 200;
// Requests outrun every other kind by orders of magnitude, so under one shared
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.ts
index 09106ca4a53..209d9f577f5 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.ts
@@ -14,6 +14,7 @@ export interface AppBundle {
rebuild: () => Promise<boolean>;
readonly code: string;
readonly lastRebuildAt: number | null;
+ readonly buildId: number;
}
export function createAppBundle({
@@ -23,6 +24,7 @@ export function createAppBundle({
}: AppBundleOptions): AppBundle {
let code = "";
let lastRebuildAt: number | null = null;
+ let buildId = 0;
let building = false;
let stale = false;
@@ -54,6 +56,7 @@ export function createAppBundle({
?.code ?? "";
lastRebuildAt = Date.now();
+ buildId += 1;
return true;
} catch (error) {
@@ -96,5 +99,9 @@ export function createAppBundle({
get lastRebuildAt() {
return lastRebuildAt;
},
+
+ get buildId() {
+ return buildId;
+ },
};
}
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.unit.spec.ts
index 6b503281b43..669d57fa03e 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.unit.spec.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/app-bundle.unit.spec.ts
@@ -103,4 +103,29 @@ describe("createAppBundle", () => {
it("holds no code until something is built", () => {
expect(setup().code).toBe("");
});
+
+ it("numbers each successful build, so entries can be tied to one", () => {
+ const bundle = setup();
+
+ // 0 is "nothing built yet", which the page treats as no build at all.
+ expect(bundle.buildId).toBe(0);
+ });
+
+ it("advances the number only when a build succeeds", async () => {
+ const bundle = setup();
+
+ await bundle.rebuild();
+ expect(bundle.buildId).toBe(1);
+
+ mockedBuild.mockRejectedValue(new Error("nope"));
+ await bundle.rebuild();
+
+ // A failed build changes nothing the preview runs — it keeps evaluating
+ // the last good bundle, so its entries stay current.
+ expect(bundle.buildId).toBe(1);
+
+ mockedBuild.mockResolvedValue(rollupOutput("built again"));
+ await bundle.rebuild();
+ expect(bundle.buildId).toBe(2);
+ });
});
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/diagnostics-store.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/diagnostics-store.unit.spec.ts
index ca01445713a..0bf5c700182 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/diagnostics-store.unit.spec.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/diagnostics-store.unit.spec.ts
@@ -10,6 +10,7 @@ const entry = (
over: Partial<DataAppDiagnosticEntry> = {},
): DataAppDiagnosticEntry => ({
time: 1700000000000,
+ buildId: 1,
kind: "error",
summary: "boom",
detail: null,
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/app-bundle-middleware.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/app-bundle-middleware.ts
index 597b65d090e..951105f1481 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/app-bundle-middleware.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/app-bundle-middleware.ts
@@ -1,6 +1,9 @@
import type { Connect } from "vite";
-import { DATA_APP_BUNDLE_URL } from "../../constants/bundle";
+import {
+ DATA_APP_BUILD_ID_HEADER,
+ DATA_APP_BUNDLE_URL,
+} from "../../constants/bundle";
import type { AppBundle } from "../app-bundle";
/** Serves the in-memory app bundle the sandbox fetches and evaluates. */
@@ -22,5 +25,6 @@ export const getAppBundleMiddleware =
}
res.setHeader("Content-Type", "text/javascript");
+ res.setHeader(DATA_APP_BUILD_ID_HEADER, String(bundle.buildId));
res.end(bundle.code);
};
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/diagnostics-endpoint-middleware.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/diagnostics-endpoint-middleware.ts
index 02596ebb4dd..ad9c9a9fa54 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/diagnostics-endpoint-middleware.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/middlewares/diagnostics-endpoint-middleware.ts
@@ -2,9 +2,11 @@ import type { Connect } from "vite";
import {
DATA_APP_DIAGNOSTICS_URL,
+ INCLUDE_STALE_PARAM,
START_EVENT_ID_PARAM,
} from "../../constants/diagnostics-channel";
import type {
+ DataAppDiagnosticPayload,
DataAppDiagnosticsMessage,
DataAppDiagnosticsReport,
} from "../../types/diagnostics-channel";
@@ -16,6 +18,7 @@ export interface DiagnosticsEndpointMiddlewareOptions {
getManifest: () => DataAppManifestStatus | null;
getClients: () => number;
getLastRebuildAt: () => number | null;
+ getBuildId: () => number;
notifyChanged: () => void;
}
@@ -34,10 +37,37 @@ const readJsonBody = async (req: Connect.IncomingMessage): Promise<unknown> => {
}
};
+/**
+ * Whether a later build has replaced the code this entry came from.
+ *
+ * Every save rebuilds, and a multi-step edit passes through builds that don't
+ * compile or don't run, so the buffer fills with failures of code the preview
+ * no longer runs. Withholding those is safe because a rebuild re-evaluates the
+ * bundle and remounts the app from scratch: anything still broken is reported
+ * again under the current build, and anything not reported again was fixed by
+ * the edit.
+ *
+ * Only *older* generations count. An entry stamped ahead of the server's
+ * counter comes from a page still running a bundle from before a dev-server
+ * restart — nothing has replaced it, and dropping it would blind the reader to
+ * a preview that is failing right now.
+ */
+const isSupersededByBuild = (
+ entry: DataAppDiagnosticPayload,
+ buildId: number,
+): boolean => entry.buildId != null && entry.buildId < buildId;
+
+// `?includeStale`, `=true` and `=1` all opt in; only an explicit false/0 does
+// not — a reader who bothered to add the param meant to see everything.
+const isFlagSet = (value: string | null): boolean =>
+ value !== null && value !== "false" && value !== "0";
+
/**
* The `DATA_APP_DIAGNOSTICS_URL` endpoint: `GET` serves the feed (from
- * `?startEventId=` onward), `POST` takes the page reporter's batches, `DELETE`
- * empties the feed. Mutations broadcast a changed-event so readers re-read.
+ * `?startEventId=` onward, withholding what a later build superseded unless
+ * `?includeStale` opts in — bare, `=true` or `=1`), `POST` takes the page
+ * reporter's batches, `DELETE` empties the feed. Mutations broadcast a
+ * changed-event so readers re-read.
*/
export const getDiagnosticsEndpointMiddleware =
({
@@ -45,6 +75,7 @@ export const getDiagnosticsEndpointMiddleware =
getManifest,
getClients,
getLastRebuildAt,
+ getBuildId,
notifyChanged,
}: DiagnosticsEndpointMiddlewareOptions): Connect.NextHandleFunction =>
async (req, res, next) => {
@@ -96,15 +127,24 @@ export const getDiagnosticsEndpointMiddleware =
return;
}
- const startEventId = Number(
- new URLSearchParams(query).get(START_EVENT_ID_PARAM),
- );
+ const params = new URLSearchParams(query);
+ const startEventId = Number(params.get(START_EVENT_ID_PARAM));
+ const includeStale = isFlagSet(params.get(INCLUDE_STALE_PARAM));
+
+ const buildId = getBuildId();
+ const stored = store.getReport(startEventId);
+ const entries = includeStale
+ ? stored.entries
+ : stored.entries.filter((entry) => !isSupersededByBuild(entry, buildId));
const report: DataAppDiagnosticsReport = {
- ...store.getReport(startEventId),
+ ...stored,
+ entries,
+ staleEntries: stored.entries.length - entries.length,
manifest: getManifest(),
clients: getClients(),
lastRebuildAt: getLastRebuildAt(),
+ buildId,
};
res.setHeader("Content-Type", "application/json");
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.ts
index 62ecd93a361..5817ad0d429 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.ts
@@ -47,6 +47,7 @@ export function dataAppSandboxDevPlugin(
getManifest: () => validateDataAppManifest(root, allowedHosts),
getClients: () => server.ws.clients.size,
getLastRebuildAt: () => bundle.lastRebuildAt,
+ getBuildId: () => bundle.buildId,
notifyChanged: () =>
server.ws.send({
type: "custom",
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.unit.spec.ts
index 6079d0dcca9..f4e36e9b1fa 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.unit.spec.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/plugin.unit.spec.ts
@@ -617,6 +617,140 @@ describe("dataAppSandboxDevPlugin", () => {
const { body } = await server.request(DATA_APP_DIAGNOSTICS_URL);
expect(body.entries).toEqual([]);
});
+
+ describe("entries an earlier build left behind", () => {
+ // Every save rebuilds, so a multi-step edit runs through builds that
+ // throw. Those errors describe code the preview has already replaced.
+ const rebuild = (server: FakeDevServer) =>
+ server.watcher.emit("all", "change", "/app/src/App.tsx");
+
+ it("serves the current build's entries and withholds the rest", async () => {
+ const { server } = await setup();
+ await report(server, [{ summary: "mid-edit crash", buildId: 1 }]);
+
+ await rebuild(server);
+ await report(server, [{ summary: "still crashing", buildId: 2 }]);
+
+ const { body } = await server.request(DATA_APP_DIAGNOSTICS_URL);
+
+ // A rebuild re-evaluates the bundle and remounts the app, so
+ // whatever is still wrong reports itself again under build 2 — and
+ // what doesn't was fixed by the edit that triggered the rebuild.
+ expect(
+ body.entries.map((entry: { summary: string }) => entry.summary),
+ ).toEqual(["still crashing"]);
+ expect(body.buildId).toBe(2);
+ expect(body.staleEntries).toBe(1);
+ });
+
+ it("keeps entries no build owns", async () => {
+ const { server } = await setup();
+ await report(server, [
+ { summary: "the preview page itself failed", buildId: null },
+ ]);
+
+ await rebuild(server);
+
+ // Recorded before any bundle loaded — a rebuild neither re-runs nor
+ // disproves it, so hiding it would lose the report for good.
+ const { body } = await server.request(DATA_APP_DIAGNOSTICS_URL);
+ expect(body.entries).toHaveLength(1);
+ expect(body.staleEntries).toBe(0);
+ });
+
+ it("keeps entries stamped ahead of the server's own counter", async () => {
+ const { server } = await setup();
+ await report(server, [
+ { summary: "from before the restart", buildId: 9 },
+ ]);
+
+ // A dev-server restart begins counting again while an open preview
+ // keeps running the bundle it already has. Nothing replaced that
+ // code, so its failures are as live as any.
+ const { body } = await server.request(DATA_APP_DIAGNOSTICS_URL);
+ expect(body.entries).toHaveLength(1);
+ expect(body.staleEntries).toBe(0);
+ });
+
+ it("keeps entries from a page that stamps nothing", async () => {
+ const { server } = await setup();
+ await report(server, [{ summary: "boom" }]);
+
+ await rebuild(server);
+
+ // An older dev entry reports without a build id. Filtering those out
+ // would empty the feed of a preview that is genuinely broken.
+ expect(
+ (await server.request(DATA_APP_DIAGNOSTICS_URL)).body.entries,
+ ).toHaveLength(1);
+ });
+
+ it("hands back everything for a reader that asks", async () => {
+ const { server } = await setup();
+ await report(server, [{ summary: "mid-edit crash", buildId: 1 }]);
+ await rebuild(server);
+
+ for (const query of [
+ "?includeStale",
+ "?includeStale=true",
+ "?includeStale=1",
+ ]) {
+ const { body } = await server.request(
+ `${DATA_APP_DIAGNOSTICS_URL}${query}`,
+ );
+
+ expect(body.entries).toHaveLength(1);
+ expect(body.staleEntries).toBe(0);
+ }
+
+ // Spelling out false is the one way to ask and still be filtered.
+ const { body } = await server.request(
+ `${DATA_APP_DIAGNOSTICS_URL}?includeStale=false`,
+ );
+ expect(body.entries).toEqual([]);
+ });
+
+ it("counts only what the cursor would have shown", async () => {
+ const { server } = await setup();
+ await report(server, [
+ { summary: "read already", buildId: 1 },
+ { summary: "read already too", buildId: 1 },
+ ]);
+ const cursor = (await server.request(DATA_APP_DIAGNOSTICS_URL)).body
+ .nextEventId;
+
+ await rebuild(server);
+ await report(server, [{ summary: "old news", buildId: 1 }]);
+
+ // Reporting entries the reader consumed before its cursor moved
+ // would make a clean feed look like it was hiding a pile.
+ const { body } = await server.request(
+ `${DATA_APP_DIAGNOSTICS_URL}?startEventId=${cursor}`,
+ );
+ expect(body.entries).toEqual([]);
+ expect(body.staleEntries).toBe(1);
+ });
+
+ it("names the build it serves on the bundle itself", async () => {
+ const { server } = await setup();
+
+ const { res } = await server.request(DATA_APP_BUNDLE_URL);
+
+ // How the page learns which generation to stamp: the header comes
+ // with the exact bytes it is about to evaluate.
+ expect(res.setHeader).toHaveBeenCalledWith(
+ "x-data-app-build-id",
+ "1",
+ );
+
+ await rebuild(server);
+ const { res: rebuilt } = await server.request(DATA_APP_BUNDLE_URL);
+ expect(rebuilt.setHeader).toHaveBeenCalledWith(
+ "x-data-app-build-id",
+ "2",
+ );
+ });
+ });
});
});
});
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/virtual-modules.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/virtual-modules.ts
index d3fe006501b..231ad81fc0b 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/virtual-modules.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/dev-plugin/virtual-modules.ts
@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
import * as dataAppVirtualModules from "build-configs/embedding-sdk/constants/data-app-virtual-modules";
import {
+ DATA_APP_BUILD_ID_HEADER,
DATA_APP_BUNDLE_URL,
DATA_APP_REBUILT_EVENT,
} from "../constants/bundle";
@@ -71,6 +72,7 @@ export const loadDataAppVirtualModule = (
`export const allowedHosts = ${JSON.stringify(allowedHosts)};`,
`export const appSlug = ${JSON.stringify(appSlug)};`,
`export const bundleUrl = ${JSON.stringify(DATA_APP_BUNDLE_URL)};`,
+ `export const buildIdHeader = ${JSON.stringify(DATA_APP_BUILD_ID_HEADER)};`,
`export const rebuiltEvent = ${JSON.stringify(DATA_APP_REBUILT_EVENT)};`,
`export const diagnosticsChangedEvent = ${JSON.stringify(DATA_APP_DIAGNOSTICS_CHANGED_EVENT)};`,
`export const sdkVersion = ${JSON.stringify(readInstalledSdkVersion(process.cwd()))};`,
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.ts
index 4ce86e2ed3b..5e352c0be06 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.ts
@@ -109,6 +109,7 @@ export const toPayload = (
return {
time: entry.time,
+ buildId: entry.buildId,
kind: entry.kind,
summary: truncateDiagnosticText(summary),
detail: detail === null ? null : truncateDiagnosticText(detail),
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.unit.spec.ts
index 62fd2d27e6b..99d8955be2f 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.unit.spec.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/diagnostics-payload.unit.spec.ts
@@ -10,6 +10,7 @@ import { toPayload } from "./diagnostics-payload";
const entry = (event: DevDiagnosticEvent): DevDiagnosticEntry => ({
id: 1,
time: 1700000000000,
+ buildId: 3,
...event,
});
@@ -80,4 +81,9 @@ describe("toPayload for requests", () => {
it("offers no hint for a request — the reason is already the answer", () => {
expect(toPayload(sdkCall({ status: 400, error: "boom" })).hint).toBeNull();
});
+
+ it("carries the build the entry was captured under, so a reader can age it", () => {
+ expect(toPayload(sdkCall()).buildId).toBe(3);
+ expect(toPayload({ ...sdkCall(), buildId: null }).buildId).toBeNull();
+ });
});
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/use-diagnostics-feed.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/use-diagnostics-feed.ts
index 11e297fa1c5..2d47a742c6b 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/use-diagnostics-feed.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/use-diagnostics-feed.ts
@@ -128,7 +128,10 @@ export const useDiagnosticsFeed = (
// Only this page load's entries: after a reload the author is looking at a
// fresh page, and a persistent error would otherwise stack up a copy per
// load. The server's buffer keeps every session — a shell reader paging it
- // with `?startEventId=` still sees what previous pages reported.
+ // with `?startEventId=` still sees what previous pages reported. Entries an
+ // earlier build reported are missing here because the endpoint withholds
+ // them from an ordinary read, not because anything discarded them: they are
+ // still in the buffer, and `?includeStale` returns them.
entries:
report?.entries.filter((entry) => entry.sessionId === DEV_SESSION_ID) ??
EMPTY_ENTRIES,
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/use-diagnostics-feed.unit.spec.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/use-diagnostics-feed.unit.spec.ts
index 6607580c358..5e010a654e4 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/use-diagnostics-feed.unit.spec.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/lib/use-diagnostics-feed.unit.spec.ts
@@ -15,6 +15,7 @@ const entry = (
eventId,
sessionId,
time: 0,
+ buildId: 1,
kind: "error",
summary: `event ${eventId}`,
detail: null,
@@ -24,6 +25,7 @@ const entry = (
const report = (
entries: DataAppDiagnosticPayload[],
+ overrides: Partial<DataAppDiagnosticsReport> = {},
): DataAppDiagnosticsReport => ({
entries,
connection: null,
@@ -31,8 +33,11 @@ const report = (
clients: 1,
lastReportAt: 1,
lastRebuildAt: 1,
+ buildId: 1,
+ staleEntries: 0,
nextEventId: (entries.at(-1)?.eventId ?? 0) + 1,
sessionId: "page-1",
+ ...overrides,
});
const ok = (body: DataAppDiagnosticsReport) =>
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics-channel.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics-channel.ts
index e6b4fd6c9d6..aa60e2e4be8 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics-channel.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics-channel.ts
@@ -10,6 +10,7 @@ export interface InstanceConnectionStatus {
export interface DataAppDiagnosticEntry {
time: number;
+ buildId: number | null;
kind: string;
summary: string;
detail: string | null;
@@ -36,6 +37,9 @@ export interface DataAppDiagnosticsReport {
clients: number;
lastReportAt: number | null;
lastRebuildAt: number | null;
+ buildId: number;
+ /** Entries the dev server withheld because an earlier build reported them. */
+ staleEntries: number;
/** Cursor for the next poll (`?startEventId=`): the last event's id + 1. */
nextEventId: number;
sessionId: string | null;
@@ -44,5 +48,5 @@ export interface DataAppDiagnosticsReport {
/** The part of the report the store owns; the rest comes from the dev server. */
export type DiagnosticsStoreReport = Omit<
DataAppDiagnosticsReport,
- "manifest" | "clients" | "lastRebuildAt"
+ "manifest" | "clients" | "lastRebuildAt" | "buildId" | "staleEntries"
>;
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics.ts
index 7833165fb09..cc906bab66f 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/types/diagnostics.ts
@@ -22,4 +22,5 @@ export type DevDiagnosticEvent =
export type DevDiagnosticEntry = {
id: number;
time: number;
+ buildId: number | null;
} & DevDiagnosticEvent;
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/vite-env.d.ts b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/vite-env.d.ts
index c9040197c20..f0e644e39eb 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app-dev/vite-env.d.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app-dev/vite-env.d.ts
@@ -16,6 +16,7 @@ declare module "virtual:metabase-data-app-dev-config" {
export const allowedHosts: string[];
export const appSlug: string;
export const bundleUrl: string;
+ export const buildIdHeader: string;
export const rebuiltEvent: string;
export const diagnosticsChangedEvent: string;
export const sdkVersion: string | null;
diff --git a/skills/metabase-data-app-setup/SKILL.md b/skills/metabase-data-app-setup/SKILL.md
index e7a90cff495..979c8ae2c79 100644
--- a/skills/metabase-data-app-setup/SKILL.md
+++ b/skills/metabase-data-app-setup/SKILL.md
@@ -222,9 +222,12 @@ curl -s "http://localhost:5174/__data-app/diagnostics?startEventId=0"
"eventId": 31, "kind": "blocked-network", "alert": true,
"summary": "Blocked fetch to api.example.com (not in allowed_hosts)",
"detail": null, // stack frames, when any
- "hint": "Add https://api.example.com to allowed_hosts in data_app.yaml …"
+ "hint": "Add https://api.example.com to allowed_hosts in data_app.yaml …",
+ "buildId": 7 // the bundle generation that reported it
}],
"clients": 1, // connected preview tabs — 0 means nothing ran
+ "buildId": 7, // the generation running now
+ "staleEntries": 164, // held back, reported by an older build — see below
"nextEventId": 32 // pass back as ?startEventId=
}
```
@@ -232,6 +235,17 @@ curl -s "http://localhost:5174/__data-app/diagnostics?startEventId=0"
**`clients: 0` does not mean healthy** — it means no preview tab is open, so an
empty `entries` proves nothing. Open `http://localhost:5174` first.
+**The feed answers for the bundle that is running, not for everything that ever
+happened.** Every save rebuilds and remounts the app, so a multi-step edit runs
+through builds that don't compile or don't render — errors from those describe
+code the preview has already replaced. They're withheld and counted in
+`staleEntries`; read mid-edit and you see the current build's failures, not a
+pile of them. Nothing is lost: the rebuild re-runs the app from scratch, so
+anything still broken reports itself again under the new `buildId`, and
+`?includeStale=true` hands back the withheld entries when comparing builds is
+the point. A *failed* build doesn't advance `buildId` — the preview keeps
+running the last good bundle, so its entries stay current.
+
Triage by `kind` (always read `hint` — it names the exact fix; never soften a
`summary` when reporting it):