Ana içeriğe geç

vNext v0.0.62 Migration Rehberi

· 6 dakikalık okuma
vNext Team
vNext Team
Burgan Tech Engineering

Bu rehber, vNext v0.0.62 ile gelen yeni yetenekleri ve mevcut bir domain projesini bu sürüme taşırken atılması gereken adımları anlatır. Sürüm dört entegrasyon odaklı yetenek getiriyor: HTTP Task'ta yapılandırılabilir contentType, state'lerde deklaratif long-poll interaction, multi-task function'larda output header/status forward ve runtime keşfi için vnext-runtime MCP sunucusu. Ayrıca bir yetkilendirme davranış değişikliği (yalnızca deny içeren grant setleri blacklist olur) ve async transition için doğrudan Dapr-enqueue continuation modu yer alıyor.

Bu sürümle birlikte bileşen şeması 0.0.47'ye yükseldi. Doğrulama yapmadan önce domain projenizde @burgan-tech/vnext-schema paketini güncelleyin.

Teknik release notları için: Release v0.0.62.

1. HttpTask contentType​

HTTP Task config'ine yeni bir contentType alanı eklendi. Böylece istekler artık yalnızca application/json ile sınırlı değil — application/xml, text/plain, application/x-www-form-urlencoded gibi farklı content-type'lar desteklenir hale geldi.

Ne değişti​

  • attributes.config.contentType ile request body'nin Content-Type header'ı tanımlanabilir.
  • Request body byte-exact korunur; bu özellikle body'nin imzalandığı (signing) senaryolarda kritiktir — yeniden serialize edilmesi imzayı geçersiz kılardı.
  • Alan opsiyoneldir; tanımlanmazsa önceki varsayılan davranış geçerlidir, mevcut tanımlar değişmeden çalışır.
{
  "attributes": {
    "type": "6",
    "config": {
      "url": "https://api.example.com/sign",
      "method": "POST",
      "contentType": "application/xml",
      "body": { "...": "..." }
    }
  }
}

Migrasyon adımları​

  1. JSON dışı bir gövde gönderen veya gövdesi imzalanan HTTP task'larınızı belirleyin.
  2. Bu task'ların config'ine uygun contentType değerini ekleyin.
  3. @burgan-tech/vnext-schema paketini 0.0.47'ye güncelleyip npm run validate ile doğrulayın.

İlgili doküman: HTTP Task

2. State interaction / Long Poll​

State Function, client tarafında long-polling ile süreç durumunu döner. Şimdiye kadar her client, açık tutulan isteğin ne zaman sonlandırılacağını kendi tahmin ediyordu. Artık bu, state tanımında deklaratif olarak belirtilebilir.

Ne değişti​

State'lere opsiyonel bir interaction.longPoll bloğu eklendi. Runtime, isteği bir transition gerçekleşene veya fallback timeout dolana kadar açık tutar. Bu sayede bir süreç tasarımında farklı client'lar süreci kendi durak noktaları ile belirleyebilir.

AlanTipZorunluAçıklama
terminatebooleanEvetState'ten çıkıldığında açık olan long-poll isteğinin sonlandırılıp sonlandırılmayacağı.
fallbackTimeoutSecondsintegerHayırİstek fallback'e düşmeden önce açık tutulacağı maksimum saniye (minimum: 1).
rolesarrayEvetLong-poll etkileşimini kullanabilecek roller. DENY her zaman ALLOW'u geçersiz kılar.
{
  "key": "waiting-approval",
  "stateType": 2,
  "interaction": {
    "longPoll": {
      "terminate": true,
      "fallbackTimeoutSeconds": 30,
      "roles": [
        { "role": "client.app", "grant": "allow" }
      ]
    }
  }
}

Migrasyon adımları​

  1. Client'ların long-poll yaptığı durak (bekleme) state'lerini belirleyin.
  2. Bu state'lere interaction.longPoll bloğunu ekleyin; hangi rolün etkileşimi kullanacağını roles ile, sonlandırma davranışını terminate ile belirtin.
  3. İstemci tarafında manuel long-poll sonlandırma mantığınız varsa, deklaratif yapıya geçirerek sadeleştirin.

İlgili dokümanlar: Workflow → State Interaction (Long Poll) · Async / Sync Yöntemi

3. Function ResponseHeader & StatusCode Forward​

Bir function onExecutionTasks ile birden fazla task çalıştırıp sonucu bir IOutputHandler ile şekillendirdiğinde, output ScriptResponse'unun taşıdığı header'lar ve status code artık nihai function HTTP yanıtına forward edilir.

Ne değişti​

  • Önceden output handler yalnızca response gövdesini etkileyebiliyordu; header ve status code düşürülüyordu.
  • Artık output handler, yanıt status'ünü (örn. 201, 202) ayarlayabilir ve Location, ETag gibi header'ları yayabilir.
  • StandardTaskResponse zaten StatusCode ve Headers taşıyordu; bu değişiklik bunların multi-task function output'una forward edilmesini sağlar.

Migrasyon adımları​

  1. Multi-task (onExecutionTasks) kullanan function'larınızda output handler'ı gözden geçirin.
  2. Yanıt status code veya header'ı kontrol etmek istiyorsanız döndürdüğünüz ScriptResponse üzerinde ilgili alanları set edin.

İlgili dokümanlar: Custom Functions · Interfaces → IOutputHandler

4. vnext-runtime MCP Sunucusu​

