backend: keep a figure in the object store, and serve it back by key

A paper needs its experiment figures, and a figure is not text: the bytes go to
MinIO and the sentence keeps a Markdown address. That is what keeps a sentence
one editable string — a picture moves between paragraphs by being cut and
pasted, and survives a template switch with the sentence it belongs to.

Three decisions carry the safety, and each is a way to serve something other
than what was uploaded:

* the key is the digest of the bytes, so uploading the same screenshot twice is
  one object and the address can never come to mean a different picture — which
  is what makes the year-long `immutable` cache header safe;
* the format is sniffed from the magic bytes, not read from the client's
  `Content-Type` or filename, and SVG is refused because an uploaded SVG served
  from this origin is stored XSS;
* serving is restricted to the key space this application writes, so
  `GET /api/images/{key}` cannot become a browser for the rest of the bucket.

Images are served through the API rather than from a public bucket URL so a
sentence never embeds a host name — the LAN in development and the public
address later would otherwise disagree — and the bucket can stay private. The
object is streamed rather than read into memory, and the connection is released
when the reader stops.

Storage unconfigured is a 503 that names the missing variables, not a crash:
the writing path does not depend on the bucket.

`scripts/smoke_images.py` walks the whole thing: each accepted format, the
refusals (text, SVG, a mislabelled file, an empty file, a key we did not
write), and a sentence that carries a figure through the paper endpoints.
This commit is contained in:
2026-09-23 13:31:27 +08:00
parent e8e129221c
commit 6f37120dc4
11 changed files with 841 additions and 0 deletions
+15
View File
@@ -11,6 +11,7 @@ from fastapi.responses import JSONResponse
from app.api.router import api_router
from app.core.config import get_settings
from app.core.storage import StorageUnavailable
from app.crud.reference import UnknownReference
settings = get_settings()
@@ -43,3 +44,17 @@ async def unknown_reference_handler(
for a rejected request, so a client needs no special case.
"""
return JSONResponse(status_code=400, content={"detail": str(error)})
@app.exception_handler(StorageUnavailable)
async def storage_unavailable_handler(
request: Request, error: StorageUnavailable
) -> JSONResponse:
"""Answer an upload or a figure load when the object store cannot be used.
``503`` rather than ``500``: nothing about the request was wrong — the
service that holds the images is missing or unreachable, and the message
says which one so the fix is one configuration away. The writing itself is
unaffected, which is why this is not allowed to look like a crash.
"""
return JSONResponse(status_code=503, content={"detail": str(error)})