"""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", }, )