From cdcff89d2521e528d1244a1191f94eb6fae5a791 Mon Sep 17 00:00:00 2001 From: aegor Date: Sun, 1 Nov 2026 14:11:53 +0300 Subject: [PATCH] feat: add idempotency-key --- compose.yaml | 1 + .../migration.sql | 13 ++ prisma/schema.prisma | 28 +++- src/common/interceptors/request-id.ts | 5 + src/docs/examples.ts | 18 ++- src/messages/messages.controller.ts | 16 +- src/messages/messages.service.ts | 49 +++++- test/api.e2e-spec.ts | 11 ++ test/concurrency.e2e-spec.ts | 1 + test/idempotency.e2e-spec.ts | 139 ++++++++++++++++++ 10 files changed, 269 insertions(+), 12 deletions(-) create mode 100644 prisma/migrations/20261101000000_idempotency_keys/migration.sql create mode 100644 test/idempotency.e2e-spec.ts diff --git a/compose.yaml b/compose.yaml index 90817a8f..0f296350 100644 --- a/compose.yaml +++ b/compose.yaml @@ -77,6 +77,7 @@ services: APP_PORT: 8080 APP_ENV: ${APP_ENV:-lab} SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + IDEMPOTENCY_TTL_SECONDS: ${IDEMPOTENCY_TTL_SECONDS:-86400} DATABASE_URL_FILE: /run/secrets/database_url CACHE_URL_FILE: /run/secrets/cache_url ports: diff --git a/prisma/migrations/20261101000000_idempotency_keys/migration.sql b/prisma/migrations/20261101000000_idempotency_keys/migration.sql new file mode 100644 index 00000000..6d141b13 --- /dev/null +++ b/prisma/migrations/20261101000000_idempotency_keys/migration.sql @@ -0,0 +1,13 @@ +CREATE TABLE "idempotency_keys" ( + "user_id" UUID NOT NULL, + "chat_id" UUID NOT NULL, + "key" VARCHAR(128) NOT NULL, + "request_hash" CHAR(64) NOT NULL, + "message_id" UUID NOT NULL, + "created_at" TIMESTAMPTZ(3) NOT NULL DEFAULT CURRENT_TIMESTAMP, + + CONSTRAINT "idempotency_keys_pkey" PRIMARY KEY ("user_id","chat_id","key"), + CONSTRAINT "idempotency_keys_key_format" CHECK ("key" ~ '^[A-Za-z0-9._:-]{1,128}$') +); + +ALTER TABLE "idempotency_keys" ADD CONSTRAINT "idempotency_keys_message_id_fkey" FOREIGN KEY ("message_id") REFERENCES "messages"("id") ON DELETE CASCADE ON UPDATE CASCADE; diff --git a/prisma/schema.prisma b/prisma/schema.prisma index 85f689f1..84469442 100644 --- a/prisma/schema.prisma +++ b/prisma/schema.prisma @@ -53,14 +53,28 @@ model ChatMember { } model Message { - id String @id @default(uuid()) @db.Uuid - chatId String @map("chat_id") @db.Uuid - senderId String @map("sender_id") @db.Uuid - text String @db.VarChar(4000) - createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3) - chat Chat @relation(fields: [chatId], references: [id], onDelete: Cascade) - sender User @relation(fields: [senderId], references: [id], onDelete: Restrict) + id String @id @default(uuid()) @db.Uuid + chatId String @map("chat_id") @db.Uuid + senderId String @map("sender_id") @db.Uuid + text String @db.VarChar(4000) + createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3) + chat Chat @relation(fields: [chatId], references: [id], onDelete: Cascade) + sender User @relation(fields: [senderId], references: [id], onDelete: Restrict) + idempotencyKeys IdempotencyKey[] @@index([chatId, createdAt, id]) @@map("messages") } + +model IdempotencyKey { + userId String @map("user_id") @db.Uuid + chatId String @map("chat_id") @db.Uuid + key String @db.VarChar(128) + requestHash String @map("request_hash") @db.Char(64) + messageId String @map("message_id") @db.Uuid + createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz(3) + message Message @relation(fields: [messageId], references: [id], onDelete: Cascade) + + @@id([userId, chatId, key]) + @@map("idempotency_keys") +} diff --git a/src/common/interceptors/request-id.ts b/src/common/interceptors/request-id.ts index 188a5117..fc494707 100644 --- a/src/common/interceptors/request-id.ts +++ b/src/common/interceptors/request-id.ts @@ -1,7 +1,11 @@ import { randomUUID } from 'crypto'; import { FastifyInstance, FastifyRequest } from 'fastify'; +import { hostname } from 'os'; const REQUEST_ID_HEADER = 'x-request-id'; +const INSTANCE_ID_HEADER = 'x-instance-id'; + +export const INSTANCE_ID = process.env.INSTANCE_ID ?? hostname(); declare module 'fastify' { interface FastifyRequest { @@ -13,6 +17,7 @@ export function registerRequestId(instance: FastifyInstance): void { instance.addHook('onRequest', (request: FastifyRequest, reply, done) => { request.requestId = randomUUID(); reply.header(REQUEST_ID_HEADER, request.requestId); + reply.header(INSTANCE_ID_HEADER, INSTANCE_ID); done(); }); } diff --git a/src/docs/examples.ts b/src/docs/examples.ts index dc78cd78..5478c5aa 100644 --- a/src/docs/examples.ts +++ b/src/docs/examples.ts @@ -88,7 +88,7 @@ export const GUIDE = ` 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\`. +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. @@ -287,9 +287,25 @@ export const OPERATION_EXAMPLES: Record = { 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, }, }, diff --git a/src/messages/messages.controller.ts b/src/messages/messages.controller.ts index cca9475c..b3a0005e 100644 --- a/src/messages/messages.controller.ts +++ b/src/messages/messages.controller.ts @@ -2,6 +2,7 @@ import { Body, Controller, Get, + Headers, HttpCode, Param, Post, @@ -12,6 +13,7 @@ import { AuthGuard } from '../auth/auth.guard'; import { CurrentUser } from '../auth/current-user.decorator'; import { parseLimit, rawCursorParam } from '../common/dto/pagination-query.dto'; import { User } from '../common/domain'; +import { ApiError } from '../common/filters/api-error'; import { CreateMessageDto } from './dto/create-message.dto'; import { MessagePageResponse, @@ -30,9 +32,11 @@ export class MessagesController { async create( @Param('chatId') chatId: string, @Body() dto: CreateMessageDto, + @Headers('idempotency-key') keyRaw: unknown, @CurrentUser() user: User, ): Promise { - const message = await this.messages.create(chatId, user.id, dto.text); + const key = parseIdempotencyKey(keyRaw); + const message = await this.messages.create(chatId, user.id, dto.text, key); return toMessageResponse(message); } @@ -48,3 +52,13 @@ export class MessagesController { return this.messages.list(chatId, user.id, limit, cursor); } } + +function parseIdempotencyKey(raw: unknown): string { + if (typeof raw !== 'string' || !/^[A-Za-z0-9._:-]{1,128}$/.test(raw)) { + throw new ApiError( + 'invalid_request', + 'Idempotency-Key header must match [A-Za-z0-9._:-]{1,128}', + ); + } + return raw; +} diff --git a/src/messages/messages.service.ts b/src/messages/messages.service.ts index ec269ef1..dfac77e8 100644 --- a/src/messages/messages.service.ts +++ b/src/messages/messages.service.ts @@ -1,5 +1,6 @@ import { Injectable } from '@nestjs/common'; import { Prisma } from '@prisma/client'; +import { createHash } from 'crypto'; import { codePointLength } from '../common/dto/code-point-length.validator'; import { decodeMessageCursor, encodeMessageCursor } from '../common/cursor'; import { Message } from '../common/domain'; @@ -16,14 +17,20 @@ interface MessageRow { createdAt: Date; } +class KeyAlreadyUsed extends Error {} + @Injectable() export class MessagesService { + private readonly keyTtlMs = + Number(process.env.IDEMPOTENCY_TTL_SECONDS ?? 86400) * 1000; + constructor(private readonly prisma: PrismaService) {} async create( chatId: string, callerId: string, text: string, + key: string, ): Promise { await this.assertMember(chatId, callerId); if (codePointLength(text.trim()) === 0) { @@ -32,10 +39,46 @@ export class MessagesService { 'text must not be empty or whitespace-only', ); } - const row = await this.prisma.message.create({ - data: { chatId, senderId: callerId, text }, + const scope = { userId: callerId, chatId, key }; + const requestHash = createHash('sha256') + .update(JSON.stringify({ text })) + .digest('hex'); + try { + return await this.prisma.$transaction(async (tx) => { + await tx.idempotencyKey.deleteMany({ + where: { + ...scope, + createdAt: { lt: new Date(Date.now() - this.keyTtlMs) }, + }, + }); + const row = await tx.message.create({ + data: { chatId, senderId: callerId, text }, + }); + const { count } = await tx.idempotencyKey.createMany({ + data: [{ ...scope, requestHash, messageId: row.id }], + skipDuplicates: true, + }); + if (count === 0) { + throw new KeyAlreadyUsed(); + } + return toMessage(row); + }); + } catch (error) { + if (!(error instanceof KeyAlreadyUsed)) { + throw error; + } + } + const stored = await this.prisma.idempotencyKey.findUnique({ + where: { userId_chatId_key: scope }, + include: { message: true }, }); - return toMessage(row); + if (!stored || stored.requestHash !== requestHash) { + throw new ApiError( + 'conflict', + 'Idempotency-Key was already used with a different request', + ); + } + return toMessage(stored.message); } async list( diff --git a/test/api.e2e-spec.ts b/test/api.e2e-spec.ts index 3cc63878..c8dcfa67 100644 --- a/test/api.e2e-spec.ts +++ b/test/api.e2e-spec.ts @@ -373,6 +373,7 @@ describe('API мессенджера (e2e) — граничные случаи const res = await request(server) .post(`/api/v1/chats/${chat.id}/messages`) + .set('Idempotency-Key', randomUUID()) .set('Authorization', bearer(alice)) .send({ text: 'hi', sender_id: bob.id }) .expect(400); @@ -385,6 +386,7 @@ describe('API мессенджера (e2e) — граничные случаи const chat = await createChat(alice, bob); await request(server) .post(`/api/v1/chats/${chat.id}/messages`) + .set('Idempotency-Key', randomUUID()) .set('Authorization', bearer(alice)) .send({ text: '' }) .expect(400); @@ -396,6 +398,7 @@ describe('API мессенджера (e2e) — граничные случаи const chat = await createChat(alice, bob); await request(server) .post(`/api/v1/chats/${chat.id}/messages`) + .set('Idempotency-Key', randomUUID()) .set('Authorization', bearer(alice)) .send({ text: ' \n\t ' }) .expect(400); @@ -408,6 +411,7 @@ describe('API мессенджера (e2e) — граничные случаи const chat = await createChat(alice, bob); await request(server) .post(`/api/v1/chats/${chat.id}/messages`) + .set('Idempotency-Key', randomUUID()) .set('Authorization', bearer(eve)) .send({ text: 'intrusion' }) .expect(404); @@ -449,6 +453,7 @@ describe('API мессенджера (e2e) — граничные случаи const chat = await createChat(alice, bob); await request(server) .post(`/api/v1/chats/${chat.id}/messages`) + .set('Idempotency-Key', randomUUID()) .set('Authorization', bearer(alice)) .send({ text: 'x'.repeat(4001) }) .expect(400); @@ -460,6 +465,7 @@ describe('API мессенджера (e2e) — граничные случаи const chat = await createChat(alice, bob); await request(server) .post(`/api/v1/chats/${chat.id}/messages`) + .set('Idempotency-Key', randomUUID()) .set('Authorization', bearer(alice)) .send({ text: 'x'.repeat(4000) }) .expect(201); @@ -473,6 +479,7 @@ describe('API мессенджера (e2e) — граничные случаи expect([...text].length).toBe(4001); await request(server) .post(`/api/v1/chats/${chat.id}/messages`) + .set('Idempotency-Key', randomUUID()) .set('Authorization', bearer(alice)) .send({ text }) .expect(400); @@ -495,6 +502,7 @@ describe('API мессенджера (e2e) — граничные случаи const chat = await createChat(alice, bob); await request(server) .post(`/api/v1/chats/${chat.id}/messages`) + .set('Idempotency-Key', randomUUID()) .set('Authorization', bearer(alice)) .send({ text: 'only message' }) .expect(201); @@ -538,11 +546,13 @@ describe('API мессенджера (e2e) — граничные случаи await request(server) .post(`/api/v1/chats/${chatA.id}/messages`) + .set('Idempotency-Key', randomUUID()) .set('Authorization', bearer(alice)) .send({ text: 'first' }) .expect(201); await request(server) .post(`/api/v1/chats/${chatA.id}/messages`) + .set('Idempotency-Key', randomUUID()) .set('Authorization', bearer(alice)) .send({ text: 'second' }) .expect(201); @@ -569,6 +579,7 @@ describe('API мессенджера (e2e) — граничные случаи for (const text of sentTexts) { await request(server) .post(`/api/v1/chats/${chat.id}/messages`) + .set('Idempotency-Key', randomUUID()) .set('Authorization', bearer(alice)) .send({ text }) .expect(201); diff --git a/test/concurrency.e2e-spec.ts b/test/concurrency.e2e-spec.ts index bcbb289d..92fcfbc5 100644 --- a/test/concurrency.e2e-spec.ts +++ b/test/concurrency.e2e-spec.ts @@ -45,6 +45,7 @@ describe('Безопасность при конкурентном доступ sendTasks.push( request(server) .post(`/api/v1/chats/${chat.body.id}/messages`) + .set('Idempotency-Key', randomUUID()) .set('Authorization', bearer(clients[c])) .send({ text: `client-${c}-message-${m}` }), ); diff --git a/test/idempotency.e2e-spec.ts b/test/idempotency.e2e-spec.ts new file mode 100644 index 00000000..a8cecc07 --- /dev/null +++ b/test/idempotency.e2e-spec.ts @@ -0,0 +1,139 @@ +import { INestApplication } from '@nestjs/common'; +import request from 'supertest'; +import { randomUUID } from 'crypto'; +import { PrismaService } from '../src/db/prisma.service'; +import { bearer, createTestApp, registerUser, TestUser } from './helpers'; + +function sleep(ms: number): Promise { + return new Promise((resolve) => setTimeout(resolve, ms)); +} + +describe('Идемпотентность отправки и X-Instance-Id (e2e)', () => { + const apps: INestApplication[] = []; + let server: any; + let replica: any; + let prisma: PrismaService; + + beforeAll(async () => { + const first = await createTestApp(); + const second = await createTestApp(); + apps.push(first.app, second.app); + server = first.server; + replica = second.server; + prisma = first.app.get(PrismaService); + }); + + afterAll(async () => { + await Promise.all(apps.map((app) => app.close())); + }); + + async function setup(label: string) { + const alice = await registerUser(server, label); + const chat = await request(server) + .post('/api/v1/chats') + .set('Authorization', bearer(alice)) + .send({ title: 'Idem', member_ids: [alice.id] }) + .expect(201); + return { alice, path: `/api/v1/chats/${chat.body.id}/messages` }; + } + + function send(target: any, user: TestUser, path: string, key: string | null, body: object) { + const req = request(target).post(path).set('Authorization', bearer(user)); + return (key === null ? req : req.set('Idempotency-Key', key)).send(body); + } + + async function countMessages(path: string, user: TestUser): Promise { + const res = await request(server) + .get(`${path}?limit=100`) + .set('Authorization', bearer(user)) + .expect(200); + return res.body.items.length; + } + + it('требует Idempotency-Key правильного формата', async () => { + const { alice, path } = await setup('keyfmt'); + for (const key of [null, '', 'has space', 'semi;colon', 'slash/key', 'x'.repeat(129)]) { + const res = await send(server, alice, path, key, { text: 'x' }); + expect(res.status).toBe(400); + expect(res.body.error.code).toBe('invalid_request'); + } + await send(server, alice, path, 'A-z_0.9:' + 'k'.repeat(120), { text: 'x' }).expect(201); + }); + + it('повтор с тем же ключом и телом возвращает тот же 201 и то же сообщение', async () => { + const { alice, path } = await setup('replay'); + const key = randomUUID(); + const first = await send(server, alice, path, key, { text: 'Привет 👋' }).expect(201); + const again = await send(replica, alice, path, key, { text: 'Привет 👋' }).expect(201); + expect(again.body).toEqual(first.body); + expect(await countMessages(path, alice)).toBe(1); + }); + + it('тот же ключ с другим телом — 409, сообщение не создаётся', async () => { + const { alice, path } = await setup('conflict'); + const key = randomUUID(); + await send(server, alice, path, key, { text: 'первое' }).expect(201); + const res = await send(server, alice, path, key, { text: 'другое' }).expect(409); + expect(res.body.error.code).toBe('conflict'); + expect(await countMessages(path, alice)).toBe(1); + }); + + it('20 параллельных запросов с одним ключом через два экземпляра создают ровно одно сообщение', async () => { + const { alice, path } = await setup('parallel'); + const key = randomUUID(); + const responses = await Promise.all( + Array.from({ length: 20 }, (_, i) => + send(i % 2 ? replica : server, alice, path, key, { text: 'одно' }), + ), + ); + expect(responses.map((r) => r.status)).toEqual(Array(20).fill(201)); + expect(new Set(responses.map((r) => r.body.id)).size).toBe(1); + expect(await countMessages(path, alice)).toBe(1); + }); + + it('область ключа — пользователь и чат: одинаковый ключ у разных пользователей и чатов независим', async () => { + const a = await setup('scopea'); + const b = await setup('scopeb'); + const key = randomUUID(); + const one = await send(server, a.alice, a.path, key, { text: 'x' }).expect(201); + const two = await send(server, b.alice, b.path, key, { text: 'x' }).expect(201); + expect(one.body.id).not.toBe(two.body.id); + }); + + it('повтор заново проверяет сессию', async () => { + const { alice, path } = await setup('recheck'); + const key = randomUUID(); + await send(server, alice, path, key, { text: 'x' }).expect(201); + await request(server) + .delete('/api/v1/auth/sessions/current') + .set('Authorization', bearer(alice)) + .expect(204); + await send(server, alice, path, key, { text: 'x' }).expect(401); + }); + + it('после IDEMPOTENCY_TTL_SECONDS ключ можно использовать заново', async () => { + const { app, server: short } = await createTestApp({ IDEMPOTENCY_TTL_SECONDS: '1' }); + apps.push(app); + const { alice, path } = await setup('ttl'); + const key = randomUUID(); + const first = await send(short, alice, path, key, { text: 'x' }).expect(201); + await sleep(1500); + const second = await send(short, alice, path, key, { text: 'y' }).expect(201); + expect(second.body.id).not.toBe(first.body.id); + expect(await prisma.idempotencyKey.count({ where: { key } })).toBe(1); + }); + + it('X-Instance-Id есть в успешных ответах, ошибках и health и стабилен в процессе', async () => { + const ids = new Set(); + for (const res of [ + await request(server).get('/health/live').expect(200), + await request(server).get('/health/ready').expect(200), + await request(server).get('/api/v1/users/me').expect(401), + await request(server).post('/api/v1/users').send('{bad').set('Content-Type', 'application/json').expect(400), + ]) { + expect(res.headers['x-instance-id']).toBeTruthy(); + ids.add(res.headers['x-instance-id']); + } + expect(ids.size).toBe(1); + }); +});