Повторение на POST заявка: кога е безопасно?
Безопасно ли е повторението на POST след timeout? Неизвестен резултат, идемпотентност и границите на ключовете в Stripe API v1.
Хипотетично приложение за бележки изпраща POST заявка за нова бележка. Времето за изчакване изтича, без да пристигне отговор. Да изпрати ли същата заявка отново? За да решим, първо трябва да разграничим два въпроса: получен ли е отговор и създадена ли е бележката.
Отговорът липсва, резултатът е неизвестен
Нека проследим един възможен сценарий. Клиентът изпраща заявката. Сървърът я обработва и потвърждава записа в базата. Отговорът се губи по пътя обратно. Клиентът отчита timeout. В този пример бележката вече съществува. Ако всяко получаване на POST създава нова бележка, повторението ще създаде втора.
AWS изрично предупреждава: timeout не доказва, че страничните ефекти не са настъпили. Следователно „не получих отговор“ не означава „операцията не е изпълнена“. Това е разликата между неизвестен резултат и потвърден неуспех. (builder.aws.com)
Какво означава идемпотентност
Според RFC 9110, раздел 9.2.2, идемпотентността означава еднакъв предвиден ефект върху сървъра при еднократно и многократно изпращане, не еднакви отговори. Автоматичното повторение на неидемпотентни заявки не се препоръчва без известна идемпотентна семантика или доказателство, че първата не е приложена. (rfc-editor.org)
В Amazon Builders’ Library Малкълм Фийтънби описва идентификатор, подаден от клиента, за разпознаване на повторенията. Еднаквите параметри сами не изразяват намерението: клиентът може действително да иска два еднакви обекта. Ключът има смисъл чрез договореното поведение на сървъра, не просто защото присъства в заявката. (aws.amazon.com)
Конкретният договор на Stripe API v1
Stripe API v1 връща запазените статус и тяло, включително грешки 500. Запазването изисква започнало изпълнение: неуспешна валидация и конфликт с едновременно изпълнявана заявка не запазват резултат. Променени параметри със същия ключ водят до грешка. API v2 има различна семантика на повторението. (docs.stripe.com)
Изпрати Idempotency-Key още при първия опит. Stripe указва повторения със същите ключ и параметри през първите 24 часа. След това ключът може да бъде премахнат; повторното му използване тогава може да започне нова заявка. Ако резултатът остава неизвестен, спри повторенията и изясни какво е станало. (docs.stripe.com)
Кога да повториш е отделен въпрос
AWS препоръчва ограничен брой повторения и нарастващи паузи с горна граница, за да контролира натоварването. Инженерният извод е отделен: по-дългата пауза не установява дали повторението е коректно. (builder.aws.com)
В обяснението си за jitter Марк Брукър показва защо еднаквите паузи могат да оставят заявките групирани във времето. Случайната компонента ги разпределя. Това променя момента на изпращане, не начина, по който сървърът разпознава една операция. (aws.amazon.com)
Какво да изясниш преди автоматичните повторения
Като упражнение върху хартия върни примера с бележката. Постави прекъсване преди обработката, след записа и преди получаването на отговора. За всеки случай запиши какво знае клиентът, какво остава неизвестно и кой текст от договора на API оправдава следващото действие. Не попълвай неизвестното с предположение.
После добави два въпроса към прегледа на интеграцията: „Как ще установим резултата, когато повторенията спрат?“ и „Каква точно гаранция дава този endpoint, в тази версия, за тази операция?“
Източници
- RFC 9110: HTTP Semantics, section 9.2.2, Idempotent Methods: https://www.rfc-editor.org/rfc/rfc9110.html
- AWS: Timeouts, retries, and backoff with jitter: https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter
- Stripe API: Idempotent requests: https://docs.stripe.com/api/idempotent_requests
- Stripe: Advanced error handling: https://docs.stripe.com/error-low-level
- Amazon Builders’ Library: Making retries safe with idempotent APIs: https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/
- AWS Architecture Blog: Exponential Backoff And Jitter: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/