Bir şey mi arıyorsunuz?

Bir konu, bir kelime, aklınızda kalan bir cümle.

Yazılara dön

Laravel’de tekrar deneme: idempotency ve outbox

Yanıtı gelmeyen bir isteği yeniden göndermeden önce neyi bilmeliyiz? Laravel’de idempotency, outbox ve worker sahipliğini bir sipariş aktarımı üzerinden ele alıyorum.

Mesajın tekrar denenmesini ve teslim kaydının korunmasını anlatan soyut outbox illüstrasyonu

Sipariş dış servise gönderildi, fakat yanıt gelmeden bağlantı koptu. Kuyruktaki iş yeniden çalışınca ne yapacak? İlk çağrı karşı tarafta tamamlandıysa aynı POST ikinci bir sipariş oluşturabilir. Hiç tamamlanmadıysa ve yeniden gönderilmezse bu kez aktarım yarım kalır. Tekrar deneme tasarımının en zor kısmı, bu iki durumu birbirinden ayırmaktır.

Laravel ve MySQL kullanan örnek bir sipariş aktarımı üzerinden ilerleyelim. Aşağıdaki zaman çizelgesi ve kodlar bu örnek için hazırlanmıştır. Kodlarda yetkilendirme, hata ayrıştırma ve migration gibi ayrıntılar tamamlanmış değil; amaç, işlemleri hangi sırayla ve hangi sınırlar içinde yürüttüğümüzü göstermek.

Yanıt yoksa sonuç da bilinmiyor olabilir

  1. 10:00:00: Uygulama sipariş değişikliğini ve aktarım niyetini aynı veritabanı transaction’ında kaydeder. İstemciye işlem kimliğiyle 202 Accepted döner.
  2. 10:00:02: Worker, event_id=E17 kaydını sahiplenir ve dış servise gönderir.
  3. 10:00:03: Dış servis siparişi R948 kimliğiyle oluşturur.
  4. 10:00:12: Yanıt ulaşmadığı için worker zaman aşımı alır. Yerel kayıtta dış sipariş kimliği yoktur.
  5. 10:00:40: Yeniden deneme başlar. Yeni bir idempotency anahtarı üretilirse dış servis bunu yeni işlem sayabilir.

Bu durumda failed yazmak, elimizde olmayan bir bilgiyi kesinleştirir. Bildiğimiz şey yanıtı alamadığımızdır; bu yüzden yerel durum outcome_unknown olmalı. Dış servis aynı anahtarla gelen isteğe aynı sonucu döndürmeyi garanti ediyorsa E17 yeniden kullanılabilir. Böyle bir garanti yoksa önce durum sorgulanmalı veya kayıtlar karşılaştırılarak sonuç netleştirilmeli.

“Kayıt bulunamadı” yanıtı bile her zaman yeniden gönderme izni sayılmaz. Sorgu yeni oluşturulan kaydı henüz göremiyor olabilir. Sağlayıcının tutarlılık ve sorgulama davranışını bilmeden bu cevaptan işlemin hiç gerçekleşmediği sonucunu çıkaramayız.

Aynı isteği tanımak

İstemciden gelen idempotency anahtarı, çift tıklamayı ve aynı isteğin ağ hatası yüzünden tekrarlanmasını karşılar. Dış servise giden olay kimliğinin işi ise farklıdır. Bu iki kimliği tesadüfen aynı değeri taşıdıkları için birbirine bağlamak yerine, aralarındaki ilişkiyi veritabanında tutmak daha açık bir tasarımdır.

-- MySQL / InnoDB şema iskeletindeki kısıtlar:
-- tenant_id, operation, idempotency_key: NOT NULL
-- operation: VARBINARY(64), idempotency_key: VARBINARY(128)
-- request_hash: BINARY(32), response_body: JSON
CREATE UNIQUE INDEX uq_replay
ON integration_requests(tenant_id, operation, idempotency_key);

CREATE UNIQUE INDEX uq_outbox_event
ON outbox_events(event_id);

