"""Константы, одинаковые на всех установках. Лимиты взяты из 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//original` ATTACHMENT_KEY_PREFIX = "attachments" ATTACHMENT_ORIGINAL_SUFFIX = "original" # обработка вложения (с лабы 5, design change `async-attachments`): # объект до обработки — `<имя базы>/staging//original`, вариант — # `<имя базы>/attachments//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