refactor(fl): allowlist the app bundle — ship only app/ plus the backend's root file

[atriaybagur]

What

list_local_base_files walks FL_APP_BASE_DIR and mirrors it 1:1 into the app bucket, filtering nothing but symlinks. This replaces that with a positive allowlist: a bundle is everything under app/ plus one root file per backend, and nothing else.

BUNDLED_APP_DIR_NAME = "app"
BUNDLED_ROOT_FILES = {
    FLBackend.NVFLARE: frozenset({"meta.json"}),       # the job definition NVFLARE deploys from
    FLBackend.FLOWER:  frozenset({"pyproject.toml"}),  # the FAB definition
}

pyproject.toml must stay at the root because [tool.flwr.app.components] resolves app.server_app:app relative to it — flwr run . executes there.

Note: this PR previously proposed a denylist of known dev/tooling directories. It now inverts that. The history below explains why; the denylist commit is still in the branch, superseded by the allowlist commit on top.

Why a denylist wasn't enough

A template directory is also a live uv project root — it is where pyproject.toml sits — so it is exactly where uv sync, ruff, pytest and friends write their caches. In dev that tree is bind-mounted into flip-api, so a denylist has to keep pace with every tool a developer might run, and one miss ships the artefact to every trust. The denylist this replaces already omitted .tox, .nox, htmlcov, .idea, dist/ and *.egg-info.

Allowlisting is closed by construction: a .venv is excluded because it is not app/, not because someone remembered to name it.

This is not hypothetical. It cost a full afternoon of e2e debugging on 2026-08-26. A .venv built against python3.14 sat in fl-apps/flower/{standard,evaluation}, was bundled to S3, and was downloaded into every Flower run directory — where the ServerApp found an interpreter-less venv, died instantly, and left [flwr-serverapp] <defunct>. The hub reported only status=INITIATED until timeout. Four consecutive runs failed this way before the cause was traced.

Note those .venv dirs are gitignored — and gitignored is not excluded from the bundler, which walks the filesystem, not git.

It also drops real files that don't belong at a trust

A denylist could never catch these, because they aren't artefacts:

file	why it should not ship
recipe.py	a developer driver that regenerates the committed configs. Its own docstring says "Run from the flip-utils venv (needs the full extra — flip + nvflare + torch)". It would otherwise sit dead in every trust's app directory as executable Python.
README.md	documentation
required_files.json	the per-template source for the backend-level manifest flip-api actually reads, one directory up at fl-apps/<backend>/required_files.json

Effect

template	before	after
nvflare/standard	6 files	3
flower/standard	6 files	4
flower/standard, with a developer's .venv	26 files	4

Design notes

• __pycache__/*.pyc/*.pyo stay named explicitly. Compiled Python is the one artefact that appears inside app/, where position alone cannot exclude it. Pruned in place on dirnames during os.walk, so those trees are never descended into.
• Uploads are untouched. The researcher's model files and any evaluation checkpoint are added by the bundler after this walk — into app*/custom/, or diverted to server_checkpoints/ so a large file does not collapse NVFLARE's app-deploy. They never pass through list_local_base_files.
• Per-backend, resolved at the call site. Both bundlers already knew their backend, so this is a one-argument change at each.
• Fails closed, but audibly. FL_APP_BASE_DIR may point at an operator-provided tree, where an allowlist drops files it does not recognise. Every excluded path is logged at debug level, and the "base application files missing" error now names the rule, so a visibly non-empty template directory reporting "missing" stays diagnosable.
• .env.app is no longer preserved. The previous denylist avoided a "skip dotfiles" rule to protect it — but there are zero .env.app files under fl-apps; all 8 live in fl-tutorials, which this walk never touches. Even there it is a simulator-time file.

Behaviour change

A template with no app/ directory now yields no bundleable files at all, so it is rejected at the first check (Base application files missing …) rather than by the later app-folder scan. test_bundle_nvflare_application_no_app_folders is updated accordingly; the error text now names the rule and the debug log lists what was excluded.

Tests

flip-api/tests/unit/fl_services/ — 200 passed. Nine cover this walk directly:

• artefacts excluded without being enumerated (.venv, .ruff_cache, .DS_Store)
• unknown tool output excluded (.tox, .nox, htmlcov, .idea, dist, *.egg-info) — the property a denylist cannot have
• __pycache__ / .pyc / .pyo inside app/
• recipe.py, README.md, required_files.json dropped
• root file is per-backend, and the other backend's does not ride along
• symlinks skipped, including a symlinked directory inside app/
• the debug log names what it dropped

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[atriaybagur]

Both inline comments addressed in eae004f: each bundling path now verifies the backend's root file (meta.json / pyproject.toml) is actually present in the walked template, after the existing empty-list guard, and fails with a FileNotFoundError naming the missing file and the template dir. Unit tests added for both backends; flip-api ruff + mypy + unit suite green (1582 passed).

[garciadias]

This hardcodes recursion into a directory literally named app, but bundle_nvflare_application's own downstream comment a few dozen lines below (Find app folders (top-level directories that start with app, e.g. app, app_site1, etc), around line 685) and fl-services/nvflare/fl-api-base/fl_api/utils/upload.py both document app_site-1/app_site-2 as a supported multi-site base-template layout. With this change, any such folder in a local base template -- baked-in or an operator-provided FL_APP_BASE_DIR override -- is silently excluded (only a DEBUG log records it), with no test covering the scenario. Was retiring multi-site base templates intentional? If so it should be called out explicitly and the stale docs/comments updated; if not, the allowlist needs to recognize app_site-/app_ directories too.

[garciadias]

The docstring promises every skipped path is logged at debug level, but a symlinked directory nested inside app/ is excluded via os.walk(followlinks=False) without ever being appended to skipped in _walk_app_dir -- unlike a symlinked directory at the template root, which is logged. Minor inconsistency between the documented guarantee and actual behavior for this one nested case.

[garciadias]

The allowlist rework is a well-reasoned, well-tested fix for a real production incident (dev/tooling artefacts shipped to trusts). However it silently and untestedly narrows a separate, documented capability: NVFLARE's multi-site app_site-N base-template folders (still referenced in this same file's bundle_nvflare_application comments and in fl-api-base/fl_api/utils/upload.py) are no longer picked up by list_local_base_files, with only a DEBUG log recording the omission. Please either widen the allowlist to recognize app_site-/app_ folders, or explicitly retire that capability with updated docs/comments and a test proving the new intentional behavior. Two additional minor nits left inline.

[garciadias]

One more finding that GitHub wouldn't let me anchor as an inline comment (the line falls outside this PR's diff hunks) — noting it here instead:

flip-api/src/flip_api/fl_services/services/fl_service.py:692 (Minor) — the "No app folders found under base application" branch is now unreachable for the scenarios the new tests exercise (both are caught earlier by the two new guards this PR adds). It's still reachable for "root file present, app/ directory entirely absent," but that case isn't tested, and its wording is now inconsistent with the clearer, rule-naming errors added elsewhere in this PR. Suggested: add a unit test for the "root file only, no app/" case, or fold it into the new guards so all three malformed-template cases share consistent wording.