Ідемпотентність запитів · fullstack.org.ua

Просунутий20 хв· Fullstack Team

Ідемпотентність запитів

Розберете ідемпотентність HTTP-операцій і реалізуєте безпечне повторення запитів та захист від дублювання операцій.

Що таке ідемпотентність

Операція є ідемпотентною, якщо її повторне виконання приводить систему до того самого стану, що й одне виконання.

Формально для операції f:

text

f(f(state)) = f(state)

Це не означає, що повторні HTTP-відповіді обов’язково будуть однаковими. Наприклад, другий GET може повернути нове представлення ресурсу. Ідемпотентність стосується передусім побічного ефекту операції.

Приклади:

встановити статус замовлення в paid — ідемпотентно;
збільшити баланс на 100 гривень — неілемпотентно;
створити платіж — зазвичай неілемпотентно без додаткового механізму;

javascript

'use strict';

const http = require('node:http');
const crypto = require('node:crypto');

const PORT = 3000;

// У production ці дані повинні зберігатися в надійному сховищі.
const idempotencyRecords = new Map();
const payments = new Map();

function sendJson(response, statusCode, body, headers = {}) {
  const payload = JSON.stringify(body);

  response.writeHead(statusCode, {
    'Content-Type': 'application/json; charset=utf-8',
    'Content-Length': Buffer.byteLength(payload),
    ...headers
  });

  response.end(payload);
}

function readRequestBody(request) {
  return new Promise((resolve, reject) => {
    const chunks = [];
    let size = 0;
    const maxSize = 1024 * 1024;

    request.on('data', (chunk) => {
      size += chunk.length;

      if (size > maxSize) {
        reject(new Error('Тіло запиту завелике'));
        request.destroy();
        return;
      }

      chunks.push(chunk);
    });

    request.on('end', () => {
      resolve(Buffer.concat(chunks).toString('utf8'));
    });

    request.on('error', reject);
  });
}

function fingerprint(body) {
  return crypto
    .createHash('sha256')
    .update(body)
    .digest('hex');
}

function validatePayment(payment) {
  if (
    !payment ||
    !Number.isInteger(payment.amount) ||
    payment.amount <= 0 ||
    typeof payment.currency !== 'string' ||
    payment.currency.length !== 3
  ) {
    return false;
  }

  return true;
}

function delay(milliseconds) {
  return new Promise((resolve) => {
    setTimeout(resolve, milliseconds);
  });
}

async function executePayment(payment) {
  // Імітуємо звернення до платіжного провайдера.
  await delay(500);

  const paymentId = crypto.randomUUID();

  const result = {
    id: paymentId,
    amount: payment.amount,
    currency: payment.currency,
    status: 'created'
  };

  payments.set(paymentId, result);

  return {
    statusCode: 201,
    body: result
  };
}

async function handleCreatePayment(request, response) {
  const key = request.headers['idempotency-key'];

  if (typeof key !== 'string' || key.length < 16 || key.length > 255) {
    sendJson(response, 400, {
      error: 'Заголовок Idempotency-Key є обов’язковим'
    });
    return;
  }

  const rawBody = await readRequestBody(request);

  let payment;

  try {
    payment = JSON.parse(rawBody);
  } catch {
    sendJson(response, 400, {
      error: 'Тіло запиту має бути коректним JSON'
    });
    return;
  }

  if (!validatePayment(payment)) {
    sendJson(response, 422, {
      error: 'Некоректні дані платежу'
    });
    return;
  }

  const requestFingerprint = fingerprint(rawBody);
  const existingRecord = idempotencyRecords.get(key);

  if (existingRecord) {
    if (existingRecord.fingerprint !== requestFingerprint) {
      sendJson(response, 409, {
        error: 'Idempotency-Key уже використано з іншим запитом'
      });
      return;
    }

    try {
      const savedResult = await existingRecord.resultPromise;

      sendJson(
        response,
        savedResult.statusCode,
        savedResult.body,
        {
          'Idempotency-Replayed': 'true'
        }
      );
    } catch {
      sendJson(response, 500, {
        error: 'Не вдалося завершити ідемпотентну операцію'
      });
    }

    return;
  }

  // Promise реєструється до початку асинхронної роботи.
  // Тому паралельний запит побачить уже наявну операцію.
  const resultPromise = executePayment(payment);

  idempotencyRecords.set(key, {
    fingerprint: requestFingerprint,
    resultPromise
  });

  try {
    const result = await resultPromise;

    sendJson(response, result.statusCode, result.body, {
      'Idempotency-Replayed': 'false'
    });
  } catch (error) {
    // Видаляємо запис лише для невдалої операції.
    // У production-проєкті це рішення залежить від гарантій
    // зовнішньої платіжної системи.
    idempotencyRecords.delete(key);

    sendJson(response, 500, {
      error: 'Помилка під час створення платежу'
    });
  }
}

