Files
paper-doc/backend/app/main.py
T
govin 6f37120dc4 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.
2026-09-23 13:31:27 +08:00

61 lines
1.9 KiB
Python

"""FastAPI application entry point.
Run locally with::
uvicorn app.main:app --reload --port 8000
"""
from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
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()
app = FastAPI(
title=settings.app_name,
debug=settings.debug,
)
app.add_middleware(
CORSMiddleware,
allow_origins=settings.cors_origins,
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
app.include_router(api_router, prefix=settings.api_prefix)
@app.exception_handler(UnknownReference)
async def unknown_reference_handler(
request: Request, error: UnknownReference
) -> JSONResponse:
"""Answer a citation to literature that is not in the library.
The refusal is raised deep in the data layer, where the ids are known, and
turned into the API's own vocabulary here rather than at every route that
might write a citation. The body matches what the rest of the API returns
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)})