Akış ve istemciler

Uyumluluk: Pactmark 0.2.x. HTTP adaptörü, Web standardı işleyiciler üzerinden tipli JSON komutları ve Server-Sent Events sunar.

Tasarımın tamamı tekrardır

Şekil 1. İstemci gördüğü son sırayı saklar. Yeniden bağlandığında depo, o noktadan itibaren kalıcı olayları yeniden oynatır ve sonra yenilerini takip eder. Hiçbir şey kaybolmaz ve hiçbir şeyin sonsuza kadar tamponlanması gerekmez.

Akışı tüketmek

const source = new EventSource("/api/agent/v1/runs/run_01J.../events", {
  withCredentials: true,
});

let lastSequence = 0;

source.onmessage = (message) => {
  const event = JSON.parse(message.data);
  lastSequence = event.sequence;
  render(event);
};

source.onerror = () => {
  source.close();
  // Gerçekten işlediğiniz son sıradan yeniden bağlanın.
  reconnect(`/api/agent/v1/runs/run_01J.../events?afterSequence=${lastSequence}`);
};

Doğrudan çalışma zamanından:

for await (const event of runtime.events(authority, runId, {
  afterSequence: lastSequence,
  signal: abortController.signal,
})) {
  lastSequence = event.sequence;
}

lastSequence değerini yeniden bağlanma mantığınızın ulaşabileceği bir yerde saklayın. Sıfırdan yeniden bağlanan bir istemci koşunun tamamını yeniden oynatır — doğru ama israf; hiç işlemediği bir sıradan yeniden bağlanan bir istemcinin ise fark etmeyeceği bir boşluğu vardır.

Bağlantı kopması bir cevap değildir

Bu, en yaygın istemci hatasıdır:

Ne oldu	Ne anlama gelir	Ne anlama gelmez
SSE bağlantısı düştü	Taşıma kayboldu	Koşu durdu
HTTP isteği zaman aşımına uğradı	İstemciniz beklemekten vazgeçti	İş iptal edildi
Sayfa kapatıldı	Bir izleyici gitti	Koşu hakkında herhangi bir şey

Sonlanma durumunu öğrenmek için sorun:

const projection = await runtime.getRun(authority, runId);
// projection.status, projection.terminalErrorCode

İşi gerçekten durdurmak için açıkça iptal edin:

await runtime.cancel(authority, runId, { reasonCode: "user_abandoned" }, command);

Geri basınç bilinçli olarak sınırlıdır

Yavaş tüketiciler sınırlandırılır. Çalışma zamanı, okumayı bırakmış bir istemciyi beklerken akışın tamamını bellekte tutmak zorunda değildir — koşu hacmi büyüdükçe daha da önemli hâle gelen bir tasarım özelliği. Bir tüketici çok geride kalırsa afterSequence ile yeniden bağlanır ve depo kalıcı olaylardan yeniden oynatır. Kalıcı log, tamponun kendisidir.

Her isteğin kimliğini doğrulayın

Her komut ve her inceleme isteği kimlik doğrulamasından geçer. “Herkese açık koşu görünümü” diye bir şey yoktur.

Komutlar

Başlat, devam et, girdi gönder, karar ver, mutabakat yap, telafi et, iptal et — her biri doğrulanmış bir CommandContext ve idempotency anahtarıyla.

İnceleme

Koşu durumu, olaylar, artifact’lar, doğrulama ve kanıt — her biri verdiğiniz yetkiyle kapsamlandırılmış.

Idempotency anahtarlarınızı paralel bir mekanizma icat etmek yerine CommandContext’e eşleyin:

const command = createCommandContext({
  commandId: createCommandId(),
  operation: "run.start",
  payload: request,
});

Bir commandId’yi farklı içerikle yeniden kullanmak KAF_HTTP_IDEMPOTENCY_CONFLICT üretir. Aynı içerikle yeniden kullanmak aynı sonucu döndürür — dengesiz bir ağın arkasında tam olarak istediğiniz şey budur.

Hattaki hatalar

HTTP hataları, kararlı bir KAF_* koduyla Problem Details kullanır. Koda göre dallanın, mesaja göre asla:

{
  "type": "https://pactmark.dev/errors/policy-denied",
  "title": "KAF_POLICY_DENIED",
  "status": 403,
  "code": "KAF_POLICY_DENIED"
}

Yanıt gövdeleri, loglardan farklı bir açıklama seviyesi kullanır. Bir not-found yanıtı, başka bir tenant’ın kaynağının var olup olmadığını kasıtlı olarak söylemez — bkz. Hata başvurusu.

Host’un sahip olduğu yapılandırma

CORS, kimlik bilgisi modu, CSRF, istek ve gövde boyutu sınırları, süre sınırları, admission ve açıklama davranışı — hepsi host yapılandırmasıdır. Adaptör sizin için varsayılan seçmez, çünkü doğru cevap istemcinizin birinci taraf bir panel mi yoksa üçüncü taraf bir entegrasyon mu olduğuna bağlıdır.

HTTP başvurusu

Her rota, komut ve inceleme semantiğiyle.

Vercel dağıtımı

Rota adaptörünü bağlamak ve açık bir yanıtın neden arka plan worker’ı olmadığı.

Başlarken

Temel kavramlar

Rehberler

Dağıtım

Üretim

Güvenlik

Akış ve istemciler

Tasarımın tamamı tekrardır

Akışı tüketmek

Bağlantı kopması bir cevap değildir

Geri basınç bilinçli olarak sınırlıdır

Her isteğin kimliğini doğrulayın

Komutlar

İnceleme

Hattaki hatalar

Host’un sahip olduğu yapılandırma

HTTP başvurusu

Vercel dağıtımı

​Tasarımın tamamı tekrardır

​Akışı tüketmek

​Bağlantı kopması bir cevap değildir

​Geri basınç bilinçli olarak sınırlıdır

​Her isteğin kimliğini doğrulayın

Komutlar

İnceleme

​Hattaki hatalar

​Host’un sahip olduğu yapılandırma

HTTP başvurusu

Vercel dağıtımı

Tasarımın tamamı tekrardır

Akışı tüketmek

Bağlantı kopması bir cevap değildir

Geri basınç bilinçli olarak sınırlıdır

Her isteğin kimliğini doğrulayın

Hattaki hatalar

Host’un sahip olduğu yapılandırma