Split flow-build-info.json into separate development and production mode files

[totally-not-ai]

Related to #25682

Background

META-INF/VAADIN/config/flow-build-info.json, the token file, carries the
configuration the build hands over to the runtime. One file serves two very
different purposes:

• prepare-frontend writes a development mode file: productionMode: false
  plus the absolute paths of the machine that runs the build (npmFolder,
  frontendFolder, node.version, the Java source and resource folders, ...).
  See BuildFrontendUtil.propagateBuildInfo.
• build-frontend rewrites the same file for production: it removes all of
  those and sets productionMode: true. See BuildFrontendUtil.updateBuildFile.

The file therefore has two distinct shapes, and which one a reader has in front
of it is only visible from the content.

Problem

One name for two shapes forces workarounds in the build plugins and in the
runtime:

1. The runtime cannot tell which copy on the class path belongs to the
   application. DefaultApplicationConfigurationFactory drops candidates whose
   URL ends with jar!/META-INF/VAADIN/config/flow-build-info.json, falls back
   to a copy inside a jar for a packaged application, counts nested archive
   separators to work out which jar is the application's, and logs "Unable to
   fully determine correct flow-build-info" when it cannot decide.
2. A development mode file packaged into a dependency by mistake is applied to
   the application. It points npmFolder at a folder on the machine that built
   the dependency, so the application fails to start with "Running project in
   development mode with no access to folder ...". Add-ons have to exclude the
   file from their artifact by hand, as
   flow-tests/test-express-build/java-add-on/pom.xml does.
3. The Maven plugin deletes the file after a production build
   (BuildFrontendMojo, FlowLifecycleParticipant) so that starting the
   application from an IDE afterwards does not read a stale
   productionMode: true token.
4. The Gradle plugin keeps the production tree in a separate output directory to
   avoid "a second, conflicting META-INF/VAADIN/config/flow-build-info.json" in
   the archive, and manages the single file through a build service and a cached
   copy (FlowPlugin, VaadinBuildFrontendTask, BuildFrontendTokenService).

Proposal

Write two files instead of one:

• META-INF/VAADIN/config/flow-development-mode-info.json, written by
  prepare-frontend. Describes the project on this machine and is not meant to
  be distributed in an artifact.
• META-INF/VAADIN/config/flow-production-mode-info.json, written by
  build-frontend. Contains no machine-specific paths, is packaged into the
  application and may be read from inside a jar.

The runtime then reads the production file from anywhere, including a jar, and
the development file only from the output of the project itself. The rest falls
out: no productionMode flag to inspect before trusting a file, no guessing
which jar owns which copy, and a development file inside a dependency is never
looked for in the first place.

To decide

• An application packaged as a plain or shaded jar in development mode has its
  development file inside a jar as well. Either that keeps working (read the
  development file from a jar when the project folder it names exists on this
  machine) or the packaging is declared unsupported in development mode.
• Compatibility: artifacts built by older versions carry only
  flow-build-info.json, so the runtime has to keep reading it for at least one
  major, with the current content-based rules.
• vaadin.frontend.token.file (FrontendUtils.PARAM_TOKEN_FILE) and
  vaadin.flow.tokenFilePath point at a single file and need a decision.
• Other places that name the file: flow-devloop-daemon, the Gradle plugin
  README, and anything outside this repository that reads the token file.

Affected

flow-server (FrontendUtils.TOKEN_FILE, AbstractConfigurationFactory,
DefaultApplicationConfigurationFactory, ServletDeployer, DAUUtils),
flow-plugin-base, flow-maven-plugin, flow-gradle-plugin,
flow-devloop-daemon, and the documentation.

[totally-not-ai]

Analysis

Valid request, and the four workarounds listed in the description are real — I checked each one against main:

