Files
paper-doc/backend/app/api/routes/images.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

140 lines
4.9 KiB
Python

"""Image endpoints: put a figure in the bucket, and hand it back to the page.
The paper's sentences store pictures as Markdown — ``![图注](/api/images/…)`` —
which is what keeps a sentence one editable string and what lets a model insert
a figure through the same API it already writes text with. This module is the
other half of that: the place the bytes go, and the place they come back from.
Uploading is one request and answers with the Markdown as well as the URL, so a
client never has to assemble the syntax itself. Serving is by *key*, restricted
to the keys this application writes (see :mod:`app.core.storage`), and streams
from the bucket rather than loading the object into memory — an experiment
figure is a megabyte or two and several of them appear on one screen.
"""
from pathlib import Path
from fastapi import APIRouter, File, HTTPException, UploadFile, status
from fastapi.responses import StreamingResponse
from app.core.config import get_settings
from app.core.storage import (
ImageNotFound,
UnsupportedImage,
content_type_for,
get_store,
image_url,
markdown_for,
)
from app.schemas.image import ImageRead
router = APIRouter(prefix="/images", tags=["images"])
settings = get_settings()
_READ_CHUNK = 1024 * 1024
def _read_capped(handle, limit: int) -> bytes:
"""Read one upload whole, refusing it the moment it passes ``limit``.
Read in pieces rather than with a single ``read()`` so an oversized file is
rejected after the first megabyte instead of after all of it.
"""
pieces: list[bytes] = []
total = 0
while True:
piece = handle.read(_READ_CHUNK)
if not piece:
break
total += len(piece)
if total > limit:
raise HTTPException(
status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
detail=(
f"图片太大了,超过 {limit // (1024 * 1024)} MB 上限。"
"先压缩或裁剪一下再上传。"
),
)
pieces.append(piece)
return b"".join(pieces)
@router.post(
"",
response_model=ImageRead,
status_code=status.HTTP_201_CREATED,
summary="Upload an image",
)
def upload_image(
file: UploadFile = File(..., description="图片文件:PNG / JPEG / GIF / WebP"),
) -> ImageRead:
"""Store one image and return the Markdown that embeds it.
The declared content type is not trusted and neither is the filename: the
format is decided from the file's own magic bytes, and the stored key comes
from the content's digest. Uploading the same picture again is therefore not
a duplicate — it is the same object, and a sentence that already points at
it keeps working.
"""
data = _read_capped(file.file, settings.max_image_bytes)
if not data:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="上传的文件是空的。",
)
try:
key, content_type, digest = get_store().save(data)
except UnsupportedImage as error:
raise HTTPException(
status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
detail=str(error),
) from error
# The filename's stem becomes the caption's starting point: a screenshot is
# usually already named after what it shows, and the writer edits the
# brackets afterwards.
caption = Path(file.filename or "").stem
return ImageRead(
key=key,
url=image_url(key),
markdown=markdown_for(key, caption),
content_type=content_type,
size=len(data),
sha256=digest,
)
@router.get("/{key:path}", summary="Serve an image")
def read_image(key: str) -> StreamingResponse:
"""Stream one image out of the bucket.
Served from this origin, so the URL in a sentence does not name a host that
differs between the LAN and the public address, and the bucket never has to
be made world-readable for the paper to show its figures.
"""
try:
chunks, content_type, length = get_store().stream(key)
except ImageNotFound as error:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="没有这张图片:地址不对,或者它已经不在存储里了。",
) from error
return StreamingResponse(
chunks,
media_type=content_type or content_type_for(key) or "application/octet-stream",
headers={
# The key is the digest of the bytes, so this URL can never come to
# mean a different picture — a year is safe, and it saves the paper
# from re-fetching every figure on every scroll.
"Cache-Control": "public, max-age=31536000, immutable",
"Content-Length": str(length),
# The type is from our own whitelist, never from the upload; this
# stops a browser from second-guessing it.
"X-Content-Type-Options": "nosniff",
},
)