CREATE INDEX ix_outbox_ready
ON outbox_events(status, available_at, id);

tenant_id doğrulanmış oturumdan alınır; istek gövdesine güvenilmez. İşlem adı order.export:v1 gibi sürümlenebilir. Anahtarda büyük ve küçük harfin farklı sayılıp sayılmayacağı da açıkça belirlenmeli, veritabanının varsayılan collation ayarına bırakılmamalı. “Önce SELECT, yoksa INSERT” kontrolü tek başına yetmez: iki istek aynı anda boş sonuç görebilir. Tekilliği veritabanındaki unique constraint korumalı.

Aynı anahtar bu kez farklı miktar, para birimi veya hedef hesapla geldiyse eski yanıtı döndürmek hatayı gizler. Bu nedenle doğrulanmış iş girdisinden deterministik bir parmak izi üretilir. Nesne anahtarları sıralanabilir; anlam taşıyan dizi sırası ise korunur. Parasal değerler float yerine birimi açık, kesin bir gösterimle hesaba katılır. Parmak izi değişmişse bu örnekteki API 409 Conflict döndürür. AWS’nin idempotent API incelemesi de aynı istek kimliğiyle farklı parametre gönderilmesini ayrıca ele alıyor.

Sipariş, kayıtlı yanıt ve outbox birlikte yazılmalı

// Sentetik yardımcılar; tamamlanmış uygulama kodu değildir.
$scope = [$authorizedTenantId, 'order.export:v1', $clientKey];
$hash = hash('sha256', canonicalJson($validatedPayload), true);

try {
    $reply = DB::transaction(function () use ($scope, $hash, $validatedPayload) {
        $request = reserveRequest($scope, $hash); // INSERT; uq_replay
        $order = applyAuthorizedOrderChange($scope[0], $validatedPayload);
        $event = appendOutbox($scope[0], $order, immutablePayload($order));
        $reply = acceptedResponse($event->id); // 202 + operation_id
        storeReplayResponse($request, $reply);
        return $reply;
    }, attempts: 3);
} catch (QueryException $e) {
    if (!isDuplicateOf($e, 'uq_replay')) {
        throw $e;
    }
    $previous = readReplayFromPrimary($scope); // Rollback sonrasında.
    authorizeReplay($previous);
    rejectFingerprintMismatch($previous, $hash); // 409
    $reply = storedResponse($previous);
}

Örnekteki yardımcı fonksiyonların tümü aynı veritabanı bağlantısını ve transaction’ı kullanmalı. Hata yakalarken de her 23000 kodunu “bu istek daha önce işlendi” diye yorumlayamayız. Hangi constraint’in ihlal edildiği ayrıştırılmalı; burada aranan uq_replay. İlk istek commit ettikten sonra onun sakladığı yanıt okunur. Lock timeout veya başka bir bütünlük hatası, önceki isteğin başarıyla tamamlandığını göstermez.

202 yanıtı aktarım isteğinin kabul edildiğini söyler. Dış sistemde siparişin oluşup oluşmadığı ayrı işlem kaydından takip edilir. Kayıtlı yanıtı döndürürken yetki de yeniden denetlenir; anahtarı bilen herkes o sonuca erişemez.

Anahtarların ne kadar saklanacağı API’nin davranışını doğrudan etkiler. Kayıt erken silinirse gecikmiş bir tekrar yeni işlem sayılabilir. Dış servisin saklama süresi de önemlidir: sağlayıcı anahtarı unuttuktan sonra eski olayı göndermek, yerel kayıt hâlâ duruyor olsa bile ikinci siparişe yol açabilir. Otomatik denemeler bu süre içinde kalmalı; süre aşılmışsa önce işlemin sonucu netleştirilmeli.

Laravel, deadlock durumunda transaction’ı yeniden deneyebilir; callback de tekrar çalışır. Bu nedenle callback’in içine dış HTTP çağrısı, e-posta gönderimi veya geri alınamayan başka bir işlem konmamalı. Yerel rollback, karşı tarafta oluşturulmuş siparişi geri alamaz.