1. Runtime guessing which copy is the application's. DefaultApplicationConfigurationFactory.getTokenFileFromClassloader first drops every candidate whose path ends with jar!/META-INF/VAADIN/config/flow-build-info.json (DefaultApplicationConfigurationFactory.java:160-167), and only if nothing is left falls back to getPossibleJarResource, which infers "we are running from a jar" from the nesting depth of vite.generated.ts, then picks a candidate at depth 1, and otherwise takes resources.get(0) with the Unable to fully determine correct flow-build-info warning (lines 179-231).
2. A development file packaged into a dependency is applied to the application. On main there is no provenance check at all, so the file is used and npmFolder points at the machine that built the dependency — DEV_FOLDER_MISSING_MESSAGE in AbstractConfigurationFactory:69. Add-ons exclude the file by hand: flow-tests/test-express-build/java-add-on/pom.xml:72, and the same exclusion exists in vaadin/quarkus (integration-tests/test-addons/*/pom.xml) and the add-on templates.
3. Maven deletes the file after a production build. BuildFrontendMojo marks it deleteOnExit and records the path in the vaadin.flow.tokenFilePath project property (lines 256-262), which FlowLifecycleParticipant.afterSessionEnd then deletes.
4. Gradle keeps the production tree in a separate output directory precisely to avoid "a second, conflicting META-INF/VAADIN/config/flow-build-info.json" (FlowPlugin.kt:101-107), and manages the single file through BuildFrontendTokenService (ensureToken/close) plus a cached copy cached-flow-build-info.json (VaadinBuildFrontendTask.kt:71).

Root cause

One path, two schemas with opposite lifecycles. The development file is machine-local state that must not be distributed; the production file is a build artifact that must be. Because they share a name, every reader has to recover the provenance from the content, and every writer has to keep the two shapes from colliding in one output tree.

A second symptom worth naming: BuildFrontendUtil.updateBuildFile derives the production file by subtracting keys from the development file — ~25 consecutive buildInfo.remove(...) calls (lines 1002-1028). That is a denylist: any key added to propagateBuildInfo and forgotten there ends up as an absolute build-machine path inside a shipped artifact. Two files let build-frontend write the production token from an allowlist instead, which removes that class of mistake rather than the symptom.

What a split does and does not buy

The runtime rule the proposal wants — production file: read from anywhere, including a jar; development file: never from a jar — does clear workarounds 1, 3 and 4. But note that it does not remove the content-based rules for at least one major: artifacts built by older versions carry only flow-build-info.json, so a packaged application still has to be read from inside a jar and still has to be inspected before being trusted. Until the old name is dropped, the split is additive to the existing logic, not a replacement for it.

The cost sits mostly outside this repo. Grounded list of readers in the vaadin org: vaadin/quarkus (deployment/.../VaadinPlugin.java writes it), vaadin/testbench (MockVaadinHelper.kt, browserless tests), vaadin/eclipse-plugin (ResourceReader, VaadinBuildParticipant), vaadin/hilla (Gradle functional tests), vaadin/docs, the add-on templates, plus flow-devloop-daemon in this repo (Frontend.java:84,227 reads frontendFolder). Nearly all of those read the development side.

Options

A — full split, both files renamed (as proposed): flow-development-mode-info.json + flow-production-mode-info.json, legacy flow-build-info.json still read with today's rules for one major.
Pro: both halves get an honest name; symmetric; the denylist in updateBuildFile can go.
Con: breaks every external reader listed above at once, so it needs a coordinated release across Quarkus/TestBench/IDE plugins/docs; the runtime carries three lookups for a whole major.

B — rename only the production half. Keep flow-build-info.json as the development file and add META-INF/VAADIN/config/flow-production-mode-info.json, written by build-frontend.
Pro: fixes the same four workarounds with one new name and one new rule ("the development name is never read from inside a jar, the production name is read from anywhere"), while every external development-side reader — IDE plugins, TestBench, devloop-daemon, Quarkus — keeps working untouched. Gradle no longer needs the separate output directory or the token build service, and Maven no longer needs the post-session delete, because the two files stop colliding. Legacy compatibility shrinks to one narrow path: a flow-build-info.json inside a jar declaring productionMode: true.
Con: asymmetric naming — the vague name survives for the development file, so the "which shape is this" question is only answered for the packaged case (which is the one that actually breaks).

C — no rename. Land #25682 and document the rule.
Pro: fixes the reported breakage (workaround 2) now, no ecosystem coordination, backportable.
Con: workarounds 1, 3 and 4 stay.

Recommendation

These are not mutually exclusive, and I'd treat them as two separate decisions:

• Now: land C. The "development file from a dependency breaks startup" bug exists in released versions, and a new filename cannot be backported to a maintenance branch — so the content-based rule is needed there regardless of what the next major does.
• Next major: B. It removes the same four workarounds as A for a fraction of the ecosystem churn, and A's remaining benefit over B is naming symmetry, not behaviour. If the symmetry is judged worth the coordinated release, A is a strict superset of B and can be done later by renaming the development file too.

On the open questions

• Plain/shaded jar in development mode. Worth keeping rather than declaring unsupported — it was flagged on fix: ignore a token file in a jar that was written for another project #25682 as a real case from the forum, and it costs one condition: when the development file is inside a jar, use it only if the project folder it names exists on this machine. That check is needed for the legacy name anyway.
• vaadin.frontend.token.file (FrontendUtils.PARAM_TOKEN_FILE). This is an explicit user override, so provenance is not in question — let it keep naming a single file of either shape, read by content. No change needed.
• vaadin.flow.tokenFilePath. Internal, only carries a path from BuildFrontendMojo to FlowLifecycleParticipant. Under B the cleanup it exists for disappears; under A it points at the production file.
• Does build-frontend still read the development file? It currently must (updateBuildFile warns Couldn't update devMode token due to missing token file. when absent), yet the Gradle plugin documents vaadinBuildFrontend as self-contained in production mode. Whichever option is chosen, writing the production token from an allowlist instead of subtracting from the development one resolves that inconsistency too.
• API surface. FrontendUtils.TOKEN_FILE is public and getConfigParametersUsingTokenData / getTokenFileFromClassloader are protected (@since 24.8); no subclasses outside this repo were found in the org, but they should still be extended with overloads rather than changed in place.

This needs a product/API decision and spans four modules plus other repositories, so I have not changed any code. @Artur- since the proposal is yours — is the asymmetric option B acceptable, or is the symmetric naming of A the point? @mshabarov the packaged-in-development-mode case you raised on #25682 is the one open behavioural question either way.

[mshabarov]

If we split this way, in production the point 2 will remain - multiple token files (from project and from jars) and no deterministic way of choosing just one properly.

[mshabarov]

Another idea is to re-use server settings (.json?) file for development.

[Artur-]

For add-on development you typically do not create a production build, so it's not an issue in that case.

We already have a deterministic way of selecting one - we pick the one from the project.

[Artur-]

@totally-not-ai What would a flow-production-mode-info.json contain in practice? Is there any harm in having two of those and picking a random one?

[mshabarov]

Add-on may be misconfigured in a way that it's build runs vaadin plugin that includes the token file into the JAR even though we recommend to exclude the file explicitly. This can be easily forgotten and leak to the project.

[totally-not-ai]

@Artur- Both good questions. I measured the first rather than guessing: I ran propagateBuildInfo followed by updateBuildFile on a mock adapter to get the two shapes the build actually produces today.

What it would contain

Development file (what prepare-frontend writes):

{
  "productionMode" : false,
  "eagerServerLoad" : false,
  "npmFolder" : "…/baseDir",
  "node.version" : "v0.0.0",
  "node.download.root" : "http://something/node/",
  "frontendFolder" : "…/frontend",
  "connect.javaSourceFolder" : "…/src/main/java",
  "javaResourceFolder" : "…/src/main/resources",
  "connect.applicationProperties" : "…/src/main/resources/application.properties",
  "connect.openApiFile" : "…/target/generated-resources/openapi.json",
  "project.frontend.generated" : "…/src/main/frontend/generated",
  "pnpm.enable" : false,
  "bun.enable" : false,
  "require.home.node" : false,
  "node.folder" : "/home/somebody/.vaadin/node",
  "build.folder" : "target",
  "disable.prepare.frontend.cache" : true,
  "react.enable" : true
}

Production file, the same file after build-frontend:

{
  "productionMode" : true,
  "eagerServerLoad" : false,
  "node.folder" : "/home/somebody/.vaadin/node",
  "disable.prepare.frontend.cache" : true,
  "react.enable" : true,
  "applicationIdentifier" : "TEST_APP_ID"
}

So in practice flow-production-mode-info.json would be four keys — productionMode, eagerServerLoad, react.enable, applicationIdentifier — plus, when the license check in updateBuildFile adds them, dau.enable, premiumFeatures.enable and commercialBanner.enable. Nothing else, and no paths. That is the argument for the split in one line: a file that small has no reason to be machine-specific, so "read it from anywhere, including a jar" is safe for it and never safe for the other one.

The dump also shows the denylist failing right now. node.folder and disable.prepare.frontend.cache are missing from the buildInfo.remove(...) list in updateBuildFile (BuildFrontendUtil.java:1002-1028), so every production artifact today ships an absolute path from the build machine plus a build-time-only flag. Harmless in effect — node.folder is only consumed through setDevModePropertiesUsingTokenData, which production never acts on — but it is exactly the leak the file split is supposed to make impossible, and it is already happening. Happy to fix those two removals separately from this issue; it is a two-line change and does not need the rename.

Two production files, picked at random

Mostly harmless, not entirely, and the part that isn't is the part that is hard to notice.

• productionMode, react.enable, eagerServerLoad describe the shape of the build. Two production builds normally agree on them, and a mismatch is a behaviour or performance difference rather than a failure. react.enable is the one that can actually misbehave, if the value disagrees with the bundle that is really on the class path.
• applicationIdentifier describes this application. DAUVaadinRequestInterceptor reads it via DeploymentConfiguration.getApplicationName() and reports daily active users under it. Picking a dependency's file reports one application's usage under another application's name.
• dau.enable, premiumFeatures.enable, commercialBanner.enable are written from the license check of the build that produced that file. Picking a dependency's file can switch DAU tracking off for an application that needs it, enable premium features granted to a different subscription, or show or suppress the commercial banner (IndexHtmlRequestHandler:739).

So the failure mode changes character rather than disappearing. Today a wrong pick is loud — wrong npmFolder, startup fails with DEV_FOLDER_MISSING_MESSAGE. After the split a wrong pick is silent misconfiguration of identity and licensing, which is worse to diagnose even though it is milder.

That refines what I wrote above about workaround 1: the split removes the need to inspect content to decide whether to trust a file and the vite.generated.ts nesting probe used to guess whether we are running from a jar, but it does not remove the need for a deterministic order. What is left is much cheaper than today's logic — prefer the project's own output directory, then the least nested jar, and warn when more than one production file is found. Ordering only, no content sniffing.

Worth noting that two production files do occur legitimately, which is why the exclusion in flow-tests/test-multi-war/test-war1/pom.xml:38 ("Exclude duplicated dev mode flow-build-info") and the equivalents in the add-on templates exist. And making "pick any" safe by construction would mean keeping the application-identifying and license keys out of the file — but those are most of its runtime value, so deterministic ordering plus a warning is the better trade.

[mcollovati]

node.folder and disable.prepare.frontend.cach should not be present in the production token file. Looks like a bug; some missing cleanup.

EDIT: fixed in #25871