- upload, metadata and download endpoints for PNG/JPEG attachments:
limits before reading and decompression, type by content,
structural integrity check without decoding pixels, safe filename
- write order: pending row with object key -> PUT to S3 -> ready;
per-step DB sessions so no pool connection is held during transfers
- attachment_ids in messages (validation, idempotency hash, history);
whitespace-only text allowed with an attachment (teacher, 2026-10-20)
- migration: attachments and message_attachments tables, text length
CHECK relaxed with NOT VALID
- student tests, fault checks and driver commands for attachments;
rollout profile starts from e1161f7 and checks the commit first
- sync attachments deltas into main specs; rules, AGENTS.md, PLAN.md
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
461 lines
15 KiB
Python
461 lines
15 KiB
Python
"""Спек `api-conventions`: JSON, ошибки, X-Request-Id, X-Instance-Id,
|
||
форматы."""
|
||
|
||
import json
|
||
import urllib.parse
|
||
import uuid
|
||
from collections import Counter
|
||
from typing import Any
|
||
|
||
import httpx
|
||
import pytest
|
||
|
||
import images
|
||
from api_client import (
|
||
API,
|
||
Actor,
|
||
Api,
|
||
new_key,
|
||
registration,
|
||
unique_username,
|
||
)
|
||
from contract import (
|
||
assert_content,
|
||
assert_created_at,
|
||
assert_error,
|
||
assert_errors,
|
||
assert_instance_id,
|
||
assert_ok,
|
||
assert_uuid,
|
||
json_body,
|
||
)
|
||
|
||
UNICODE_TEXT = "Привет, мир 👋"
|
||
# не UUID в пути: типы JSON, записанные строкой URL
|
||
NOT_UUID_PATHS = ("123", "false", "[]", "{}")
|
||
# не UUID в элементе member_ids: значения других типов JSON
|
||
NOT_UUID_VALUES: tuple[Any, ...] = ([], {}, 123, False)
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Unicode сохраняется")
|
||
def test_unicode_round_trip(api: Api, bob: Actor) -> None:
|
||
alice = api.register(display_name=UNICODE_TEXT)
|
||
chat = api.create_chat(alice, bob, title=UNICODE_TEXT)
|
||
resp = api.post_message(alice, chat["id"], json={"text": UNICODE_TEXT})
|
||
message = assert_ok(resp, 201, "Message")
|
||
# тело разбирается из байтов как UTF-8, без догадок httpx о кодировке
|
||
assert json.loads(resp.content.decode("utf-8"))["text"] == UNICODE_TEXT
|
||
|
||
me = assert_ok(
|
||
api.request("GET", f"{API}/users/me", actor=alice),
|
||
200,
|
||
"User",
|
||
)
|
||
stored_chat = assert_ok(
|
||
api.request("GET", f"{API}/chats/{chat['id']}", actor=bob),
|
||
200,
|
||
"Chat",
|
||
)
|
||
history = api.all_messages(bob, chat["id"])
|
||
assert alice.user["display_name"] == me["display_name"] == UNICODE_TEXT
|
||
assert chat["title"] == stored_chat["title"] == UNICODE_TEXT
|
||
assert [item["text"] for item in history] == [message["text"]]
|
||
assert message["text"] == UNICODE_TEXT
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Длина в code points")
|
||
def test_length_in_code_points(api: Api, alice: Actor) -> None:
|
||
title = "👋" * 100
|
||
assert len(title.encode("utf-8")) > 100
|
||
chat = api.create_chat(alice, title=title)
|
||
assert chat["title"] == title
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Успешный ответ")
|
||
def test_request_id_on_success(api: Api, alice: Actor) -> None:
|
||
responses = [
|
||
api.request("GET", "/health/live"),
|
||
api.request("GET", f"{API}/users/me", actor=alice),
|
||
api.request("GET", f"{API}/chats", actor=alice),
|
||
]
|
||
for resp in responses:
|
||
assert resp.status_code == 200
|
||
assert resp.headers.get("X-Request-Id", "").strip()
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Разные запросы")
|
||
def test_request_ids_differ(api: Api) -> None:
|
||
first = api.request("GET", "/health/live").headers["X-Request-Id"]
|
||
second = api.request("GET", "/health/live").headers["X-Request-Id"]
|
||
assert first != second
|
||
|
||
|
||
def business_responses(
|
||
api: Api,
|
||
alice: Actor,
|
||
eve: Actor,
|
||
chat: dict[str, Any],
|
||
) -> list[tuple[httpx.Response, int]]:
|
||
"""Успехи 200 и 201 и ошибки 400, 401, 404 и 409 — с ожидаемым
|
||
статусом."""
|
||
key = new_key()
|
||
sent = api.post_message(alice, chat["id"], key=key, json={"text": "a"})
|
||
return [
|
||
(api.request("GET", f"{API}/users/me", actor=alice), 200),
|
||
(sent, 201),
|
||
(api.request("GET", f"{API}/chats/nope", actor=alice), 400),
|
||
(api.request("GET", f"{API}/users/me"), 401),
|
||
(api.request("GET", f"{API}/chats/{chat['id']}", actor=eve), 404),
|
||
(
|
||
api.post_message(alice, chat["id"], key=key, json={"text": "b"}),
|
||
409,
|
||
),
|
||
]
|
||
|
||
|
||
def service_responses(api: Api) -> list[tuple[httpx.Response, int]]:
|
||
"""Health, неизвестный путь и неподдерживаемый метод."""
|
||
return [
|
||
(api.request("GET", "/health/live"), 200),
|
||
(api.request("GET", "/health/ready"), 200),
|
||
(api.request("GET", f"{API}/unknown"), 404),
|
||
(api.request("DELETE", f"{API}/users"), 405),
|
||
]
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Instance id в успешном ответе и ошибке")
|
||
def test_instance_id_on_success_and_error(
|
||
api: Api,
|
||
alice: Actor,
|
||
eve: Actor,
|
||
chat: dict[str, Any],
|
||
) -> None:
|
||
for resp, status in business_responses(api, alice, eve, chat):
|
||
assert resp.status_code == status, resp.text
|
||
assert_instance_id(resp)
|
||
|
||
|
||
@pytest.mark.spec(
|
||
"api-conventions",
|
||
"Instance id в health и служебных ответах",
|
||
)
|
||
def test_instance_id_on_service_responses(api: Api) -> None:
|
||
for resp, status in service_responses(api):
|
||
assert resp.status_code == status, resp.text
|
||
assert_instance_id(resp)
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Одно значение на процесс")
|
||
def test_one_instance_id_per_process(
|
||
api: Api,
|
||
alice: Actor,
|
||
eve: Actor,
|
||
chat: dict[str, Any],
|
||
expect_replicas: int,
|
||
) -> None:
|
||
"""Две одинаковые серии по 18 разных запросов. Против одного процесса
|
||
— одно значение на всё. Через балансировщик (round-robin, до 8
|
||
реплик) каждая реплика отвечает в серии хотя бы дважды: значение,
|
||
новое на каждый запрос, не прошло бы ни одну проверку."""
|
||
|
||
def series() -> list[str]:
|
||
responses = business_responses(api, alice, eve, chat)
|
||
for _ in range(3):
|
||
responses += service_responses(api)
|
||
return [assert_instance_id(resp) for resp, _ in responses]
|
||
|
||
first, second = series(), series()
|
||
counts = Counter(first + second)
|
||
print(f"two series of {len(first)} requests: {dict(counts)}")
|
||
if expect_replicas < 2:
|
||
assert len(counts) == 1, f"one process answered with {set(counts)}"
|
||
return
|
||
assert all(served > 1 for served in counts.values()), counts
|
||
assert set(second) <= set(first), (
|
||
f"new X-Instance-Id in the second series: {set(second) - set(first)}"
|
||
)
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Ошибка содержит request_id заголовка")
|
||
def test_error_request_id_matches_header(
|
||
api: Api,
|
||
alice: Actor,
|
||
eve: Actor,
|
||
chat: dict[str, Any],
|
||
) -> None:
|
||
# assert_error сверяет error.request_id с заголовком у каждой ошибки
|
||
assert_error(api.request("GET", f"{API}/chats/nope", actor=alice), 400)
|
||
assert_error(api.request("GET", f"{API}/users/me"), 401)
|
||
assert_error(
|
||
api.request("GET", f"{API}/chats/{chat['id']}", actor=eve),
|
||
404,
|
||
)
|
||
assert_error(api.request("DELETE", f"{API}/users"), 405)
|
||
resp = api.request(
|
||
"POST",
|
||
f"{API}/users",
|
||
json=registration(alice.username, "Alice"),
|
||
)
|
||
assert_error(resp, 409)
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Нет тела FastAPI по умолчанию")
|
||
def test_no_fastapi_detail(api: Api, alice: Actor) -> None:
|
||
validation = api.request(
|
||
"POST",
|
||
f"{API}/users",
|
||
json=registration("ab", "x"),
|
||
)
|
||
not_found = api.request("GET", f"{API}/unknown", actor=alice)
|
||
for resp, status in ((validation, 400), (not_found, 404)):
|
||
assert_error(resp, status)
|
||
assert list(json_body(resp)) == ["error"]
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Неизвестный путь")
|
||
def test_unknown_path(api: Api) -> None:
|
||
assert_error(api.request("GET", f"{API}/unknown"), 404)
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Неподдерживаемый метод")
|
||
def test_method_not_allowed(api: Api) -> None:
|
||
assert_error(api.request("DELETE", f"{API}/users"), 405)
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Лишнее поле")
|
||
def test_extra_field(api: Api, alice: Actor) -> None:
|
||
resp = api.request(
|
||
"POST",
|
||
f"{API}/users",
|
||
json={**registration(unique_username(), "Extra"), "is_admin": True},
|
||
)
|
||
assert_error(resp, 400)
|
||
resp = api.request(
|
||
"POST",
|
||
f"{API}/chats",
|
||
actor=alice,
|
||
json={"title": "Extra", "member_ids": [alice.id], "topic": "x"},
|
||
)
|
||
assert_error(resp, 400)
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Неверный тип без приведения")
|
||
def test_wrong_type_is_not_coerced(api: Api) -> None:
|
||
username = unique_username()
|
||
resp = api.request(
|
||
"POST",
|
||
f"{API}/users",
|
||
json=registration(username, 123),
|
||
)
|
||
assert_error(resp, 400)
|
||
# пользователь не создан: то же имя свободно
|
||
user = api.register(username=username, display_name="123").user
|
||
assert user["display_name"] == "123"
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Формат created_at")
|
||
@pytest.mark.spec("api-conventions", "Формат id")
|
||
def test_id_and_created_at_format(
|
||
api: Api,
|
||
alice: Actor,
|
||
chat: dict[str, Any],
|
||
) -> None:
|
||
message = api.send_message(alice, chat["id"], "format")
|
||
for obj in (alice.user, chat, message):
|
||
assert_uuid(obj["id"])
|
||
assert_created_at(obj["created_at"])
|
||
for member_id in chat["member_ids"]:
|
||
assert_uuid(member_id)
|
||
assert_uuid(message["chat_id"])
|
||
assert_uuid(message["sender_id"])
|
||
|
||
|
||
def other_uuid_forms(value: str) -> dict[str, str]:
|
||
"""Тот же UUID в записях, которых нет в `format: uuid` контракта."""
|
||
return {
|
||
"no hyphens": value.replace("-", ""),
|
||
"urn": f"urn:uuid:{value}",
|
||
"braces": f"{{{value}}}",
|
||
}
|
||
|
||
|
||
def chat_id_requests(
|
||
api: Api,
|
||
actor: Actor,
|
||
chat_id: str,
|
||
) -> dict[str, httpx.Response]:
|
||
"""Три ручки с `chat_id` в пути; значение кодируется для URL явно."""
|
||
quoted = urllib.parse.quote(chat_id, safe="")
|
||
return {
|
||
"GET chat": api.request("GET", f"{API}/chats/{quoted}", actor=actor),
|
||
"GET history": api.messages_page(actor, quoted),
|
||
"POST message": api.post_message(
|
||
actor,
|
||
quoted,
|
||
json={"text": "path"},
|
||
),
|
||
}
|
||
|
||
|
||
def post_chat(
|
||
api: Api,
|
||
actor: Actor,
|
||
title: str,
|
||
member_ids: list[Any],
|
||
) -> httpx.Response:
|
||
return api.request(
|
||
"POST",
|
||
f"{API}/chats",
|
||
actor=actor,
|
||
json={"title": title, "member_ids": member_ids},
|
||
)
|
||
|
||
|
||
def chat_titles(api: Api, actor: Actor) -> set[str]:
|
||
return {
|
||
chat["title"]
|
||
for page in api.chat_pages(actor)
|
||
for chat in page["items"]
|
||
}
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "UUID другого типа в теле")
|
||
def test_uuid_of_other_type_in_body(api: Api, alice: Actor) -> None:
|
||
title = f"rejected-{uuid.uuid4().hex}"
|
||
# рядом с id Алисы: иначе 400 дала бы и проверка «вызывающий в списке»
|
||
assert_errors(
|
||
{
|
||
repr(value): post_chat(api, alice, title, [alice.id, value])
|
||
for value in NOT_UUID_VALUES
|
||
},
|
||
400,
|
||
)
|
||
assert title not in chat_titles(api, alice)
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Не UUID в пути")
|
||
def test_not_uuid_in_path(api: Api, alice: Actor) -> None:
|
||
assert_errors(
|
||
{
|
||
f"{name} {value}": resp
|
||
for value in NOT_UUID_PATHS
|
||
for name, resp in chat_id_requests(api, alice, value).items()
|
||
},
|
||
400,
|
||
)
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Другая запись UUID")
|
||
def test_other_uuid_forms(
|
||
api: Api,
|
||
alice: Actor,
|
||
bob: Actor,
|
||
chat: dict[str, Any],
|
||
) -> None:
|
||
history = api.all_messages(alice, chat["id"])
|
||
title = f"rejected-{uuid.uuid4().hex}"
|
||
responses = {
|
||
f"{name} / {form}": resp
|
||
for form, value in other_uuid_forms(chat["id"]).items()
|
||
for name, resp in chat_id_requests(api, alice, value).items()
|
||
}
|
||
responses |= {
|
||
f"member_ids / {form}": post_chat(api, alice, title, [alice.id, value])
|
||
for form, value in other_uuid_forms(bob.id).items()
|
||
}
|
||
assert_errors(responses, 400)
|
||
assert api.all_messages(alice, chat["id"]) == history
|
||
assert title not in chat_titles(api, alice)
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "UUID в верхнем регистре в пути")
|
||
def test_upper_case_uuid_in_path(
|
||
api: Api,
|
||
alice: Actor,
|
||
chat: dict[str, Any],
|
||
) -> None:
|
||
upper = chat["id"].upper()
|
||
got = api.request("GET", f"{API}/chats/{upper}", actor=alice)
|
||
# assert_ok проверяет и формат: id и chat_id в ответах — нижний регистр
|
||
assert assert_ok(got, 200, "Chat") == chat
|
||
sent = assert_ok(
|
||
api.post_message(alice, upper, json={"text": "upper"}),
|
||
201,
|
||
"Message",
|
||
)
|
||
assert sent["chat_id"] == chat["id"]
|
||
upper_page = assert_ok(api.messages_page(alice, upper), 200, "MessagePage")
|
||
lower_page = assert_ok(
|
||
api.messages_page(alice, chat["id"]),
|
||
200,
|
||
"MessagePage",
|
||
)
|
||
assert upper_page == lower_page == {"items": [sent], "next_cursor": None}
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Лимит и тип вложения")
|
||
def test_attachment_limit_and_type_codes(
|
||
api: Api,
|
||
alice: Actor,
|
||
chat: dict[str, Any],
|
||
) -> None:
|
||
over = images.png_of_size(images.MAX_BYTES + 1)
|
||
assert_error(api.post_attachment(alice, chat["id"], over), 413)
|
||
text = "не картинка".encode()
|
||
assert_error(api.post_attachment(alice, chat["id"], text), 415)
|
||
|
||
|
||
def attachment_requests(
|
||
api: Api,
|
||
actor: Actor,
|
||
attachment_id: str,
|
||
) -> dict[str, httpx.Response]:
|
||
quoted = urllib.parse.quote(attachment_id, safe="")
|
||
return {
|
||
"meta": api.attachment_meta(actor, quoted),
|
||
"content": api.attachment_content(actor, quoted),
|
||
}
|
||
|
||
|
||
@pytest.mark.spec("api-conventions", "Идентификаторы вложений в другой записи")
|
||
def test_attachment_ids_in_other_forms(
|
||
api: Api,
|
||
alice: Actor,
|
||
chat: dict[str, Any],
|
||
) -> None:
|
||
attachment = api.upload(alice, chat["id"], images.sample_png())
|
||
responses = {
|
||
f"{name} / {form}": resp
|
||
for form, value in other_uuid_forms(attachment["id"]).items()
|
||
for name, resp in attachment_requests(api, alice, value).items()
|
||
}
|
||
responses |= {
|
||
f"attachment_ids / {form}": api.post_message(
|
||
alice,
|
||
chat["id"],
|
||
json={"text": "x", "attachment_ids": [value]},
|
||
)
|
||
for form, value in other_uuid_forms(attachment["id"]).items()
|
||
}
|
||
assert_errors(responses, 400)
|
||
assert api.all_messages(alice, chat["id"]) == []
|
||
|
||
|
||
@pytest.mark.spec(
|
||
"api-conventions",
|
||
"Идентификаторы вложений в верхнем регистре",
|
||
)
|
||
def test_attachment_ids_in_upper_case(
|
||
api: Api,
|
||
alice: Actor,
|
||
chat: dict[str, Any],
|
||
) -> None:
|
||
data = images.sample_png()
|
||
attachment = api.upload(alice, chat["id"], data)
|
||
upper = attachment["id"].upper()
|
||
meta = assert_ok(api.attachment_meta(alice, upper), 200, "Attachment")
|
||
assert meta == attachment
|
||
assert_content(api.attachment_content(alice, upper), data, "image/png")
|
||
message = api.send_message(alice, chat["id"], "x", attachment_ids=[upper])
|
||
assert message["attachment_ids"] == [attachment["id"]]
|