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:
@@ -4,6 +4,7 @@ from fastapi import APIRouter
|
||||
|
||||
from app.api.routes import (
|
||||
health,
|
||||
images,
|
||||
papers,
|
||||
reference_tags,
|
||||
references,
|
||||
@@ -13,6 +14,7 @@ from app.api.routes import (
|
||||
|
||||
api_router = APIRouter()
|
||||
api_router.include_router(health.router)
|
||||
api_router.include_router(images.router)
|
||||
api_router.include_router(papers.router)
|
||||
api_router.include_router(reference_tags.router)
|
||||
api_router.include_router(references.router)
|
||||
|
||||
@@ -0,0 +1,139 @@
|
||||
"""Image endpoints: put a figure in the bucket, and hand it back to the page.
|
||||
|
||||
The paper's sentences store pictures as Markdown — ```` —
|
||||
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",
|
||||
},
|
||||
)
|
||||
Reference in New Issue
Block a user