afterCommit neden tek başına yetmiyor?

afterCommit, işin veritabanı commit edilmeden gönderilmesini önler. Fakat commit tamamlandıktan sonra, kuyruğa gönderim yapılmadan süreç kapanabilir. Bellekte bekleyen callback bu durumda kaybolur. Kalıcı bir gönderim kaydı bulunmadıkça sıradaki taramanın bulacağı bir şey de olmaz.

Outbox kullanıldığında siparişle gönderilecek olay aynı transaction içinde saklanır. Bekleyen kayıtları tarayan poller, süreç yeniden başladığında da olayı bulabilir. afterCommit() poller’ı erkenden uyandırmak için kullanılabilir; aktarımın devam etmesi yalnız bu uyandırmaya bağlı kalmaz. Transactional outbox deseni, veritabanı kaydıyla dış sisteme bildirim arasındaki bu sorunu ele alır. Aynı olayın birden fazla kez teslim edilmesini ise tek başına önlemez.

Seçim Ne sağlar? Bedeli
Commit sonrası doğrudan dispatch Worker’ın commit öncesi kaydı okumasını engeller. Commit–dispatch arasındaki süreç kaybı için ayrı kurtarma gerekir.
Aynı transaction’da outbox + poller İş kaydıyla gönderilecek olayın birlikte kaydedilmesini sağlar. Tarama, gecikme, lease ve tablo temizliği yönetilir.
Outbox + karşı tarafta idempotency Yinelenen teslimatın iş etkisini sınırlayabilir. Karşı tarafın anahtar kapsamı ve saklama sözleşmesine bağlıdır.

Outbox gövdesi, olay oluştuğu andaki iş verisini taşımalı. Worker her denemede güncel siparişi okuyup yeni gövde üretirse aynı event_id farklı içerikle gönderilebilir. Tutar, adres veya miktar sonradan değiştiğinde yeni bir sürüm ve olay oluşturmak gerekir. İlk aktarımı yeniden denemekle sonraki değişikliği göndermek böyle ayrılır. Bağlantı sırları bu kayda eklenmez; gönderim sırasında güvenli yapılandırmadan alınır.

HTTP çağrısı boyunca satır kilidini tutmamak

Worker, gönderilecek kaydı kısa bir transaction içinde süreli olarak sahiplenebilir. Bu sahipliğin kimliği ve süresi, yani lease bilgisi, işlem bittikten sonra sonucu hangi worker’ın yazabileceğini belirler.

START TRANSACTION;
SELECT id FROM outbox_events
WHERE status = 'pending' AND available_at <= NOW(6)
ORDER BY id LIMIT 1 FOR UPDATE SKIP LOCKED;

UPDATE outbox_events
SET status = 'sending', lease_token = :token,
    lease_until = DATE_ADD(NOW(6), INTERVAL 60 SECOND),
    attempts = attempts + 1
WHERE id = :selected_id;
COMMIT;
-- HTTP çağrısı transaction DIŞINDA.

UPDATE outbox_events
SET status = 'delivered', remote_id = :remote_id
WHERE id = :selected_id AND status = 'sending'
  AND lease_token = :token AND lease_until > NOW(6);

Bu örnekte satır bulunmazsa UPDATE çalıştırılmaz; süreler de yalnız örnek değerlerdir. MySQL’in SKIP LOCKED seçeneği, başka worker’ın kilitlediği satırı beklemeden atlar. Kuyruk benzeri tablolar için yararlıdır, fakat işlerin doğru sırayla gönderileceğini garanti etmez. Aynı siparişin olaylarında sıra önemliyse sipariş kimliği ve sıra numarası üzerinden, önceki olay tamamlanmadan sonrakinin gönderilmesi ayrıca engellenmeli.

Lease süresi dolan worker’ın geç gelen yanıtı, kaydı daha sonra sahiplenen worker’ın sonucunu ezmemeli. Son UPDATE’in etkilediği satır sayısına bu yüzden bakılır. Süresi dolmuş sending kaydı da doğrudan yeniden gönderilmez; önce sonucu bilinmeyen işlem olarak ele alınır. Lease’in bitmesi, dış serviste devam eden çağrıyı durdurmaz.

