Vercel Workflow SDK 5.3.1 atomik idempotent başlatma ekliyor, yinelenen çalışma yarışını kapatıyor

Vercel, Workflow SDK'sının 5.3.1 sürümünü çalışmaların başlama biçiminde bir değişiklikle yayımladı: start() artık bir çalışmayı kabul etme ve hook'unu talep etme işlemlerini tek bir atomik adımda gerçekleştirebiliyor. Vercel changelog'una göre yinelenen workflow başlatmaları artık güvenli biçimde başarısız oluyor ve önceki iki adımlı desende varlığı belgelenmiş bir yinelenen başlatma yarışı kapatılıyor.

Kapatılan yarış

Bu sürümden önce idempotent başlatmalar, getHookByToken() ile mevcut bir hook'un aranması ve ardından start() çağrılmasıyla kuruluyordu. Arama ve başlatma ayrı işlemler olduğu için changelog, aynı token'ı taşıyan iki eşzamanlı isteğin her ikisinin de aramayı geçebildiği ve her ikisinin de çalışma başlatabildiği bir boşluk tanımlıyor.

Yeni API bu adımları tek bir işleme indiriyor. Çağıranlar start() fonksiyonuna experimental_hook: { token } seçeneğini geçiriyor ve SDK, çalışmayı kabul edip hook'u atomik olarak talep ediyor. Belirli bir token'ı yalnızca tek bir çalışma sahiplenebiliyor; aynı token'la yapılan ikinci bir start() çağrısı, sahibin conflictingRunId değerini taşıyan bir HookConflictError fırlatıyor ve kopya hiçbir zaman çalışmaya dönüşmüyor.

Kopyalar yok edilmiyor, yönlendiriliyor

Başarısız olan bir kopya başlatma çıkmaz sokak olmak zorunda değil. Changelog, HookConflictError hatasını yakalayan ve kopyanın yükünü, token'ı sahiplenen çalışmaya resumeHook(token, payload) ile ileten bir istek işleyiciyi gösteriyor; böylece o çalışmanın kimliği started: false bayrağıyla döndürülüyor.

Hook, çalışma kabul edildiği anda talep edildiği için resumeHook, çalışma yürütülmeye başlamadan önce bile işliyor; Vercel, erken yüklerin tamponlandığını ve sırayla teslim edildiğini söylüyor. Workflow içinde aynı token'la çağrılan createHook({ token }), başlatmada talep edilen hook'a bağlanıyor: Vercel bu bağlanmayı garanti olarak nitelendiriyor çünkü yeni bir hook kaydetmiyor, workflow adımı eklemiyor ve getConflict() null olarak sonuçlanıyor.

Token, idempotency anahtarıdır

Token'ın çağıranın kendi alanından gelmesi bekleniyor: bir sipariş kimliği, fatura kimliği, içe aktarma kimliği ya da istek kimliği. Vercel, tek başına token'ın idempotency'yi garanti ettiğini ve workflow'un hook'u hiç açmak zorunda olmadığını söylüyor. Workflow açmazsa, token yalnızca bir idempotency anahtarı olarak hizmet eder ve çalışma normal biçimde tamamlanır.

Bir çalışma bittikten sonraki koruma için experimental_minRetention, çalışma sona erdiğinde token'ı kullanılamaz bırakıyor; saklama penceresi start() anından itibaren sayıldığı için geç gelen kopyalar yeni bir çalışma doğurmak yerine reddediliyor. Hem başlatma seçeneği hem de saklama denetimi bu sürümde hâlâ deneysel olarak işaretlenmiş durumda. Vercel, kullanıcıları özelliği benimsemek için workflow 5.3.1'e yükseltmeye ve idempotency belgelerini okumaya yönlendiriyor.

Neden önemli

Idempotency, webhook'lar, istemci yeniden denemeleri ya da çift tıklamalarla çalışan her şey için temel bir gerekliliktir; şu ana kadar Workflow SDK kullanıcıları bunu, bilinen bir yarış içeren iki adımlı ara-ve-başlat deseniyle kurmak zorundaydı. Garantiyi platforma taşımak, tek bir token'ın tam olarak tek bir çalışmayla eşleşmesi ve sessiz bir kopyanın yerine makine tarafından okunabilir bir çakışma hatası gelmesi anlamına geliyor.

Tasarım ayrıca gereksiz isteklere faydalı bir yön veriyor: Bir uygulama kopyayı çöpe atmak yerine yükünü token'ı sahiplenen çalışmaya devredebilir ve yükün sırayla işlenmesini sağlayabilir. Bu, bir hata yolunu istek işlemenin normal bir parçasına dönüştürüyor; bu da sipariş işleme, içe aktarmalar ve bir alan tanımlayıcısıyla anahtarlanan güncellemeler alan her workflow için önemli. Küçük bir API eklentisi, doğruluk üzerinde büyük bir etki yaratıyor.