Stripe пам'ятає ваш запит, коли відповідь зникає

Що охоплює це відео

• Ідемпотентність стосується передбачуваного ефекту повторення операції. Stripe API v1 додає задокументований контракт відтворення збережених відповідей.
• Повторна спроба тієї ж логічної дії використовує той самий ключ і параметри. Зберігайте ключ операції під час окремих викликів SDK або перезапусків програми; справді нова дія потребує власного ключа.
• Після початку виконання кінцевої точки Stripe API v1 зберігає статус і тіло першого запиту, включаючи помилки 500, і повертає цю збережену відповідь під час повторних спроб.
• Змінені параметри з тим же ключем призводять до невідповідності. Помилки перевірки та конфлікти паралельного виконання не зберігають ідемпотентний результат для цієї спроби і можуть бути повторені.
• Stripe зберігає ключі API v1 щонайменше 24 години і може їх видалити після цього. Обмежте невирішені повторні спроби мережі першими 24 годинами, потім зупиніться та узгодьте, перш ніж повторювати операцію.
• Кешована помилка 500 може продовжувати відтворюватися після відновлення зв'язку. Оригінальна операція могла мати побічні ефекти; використовуйте відповідний об'єкт, запит на панелі інструментів та вебхуки, щоб встановити її результат.
• API v2 використовує іншу семантику відтворення. Ключ не встановлює універсальну доставку рівно один раз для електронної пошти, інвентаризації та кожної операції локальної бази даних.

Перекладена стенограма

Перекладено з оригінальної англійської розповіді. Доступне аудіо та субтитри контролюються YouTube.

Таймаут скасував ваш платіж?

0:00 Ви думаєте, що таймаут означає, що ваш платіж не вдався. Сервер може завершити роботу, поки відповідь зникає, залишаючи ваш чек впевнено відображаючи абсолютно нічого. Чому повторна спроба може знову стягнути плату? Як Stripe пам'ятає спробу? Коли варто припинити повторні спроби? І пам'ятайте про одну неприємну деталь. Запам'ятована помилка може пережити проблему з мережею.

0:17 Ми повернемося до цього. Це The Daily Diff, під капотом.

Що ідентифікує ключ ідемпотентності?

0:21 Ідемпотентність означає, що повторення операції має той самий передбачуваний ефект, що й виконання її один раз. Ключ ідемпотентності позначає одну логічну дію. Stripe API версії один розпізнає цей мітку під час повторних спроб і відтворює збережену відповідь. Уявіть, що купуєте каву. Stripe завершує ваш платіжний запит, і відповідь губиться під час повернення додому. Клієнт бачить спінер. Їхній банк може мати більш захоплюючу інтерпретацію. Незахищений запит на створення може повторити побічний ефект.

Як той самий ключ робить повторну спробу безпечною?

0:45 Приєднайте унікальний ключ перед першою спробою і зберігайте його для повторних спроб. Якщо ваша програма перезапускається, зберігайте цей ключ з операцією у ваших записах. Для Stripe API версії один, як тільки починається виконання кінцевої точки, статус і тіло першого запиту зберігаються. Надішліть той самий ключ і параметри знову, і Stripe поверне збережену відповідь. Кава залишається на місці, поки її чек знову подорожує.

Що саме зберігає Stripe?

1:07 Ось фактичне формулювання Stripe. Повторні спроби з тим самим ключем повертають збережену відповідь, включаючи помилки п'ятсот. Документація робить більше роботи, ніж ваш оптимістично названий помічник для повторних спроб. Клієнт знову натискає. Ваша програма вирішує, чи відновлює це відкладену покупку, чи починає іншу одну. Справді нова кава отримує новий ключ. Свіжий ключ для кожної повторної спроби мережі руйнує захист.

1:27 Різні параметри з тим самим ключем викликають невідповідність.

Що відбувається, коли запит змінюється?

1:30 Якщо параметри не проходять перевірку, або інший запит з цим ключем все ще виконується, Stripe не зберігає ідемпотентний результат для цієї спроби. Ці запити можуть бути повторені. Запит, що змагається, отримує конфлікт. Це правила версії один. Версія два поводиться по-іншому. Заголовок не може обіцяти доставку рівно один раз по всій вашій системі. Електронна пошта, інвентаризація та ваша база даних потребують обробки помилок.

1:52 Ключ захищає операцію в межах її задокументованої області. Stripe зберігає ключі версії один щонайменше двадцять чотири години і може їх видалити

Як довго пам'ятається результат, щоб безпечно повторити спробу?

1:59 після цього. Видалений ключ може виконати новий запит. Тримайте невирішені повторні спроби протягом першого дня. Після цього зупиніться і узгодьте початковий результат. Використовуйте експоненційну відстрочку та джиттер, щоб дати серверу перепочити. Інакше повторні спроби утворюють чергу біля палаючої кав'ярні. Бібліотеки Stripe обробляють повторні спроби, але перевіряйте налаштування за замовчуванням вашої бібліотеки. Ця неприємна помилка — це підступ.

Чому пам'ятана помилка може повертатися?

2:20 Кешована відповідь п'ятсот продовжує відтворюватися після відновлення зв'язку. Оригінальна операція могла мати побічні ефекти. Вирішіть її результат, використовуючи об'єкти, панель інструментів та вебхуки. Новий ключ може повторити дію. Якщо ви волієте це читати, ніж чути, як я це кажу, то “diff” надходить до вашої поштової скриньки щоранку, безкоштовно на daily diff dot dev, посилання нижче.

Чи відправлю я кнопку повторної спроби з цим контрактом?

2:39 Вердикт, під капотом. ВІДПРАВИТИ. Я б відправив стабільні ключі з обмеженими повторними спробами та узгодженням, щоб клієнти отримували каву, не фінансуючи вашу освіту в розподілених системах. І це “diff” на сьогодні. Я Ніко з Axrisi. Зливайте відповідально.

Джерела

1. Idempotent requestsStripe Docs
2. Designing robust and predictable APIs with idempotencyStripe Engineering — Brandur Leach
3. Advanced error handlingStripe Docs
4. HTTP Semantics — RFC 9110 §9.2.2 Idempotent MethodsIETF / RFC Editor