Zerwane połączenie może pozostawić Cię w niepewności, czy żądanie wysyłki się powiodło. Utracone potwierdzenie może też spowodować, że nadawca webhooka dostarczy zdarzenie, które Twoja aplikacja już zapisała.
Te awarie zachodzą w przeciwnych kierunkach. Bird może rozpoznać powtórzone żądanie API za pomocą klucza, który podajesz. Twój odbiornik webhooków potrzebuje własnego rejestru zdarzeń, które już przyjął.
Jak bezpiecznie spróbować ponownie wysłać wiadomość?
Przy każdej ponownej próbie używaj tego samego Idempotency-Key i identycznego żądania. Gwarancją jest przyjęcie dokładnie raz: pasujące ponowne próby w ciągu trzech godzin muszą prowadzić do jednej przyjętej operacji, nawet jeśli utracisz jej odpowiedź.
Sam wybierasz klucz o długości do 255 znaków i zachowujesz go między ponownymi próbami. Stabilna wartość taka jak welcome-user/usr_abc123 może identyfikować operację wiadomości powitalnej nawet po restarcie procesu.
Nagłówek dotyczy żądań mutujących, takich jak POST, PATCH i DELETE. Żądanie bez klucza jest przetwarzane bez tej deduplikacji. GET ignoruje nagłówek, ponieważ odczyt zasobu jest bezpieczny do powtórzenia.
Bird zwraca zapisaną odpowiedź dla pasującego ukończonego żądania, łącznie z oryginalnym statusem i ciałem. Odpowiedź zawiera Idempotency-Replay: true, więc możesz zidentyfikować to ponowne użycie w swoich logach.
Przewodnik po idempotentności dokumentuje domyślne trzygodzinne okno dla ukończonych odpowiedzi. Ponowna próba po jego wygaśnięciu może zostać wykonana jako nowa operacja. Nie polegaj na tym kluczu jako trwałej ochronie przed zduplikowanymi wysyłkami.
SDK Bird generują klucz dla mutacji i używają go ponownie w swoich wewnętrznych ponownych próbach. Bird CLI również generuje klucz dla żądania mutującego, gdy jest on nieobecny. Ustaw --idempotency-key jawnie, gdy oddzielne wywołania poleceń muszą współdzielić tę samą operację.
W przypadku przesyłania SMTP użyj nagłówka wiadomości X-Bird-Idempotency-Key. Pozwala to ponowionemu przesłaniu zidentyfikować tę samą operację.
Co się stanie, jeśli użyję klucza nieprawidłowo?
Bird odrzuca kolidujące użycie klucza zamiast zwracać odpowiedź dla innej operacji.
| Sytuacja | Odpowiedź i naprawa |
|---|---|
| Ten sam klucz i żądanie, zachowana odpowiedź | Zapisana odpowiedź w okresie przechowywania, z Idempotency-Replay: true. |
| Ukończony klucz użyty ponownie dla innego żądania | 409 z E01005, oznaczające ponowne użycie klucza idempotentności. Popraw klucz przed ponowną próbą. |
| Inne żądanie z tym kluczem wciąż trwa | 409 z E01004, oznaczające żądanie w toku. Poczekaj chwilę i spróbuj ponownie. |
| Klucz przekracza 255 znaków | 422 z E01001 na endpointach deklarujących ten nagłówek. Skróć klucz. |
Porównanie obejmuje metodę, endpoint, parametry ścieżki, ciąg zapytania i ciało. W przypadku JSON zmiana białych znaków zmienia tożsamość żądania, więc zachowaj oryginalne ciało podczas ponownych prób.
Jeśli oryginalne żądanie wciąż trwa, poczekaj przed ponowną próbą. Zachowaj ten sam klucz i żądanie, aby ponowna próba identyfikowała oryginalną operację.
API nie zachowuje odpowiedzi 5xx jako ukończonej odpowiedzi. Po przekroczeniu limitu czasu lub błędzie serwera ponów żądanie z ograniczonym backoffem, tym samym kluczem i identycznym żądaniem w ciągu trzech godzin. Gwarancja przyjęcia dokładnie raz obejmuje również utraconą odpowiedź.
Odrzucenie 4xx może zostać zachowane. Dla poprawionego żądania użyj nowego klucza: niezmieniona ponowna próba odtwarza zachowane odrzucenie, a zmienione dane wejściowe kolidują z zachowanym kluczem.
Dlaczego dostaję ten sam webhook dwa razy?
Jeśli Bird nie otrzyma pomyślnej odpowiedzi, może spróbować ponownie dostarczyć zdarzenie, które Twój odbiornik już zapisał.
Odbiornik może zapisać zdarzenie tuż przed zerwaniem połączenia. Bird nie widzi pomyślnego potwierdzenia i próbuje ponownie, mimo że odbiornik już ma to zdarzenie.
Każda ponowna próba zachowuje ten sam nagłówek webhook-id, który identyfikuje zdarzenie. Odtworzenie nieudanego dostarczenia również zachowuje ten identyfikator, więc oba można rozpoznać jako to samo zdarzenie.
Jak uczynić mój handler idempotentnym?
Zapisuj każdy webhook-id z unikalnym ograniczeniem bazodanowym przed zaplanowaniem pracy dla zdarzenia.
Sprawdzanie istniejącego wiersza przed wstawieniem pozostawia wyścig: dwa równoczesne żądania mogą nie zobaczyć żadnego wiersza. Pozwól bazie danych odrzucić zduplikowane identyfikatory.
Zapisz identyfikator i zadanie w tej samej transakcji. Zapobiega to zarejestrowaniu identyfikatora bez zakolejkowania żadnej pracy.
- Zweryfikuj żądanie, a następnie wstaw jego identyfikator i zadanie w tej samej transakcji.
- Zwróć
2xxpo zatwierdzeniu transakcji, aby Bird mógł przestać ponawiać. - Przetwarzaj zapisane zadanie w workerze, który może bezpiecznie powtarzać własne akcje.
Jeśli zduplikowany identyfikator jest już zatwierdzony, zwróć sukces bez tworzenia kolejnego zadania. W przypadku nieudanej transakcji zwróć błąd, aby Bird ponowił próbę.
Nie umieszczaj wolnej pracy w odbiorniku, ponieważ oczekiwanie na nią może spowodować przekroczenie limitu czasu żądania. Worker może podejmować ponowne próby z przyczyn niezwiązanych z dostarczaniem webhooków, więc ochrona samego odbiornika nie wystarcza.
Zdarzenia mogą też przychodzić w niewłaściwej kolejności. Porównuj czasy zdarzeń w timestamp przed nadpisaniem nowszego stanu. Ponowienia nieudanych webhooków zawierają przykład częściowego kosztu.
Na czym nie powinno się polegać?
Nie zakładaj, że deduplikacja żądań uniemożliwia zduplikowane efekty uboczne.
W przypadku obsługiwanego zapisu HTTP Bird wiąże klucz idempotentności z obszarem roboczym lub organizacją żądania. Obsługiwane operacje personelu używają zamiast tego konta działającego pracownika. Jeśli ochrona jest niedostępna, Bird zwraca 503 E01033 IdempotencyUnavailable przed wykonaniem tej próby. Nie rozstrzyga to wyniku wcześniejszej próby. Gwarancja przyjęcia dokładnie raz obejmuje pasujące ponowne próby w ciągu trzech godzin. Aby potwierdzić dostarczenie, sprawdź status wiadomości. Jeśli ponowne próby się wyczerpią lub okno wygaśnie, sprawdź wynik oryginalnej operacji, zanim wyślesz żądanie ponownie.
Podobnie webhook-id rozróżnia powtórzone dostarczenia jednego zdarzenia. Oddzielne zdarzenia mają oddzielne identyfikatory. Twoja aplikacja nadal decyduje, czy te zdarzenia uzasadniają powtórzenie tej samej akcji.
Idempotentność opisuje działanie ponownych prób w API. Webhooki opisują oddzielne gwarancje dostarczenia, które obsługuje Twój odbiornik.
W skrócie
Ponowne próby żądań do API i ponowne próby webhooków wymagają różnych rekordów.
Używaj ponownie Idempotency-Key w żądaniach do Bird. Twój odbiornik zapisuje webhook-id, aby rozpoznać zdarzenie, które już przyjął.
Odrzucenia również mogą zostać zachowane.
Zachowane odrzucenie jest odtwarzane. Poprawione żądanie wymaga nowego klucza, ponieważ jego dane wejściowe się różnią.
Ukończony klucz nie może identyfikować innych żądań.
Zmienione ciało żądania lub endpoint JSON może spowodować konflikt 409. Popraw klucz zamiast ponawiać ten konflikt bez zmian.
Deduplikacja ma ograniczenia.
Gwarancja API obejmuje przyjęcie dokładnie raz pasujących ponownych prób w ciągu trzech godzin. Twój odbiornik webhooków potrzebuje własnych trwałych rekordów zdarzeń.