Files
mtusi2026lab6/src/infra/db/models/attachment.py
T

316 lines
13 KiB
Python

from datetime import datetime
from uuid import UUID
from sqlalchemy import (
CheckConstraint,
DateTime,
ForeignKey,
ForeignKeyConstraint,
Index,
Integer,
LargeBinary,
SmallInteger,
Text,
UniqueConstraint,
text,
)
from sqlalchemy.orm import Mapped, mapped_column
from src.infra.db.models.base import Base
from src.utils.constants import (
ATTACHMENT_FILENAME_MAX_LENGTH,
ATTACHMENT_FILENAME_MIN_LENGTH,
ATTACHMENT_MAX_BYTES,
ATTACHMENT_SHA256_BYTES,
MESSAGE_ATTACHMENTS_MAX,
OBJECT_KEY_MAX_BYTES,
)
class Attachment(Base):
"""Метаданные вложения; байты — объект `object_key` в S3.
Строка пишется в статусе `pending` до записи объекта и становится
`ready` после неё (design change `attachments`, решение 1). Владелец —
участник чата вложения: проверяет сама БД.
"""
__tablename__ = "attachments"
__table_args__ = (
ForeignKeyConstraint(
["chat_id", "owner_id"],
["chat_members.chat_id", "chat_members.user_id"],
),
CheckConstraint(
"char_length(filename) BETWEEN "
f"{ATTACHMENT_FILENAME_MIN_LENGTH} "
f"AND {ATTACHMENT_FILENAME_MAX_LENGTH}",
name="filename_length",
),
# контракт: без `/`, `\` и управляющих символов (Cc); NUL в text
# PostgreSQL не бывает. Внутри скобок ARE `\\` — обратная косая
CheckConstraint(
r"filename !~ '[/\\\u0001-\u001f\u007f-\u009f]'",
name="filename_chars",
),
CheckConstraint(
"content_type IN ('image/png', 'image/jpeg')",
name="content_type",
),
CheckConstraint(
f"size_bytes BETWEEN 1 AND {ATTACHMENT_MAX_BYTES}",
name="size_bytes",
),
CheckConstraint(
f"octet_length(sha256) = {ATTACHMENT_SHA256_BYTES}",
name="sha256_length",
),
CheckConstraint(
f"octet_length(object_key) BETWEEN 1 AND {OBJECT_KEY_MAX_BYTES}",
name="object_key_length",
),
CheckConstraint(
"status IN ('pending', 'queued', 'processing', 'ready', 'failed')",
name="status",
),
# код ошибки — только у failed, и у failed он обязателен
CheckConstraint(
"(status = 'failed') = (error_code IS NOT NULL)",
name="error_code_failed",
),
CheckConstraint(
"updated_at >= created_at",
name="updated_after_created",
),
# кандидаты уборщика: строки pending старше grace по (created_at,
# id), keyset (design change upload-consistency, решение 6).
# Autogenerate условие не видит; в ревизии — CONCURRENTLY
Index(
"ix_attachments_pending_created_at",
"created_at",
"id",
postgresql_where=text("status = 'pending'"),
),
# кандидаты очистки staging keyset (design change
# pipeline-reliability, решения 9 и 10)
Index(
"ix_attachments_staging_cleanup",
"status",
"updated_at",
"id",
postgresql_where=text("staging_key IS NOT NULL"),
),
)
id: Mapped[UUID] = mapped_column(primary_key=True)
chat_id: Mapped[UUID]
owner_id: Mapped[UUID]
filename: Mapped[str] = mapped_column(Text)
content_type: Mapped[str] = mapped_column(Text)
size_bytes: Mapped[int] = mapped_column(Integer)
sha256: Mapped[bytes] = mapped_column(LargeBinary)
object_key: Mapped[str] = mapped_column(Text, unique=True)
status: Mapped[str] = mapped_column(Text)
updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
# когда сверка подтвердила, что оригинала ready нет или он другого
# размера (design change track2-reconciler, решения 5 и 6); NULL — не
# помечено. Индекса нет: сверка просматривает все строки ready, API
# читает по id
lost_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
# ключ объекта в staging (design change async-attachments, решение 1);
# NULL — строка прежней версии, объект которой сразу по `object_key`
staging_key: Mapped[str | None] = mapped_column(Text)
# код failed в API; NULL во всех остальных состояниях
error_code: Mapped[str | None] = mapped_column(Text)
class AttachmentJob(Base):
"""Логическая работа над вложением: `job_id` контракта, счёт попыток и
outbox — `state = 'queued' AND published_at IS NULL` (design change
`async-attachments`, решение 1; `pipeline-reliability`, решения 1 и 10).
Одна на вложение и версию; при повторах, повторной доставке и replay `id`
не меняется."""
__tablename__ = "attachment_jobs"
__table_args__ = (
UniqueConstraint("attachment_id", "pipeline_version"),
CheckConstraint("pipeline_version >= 1", name="pipeline_version"),
CheckConstraint(
"state IN ('queued', 'processing', 'succeeded', 'failed')",
name="state",
),
CheckConstraint("attempt >= 0", name="attempt"),
CheckConstraint(
"attempt_base BETWEEN 0 AND attempt",
name="attempt_base",
),
# контекст W3C загрузки (design change job-trace-propagation, решение
# 4): шаблон contracts/jobs.schema.json; в ревизии — NOT VALID
CheckConstraint(
"traceparent ~ '^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$'",
name="traceparent",
),
CheckConstraint(
"tracestate IS NULL OR (traceparent IS NOT NULL "
"AND char_length(tracestate) BETWEEN 1 AND 512)",
name="tracestate",
),
# Autogenerate условие и выражение не видит; в ревизии — CONCURRENTLY.
# Запросы пишут state константой, иначе общий план подготовленного
# выражения индекс не возьмёт
Index(
"ix_attachment_jobs_outbox",
text("COALESCE(next_attempt_at, created_at)"),
"id",
postgresql_where=text(
"state = 'queued' AND published_at IS NULL",
),
),
Index(
"ix_attachment_jobs_published",
"published_at",
postgresql_where=text(
"state = 'queued' AND published_at IS NOT NULL",
),
),
Index(
"ix_attachment_jobs_lease",
"lease_expires_at",
postgresql_where=text("state = 'processing'"),
),
)
id: Mapped[UUID] = mapped_column(primary_key=True)
# без каскада: вложение с заданием удалить нельзя
attachment_id: Mapped[UUID] = mapped_column(ForeignKey("attachments.id"))
pipeline_version: Mapped[int] = mapped_column(Integer)
state: Mapped[str] = mapped_column(Text)
# начатые попытки; источник истины счёта, а не заголовки брокера
attempt: Mapped[int] = mapped_column(
Integer,
server_default=text("0"),
)
# значение attempt при последнем replay: бюджет — attempt - attempt_base,
# сам attempt монотонен, это fencing-токен (design change
# pipeline-reliability, решение 5)
attempt_base: Mapped[int] = mapped_column(
Integer,
server_default=text("0"),
)
# причина последней ошибки для оператора, без секретов
last_error_code: Mapped[str | None] = mapped_column(Text)
next_attempt_at: Mapped[datetime | None] = mapped_column(
DateTime(timezone=True),
)
lease_expires_at: Mapped[datetime | None] = mapped_column(
DateTime(timezone=True),
)
# когда брокер подтвердил последнее сообщение; NULL — намерение не передано
published_at: Mapped[datetime | None] = mapped_column(
DateTime(timezone=True),
)
updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
finished_at: Mapped[datetime | None] = mapped_column(
DateTime(timezone=True),
)
# контекст server span загрузки; NULL — строка прежней версии или реплика
# без телеметрии (design change job-trace-propagation, решение 4)
traceparent: Mapped[str | None] = mapped_column(Text)
tracestate: Mapped[str | None] = mapped_column(Text)
class AttachmentJobReplay(Base):
"""Запись аудита replay задания `failed` (design change
`pipeline-reliability`, решения 5 и 10): кто, когда, прежние код и
причина, число попыток. Без каскада: задание с записью удалить нельзя."""
__tablename__ = "attachment_job_replays"
__table_args__ = (
CheckConstraint(
"char_length(operator) BETWEEN 1 AND 64",
name="operator_length",
),
CheckConstraint("attempt >= 0", name="attempt"),
)
id: Mapped[UUID] = mapped_column(primary_key=True)
job_id: Mapped[UUID] = mapped_column(
ForeignKey("attachment_jobs.id"),
index=True,
)
operator: Mapped[str] = mapped_column(Text)
# прежний error_code вложения
error_code: Mapped[str | None] = mapped_column(Text)
# прежняя причина задания (last_error_code)
reason: Mapped[str | None] = mapped_column(Text)
attempt: Mapped[int] = mapped_column(Integer)
class AttachmentVariant(Base):
"""Вариант готового вложения; первичный ключ — ключ эффекта контракта
`(attachment_id, pipeline_version, variant)`: повтор второй строки не
создаёт. Оригинал — не строка этой таблицы."""
__tablename__ = "attachment_variants"
__table_args__ = (
CheckConstraint(
"variant IN ('thumbnail', 'crop', 'optimized')",
name="variant",
),
CheckConstraint(
f"octet_length(object_key) BETWEEN 1 AND {OBJECT_KEY_MAX_BYTES}",
name="object_key_length",
),
CheckConstraint(
"content_type IN ('image/jpeg', 'image/png', 'image/webp')",
name="content_type",
),
CheckConstraint("size_bytes > 0", name="size_bytes"),
CheckConstraint("width > 0", name="width"),
CheckConstraint("height > 0", name="height"),
CheckConstraint(
f"octet_length(sha256) = {ATTACHMENT_SHA256_BYTES}",
name="sha256_length",
),
)
attachment_id: Mapped[UUID] = mapped_column(
ForeignKey("attachments.id"),
primary_key=True,
)
pipeline_version: Mapped[int] = mapped_column(Integer, primary_key=True)
variant: Mapped[str] = mapped_column(Text, primary_key=True)
object_key: Mapped[str] = mapped_column(Text, unique=True)
content_type: Mapped[str] = mapped_column(Text)
size_bytes: Mapped[int] = mapped_column(Integer)
width: Mapped[int] = mapped_column(Integer)
height: Mapped[int] = mapped_column(Integer)
sha256: Mapped[bytes] = mapped_column(LargeBinary)
class MessageAttachment(Base):
"""Вложение в сообщении; `position` — место в `attachment_ids`.
Внешние ключи без каскада: вложение, на которое ссылается сообщение,
БД удалить не даст. Индекс по `attachment_id` — для удаления строки
вложения (проверка FK) и вопроса «на вложение ссылаются сообщения?».
`created_at` — время сообщения, как у участников чата — время чата.
"""
__tablename__ = "message_attachments"
__table_args__ = (
UniqueConstraint("message_id", "attachment_id"),
CheckConstraint(
f"position BETWEEN 0 AND {MESSAGE_ATTACHMENTS_MAX - 1}",
name="position_range",
),
Index(None, "attachment_id"),
)
message_id: Mapped[UUID] = mapped_column(
ForeignKey("messages.id"),
primary_key=True,
)
position: Mapped[int] = mapped_column(SmallInteger, primary_key=True)
attachment_id: Mapped[UUID] = mapped_column(ForeignKey("attachments.id"))