- 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>
440 lines
14 KiB
Python
440 lines
14 KiB
Python
"""HTTP-клиент набора: запросы к API и идентификация в одном месте."""
|
||
|
||
import base64
|
||
import dataclasses
|
||
import hashlib
|
||
import secrets
|
||
import uuid
|
||
from collections.abc import Callable, Sequence
|
||
from dataclasses import dataclass
|
||
from datetime import datetime
|
||
from typing import Any
|
||
|
||
import httpx
|
||
|
||
from contract import assert_ok
|
||
|
||
API = "/api/v1"
|
||
SESSIONS = f"{API}/auth/sessions"
|
||
# защита от бесконечного обхода, если next_cursor никогда не станет null
|
||
MAX_PAGES = 1000
|
||
# с лабы 3 обязателен у POST сообщения: одна отправка — один ключ, повтор
|
||
# неподтверждённой отправки — тот же ключ
|
||
IDEMPOTENCY_KEY = "Idempotency-Key"
|
||
|
||
|
||
class _NewKey:
|
||
"""Маркер `post_message`: сгенерировать новый ключ."""
|
||
|
||
def __repr__(self) -> str:
|
||
return "NEW_KEY"
|
||
|
||
|
||
NEW_KEY = _NewKey()
|
||
|
||
|
||
def unique_username() -> str:
|
||
"""Имя под `^[a-z0-9_]{3,32}$`, уникальное для каждого вызова."""
|
||
return f"t_{uuid.uuid4().hex[:12]}"
|
||
|
||
|
||
def unique_password() -> str:
|
||
"""Синтетический пароль из 12–128 символов, свой у каждого вызова."""
|
||
return f"pw-{uuid.uuid4().hex}"
|
||
|
||
|
||
def new_key() -> str:
|
||
"""Новый `Idempotency-Key`: 32 символа из допустимого алфавита."""
|
||
return uuid.uuid4().hex
|
||
|
||
|
||
def key_headers(key: str | None = None) -> dict[str, str]:
|
||
"""Заголовок ключа для запросов в обход `post_message`."""
|
||
return {IDEMPOTENCY_KEY: new_key() if key is None else key}
|
||
|
||
|
||
def registration(
|
||
username: str,
|
||
display_name: Any = "Test user",
|
||
password: Any = None,
|
||
) -> dict[str, Any]:
|
||
"""Тело `POST /users`; пароль по умолчанию — новый синтетический."""
|
||
return {
|
||
"username": username,
|
||
"display_name": display_name,
|
||
"password": unique_password() if password is None else password,
|
||
}
|
||
|
||
|
||
def basic_auth(username: str, password: str) -> dict[str, str]:
|
||
"""`Authorization: Basic` из username и пароля в UTF-8."""
|
||
raw = f"{username}:{password}".encode()
|
||
return {"Authorization": "Basic " + base64.b64encode(raw).decode("ascii")}
|
||
|
||
|
||
def bearer_auth(token: str) -> dict[str, str]:
|
||
return {"Authorization": f"Bearer {token}"}
|
||
|
||
|
||
def order_key(item: dict[str, Any]) -> tuple[datetime, int]:
|
||
"""Порядок списков API: `(created_at, id)`, id сравнивается как UUID."""
|
||
created_at = datetime.fromisoformat(item["created_at"])
|
||
return created_at, uuid.UUID(item["id"]).int
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class Actor:
|
||
"""Пользователь, его пароль и токен текущей сессии."""
|
||
|
||
user: dict[str, Any]
|
||
password: str
|
||
token: str
|
||
|
||
@classmethod
|
||
def unregistered(cls) -> "Actor":
|
||
"""Пользователь, которого нет на сервере, с невыданным токеном."""
|
||
return cls(
|
||
user={"id": str(uuid.uuid4()), "username": unique_username()},
|
||
password=unique_password(),
|
||
token=secrets.token_urlsafe(32),
|
||
)
|
||
|
||
@property
|
||
def id(self) -> str:
|
||
return self.user["id"]
|
||
|
||
@property
|
||
def username(self) -> str:
|
||
return self.user["username"]
|
||
|
||
def with_token(self, token: str) -> "Actor":
|
||
"""Тот же пользователь с другой сессией."""
|
||
return dataclasses.replace(self, token=token)
|
||
|
||
def headers(self) -> dict[str, str]:
|
||
"""Идентификация: с лабы 2 — Bearer-токен сессии."""
|
||
return bearer_auth(self.token)
|
||
|
||
|
||
class Api:
|
||
"""Тонкая обёртка над `httpx.Client` с методами API мессенджера."""
|
||
|
||
def __init__(self, base_url: str, *, timeout: float = 5) -> None:
|
||
self.client = httpx.Client(base_url=base_url, timeout=timeout)
|
||
|
||
def close(self) -> None:
|
||
self.client.close()
|
||
|
||
def __enter__(self) -> "Api":
|
||
return self
|
||
|
||
def __exit__(self, *_: object) -> None:
|
||
self.close()
|
||
|
||
def request(
|
||
self,
|
||
method: str,
|
||
path: str,
|
||
*,
|
||
actor: Actor | None = None,
|
||
headers: dict[str, str] | None = None,
|
||
**kwargs: Any,
|
||
) -> httpx.Response:
|
||
merged = actor.headers() if actor is not None else {}
|
||
merged.update(headers or {})
|
||
return self.client.request(method, path, headers=merged, **kwargs)
|
||
|
||
def register(
|
||
self,
|
||
*,
|
||
username: str | None = None,
|
||
display_name: str = "Test user",
|
||
password: str | None = None,
|
||
) -> Actor:
|
||
"""Регистрация и сразу вход: у пользователя есть токен."""
|
||
password = password or unique_password()
|
||
resp = self.request(
|
||
"POST",
|
||
f"{API}/users",
|
||
json=registration(
|
||
username or unique_username(),
|
||
display_name,
|
||
password,
|
||
),
|
||
)
|
||
user = assert_ok(resp, 201, "User")
|
||
return self.login(user, password)
|
||
|
||
def login_response(self, username: str, password: str) -> httpx.Response:
|
||
return self.request(
|
||
"POST",
|
||
SESSIONS,
|
||
headers=basic_auth(username, password),
|
||
)
|
||
|
||
def login(self, user: dict[str, Any], password: str) -> Actor:
|
||
"""Новая сессия пользователя; ответ проверяется по схеме `Session`."""
|
||
resp = self.login_response(user["username"], password)
|
||
session = assert_ok(resp, 201, "Session")
|
||
assert session["user"] == user, "session user differs from user"
|
||
return Actor(user=user, password=password, token=session["token"])
|
||
|
||
def logout(self, actor: Actor) -> httpx.Response:
|
||
return self.request("DELETE", f"{SESSIONS}/current", actor=actor)
|
||
|
||
def create_chat(
|
||
self,
|
||
actor: Actor,
|
||
*members: Actor,
|
||
title: str = "Test chat",
|
||
) -> dict[str, Any]:
|
||
"""Чат, где `actor` — первый участник, за ним `members`."""
|
||
member_ids = [actor.id, *(member.id for member in members)]
|
||
resp = self.request(
|
||
"POST",
|
||
f"{API}/chats",
|
||
actor=actor,
|
||
json={"title": title, "member_ids": member_ids},
|
||
)
|
||
return assert_ok(resp, 201, "Chat")
|
||
|
||
def post_message(
|
||
self,
|
||
actor: Actor | None,
|
||
chat_id: str,
|
||
*,
|
||
key: str | None | _NewKey = NEW_KEY,
|
||
headers: dict[str, str] | None = None,
|
||
**kwargs: Any,
|
||
) -> httpx.Response:
|
||
"""`POST` сообщения как есть; тело — `json=` или `content=`.
|
||
|
||
`key`: по умолчанию — новый ключ, `None` — без заголовка, строка —
|
||
этот ключ (в том числе пустой или неверный).
|
||
"""
|
||
merged = dict(headers or {})
|
||
if isinstance(key, _NewKey):
|
||
merged[IDEMPOTENCY_KEY] = new_key()
|
||
elif key is not None:
|
||
merged[IDEMPOTENCY_KEY] = key
|
||
return self.request(
|
||
"POST",
|
||
f"{API}/chats/{chat_id}/messages",
|
||
actor=actor,
|
||
headers=merged,
|
||
**kwargs,
|
||
)
|
||
|
||
def send_message(
|
||
self,
|
||
actor: Actor,
|
||
chat_id: str,
|
||
text: str,
|
||
*,
|
||
key: str | None = None,
|
||
attachment_ids: Sequence[str] | None = None,
|
||
) -> dict[str, Any]:
|
||
"""Успешная отправка: 201 и `Message`; без `key` — новый ключ.
|
||
|
||
`attachment_ids=None` — поля в теле нет.
|
||
"""
|
||
body: dict[str, Any] = {"text": text}
|
||
if attachment_ids is not None:
|
||
body["attachment_ids"] = list(attachment_ids)
|
||
resp = self.post_message(
|
||
actor,
|
||
chat_id,
|
||
key=new_key() if key is None else key,
|
||
json=body,
|
||
)
|
||
message = assert_ok(resp, 201, "Message")
|
||
if attachment_ids is not None:
|
||
assert message["attachment_ids"] == [
|
||
item.lower() for item in attachment_ids
|
||
], "attachment_ids differ from sent"
|
||
return message
|
||
|
||
def post_attachment(
|
||
self,
|
||
actor: Actor | None,
|
||
chat_id: str,
|
||
data: Any,
|
||
*,
|
||
content_type: str | None = "image/png",
|
||
filename: str | None = "image.png",
|
||
headers: dict[str, str] | None = None,
|
||
) -> httpx.Response:
|
||
"""Загрузка как есть: сырые байты (или итератор — частями, без
|
||
`Content-Length`); `None` — без заголовка или параметра."""
|
||
merged = dict(headers or {})
|
||
if content_type is not None:
|
||
merged["Content-Type"] = content_type
|
||
params = {} if filename is None else {"filename": filename}
|
||
return self.request(
|
||
"POST",
|
||
f"{API}/chats/{chat_id}/attachments",
|
||
actor=actor,
|
||
headers=merged,
|
||
params=params,
|
||
content=data,
|
||
)
|
||
|
||
def upload(
|
||
self,
|
||
actor: Actor,
|
||
chat_id: str,
|
||
data: bytes,
|
||
*,
|
||
content_type: str = "image/png",
|
||
filename: str = "image.png",
|
||
) -> dict[str, Any]:
|
||
"""Успешная загрузка: 201 и `Attachment` с размером и SHA-256."""
|
||
resp = self.post_attachment(
|
||
actor,
|
||
chat_id,
|
||
data,
|
||
content_type=content_type,
|
||
filename=filename,
|
||
)
|
||
attachment = assert_ok(resp, 201, "Attachment")
|
||
assert attachment["size_bytes"] == len(data), "size_bytes differs"
|
||
assert attachment["sha256"] == hashlib.sha256(data).hexdigest(), (
|
||
"sha256 differs"
|
||
)
|
||
assert attachment["chat_id"] == chat_id.lower(), "chat_id differs"
|
||
assert attachment["owner_id"] == actor.id, "owner_id differs"
|
||
assert attachment["filename"] == filename, "filename changed"
|
||
return attachment
|
||
|
||
def attachment_meta(
|
||
self,
|
||
actor: Actor | None,
|
||
attachment_id: str,
|
||
) -> httpx.Response:
|
||
return self.request(
|
||
"GET",
|
||
f"{API}/attachments/{attachment_id}",
|
||
actor=actor,
|
||
)
|
||
|
||
def attachment_content(
|
||
self,
|
||
actor: Actor | None,
|
||
attachment_id: str,
|
||
*,
|
||
variant: str | None = None,
|
||
) -> httpx.Response:
|
||
params = {} if variant is None else {"variant": variant}
|
||
return self.request(
|
||
"GET",
|
||
f"{API}/attachments/{attachment_id}/content",
|
||
actor=actor,
|
||
params=params,
|
||
)
|
||
|
||
def messages_page(
|
||
self,
|
||
actor: Actor,
|
||
chat_id: str,
|
||
*,
|
||
limit: int | str | None = None,
|
||
cursor: str | None = None,
|
||
) -> httpx.Response:
|
||
return self.request(
|
||
"GET",
|
||
f"{API}/chats/{chat_id}/messages",
|
||
actor=actor,
|
||
params=_page_params(limit, cursor),
|
||
)
|
||
|
||
def chats_page(
|
||
self,
|
||
actor: Actor,
|
||
*,
|
||
limit: int | str | None = None,
|
||
cursor: str | None = None,
|
||
) -> httpx.Response:
|
||
return self.request(
|
||
"GET",
|
||
f"{API}/chats",
|
||
actor=actor,
|
||
params=_page_params(limit, cursor),
|
||
)
|
||
|
||
def message_pages(
|
||
self,
|
||
actor: Actor,
|
||
chat_id: str,
|
||
*,
|
||
limits: Sequence[int] = (100,),
|
||
) -> list[dict[str, Any]]:
|
||
"""Все страницы истории по `next_cursor`.
|
||
|
||
Страница `i` берётся с `limits[i]`, дальше — с последним `limit`.
|
||
"""
|
||
|
||
def fetch(limit: int, cursor: str | None) -> httpx.Response:
|
||
return self.messages_page(
|
||
actor,
|
||
chat_id,
|
||
limit=limit,
|
||
cursor=cursor,
|
||
)
|
||
|
||
return walk_pages(fetch, limits=limits, schema="MessagePage")
|
||
|
||
def chat_pages(
|
||
self,
|
||
actor: Actor,
|
||
*,
|
||
limits: Sequence[int] = (100,),
|
||
) -> list[dict[str, Any]]:
|
||
def fetch(limit: int, cursor: str | None) -> httpx.Response:
|
||
return self.chats_page(actor, limit=limit, cursor=cursor)
|
||
|
||
return walk_pages(fetch, limits=limits, schema="ChatPage")
|
||
|
||
def all_messages(
|
||
self,
|
||
actor: Actor,
|
||
chat_id: str,
|
||
*,
|
||
limits: Sequence[int] = (100,),
|
||
) -> list[dict[str, Any]]:
|
||
pages = self.message_pages(actor, chat_id, limits=limits)
|
||
return [item for page in pages for item in page["items"]]
|
||
|
||
|
||
def walk_pages(
|
||
fetch: Callable[[int, str | None], httpx.Response],
|
||
*,
|
||
limits: Sequence[int],
|
||
schema: str,
|
||
) -> list[dict[str, Any]]:
|
||
"""Обход списка по курсору до `next_cursor` null."""
|
||
pages: list[dict[str, Any]] = []
|
||
cursor: str | None = None
|
||
for number in range(MAX_PAGES):
|
||
limit = limits[min(number, len(limits) - 1)]
|
||
page = assert_ok(fetch(limit, cursor), 200, schema)
|
||
assert len(page["items"]) <= limit, (
|
||
f"page {number} has {len(page['items'])} items, limit {limit}"
|
||
)
|
||
pages.append(page)
|
||
cursor = page["next_cursor"]
|
||
if cursor is None:
|
||
return pages
|
||
raise AssertionError(f"next_cursor is not null after {MAX_PAGES} pages")
|
||
|
||
|
||
def _page_params(
|
||
limit: int | str | None,
|
||
cursor: str | None,
|
||
) -> dict[str, str]:
|
||
params: dict[str, str] = {}
|
||
if limit is not None:
|
||
params["limit"] = str(limit)
|
||
if cursor is not None:
|
||
params["cursor"] = cursor
|
||
return params
|