feat: add idempotency-key

This commit is contained in:
2026-11-01 14:11:53 +03:00
parent b4d1497d1c
commit cdcff89d25
10 changed files with 269 additions and 12 deletions
+1
View File
@@ -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:
@@ -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;
+21 -7
View File
@@ -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")
}
+5
View File
@@ -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();
});
}
+17 -1
View File
@@ -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<string, OperationExamples> = {
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,
},
},
+15 -1
View File
@@ -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<MessageResponse> {
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;
}
+46 -3
View File
@@ -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<Message> {
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(
+11
View File
@@ -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);
+1
View File
@@ -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}` }),
);
+139
View File
@@ -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<void> {
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<number> {
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<string>();
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);
});
});