~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""PR #3299 replaced Flask with FastAPI end to end. Every route Flask served
under a URL had to be re-declared by hand as a FastAPI router; nothing
mechanical enforced that the new declaration used the same method, the same
path, or existed at all. `test_route_contracts.py`, `test_fastapi_migration.py`,
`test_all_endpoints.py`, `test_urls_js.py` and `test_url_for_links.py` all
check the NEW app against itself — a route that silently changed method, path
shape, or vanished, while staying internally consistent, passes every one of
them. This is the missing check: the OLD (Flask) route table against the NEW
(FastAPI) route table.
Running both stacks side by side is not possible — Flask and its dependencies
are fully deleted from this branch. Both tables are instead recovered
*statically*: `ast`-parsing `@bp.route(...)` / `Blueprint(...)` /
`register_blueprint(...)` out of the pre-migration commit for Flask,
and `@router.<method>(...)` / `APIRouter(prefix=...)` out of the checked-out
`web/routers/*.py` for FastAPI. No Flask import, no FastAPI app import, no
network beyond `git show`.
The property under test: **the (METHOD, normalised-path) diff between
Flask's route table and FastAPI's route table must equal the diff this file
committed and a human reviewed.** Any route that changed method, path shape,
or disappeared without landing in that reviewed diff fails the build. This
proves routing-table parity — that every URL+method pair from Flask still
routes to *something* in FastAPI, or was a reviewed, intentional removal.
A second layer, `TestRouteBehaviourParityAgainstFlaskSnapshot`, carries the
same idea past route existence: for every route both tables agree on, it
compares the HTTP method set, the path-parameter types Flask's URL
converters implied, which rules were declared with a trailing slash,
whether the route was behind `@login_required`, which literal HTTP status
codes the handler can return, and whether the JSON error body still carries
an `error` key. Same contract, same escape hatch: the divergence set must
equal a committed, human-reviewed table.
None of this proves anything about response payload *contents*, headers, or
runtime behaviour — two routes can agree on all six axes and still return
different JSON. See `test_route_contracts.py` for schema-level checks of the
new side alone.
Two layers, mirroring `test_source_provenance_map.py`'s guardian, so the
committed snapshot still protects local or partial checkouts that cannot read
the pre-migration baseline:
* `TestFastAPIRouteTableAgainstFlaskSnapshot` is pure filesystem (the Flask
side is a committed, human-reviewed snapshot) and always gates.
* `TestFlaskSnapshotIsCurrent` re-derives the Flask table from the immutable
pre-migration baseline and skips locally when that commit is unreachable;
it exists to catch snapshot drift/rot after the Flask files are deleted.
Regenerating `flask_route_table_snapshot.json` (needs the baseline commit),
from the repository root::
python -c "
import sys; sys.path.insert(0, 'tests/web')
import test_route_table_parity as m
m.write_snapshot(m.FLASK_SNAPSHOT_BASELINE)
"
Then re-review the resulting diff against every EXPECTED_* table in this
file. Regenerating is never a fix on its own: the snapshot is the *old*
app's behaviour, and it only changes if the extraction changed or history
was rewritten. If a regeneration moves it, work out which of those two
happened before trusting the new file.
"""
# allow: no-sut-import — a guardian test over route *tables*, not behaviour.
# Its subject is Flask source text at the legacy baseline (parsed with `ast`, never
# imported — Flask is not a dependency of this branch) and FastAPI router
# source text on this branch (also parsed with `ast`, never imported/run).
# tests/test_source_provenance_map.py carries the same exemption for the
# same reason.
import ast
import itertools
import json
import os
import re
import subprocess
from pathlib import Path
from typing import Never
import pytest
REPO_ROOT = Path(__file__).resolve().parents[2]
DATA_DIR = Path(__file__).resolve().parent
SNAPSHOT_FILE = DATA_DIR / "flask_route_table_snapshot.json"
FLASK_SNAPSHOT_BASELINE = "78904a4f48c4cadc74ab461c242e130d76fdd499"
ROUTERS_DIR = REPO_ROOT / "src" / "local_deep_research" / "web" / "routers"
FASTAPI_APP_FILE = (
REPO_ROOT / "src" / "local_deep_research" / "web" / "fastapi_app.py"
)
_SNAPSHOT_KEYS = {"routes", "views"}
_SNAPSHOT_VIEW_KEYS = {
"methods",
"path",
"func",
"file",
"auth",
"status_codes",
"body_keys",
}
_SNAPSHOT_HTTP_METHODS = {
"DELETE",
"GET",
"HEAD",
"OPTIONS",
"PATCH",
"POST",
"PUT",
}
# ---------------------------------------------------------------------------
# Reviewed, intentional diff between the Flask table and the FastAPI table.
# Every entry here was looked at by a human and judged correct. Anything the
# live diff produces that is NOT in these two sets fails the build.
#
# normalise() collapses path *parameter names* to a bare placeholder (`{}`,
# or `{:path}` for a greedy/slash-eating segment) before comparing, because
# Flask and FastAPI routinely rename the same slot (`<string:research_id>`
# vs `{id}`) and the name is not part of the route's identity for this
# check. What IS preserved: literal segments, method, and whether the
# trailing segment is greedy (Flask `<path:...>` / FastAPI `{...:path}`).
# ---------------------------------------------------------------------------
# The duplicate legacy `/api/news/*` blueprint (web/routes/news_routes.py)
# was deleted outright. The surviving /news/api/* blueprint covers the same
# capabilities, but its routes, inputs, and responses are not identical; see
# changelog.d/3299.breaking.md. The removal measures 12 (METHOD, path) entries
# from 11 distinct route declarations (one declared both PUT and PATCH on the
# same path). The changelog separately lists cases requiring more than a prefix
# substitution; that is not the number of removed pairs.
EXPECTED_REMOVED = [
("DELETE", "/api/news/subscriptions/{}"),
("GET", "/api/news/categories"),
("GET", "/api/news/feed"),
("GET", "/api/news/subscriptions"),
("GET", "/api/news/subscriptions/{}"),
("GET", "/api/news/subscriptions/{}/history"),
("PATCH", "/api/news/subscriptions/{}"),
("POST", "/api/news/feedback"),
("POST", "/api/news/preferences"),
("POST", "/api/news/research"),
("POST", "/api/news/subscriptions"),
("PUT", "/api/news/subscriptions/{}"),
# Legacy corruption repair is now the one-time migration 0031.
("POST", "/settings/fix_corrupted_settings"),
# Context-overflow analytics moved out from under the /metrics blueprint
# prefix to top-level /api paths (routes/context_overflow_api.py's own
# decorators were always "/api/context-overflow" etc; Flask prepended
# the blueprint's registered url_prefix="/metrics" in front of them).
("GET", "/metrics/api/context-overflow"),
("GET", "/metrics/api/research/{}/context-overflow"),
# research_bp's bare page alias for the settings page. settings_bp's own
# "/" route (-> "/settings/", WITH trailing slash) is unaffected and
# still present on both sides. FastAPI's default redirect_slashes behavior
# redirects /settings to /settings/ with 307, so the page remains reachable;
# this records a route-declaration difference, not a removed user flow.
("GET", "/settings"),
# Flask's <path:key> converter is greedy (matches segments containing
# "/"); FastAPI's {key} is not. Valid custom keys containing "/" therefore
# 404 after migration. Documented in changelog.d/3299.breaking.md and
# tracked for compatibility restoration in #6056; built-in keys are clear.
("DELETE", "/settings/api/{:path}"),
("GET", "/settings/api/{:path}"),
("PUT", "/settings/api/{:path}"),
# The library's bulk re-index trigger moved from GET to POST. It runs
# the embedding/index pipeline over every document in the collection
# (`?force_reindex=true` stages and atomically replaces vectors that
# already exist), so it is a mutation and belongs on a verb CSRFMiddleware
# guards — enforcement there is keyed on the method, and a per-path
# allowlist cannot stand in for it (the middleware compares
# `scope["path"]` as a string, the router matches a `$`-anchored
# regex, and uvicorn's percent-decode makes those two disagree). Same
# path, same handler, same query parameters, same SSE response; the
# GET now 405s. No shipped frontend called it — urls.js's
# RAG_INDEX_ALL has no caller and the history page's Index All button
# POSTs COLLECTION_INDEX_START — and fetch-based SSE clients send the
# token as they already do for every other POST. Paired with the
# ("POST", ...) entry in EXPECTED_ADDED and the method-set entry in
# EXPECTED_METHOD_SET_DIVERGENCES.
("GET", "/library/api/rag/index-all"),
# Same verb move for the parameterized sibling: the per-collection
# re-index trigger. Nothing in the repo sent the GET either — the
# history page's Index button POSTs COLLECTION_INDEX_START.
("GET", "/library/api/collections/{}/index"),
]
EXPECTED_ADDED = [
("GET", "/api/context-overflow"),
("GET", "/api/research/{}/context-overflow"),
# FastAPI-side counterparts of the greedy-vs-non-greedy settings key
# change noted above.
("DELETE", "/settings/api/{}"),
("GET", "/settings/api/{}"),
("PUT", "/settings/api/{}"),
# Model discovery calls providers with the user's stored keys and
# rewrites their cached rows (on a cache miss, for every provider with
# ``?force_refresh=true``, for one with ``?refresh_provider=``), so it
# moved from GET (``?force_refresh=true`` included) to a
# CSRF-protected POST. Ordinary GET reads remain available.
("POST", "/settings/api/available-models"),
# FastAPI-side counterpart of the bulk re-index GET -> POST move
# recorded in EXPECTED_REMOVED above.
("POST", "/library/api/rag/index-all"),
# ...and of the per-collection sibling right below it.
("POST", "/library/api/collections/{}/index"),
]
def _git(*args: str) -> str | None:
"""Run a read-only git command, or None if it cannot be answered.
None always means "this environment cannot tell me", never "the answer
is empty" — a partial checkout can lack the baseline commit, and a gate
that silently passed in CI would be worse than no gate.
"""
try:
completed = subprocess.run(
["git", *args],
cwd=REPO_ROOT,
capture_output=True,
timeout=120,
check=False,
)
except (OSError, subprocess.SubprocessError):
return None
if completed.returncode != 0:
return None
return completed.stdout.decode("utf-8", "replace")
def _unavailable_git_evidence(message: str) -> Never:
if os.environ.get("CI"):
pytest.fail(message)
pytest.skip(message)
def _literal(node):
return node.value if isinstance(node, ast.Constant) else None
def _join(prefix, path):
prefix = prefix or ""
if not prefix:
return path
if prefix.endswith("/") and path.startswith("/"):
return prefix[:-1] + path
if not prefix.endswith("/") and not path.startswith("/"):
return prefix + "/" + path
return prefix + path
_PARAM_RE = re.compile(r"\{([^}]*)\}")
def normalise(method: str, path: str) -> tuple[str, str]:
"""(METHOD, path) with every {param} collapsed to a bare placeholder.
`{name:path}` (FastAPI) and the already-`{name:path}`-shaped output of
`_flask_to_placeholder` (from Flask's `<path:name>`) both collapse to
`{:path}` so a greedy segment still compares as greedy; every other
`{name}` collapses to `{}`, deliberately discarding the parameter name.
"""
def repl(m: re.Match) -> str:
return "{:path}" if m.group(1).endswith(":path") else "{}"
return method.upper(), _PARAM_RE.sub(repl, path)
_FLASK_CONVERTER_RE = re.compile(
r"<(?:([a-zA-Z_]+):)?([a-zA-Z_][a-zA-Z0-9_]*)>"
)
def _flask_to_placeholder(path: str) -> str:
"""Flask's `<int:x>` / `<path:x>` / `<x>` -> FastAPI-shaped `{x}` / `{x:path}`."""
def repl(m: re.Match) -> str:
conv, name = m.group(1), m.group(2)
return f"{{{name}:path}}" if conv == "path" else f"{{{name}}}"
return _FLASK_CONVERTER_RE.sub(repl, path)
# ---------------------------------------------------------------------------
# Behaviour layer. The route table above answers "does the URL still route
# somewhere"; everything below answers "does it still behave the same", to
# the extent a static reader can tell.
#
# Four dimensions are compared per route, all of them recoverable from source
# text alone:
#
# auth gate Flask's `@login_required` decorator vs FastAPI's
# `Depends(require_auth)`. Both produce 401; a route that
# lost its gate is a missing-authentication regression, and
# a route that gained one 401s a caller that used to work.
# path converter Flask's `<int:x>` / `<path:x>` vs FastAPI's `{x}` plus a
# type annotation. `<int:x>` -> unannotated `{x}` silently
# widens what the route accepts; the reverse silently 422s
# ids that used to work.
# status codes literal HTTP codes the handler can return.
# body keys which of `error` / `detail` / `message` the handler puts
# in a JSON body — FastAPI's default envelope is `detail`,
# so a client parsing `error` breaks silently.
#
# WHAT THE STATUS-CODE AND BODY-KEY SCAN CAN AND CANNOT SEE. It reads the
# handler body plus ONE level of same-module helper functions the handler
# calls by bare name. It does NOT follow into service classes, other
# modules, or app-level exception handlers. That is deliberate — a
# whole-program analysis is not available statically — but it means the raw
# diff carries false positives in BOTH directions: a code that moved from
# the view into a service layer reads as "lost", and a code raised by a
# shared dependency reads as "gained". Every such case is resolved by hand
# and recorded in the reviewed tables below WITH the reason, so the tables
# are a review record rather than a mute suppression list. The scan is
# symmetric across the two sides, which is what makes the comparison
# meaningful at all: the same reader looks at both.
# ---------------------------------------------------------------------------
# Flask decorators that make a view return 401 to an anonymous caller, and
# the FastAPI dependency that replaced them. Counted at the time of
# writing, over routed views only: Flask carries 307 `@login_required`,
# 4 `@scheduler_control_required` and 4 `@api_access_control`; FastAPI
# carries 300 route decorations declaring `Depends(require_auth)`, 4
# `Depends(require_scheduler_control)` and 4 `Depends(require_api_access)`,
# resolving to 304 auth-gated views once nested dependencies are closed
# over. The two totals are not meant to match: Flask's includes the 11
# routes of the duplicate news blueprint this PR deleted (see
# EXPECTED_REMOVED), and a view with two `@bp.route` decorators counts
# once on the Flask side and twice on the FastAPI side. What must match,
# and is asserted below, is the gate on each individual shared route.
_FLASK_AUTH_DECORATORS = {
"login_required",
# Wrapping gates that themselves 401 an anonymous caller. Their FastAPI
# counterparts declare `Depends(require_auth)` internally, which
# `_close_over_dependencies` resolves, so both sides must list them or
# every /api/v1 and news-scheduler route reads as newly gated.
"api_access_control",
"scheduler_control_required",
}
_FASTAPI_AUTH_DEPENDENCIES = {"require_auth"}
# Flask URL converters -> the Python type FastAPI must annotate the matching
# path parameter with to accept and reject exactly the same strings.
# FastAPI treats an unannotated path parameter as `str`, so `str` and None
# are equivalent here. `path` is `str`-typed too: its greediness is not
# expressed by the annotation but by the `{x:path}` suffix, which
# `normalise()` already folds into the route key, so a greediness change
# surfaces as a route-table diff rather than a converter diff.
_FLASK_CONVERTER_TO_ANNOTATION = {
None: "str",
"string": "str",
"int": "int",
"float": "float",
"uuid": "str",
"path": "str",
"any": "str",
}
_BODY_KEYS_OF_INTEREST = ("error", "detail", "message")
def _annotated_aliases(tree: ast.Module) -> dict:
"""Map ``NAME -> Annotated[...]`` for module-level
``NAME = Annotated[...]`` assignments, e.g. notes.py's
``_NotesBody = Annotated[..., Depends(_notes_json_body)]``.
A route parameter can reference a dependency through such an alias
(``body: _NotesBody``) instead of spelling ``Annotated[...]`` inline.
The alias's own AST node never appears inside the route function's
subtree, so a plain `ast.walk(fn)` cannot see the wrapped
``Depends(...)`` (or the status codes it raises) — this lets callers
substitute the alias's node in before walking.
"""
aliases = {}
for node in tree.body:
if not (
isinstance(node, ast.Assign)
and len(node.targets) == 1
and isinstance(node.targets[0], ast.Name)
):
continue
value = node.value
head = value.value if isinstance(value, ast.Subscript) else None
is_annotated = (
isinstance(head, ast.Name) and head.id == "Annotated"
) or (isinstance(head, ast.Attribute) and head.attr == "Annotated")
if is_annotated:
aliases[node.targets[0].id] = value
return aliases
def _module_functions(tree: ast.Module) -> dict:
"""Module-LEVEL functions only, deliberately not `ast.walk`.
Both stacks nest a `_impl` / `_sync` closure inside many views, and the
same name is reused across unrelated views in one file. Walking the
whole tree put every one of those in a single flat namespace, so a
helper-following scan merged status codes between routes that share
nothing but a closure name — it invented ~30 phantom divergences.
Nested functions still get scanned, but as part of the view that
contains them, which is where they belong.
"""
return {
node.name: node
for node in tree.body
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))
}
def _decorator_names(fn) -> set[str]:
names = set()
for dec in fn.decorator_list:
target = dec.func if isinstance(dec, ast.Call) else dec
if isinstance(target, ast.Name):
names.add(target.id)
elif isinstance(target, ast.Attribute):
names.add(target.attr)
return names
def _scan_one_function(fn, *, flask_side: bool, aliases: dict | None = None):
"""-> (literal status codes, body keys of interest, bare names called).
``aliases`` (FastAPI side only) maps a module-level ``Annotated[...]``
alias name to its AST node — e.g. notes.py's ``_NotesBody`` used as
``body: _NotesBody``. A parameter annotated with such a bare-name alias
hides its ``Depends(...)`` behind the alias, outside `fn`'s own
subtree, so those params get the alias's node walked in alongside `fn`.
"""
codes: set[int] = set()
keys: set[str] = set()
calls: set[str] = set()
extra_nodes = []
if aliases:
params = (
list(fn.args.posonlyargs)
+ list(fn.args.args)
+ list(fn.args.kwonlyargs)
)
for arg in params:
ann = arg.annotation
if isinstance(ann, ast.Name) and ann.id in aliases:
extra_nodes.append(aliases[ann.id])
for node in itertools.chain(
ast.walk(fn), *(ast.walk(n) for n in extra_nodes)
):
if isinstance(node, ast.Name):
# Every bare name, not just called ones: both stacks hand
# helpers to a runner (`await run_db_sync(_start_sync)`,
# `Depends(require_api_access)`) as often as they call them,
# and a call-only scan misses all of those.
calls.add(node.id)
if isinstance(node, ast.Call):
func = node.func
if isinstance(func, ast.Name):
name = func.id
elif isinstance(func, ast.Attribute):
name = func.attr
else:
name = None
first = node.args[0] if node.args else None
if (
name in ("abort", "HTTPException", "StarletteHTTPException")
and isinstance(first, ast.Constant)
and isinstance(first.value, int)
):
codes.add(first.value)
if flask_side and name == "redirect":
# Flask's redirect() defaults to 302; the FastAPI side spells
# RedirectResponse(status_code=302) out, caught just below.
codes.add(302)
for kw in node.keywords:
if (
kw.arg == "status_code"
and isinstance(kw.value, ast.Constant)
and isinstance(kw.value.value, int)
):
codes.add(kw.value.value)
if (
isinstance(node, ast.Return)
and isinstance(node.value, ast.Tuple)
and len(node.value.elts) >= 2
):
# Flask's `return jsonify(...), 400` tuple form.
second = node.value.elts[1]
if isinstance(second, ast.Constant) and isinstance(
second.value, int
):
codes.add(second.value)
if isinstance(node, ast.Dict):
for key in node.keys:
value = _literal(key) if key is not None else None
if value in _BODY_KEYS_OF_INTEREST:
keys.add(value)
return codes, keys, calls
# How far the scan chases module-level helpers out of a view. 2 is not a
# round number: it is where the measured divergence count stops falling.
# Depth 1 leaves 12 routes looking like they lost a status code purely
# because the code moved one hop into a `_sync` helper; depth 2 clears 3
# of those and every one of the ~11 body-key false positives from the same
# cause. Depth 3 does not clear any further false positive and *adds* one
# (it reaches far enough on the Flask side to pick up a code the route
# cannot actually reach), so the extra hop is pure noise.
_SCAN_DEPTH = 2
def _scan_view(
fn, module_fns, *, flask_side: bool, aliases: dict | None = None
):
"""Status codes + body keys of a view plus the helpers it reaches."""
codes, keys, refs = _scan_one_function(
fn, flask_side=flask_side, aliases=aliases
)
seen = {fn.name}
frontier = refs
for _ in range(_SCAN_DEPTH):
following = set()
for name in sorted(frontier):
helper = module_fns.get(name)
if name in seen or helper is None or helper is fn:
continue
seen.add(name)
helper_codes, helper_keys, helper_refs = _scan_one_function(
helper, flask_side=flask_side
)
codes |= helper_codes
keys |= helper_keys
following |= helper_refs
frontier = following
return codes, keys
def _view_record(
*,
methods,
path,
func,
file,
auth,
codes,
keys,
):
"""One JSON-round-trippable row of the behaviour table."""
return {
"methods": sorted(methods),
"path": path,
"func": func,
"file": file,
"auth": bool(auth),
"status_codes": sorted(codes),
"body_keys": sorted(keys),
}
# ---------------------------------------------------------------------------
# FastAPI side: static AST over the routers this branch actually ships.
# Always available — no origin/main dependency.
# ---------------------------------------------------------------------------
_HTTP_METHODS = {"get", "post", "put", "delete", "patch"}
def _fastapi_router_prefix(tree: ast.AST) -> str | None:
for node in ast.walk(tree):
if (
isinstance(node, ast.Assign)
and isinstance(node.value, ast.Call)
and isinstance(node.value.func, ast.Name)
and node.value.func.id == "APIRouter"
):
for kw in node.value.keywords:
if kw.arg == "prefix":
return _literal(kw.value)
return None
def _fastapi_dependency_names(fn, dec) -> set[str]:
"""Every `Depends(name)` reachable from a handler's signature/decorator.
Covers the two spellings this branch uses — a default value
(`user: str = Depends(require_auth)`) and the decorator's
`dependencies=[Depends(...)]` list. `Annotated[..., Depends(...)]` is
also handled, though no router uses it today.
"""
names: set[str] = set()
def collect(node):
for sub in ast.walk(node):
if (
isinstance(sub, ast.Call)
and isinstance(sub.func, ast.Name)
and sub.func.id == "Depends"
and sub.args
):
target = sub.args[0]
if isinstance(target, ast.Name):
names.add(target.id)
elif isinstance(target, ast.Attribute):
names.add(target.attr)
args = fn.args
for default in list(args.defaults) + [
d for d in args.kw_defaults if d is not None
]:
collect(default)
for arg in list(args.posonlyargs) + list(args.args) + list(args.kwonlyargs):
if arg.annotation is not None:
collect(arg.annotation)
for kw in dec.keywords:
if kw.arg == "dependencies":
collect(kw.value)
return names
def _annotation_name(node) -> str | None:
if node is None:
return None
try:
return ast.unparse(node)
except (AttributeError, ValueError): # pragma: no cover - defensive
return "?"
def _close_over_dependencies(names: set[str], module_fns: dict) -> set[str]:
"""Expand a handler's `Depends(...)` set through nested dependencies.
FastAPI dependencies nest: `/api/v1`'s `require_api_access` itself
declares `Depends(require_auth)`, so those routes ARE auth-gated even
though `require_auth` never appears in the handler's own signature.
Only same-module dependency functions can be followed — which is
enough here, because every wrapping gate on this branch
(`require_api_access`, `require_scheduler_control`) is defined in the
router that uses it.
"""
resolved = set(names)
frontier = set(names)
while frontier:
following: set[str] = set()
for name in sorted(frontier):
fn = module_fns.get(name)
if fn is None:
continue
for nested in _fastapi_dependency_names(fn, _NO_DECORATOR):
if nested not in resolved:
resolved.add(nested)
following.add(nested)
frontier = following
return resolved
# A decorator-shaped stand-in with no keywords, for _fastapi_dependency_names
# calls that are inspecting a plain dependency function rather than a route
# handler (there is no decorator to read `dependencies=` off).
_NO_DECORATOR = ast.Call(func=ast.Name(id="_"), args=[], keywords=[])
def derive_fastapi_view_table() -> list[dict]:
"""Every FastAPI route with the behaviour detail the parity layer needs.
Read straight off the source tree — no import of the app, no server.
Each row also carries `params` (parameter name -> annotation source
text) so the converter check can look up what a path slot is typed as.
"""
views: list[dict] = []
files = [FASTAPI_APP_FILE] + sorted(ROUTERS_DIR.glob("*.py"))
for path in files:
# fastapi_app.py declares a handful of routes directly on `app`
# rather than through a router (root page, favicon, legacy static
# redirect); the routers use `router`.
holder = "app" if path == FASTAPI_APP_FILE else "router"
src = path.read_text(encoding="utf-8")
tree = ast.parse(src, filename=str(path))
module_fns = _module_functions(tree)
aliases = _annotated_aliases(tree)
prefix = _fastapi_router_prefix(tree) if holder == "router" else None
router_deps = _fastapi_router_dependencies(tree)
rel = path.relative_to(REPO_ROOT).as_posix()
for node in ast.walk(tree):
if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
continue
for dec in node.decorator_list:
if not (
isinstance(dec, ast.Call)
and isinstance(dec.func, ast.Attribute)
and isinstance(dec.func.value, ast.Name)
and dec.func.value.id == holder
and dec.func.attr in _HTTP_METHODS
):
continue
route_path = _literal(dec.args[0]) if dec.args else None
if route_path is None:
continue
codes, keys = _scan_view(
node, module_fns, flask_side=False, aliases=aliases
)
for kw in dec.keywords:
if kw.arg == "status_code" and isinstance(
kw.value, ast.Constant
):
codes.add(kw.value.value)
deps = _close_over_dependencies(
_fastapi_dependency_names(node, dec) | router_deps,
module_fns,
)
auth = bool(deps & _FASTAPI_AUTH_DEPENDENCIES)
if auth:
codes.add(401)
params = {}
sig = node.args
for arg in (
list(sig.posonlyargs)
+ list(sig.args)
+ list(sig.kwonlyargs)
):
params[arg.arg] = _annotation_name(arg.annotation)
record = _view_record(
methods=[dec.func.attr.upper()],
path=_join(prefix, route_path)
if holder == "router"
else route_path,
func=node.name,
file=rel,
auth=auth,
codes=codes,
keys=keys,
)
record["params"] = params
views.append(record)
return views
def _fastapi_router_dependencies(tree: ast.AST) -> set[str]:
"""`Depends(...)` names on the `APIRouter(dependencies=[...])` itself."""
names: set[str] = set()
for node in ast.walk(tree):
if (
isinstance(node, ast.Assign)
and isinstance(node.value, ast.Call)
and isinstance(node.value.func, ast.Name)
and node.value.func.id == "APIRouter"
):
for kw in node.value.keywords:
if kw.arg != "dependencies":
continue
for sub in ast.walk(kw.value):
if (
isinstance(sub, ast.Call)
and isinstance(sub.func, ast.Name)
and sub.func.id == "Depends"
and sub.args
and isinstance(sub.args[0], ast.Name)
):
names.add(sub.args[0].id)
return names
def derive_fastapi_route_table() -> set[tuple[str, str]]:
"""Every (METHOD, path) FastAPI serves, read straight off the source tree."""
return {
(method, view["path"])
for view in derive_fastapi_view_table()
for method in view["methods"]
}
# ---------------------------------------------------------------------------
# Flask side: static AST over the legacy baseline. Only used by the staleness check
# below — the main parity test reads the committed snapshot instead, so it
# never needs Git history to gate.
#
# Blueprints are scattered across ~20 files outside web/routes/ too
# (web/auth/, benchmarks/web_api/, chat/, followup_research/, news/,
# research_library/*, research_scheduler/) and app_factory.py's
# register_blueprints() wires each one in with an optional url_prefix
# override. One (news/web.py's create_news_blueprint()) nests a second,
# cross-file blueprint inside itself via bp.register_blueprint(...) before
# the whole thing is registered on the app — that nesting is flattened
# explicitly below because resolving it generically would mean parsing
# call graphs across files, not just declarations.
# ---------------------------------------------------------------------------
# (path relative to repo root, blueprint variable name, url_prefix override
# passed at app.register_blueprint(), or None to use the blueprint's own
# declared url_prefix). Derived by reading
# the baseline app_factory.py imports and its
# register_blueprints() function by hand.
_FLASK_REGISTRATIONS: list[tuple[str, str, str | None]] = [
("src/local_deep_research/web/auth/routes.py", "auth_bp", None),
(
"src/local_deep_research/web/routes/research_routes.py",
"research_bp",
None,
),
(
"src/local_deep_research/web/routes/history_routes.py",
"history_bp",
None,
),
(
"src/local_deep_research/web/routes/metrics_routes.py",
"metrics_bp",
None,
),
(
"src/local_deep_research/web/routes/settings_routes.py",
"settings_bp",
None,
),
(
"src/local_deep_research/web/routes/api_routes.py",
"api_bp",
"/research/api",
),
(
"src/local_deep_research/benchmarks/web_api/benchmark_routes.py",
"benchmark_bp",
None,
),
(
"src/local_deep_research/web/routes/context_overflow_api.py",
"context_overflow_bp",
"/metrics",
),
("src/local_deep_research/web/routes/news_routes.py", "bp", None),
("src/local_deep_research/chat/routes.py", "chat_bp", None),
(
"src/local_deep_research/followup_research/routes.py",
"followup_bp",
None,
),
("src/local_deep_research/news/web.py", "bp", "/news"),
# news/web.py's `bp` does `bp.register_blueprint(news_api_bp)` with
# news_api_bp imported from news/flask_api.py (own url_prefix="/api",
# no override at the nesting call) — flattened: "/news" + "/api".
("src/local_deep_research/news/flask_api.py", "news_api_bp", "/news/api"),
("src/local_deep_research/web/api.py", "api_blueprint", None),
(
"src/local_deep_research/research_library/routes/library_routes.py",
"library_bp",
None,
),
(
"src/local_deep_research/research_library/routes/rag_routes.py",
"rag_bp",
None,
),
(
"src/local_deep_research/research_library/routes/zotero_routes.py",
"zotero_bp",
None,
),
(
"src/local_deep_research/research_library/deletion/routes/delete_routes.py",
"delete_bp",
None,
),
(
"src/local_deep_research/research_library/search/routes/search_routes.py",
"search_bp",
None,
),
(
"src/local_deep_research/research_scheduler/routes.py",
"scheduler_bp",
None,
),
("src/local_deep_research/web/routes/notes_routes.py", "notes_bp", None),
(
"src/local_deep_research/web/routes/unified_search_routes.py",
"unified_search_bp",
None,
),
]
# Routes declared directly on `app` in app_factory.py rather than through
# any blueprint (root page, favicon, static passthrough).
_FLASK_APP_ROUTES: list[tuple[str, str]] = [
("GET", "/"),
("GET", "/favicon.ico"),
("GET", "/static/<path:path>"),
]
def _hook_method_scope(fn) -> frozenset:
"""Which HTTP methods a `before_request` hook actually acts on.
A hook whose body opens `if request.method in ("POST", "PUT", ...)` is
a no-op for every other method, and crediting its status codes to a
GET route would invent a divergence rather than find one. An empty set
means "no method guard found" — the hook applies to all methods, which
is Flask's own default.
"""
scope: set[str] = set()
for node in ast.walk(fn):
if not isinstance(node, ast.Compare):
continue
if not (
isinstance(node.left, ast.Attribute)
and node.left.attr == "method"
and isinstance(node.left.value, ast.Name)
and node.left.value.id == "request"
):
continue
if not (len(node.ops) == 1 and isinstance(node.ops[0], ast.In)):
continue
target = node.comparators[0]
if isinstance(target, (ast.Tuple, ast.List, ast.Set)):
for element in target.elts:
value = _literal(element)
if isinstance(value, str):
scope.add(value.upper())
return frozenset(scope)
def _parse_flask_file(source: str, rel_path: str):
"""-> (var -> declared url_prefix, var -> [view record], nested list).
Each view record is the same shape `derive_fastapi_view_table()`
produces, minus `params` (Flask carries its parameter types in the URL
rule itself, not in the signature), plus the still-unjoined route
`path`. The blueprint prefix is applied by the caller.
"""
tree = ast.parse(source)
module_fns = _module_functions(tree)
var_prefix: dict[str, str | None] = {}
var_routes: dict[str, list[dict]] = {}
nested: list[tuple[str, str, str | None]] = []
# `@bp.before_request` hooks short-circuit EVERY route on the blueprint,
# so their status codes and body keys belong to every one of those
# routes. Without this the notes blueprint's two hooks (413 oversized
# body, 400 non-object JSON) look like 26 FastAPI routes each inventing
# a new 413 — when in fact FastAPI's `_notes_json_body` dependency is
# the direct, documented port of exactly those hooks.
var_before_request: dict[str, list[tuple[frozenset, set, set]]] = {}
for node in ast.walk(tree):
if (
isinstance(node, ast.Assign)
and isinstance(node.value, ast.Call)
and isinstance(node.value.func, ast.Name)
and node.value.func.id == "Blueprint"
and len(node.targets) == 1
and isinstance(node.targets[0], ast.Name)
):
var = node.targets[0].id
prefix = None
for kw in node.value.keywords:
if kw.arg == "url_prefix":
prefix = _literal(kw.value)
var_prefix[var] = prefix
var_routes.setdefault(var, [])
for node in ast.walk(tree):
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
for dec in node.decorator_list:
if (
isinstance(dec, ast.Attribute)
and dec.attr == "before_request"
and isinstance(dec.value, ast.Name)
and dec.value.id in var_routes
):
hook_codes, hook_keys = _scan_view(
node, module_fns, flask_side=True
)
var_before_request.setdefault(dec.value.id, []).append(
(
_hook_method_scope(node),
hook_codes,
hook_keys,
)
)
for node in ast.walk(tree):
if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
for dec in node.decorator_list:
if (
isinstance(dec, ast.Call)
and isinstance(dec.func, ast.Attribute)
and dec.func.attr == "route"
and isinstance(dec.func.value, ast.Name)
):
var = dec.func.value.id
if var not in var_routes:
continue
path = _literal(dec.args[0]) if dec.args else None
methods = None
for kw in dec.keywords:
if kw.arg == "methods" and isinstance(
kw.value, ast.List
):
methods = [_literal(e) for e in kw.value.elts]
if methods is None:
methods = ["GET"]
if path is None:
continue
auth = bool(_decorator_names(node) & _FLASK_AUTH_DECORATORS)
codes, keys = _scan_view(node, module_fns, flask_side=True)
for scope, hook_codes, hook_keys in var_before_request.get(
var, []
):
if scope and not scope & set(methods):
continue
codes |= hook_codes
keys |= hook_keys
if auth:
codes.add(401)
var_routes[var].append(
_view_record(
methods=methods,
path=path,
func=node.name,
file=rel_path,
auth=auth,
codes=codes,
keys=keys,
)
)
if isinstance(node, ast.Expr) and isinstance(node.value, ast.Call):
call = node.value
if (
isinstance(call.func, ast.Attribute)
and call.func.attr == "register_blueprint"
and isinstance(call.func.value, ast.Name)
and call.args
and isinstance(call.args[0], ast.Name)
):
parent = call.func.value.id
child = call.args[0].id
override = None
for kw in call.keywords:
if kw.arg == "url_prefix":
override = _literal(kw.value)
nested.append((parent, child, override))
return var_prefix, var_routes, nested
def derive_flask_view_table_from_origin_main(
merge_base: str,
) -> list[dict] | None:
"""Flask's route table WITH behaviour detail, from baseline source text.
None (never an empty list) when any source file is unreadable, so a
shallow checkout skips instead of silently comparing against nothing.
"""
views: list[dict] = []
for rel_path, var, override in _FLASK_REGISTRATIONS:
source = _git("show", f"{merge_base}:{rel_path}")
if source is None:
return None
var_prefix, var_routes, nested = _parse_flask_file(source, rel_path)
if var not in var_routes:
return None
effective = (
override if override is not None else (var_prefix.get(var) or "")
)
for record in var_routes[var]:
views.append({**record, "path": _join(effective, record["path"])})
for parent, child, child_override in nested:
if parent != var or child not in var_routes:
continue
child_eff = (
child_override
if child_override is not None
else (var_prefix.get(child) or "")
)
combined = _join(effective, child_eff) if child_eff else effective
for record in var_routes[child]:
views.append(
{**record, "path": _join(combined, record["path"])}
)
return sorted(
views, key=lambda r: (r["path"], r["methods"], r["file"], r["func"])
)
def derive_flask_route_table_from_origin_main(
merge_base: str,
) -> set[tuple[str, str]] | None:
"""Re-derive Flask's route table from the immutable baseline source."""
views = derive_flask_view_table_from_origin_main(merge_base)
if views is None:
return None
pairs: set[tuple[str, str]] = set(_FLASK_APP_ROUTES)
for record in views:
for method in record["methods"]:
pairs.add((method, record["path"]))
return pairs
def write_snapshot(merge_base: str) -> int:
"""Regenerate the committed snapshot from the legacy baseline; -> view count.
Not called by any test — it is the documented regeneration entry point
(see the module docstring), kept next to the reader so the two formats
cannot drift. One route or view per line rather than
`json.dumps(indent=...)`: the file is reviewed as a diff, and a
pretty-printed nesting turns a one-route change into a 40-line hunk.
"""
views = derive_flask_view_table_from_origin_main(merge_base)
routes = derive_flask_route_table_from_origin_main(merge_base)
if views is None or routes is None:
raise RuntimeError(
f"cannot read the Flask sources at {merge_base}; fetch "
"the baseline commit (a partial clone cannot regenerate this file)"
)
lines = ["{", ' "routes": [']
lines += [f" {json.dumps(list(pair))}," for pair in sorted(routes)[:-1]]
lines.append(f" {json.dumps(list(sorted(routes)[-1]))}")
lines += [" ],", ' "views": [']
lines += [f" {json.dumps(view)}," for view in views[:-1]]
lines.append(f" {json.dumps(views[-1])}")
lines += [" ]", "}", ""]
SNAPSHOT_FILE.write_text("\n".join(lines), encoding="utf-8")
return len(views)
def _snapshot_schema_error(location: str, message: str) -> Never:
raise ValueError(f"invalid Flask route snapshot at {location}: {message}")
def _validate_snapshot(snapshot: object) -> dict:
"""Reject data hidden beside, or malformed inside, the route contract.
The snapshot is an allowlisted JSON path in a public repository. Merely
indexing ``routes`` and ``views`` would let an unrelated top-level payload
ride along without affecting the parity assertions. Validate the complete
shape before any consumer sees it so the file remains only the narrow,
reviewable compatibility contract it claims to be.
"""
if type(snapshot) is not dict:
_snapshot_schema_error("$", "expected an object")
if set(snapshot) != _SNAPSHOT_KEYS:
missing = sorted(_SNAPSHOT_KEYS - set(snapshot))
extra = sorted(set(snapshot) - _SNAPSHOT_KEYS)
_snapshot_schema_error(
"$", f"top-level keys differ; missing={missing}, extra={extra}"
)
routes = snapshot["routes"]
if type(routes) is not list or not routes:
_snapshot_schema_error("$.routes", "expected a non-empty list")
route_pairs: set[tuple[str, str]] = set()
for index, route in enumerate(routes):
location = f"$.routes[{index}]"
if (
type(route) is not list
or len(route) != 2
or not all(type(value) is str for value in route)
):
_snapshot_schema_error(
location, "expected exactly [HTTP_METHOD, /path]"
)
method, path = route
if method not in _SNAPSHOT_HTTP_METHODS:
_snapshot_schema_error(location, f"unsupported method {method!r}")
if not path.startswith("/"):
_snapshot_schema_error(location, f"path is not rooted: {path!r}")
pair = (method, path)
if pair in route_pairs:
_snapshot_schema_error(location, f"duplicate route {pair!r}")
route_pairs.add(pair)
views = snapshot["views"]
if type(views) is not list or not views:
_snapshot_schema_error("$.views", "expected a non-empty list")
view_fingerprints: set[str] = set()
for index, view in enumerate(views):
location = f"$.views[{index}]"
if type(view) is not dict:
_snapshot_schema_error(location, "expected an object")
if set(view) != _SNAPSHOT_VIEW_KEYS:
missing = sorted(_SNAPSHOT_VIEW_KEYS - set(view))
extra = sorted(set(view) - _SNAPSHOT_VIEW_KEYS)
_snapshot_schema_error(
location, f"view keys differ; missing={missing}, extra={extra}"
)
methods = view["methods"]
path = view["path"]
func = view["func"]
source_file = view["file"]
auth = view["auth"]
status_codes = view["status_codes"]
body_keys = view["body_keys"]
if (
type(methods) is not list
or not methods
or not all(
type(method) is str and method in _SNAPSHOT_HTTP_METHODS
for method in methods
)
or len(methods) != len(set(methods))
):
_snapshot_schema_error(
f"{location}.methods", "expected unique supported HTTP methods"
)
if type(path) is not str or not path.startswith("/"):
_snapshot_schema_error(
f"{location}.path", "expected a rooted route path"
)
if type(func) is not str or not func.isidentifier():
_snapshot_schema_error(
f"{location}.func", "expected a Python identifier"
)
if (
type(source_file) is not str
or not source_file.startswith("src/")
or "\\" in source_file
or ".." in Path(source_file).parts
):
_snapshot_schema_error(
f"{location}.file", "expected a repository-relative src/ path"
)
if type(auth) is not bool:
_snapshot_schema_error(f"{location}.auth", "expected a boolean")
if type(status_codes) is not list or not all(
type(code) is int and 100 <= code <= 599 for code in status_codes
):
_snapshot_schema_error(
f"{location}.status_codes",
"expected HTTP status integers from 100 through 599",
)
if type(body_keys) is not list or not all(
type(key) is str for key in body_keys
):
_snapshot_schema_error(
f"{location}.body_keys", "expected a list of strings"
)
missing_pairs = sorted(
(method, path)
for method in methods
if (method, path) not in route_pairs
)
if missing_pairs:
_snapshot_schema_error(
location,
f"view method/path pairs missing from routes: {missing_pairs}",
)
fingerprint = json.dumps(view, sort_keys=True, separators=(",", ":"))
if fingerprint in view_fingerprints:
_snapshot_schema_error(location, "duplicate view record")
view_fingerprints.add(fingerprint)
return snapshot
def _read_snapshot() -> dict:
"""The committed snapshot, as a mapping with `routes` and `views`.
`routes` is the (METHOD, path) table the original parity check compares
against. `views` is the per-view behaviour detail added later — auth
gate, literal status codes, body keys. They are kept in one file, and
one freshness check keeps them consistent: two files could drift apart
and only one of them be noticed.
"""
return _validate_snapshot(
json.loads(SNAPSHOT_FILE.read_text(encoding="utf-8"))
)
def _minimal_valid_snapshot() -> dict:
return {
"routes": [["GET", "/health"]],
"views": [
{
"methods": ["GET"],
"path": "/health",
"func": "health",
"file": "src/example.py",
"auth": False,
"status_codes": [200],
"body_keys": ["status"],
}
],
}
class TestFlaskSnapshotSchema:
def test_committed_snapshot_has_only_the_validated_contract(self):
snapshot = _read_snapshot()
assert set(snapshot) == _SNAPSHOT_KEYS
def test_rejects_an_unrelated_top_level_payload(self):
snapshot = _minimal_valid_snapshot()
snapshot["notes"] = {"unexpected": "unreviewed payload"}
with pytest.raises(ValueError, match="top-level keys differ"):
_validate_snapshot(snapshot)
def test_rejects_extra_fields_hidden_in_a_view(self):
snapshot = _minimal_valid_snapshot()
snapshot["views"][0]["comment"] = "unreviewed payload"
with pytest.raises(ValueError, match="view keys differ"):
_validate_snapshot(snapshot)
@pytest.mark.parametrize(
("field", "value", "message"),
[
("methods", ["TRACE"], "supported HTTP methods"),
("path", "health", "rooted route path"),
("func", "not-a-function", "Python identifier"),
("file", "../outside/routes.py", "repository-relative"),
("auth", "false", "expected a boolean"),
("status_codes", [True], "HTTP status integers"),
("body_keys", ["status", 7], "list of strings"),
],
)
def test_rejects_malformed_view_fields(self, field, value, message):
snapshot = _minimal_valid_snapshot()
snapshot["views"][0][field] = value
with pytest.raises(ValueError, match=message):
_validate_snapshot(snapshot)
def test_rejects_duplicate_route_records(self):
snapshot = _minimal_valid_snapshot()
snapshot["routes"].append(["GET", "/health"])
with pytest.raises(ValueError, match="duplicate route"):
_validate_snapshot(snapshot)
def _load_snapshot() -> set[tuple[str, str]]:
return {(m, p) for m, p in _read_snapshot()["routes"]}
def _load_view_snapshot() -> list[dict]:
return _read_snapshot()["views"]
def _diff(flask_pairs, fastapi_pairs):
flask_norm = {
normalise(m, _flask_to_placeholder(p)) for m, p in flask_pairs
}
fastapi_norm = {normalise(m, p) for m, p in fastapi_pairs}
removed = sorted(flask_norm - fastapi_norm)
added = sorted(fastapi_norm - flask_norm)
return removed, added
class TestFastAPIRouteTableAgainstFlaskSnapshot:
"""Always gates: compares the live FastAPI table to the committed,
human-reviewed Flask snapshot. This is the actual parity assertion."""
def test_snapshot_file_exists(self):
assert SNAPSHOT_FILE.is_file(), (
f"Flask route snapshot missing at {SNAPSHOT_FILE} — see "
"TestFlaskSnapshotIsCurrent for how to regenerate it."
)
def test_route_diff_matches_the_reviewed_expectations(self):
flask_pairs = _load_snapshot()
fastapi_pairs = derive_fastapi_route_table()
removed, added = _diff(flask_pairs, fastapi_pairs)
unexpected_removed = sorted(set(removed) - set(EXPECTED_REMOVED))
unexpected_added = sorted(set(added) - set(EXPECTED_ADDED))
stale_expected_removed = sorted(set(EXPECTED_REMOVED) - set(removed))
stale_expected_added = sorted(set(EXPECTED_ADDED) - set(added))
problems = []
if unexpected_removed:
problems.append(
"Routes Flask served that FastAPI no longer does, and this "
"was NOT reviewed:\n"
+ "\n".join(f" {m} {p}" for m, p in unexpected_removed)
)
if unexpected_added:
problems.append(
"Routes FastAPI serves that Flask never did, and this was "
"NOT reviewed:\n"
+ "\n".join(f" {m} {p}" for m, p in unexpected_added)
)
if stale_expected_removed:
problems.append(
"EXPECTED_REMOVED lists routes that are no longer missing "
"(the route came back, or the snapshot changed) — prune "
"these entries:\n"
+ "\n".join(f" {m} {p}" for m, p in stale_expected_removed)
)
if stale_expected_added:
problems.append(
"EXPECTED_ADDED lists routes that no longer exist in "
"FastAPI — prune these entries:\n"
+ "\n".join(f" {m} {p}" for m, p in stale_expected_added)
)
assert not problems, (
"\n\n".join(problems)
+ "\n\nThis test compares ROUTING TABLES ONLY (method + path "
"shape). It proves every Flask URL+method still routes to "
"something (or was a reviewed removal) — it proves nothing "
"about request/response bodies, status codes, or behaviour."
)
class TestFlaskSnapshotIsCurrent:
"""Re-derive the snapshot from the immutable legacy Flask baseline."""
def test_snapshot_matches_a_fresh_extraction_from_origin_main(self):
fresh = derive_flask_route_table_from_origin_main(
FLASK_SNAPSHOT_BASELINE
)
if fresh is None:
_unavailable_git_evidence(
"one or more Flask route source files could not be read at "
f"baseline {FLASK_SNAPSHOT_BASELINE}; cannot verify snapshot freshness"
)
# Both `fresh` and the snapshot are raw Flask converter syntax
# (`<int:x>`, `<path:x>`, ...) — no placeholder conversion here.
# That conversion only happens later, when diffing against FastAPI's
# `{x}` syntax in TestFastAPIRouteTableAgainstFlaskSnapshot.
snapshot = _load_snapshot()
missing_from_snapshot = sorted(fresh - snapshot)
extra_in_snapshot = sorted(snapshot - fresh)
assert not missing_from_snapshot and not extra_in_snapshot, (
"flask_route_table_snapshot.json no longer matches a fresh "
f"static extraction from {FLASK_SNAPSHOT_BASELINE}. Regenerate "
"it (see the module docstring) and re-review the diff against "
"EXPECTED_REMOVED/EXPECTED_ADDED.\n"
f"Missing from snapshot: {missing_from_snapshot}\n"
f"Extra in snapshot (no longer in Flask source): {extra_in_snapshot}"
)
def test_view_detail_matches_a_fresh_extraction_from_origin_main(self):
"""The behaviour half of the same file.
Kept separate from the route-table half so a drift in one is not
reported as a drift in the other: the route table is what
EXPECTED_REMOVED/EXPECTED_ADDED are reviewed against, the view
detail is what the behavioural tables are reviewed against, and
they fail for different reasons.
"""
fresh = derive_flask_view_table_from_origin_main(
FLASK_SNAPSHOT_BASELINE
)
if fresh is None:
_unavailable_git_evidence(
"one or more Flask route source files could not be read at "
f"baseline {FLASK_SNAPSHOT_BASELINE}; cannot verify snapshot freshness"
)
snapshot = _load_view_snapshot()
assert len(snapshot) == len(fresh), (
f"the snapshot holds {len(snapshot)} Flask views, a fresh "
f"extraction finds {len(fresh)}. Regenerate the snapshot and "
"re-review the behavioural expectation tables."
)
def identify(view):
return (view["path"], tuple(view["methods"]), view["func"])
drifted = [
(identify(old), old, new)
for old, new in zip(snapshot, fresh)
if old != new
]
assert not drifted, (
"the per-view behaviour detail in "
"flask_route_table_snapshot.json no longer matches a fresh "
f"extraction from {FLASK_SNAPSHOT_BASELINE}:\n"
+ "\n".join(
f" {ident}\n snapshot: {old}\n fresh: {new}"
for ident, old, new in drifted[:10]
)
)
# ---------------------------------------------------------------------------
# Behaviour comparison: index both tables by the same (METHOD, normalised
# path) key the route-table check uses, so a route only enters the
# behavioural comparison once both sides agree it exists.
# ---------------------------------------------------------------------------
def _index_views(views, *, flask_side: bool) -> dict:
index: dict[tuple[str, str], list[dict]] = {}
for view in views:
path = (
_flask_to_placeholder(view["path"]) if flask_side else view["path"]
)
for method in view["methods"]:
index.setdefault(normalise(method, path), []).append(view)
return index
def _matched_views():
"""-> (flask index, fastapi index, sorted keys present in both)."""
flask_index = _index_views(_load_view_snapshot(), flask_side=True)
fastapi_index = _index_views(derive_fastapi_view_table(), flask_side=False)
return (
flask_index,
fastapi_index,
sorted(set(flask_index) & set(fastapi_index)),
)
def _union(views, field) -> set:
merged: set = set()
for view in views:
merged.update(view[field])
return merged
def _where(views) -> str:
return ", ".join(f"{v['file']}:{v['func']}" for v in views)
# ---------------------------------------------------------------------------
# Reviewed behavioural expectations. Same contract as EXPECTED_REMOVED /
# EXPECTED_ADDED above: everything listed here was read on both sides by a
# human and judged correct; anything the live comparison produces that is
# NOT listed fails the build, and anything listed that no longer diverges
# fails too (so the tables cannot rot into permanent suppression).
# ---------------------------------------------------------------------------
# {normalised path: (Flask method set, FastAPI method set)}. A path both
# tables serve on a DIFFERENT set of verbs fails
# `test_method_sets_match_per_path` unless it is listed here with both
# sides spelled out — and an entry whose two sides stop diverging, or
# start diverging differently, fails too.
EXPECTED_METHOD_SET_DIVERGENCES = {
# GET remains a cache-only read, while POST discovers on a cache miss,
# replaces the whole model cache with ``?force_refresh=true`` and
# refreshes one provider with ``?refresh_provider=``. A GET carrying
# ``refresh_provider`` or ``force_refresh=true`` returns 405 (#6465).
"/settings/api/available-models": ({"GET"}, {"GET", "POST"}),
# The bulk re-index trigger; see the paired entries in
# EXPECTED_REMOVED / EXPECTED_ADDED for why the verb changed. Stated
# here as well because a verb move is exactly the "silent 405 for
# every client still sending the old method" this test exists to
# surface, and it should be reviewed as a method change rather than
# read as two unrelated diff lines. Nothing in the repo sent the GET.
"/library/api/rag/index-all": ({"GET"}, {"POST"}),
# The per-collection sibling; same reasoning as above. Nothing in
# the repo sent the GET.
"/library/api/collections/{}/index": (
{"DELETE", "GET"},
{"DELETE", "POST"},
),
}
# (METHOD, normalised path, slot index, Flask converter, FastAPI annotation).
# The whole comparison is 141 parameter slots across 308 shared routes, of
# which 8 are Flask `<int:...>` — every one of those 8 is annotated `int` on
# the FastAPI side, so the int-widening failure mode this check exists for
# does not occur anywhere. One slot diverges textually:
EXPECTED_CONVERTER_DIVERGENCES = [
# `/chat/` and `/chat/<session_id>` are one view with an optional
# parameter on BOTH sides (Flask: two `@chat_bp.route` decorators and
# `def chat_page(session_id=None)`; FastAPI: two `@router.get`
# decorators and `session_id: str | None = None`). When the slot is
# present it is matched as a string either way — the `| None` arm is
# unreachable for the parameterised route — so the set of accepted URLs
# is identical. Kept as an explicit entry rather than taught to the
# comparator, because "strip `| None` and re-compare" would also hide a
# genuine `int | None` vs `int` change.
("GET", "/chat/{}", 0, "string", "str | None"),
]
# Flask `@login_required` -> FastAPI `Depends(require_auth)`. The removal
# direction has NO expectations table on purpose: a route that lost its auth
# gate is a missing-authentication vulnerability, never a reviewed change,
# so `test_no_route_lost_its_auth_gate` asserts the empty set directly and
# there is nowhere to record an exception.
EXPECTED_AUTH_GATE_ADDED = [
# Flask checked `session.get("username")` by hand and redirected; the
# port replaced that with `Depends(require_auth)`, which additionally
# rejects a stale session whose database is no longer open. Browser
# callers still get a 302 to /auth/login (the app's HTTPException
# handler converts 401 -> redirect for non-JSON requests), so the
# common path is unchanged; an XHR caller now gets 401 where it used
# to get 302. web/routers/auth.py:change_password_page/change_password.
("GET", "/auth/change-password"),
("POST", "/auth/change-password"),
# Same pattern: Flask's view did its own `jsonify({"error": "Not
# authenticated"}), 401`. web/routers/auth.py:integrity_check.
("GET", "/auth/integrity-check"),
# Deliberate, and the only one of the four that changes what an
# anonymous caller can reach: the news health endpoint was public and
# is now authenticated (it leaked subsystem state and wrote a
# `user_id="health_check"` sentinel row). /api/v1/health remains the
# public liveness probe. web/routers/news_pages.py:news_health_check.
# Documented in changelog.d/3299.breaking.md so operators know to move
# monitoring to the surviving public /api/v1/health endpoint.
("GET", "/news/health"),
]
# Status codes the Flask view could return that no FastAPI counterpart can.
# {(METHOD, normalised path): [codes]}.
EXPECTED_STATUS_CODES_LOST = {
# The legacy static shim intentionally serves assets in place (#6641),
# removing the Location header. Existing files now return 200 with the
# same asset and cache policy as /static/; missing or invalid paths use
# the shared 404 handler. Runtime parity and no-redirect coverage live
# in test_static_file_serving.py and routers/test_redirect_static.py.
("GET", "/redirect-static/{:path}"): [302],
# --- The notes blueprint's oversized-body 413, on non-mutating methods.
# Flask armed it with a blueprint-wide `@notes_bp.before_request`
# (`_reject_oversized_bodies`), which ran for EVERY method. FastAPI
# ports it as the `Depends(_notes_json_body)` dependency, which is
# declared on the 24 mutating routes only — so a GET or DELETE to a
# notes route with an oversized Content-Length is no longer capped at
# the notes-specific 2x50MB ceiling. It is still capped, by the
# app-wide BodySizeLimitMiddleware (`fastapi_app.py`'s
# `max_json_body_size`), just at a much higher figure. Real, narrow,
# and undocumented; recorded rather than treated as a regression
# because no notes GET/DELETE route reads a request body at all.
("GET", "/notes/"): [413],
("GET", "/notes/{}"): [413],
("GET", "/notes/api/documents/{}/annotations"): [413],
("GET", "/notes/api/documents/{}/notes"): [413],
("GET", "/notes/api/notes"): [413],
("GET", "/notes/api/notes/ask-context"): [413],
("GET", "/notes/api/notes/search-for-linking"): [413],
("GET", "/notes/api/notes/semantic-search"): [413],
("GET", "/notes/api/notes/{}"): [413],
("GET", "/notes/api/notes/{}/backlinks"): [413],
("GET", "/notes/api/notes/{}/collections"): [413],
("GET", "/notes/api/notes/{}/outgoing-links"): [413],
("GET", "/notes/api/notes/{}/research"): [413],
("GET", "/notes/api/notes/{}/similar"): [413],
("GET", "/notes/api/notes/{}/suggested-links"): [413],
("GET", "/notes/api/notes/{}/unlinked-mentions"): [413],
("GET", "/notes/api/notes/{}/versions"): [413],
("GET", "/notes/api/notes/{}/versions/semantic-diff"): [413],
("GET", "/notes/api/notes/{}/versions/{}"): [413],
("GET", "/notes/api/research/{}/annotations"): [413],
("GET", "/notes/api/research/{}/notes"): [413],
("DELETE", "/notes/api/documents/{}/annotations/{}"): [413],
("DELETE", "/notes/api/notes/{}"): [413],
("DELETE", "/notes/api/notes/{}/collections/{}"): [413],
("DELETE", "/notes/api/research/{}/annotations/{}"): [413],
# --- Scan-visibility limits, verified by hand as unchanged behaviour.
# The 404 still happens; it is raised as a typed
# `SubscriptionNotFoundException(status_code=404)` from
# news/exceptions.py by the service layer and rendered by the app's
# NewsAPIException handler, instead of being a literal in the view.
("GET", "/news/api/subscriptions/{}"): [404],
("PUT", "/news/api/subscriptions/{}"): [404],
("DELETE", "/news/api/subscriptions/{}"): [404],
# PRUNED 2026-08: POST /settings/api/notifications/test-url no longer
# diverges. The entry recorded the port's inability to reach Flask's
# "No notification URL configured" 400, because the port had dropped
# the stored-URL fallback entirely -- with no fallback there was no
# unconfigured-URL branch to answer 400 from. #5958 (commit a84a8e2c9)
# restored the fallback, and with it the literal
# `JSONResponse({...}, status_code=400)` the Flask view had. Parity
# restored at the source; nothing here was relaxed to accommodate it.
# Flask redirected an unauthenticated caller with a literal 302; the
# port raises 401 and the app's HTTPException handler turns that into
# the same 302 for browser requests. Paired with the auth-gate entry
# above and with the 401 in EXPECTED_STATUS_CODES_GAINED.
("GET", "/auth/change-password"): [302],
# --- Backup status probe: Flask's 500 error envelope became an
# in-band 200 status report (#7199). The endpoint reads the
# last-attempt failure record before its try block; if listing the
# backup directory then raises, a 500 would make the JS client's
# catch() replace the section with a generic "Could not load backup
# status." -- discarding the failure report this screen exists to
# surface, exactly when storage trouble makes the two failures
# correlated. The 200 body keeps the same keys as the success branch
# with listing_available=False / count=None; the always-200 shape is
# recorded in DICT_RETURN_ALLOWLIST
# (test_migration_antipattern_guards.py). Auth failures still 401.
("GET", "/settings/api/backup-status"): [500],
}
# Status codes a FastAPI route can return that its Flask counterpart could
# not. Not automatically a regression — most are new input validation — but
# each one can turn a request that used to succeed into a failure.
EXPECTED_STATUS_CODES_GAINED = {
# A GET carrying ``refresh_provider`` or ``force_refresh=true`` would
# call providers with the stored keys and rewrite cached models without
# a CSRF check (``force_refresh=true`` deleted every cached row). It now
# fails with 405 and directs clients to POST (#6465).
("GET", "/settings/api/available-models"): [405],
# SameSite=Lax lets a link from another site open the chat page signed
# in. When Sec-Fetch-Site says another origin started the navigation, a
# `?q=` is redirected away (303, same page without it) before auth runs,
# so the link cannot pre-fill the chat box. Runtime coverage:
# tests/chat/test_chat_page_routes.py. chat.py:_drop_foreign_chat_query.
("GET", "/chat/"): [303],
("GET", "/chat/{}"): [303],
# Offsets above 10,000 are rejected before reaching the database. Flask
# attempted the query (and could raise on values outside SQLite's integer
# range); ordinary offsets and non-integer fallback behavior are retained.
# test_pagination_clamping_census exercises the accepted boundary and the
# rejected requests for each route, rather than relying on this AST census.
("GET", "/api/history"): [400],
("GET", "/history/api"): [400],
("GET", "/library/api/documents"): [400],
# Chat pagination now rejects malformed, timezone-free, overflowing,
# and incomplete cursors with 400 instead of replaying the newest page
# or failing during DB binding. Runtime coverage: TestChatMessageAPI.
("GET", "/api/chat/sessions/{}/messages"): [400],
# Counterpart of the 302 entry above; same single behaviour.
("GET", "/auth/change-password"): [401],
("GET", "/news/health"): [401],
# The serialized rekey lifecycle (database/rekey_lock.py) maps typed
# operational failures to 503 so they do not masquerade as a form error
# or a 500. The 503 covers a retryable failure before anything was
# rekeyed (RekeyUnavailableError) and durable rekey state that needs the
# verified recovery path first (RekeyRecoveryRequiredError). An outcome
# left indeterminate AFTER the rekey ran (RekeyIndeterminateError)
# revokes every session and redirects to login like a success instead.
# web/routers/auth.py:change_password.
("POST", "/auth/change-password"): [503],
# Registration's auto-login answers 503 when the new account's session
# epoch cannot be read (RekeyOperationalError from create_session), as
# login does; the account itself stays created. auth.py:register.
("POST", "/auth/register"): [503],
# Intentional: an unimplemented endpoint answers 501 rather than letting
# a bare `except Exception` turn NotImplementedException into a 500.
("GET", "/news/api/categories"): [501],
# Legacy subscriptions can contain intervals outside today's scheduling
# bounds. Manual Run Now rejects them before dispatch and asks the user
# to edit the interval, rather than starting research with invalid state.
("POST", "/news/api/subscriptions/{}/run"): [400],
# Non-UUID collection ids used to be rendered into the page template
# unvalidated (stored-XSS vector); they now 404 before rendering.
# web/routers/rag.py:_validated_collection_id.
("GET", "/library/collections/{}"): [404],
("GET", "/library/collections/{}/upload"): [404],
# Not a behaviour change. Flask returned the same 400 from
# `jsonify(result), (200 if result.get("success") else 400)` -- a ternary
# the AST scan cannot read as a constant, so the Flask side records only
# its 401. The port spells the two branches out (it rebuilds the body
# from a key allowlist instead of forwarding the service dict), which is
# what makes the 400 visible to the scan. web/routers/zotero.py.
("POST", "/library/api/zotero/test"): [400],
# The legacy static-URL shim now rejects paths that a client or proxy
# could normalize outside `/static/` (dot/empty segments, backslashes,
# control characters) instead of redirecting them. Flask redirected
# unconditionally, so this 404 is new; existing assets are now served
# directly with 200 (#6641). Raised as `HTTPException(404)` so the app's
# shared 404 handler renders it. web/routers/research.py:redirect_static.
("GET", "/redirect-static/{:path}"): [404],
# An explicit `is_configured` pre-check before any Zotero network call.
# Two edge cases change outcome: a personal library with a missing API
# key used to surface as 401 (ZoteroAuthError) and is now 400, and
# `enabled=False` used to be ignored on these two endpoints and now
# 400s. Documented in changelog.d/3299.breaking.md. web/routers/zotero.py.
("GET", "/library/api/zotero/collections"): [400],
("GET", "/library/api/zotero/groups"): [400],
# Flask had no "resource not found" branch here and fell through to a
# generic 500; the port answers 404. A bug fix, undocumented.
# A PDF the storage size limit refuses answers 409 with a message that
# names the "Maximum PDF Size (MB)" setting (#6913); the text is kept.
("POST", "/library/api/download/{}"): [404, 409],
# Werkzeug applied MAX_CONTENT_LENGTH implicitly and Flask rendered it
# through `@app.errorhandler(413)`; FastAPI has no implicit gate, so
# the same cap is spelled out in the handler. Parity restored, not a
# new rejection.
("POST", "/library/api/collections/{}/upload"): [413],
# The migration now validates collection identifiers before dispatch and
# rejects malformed index-start requests with a clean client error.
("POST", "/library/api/collections/{}/index/start"): [400],
# Same 400 as the keyword search always produced, moved into a shared
# `_validated_query_and_limit` helper; the Flask side built it inline
# in a way the scan credits to the view.
("GET", "/library/search/api/keyword"): [400],
# The one deliberate reversal of a Flask behaviour: Flask swallowed
# every error here and returned 200 with `status: "success"` ("Return
# 200 to avoid breaking the UI"); the port returns a real 500 so the
# UI can tell "no data" from "this query failed". Documented in
# changelog.d/3299.breaking.md; a dashboard that treats any 200 as success
# will now surface an error where it used to show an empty chart.
("GET", "/metrics/api/cost-analytics"): [500],
# The download endpoint now rejects malformed journal-data requests at
# its FastAPI boundary instead of letting them reach the exporter.
("POST", "/metrics/api/journal-data/download"): [400],
# Explicit app.lock_settings guards now give every JSON settings mutator
# the same 403 contract instead of relying on a silent manager refusal.
("POST", "/settings/api/search-favorites/toggle"): [403],
("POST", "/settings/save_all_settings"): [403],
("PUT", "/settings/api/search-favorites"): [403],
# New branches (#5765): when the deletion cascade cannot drop a
# (currently hypothetical -- FAISS is the only shipping provider)
# server-backed vector collection, the index is not deleted and the
# route answers 503 (vector store unreachable, retryable) or 500
# (a failure a retry won't fix) instead of the sibling 404, so a retry
# layer doesn't read the failure as "already gone" and mark it deleted.
# Kept as literal `JSONResponse(..., status_code=...)` calls (like the
# existing literal 404 beside them) specifically so this scan sees
# them; library_delete.py:delete_collection_index.
("DELETE", "/library/api/collections/{}/index"): [500, 503],
# Mass-assignment fix: FolderManager.update_folder used to run a blind
# hasattr-gated setattr loop (accepting any field name, including
# SQLAlchemy internals). normalize_folder_update now allowlists
# updatable fields and type-validates each one before dispatch, 400ing
# a genuinely unexpected field name or a wrong-typed value instead of
# silently ignoring/misapplying it. The allowlisted id/created_at/
# updated_at read-modify-write echo (folder.to_dict()'s own output) is
# tolerated, not rejected -- this 400 is still reachable via any other
# unknown field or a type error (e.g. sort_order not an int).
# news_flask_api.py:update_folder, news/constants.py:normalize_folder_update.
("PUT", "/news/api/subscription/folders/{}"): [400],
}
# Routes whose Flask handler put an `error` key in a JSON body and whose
# FastAPI counterpart puts none. FastAPI's own error envelope is `detail`,
# so this is the shape change most likely to break a client silently.
EXPECTED_ERROR_KEY_DROPPED = [
# Documented individually in changelog.d/3299.breaking.md. Both of these
# replace Flask's hand-rolled
# `jsonify({"success": False, "error": "Not authenticated"}), 401`
# became `Depends(require_auth)` -> `{"detail": ...}`.
("GET", "/auth/integrity-check"),
("GET", "/notes/api/notes/ask-context"),
# Not a real change: /api/v1 is the documented programmatic API, and
# the app's HTTPException handler emits BOTH keys
# (`{"error": ..., "detail": ...}`) for any path under /api/v1
# precisely to keep existing scripts working. fastapi_app.py's
# handle_http_exception.
("GET", "/api/v1/"),
# The notes 413 body carried `{"success": False, "error": ...}`; these
# two are the same non-mutating-method scope change recorded in
# EXPECTED_STATUS_CODES_LOST, seen through the body-key lens.
("GET", "/notes/"),
("GET", "/notes/{}"),
]
# Anti-vacuity floors. A parity check that resolves nothing passes
# trivially, so every behavioural test asserts a lower bound on how much it
# actually compared. These are set just under the counts measured when the
# tables above were reviewed (308 shared routes, 141 parameter slots of
# which 8 int, 294 auth-gated routes, 305 routes with status codes on both
# sides, 191 routes whose Flask side emits an `error` key, 10 rules
# declared with a trailing slash). If an extraction breaks and starts
# yielding an empty or shrunken table, these fail loudly instead of the
# comparison silently succeeding against nothing.
MIN_SHARED_ROUTES = 300
MIN_PARAMETER_SLOTS = 135
MIN_INT_PARAMETER_SLOTS = 8
MIN_AUTH_GATED_ROUTES = 285
MIN_ROUTES_WITH_STATUS_CODES = 295
MIN_ROUTES_WITH_ERROR_KEY = 180
MIN_TRAILING_SLASH_RULES = 10
class TestRouteBehaviourParityAgainstFlaskSnapshot:
"""The behavioural layer. Always gates — the Flask side is the committed
snapshot, the FastAPI side is read off this branch's source tree.
`TestFastAPIRouteTableAgainstFlaskSnapshot` proves every Flask URL still
routes somewhere. These prove the thing routed to still answers the same
way, along the four axes a static reader can settle: HTTP methods, path
converters, trailing slashes, auth gates, status codes, and error-body
shape.
"""
def test_method_sets_match_per_path(self):
"""A Flask `methods=["GET", "POST"]` that became `@router.get` only
is a silent 405 for every POST client.
The (METHOD, path) diff in EXPECTED_REMOVED/EXPECTED_ADDED already
catches this — a lost method is a lost pair. This states it as its
own property so the failure message names the path and both method
sets instead of showing two unrelated-looking diff lines, and so
the dimension is visibly covered rather than covered by accident.
A deliberate verb move is recorded in
EXPECTED_METHOD_SET_DIVERGENCES, with both method sets written
out, on the same contract as every other table here: an
unreviewed divergence fails, and so does an entry that no longer
diverges (or diverges differently).
"""
flask_index, fastapi_index, _ = _matched_views()
flask_methods: dict[str, set[str]] = {}
for method, path in flask_index:
flask_methods.setdefault(path, set()).add(method)
fastapi_methods: dict[str, set[str]] = {}
for method, path in fastapi_index:
fastapi_methods.setdefault(path, set()).add(method)
shared = sorted(set(flask_methods) & set(fastapi_methods))
assert len(shared) >= MIN_SHARED_ROUTES - 30, (
f"only {len(shared)} paths exist on both sides; the extraction "
"is broken and this comparison is near-vacuous"
)
mismatches = [
(
path,
sorted(flask_methods[path]),
sorted(fastapi_methods[path]),
)
for path in shared
if flask_methods[path] != fastapi_methods[path]
]
reviewed = {
path
for path, flask, fastapi in mismatches
if EXPECTED_METHOD_SET_DIVERGENCES.get(path)
== (set(flask), set(fastapi))
}
unexpected = [m for m in mismatches if m[0] not in reviewed]
stale = sorted(set(EXPECTED_METHOD_SET_DIVERGENCES) - reviewed)
assert not unexpected and not stale, (
"these paths serve a different set of HTTP methods than Flask "
"did, and it was NOT reviewed. A method Flask accepted and "
"FastAPI does not is a 405 for any client still sending it:\n"
+ "\n".join(
f" {path}: Flask {flask} -> FastAPI {fastapi}"
for path, flask, fastapi in unexpected
)
+ "\n\nEXPECTED_METHOD_SET_DIVERGENCES entries whose two "
"method sets no longer diverge as recorded — prune or "
f"re-review these:\n{stale}"
)
def test_path_converter_types_match(self):
"""Flask `<int:x>` -> FastAPI `{x}` with no annotation widens what
the route accepts; the reverse 422s ids that used to work.
Greediness (`<path:x>` vs `{x:path}`) is deliberately NOT checked
here — `normalise()` folds it into the route key, so a greediness
change surfaces in the route-table diff instead (and one already
has: `/settings/api/<path:key>`).
"""
flask_index, fastapi_index, shared = _matched_views()
divergences = []
slots = 0
int_slots = 0
for key in shared:
for flask_view in flask_index[key]:
converters = [
(m.group(1), m.group(2))
for m in _FLASK_CONVERTER_RE.finditer(flask_view["path"])
]
if not converters:
continue
for fastapi_view in fastapi_index[key]:
names = [
m.group(1).split(":")[0]
for m in _PARAM_RE.finditer(fastapi_view["path"])
]
if len(names) != len(converters):
divergences.append(
(
*key,
-1,
flask_view["path"],
fastapi_view["path"],
)
)
continue
for index, ((converter, _), name) in enumerate(
zip(converters, names)
):
expected = _FLASK_CONVERTER_TO_ANNOTATION[converter]
# An unannotated FastAPI path parameter is a `str`.
actual = fastapi_view["params"].get(name) or "str"
slots += 1
if converter == "int":
int_slots += 1
if actual != expected:
divergences.append(
(
*key,
index,
converter or "string",
actual,
)
)
assert slots >= MIN_PARAMETER_SLOTS, (
f"only {slots} path-parameter slots were compared (expected at "
f"least {MIN_PARAMETER_SLOTS}); the converter extraction is "
"broken and this test is near-vacuous"
)
assert int_slots >= MIN_INT_PARAMETER_SLOTS, (
f"only {int_slots} Flask `<int:...>` slots were found (expected "
f"at least {MIN_INT_PARAMETER_SLOTS}); the int-widening failure "
"mode this test exists for is no longer being checked"
)
unexpected = sorted(
set(divergences) - set(EXPECTED_CONVERTER_DIVERGENCES)
)
stale = sorted(set(EXPECTED_CONVERTER_DIVERGENCES) - set(divergences))
assert not unexpected and not stale, (
"path-parameter types no longer agree with Flask's URL "
"converters.\nUnreviewed divergences (METHOD, path, slot, "
f"Flask converter, FastAPI annotation):\n{unexpected}\n"
f"EXPECTED_CONVERTER_DIVERGENCES entries that no longer "
f"diverge — prune them:\n{stale}"
)
def test_trailing_slash_rule_shapes_match(self):
"""Werkzeug redirects `/foo` -> `/foo/` for a rule declared with a
trailing slash, and 404s `/foo/` for one declared without.
Starlette's `redirect_slashes` redirects in BOTH directions, so it
is strictly more permissive — but only for rules whose declared
shape survived the port. A rule that lost its trailing slash (or
gained one) changes which URL is canonical and which is the
redirect, and any client that follows redirects sees a different
Location.
Two things are asserted: the set of rules declared WITH a trailing
slash is identical on both sides, and no source file turns
`redirect_slashes` off (which would take the Werkzeug-era
`/foo` -> `/foo/` redirect away from all of them at once).
Not checkable statically, reported instead: Werkzeug redirects with
308 for non-GET and Starlette with 307. Both preserve method and
body, so this is only visible to a client that inspects the status.
"""
flask_index, fastapi_index, _ = _matched_views()
flask_slashed = sorted(
key for key in flask_index if key[1].endswith("/") and key[1] != "/"
)
fastapi_slashed = sorted(
key
for key in fastapi_index
if key[1].endswith("/") and key[1] != "/"
)
assert len(flask_slashed) >= MIN_TRAILING_SLASH_RULES, (
f"only {len(flask_slashed)} trailing-slash rules found in the "
f"Flask snapshot (expected at least "
f"{MIN_TRAILING_SLASH_RULES}); extraction is broken"
)
assert flask_slashed == fastapi_slashed, (
"the set of routes DECLARED with a trailing slash changed. "
"Werkzeug and Starlette both redirect the other spelling, but "
"which URL is canonical (and therefore which one a redirect "
"points at) follows the declaration:\n"
f" only in Flask: {sorted(set(flask_slashed) - set(fastapi_slashed))}\n"
f" only in FastAPI: {sorted(set(fastapi_slashed) - set(flask_slashed))}"
)
disabled = sorted(
path.relative_to(REPO_ROOT).as_posix()
for path in [FASTAPI_APP_FILE, *ROUTERS_DIR.glob("*.py")]
if "redirect_slashes=False" in path.read_text(encoding="utf-8")
)
assert not disabled, (
"`redirect_slashes=False` appears in "
f"{disabled}. Starlette's slash redirect is the only thing "
"standing in for Werkzeug's `strict_slashes` behaviour; "
"turning it off 404s every client that hits the other "
f"spelling of these {len(flask_slashed)} rules."
)
def test_no_route_lost_its_auth_gate(self):
"""A route Flask required a login for that FastAPI does not is a
missing-authentication vulnerability. There is deliberately no
expectations table for this direction — the assertion is that the
set is empty."""
flask_index, fastapi_index, shared = _matched_views()
gated = [
key for key in shared if any(v["auth"] for v in flask_index[key])
]
assert len(gated) >= MIN_AUTH_GATED_ROUTES, (
f"only {len(gated)} of {len(shared)} shared routes read as "
f"auth-gated on the Flask side (expected at least "
f"{MIN_AUTH_GATED_ROUTES}); the `@login_required` extraction is "
"broken and this test would pass against an empty set"
)
lost = [
(key, _where(fastapi_index[key]))
for key in gated
if not any(v["auth"] for v in fastapi_index[key])
]
assert not lost, (
"these routes required authentication under Flask "
"(`@login_required`) and their FastAPI handlers declare no "
"`Depends(require_auth)`. Each one is reachable anonymously:\n"
+ "\n".join(f" {m} {p} -> {where}" for (m, p), where in lost)
)
def test_auth_gates_added_were_reviewed(self):
"""The other direction: a route that gained a gate 401s a caller
that used to work. Legitimate, but never silently."""
flask_index, fastapi_index, shared = _matched_views()
added = sorted(
key
for key in shared
if any(v["auth"] for v in fastapi_index[key])
and not any(v["auth"] for v in flask_index[key])
)
unexpected = sorted(set(added) - set(EXPECTED_AUTH_GATE_ADDED))
stale = sorted(set(EXPECTED_AUTH_GATE_ADDED) - set(added))
assert not unexpected and not stale, (
"authentication requirements changed without review.\n"
"Newly gated, not in EXPECTED_AUTH_GATE_ADDED (an anonymous "
f"caller that worked before now gets 401):\n{unexpected}\n"
"EXPECTED_AUTH_GATE_ADDED entries that are no longer newly "
f"gated — prune them:\n{stale}"
)
def test_status_codes_match_the_reviewed_table(self):
"""Explicit `return ..., 400` / `abort(403)` on the Flask side
against what the FastAPI handler can produce.
Read the scan's limits in the header comment above
`_FLASK_AUTH_DECORATORS` before adding to the tables: a "lost" code
is often a code that moved into a service layer, and the honest
resolution is to verify it by hand and record WHY, which is what
every entry in the two tables does.
"""
flask_index, fastapi_index, shared = _matched_views()
resolved = 0
lost: dict[tuple[str, str], list[int]] = {}
gained: dict[tuple[str, str], list[int]] = {}
for key in shared:
flask_codes = _union(flask_index[key], "status_codes")
fastapi_codes = _union(fastapi_index[key], "status_codes")
if flask_codes and fastapi_codes:
resolved += 1
missing = sorted(
c for c in flask_codes - fastapi_codes if 300 <= c < 600
)
extra = sorted(
c for c in fastapi_codes - flask_codes if 300 <= c < 600
)
if missing:
lost[key] = missing
if extra:
gained[key] = extra
assert resolved >= MIN_ROUTES_WITH_STATUS_CODES, (
f"only {resolved} of {len(shared)} shared routes yielded a "
"status code on BOTH sides (expected at least "
f"{MIN_ROUTES_WITH_STATUS_CODES}); the scan is broken and most "
"of this comparison is comparing empty sets"
)
problems = []
for label, live, reviewed in (
("no longer reachable", lost, EXPECTED_STATUS_CODES_LOST),
("newly reachable", gained, EXPECTED_STATUS_CODES_GAINED),
):
for key, codes in sorted(live.items()):
if reviewed.get(key) != codes:
problems.append(
f" {key[0]} {key[1]}: {codes} {label}, reviewed "
f"table says {reviewed.get(key)} "
f"({_where(fastapi_index[key])})"
)
for key in sorted(set(reviewed) - set(live)):
problems.append(
f" {key[0]} {key[1]}: reviewed as {label} "
f"{reviewed[key]}, but no longer diverges — prune it"
)
assert not problems, (
"status codes diverged from Flask outside the reviewed "
"tables:\n" + "\n".join(problems)
)
def test_error_body_key_did_not_silently_become_detail(self):
"""FastAPI's default error envelope is `{"detail": ...}`; Flask's
was `{"error": ...}` almost everywhere. A client doing
`response.json()["error"]` breaks with no status-code change to
warn it.
Scope, stated plainly: this compares which of `error` / `detail` /
`message` appear as literal dict keys anywhere in the handler (plus
the helpers `_scan_view` reaches). It catches a route that dropped
`error` entirely. It does NOT catch a route that kept an `error`
key on one branch while a different branch switched to `detail` —
several routes did exactly that for their 401, which
changelog.d/3299.breaking.md documents as intended.
"""
flask_index, fastapi_index, shared = _matched_views()
with_error = [
key
for key in shared
if "error" in _union(flask_index[key], "body_keys")
]
assert len(with_error) >= MIN_ROUTES_WITH_ERROR_KEY, (
f"only {len(with_error)} shared routes read as emitting an "
f"`error` key on the Flask side (expected at least "
f"{MIN_ROUTES_WITH_ERROR_KEY}); the body-key extraction is "
"broken and this test is near-vacuous"
)
dropped = sorted(
key
for key in with_error
if "error" not in _union(fastapi_index[key], "body_keys")
)
unexpected = sorted(set(dropped) - set(EXPECTED_ERROR_KEY_DROPPED))
stale = sorted(set(EXPECTED_ERROR_KEY_DROPPED) - set(dropped))
assert not unexpected and not stale, (
"JSON error-body shape changed outside the reviewed table.\n"
"Routes that emitted an `error` key under Flask and emit none "
"now — any client parsing `error` sees KeyError/None:\n"
+ "\n".join(
f" {m} {p} -> {_where(fastapi_index[(m, p)])}"
for m, p in unexpected
)
+ "\nEXPECTED_ERROR_KEY_DROPPED entries that no longer drop it "
f"— prune them: {stale}"
)