const ALICE_ID = '11111111-1111-4111-8111-111111111111'; const BOB_ID = '22222222-2222-4222-8222-222222222222'; const CHAT_ID = '33333333-3333-4333-8333-333333333333'; const MESSAGE_ID = '44444444-4444-4444-8444-444444444444'; const CURSOR = 'eyJjaGF0SWQiOiIzMzMzMzMzMy0zMzMzLTQzMzMtODMzMy0zMzMzMzMzMzMzMzMiLCJpZCI6IjQ0NDQ0NDQ0LTQ0NDQtNDQ0NC04NDQ0LTQ0NDQ0NDQ0NDQ0NCJ9'; const ALICE = { id: ALICE_ID, username: 'alice', display_name: 'Алиса', created_at: '2026-09-01T12:00:00.000Z', }; const CHAT = { id: CHAT_ID, title: 'Проект по ВНП', member_ids: [ALICE_ID, BOB_ID], created_at: '2026-09-01T12:01:00.000Z', }; const MESSAGE = { id: MESSAGE_ID, chat_id: CHAT_ID, sender_id: ALICE_ID, text: 'Привет, Боб! 👋', created_at: '2026-09-01T12:02:00.000Z', }; export interface Example { summary: string; value: unknown; } export interface OperationExamples { request?: Record; responses: Record>; } function example(summary: string, value: unknown): Example { return { summary, value }; } function error(code: string, message: string): unknown { return { error: { code, message, request_id: '9b2c6f1e-5d4a-4c3b-8a2f-1e0d9c8b7a6f', }, }; } const UNAUTHORIZED = { missing: example( 'Нет/неверный/истёкший/отозванный Bearer-токен', error('unauthorized', 'missing or invalid session'), ), }; const UNAVAILABLE = { database: example( 'PostgreSQL недоступен', error('unavailable', 'database unavailable'), ), }; const CHAT_NOT_FOUND = { notFound: example( 'Чата нет или вызывающий не участник (не 403)', error('not_found', 'chat not found'), ), }; const INVALID_CHAT_ID = example( 'chat_id не UUID', error('invalid_request', 'chatId must be a valid UUID'), ); export const GUIDE = ` Учебный мессенджер, лабораторная 3: PostgreSQL, сессии, Redis-кэш сессий. Документ — обязательный контракт \`contracts/openapi.json\`, дополненный примерами запросов и ответов. **Как пройти сценарий в Swagger UI** 1. \`POST /api/v1/users\` — зарегистрируйте пользователей (примеры alice, bob, eve в списке Examples). Повторная регистрация того же username — 409, меняйте username. 2. **Authorize → basicAuth**: username и password из шага 1 → \`POST /api/v1/auth/sessions\` → скопируйте \`token\`. 3. **Authorize → bearerAuth**: вставьте token (без слова Bearer). Basic отправляется только на вход, остальные запросы идут с Bearer. 4. \`GET /api/v1/users/me\` — свой id; id второго участника — из ответа его регистрации. 5. \`POST /api/v1/chats\` с \`member_ids\` = [свой id, id собеседника] → \`chat_id\`. 6. \`POST /api/v1/chats/{chat_id}/messages\`, затем \`GET …/messages?limit=1\` и следующая страница с \`cursor\` = \`next_cursor\`. 7. Чтобы действовать от другого пользователя: Logout в Authorize, вход им и новый token. 8. \`DELETE /api/v1/auth/sessions/current\` — logout; тот же token дальше даёт 401. Сессия живёт \`SESSION_TTL_SECONDS\` (по умолчанию 3600 с). Пароль — 12–128 символов Unicode, двоеточие допустимо. `; export const OPERATION_EXAMPLES: Record = { 'GET /health/live': { responses: { '200': { ok: example('Процесс жив', { status: 'ok' }) }, }, }, 'GET /health/ready': { responses: { '200': { ok: example('PostgreSQL доступен (Redis не критичен)', { status: 'ok', }), }, '503': UNAVAILABLE, }, }, 'POST /api/v1/users': { request: { alice: example('Алиса', { username: 'alice', display_name: 'Алиса', password: 'Alice-password-123', }), bob: example('Боб', { username: 'bob', display_name: 'Боб', password: 'Bob-password-123', }), eve: example('Ева (посторонняя)', { username: 'eve', display_name: 'Ева', password: 'Eve-password-123', }), colon: example('Пароль с двоеточием и эмодзи', { username: 'carol', display_name: 'Кэрол 🌸', password: 'пароль:с:двоеточием🔑', }), }, responses: { '201': { created: example('Пользователь создан', ALICE) }, '400': { username: example( 'username не соответствует [a-z0-9_]{3,32}', error('invalid_request', 'username must match [a-z0-9_]{3,32}'), ), password: example( 'password короче 12 символов', error( 'invalid_request', 'password must be between 12 and 128 Unicode code points', ), ), extra: example( 'Лишнее поле в JSON', error('invalid_request', 'property extra should not exist'), ), }, '409': { taken: example( 'username уже занят', error('conflict', 'username is already taken'), ), }, '503': UNAVAILABLE, }, }, 'POST /api/v1/auth/sessions': { responses: { '201': { created: example('Сессия создана', { token: 'q8Hn3vXl0ZbJ7mWcY2sRkT5uPaE9dFgVhN1oLxI4w6A', token_type: 'Bearer', expires_at: '2026-09-01T13:00:00.000Z', user: ALICE, }), }, '401': { invalid: example( 'Неверный пароль, неизвестный пользователь или нет Basic — ответ одинаковый', error('unauthorized', 'invalid credentials'), ), }, '503': UNAVAILABLE, }, }, 'DELETE /api/v1/auth/sessions/current': { responses: { '401': UNAUTHORIZED, '503': UNAVAILABLE, }, }, 'GET /api/v1/users/me': { responses: { '200': { me: example('Текущий пользователь из сессии', ALICE) }, '401': UNAUTHORIZED, '503': UNAVAILABLE, }, }, 'POST /api/v1/chats': { request: { pair: example('Чат Алисы и Боба', { title: CHAT.title, member_ids: CHAT.member_ids, }), solo: example('Чат только с собой', { title: 'Заметки', member_ids: [ALICE_ID], }), }, responses: { '201': { created: example('Чат создан атомарно', CHAT) }, '400': { noCaller: example( 'Вызывающий не в member_ids', error('invalid_request', 'member_ids must include the caller'), ), unknown: example( 'Неизвестный участник — транзакция откатывается', error('invalid_request', 'member_ids contain an unknown user'), ), duplicate: example( 'Дубликаты в member_ids', error( 'invalid_request', "All member_ids's elements must be unique", ), ), }, '401': UNAUTHORIZED, '503': UNAVAILABLE, }, }, 'GET /api/v1/chats': { responses: { '200': { page: example('Страница чатов с продолжением', { items: [CHAT], next_cursor: 'eyJpZCI6IjMzMzMzMzMzLTMzMzMtNDMzMy04MzMzLTMzMzMzMzMzMzMzMyJ9', }), last: example('Последняя страница', { items: [CHAT], next_cursor: null, }), }, '400': { limit: example( 'limit вне 1–100', error('invalid_request', 'limit must be between 1 and 100'), ), cursor: example( 'Испорченный или чужой cursor', error('invalid_request', 'invalid cursor'), ), }, '401': UNAUTHORIZED, '503': UNAVAILABLE, }, }, 'GET /api/v1/chats/{chat_id}': { responses: { '200': { chat: example('Чат, где вызывающий — участник', CHAT) }, '400': { chatId: INVALID_CHAT_ID }, '401': UNAUTHORIZED, '404': CHAT_NOT_FOUND, '503': UNAVAILABLE, }, }, 'POST /api/v1/chats/{chat_id}/messages': { request: { text: example('Обычное сообщение', { text: MESSAGE.text }), long: example('Максимум — 4000 символов Unicode', { text: 'Длинный текст…', }), }, responses: { '201': { created: example('Отправитель берётся из сессии', MESSAGE), }, '400': { blank: example( 'Пустой или пробельный текст', error( 'invalid_request', 'text must not be empty or whitespace-only', ), ), sender: example( 'sender_id в теле не принимается', error('invalid_request', 'property sender_id should not exist'), ), chatId: INVALID_CHAT_ID, }, '401': UNAUTHORIZED, '404': CHAT_NOT_FOUND, '503': UNAVAILABLE, }, }, 'GET /api/v1/chats/{chat_id}/messages': { responses: { '200': { page: example('Страница истории (limit=1) с cursor', { items: [MESSAGE], next_cursor: CURSOR, }), last: example('Последняя страница', { items: [MESSAGE], next_cursor: null, }), }, '400': { otherChat: example( 'cursor от другого чата', error('invalid_request', 'cursor belongs to a different chat'), ), cursor: example( 'Испорченный cursor или cursor несуществующего сообщения', error('invalid_request', 'invalid cursor'), ), limit: example( 'limit вне 1–100', error('invalid_request', 'limit must be between 1 and 100'), ), }, '401': UNAUTHORIZED, '404': CHAT_NOT_FOUND, '503': UNAVAILABLE, }, }, };