feat(backend): модуль «замена фона» и хранилище своих картинок

Отключаемый в админке модуль `virtual_background` (дефолт — выключен, чтобы
обновление не меняло продукт у тех, кто ничего не просил). Флаг едет клиенту
двумя путями: на публичные страницы входа — через `GET /public/settings`,
участнику комнаты — в join-ответе (`JoinOut`), потому что значение нужно на
руках ДО первого рендера комнаты, а `/admin/settings` доступен только админу.

Свои картинки пользователя (`/users/me/backgrounds`, GET/POST/DELETE):
файлы на диске (`backgrounds/{user_id}/{id}.{ext}`), в БД только путь — как у
аватаров, «чтобы не грузили БД». Лимит в 10 штук проверяется на сервере под
блокировкой строки пользователя: две одновременные загрузки иначе обе увидели
бы «уже девять» и обе прошли бы. Удаление сносит и запись, и файл; чужую
картинку по её id удалить нельзя — владелец в условии запроса.

Валидация загрузки (допустимые форматы, магические байты, реальный размер)
выделена из `services/avatars.py` в общий `services/images.py`: правила у
аватара и фона одни и те же, а разъехавшись, они дали бы дыру ровно там, ради
чего проверка и написана. Публичный API аватаров не изменился.

Сжимает картинку клиент (Pillow на бэкенде нет), но серверная валидация
остаётся полноценной — запрос может прийти и мимо интерфейса.

Новый ключ настройки вписан в `_MANAGED_KEYS` тестов: без этого включённый
в общей dev-БД модуль ронял чужие тесты, которые считают себя изолированными.
This commit is contained in:
2026-08-10 08:59:16 +03:00
parent 88401d6aa1
commit fec9255baa
21 changed files with 717 additions and 64 deletions

View File

@@ -3,80 +3,49 @@
Файл лежит на диске `MEDIA_ROOT/avatars/{user_id}.{ext}`; в БД (`users.avatar_path`)
хранится путь относительно `MEDIA_ROOT` (`avatars/{user_id}.{ext}`) — тот же
приём, что и у записей аудиотреков (`recordings_dir`, `core/config.py`).
Сама проверка содержимого (допустимые форматы, магические байты, реальный
размер) живёт в `services/images.py` — она общая с картинками фона видео
(`services/backgrounds.py`).
"""
import uuid
from collections.abc import Callable
from pathlib import Path
from fastapi import UploadFile
from services.images import (
ImageInvalidTypeError,
ImageTooLargeError,
read_and_validate_image,
)
# Лимит размера загружаемого аватара — 2 МБ.
MAX_AVATAR_SIZE_BYTES = 2 * 1024 * 1024
# Читаем файл чанками, не доверяя заголовку `Content-Length` (клиент может
# солгать о размере) — реальный размер считается по факту прочитанных байт.
_CHUNK_SIZE_BYTES = 64 * 1024
# Допустимые типы изображений -> расширение файла на диске.
_ALLOWED_CONTENT_TYPES: dict[str, str] = {
"image/jpeg": "jpg",
"image/png": "png",
"image/webp": "webp",
}
# Магические байты (сигнатуры) форматов — заголовку `Content-Type` от клиента
# доверять нельзя (легко подделать), реальный формат определяется по
# содержимому файла.
_MAGIC_CHECKS: dict[str, Callable[[bytes], bool]] = {
"image/jpeg": lambda head: head[:3] == b"\xff\xd8\xff",
"image/png": lambda head: head[:8] == b"\x89PNG\r\n\x1a\n",
"image/webp": lambda head: head[:4] == b"RIFF" and head[8:12] == b"WEBP",
}
# Достаточно первых 12 байт, чтобы проверить все сигнатуры выше (WebP —
# самая длинная проверка, требует байты 8..11 включительно).
_MAGIC_HEAD_SIZE = 12
class AvatarTooLargeError(Exception):
class AvatarTooLargeError(ImageTooLargeError):
"""Загружаемый файл превышает `MAX_AVATAR_SIZE_BYTES` (413)."""
class AvatarInvalidTypeError(Exception):
class AvatarInvalidTypeError(ImageInvalidTypeError):
"""`Content-Type` не входит в список допустимых либо не совпадает с содержимым (415)."""
async def read_and_validate_avatar(file: UploadFile) -> tuple[bytes, str]:
"""Прочитать содержимое файла аватара чанками и провалидировать тип/размер.
"""Прочитать содержимое файла аватара и провалидировать тип/размер.
Возвращает `(содержимое, расширение)`. Порядок проверок: сначала
заявленный `Content-Type` (быстрый отсев), затем фактический размер по
мере чтения, затем магические байты содержимого — заявленный тип должен
совпасть с реальным (иначе подделка `Content-Type` не даст загрузить,
например, исполняемый файл под видом `image/png`).
Возвращает `(содержимое, расширение)`. Ошибки общего валидатора
перезаворачиваются в «аватарные» — вызывающий код (`api/users.py`,
`api/admin.py`) отображает их в 413/415 и не должен знать про
`services/images.py`.
"""
declared_type = file.content_type
if declared_type not in _ALLOWED_CONTENT_TYPES:
raise AvatarInvalidTypeError(f"unsupported_content_type: {declared_type}")
chunks: list[bytes] = []
total_size = 0
while True:
chunk = await file.read(_CHUNK_SIZE_BYTES)
if not chunk:
break
total_size += len(chunk)
if total_size > MAX_AVATAR_SIZE_BYTES:
raise AvatarTooLargeError(f"file exceeds {MAX_AVATAR_SIZE_BYTES} bytes")
chunks.append(chunk)
content = b"".join(chunks)
magic_check = _MAGIC_CHECKS[declared_type]
if not magic_check(content[:_MAGIC_HEAD_SIZE]):
raise AvatarInvalidTypeError("content_does_not_match_declared_content_type")
return content, _ALLOWED_CONTENT_TYPES[declared_type]
try:
return await read_and_validate_image(file, MAX_AVATAR_SIZE_BYTES)
except ImageTooLargeError as exc:
raise AvatarTooLargeError(str(exc)) from exc
except ImageInvalidTypeError as exc:
raise AvatarInvalidTypeError(str(exc)) from exc
def _avatar_relative_path(user_id: uuid.UUID, ext: str) -> str:

