forked from mtusi2026/mtusi2026lab3
344 lines
10 KiB
TypeScript
344 lines
10 KiB
TypeScript
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<string, Example>;
|
||
responses: Record<string, Record<string, Example>>;
|
||
}
|
||
|
||
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\` с заголовком \`Idempotency-Key\` (любая строка из \`A-Za-z0-9._:-\`, до 128 символов). Повтор с тем же ключом и телом вернёт то же сообщение, с другим телом — 409. Затем \`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<string, OperationExamples> = {
|
||
'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,
|
||
key: example(
|
||
'Нет Idempotency-Key или неверный формат',
|
||
error(
|
||
'invalid_request',
|
||
'Idempotency-Key header must match [A-Za-z0-9._:-]{1,128}',
|
||
),
|
||
),
|
||
},
|
||
'401': UNAUTHORIZED,
|
||
'404': CHAT_NOT_FOUND,
|
||
'409': {
|
||
keyReused: example(
|
||
'Тот же Idempotency-Key с другим телом',
|
||
error(
|
||
'conflict',
|
||
'Idempotency-Key was already used with a different request',
|
||
),
|
||
),
|
||
},
|
||
'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,
|
||
},
|
||
},
|
||
};
|