const server = http.createServer(async (request, response) => {
  if (request.method === 'POST' && request.url === '/payments') {
    try {
      await handleCreatePayment(request, response);
    } catch {
      sendJson(response, 500, {
        error: 'Внутрішня помилка сервера'
      });
    }

    return;
  }

  sendJson(response, 404, {
    error: 'Маршрут не знайдено'
  });
});

server.listen(PORT, () => {
  console.log(`Сервер слухає http://localhost:${PORT}`);
});

javascript

const idempotencyKey = crypto.randomUUID();

for (let attempt = 0; attempt < 3; attempt += 1) {
  try {
    const response = await sendPayment({
      idempotencyKey,
      amount: 1000,
      currency: 'UAH'
    });

    if (response.ok) {
      return response;
    }

    if (response.status === 409) {
      throw new Error('Конфлікт ідемпотентного ключа');
    }

    if (response.status >= 400 && response.status < 500) {
      throw new Error('Помилка в даних запиту');
    }
  } catch (error) {
    if (attempt === 2) {
      throw error;
    }

    await waitWithBackoff(attempt);
  }
}

Ідемпотентність запитів

Що таке ідемпотентність

Ідемпотентність HTTP-методів

`PUT` як ідемпотентна операція

`POST` і повторне створення

Чому повторення запитів взагалі потрібне

Ідемпотентний ключ

Відбиток запиту

Реалізація на Node.js

Конкурентні повтори

Що саме потрібно зберігати

Життєвий цикл запису

Повторення запитів на клієнті

Чи можна повторювати помилки

Межі ідемпотентності

Зберігання та термін дії ключів

Безпека ідемпотентних ключів

Типові помилки

Генерувати новий ключ під час кожного повтору

Ігнорувати відмінність тіл запитів

Записувати ключ після виконання операції

Зберігати лише ідентифікатор ресурсу

Видаляти запис одразу після відповіді

Вважати `500` доказом невиконання

Покладатися на пам'ять одного процесу

Підсумок

Ідемпотентність запитів

Що таке ідемпотентність

Ідемпотентність HTTP-методів

PUT як ідемпотентна операція

POST і повторне створення

Чому повторення запитів взагалі потрібне

Ідемпотентний ключ

Відбиток запиту

Реалізація на Node.js

Конкурентні повтори

Що саме потрібно зберігати

Життєвий цикл запису

Повторення запитів на клієнті

Чи можна повторювати помилки

Межі ідемпотентності

Зберігання та термін дії ключів

Безпека ідемпотентних ключів

Типові помилки

Генерувати новий ключ під час кожного повтору

Ігнорувати відмінність тіл запитів

Записувати ключ після виконання операції

Зберігати лише ідентифікатор ресурсу

Видаляти запис одразу після відповіді

Вважати 500 доказом невиконання

Покладатися на пам'ять одного процесу

Підсумок

`PUT` як ідемпотентна операція

`POST` і повторне створення

Вважати `500` доказом невиконання