Stripe kommer ihåg din förfrågan när svaret försvinner

Vad den här videon täcker

• Idempotens handlar om den avsedda effekten av att upprepa en operation. Stripe API v1 lägger till ett dokumenterat kontrakt för återuppspelning av sparade svar.
• Ett nytt försök med samma logiska åtgärd använder samma nyckel och parametrar. Behåll operationsnyckeln över separata SDK-anrop eller applikationsomstarter; en genuint ny åtgärd behöver sin egen nyckel.
• Efter att slutpunktskörningen påbörjas sparar Stripe API v1 den första förfrågans status och brödtext, inklusive 500-fel, och returnerar det sparade svaret vid nya försök.
• Ändrade parametrar med samma nyckel ger en avvikelse. Valideringsfel och samtidiga exekveringskonflikter sparar inget idempotent resultat för det försöket och kan göras om.
• Stripe behåller API v1-nycklar i minst 24 timmar och kan därefter gallra dem. Begränsa olösta nätverksförsök till de första 24 timmarna, stoppa sedan och stäm av innan operationen upprepas.
• En cachad 500 kan fortsätta spelas upp efter att anslutningen återställts. Den ursprungliga operationen kan ha bieffekter; använd det relevanta objektet, Dashboard-förfrågan och webhooks för att fastställa dess resultat.
• API v2 använder annan återuppspelningssemantik. En nyckel etablerar inte universell exakt en gång-leverans för e-post, inventering och varje lokal databasoperation.

Översatt transkription

Översatt från den ursprungliga engelska berättelsen. Tillgängligt ljud och undertexter styrs av YouTube.

Avbröt en timeout din betalning?

0:00 Du tror att en timeout innebär att din betalning misslyckades. Servern kan slutföra medan svaret försvinner, och lämnar din kassa med absolut ingenting. Varför kan ett nytt försök debitera igen? Hur kommer Stripe ihåg ett försök? När ska du sluta försöka igen? Och ha en otäck detalj i åtanke. Ett ihågkommet fel kan överleva nätverksproblemet.

0:17 Vi återkommer till det. Detta är The Daily Diff, under huven.

Vad identifierar en idempotensnyckel?

0:21 Idempotens innebär att upprepning av en operation har samma avsedda effekt som att göra det en gång. En idempotensnyckel märker en logisk åtgärd. Stripe's API version ett känner igen den etiketten vid nya försök och spelar upp ett sparat svar. Föreställ dig att köpa en kaffe. Stripe slutför din betalningsförfrågan, och svaret går förlorat på vägen hem. Kunden ser en snurrande ikon. Deras bank kan ha en mer spännande tolkning. En oskyddad skapa-förfrågan kan upprepa bieffekten.

Hur gör samma nyckel ett nytt försök säkert?

0:45 Bifoga en unik nyckel före det första försöket och behåll den för nya försök. Om din applikation startar om, bevara den nyckeln med operationen i dina register. För Stripes version ett API, när slutpunktskörningen påbörjas, sparas den första förfrågans status och brödtext. Skicka samma nyckel och parametrar igen, och Stripe returnerar det sparade svaret. Kaffet står kvar medan kvittot reser igen.

Vad exakt sparar Stripe?

1:07 Här är Stripes faktiska ordalydelse. Nya försök med samma nyckel returnerar det sparade svaret, inklusive fel femhundra. Dokumentationen gör mer arbete än din optimistiskt namngivna återförsökshjälpare. Kunden trycker igen. Din app bestämmer om det återupptar det väntande köpet eller startar ett nytt ett. En genuint ny kaffe får en ny nyckel. En nyckel för varje nätverksförsök upphäver skyddet.

1:27 Olika parametrar med samma nyckel utlöser en avvikelse.

Vad händer när förfrågan ändras?

1:30 Om parametrar misslyckas validering, eller en annan förfrågan med den nyckeln fortfarande utförs, sparar Stripe inget idempotent resultat för det försöket. Dessa förfrågningar kan göras om. En racing-förfrågan får en konflikt. Dessa är version ett regler. Version två beter sig annorlunda. En rubrik kan inte lova exakt en gång-leverans över ditt system. E-post, inventering och din databas behöver alla felhantering.

1:52 Nyckeln skyddar operationen inom dess dokumenterade räckvidd. Stripe behåller version ett nycklar i minst tjugofyra timmar och kan gallra

Hur länge är det ihågkomna resultatet säkert att göra om?

1:59 dem därefter. En gallrad nyckel kan utföra en ny förfrågan. Håll olösta nya försök inom den första dagen. Utöver det, stoppa och stäm av det ursprungliga resultatet. Använd exponentiell backoff och jitter för att ge servern andrum. Annars bildar nya försök en kö utanför ett brinnande kafé. Stripe's bibliotek hanterar nya försök, men kontrollera ditt biblioteks standardinställningar. Det envisa felet är haken.

Varför kan ett ihågkommet fel fortsätta att komma tillbaka?

2:20 Ett cachat femhundra-svar fortsätter att spelas upp efter att anslutningen återställts. Den ursprungliga operationen kan ha producerat bieffekter. Lös dess resultat med hjälp av objekt, Dashboard och webhooks. En ny nyckel kan upprepa åtgärden. Om du hellre vill läsa detta än höra mig säga det, landar diffen i din inkorg varje morgon, gratis på the daily diff dot dev, länk nedan.

Skulle jag skicka en "försök igen"-knapp med detta kontrakt?

2:39 Dom, under huven. SHIP IT. Jag skulle skeppa stabila nycklar med begränsade nya försök och avstämning, så kunderna får kaffe utan att finansiera din utbildning i distribuerade system. Och det var diffen för idag. Jag är Niko från Axrisi. Sammanfoga ansvarsfullt.

Källor

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