View File

@@ -0,0 +1,135 @@
"""Свои картинки пользователя для замены фона видео: лимит, файлы на диске, URL.
Как и аватары (`services/avatars.py`), картинки лежат **файлами на диске**
(`MEDIA_ROOT/backgrounds/{user_id}/{background_id}.{ext}`), а в БД — только
путь (`user_backgrounds.path`): требование оператора «чтобы не грузили БД».
Раздаёт их nginx напрямую (`location /media/`), в обход backend.
Картинку ужимает КЛИЕНТ (canvas → WebP, см. `frontend/src/lib/imageResize.ts`):
фон всё равно рендерится в браузере, и ставить Pillow на сервер ради одной
операции не нужно. Но валидация здесь остаётся полноценной — запрос может
прийти и мимо интерфейса.
Имя файла — id самой записи, а не порядковый номер: запись никогда не
перезаписывается (загрузка всегда создаёт новую), поэтому URL картинки
неизменен и его можно кэшировать браузером без cache-busting-параметра,
в отличие от аватара.
"""
import uuid
from pathlib import Path
from fastapi import UploadFile
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
from models.user import User
from models.user_background import UserBackground
from services.images import (
ImageInvalidTypeError,
ImageTooLargeError,
read_and_validate_image,
)
# Сколько своих картинок разрешено одному пользователю — прямое требование
# задачи («но не более 10»). Проверяется здесь, на сервере: ограничение только
# в интерфейсе обходится curl'ом.
MAX_BACKGROUNDS_PER_USER = 10
# Лимит размера загружаемого файла — 2 МБ, как у аватара. Клиент присылает
# ужатый WebP (обычно 100300 КБ), так что до лимита доходит только тот, кто
# шлёт запрос в обход интерфейса.
MAX_BACKGROUND_SIZE_BYTES = 2 * 1024 * 1024
class BackgroundTooLargeError(ImageTooLargeError):
"""Загружаемый файл превышает `MAX_BACKGROUND_SIZE_BYTES` (413)."""
class BackgroundInvalidTypeError(ImageInvalidTypeError):
"""`Content-Type` не входит в список допустимых либо не совпадает с содержимым (415)."""
class BackgroundLimitReachedError(Exception):
"""У пользователя уже `MAX_BACKGROUNDS_PER_USER` картинок (409)."""
async def list_backgrounds(session: AsyncSession, user_id: uuid.UUID) -> list[UserBackground]:
"""Все картинки пользователя, свежие сверху."""
result = await session.execute(
select(UserBackground)
.where(UserBackground.user_id == user_id)
.order_by(UserBackground.created_at.desc(), UserBackground.id.desc())
)
return list(result.scalars().all())
async def add_background(
session: AsyncSession, media_root: Path, user_id: uuid.UUID, file: UploadFile
) -> UserBackground:
"""Провалидировать, сохранить на диск и завести запись о новой картинке.
Бросает `BackgroundTooLargeError`/`BackgroundInvalidTypeError`/
`BackgroundLimitReachedError`. Коммит — за вызывающим (роутером), как и в
остальных эндпоинтах профиля.
Строка пользователя блокируется (`FOR UPDATE`) на время проверки лимита:
без этого две одновременные загрузки (двойной клик по кнопке) обе
увидели бы «уже 9» и обе прошли бы — лимит, проверяемый на сервере,
обязан держаться и в этом случае.
"""
await session.execute(select(User.id).where(User.id == user_id).with_for_update())
count = await session.scalar(
select(func.count()).select_from(UserBackground).where(UserBackground.user_id == user_id)
)
if (count or 0) >= MAX_BACKGROUNDS_PER_USER:
raise BackgroundLimitReachedError(f"limit is {MAX_BACKGROUNDS_PER_USER}")
try:
content, ext = await read_and_validate_image(file, MAX_BACKGROUND_SIZE_BYTES)
except ImageTooLargeError as exc:
raise BackgroundTooLargeError(str(exc)) from exc
except ImageInvalidTypeError as exc:
raise BackgroundInvalidTypeError(str(exc)) from exc
# id генерируем здесь, а не полагаемся на `server_default`: он нужен ДО
# вставки, чтобы собрать имя файла на диске.
background_id = uuid.uuid4()
relative_path = f"backgrounds/{user_id}/{background_id}.{ext}"
background = UserBackground(id=background_id, user_id=user_id, path=relative_path)
session.add(background)
# Запись сначала, файл потом: если вставка не пройдёт (лимит, гонка,
# отвалившаяся БД), на диске не останется мусора.
await session.flush()
file_path = media_root / relative_path
file_path.parent.mkdir(parents=True, exist_ok=True)
file_path.write_bytes(content)
return background
async def delete_background(
session: AsyncSession, media_root: Path, user_id: uuid.UUID, background_id: uuid.UUID
) -> bool:
"""Удалить картинку пользователя вместе с файлом. `False` — записи нет (404).
`user_id` в условии обязателен: без него владелец записи не проверялся бы
и любой аутентифицированный пользователь мог бы удалить чужую картинку,
зная её id.
"""
background = await session.scalar(
select(UserBackground).where(
UserBackground.id == background_id, UserBackground.user_id == user_id
)
)
if background is None:
return False
file_path = media_root / background.path
file_path.unlink(missing_ok=True)
await session.delete(background)
return True
def background_url(path: str) -> str:
"""Публичный URL картинки фона (раздаётся nginx из тома `media`)."""
return f"/media/{path}"

