AI-Cognitive-Leap/agnes-the-ai-analyst
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(version): clarify APP_VERSION scope + middleware /api prefix rationale

Browse source
This commit is contained in:
ZdenekSrotyr 2026-05-06 15:29:20 +02:00
parent 57170bc556
commit af2b866961
2 changed files with 19 additions and 7 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
app/main.py
View file

@ -185,6 +185,8 @@ def create_app() -> FastAPI:
@app.middleware("http") @app.middleware("http")
async def _add_version_headers(request, call_next): async def _add_version_headers(request, call_next):
response = await call_next(request) response = await call_next(request)
# /api/* only — headers are advisory to the agnes CLI; UI/docs/marketplace
# traffic doesn't consume them.
if request.url.path.startswith("/api/"): if request.url.path.startswith("/api/"):
response.headers["X-Agnes-Latest-Version"] = APP_VERSION response.headers["X-Agnes-Latest-Version"] = APP_VERSION
response.headers["X-Agnes-Min-Version"] = MIN_COMPAT_CLI_VERSION response.headers["X-Agnes-Min-Version"] = MIN_COMPAT_CLI_VERSION

24
app/version.py
View file

@ -1,12 +1,22 @@
"""Single source of truth for app + CLI compat versions. """Version constants used by FastAPI's `version=` field and the
`X-Agnes-{Latest,Min}-Version` response-header middleware.
`APP_VERSION` is read from package metadata so it tracks `pyproject.toml` `APP_VERSION` reads from package metadata so it tracks `pyproject.toml`
without a manual literal to keep in sync. without a manual literal to keep in sync. **This is not a project-wide
single source of truth** — `AGNES_VERSION` env var (set by CI/Docker
builds) continues to drive `/api/version`, `/cli/install.sh`, and the
admin UI. Those call sites pre-date `app/version.py` and are out of scope
for this change.
`MIN_COMPAT_CLI_VERSION` is the oldest CLI version the server still accepts `MIN_COMPAT_CLI_VERSION` is the oldest CLI version the server advertises
on `/api/*`. Bumped manually when shipping a wire-protocol break. Day-one as compatible on `/api/*` response headers. Enforcement lives in the
value of "0.0.0" means no enforcement — set the floor the first time a client: `cli/client.py:_check_version_headers` exits the CLI when its
deliberate break ships. local version is below this floor. The middleware itself does not reject
requests — older clients just get a header they're free to ignore (in
practice, only the agnes CLI inspects it).
Day-one value of `MIN_COMPAT_CLI_VERSION` is `0.0.0` (no enforcement);
bumped manually when shipping a wire-protocol break.
""" """
from importlib.metadata import PackageNotFoundError from importlib.metadata import PackageNotFoundError