Bu tasarımda teslimat tekrarlanabilir: at-least-once akışın karşı tarafında aynı işin iki kez oluşmasını önlemeye çalışıyoruz. Uçtan uca exactly-once garantisi vermiyoruz.

Her hata aynı şekilde tekrar edilmez

Laravel HTTP istemcisi zaman aşımında ConnectionException üretir. Ancak varsayılan davranışta 4xx/5xx yanıtları exception oluşturmaz. Yalnız catch bloğu yazmak yeterli değildir; yanıtın durum kodu da kontrol edilmelidir. Alan doğrulama hatası verinin düzeltilmesini bekler. 429 için sağlayıcının bekleme talimatı dikkate alınır. 5xx veya zaman aşımı ise yazma işleminin hiç gerçekleşmediğini kanıtlamaz.

Yeniden denemenin güvenli olduğu biliniyorsa deneme sayısı sınırlanabilir, bekleme süresi artırılabilir ve aynı anda yığılmayı azaltmak için jitter eklenebilir. Amazon’un retry incelemesinde anlatılan sorun burada da geçerli: HTTP istemcisi üç, kuyruk beş kez denerse tek iş on beş çağrıya çıkabilir. Tekrar denemeleri bir katmanda yönetmek, toplam sayıyı izlemeyi kolaylaştırır. Sınır dolduğunda yeni çağrılar üretmek yerine mevcut işlemin sonucu araştırılır.

Poller Laravel queue üzerinde çalışıyorsa HTTP zaman aşımı, worker’ın çalışma süresi ve kuyruğun işi yeniden kullanılabilir hâle getirdiği süre birlikte ayarlanmalı. Laravel belgeleri, worker timeout’unun retry_after değerinden birkaç saniye kısa tutulmasını öneriyor. Lease de normal çalışma bitmeden başka worker’ın aynı kaydı almasına yol açmamalı. Bu süreleri uyumlu seçmek tekrarları azaltır; idempotency kontrolünün yerini tutmaz.

İzlenecek tek gösterge başarısız job sayısı değil. En eski bekleyen outbox kaydının yaşı, sonucu bilinmeyen işlemler ve lease’i kaybettiği için reddedilen güncellemeler de takip edilmeli. Kuyruk boş görünürken poller durmuş olabilir. Alarmın hangi tenant ve işleme ait olduğunu görebilmek, yeni bir gönderim başlatmadan sorunu araştırmayı sağlar.

Testte hangi hataları üretmek gerekir?

Aynı tenant, işlem ve anahtarla eşzamanlı iki istek gönderildiğinde tek bir iş değişikliği ve outbox kaydı oluşmalı. Aynı anahtar farklı gövdeyle gelirse 409 dönmeli. Başka tenant aynı anahtarı bağımsız kullanabilmeli; yetkisi kaldırılan kullanıcı ise eski kayıtlı yanıta erişememeli.

Commit sonrasında, poller uyandırılmadan süreç durdurulduğunda olay sonraki taramada bulunmalı. Dış servis kaydı oluşturduktan sonra yanıt kesildiğinde ikinci sipariş oluşmamalı; güvenli tekrar koşulları yoksa işlem başarıya çevrilmeden outcome_unknown olarak kalmalı. Lease devredildikten sonra eski worker’ın güncellemesi sıfır satır etkilemeli.

Bunları yalnız sorunsuz akışı taklit eden mock’larla sınamak yeterli olmaz. Constraint ve kilit yarışlarını gerçek veritabanında, bağlantı kopmalarını da kontrollü bir test sunucusunda görmek gerekir. Asıl kontrol, ilk isteğin çalışması kadar ikinci isteğin ne yaptığıdır.

Siz ne düşünüyorsunuz?

Bu site istenmeyenleri azaltmak için Akismet kullanır. Yorum verilerinizin nasıl işlendiğini öğrenin.