feat: add image attachments to messages

- upload, metadata and download endpoints for PNG/JPEG attachments:
  limits before reading and decompression, type by content,
  structural integrity check without decoding pixels, safe filename
- write order: pending row with object key -> PUT to S3 -> ready;
  per-step DB sessions so no pool connection is held during transfers
- attachment_ids in messages (validation, idempotency hash, history);
  whitespace-only text allowed with an attachment (teacher, 2026-10-20)
- migration: attachments and message_attachments tables, text length
  CHECK relaxed with NOT VALID
- student tests, fault checks and driver commands for attachments;
  rollout profile starts from e1161f7 and checks the commit first
- sync attachments deltas into main specs; rules, AGENTS.md, PLAN.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-21 01:08:56 +03:00
co-authored by Claude Opus 5.5
parent 73779f7acd
commit 116d8d3bf0
72 changed files with 5546 additions and 247 deletions
+24
View File
@@ -56,8 +56,32 @@ CHAT_MEMBERS_MIN = 1
CHAT_MEMBERS_MAX = 100
# сообщение
# пустой текст допустим только вместе с вложением: правило — в сервисе и
# схеме API, CHECK в БД — только верхняя граница (design change
# `attachments`, решение 3)
MESSAGE_TEXT_MIN_LENGTH = 1
MESSAGE_TEXT_MAX_LENGTH = 4000
MESSAGE_ATTACHMENTS_MAX = 10
# вложение (с лабы 4): лимиты контракта, это не настройки — skeleton
# называет их MAX_UPLOAD_BYTES и MAX_IMAGE_PIXELS
ATTACHMENT_MAX_BYTES = 10 * 1024 * 1024
ATTACHMENT_MAX_PIXELS = 40_000_000
ATTACHMENT_FILENAME_MIN_LENGTH = 1
ATTACHMENT_FILENAME_MAX_LENGTH = 255
# запрещённые в filename символы по контракту: разделители пути и
# управляющие символы (категория Unicode Cc: U+0000–U+001F, U+007F–U+009F)
ATTACHMENT_FILENAME_FORBIDDEN_CHARS = frozenset({"/", "\\"})
ATTACHMENT_FILENAME_FORBIDDEN_CATEGORY = "Cc"
# SHA-256 оригинала в БД — 32 байта
ATTACHMENT_SHA256_BYTES = 32
# предел длины ключа объекта S3, байты
OBJECT_KEY_MAX_BYTES = 1024
# ключ объекта: `<имя базы>/attachments/<id>/original`
ATTACHMENT_KEY_PREFIX = "attachments"
ATTACHMENT_ORIGINAL_SUFFIX = "original"
# блок чтения тела загрузки не больше этого, байты
ATTACHMENT_READ_CHUNK_BYTES = 64 * 1024
# пагинация
PAGE_LIMIT_MIN = 1
+393
View File
@@ -0,0 +1,393 @@
"""Структурная проверка PNG и JPEG без декодирования пикселей.
Тип — по сигнатуре, размеры — из заголовка до распаковки (IHDR у PNG,
кадр SOF у JPEG). Целостность (design change `attachments`, решение 2):
- PNG: IHDR первым и с допустимыми полями, длина и CRC каждого чанка,
нет неизвестных критичных чанков, PLTE на своём месте, IDAT подряд,
поток zlib завершён и распакован ровно в объём по размерам, глубине и
чересстрочности, тип фильтра каждой строки ≤ 4, есть IEND;
- JPEG: маркеры и длины сегментов до EOI, один кадр с ненулевыми
размерами, хотя бы один скан после кадра, EOI есть.
Байты после IEND и EOI допускаются: они часть оригинала. Искажение внутри
сжатых данных скана JPEG не обнаруживается: у формата нет контрольной
суммы.
Память не зависит от числа пикселей: IDAT распаковывается блоками не
больше `_INFLATE_OUT_BYTES`, а вход подаётся кусками `_INFLATE_IN_BYTES`.
Строки проверяются срезом с шагом длины строки, конец данных скана JPEG
ищет регулярное выражение — оба в C, без цикла Python по строкам и
байтам. Только stdlib, без логов: бросает свои исключения, сервис
переводит их в доменные.
"""
import re
import struct
import zlib
from dataclasses import dataclass
from src.schemas.enums import ImageType
PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
JPEG_SIGNATURE = b"\xff\xd8\xff"
# выход распаковки за один вызов и кусок входа: пик памяти проверки —
# единицы MiB при любом числе пикселей
_INFLATE_OUT_BYTES = 1024 * 1024
_INFLATE_IN_BYTES = 64 * 1024
# предел длины чанка PNG и размера по спецификации: 2^31 - 1
_PNG_MAX_UINT = 2**31 - 1
# допустимая глубина по типу цвета и число каналов
_PNG_DEPTHS: dict[int, frozenset[int]] = {
0: frozenset({1, 2, 4, 8, 16}),
2: frozenset({8, 16}),
3: frozenset({1, 2, 4, 8}),
4: frozenset({8, 16}),
6: frozenset({8, 16}),
}
_PNG_CHANNELS = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4}
_PNG_PALETTE_TYPE = 3
# PLTE запрещён у серых изображений
_PNG_NO_PALETTE_TYPES = frozenset({0, 4})
# проходы Adam7: (x0, y0, dx, dy)
_ADAM7 = (
(0, 0, 8, 8),
(4, 0, 8, 8),
(0, 4, 4, 8),
(2, 0, 4, 4),
(0, 2, 2, 4),
(1, 0, 2, 2),
(0, 1, 1, 2),
)
# типы фильтра строки 0–4: всё, что не они, остаётся после translate
_PNG_FILTER_TYPES = bytes(range(5))
# маркеры кадра: SOF0–3, 5–7, 9–11, 13–15 (C4 — DHT, C8 — JPG, CC — DAC)
_JPEG_SOF = frozenset(
{0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7}
| {0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF},
)
_JPEG_SOI = 0xD8
_JPEG_EOI = 0xD9
_JPEG_SOS = 0xDA
_JPEG_TEM = 0x01
_JPEG_RST = frozenset(range(0xD0, 0xD8))
# конец данных скана: FF, за которым не 00 (вставка) и не RST0–7
_JPEG_SCAN_END = re.compile(rb"\xff[^\x00\xd0-\xd7]")
class ImageError(ValueError):
"""Изображение не прошло проверку."""
class UnsupportedImage(ImageError):
"""Не PNG и не JPEG."""
class DamagedImage(ImageError):
"""Структура изображения нарушена."""
class TooManyPixels(ImageError):
"""В заголовке больше пикселей, чем допускает лимит."""
@dataclass(frozen=True, slots=True)
class ImageInfo:
content_type: ImageType
width: int
height: int
def inspect_image(data: bytes, *, max_pixels: int) -> ImageInfo:
"""Тип и размеры изображения после проверки структуры.
`UnsupportedImage` — сигнатура не PNG и не JPEG (в том числе пустые
данные), `TooManyPixels` — больше `max_pixels` по заголовку,
`DamagedImage` — нарушена структура.
"""
if data.startswith(PNG_SIGNATURE):
return _inspect_png(data, max_pixels=max_pixels)
if data.startswith(JPEG_SIGNATURE):
return _inspect_jpeg(data, max_pixels=max_pixels)
raise UnsupportedImage("unknown signature")
def _check_pixels(width: int, height: int, *, max_pixels: int) -> None:
if width * height > max_pixels:
raise TooManyPixels("too many pixels")
# --- PNG ---------------------------------------------------------------
@dataclass(frozen=True, slots=True)
class _Segment:
"""Строки одного прохода в распакованном потоке: [start, end), шаг."""
start: int
end: int
stride: int
def _png_segments(
width: int,
height: int,
*,
bits_per_pixel: int,
interlaced: bool,
) -> list[_Segment]:
"""Где в распакованном потоке строки и какой они длины.
Строка — байт фильтра и `ceil(ширина × бит на пиксель / 8)` байт.
Пустой проход Adam7 (ширина или высота 0) строк не даёт.
"""
passes = _ADAM7 if interlaced else ((0, 0, 1, 1),)
segments = []
start = 0
for x0, y0, dx, dy in passes:
pass_width = (width - x0 + dx - 1) // dx if width > x0 else 0
pass_height = (height - y0 + dy - 1) // dy if height > y0 else 0
if not pass_width or not pass_height:
continue
stride = 1 + (pass_width * bits_per_pixel + 7) // 8
end = start + stride * pass_height
segments.append(_Segment(start=start, end=end, stride=stride))
start = end
return segments
class _IdatStream:
"""Поток IDAT: распаковка блоками, объём и типы фильтров строк."""
def __init__(self, segments: list[_Segment]) -> None:
self._segments = segments
self._expected = segments[-1].end
self._inflater = zlib.decompressobj()
self._total = 0
def feed(self, chunk: memoryview) -> None:
for offset in range(0, len(chunk), _INFLATE_IN_BYTES):
if self._inflater.eof:
# остаток после конца потока zlib libpng тоже пропускает
return
self._inflate(chunk[offset : offset + _INFLATE_IN_BYTES])
def finish(self) -> None:
if not self._inflater.eof or self._total != self._expected:
raise DamagedImage("image data size differs")
def _inflate(self, piece: memoryview | bytes) -> None:
while True:
try:
out = self._inflater.decompress(piece, _INFLATE_OUT_BYTES)
except zlib.error as e:
raise DamagedImage("broken image data stream") from e
self._check_rows(out)
if self._inflater.eof:
return
piece = self._inflater.unconsumed_tail
# вход кончился, а выход не упёрся в предел — буфер пуст
if not piece and len(out) < _INFLATE_OUT_BYTES:
return
def _check_rows(self, out: bytes) -> None:
begin = self._total
self._total += len(out)
# «бомба» и лишние данные: выход больше, чем дают размеры
if self._total > self._expected:
raise DamagedImage("image data longer than dimensions")
for segment in self._segments:
low = max(begin, segment.start)
high = min(self._total, segment.end)
if low >= high:
continue
# первый байт фильтра в [low, high) по сетке строк прохода
first = low + (-(low - segment.start) % segment.stride)
filters = out[first - begin : high - begin : segment.stride]
if filters.translate(None, _PNG_FILTER_TYPES):
raise DamagedImage("unknown row filter")
def _inspect_png(data: bytes, *, max_pixels: int) -> ImageInfo:
view = memoryview(data)
size = len(data)
pos = len(PNG_SIGNATURE)
width = height = 0
color_type = -1
stream: _IdatStream | None = None
seen_palette = False
idat_state = "before" # before → inside → after
first = True
while True:
if pos + 8 > size:
raise DamagedImage("truncated chunk header")
length, chunk_type = struct.unpack_from(">I4s", data, pos)
if length > _PNG_MAX_UINT or not chunk_type.isalpha():
raise DamagedImage("bad chunk")
body_end = pos + 8 + length
if body_end + 4 > size:
raise DamagedImage("truncated chunk")
(crc,) = struct.unpack_from(">I", data, body_end)
if zlib.crc32(view[pos + 4 : body_end]) != crc:
raise DamagedImage("chunk CRC mismatch")
body = view[pos + 8 : body_end]
pos = body_end + 4
if first:
if chunk_type != b"IHDR":
raise DamagedImage("IHDR is not first")
first = False
width, height, color_type, bits_per_pixel, interlaced = (
_parse_ihdr(body)
)
_check_pixels(width, height, max_pixels=max_pixels)
stream = _IdatStream(
_png_segments(
width,
height,
bits_per_pixel=bits_per_pixel,
interlaced=interlaced,
),
)
continue
if chunk_type == b"IDAT":
if idat_state == "after":
raise DamagedImage("IDAT chunks are not consecutive")
if color_type == _PNG_PALETTE_TYPE and not seen_palette:
raise DamagedImage("PLTE is missing")
idat_state = "inside"
stream.feed(body)
continue
if idat_state == "inside":
idat_state = "after"
if chunk_type == b"IEND":
if length or idat_state == "before":
raise DamagedImage("bad IEND")
stream.finish()
return ImageInfo(
content_type=ImageType.PNG,
width=width,
height=height,
)
if chunk_type == b"PLTE":
if (
seen_palette
or idat_state != "before"
or color_type in _PNG_NO_PALETTE_TYPES
or not length
or length % 3
or length > 3 * 256
):
raise DamagedImage("bad PLTE")
seen_palette = True
continue
if chunk_type == b"IHDR" or chunk_type[0:1].isupper():
# второй IHDR или неизвестный критичный чанк
raise DamagedImage("unexpected critical chunk")
# вспомогательный чанк: проверена только CRC
def _parse_ihdr(body: memoryview) -> tuple[int, int, int, int, bool]:
"""Ширина, высота, тип цвета, бит на пиксель, чересстрочность."""
if len(body) != 13:
raise DamagedImage("bad IHDR length")
width, height, depth, color_type, compression, filtering, interlace = (
struct.unpack(">IIBBBBB", body)
)
if (
not 0 < width <= _PNG_MAX_UINT
or not 0 < height <= _PNG_MAX_UINT
or depth not in _PNG_DEPTHS.get(color_type, ())
or compression
or filtering
or interlace not in (0, 1)
):
raise DamagedImage("bad IHDR")
bits_per_pixel = depth * _PNG_CHANNELS[color_type]
return width, height, color_type, bits_per_pixel, interlace == 1
# --- JPEG --------------------------------------------------------------
def _inspect_jpeg(data: bytes, *, max_pixels: int) -> ImageInfo:
size = len(data)
pos = 2
frame: tuple[int, int] | None = None
scans = 0
while True:
if pos >= size or data[pos] != 0xFF:
raise DamagedImage("marker expected")
# байты-заполнители FF перед маркером
while pos < size and data[pos] == 0xFF:
pos += 1
if pos >= size:
raise DamagedImage("truncated marker")
marker = data[pos]
pos += 1
if marker == _JPEG_EOI:
if frame is None or not scans:
raise DamagedImage("no frame or scan")
width, height = frame
return ImageInfo(
content_type=ImageType.JPEG,
width=width,
height=height,
)
if marker == _JPEG_TEM:
continue
if marker in (0x00, _JPEG_SOI) or marker in _JPEG_RST:
raise DamagedImage("unexpected marker")
if pos + 2 > size:
raise DamagedImage("truncated segment")
(length,) = struct.unpack_from(">H", data, pos)
if length < 2 or pos + length > size:
raise DamagedImage("bad segment length")
segment = data[pos + 2 : pos + length]
pos += length
if marker in _JPEG_SOF:
if frame is not None:
raise DamagedImage("more than one frame")
frame = _parse_sof(segment)
_check_pixels(*frame, max_pixels=max_pixels)
elif marker == _JPEG_SOS:
if frame is None:
raise DamagedImage("scan before frame")
_check_sos(segment)
scans += 1
# данные скана: до первого маркера, кроме вставок и RST
found = _JPEG_SCAN_END.search(data, pos)
if found is None:
raise DamagedImage("scan data is not terminated")
pos = found.start()
def _parse_sof(segment: bytes) -> tuple[int, int]:
"""Ширина и высота кадра; длина сегмента сходится с числом компонент."""
if len(segment) < 6:
raise DamagedImage("bad frame header")
_, height, width, components = struct.unpack_from(">BHHB", segment)
if (
not width
or not height
or not 1 <= components <= 4
or len(segment) != 6 + 3 * components
):
raise DamagedImage("bad frame header")
return width, height
def _check_sos(segment: bytes) -> None:
if not segment:
raise DamagedImage("bad scan header")
components = segment[0]
if not 1 <= components <= 4 or len(segment) != 4 + 2 * components:
raise DamagedImage("bad scan header")