vNext bileşenlerini, canlı runtime verisini ve statik vnext-meta'yı MCP uyumlu ajanlara (Claude Code, Cursor, CI, hosted asistanlar) sunan standalone bir Model Context Protocol sunucusu (vnext-runtime) hayata geçirildi. Böylece AI toolları ile doğrudan runtime bazında AI agent yapılandırmaları kullanılabilir.

Ne değişti​

  • Sunucu, Orchestration HTTP API'yi tiplenmiş bir HttpClient ile çağırır; DB / Redis / Dapr referansı yoktur.
  • İki transport: stdio (lokal IDE) ve Streamable HTTP (hosted / CI).
  • Her instance tek domain sunar (Mcp:Domain); HTTP transport'ta sabit bir Mcp:ApiKey ile yetkilendirilir (stdio gated değildir).
  • Tool grupları: ComponentTools, RuntimeTools, MetaTools ve AllowMutations ile açılan MutatingRuntimeTools.
dotnet tool install -g BBT.Workflow.Mcp
claude mcp add vnext-runtime \
  --env Mcp__OrchestrationBaseUrl=http://localhost:4201 \
  --env Mcp__Domain=<your-domain> \
  -- vnext-mcp

Migrasyon adımları​

  1. Lokal IDE için dotnet tool ile kurun (BBT.Workflow.Mcp), Mcp__Domain ve Mcp__OrchestrationBaseUrl ortam değişkenlerini verin.
  2. Hosted/CI için Docker image'ı (ghcr.io/burgan-tech/vnext/mcp-server) HTTP transport ile çalıştırın ve Mcp__ApiKey ile koruyun.
  3. Mutasyon araçlarına (start/transition/publish/invalidate) ihtiyaç yoksa AllowMutations=false (varsayılan) bırakın.

İlgili doküman: vnext-runtime MCP Server

5. Davranış Değişikliği — Deny-only Rol Grant'ları Blacklist​

Yetkilendirme modelinde bir roles / queryRoles setinin niyeti artık iki şekilde yorumlanır:

  • Set içinde en az bir allow varsa → allow-list (whitelist): yalnızca eşleşen allow rolleri geçer (varsayılan deny). Mevcut davranış.
  • Set yalnızca deny içeriyorsa → blacklist: listelenenler dışındaki herkese izin verilir (varsayılan allow). Yeni davranış.

Her iki durumda da DENY her zaman ALLOW'u geçersiz kılar. Bu sayede "X hariç herkese izin ver" kuralı, izinli her rolü tek tek saymadan ifade edilebilir.

:::warning Geriye dönük etki Yalnızca deny grant'ı içeren mevcut bir set, önceki sürümde pratikte herkesi engelleyebilirken, bu sürümde listelenenler dışındaki herkese açık hale gelir. :::

Migrasyon adımları​

  1. Tüm transition roles, flow/state queryRoles, state alias.roles ve master şema x-roles tanımlarınızı tarayın.
  2. Yalnızca deny içeren setleri belirleyin; niyetiniz "herkesi engelle" idiyse en az bir allow grant'ı ile allow-list'e çevirin.
  3. Niyetiniz gerçekten "listelenenler hariç herkese izin" ise mevcut deny-only set'i koruyabilirsiniz.

İlgili doküman: Yetkilendirme (Authorization)

6. Async Continuation — Doğrudan Dapr-enqueue + Outbox Fallback​

v0.0.60'taki yapılandırılabilir asenkron transition modlarının üzerine, continuation'lar artık doğrudan Dapr üzerinden kuyruğa alınabilir; doğrudan enqueue yolu kullanılamadığında transactional outbox dayanıklılık fallback'i devreye girer. Bu, sağlıklı koşullarda async continuation gecikmesini azaltırken dayanıklılık garantisini korur.

Migrasyon adımları​

  1. sync=true / sync=false davranışı için Async / Sync Yöntemi sayfasına bakın.
  2. Bu sürüm dayanıklılık değişiklikleri için EF Core migration'ları içerir — db-migrator image'ı ile şema güncellemesini uygulayın.

İlgili doküman: Async / Sync Yöntemi

7. Düzeltmeler​

Bu düzeltmeler çoğunlukla otomatik olarak geçerlidir; ek migrasyon adımı gerektirmez:

  • SOAP Task derleme + escaping (#738): SoapTask mapping'i CS0012 ile derlenemiyordu ve varsayılan yolda XML özel karakter escaping'i tutarsızdı; düzeltildi.
  • ChainToken gate (#730): Parent instance Busy subtype taşırken child sub-process'in Ready'ye geçişi yanlışlıkla reddediliyordu; düzeltildi.
  • Domain replacement (#729): Source domain ile eşleşen subprocess referansları atlanıyordu; replacement artık doğru yeniden yazıyor.

Özet​

  • HttpTask contentType ile farklı content-type desteği + imzalama için byte-exact body.
  • State interaction.longPoll ile deklaratif, rol bazlı long-poll sonlandırma; client'lar kendi durak noktalarını belirler.
  • Multi-task function output'unda header/status code nihai yanıta forward edilir.
  • vnext-runtime MCP ile component/runtime/meta keşfi AI toollarına açılır (stdio + Streamable HTTP).
  • Deny-only rol grant setleri artık blacklist (default allow); DENY > ALLOW korunur.
  • Async continuation doğrudan Dapr-enqueue + outbox fallback ile çalışır.
  • Bileşen şeması 0.0.47'ye yükseldi.

Teknik release notları: Release v0.0.62