299 lines
15 KiB
Python
299 lines
15 KiB
Python
"""Константы, одинаковые на всех установках.
|
||
|
||
Лимиты взяты из 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
|