Stripe ricorda la tua richiesta quando la risposta scompare

Contenuto di questo video

• L'idempotenza riguarda l'effetto desiderato di ripetere un'operazione. L'API Stripe v1 aggiunge un contratto documentato di riproduzione della risposta salvata.
• Un tentativo della stessa azione logica utilizza la stessa chiave e gli stessi parametri. Persisti la chiave dell'operazione tra chiamate SDK separate o riavvii dell'applicazione; un'azione genuinamente nuova necessita della propria chiave.
• Dopo l'inizio dell'esecuzione dell'endpoint, Stripe API v1 salva lo stato e il corpo della prima richiesta, inclusi gli errori 500, e restituisce tale risposta salvata sui tentativi.
• Parametri modificati con la stessa chiave producono una discrepanza. Errori di validazione e conflitti di esecuzione concorrente non salvano alcun risultato idempotente per quel tentativo e possono essere ritentati.
• Stripe conserva le chiavi API v1 per almeno 24 ore e può eliminarle in seguito. Limita i tentativi di rete irrisolti alle prime 24 ore, quindi ferma e riconcilia prima di ripetere l'operazione.
• Un errore 500 memorizzato nella cache può continuare a riprodursi dopo il ripristino della connettività. L'operazione originale potrebbe avere effetti collaterali; utilizza l'oggetto pertinente, la richiesta della Dashboard e i webhook per stabilirne l'esito.
• L'API v2 utilizza una semantica di riproduzione diversa. Una chiave non stabilisce una consegna esattamente una volta universale per e-mail, inventario e ogni operazione di database locale.

Trascrizione tradotta

Tradotto dalla narrazione originale inglese. L'audio e i sottotitoli disponibili sono controllati da YouTube.

Un timeout ha annullato il tuo pagamento?

0:00 Pensi che un timeout significhi che il tuo pagamento è fallito. Il server può terminare mentre la risposta scompare, lasciando il tuo checkout che mostra con sicurezza assolutamente nulla. Perché un nuovo tentativo può addebitare di nuovo? Come fa Stripe a ricordare un tentativo? Quando dovresti smettere di riprovare? E tieni a mente un brutto dettaglio. Un errore ricordato può sopravvivere al problema di rete.

0:17 Ci torneremo su. Questo è The Daily Diff, sotto il cofano.

Cosa identifica una chiave di idempotenza?

0:21 L'idempotenza significa che ripetere un'operazione ha lo stesso effetto desiderato che farla una volta. Una chiave di idempotenza etichetta un'azione logica. La versione uno dell'API di Stripe riconosce quell'etichetta sui tentativi e riproduce una risposta salvata. Immagina di comprare un caffè. Stripe completa la tua richiesta di pagamento e la risposta si perde nel ritorno a casa. Il cliente vede una rotella di caricamento. La loro banca potrebbe avere un'interpretazione più eccitante. Una richiesta di creazione non protetta può ripetere l'effetto collaterale.

In che modo la stessa chiave rende sicuro un nuovo tentativo?

0:45 Allega una chiave univoca prima del primo tentativo e conservala per i tentativi successivi. Se la tua applicazione si riavvia, conserva quella chiave con l'operazione nei tuoi registri. Per l'API versione uno di Stripe, una volta iniziata l'esecuzione dell'endpoint, lo stato e il corpo della prima richiesta vengono salvati. Invia nuovamente la stessa chiave e gli stessi parametri, e Stripe restituisce la risposta salvata. Il caffè rimane al suo posto mentre la sua ricevuta viaggia di nuovo.

Cosa salva esattamente Stripe?

1:07 Ecco le parole effettive di Stripe. I tentativi con la stessa chiave restituiscono la risposta salvata, inclusi gli errori cinquecento. La documentazione fa più lavoro del tuo aiutante di riprovare dal nome ottimistico. Il cliente tocca di nuovo. La tua app decide se ciò riprende l'acquisto in sospeso o ne avvia un altro. Un caffè genuinamente nuovo ottiene una nuova chiave. Una nuova chiave per ogni tentativo di rete vanifica la protezione.

1:27 Parametri diversi con la stessa chiave attivano una discrepanza.

Cosa succede quando la richiesta cambia?

1:30 Se i parametri falliscono la validazione, o un'altra richiesta con quella chiave è ancora in esecuzione, Stripe non salva alcun risultato idempotente per quel tentativo. Tali richieste possono essere ritentate. Una richiesta in corsa ottiene un conflitto. Queste sono le regole della versione uno. La versione due si comporta in modo diverso. Un'intestazione non può promettere una consegna esattamente una volta in tutto il tuo sistema. E-mail, inventario e il tuo database necessitano ciascuno di gestione degli errori.

1:52 La chiave protegge l'operazione all'interno del suo ambito documentato. Stripe conserva le chiavi della versione uno per almeno ventiquattro ore e può eliminarle

Per quanto tempo il risultato ricordato è sicuro da riprovare?

1:59 successivamente. Una chiave eliminata può eseguire una nuova richiesta. Mantieni i tentativi irrisolti entro il primo giorno. Oltre a ciò, ferma e riconcilia il risultato originale. Usa il backoff esponenziale e il jitter per dare al server respiro. Altrimenti i tentativi formano una coda fuori da una caffetteria in fiamme. Le librerie di Stripe gestiscono i tentativi, ma controlla le impostazioni predefinite della tua libreria. Quell'errore persistente è il problema.

Perché un errore ricordato può continuare a ripresentarsi?

2:20 Una risposta cinquecento memorizzata nella cache continua a riprodursi dopo il ripristino della connettività. L'operazione originale potrebbe aver prodotto effetti collaterali. Risolvi il suo esito utilizzando oggetti, la Dashboard e i webhook. Una nuova chiave può ripetere l'azione. Se preferisci leggere questo anziché sentirmi dire, il diff arriva nella tua casella di posta ogni mattina, gratuitamente su the daily diff dot dev, link sotto.

Inviererei un pulsante di riprova con questo contratto?

2:39 Verdetto, sotto il cofano. Spediscilo. Spedirei chiavi stabili con tentativi limitati e riconciliazione, così i clienti ottengono il caffè senza finanziare la tua educazione ai sistemi distribuiti. E questo è il diff per oggi. Sono Niko di Axrisi. Unisci con responsabilità.

Fonti

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