diff --git a/backend/.env.example b/backend/.env.example index 51b38a7..b588989 100644 --- a/backend/.env.example +++ b/backend/.env.example @@ -17,3 +17,18 @@ DB_NAME=paper_doc # The password must be percent-encoded (a raw '@' would be parsed as the # user/host separator). Prefer the DB_* parts above and let the app encode it. # DATABASE_URL=mysql+pymysql://Govin:change-me%40123@192.168.1.88:32738/paper_doc + +# --- Object storage (MinIO) — where the images a paper embeds are kept --- +# Leave these empty and the paper still writes and reads; only the image +# endpoints answer 503, saying exactly which variables are missing. +# The bucket is created on the first upload if it does not exist yet, so a +# dedicated access key with read/write on that one bucket is enough. +# Inside the cluster, use the Service: http://minio.minio.svc.cluster.local:9000 +MINIO_ENDPOINT=http://192.168.1.88:30090 +MINIO_ACCESS_KEY=change-me +MINIO_SECRET_KEY=change-me +MINIO_BUCKET=paper-images +MINIO_REGION=us-east-1 + +# Largest image accepted, in bytes (default 20 MiB). +# MAX_IMAGE_BYTES=20971520 diff --git a/backend/app/api/router.py b/backend/app/api/router.py index df4f0d0..77edc1f 100644 --- a/backend/app/api/router.py +++ b/backend/app/api/router.py @@ -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) diff --git a/backend/app/api/routes/images.py b/backend/app/api/routes/images.py new file mode 100644 index 0000000..cfd01d3 --- /dev/null +++ b/backend/app/api/routes/images.py @@ -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 — ``![图注](/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", + }, + ) diff --git a/backend/app/core/config.py b/backend/app/core/config.py index 8ae3387..c355a98 100644 --- a/backend/app/core/config.py +++ b/backend/app/core/config.py @@ -53,6 +53,24 @@ class Settings(BaseSettings): db_pool_pre_ping: bool = True db_pool_recycle: int = 3600 + # --- Object storage (MinIO) ------------------------------------------ + # + # Where the images a paper embeds are kept. Empty by default rather than + # pointed at a plausible host: a wrong-but-set address fails as a timeout + # deep inside boto3, while an empty one fails immediately and says which + # variables are missing. The bucket is created on first upload if it is not + # there, so a fresh deployment needs the credentials and nothing else. + minio_endpoint: str = "" + minio_access_key: str = "" + minio_secret_key: str = "" + minio_bucket: str = "paper-images" + minio_region: str = "us-east-1" + + #: Largest image accepted, in bytes. An experiment figure is a few hundred + #: kilobytes; the ceiling is here to stop a mistake (a raw TIFF, a video) + #: from filling the bucket, not to be hit in normal use. + max_image_bytes: int = 20 * 1024 * 1024 + @property def sqlalchemy_url(self) -> Union[URL, str]: """The SQLAlchemy connection URL. diff --git a/backend/app/core/storage.py b/backend/app/core/storage.py new file mode 100644 index 0000000..676f191 --- /dev/null +++ b/backend/app/core/storage.py @@ -0,0 +1,298 @@ +"""Object storage for the images a paper embeds (MinIO, spoken over S3). + +An image is not text, so it does not live in the database: the sentence keeps a +short URL and the bytes live in the bucket. That split is what keeps a sentence +editable as one string — the writer can move a figure between paragraphs by +cutting and pasting text, and the object itself never has to move. + +Three decisions are worth stating, because each of them is a way to serve +something other than what was uploaded: + +* **The key is content-addressed.** ``2026/09/9f8c1a4b7e2d0c33.png`` is derived + from the bytes, so uploading the same screenshot twice stores one object, and + a URL cannot quietly come to mean a *different* picture than the one it was + written for. That is also what makes the year-long ``immutable`` cache header + safe to hand out. +* **The format is sniffed, not trusted.** The upload's ``Content-Type`` and its + filename are the client's claims; the magic bytes are the fact. Only formats a + browser draws in an ```` are accepted, and SVG is deliberately not among + them — an uploaded SVG served from this origin is stored XSS. +* **Images are served from our own path.** ``/api/images/{key}`` streams the + object, so a paper never embeds a host name that differs between the LAN and + the public address, and the bucket can stay private. +""" + +from __future__ import annotations + +import hashlib +import re +from contextlib import contextmanager +from datetime import datetime, timezone +from functools import lru_cache +from typing import Iterator + +import boto3 +from botocore.client import Config +from botocore.exceptions import BotoCoreError, ClientError + +from app.core.config import Settings, get_settings + + +class StorageUnavailable(RuntimeError): + """The object store is not configured, or could not be reached.""" + + +class UnsupportedImage(ValueError): + """The uploaded bytes are not a picture we are willing to store.""" + + +class ImageNotFound(KeyError): + """No image is stored under that key.""" + + +#: Sniffed format -> how the object is stored. Every format listed is one a +#: browser renders; the extension is what the key ends in, and it is also how +#: the content type is decided again when the object is served. +IMAGE_FORMATS: dict[str, tuple[str, str]] = { + "png": ("image/png", ".png"), + "jpeg": ("image/jpeg", ".jpg"), + "gif": ("image/gif", ".gif"), + "webp": ("image/webp", ".webp"), +} + +#: The shape of a key this application writes: ``YYYY/MM/<16 hex>``. +#: +#: Serving is restricted to it, so the read endpoint cannot be turned into a +#: browser for the rest of the bucket — a request for anything this module did +#: not store is a 404, whatever else happens to be in there. +KEY_PATTERN = re.compile(r"^\d{4}/\d{2}/[0-9a-f]{16}\.(?:png|jpg|gif|webp)$") + +#: Content type by extension, for serving. A whitelist rather than a parse of +#: whatever the object's metadata says. +CONTENT_TYPE_BY_EXTENSION: dict[str, str] = { + ".png": "image/png", + ".jpg": "image/jpeg", + ".gif": "image/gif", + ".webp": "image/webp", +} + +#: How much of a key's digest goes into it. 64 bits of SHA-256: a collision +#: would need more distinct images than a paper will ever hold, and 16 hex +#: characters keep the URL short enough to read in a sentence. +DIGEST_CHARS = 16 + +_CHUNK = 64 * 1024 + + +def sniff(data: bytes) -> str: + """Name the format of ``data``, or refuse it. + + Returns a key of :data:`IMAGE_FORMATS`. The check is on the leading bytes + because that is the only part of the claim the uploader cannot choose. + """ + if data.startswith(b"\x89PNG\r\n\x1a\n"): + return "png" + if data.startswith(b"\xff\xd8\xff"): + return "jpeg" + if data.startswith((b"GIF87a", b"GIF89a")): + return "gif" + if data[:4] == b"RIFF" and data[8:12] == b"WEBP": + return "webp" + + raise UnsupportedImage( + "只接受 PNG / JPEG / GIF / WebP 图片,这个文件的格式无法识别。" + "(SVG 不支持:它会在页面上执行脚本。)" + ) + + +def is_key(key: str) -> bool: + """Whether ``key`` has the shape this application stores.""" + return bool(KEY_PATTERN.match(key)) + + +def content_type_for(key: str) -> str | None: + """The content type to serve ``key`` as, or ``None`` if we would not serve it.""" + if not is_key(key): + return None + return CONTENT_TYPE_BY_EXTENSION.get(f".{key.rsplit('.', 1)[-1].lower()}") + + +def image_url(key: str, settings: Settings | None = None) -> str: + """The URL a sentence stores for ``key``. + + Relative on purpose: the paper is read from the LAN in development and from + the public name later, and a sentence that hard-coded either would break on + the other. The prefix comes from the API settings, so it follows the mount + point instead of being spelled out twice. + """ + settings = settings or get_settings() + return f"{settings.api_prefix}/images/{key}" + + +def markdown_for(key: str, caption: str = "", settings: Settings | None = None) -> str: + """The Markdown a writer (or a model) pastes into a sentence. + + Generating it here rather than in each client is the same argument as + numbering citations on the server: the syntax is one rule, and two + implementations of a rule eventually disagree. + """ + safe = caption.replace("[", "(").replace("]", ")").replace("(", "(").replace(")", ")") + return f"![{safe.strip()}]({image_url(key, settings)})" + + +class ImageStore: + """The bucket, seen through the four operations the API needs.""" + + def __init__(self, settings: Settings) -> None: + self._settings = settings + self._client = None + + @property + def bucket(self) -> str: + return self._settings.minio_bucket + + @property + def endpoint(self) -> str: + return self._settings.minio_endpoint or "(未配置)" + + # --- connection ------------------------------------------------------ + def _require(self) -> None: + """Refuse early, and in the API's words, when storage is not set up. + + A missing configuration is an operator's mistake, not the caller's, so + it must not surface as a stack trace from deep inside boto3. + """ + settings = self._settings + if not ( + settings.minio_endpoint + and settings.minio_access_key + and settings.minio_secret_key + ): + raise StorageUnavailable( + "图片存储还没有配置好(缺少 MINIO_ENDPOINT / MINIO_ACCESS_KEY / " + "MINIO_SECRET_KEY),暂时不能上传图片。" + ) + + def client(self): + """The boto3 client, built on first use so importing costs nothing.""" + self._require() + if self._client is None: + self._client = boto3.client( + "s3", + endpoint_url=self._settings.minio_endpoint, + aws_access_key_id=self._settings.minio_access_key, + aws_secret_access_key=self._settings.minio_secret_key, + region_name=self._settings.minio_region, + config=Config(signature_version="s3v4", retries={"max_attempts": 3}), + ) + return self._client + + def _unavailable(self, error: Exception) -> StorageUnavailable: + """Restate a boto3 failure as something a person can act on.""" + if isinstance(error, ClientError): + code = error.response.get("Error", {}).get("Code", "unknown") + return StorageUnavailable( + f"对象存储返回错误 {code}({self.endpoint},桶 {self.bucket}):{error}" + ) + return StorageUnavailable(f"连不上对象存储 {self.endpoint}:{error}") + + @contextmanager + def _translated(self): + """Let boto3's exception vocabulary stop at this module's boundary.""" + try: + yield + except (BotoCoreError, ClientError) as error: + raise self._unavailable(error) from error + + # --- operations ------------------------------------------------------ + def ensure_bucket(self) -> None: + """Create the bucket if it is not there yet. + + The bucket is normally made once by whoever deploys, but a missing one + is an easy mistake to make and a tedious one to diagnose. Making it on + first use costs one HEAD on an upload and turns that mistake into a + working upload. + """ + client = self.client() + try: + client.head_bucket(Bucket=self.bucket) + return + except ClientError as error: + code = error.response.get("Error", {}).get("Code", "") + if code not in {"404", "NoSuchBucket", "NotFound"}: + raise self._unavailable(error) from error + + try: + client.create_bucket(Bucket=self.bucket) + except ClientError as error: + # Two uploads racing on a fresh deployment: one of them creates the + # bucket, the other is told it exists. Neither is a failure. + code = error.response.get("Error", {}).get("Code", "") + if code not in {"BucketAlreadyOwnedByYou", "BucketAlreadyExists"}: + raise self._unavailable(error) from error + + def save(self, data: bytes) -> tuple[str, str, str]: + """Store ``data`` and return ``(key, content_type, sha256)``. + + Storing is idempotent: the key comes from the bytes, so the same picture + uploaded from two paragraphs — or twice by mistake — is one object. + """ + self._require() + + digest = hashlib.sha256(data).hexdigest() + content_type, extension = IMAGE_FORMATS[sniff(data)] + stamp = datetime.now(timezone.utc) + key = f"{stamp:%Y/%m}/{digest[:DIGEST_CHARS]}{extension}" + + with self._translated(): + self.ensure_bucket() + self.client().put_object( + Bucket=self.bucket, + Key=key, + Body=data, + ContentType=content_type, + # Safe because the key is the content's digest: these bytes can + # never be replaced by different bytes under the same URL. + CacheControl="public, max-age=31536000, immutable", + ) + return key, content_type, digest + + def stream(self, key: str) -> tuple[Iterator[bytes], str, int]: + """Open ``key`` for serving, as ``(chunks, content_type, length)``.""" + self._require() + + content_type = content_type_for(key) + if content_type is None: + raise ImageNotFound(key) + + try: + response = self.client().get_object(Bucket=self.bucket, Key=key) + except ClientError as error: + code = error.response.get("Error", {}).get("Code", "") + if code in {"NoSuchKey", "NoSuchBucket", "404", "NotFound"}: + raise ImageNotFound(key) from error + raise self._unavailable(error) from error + except BotoCoreError as error: + raise self._unavailable(error) from error + + body = response["Body"] + return _closing_chunks(body), content_type, int(response.get("ContentLength") or 0) + + +def _closing_chunks(body, chunk: int = _CHUNK) -> Iterator[bytes]: + """Hand out the object's bytes and release the connection when done. + + boto3's body is a stream on a socket from the pool; a response that is + abandoned without closing it leaks that connection until the pool is empty. + """ + try: + for piece in body.iter_chunks(chunk): + yield piece + finally: + body.close() + + +@lru_cache +def get_store() -> ImageStore: + """Return the process-wide store.""" + return ImageStore(get_settings()) diff --git a/backend/app/main.py b/backend/app/main.py index d178966..d3ea879 100644 --- a/backend/app/main.py +++ b/backend/app/main.py @@ -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)}) diff --git a/backend/app/schemas/__init__.py b/backend/app/schemas/__init__.py index d0de746..7e9b3a4 100644 --- a/backend/app/schemas/__init__.py +++ b/backend/app/schemas/__init__.py @@ -6,6 +6,7 @@ from app.schemas.common import ( PageResult, normalize_hex_color, ) +from app.schemas.image import ImageRead from app.schemas.paper import ( CitationInput, CitationRead, @@ -57,6 +58,7 @@ from app.schemas.template_title import ( __all__ = [ "BatchDeleteRequest", + "ImageRead", "ReferenceAuthorInput", "ReferenceAuthorRead", "ReferenceCitationRead", diff --git a/backend/app/schemas/image.py b/backend/app/schemas/image.py new file mode 100644 index 0000000..bdb73a6 --- /dev/null +++ b/backend/app/schemas/image.py @@ -0,0 +1,20 @@ +"""The shape an upload answers with.""" + +from pydantic import BaseModel, Field + + +class ImageRead(BaseModel): + """One stored image, as the client needs to know about it. + + The caller gets the URL *and* the Markdown that embeds it, because those are + the two things it needs and only one of them is pleasant to assemble by + hand. They are produced together here so a client cannot invent a slightly + different syntax than the one the reader parses. + """ + + key: str = Field(description="对象在桶里的键,也是这个 URL 的唯一来源") + url: str = Field(description="句子里的图片地址(同源相对路径,如 /api/images/…)") + markdown: str = Field(description="可直接粘进句子的 Markdown:![图注](地址)") + content_type: str = Field(description="识别出来的图片类型,如 image/png") + size: int = Field(description="字节数") + sha256: str = Field(description="内容的 SHA-256,键就是它的一部分") diff --git a/backend/requirements.txt b/backend/requirements.txt index 176c4e7..21a993d 100644 --- a/backend/requirements.txt +++ b/backend/requirements.txt @@ -5,6 +5,11 @@ alembic>=1.14 pymysql>=1.1 cryptography>=43.0 pydantic-settings>=2.6 +# Object storage for the images a paper embeds (app/core/storage.py). boto3 is +# the S3 client; python-multipart is what FastAPI needs to parse an upload at +# all — without it a multipart route fails when the app is imported. +boto3>=1.35 +python-multipart>=0.0.20 # MCP server (app/mcp/) — the same domain layer, exposed as MCP tools for # Claude Code, Codex and the DeepSeek Harness. Only the MCP entry points need # it; the REST API does not import it. diff --git a/backend/scripts/smoke_images.py b/backend/scripts/smoke_images.py new file mode 100644 index 0000000..8156126 --- /dev/null +++ b/backend/scripts/smoke_images.py @@ -0,0 +1,327 @@ +"""End-to-end smoke test for images (插图), against a running API. + +Run it while the backend is up, with MinIO reachable:: + + .venv/bin/python scripts/smoke_images.py + +It uploads pictures of each accepted format, fetches them back byte for byte, +checks the refusals (a text file, an SVG, an empty file, a key we did not +write), and then writes a sentence that embeds a figure to prove the paper's +own endpoints carry image Markdown through untouched. Exits non-zero on the +first failed expectation, so it is usable as a gate. + +Nothing needs cleaning up afterwards, and that is the point of the design being +tested: a key is the digest of the picture, so a second run stores the same +objects rather than more copies of them. +""" + +from __future__ import annotations + +import base64 +import hashlib +import json +import re +import struct +import sys +import urllib.error +import urllib.parse +import urllib.request +import zlib +from typing import Any + +BASE = "http://127.0.0.1:8000/api" +#: The origin the API is mounted on. An image URL comes back as `/api/images/…` +#: — the path a *browser* uses — so fetching one has to join it to the origin +#: rather than to the API prefix, or it asks for `/api/api/images/…`. +ROOT = "http://127.0.0.1:8000" + +KEY_PATTERN = re.compile(r"^\d{4}/\d{2}/[0-9a-f]{16}\.(?:png|jpg|gif|webp)$") + +_checks = 0 + + +def call(method: str, path: str, body: Any = None, expect: int = 200) -> Any: + """Perform one JSON API call and assert its status code.""" + data = json.dumps(body).encode() if body is not None else None + url = BASE + urllib.parse.quote(path, safe="/?&=%") + request = urllib.request.Request( + url, + data=data, + method=method, + headers={"Content-Type": "application/json"}, + ) + status, payload, _ = _send(request) + if status != expect: + raise AssertionError(f"{method} {path} -> {status}, expected {expect}: {payload[:300]}") + return json.loads(payload) if payload else None + + +def _send(request: urllib.request.Request): + """Send a request and return ``(status, text body, headers)`` whatever happens. + + The headers are handed over as the live mapping rather than as a ``dict``: + uvicorn writes them lower-cased, and a plain dict lookup for + ``Content-Type`` would miss them. + """ + try: + with urllib.request.urlopen(request, timeout=60) as response: + return response.status, response.read().decode("utf-8", "replace"), response.headers + except urllib.error.HTTPError as error: + return error.code, error.read().decode("utf-8", "replace"), error.headers + + +def upload( + filename: str, + data: bytes, + content_type: str = "application/octet-stream", + expect: int = 201, +) -> Any: + """POST one file as ``multipart/form-data``, which is what a browser sends. + + Built by hand rather than with `requests`, so this script needs nothing the + project does not already install. + """ + boundary = "----paperdocsmokeboundary" + head = ( + f"--{boundary}\r\n" + f'Content-Disposition: form-data; name="file"; filename="{filename}"\r\n' + f"Content-Type: {content_type}\r\n\r\n" + ).encode() + body = head + data + f"\r\n--{boundary}--\r\n".encode() + request = urllib.request.Request( + BASE + "/images", + data=body, + method="POST", + headers={"Content-Type": f"multipart/form-data; boundary={boundary}"}, + ) + status, payload, _ = _send(request) + if status != expect: + raise AssertionError(f"upload {filename} -> {status}, expected {expect}: {payload[:300]}") + return json.loads(payload) if payload else None + + +def fetch(path: str, expect: int = 200): + """GET an application path (``/api/images/…``) and return its bytes and headers.""" + request = urllib.request.Request(ROOT + path, method="GET") + try: + with urllib.request.urlopen(request, timeout=30) as response: + status, headers, body = response.status, response.headers, response.read() + except urllib.error.HTTPError as error: + status, headers, body = error.code, error.headers, error.read() + if status != expect: + raise AssertionError(f"GET {path} -> {status}, expected {expect}") + return body, headers + + +def check(label: str, condition: bool, detail: str = "") -> None: + """Assert one expectation and report it.""" + global _checks + _checks += 1 + if not condition: + raise AssertionError(f"{label}: {detail}") + print(f" ok {label}") + + +# --- the files under test ---------------------------------------------------- + + +def make_png(width: int = 240, height: int = 160) -> bytes: + """A real PNG: a gradient, so two of them differ and compression is honest.""" + + def chunk(tag: bytes, payload: bytes) -> bytes: + body = tag + payload + return struct.pack(">I", len(payload)) + body + struct.pack(">I", zlib.crc32(body) & 0xFFFFFFFF) + + rows = bytearray() + for y in range(height): + rows.append(0) # filter: none + for x in range(width): + rows += bytes(((x * 255) // max(width - 1, 1), (y * 255) // max(height - 1, 1), 128)) + + header = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0) + return ( + b"\x89PNG\r\n\x1a\n" + + chunk(b"IHDR", header) + + chunk(b"IDAT", zlib.compress(bytes(rows), 9)) + + chunk(b"IEND", b"") + ) + + +#: A 1x1 GIF and a 1x1 JPEG: the smallest real files of each format, which is +#: all that is needed to prove the format is recognised and stored as itself. +GIF_1PX = base64.b64decode("R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7") +JPEG_1PX = base64.b64decode( + "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0a" + "HBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAABAAEBAREA/8QAFAABAAAAAAAA" + "AAAAAAAAAAAACf/EABQQAQAAAAAAAAAAAAAAAAAAAAD/2gAIAQEAAD8AKp//2Q==" +) + +SVG = b'' + + +def main() -> int: + created_papers: list[int] = [] + + try: + png = make_png() + check("the fixture is a PNG", png.startswith(b"\x89PNG")) + check("the JPEG fixture starts like a JPEG", JPEG_1PX.startswith(b"\xff\xd8\xff")) + check("the GIF fixture starts like a GIF", GIF_1PX.startswith(b"GIF89a")) + + print("1. upload a PNG") + image = upload("试验装置.png", png, "image/png") + key = image["key"] + check("key has the shape we serve", bool(KEY_PATTERN.match(key)), key) + check("key ends in .png", key.endswith(".png"), key) + check("url is same-origin", image["url"] == f"/api/images/{key}", image["url"]) + check( + "markdown embeds the url, caption from the filename", + image["markdown"] == f"![试验装置](/api/images/{key})", + image["markdown"], + ) + check("content type sniffed", image["content_type"] == "image/png", image["content_type"]) + check("size reported", image["size"] == len(png), f"{image['size']} != {len(png)}") + check( + "sha256 is the content's", + image["sha256"] == hashlib.sha256(png).hexdigest(), + image["sha256"], + ) + check("the digest is in the key", image["sha256"][:16] in key, key) + + print("2. fetch it back") + body, headers = fetch(image["url"]) + check("bytes identical", body == png, f"{len(body)} != {len(png)}") + check( + "served as image/png", + headers.get("Content-Type") == "image/png", + headers.get("Content-Type", ""), + ) + check( + "immutable cache header", + "immutable" in headers.get("Cache-Control", ""), + headers.get("Cache-Control", ""), + ) + check( + "nosniff", + headers.get("X-Content-Type-Options") == "nosniff", + headers.get("X-Content-Type-Options", ""), + ) + check( + "content-length matches", + headers.get("Content-Length") == str(len(png)), + headers.get("Content-Length", ""), + ) + + print("3. the same bytes are the same object") + again = upload("another-name.png", png, "image/png") + check("same key", again["key"] == key, f"{again['key']} != {key}") + check( + "the caption follows the name given this time", + again["markdown"] == f"![another-name](/api/images/{key})", + again["markdown"], + ) + + print("4. the other formats") + gif = upload("图.gif", GIF_1PX, "image/gif") + check("gif key", gif["key"].endswith(".gif"), gif["key"]) + check("gif type", gif["content_type"] == "image/gif", gif["content_type"]) + check("gif bytes", fetch(gif["url"])[0] == GIF_1PX) + + jpeg = upload("figure.jpeg", JPEG_1PX, "image/jpeg") + check("jpeg key", jpeg["key"].endswith(".jpg"), jpeg["key"]) + check("jpeg type", jpeg["content_type"] == "image/jpeg", jpeg["content_type"]) + check("jpeg bytes", fetch(jpeg["url"])[0] == JPEG_1PX) + + print("5. what it refuses") + refused = upload("notes.txt", b"this is not a picture\n", "text/plain", expect=415) + check("a text file is 415", "格式" in refused["detail"], refused["detail"]) + + svg = upload("attack.svg", SVG, "image/svg+xml", expect=415) + check("an SVG is 415", "SVG" in svg["detail"], svg["detail"]) + + # A file that lies about being a PNG is still refused: the magic bytes + # are what count, not the declared type or the extension. + liar = upload("fake.png", b"", "image/png", expect=415) + check("a mislabelled file is 415", "格式" in liar["detail"], liar["detail"]) + + empty = upload("empty.png", b"", "image/png", expect=400) + check("an empty upload is 400", "空" in empty["detail"], empty["detail"]) + + print("6. what it will not serve") + missing, _ = fetch(f"/api/images/2026/01/{'0' * 16}.png", expect=404) + check("a key with no object is 404", True, missing.decode("utf-8", "replace")[:80]) + + fetch("/api/images/mattermost/20260724/logo.png", expect=404) + check("a key we did not write is 404 (the bucket is not browsable)", True) + + fetch("/api/images/2026/01/zzzzzzzzzzzzzzzz.png", expect=404) + check("a key outside the key space is 404", True) + + print("7. a sentence carries the figure") + templates = call("GET", "/templates?page_size=50")["items"] + check("a template exists", bool(templates), f"got {len(templates)}") + paper = call( + "POST", + "/papers", + { + "title": "冒烟测试-插图论文", + "template_id": templates[0]["id"], + "status": "draft", + }, + expect=201, + ) + created_papers.append(paper["id"]) + sort = call("GET", f"/papers/{paper['id']}/document")["paragraphs"][0][ + "paper_template_filed_sort" + ] + + caption = "试验装置示意图" + prose = f"试验装置如 {image['markdown']} 所示,量测点布置在试件中部。" + call( + "POST", + f"/papers/{paper['id']}/sentences", + {"paper_template_filed_sort": sort, "content": prose, "sort": 1}, + expect=201, + ) + call( + "POST", + f"/papers/{paper['id']}/sentences", + { + "paper_template_filed_sort": sort, + "content": f"![{caption}]({image['url']}){{width=70%}}", + "sort": 2, + "line_break_before": True, + }, + expect=201, + ) + + document = call("GET", f"/papers/{paper['id']}/document") + paragraph = next( + item for item in document["paragraphs"] if item["paper_template_filed_sort"] == sort + ) + contents = [sentence["content"] for sentence in paragraph["sentences"]] + check("the inline image survives the round trip", contents[0] == prose, contents[0]) + check( + "the figure sentence survives with its size", + contents[1] == f"![{caption}]({image['url']}){{width=70%}}", + contents[1], + ) + check("it is on a line of its own", paragraph["sentences"][1]["line_break_before"]) + check( + "the server did not touch the markup", + image["url"] in contents[0] and image["url"] in contents[1], + ) + + print(f"\nall {_checks} checks passed") + return 0 + finally: + # Never leave test rows behind, even on a failed expectation. + for paper_id in created_papers: + try: + call("DELETE", f"/papers/{paper_id}", expect=204) + except Exception as error: # noqa: BLE001 — cleanup must not mask the failure + print(f" !! could not delete paper {paper_id}: {error}", file=sys.stderr) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/frontend/src/utils/math.ts b/frontend/src/utils/rich.ts similarity index 100% rename from frontend/src/utils/math.ts rename to frontend/src/utils/rich.ts