View File

@@ -56,13 +56,15 @@ def build_join(
hand_queue_enabled: bool,
publish_quality_cap: PublishQualityCap,
stage_max_tiles: StageMaxTiles,
virtual_background_enabled: bool,
avatar_url: str | None = None,
is_organizer: bool = False,
) -> JoinOut:
"""Построить ответ join: LiveKit access-токен для входа в комнату конференции.
Имя LiveKit-комнаты всегда равно `conference.slug` (ADR-001, п.4).
`chat_enabled`/`hand_queue_enabled`/`publish_quality_cap`/`stage_max_tiles`
`chat_enabled`/`hand_queue_enabled`/`publish_quality_cap`/`stage_max_tiles`/
`virtual_background_enabled`
— снятые вызывающей стороной значения `instance_settings`: читаются здесь
параметрами, а не заново из БД, чтобы не плодить отдельный запрос настроек
на каждый join.
@@ -96,4 +98,5 @@ def build_join(
hand_queue_enabled=hand_queue_enabled,
publish_quality_cap=publish_quality_cap,
stage_max_tiles=stage_max_tiles,
virtual_background_enabled=virtual_background_enabled,
)

View File

@@ -158,6 +158,7 @@ class ConferenceService:
hand_queue_enabled=cfg.hand_queue.enabled,
publish_quality_cap=cfg.media_limits.publish_quality_cap,
stage_max_tiles=cfg.media_limits.stage_max_tiles,
virtual_background_enabled=cfg.virtual_background_enabled,
avatar_url=resolve_avatar_url(self._media_root, owner_avatar_path),
is_organizer=True,
)
@@ -255,6 +256,7 @@ class ConferenceService:
hand_queue_enabled=cfg.hand_queue.enabled,
publish_quality_cap=cfg.media_limits.publish_quality_cap,
stage_max_tiles=cfg.media_limits.stage_max_tiles,
virtual_background_enabled=cfg.virtual_background_enabled,
avatar_url=resolve_avatar_url(self._media_root, user.avatar_path),
is_organizer=conference.owner_id is not None and conference.owner_id == user.id,
)
@@ -280,6 +282,7 @@ class ConferenceService:
hand_queue_enabled=cfg.hand_queue.enabled,
publish_quality_cap=cfg.media_limits.publish_quality_cap,
stage_max_tiles=cfg.media_limits.stage_max_tiles,
virtual_background_enabled=cfg.virtual_background_enabled,
)
async def mute_participant(

View File

@@ -0,0 +1,79 @@
"""Общая валидация загружаемых картинок: тип по содержимому и реальный размер.
Выделено из `services/avatars.py`, когда те же правила понадобились фонам
видео (`services/backgrounds.py`): списки допустимых форматов и сигнатур
должны быть в одном месте — разъехавшись, они дали бы дыру ровно в том
месте, ради которого проверка и написана.
Правила намеренно не смягчаются для «уже проверенных на клиенте» файлов:
браузер жмёт картинку фона перед отправкой (canvas → WebP), но запрос к API
может прийти и мимо интерфейса — клиенту верить нельзя.
"""
from collections.abc import Callable
from fastapi import UploadFile
# Читаем файл чанками, не доверяя заголовку `Content-Length` (клиент может
# солгать о размере) — реальный размер считается по факту прочитанных байт.
_CHUNK_SIZE_BYTES = 64 * 1024
# Допустимые типы изображений -> расширение файла на диске.
ALLOWED_IMAGE_CONTENT_TYPES: dict[str, str] = {
"image/jpeg": "jpg",
"image/png": "png",
"image/webp": "webp",
}
# Магические байты (сигнатуры) форматов — заголовку `Content-Type` от клиента
# доверять нельзя (легко подделать), реальный формат определяется по
# содержимому файла.
_MAGIC_CHECKS: dict[str, Callable[[bytes], bool]] = {
"image/jpeg": lambda head: head[:3] == b"\xff\xd8\xff",
"image/png": lambda head: head[:8] == b"\x89PNG\r\n\x1a\n",
"image/webp": lambda head: head[:4] == b"RIFF" and head[8:12] == b"WEBP",
}
# Достаточно первых 12 байт, чтобы проверить все сигнатуры выше (WebP —
# самая длинная проверка, требует байты 8..11 включительно).
_MAGIC_HEAD_SIZE = 12
class ImageTooLargeError(Exception):
"""Загружаемый файл превышает переданный лимит размера (413)."""
class ImageInvalidTypeError(Exception):
"""`Content-Type` не входит в список допустимых либо не совпадает с содержимым (415)."""
async def read_and_validate_image(file: UploadFile, max_size_bytes: int) -> tuple[bytes, str]:
"""Прочитать файл чанками и провалидировать тип/размер.
Возвращает `(содержимое, расширение)`. Порядок проверок: сначала
заявленный `Content-Type` (быстрый отсев), затем фактический размер по
мере чтения, затем магические байты содержимого — заявленный тип должен
совпасть с реальным (иначе подделка `Content-Type` не даст загрузить,
например, исполняемый файл под видом `image/png`).
"""
declared_type = file.content_type
if declared_type not in ALLOWED_IMAGE_CONTENT_TYPES:
raise ImageInvalidTypeError(f"unsupported_content_type: {declared_type}")
chunks: list[bytes] = []
total_size = 0
while True:
chunk = await file.read(_CHUNK_SIZE_BYTES)
if not chunk:
break
total_size += len(chunk)
if total_size > max_size_bytes:
raise ImageTooLargeError(f"file exceeds {max_size_bytes} bytes")
chunks.append(chunk)
content = b"".join(chunks)
magic_check = _MAGIC_CHECKS[declared_type]
if not magic_check(content[:_MAGIC_HEAD_SIZE]):
raise ImageInvalidTypeError("content_does_not_match_declared_content_type")
return content, ALLOWED_IMAGE_CONTENT_TYPES[declared_type]

View File

@@ -56,6 +56,7 @@ _KEY_CONTACT_EMAIL = "contact_email"
_KEY_MEDIA_LIMITS = "media_limits"
_KEY_CONSENT_POLICY = "consent_policy"
_KEY_DEVICE_CHECK = "device_check"
_KEY_VIRTUAL_BACKGROUND = "virtual_background"
BOOTSTRAP_MANAGED_KEYS: tuple[str, ...] = (
_KEY_CHAT,
@@ -81,6 +82,10 @@ _DEFAULT_REGISTRATION_EMAIL_DOMAIN_VALUE: dict[str, Any] = {"enabled": False, "d
_DEFAULT_CONTACT_EMAIL_VALUE: dict[str, Any] = {"enabled": False, "email": None}
_DEFAULT_MEDIA_LIMITS_VALUE: dict[str, Any] = {"publish_quality_cap": "off", "stage_max_tiles": 25}
_DEFAULT_DEVICE_CHECK_VALUE = {"enabled": False}
_DEFAULT_VIRTUAL_BACKGROUND_VALUE = {"enabled": False}
"""Замена фона видео (сессия 35). Дефолт — выключено: фича постоянно считает
нейросеть сегментации на клиенте, и включать её самим фактом обновления у тех,
кто ничего не просил, нельзя (то же правило, что и у остальных модулей)."""
DEFAULT_CONSENT_POLICY_TEXT = """Это типовой шаблон для предварительной демонстрации. Текст не проходил проверку юриста и не может использоваться как окончательная редакция без такой проверки. Администратор обязан заменить плейсхолдеры в квадратных скобках и, при необходимости, весь текст — под свою организацию и юрисдикцию.
@@ -154,6 +159,7 @@ class SettingsUpdateIn(BaseModel):
consent_required: bool | None = None
consent_policy_text: str | None = None
device_check_enabled: bool | None = None
virtual_background_enabled: bool | None = None
class BootstrapOverrides(BaseModel):
@@ -207,6 +213,7 @@ def build_bootstrap_defaults(
_KEY_MEDIA_LIMITS: dict(_DEFAULT_MEDIA_LIMITS_VALUE),
_KEY_CONSENT_POLICY: dict(_DEFAULT_CONSENT_POLICY_VALUE),
_KEY_DEVICE_CHECK: dict(_DEFAULT_DEVICE_CHECK_VALUE),
_KEY_VIRTUAL_BACKGROUND: dict(_DEFAULT_VIRTUAL_BACKGROUND_VALUE),
}
if overrides is None:
return defaults
@@ -345,6 +352,10 @@ class InstanceSettingsService:
cfg.device_check_enabled = patch.device_check_enabled
await self._set(_KEY_DEVICE_CHECK, {"enabled": patch.device_check_enabled})
if patch.virtual_background_enabled is not None:
cfg.virtual_background_enabled = patch.virtual_background_enabled
await self._set(_KEY_VIRTUAL_BACKGROUND, {"enabled": patch.virtual_background_enabled})
if patch.registration_team_choice is not None:
cfg.registration_team_choice = patch.registration_team_choice
await self._set(
@@ -616,4 +627,7 @@ def _build_config(rows: dict[str, Any]) -> InstanceConfig:
device_check_enabled=rows.get(_KEY_DEVICE_CHECK, _DEFAULT_DEVICE_CHECK_VALUE).get(
"enabled", False
),
virtual_background_enabled=rows.get(
_KEY_VIRTUAL_BACKGROUND, _DEFAULT_VIRTUAL_BACKGROUND_VALUE
).get("enabled", False),
)