Error bodies carry both keys, and /healthz can stand down

Both found by adopting the shell in scribe, which is older than chrome and
had conventions of its own.

chrome answered an API error with {"error": ...}. FastAPI's convention is
{"detail": ...}, and scribe's client reads exactly that:

    msg = (await r.json()).detail || msg

A missing key there does not fail - it falls back to r.statusText, so every
error message in the UI quietly becomes "Bad Request" and the real reason
is lost. That is the worst shape for a regression: no exception, no failing
request, just worse text. Both keys are sent now. marketplace and
agent-bridge read `error` and are unaffected.

chrome also registers /healthz, and being registered first it won over
scribe's - which reports whether whisper, piper and xtts are reachable,
the thing actually worth knowing when scribe is unwell. `health=False`
lets a service keep its own, the same way language_switcher=False already
lets it keep its own language control.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Michał Kopeć 2026-10-04 20:54:24 +02:00
parent 9277e344ec
commit 039b6f3711
5 changed files with 44 additions and 7 deletions

View file

@ -78,7 +78,7 @@ Pin a tag, not a branch:
```toml
dependencies = [
"chrome @ git+https://git.wierzbowa.cloud/michal/chrome@v0.5.0",
"chrome @ git+https://git.wierzbowa.cloud/michal/chrome@v0.6.0",
]
```

View file

@ -7,7 +7,7 @@ need an `if service == "marketplace"`, it belongs in the service.
from pathlib import Path
__version__ = "0.5.0"
__version__ = "0.6.0"
PACKAGE_DIR = Path(__file__).parent
STATIC_DIR = PACKAGE_DIR / "static"

View file

@ -25,6 +25,19 @@ from starlette.exceptions import HTTPException as StarletteHTTPException
from . import STATIC_DIR, TEMPLATES_DIR, WEBAWESOME_VERSION, assets, i18n
def _error_body(detail: object) -> dict:
"""A JSON error carrying both conventional keys.
chrome started with `error`, and marketplace and agent-bridge read that.
FastAPI's own convention is `detail`, and scribe's client was written
against it long before chrome existed - `(await r.json()).detail || msg`,
which degrades every error message in its UI to "Bad Request" if the key
is missing. Sending both costs a few bytes and spares two codebases a
rewrite over a naming difference.
"""
return {"error": detail, "detail": detail}
def _safe_local(target: str | None) -> str | None:
"""``target`` if it is a local path, else None.
@ -77,6 +90,7 @@ class Chrome:
mount_prefix: str = "",
static_path: str = "/static",
language_switcher: bool = True,
health: bool = True,
) -> None:
self.app = app
self.service = service
@ -132,7 +146,11 @@ class Chrome:
#: object taken out of it. Takes a Request, returns a dict.
self.page_context = None
app.include_router(health_router(service, version))
# A service with a richer probe of its own keeps it - scribe's
# reports which speech engines it can reach, which is the thing
# worth knowing when it is unwell.
if health:
app.include_router(health_router(service, version))
self._install_language_route()
self._install_error_pages()
@ -225,7 +243,7 @@ class Chrome:
if request.url.path.startswith(("/api/", "/healthz")):
from fastapi.responses import JSONResponse
return JSONResponse({"error": exc.detail}, status_code=exc.status_code)
return JSONResponse(_error_body(exc.detail), status_code=exc.status_code)
key = "404" if exc.status_code == 404 else "500"
locale = self.translations.locale_for(request)
return self.render(

View file

@ -1,6 +1,6 @@
[project]
name = "chrome"
version = "0.5.0"
version = "0.6.0"
description = "Shared page shell, design tokens and service helpers for the internal services."
requires-python = ">=3.13"
dependencies = [

View file

@ -80,10 +80,15 @@ def test_html_errors_render_the_themed_page(client):
assert "error-code" in r.text and "Test Service" in r.text
def test_api_errors_stay_json(client):
def test_api_errors_stay_json_under_both_conventional_keys(client):
"""`error` is what chrome started with and what marketplace and
agent-bridge read; `detail` is FastAPI's own, which scribe's client was
written against years earlier. Sending both spares a rewrite over a
naming difference - and a client reading the missing one degrades
silently to the HTTP status text, which is the worst way to find out."""
r = client.get("/api/boom")
assert r.status_code == 404
assert r.json() == {"error": "no such thing"}
assert r.json() == {"error": "no such thing", "detail": "no such thing"}
def test_language_cookie_round_trips(client):
@ -373,3 +378,17 @@ def test_a_service_can_supply_its_own_language_control(tmp_path):
assert "data-lang-select" not in without
# Only the language control stands down; the theme toggle is unaffected.
assert "data-theme-choice" in without
def test_a_service_can_keep_its_own_health_probe(tmp_path):
"""scribe's reports which speech engines it can reach, which is the
thing worth knowing when it is unwell. chrome's would otherwise win by
being registered first."""
app = FastAPI()
Chrome(app, service="t", version="1", title="T", health=False)
@app.get("/healthz")
def healthz():
return {"ok": True, "engine": "reachable"}
assert TestClient(app).get("/healthz").json() == {"ok": True, "engine": "reachable"}