Files
mtusi2026lab6/src/utils/constants.py
T

299 lines
15 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""Константы, одинаковые на всех установках.
Лимиты взяты из contracts/openapi.json и contracts/README.md: менять их
нельзя, это часть контракта.
"""
# пути
API_V1_PREFIX = "/api/v1"
HEALTH_LIVE_PATH = "/health/live"
HEALTH_READY_PATH = "/health/ready"
HEALTH_PATHS = frozenset({HEALTH_LIVE_PATH, HEALTH_READY_PATH})
# заголовки
REQUEST_ID_HEADER = "X-Request-Id"
INSTANCE_ID_HEADER = "X-Instance-Id"
IDEMPOTENCY_KEY_HEADER = "Idempotency-Key"
# идентификатор на входе: запись 8-4-4-4-12 (`format: uuid` контракта),
# шестнадцатеричные цифры в любом регистре
UUID_PATTERN = (
r"^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}"
r"-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$"
)
# экземпляр API: значение X-Instance-Id безопасно для заголовка и журнала
INSTANCE_ID_PATTERN = r"^[A-Za-z0-9._-]{1,64}$"
# ключ идемпотентности: шаблон и длины — как у параметра в контракте
IDEMPOTENCY_KEY_PATTERN = r"^[A-Za-z0-9._:-]+$"
IDEMPOTENCY_KEY_MIN_LENGTH = 1
IDEMPOTENCY_KEY_MAX_LENGTH = 128
# в БД хранится SHA-256 канонического тела запроса, а не тело
REQUEST_HASH_BYTES = 32
# пользователь
USERNAME_PATTERN = r"^[a-z0-9_]{3,32}$"
DISPLAY_NAME_MIN_LENGTH = 1
DISPLAY_NAME_MAX_LENGTH = 100
PASSWORD_MIN_LENGTH = 12
PASSWORD_MAX_LENGTH = 128
# начало хэша Argon2id: CHECK в БД не даёт записать пароль иначе
PASSWORD_HASH_PREFIX = "$argon2id$"
# сессия
# байты случайности токена: 256 бит, 43 символа base64url
SESSION_TOKEN_BYTES = 32
# в БД хранится SHA-256 токена, а не токен
TOKEN_HASH_BYTES = 32
# realm в WWW-Authenticate
AUTH_REALM = "messenger"
# чат
CHAT_TITLE_MIN_LENGTH = 1
CHAT_TITLE_MAX_LENGTH = 100
CHAT_MEMBERS_MIN = 1
CHAT_MEMBERS_MAX = 100
# сообщение
# нижней границы нет: пустой текст допустим только вместе с вложением,
# правило — в схеме API, CHECK в БД — только верхняя граница (design
# change `attachments`, решения 3 и 8)
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"
# обработка вложения (с лабы 5, design change `async-attachments`):
# объект до обработки — `<имя базы>/staging/<id>/original`, вариант —
# `<имя базы>/attachments/<id>/v<версия>-<вариант>`
ATTACHMENT_STAGING_PREFIX = "staging"
# версия обработки; курс использует одну (contracts/attachment-states.md)
ATTACHMENT_PIPELINE_VERSION = 1
# поля type и schema_version сообщения contracts/jobs.schema.json
ATTACHMENT_JOB_TYPE = "attachment.process.v1"
ATTACHMENT_JOB_SCHEMA_VERSION = 1
# очередь заданий — `<имя базы>.attachment.process.v1`: прогон на временной
# базе не смешивается с рабочим, как объекты S3 и ключи кэша
ATTACHMENT_QUEUE_SUFFIX = "attachment.process.v1"
# thumbnail контракта: вписан в квадрат, JPEG
THUMBNAIL_MAX_SIDE = 256
THUMBNAIL_JPEG_QUALITY = 85
# crop контракта: центрированный квадрат, JPEG (design change
# `pipeline-reliability`, решение 6)
CROP_SIDE = 128
CROP_JPEG_QUALITY = 85
# optimized контракта: вписан в квадрат, WebP; method 6 на пробе в 3,5 раза
# дольше без выигрыша
OPTIMIZED_MAX_SIDE = 1280
OPTIMIZED_WEBP_QUALITY = 80
OPTIMIZED_WEBP_METHOD = 4
# сверка bucket и БД: сколько расхождений за проход пишется отдельными
# записями журнала; остальные — только числом в итоге (design change
# `track2-reconciler`, решение 8)
RECONCILE_FINDINGS_LOGGED_MAX = 1000
# пауза предела скорости сверки — кусками не дольше этого, с проверкой
# сигнала между ними: остановка не ждёт конца паузы (design change
# `track2-reconcile-cost`, решение 6)
RECONCILE_PACE_STEP_SECONDS = 0.2
# секунды в Retry-After ответа 429, когда места загрузки процесса заняты:
# за секунду реплика доводит несколько загрузок (7–8,5 по 10 MiB), а повтор
# через LB уходит на следующую реплику (design change `upload-memory`,
# решение 2)
UPLOAD_RETRY_AFTER_SECONDS = 1
# секунды в Retry-After ответа 429, когда достигнут предел незавершённых
# заданий: за 5 с worker завершает 4–15 заданий, повтор через секунду почти
# всегда получил бы тот же 429, а простоя нет: при заполненном пределе работы
# на десятки секунд (design change `track1-queue-overload`, решение 2)
UPLOAD_BACKLOG_RETRY_AFTER_SECONDS = 5
# пагинация
PAGE_LIMIT_MIN = 1
PAGE_LIMIT_MAX = 100
PAGE_LIMIT_DEFAULT = 50
# база данных
# имя соединений сервиса в pg_stat_activity
DB_APPLICATION_NAME = "mtusi-messenger"
# секунды на проверку Postgres в /health/ready
READINESS_DB_TIMEOUT_SECONDS = 2
# логгер пула engine: SQLAlchemy называет его модулем и классом пула
# (`CountingQueuePool`, design change `job-trace-propagation`, решение 10);
# журнал держит его на WARNING, как прежний пул SQLAlchemy
DB_POOL_LOGGER = "src.infra.db.engine.CountingQueuePool"
# секунды на мягкое закрытие соединения, если SQLAlchemy не передал свой
# срок; дальше соединение обрывается
DB_CLOSE_TIMEOUT_SECONDS = 2
# кэш (Valkey)
# начало ключей; v1 — формат значений: новый формат — v2, и старые ключи
# не читаются без чистки кэша
CACHE_KEY_PREFIX = "messenger:v1"
# телеметрия (с лабы 6, design change `otel-telemetry`, решения 8–12)
# service.name ресурса: процесс API и процесс worker
TELEMETRY_SERVICE_API = "messenger-api"
TELEMETRY_SERVICE_WORKER = "messenger-worker"
# service.version — info.version контракта, который реализует код
# (contracts/openapi.json); из неё же версия приложения FastAPI
SERVICE_VERSION = "1.6.0"
# имя инструментирования (otel_scope_name в Prometheus)
TELEMETRY_SCOPE = "mtusi-messenger"
# пути OTLP/HTTP сигналов от адреса Collector
TELEMETRY_TRACES_PATH = "/v1/traces"
TELEMETRY_METRICS_PATH = "/v1/metrics"
TELEMETRY_LOGS_PATH = "/v1/logs"
# секунды, которые процесс ждёт закрытия SDK при остановке; что не ушло —
# теряется (решение 13): API — 8 с дренажа + закрытие клиентов + 1 с < 10 с
TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS = 1
# секунды от SIGTERM до SIGKILL docker (stop_grace_period сервисов приложения)
CONTAINER_STOP_TIMEOUT_SECONDS = 10
# секунды на дренаж uvicorn и закрытие SDK API: остаток до SIGKILL — закрытие
# клиентов в lifespan и выход процесса. Без телеметрии дренаж до 9 с, с ней —
# дренаж + TELEMETRY_SHUTDOWN_TIMEOUT_SECONDS (проверка настроек, verify W3)
API_STOP_BUDGET_SECONDS = 9
# секунды: не больше одной записи логгера `opentelemetry.*` в stdout за окно
TELEMETRY_SDK_LOG_WINDOW_SECONDS = 60
# префикс логгеров самого SDK: их записи не экспортируются
TELEMETRY_SDK_LOGGER_PREFIX = "opentelemetry"
# лимиты span и записей журнала: длина значения атрибута (запрос SQL,
# traceback) и число атрибутов
TELEMETRY_MAX_ATTRIBUTES = 128
TELEMETRY_SPAN_ATTRIBUTE_LENGTH = 4096
TELEMETRY_LOG_ATTRIBUTE_LENGTH = 32768
# метрики (имена OpenTelemetry; в Prometheus — с единицей и подчёркиваниями)
METRIC_HTTP_SERVER_DURATION = "http.server.request.duration"
METRIC_JOB_DURATION = "messenger.job.duration"
# границы buckets, секунды: чтение 2–10 мс, вход с Argon2id 0,1–0,5 с,
# загрузки до 5 с, срок JSON-запроса 6 с, timeout server LB 10 и 30 с
HTTP_DURATION_BUCKETS = (
0.005,
0.01,
0.025,
0.05,
0.1,
0.25,
0.5,
1,
2.5,
5,
10,
30,
)
# процесс обработки 0,2–1 с, его срок 40 с, срок попытки 60 с
JOB_DURATION_BUCKETS = (0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 20, 40, 60)
# стандартные методы HTTP (semantic conventions); прочие — `_OTHER`
HTTP_KNOWN_METHODS = frozenset(
{
"CONNECT",
"DELETE",
"GET",
"HEAD",
"OPTIONS",
"PATCH",
"POST",
"PUT",
"TRACE",
},
)
HTTP_OTHER_METHOD = "_OTHER"
# атрибуты span и метрик (semantic conventions и свои `messenger.*`)
ATTR_HTTP_METHOD = "http.request.method"
ATTR_HTTP_ROUTE = "http.route"
ATTR_HTTP_STATUS = "http.response.status_code"
ATTR_ERROR_TYPE = "error.type"
ATTR_REQUEST_ID = "messenger.request_id"
ATTR_JOB_TYPE = "messenger.job.type"
ATTR_JOB_OUTCOME = "messenger.job.outcome"
ATTR_CACHE_RESULT = "messenger.cache.result"
ATTR_OBJECT_SIZE = "messenger.object.size"
ATTR_S3_RESULT = "messenger.s3.result"
ATTR_RENDER_INPUT_SIZE = "messenger.render.input_size"
ATTR_RENDER_OUTCOME = "messenger.render.outcome"
ATTR_RENDER_EXIT_CODE = "messenger.render.exit_code"
ATTR_RENDER_PEAK_KIB = "messenger.render.peak_kib"
# сквозная трасса и сигналы уровня 4 (design change `job-trace-propagation`,
# решения 1–13)
TELEMETRY_SERVICE_RELAY = "messenger-relay"
# W3C Trace Context: версия 00, как шаблон contracts/jobs.schema.json; те же
# значения — колонки attachment_jobs и заголовки сообщения AMQP
TRACEPARENT_PATTERN = r"^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$"
TRACESTATE_MAX_LENGTH = 512
TRACE_HEADER_TRACEPARENT = "traceparent"
TRACE_HEADER_TRACESTATE = "tracestate"
# span брокера (semantic conventions messaging)
MESSAGING_SYSTEM = "rabbitmq"
MESSAGING_OPERATION_PUBLISH = "publish"
MESSAGING_OPERATION_PROCESS = "process"
ATTR_MESSAGING_SYSTEM = "messaging.system"
ATTR_MESSAGING_DESTINATION = "messaging.destination.name"
ATTR_MESSAGING_OPERATION_TYPE = "messaging.operation.type"
ATTR_MESSAGING_OPERATION_NAME = "messaging.operation.name"
ATTR_JOB_ATTEMPT = "messenger.job.attempt"
ATTR_JOB_REPLAYED = "messenger.job.replayed"
ATTR_JOB_RETRY_REASON = "messenger.job.retry_reason"
ATTR_JOB_REDELIVERED = "messenger.job.redelivered"
ATTR_JOB_REASON = "messenger.job.reason"
ATTR_JOB_ERROR_CODE = "messenger.job.error_code"
# метрики уровня 4 (таблица решения 13)
METRIC_JOB_TIME_TO_READY = "messenger.job.time_to_ready"
METRIC_QUEUE_DEPTH = "messenger.queue.depth"
METRIC_QUEUE_OLDEST_AGE = "messenger.queue.oldest_age"
METRIC_DB_CONNECTION_COUNT = "db.client.connection.count"
METRIC_DB_CONNECTION_MAX = "db.client.connection.max"
METRIC_DB_CONNECTION_PENDING = "db.client.connection.pending_requests"
METRIC_DB_CONNECTION_TIMEOUTS = "db.client.connection.timeouts"
METRIC_WORKER_BUSY = "messenger.worker.busy"
METRIC_WORKER_CAPACITY = "messenger.worker.capacity"
METRIC_WORKER_WAITING = "messenger.worker.waiting"
METRIC_CONTAINER_CPU_TIME = "container.cpu.time"
METRIC_CONTAINER_MEMORY_USAGE = "container.memory.usage"
METRIC_CONTAINER_CPU_LIMIT = "messenger.container.cpu.limit"
METRIC_CONTAINER_MEMORY_LIMIT = "messenger.container.memory.limit"
ATTR_QUEUE_STAGE = "messenger.queue.stage"
ATTR_DB_POOL_NAME = "db.client.connection.pool.name"
ATTR_DB_CONNECTION_STATE = "db.client.connection.state"
DB_CONNECTION_STATE_USED = "used"
DB_CONNECTION_STATE_IDLE = "idle"
# стадии незавершённых заданий: ждёт срока следующей попытки, срок наступил и
# не опубликовано, опубликовано и не взято, идёт попытка
QUEUE_STAGE_SCHEDULED = "scheduled"
QUEUE_STAGE_OUTBOX = "outbox"
QUEUE_STAGE_PUBLISHED = "published"
QUEUE_STAGE_PROCESSING = "processing"
# время до ready, секунды: путь без повторов 0,5–2 с, бюджет smoke 60 с,
# паузы повторов до 75 с, возврат по аренде 70 с, наибольшая пауза 300 с
TIME_TO_READY_BUCKETS = (0.25, 0.5, 1, 2.5, 5, 10, 20, 30, 60, 120, 300, 600)
# снимок очереди relay: не чаще раза в интервал; старше срока не отдаётся
QUEUE_SNAPSHOT_INTERVAL_SECONDS = 5
QUEUE_SNAPSHOT_STALE_SECONDS = 30
# cgroup v2 контейнера изнутри (решение 12)
CGROUP_ROOT = "/sys/fs/cgroup"
# хранилище объектов (S3)
# имя bucket по правилам S3: 3–63 символа, строчные латинские буквы,
# цифры, точка и дефис, по краям — буква или цифра
S3_BUCKET_NAME_PATTERN = r"^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$"
# разделитель пространства имён (имени базы) и остатка ключа объекта:
# `<имя базы>/<…>`, как ключи кэша по имени базы
S3_KEY_SEPARATOR = "/"
# секунды, после которых aiohttp закрывает простаивающее соединение с S3:
# раньше шлюза SeaweedFS (120 с), чтобы запрос не ушёл в закрывающееся
S3_KEEPALIVE_TIMEOUT_SECONDS = 15