perf: идемпотентная отправка сообщения одним вызовом SQL (трек 1)

Гипотеза из профиля (py-spy, 2 x 1.0 CPU, 240 req/s): ~57 % CPU реплики
уходит в psycopg — накладные расходы на каждый оператор; на одно
сообщение ~11 обращений к PostgreSQL в двух транзакциях (проверка
членства, BEGIN, ключ, часы чата, сообщение, COMMIT, проверки пула).

- migrations/0003: функция post_message — та же логика и тот же SQL,
  что в многооператорном пути; вызывается в autocommit, поэтому вызов и
  есть транзакция (ключ, часы чата и сообщение — всё или ничего).
- пул: autocommit-соединения; многооператорная работа по-прежнему в явной
  conn.transaction(); ping — один оператор без транзакции.
- MESSAGE_WRITE_PATH=function (по умолчанию) | multi (прежний путь) — A/B
  на одном образе. Порядок ответов одинаков: постороннему всегда 404,
  даже при неверном ключе/теле.
- Оба режима проходят одни и те же тесты идемпотентности и контракта.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Alexey Bodanyuk
2026-10-19 16:03:22 +03:00
co-authored by Claude Opus 5.5
parent 26a0d86431
commit 4830be414e
10 changed files with 141 additions and 15 deletions
+2
View File
@@ -15,6 +15,8 @@ CACHE_URL_FILE=/run/secrets/cache_url
API_REPLICAS=2 API_REPLICAS=2
# Idempotency-Key results are kept at least this long (contract: >= 24 h). # Idempotency-Key results are kept at least this long (contract: >= 24 h).
IDEMPOTENCY_TTL_SECONDS=86400 IDEMPOTENCY_TTL_SECONDS=86400
# Write path of POST message: function = one SQL call (migration 0003), multi = lab3 baseline path.
MESSAGE_WRITE_PATH=function
# Additional settings of this implementation (defaults shown; all optional): # Additional settings of this implementation (defaults shown; all optional):
LOG_LEVEL=info LOG_LEVEL=info
DB_POOL_MIN=1 DB_POOL_MIN=1
+2
View File
@@ -27,6 +27,8 @@ x-api-env: &api-env
DRAIN_SECONDS: ${DRAIN_SECONDS:-3} DRAIN_SECONDS: ${DRAIN_SECONDS:-3}
SHUTDOWN_TIMEOUT_SECONDS: ${SHUTDOWN_TIMEOUT_SECONDS:-8} SHUTDOWN_TIMEOUT_SECONDS: ${SHUTDOWN_TIMEOUT_SECONDS:-8}
DOCS_ENABLED: ${DOCS_ENABLED:-true} DOCS_ENABLED: ${DOCS_ENABLED:-true}
# Track 1 improvement: `function` = one SQL call per send (default), `multi` = old path (A/B).
MESSAGE_WRITE_PATH: ${MESSAGE_WRITE_PATH:-function}
services: services:
postgres: postgres:
+50
View File
@@ -0,0 +1,50 @@
-- 0003 (lab 3, track 1 improvement): the whole idempotent "send message" as ONE statement.
-- Additive (a new function), so replicas of the previous version keep working while it is
-- applied, and the previous write path (MESSAGE_WRITE_PATH=multi) stays usable for A/B runs.
--
-- Same semantics and the same SQL as repo.post_message (multi-statement path), but executed
-- inside the server: the API sends one call instead of ~11 round trips in two transactions
-- (membership check, BEGIN, key claim, chat clock, message, COMMIT, pool checks). Called in
-- autocommit mode, so the function call IS the transaction: key row, chat clock and message
-- commit together or not at all. VOLATILE + READ COMMITTED: every statement inside takes a
-- fresh snapshot, so after waiting on a concurrent claim of the same key the stored result
-- of the winner is visible, exactly as in the multi-statement path.
--
-- o_status: created | replayed | conflict | not_found | retry (key vanished in between: cleanup)
CREATE FUNCTION post_message(p_user uuid, p_chat uuid, p_key text, p_hash bytea, p_message uuid,
p_text bytea, p_ttl_seconds integer)
RETURNS TABLE (o_status text, o_id uuid, o_text bytea, o_created_at timestamptz)
LANGUAGE plpgsql VOLATILE AS $$
DECLARE
v_created timestamptz;
BEGIN
PERFORM 1 FROM chat_members m WHERE m.chat_id = p_chat AND m.user_id = p_user;
IF NOT FOUND THEN
RETURN QUERY SELECT 'not_found'::text, NULL::uuid, NULL::bytea, NULL::timestamptz;
RETURN;
END IF;
INSERT INTO idempotency_keys AS k (user_id, chat_id, key, request_hash, message_id)
VALUES (p_user, p_chat, p_key, p_hash, p_message)
ON CONFLICT (user_id, chat_id, key) DO UPDATE
SET request_hash = EXCLUDED.request_hash, message_id = EXCLUDED.message_id, created_at = clock_timestamp()
WHERE k.created_at < clock_timestamp() - make_interval(secs => p_ttl_seconds);
IF FOUND THEN
-- Per-chat clock under the chat row lock (see migrations/0001 and docs/DATA_MODEL.md).
UPDATE chats c SET last_message_at = greatest(clock_timestamp(), c.last_message_at + interval '1 microsecond')
WHERE c.id = p_chat RETURNING c.last_message_at INTO v_created;
INSERT INTO messages (id, chat_id, sender_id, text, created_at)
VALUES (p_message, p_chat, p_user, p_text, v_created);
RETURN QUERY SELECT 'created'::text, p_message, p_text, v_created;
RETURN;
END IF;
RETURN QUERY
SELECT CASE WHEN k.request_hash = p_hash THEN 'replayed' ELSE 'conflict' END, m.id, m.text, m.created_at
FROM idempotency_keys k JOIN messages m ON m.id = k.message_id
WHERE k.user_id = p_user AND k.chat_id = p_chat AND k.key = p_key;
IF NOT FOUND THEN
RETURN QUERY SELECT 'retry'::text, NULL::uuid, NULL::bytea, NULL::timestamptz;
END IF;
END
$$;
+30 -11
View File
@@ -287,23 +287,41 @@ async def get_chat(request: Request) -> JSONResponse:
return ok((await repo.get_chat(db_of(request), user_id, chat_id)).to_json()) return ok((await repo.get_chat(db_of(request), user_id, chat_id)).to_json())
async def create_message(request: Request) -> JSONResponse: def parse_message(data: dict[str, Any]) -> tuple[str, list[str]]:
user_id = await authenticate(request)
chat_id = path_uuid(request, "chat_id")
db = db_of(request)
await repo.ensure_member(db, user_id, chat_id) # outsiders get 404 before key/body are looked at
key = idempotency_key(request)
data = await read_json(request)
validation.check_fields(data, {"text"}, frozenset({"attachment_ids"})) validation.check_fields(data, {"text"}, frozenset({"attachment_ids"}))
text = validation.text_field(data, "text", 4000) text = validation.text_field(data, "text", 4000)
attachment_ids = validation.attachment_ids_field(data) attachment_ids = validation.attachment_ids_field(data)
if attachment_ids: if attachment_ids:
# Lab 3 has no attachments: every referenced ID is unknown (lab 4 semantics: 404). # Lab 3 has no attachments: every referenced ID is unknown (lab 4 semantics: 404).
raise NotFound("Вложение не найдено") raise NotFound("Вложение не найдено")
# sender_id is derived from the session, never taken from the body. return text, attachment_ids
async def create_message(request: Request) -> JSONResponse:
"""Order of answers for both write paths: 401 -> 400 bad chat id -> 404 outsider -> 400 key/body
-> 409 other body with the same key -> 201 (new or replayed). sender_id comes from the session."""
user_id = await authenticate(request)
chat_id = path_uuid(request, "chat_id")
db = db_of(request)
settings = request.app.state.settings settings = request.app.state.settings
result = await repo.post_message(db, user_id, chat_id, key, request_fingerprint(text, attachment_ids), text, if settings.message_write_path == "multi":
settings.idempotency_ttl_seconds) await repo.ensure_member(db, user_id, chat_id) # outsiders get 404 before key/body are looked at
key = idempotency_key(request)
text, attachment_ids = parse_message(await read_json(request))
result = await repo.post_message(db, user_id, chat_id, key, request_fingerprint(text, attachment_ids), text,
settings.idempotency_ttl_seconds)
else:
try:
key = idempotency_key(request)
text, attachment_ids = parse_message(await read_json(request))
except ApiError:
# Rare error path only: an outsider must still get 404, not a hint about the body.
await repo.ensure_member(db, user_id, chat_id)
raise
# Membership check, key claim, chat clock and message: one SQL call, one transaction.
result = await repo.post_message_single_call(db, user_id, chat_id, key,
request_fingerprint(text, attachment_ids), text,
settings.idempotency_ttl_seconds)
if result.replayed: if result.replayed:
log.info("idempotent_replay", extra={"fields": {"request_id": request.state.request_id, log.info("idempotent_replay", extra={"fields": {"request_id": request.state.request_id,
"message_id": result.message.id}}) "message_id": result.message.id}})
@@ -361,7 +379,8 @@ def create_app(settings: Settings | None = None) -> Starlette:
log.info("dependencies_configured", extra={"fields": { log.info("dependencies_configured", extra={"fields": {
"session_store": sessions.name, "session_ttl_s": settings.session_ttl_seconds, "session_store": sessions.name, "session_ttl_s": settings.session_ttl_seconds,
"db_pool_max": settings.db_pool_max, "db_timeout_s": settings.db_timeout_seconds, "db_pool_max": settings.db_pool_max, "db_timeout_s": settings.db_timeout_seconds,
"instance_id": settings.instance_id, "drain_s": settings.drain_seconds}}) "instance_id": settings.instance_id, "drain_s": settings.drain_seconds,
"message_write_path": settings.message_write_path}})
tasks = [asyncio.create_task(purge_loop())] tasks = [asyncio.create_task(purge_loop())]
if settings.stats_log_seconds > 0: if settings.stats_log_seconds > 0:
tasks.append(asyncio.create_task(stats_loop(settings.stats_log_seconds))) tasks.append(asyncio.create_task(stats_loop(settings.stats_log_seconds)))
+11
View File
@@ -69,6 +69,13 @@ def _bool(name: str, default: bool) -> bool:
return raw in {"true", "1"} return raw in {"true", "1"}
def _choice(name: str, default: str, allowed: set[str]) -> str:
value = os.environ.get(name, "").strip().lower() or default
if value not in allowed:
raise ConfigError(f"{name} must be one of {sorted(allowed)}, got {value!r}")
return value
def _secret(name: str, required: bool) -> str: def _secret(name: str, required: bool) -> str:
"""Value of <NAME>_FILE (preferred, Docker secret) or <NAME> (local runs/tests).""" """Value of <NAME>_FILE (preferred, Docker secret) or <NAME> (local runs/tests)."""
path = os.environ.get(f"{name}_FILE", "").strip() path = os.environ.get(f"{name}_FILE", "").strip()
@@ -107,6 +114,7 @@ class Settings:
drain_seconds: float = 0.0 drain_seconds: float = 0.0
idempotency_ttl_seconds: int = 86400 idempotency_ttl_seconds: int = 86400
stats_log_seconds: float = 0.0 stats_log_seconds: float = 0.0
message_write_path: str = "function"
@property @property
def db_statement_timeout_ms(self) -> int: def db_statement_timeout_ms(self) -> int:
@@ -154,4 +162,7 @@ class Settings:
idempotency_ttl_seconds=_int("IDEMPOTENCY_TTL_SECONDS", 86400, 86400, 30 * 24 * 3600), idempotency_ttl_seconds=_int("IDEMPOTENCY_TTL_SECONDS", 86400, 86400, 30 * 24 * 3600),
# Experiments (bench/track1): log DB pool counters and process CPU every N s; 0 = off. # Experiments (bench/track1): log DB pool counters and process CPU every N s; 0 = off.
stats_log_seconds=_float("STATS_LOG_SECONDS", 0.0, 0.0, 60.0), stats_log_seconds=_float("STATS_LOG_SECONDS", 0.0, 0.0, 60.0),
# Track 1: `function` = one SQL call per send (migration 0003), `multi` = the previous
# multi-statement transaction; both have identical semantics (A/B on one image).
message_write_path=_choice("MESSAGE_WRITE_PATH", "function", {"function", "multi"}),
) )
+9 -2
View File
@@ -74,6 +74,10 @@ class Database:
"options": options, "options": options,
"connect_timeout": max(1, int(settings.db_timeout_seconds)), "connect_timeout": max(1, int(settings.db_timeout_seconds)),
"application_name": "messenger-api", "application_name": "messenger-api",
# Autocommit connections: a single statement (post_message function, ping) is its
# own transaction with ONE round trip; multi-statement work uses an explicit
# conn.transaction() (BEGIN ... COMMIT), see run().
"autocommit": True,
# Detect a dead peer / lost network without any cancel request (see module doc). # Detect a dead peer / lost network without any cancel request (see module doc).
"keepalives": 1, "keepalives": 1,
"keepalives_idle": 5, "keepalives_idle": 5,
@@ -91,14 +95,17 @@ class Database:
async def close(self) -> None: async def close(self) -> None:
await self.pool.close(timeout=2) await self.pool.close(timeout=2)
async def run(self, work: Work[T], deadline: float | None = None) -> T: async def run(self, work: Work[T], deadline: float | None = None, *, transaction: bool = True) -> T:
"""Run `work(conn)` in one transaction (COMMIT on success, ROLLBACK on any exception). """Run `work(conn)` in one transaction (COMMIT on success, ROLLBACK on any exception).
transaction=False: `work` issues exactly ONE statement, which autocommit makes atomic.
Domain errors raised by `work` (NotFound, Conflict, ...) propagate unchanged; Domain errors raised by `work` (NotFound, Conflict, ...) propagate unchanged;
database unavailability and the deadline become Unavailable (503). database unavailability and the deadline become Unavailable (503).
""" """
async def unit() -> T: async def unit() -> T:
async with self.pool.connection() as conn: async with self.pool.connection() as conn:
if not transaction:
return await work(conn)
async with conn.transaction(): async with conn.transaction():
return await work(conn) return await work(conn)
@@ -118,7 +125,7 @@ class Database:
async def select_one(conn: psycopg.AsyncConnection) -> None: async def select_one(conn: psycopg.AsyncConnection) -> None:
await conn.execute("SELECT 1") await conn.execute("SELECT 1")
try: try:
await self.run(select_one, deadline=timeout) await self.run(select_one, deadline=timeout, transaction=False)
return True return True
except Unavailable: except Unavailable:
return False return False
+23
View File
@@ -268,6 +268,29 @@ async def post_message(db: Database, user_id: str, chat_id: str, key: str, reque
return await db.run(work) return await db.run(work)
POST_MESSAGE_CALL = "SELECT o_status, o_id, o_text, o_created_at FROM post_message(%s, %s, %s, %s, %s, %s, %s)"
async def post_message_single_call(db: Database, user_id: str, chat_id: str, key: str, request_hash: bytes,
text: str, ttl_seconds: int) -> PostResult:
"""Same contract as post_message, ONE round trip: SQL function post_message (migration 0003)
in autocommit mode, i.e. the call is the whole transaction. Track 1 improvement."""
message_id = uuid.uuid4()
async def work(conn: psycopg.AsyncConnection) -> tuple:
cur = await conn.execute(POST_MESSAGE_CALL,
(user_id, chat_id, key, request_hash, message_id, _b(text), ttl_seconds))
return await cur.fetchone()
status, stored_id, stored_text, created_at = await db.run(work, transaction=False)
if status == "not_found":
raise NotFound("Чат не найден")
if status == "conflict":
raise Conflict("Idempotency-Key уже использован с другим сообщением")
if status == "retry":
raise Unavailable("Повторите запрос с тем же Idempotency-Key")
return PostResult(Message(str(stored_id), chat_id, user_id, _s(stored_text), created_at), status == "replayed")
async def purge_idempotency_keys(db: Database, ttl_seconds: int, batch: int = 5000) -> int: async def purge_idempotency_keys(db: Database, ttl_seconds: int, batch: int = 5000) -> int:
"""Delete expired keys in bounded batches; one replica at a time (advisory xact lock).""" """Delete expired keys in bounded batches; one replica at a time (advisory xact lock)."""
async def work(conn: psycopg.AsyncConnection) -> int: async def work(conn: psycopg.AsyncConnection) -> int:
+1 -1
View File
@@ -317,7 +317,7 @@ def test_running_containers_have_limits_and_no_bypass_ports():
def test_migrations_ran_once_by_the_migrate_service(): def test_migrations_ran_once_by_the_migrate_service():
applied = psql("SELECT version FROM schema_migrations ORDER BY version").split() applied = psql("SELECT version FROM schema_migrations ORDER BY version").split()
assert applied == ["0001_init", "0002_idempotency_keys"] assert applied == ["0001_init", "0002_idempotency_keys", "0003_post_message_function"]
migrate = compose("ps", "-a", "--format", "json", "migrate").stdout migrate = compose("ps", "-a", "--format", "json", "migrate").stdout
rows = [json.loads(line) for line in migrate.splitlines() if line.strip()] rows = [json.loads(line) for line in migrate.splitlines() if line.strip()]
assert rows and all(r["State"] == "exited" and r["ExitCode"] == 0 for r in rows) assert rows and all(r["State"] == "exited" and r["ExitCode"] == 0 for r in rows)
+2 -1
View File
@@ -77,7 +77,8 @@ def test_migrations_rerun_is_a_noop():
result = compose("run", "--rm", "--no-deps", "migrate") result = compose("run", "--rm", "--no-deps", "migrate")
assert "0001_init: already applied, skipped" in result.stdout assert "0001_init: already applied, skipped" in result.stdout
assert "0002_idempotency_keys: already applied, skipped" in result.stdout assert "0002_idempotency_keys: already applied, skipped" in result.stdout
assert psql("SELECT count(*) FROM schema_migrations") == "2" assert "0003_post_message_function: already applied, skipped" in result.stdout
assert psql("SELECT count(*) FROM schema_migrations") == "3"
assert psql("SELECT count(*) FROM users") == users_before assert psql("SELECT count(*) FROM users") == users_before
+11
View File
@@ -189,3 +189,14 @@ def test_idempotency_ttl_cannot_be_below_24_hours(monkeypatch):
monkeypatch.setenv("IDEMPOTENCY_TTL_SECONDS", "3600") monkeypatch.setenv("IDEMPOTENCY_TTL_SECONDS", "3600")
with pytest.raises(ConfigError): with pytest.raises(ConfigError):
Settings.from_env() Settings.from_env()
def test_message_write_path_setting(monkeypatch):
monkeypatch.setenv("DATABASE_URL", "postgresql://x@y/z")
monkeypatch.delenv("MESSAGE_WRITE_PATH", raising=False)
assert Settings.from_env().message_write_path == "function"
monkeypatch.setenv("MESSAGE_WRITE_PATH", "multi")
assert Settings.from_env().message_write_path == "multi"
monkeypatch.setenv("MESSAGE_WRITE_PATH", "fast")
with pytest.raises(ConfigError):
Settings.from_env()