10/Documentation
Dayanıklı hat protokolü (deneysel)
Geliştiriciler için Collie ile dayanıklı bir aracı arasında nelerin iletildiği: yollar, hello ve epoch, bir sorma işleminin yaşam döngüsü ve istek kimlikleri, soket ve belirteç aktarımları, sınırlar ve sürüm kuralı; kesin kurallar için WIRE.md bağlantısıyla birlikte
Deneysel. Kablo değişebilir veya özellik sonraki bir ikincil sürümde kaldırılabilir. Bir değişikliğin size nasıl ulaşacağını Sürümler ve açıklayıcı merhaba açıklar.
Durable kablo, Collie'nin bir durable agent ile iletişim kurma yöntemidir. Bu sayfa, SDK olmadan bir durable agent yazan veya SDK'nin ne yaptığını öğrenmek isteyen geliştiriciler için bunu açıklar. Kesin kurallar WIRE.md içindedir; bu sayfa ile o dosya farklılık gösterdiğinde WIRE.md doğrudur. Durable SDK bunların tümünü sizin yerinize konuşur.
Neler aktarılır
Collie arama yapar, durable agent dinler ve her etkileşim JSON gövdesine sahip bir HTTP isteğidir.
Durable agent özel bir Unix soketi üzerinden veya TLS arkasında bir URL'de (Aktarım protokolleri) dinler. Collie bunu sorgular (poll): push, WebSocket ve akış yoktur. Her yol sabit bir ad olan ve sürümü belirtmeyen /session/v1 ile başlar. İlk hello dışındaki her çağrı sürümü X-Collie-Session başlığında taşır. İstek gövdesi en fazla 64 KiB boyutunda tek bir JSON nesnesidir ve boş bir POST gövdesi {} olarak okunur.
| yöntem ve yol | ne yapar | yanıt sınırı |
|---|---|---|
GET /hello | Durable agent'ın adı, sürüm aralığı, çağı (epoch), hazır olma durumu ve sınırları (caps) | 16 KiB |
GET /snapshot | Düzen: çalışma alanları, sekmeler, durumlarıyla birlikte paneller, sıra ve açık talepler (asks) ile başlatıcılar. Bir ETag taşır ve hiçbir şey değişmediğinde 304 yanıtı verir | 4 MiB |
GET /pane/:id/events?after=N&epoch=E | Bir imleçten sonraki panel olayları | 8 MiB |
POST /pane/:id/answer | Bir talebe (ask) yanıt | 16 KiB |
POST /pane/:id/send | Çalışan sırayı yönlendirmek veya bir sonrakini beklemek için panel metni | 16 KiB |
POST /pane/:id/abort | Çalışan sırayı durdurun | 16 KiB |
POST /pane/:id/action | Panelin kemer düğmelerinden birine dokunma | 16 KiB |
POST /rename | Bir çalışma alanı veya sekme için yeni bir başlık | 16 KiB |
POST /close | Bir paneli, sekmeyi veya çalışma alanını kapatın | 16 KiB |
POST /starter/:id | Bir başlatıcı çalıştırın. Yanıt, yeni panelin adını belirtir | 16 KiB |
GET /conversations?after=C&limit=N | Durable agent'ın açık ve kapalı konuşmaları, en yeni ilk sırada | 1 MiB |
GET /conversation/:id/items?after=C&limit=N | Bir konuşmanın ögeleri, en eski ilk sırada | 8 MiB |
POST /reopen | Kapatılmış bir konuşmayı tekrar gösterin | 16 KiB |
Her hata, 409 stale veya 404 no-such-pane gibi bir code içeren JSON gövdesidir. Diğer tüm yollar 404 not-found yanıtı verir. Sınırını aşan yanıt okunmaz ve yanıtı kesilen bir POST isteğinin sonucu belirsizdir (İstek kimlikleri).
Hello ve çağ (epoch)
hello, durable agent'ın kim olduğunu belirtir; çağ ise Collie'nin onun hangi başlangıcıyla konuştuğunu gösterir.
hello alanı | içerdikleri |
|---|---|
service | Tam olarak collie-durable. Bu olmadan Collie, durable agent'ı başka bir sunucu olarak algılar ve başka hiçbir çağrı yapmaz |
protocol | Durable agent'ın konuştuğu kablo sürüm aralığı, { min, max }. Günümüzde { min: 1, max: 1 } |
host.name | Durable agent'ın kendi adı, yalnızca ekran metnidir, en fazla 64 bayt |
epoch | Durable agent'ın her başlangıcında yeni ve rastgele, en az 128 bit, hiçbir zaman yeniden kullanılmaz |
ready | Durable agent bir başlatmanın ardından panellerini yerleştirirken False değerindedir |
caps | Durable agent'ın yapabilecekleri; her biri bir booleandır. Bulunmayan bir yetenek false kabul edilir |
Collie önce sürüm başlığı olmadan hello çağrısı yapar, her iki tarafın da desteklediği en yüksek sürümü seçer ve sonraki her çağrıda bunu gönderir. ready false olduğu sürece hello dışındaki her rota 503 starting yanıtı verir ve telefon durable agent'ı başlatılıyor olarak gösterir. Bir durable agent, ready değerini yalnızca her konuşma tekrar gösterildiğinde ve her açık talep (ask) tekrar iletildiğinde belirler; böylece bir yeniden başlatma asla yarım bir yerleşim göstermez.
Snapshot'ın ETag değeri "<epoch>-<rev>" olur. rev, okuyucunun görebileceği her değişiklikte artar; bu sayede 304 yanıtı durable agent için neredeyse hiç maliyet oluşturmaz. Yeni bir epoch, Collie'ye durable agent'ın yeniden başladığını bildirir. Collie, yeni snapshot'ı okuyana kadar elindeki panelleri göstermeye devam eder. Ardından her paneli eski imleciyle okur ve tek bir yanıtta panelin geçerli tüm görünümünü alır.
Başarılı bir okumanın ardından tek bir başarısız okuma olursa o yoklama için son snapshot korunur. Art arda iki hata, durable agent'ı erişilemez olarak gösterir. Gizlilik denetiminden geçemeyen bir soket yolu hemen erişilemez olur.
Talepler ve yanıtlar
Talep (ask) bir soru kartıdır; durable agent'ın ask olayından ask-closed anına kadar açıktır.
| durum | kimin belirlediği | telefonun gösterdiği içerik |
|---|---|---|
| Open | Durable agent talebi oluşturur. Herhangi bir talep açıkken panel waiting olarak okunur | "Yanıtınız gerekiyor" altında, durable agent'ın adını ve talepte expiresAt varsa kalan süreyi içeren bir kart |
| Changed | Durable agent talebi yerinde değiştirir ve revision değeri artar | Kart yeniden çizilir. Eski forma dokunulduğunda 409 stale döner ve kartta "Bu talep değişti. Tekrar okuyun, ardından bir yanıta dokunun." yazar. |
| Taken | Telefon yanıt verir ve durable agent talebi by: "phone" ile kapatır | Kart kaybolur ve seçeneğin belirttiği şekilde araç çalıştırılır veya reddedilir |
| Durable agent içinde kararlaştırıldı | Durable agent talebi kendisi kapatır, decidedBy: "program". Sıranın durdurulması da buna dahildir | Chat içinde "Durable agent içinde kararlaştırıldı" ile başlayan ve talebin başlığını içeren bir satır |
| Timed out | Saat expiresAt değerini geçer, decidedBy: "timeout" | Chat içinde "Bir yanıttan önce zaman aşımına uğradı" ile başlayan ve talebin başlığını içeren bir satır |
Karardan sonra gelen bir dokunma, ilk sonuçla birlikte 409 decided alır ve hiçbir şey çalıştırılmaz. Kart daha sonra ilk kararı kimin verdiğini söyler: "Durable agent içinde kararlaştırıldı.", "Bir yanıttan önce zaman aşımına uğradı." veya başka bir dokunmanın ardından "Zaten yanıtlandı. Bu kart sonraki güncellemede kaybolur." Durable agent'ın artık bilmediği bir talep 200 too-late yanıtı verir. Kart ardından "Alınmadı. Soru birazdan tekrar görünebilir." der, çünkü yeniden başlatmanın ardından durable agent soruyu aynı kimlikle tekrar oluşturabilir.
| kural | neden |
|---|---|
| Talep kimliği, panel kimliği ile araç çağrısı kimliğinin bir karmasıdır (hash) | Yeniden başlatmanın ardından tekrar iletilen aynı araç çağrısı aynı kimliğe sahip olur, böylece yeniden başlatma sırasında gönderilen bir yanıt hedefine ulaşır |
Bir permission kartı, modelin sözlerinden değil, yalnızca aracın adından ve bağımsız değişkenlerinden oluşturulur | Evet yanıtı isteyen bir model çağrıyı övgüyle tanımlayabilir |
TLS arkasındaki bir durable agent hiçbir allow-always sunmamalıdır | Belirteç tek geçittir; bu nedenle belirteci elinde bulunduranın vereceği tek bir yanıt, sonraki tüm çağrıların geçmesine izin verir |
Telefon; sözcükleri kesilmiş ya da temizlenmiş veya hiçbir araç belirtmeyen bir kartta hiçbir allow-always sunmaz | Kişi, yetkinin neleri kapsadığını göremez |
expiresAt, bir saat dilimi içeren ISO 8601 biçimidir | Bu süreden sonra talep timeout tarafından karara bağlanır ve bir anlık görüntü artık onu açık olarak listelemez |
| Kalıcı ajan, bölme başına karara bağlanmış en az son 500 talebinin sonucunu saklar | Gecikmiş bir dokunma, yalın bir too-late yerine decided ve ilk sonucu alır |
Bir talep dört türden biridir: permission, choice, text veya form. Her birinin SDK'nin Sorular alanında listelenen kendi yanıt biçimi vardır.
İstek kimlikleri
Telefondan gelen her eylemin bir istek kimliği vardır, bu nedenle en fazla bir kez çalışır.
Telefon, niyet başına bir istek kimliği oluşturur ve Collie bu kimliği iletmeden önce kendi makbuzunu yazar. Kalıcı ajan, dönemine ait en az son 500 kimliği saklar. Tamamlanmış bir kimliğin tekrarı, ilk yanıtı replayed: true ile yeniden alır ve hiçbir şey çalıştırmaz. Farklı bir yük ile aynı kimlik ise 409 request-id-reused alır.
Collie hiçbir zaman kendiliğinden bir POST isteğini yeniden denemez. Zaman aşımına uğrayan, bağlantısını kaybeden veya 5xx alan bir POST isteğinin sonucu bilinmez. Bir yanıt için kart daha sonra "Not sure the answer arrived. Try again sends it once more." iletisini gösterir ve Tekrar dene aynı istek kimliğini gönderir; böylece kalıcı ajanın belleği yinelenen isteği yanıtlar.
Talebin kapandığını veya sıranın geçtiğini gören bir yeniden deneme, ilk denemenin ulaşıp ulaşmadığını belirleyemez. Collie daha sonra telefona "maybe applied" yanıtını verir, kart "May already be applied. Check the chat." iletisini gösterir ve eylem asla üçüncü kez gönderilmez.
Aktarım protokolleri
Kalıcı ajan iki iletim yolundan birini kullanır: Collie'nin makinesindeki özel bir soket veya bir belirteç ile TLS.
Baytlar her ikisinde de aynıdır: yollar, gövdeler, sürüm başlığı, ETag ve hata kodları. Yalnızca kalıcı ajana kimin erişebileceği farklılık gösterir.
| soket üzerinden | kural |
|---|---|
| Yol | Mutlak, en fazla 103 bayt. Her iki taraf da bunu COLLIE_DURABLE_SOCKET üzerinden okur |
| Modlar | Soket, 0700 modundaki bir klasörde bulunan 0600 modundadır. Kalıcı ajan, dinlemeden önce eski bir soket dosyasını kaldırır |
| Yol denetimi | Her bağlantıdan önce Collie yolun her bir parçasını lstat ile denetler. Hiçbir parça sembolik bağ değildir. Soketin klasörü 0700 modu ile sizindir. /tmp gibi yapışkan olanlar hariç, üzerindeki hiçbir klasör grup veya diğer kullanıcılar tarafından yazılamaz. Soket, hiçbir grup veya diğer kullanıcı izni olmadan sizindir |
| Başarısız bir denetim | Collie bağlanmaz ve kalıcı ajanı socket-not-private ve başarısız olan parça ile erişilemez olarak gösterir |
| Belirteç | Yok. Özel soket bir kapı görevi görür |
| Kimler işlem yapabilir | Kullanıcınıza ait herhangi bir işlem. Kalıcı ajan kendi alt işlemlerini 403 caller-refused ile reddedebilir |
| Zaman aşımları | hello, snapshot ve events için 1000 ms. Bir answer, send, stop, action, rename veya close için 3000 ms. Bir starter için 30000 ms |
| Collie ne sıklıkla sorgular | Bir telefon izlerken her 1 sn'de bir, aksi halde her 3 sn'de bir. Kapalı durumdaki bir kalıcı ajana yoklama başına bir kez sorulur |
| Sistemler | Linux ve macOS. Windows için soket iletim yolu yoktur |
| TLS üzerinden | kural |
|---|---|
| URL | https:// veya yerel bir test için http://127.0.0.1:<port> ya da http://localhost:<port>. En fazla 2048 bayt, kullanıcı adı veya parola yok, sorgu yok, parça yok. Collie buna /session/v1 ekler |
| Belirteç | En az 32 bayt, boşluk içermeyen yazdırılabilir ASCII. Collie, hello dahil her istekte Authorization: Bearer <token> gönderir |
| Durable agent denetimi | Sürümden, hello ve ready değerlerinden önce, sabit zamanda karşılaştırılan belirteç. Eksik veya yanlış bir belirteç, yalnızca yalın bir 401 { "code": "unauthorized" } alır, başka hiçbir şey almaz |
| Yönlendirmeler | Collie hiçbirini izlemez. Bir 3xx durum olarak yukarı iletilir, böylece belirteç asla başka bir ana bilgisayara ulaşmaz |
| ETag | Yanıtı sıkıştıran bir proxy etiketi W/"<epoch>-<rev>" olarak zayıflatabilir. Her iki taraf da etiketi W/ kaldırılmış halde karşılaştırır |
| Bir ret | Bir 401 veya 403, durable agent'ı token-refused ile ulaşılamaz olarak gösterir |
| Zaman aşımları | Her okuma ve yazma için 5000 ms, çünkü uyuyan bir durable agent soğuk uyanabilir. Bir starter için 30000 ms |
| Collie ne sıklıkla sorgular | Bir telefon izlerken her 2 saniyede bir, aksi takdirde her 10 saniyede bir. Kapalı veya reddedilen bir durable agent'a en fazla 10 saniyede bir sorulur |
Her zaman aşımı, bağlantıdan son bayta kadar tüm veri alışverişi için bir son tarihtir. TLS üzerinden her yoklama, sunucunuzun faturalandırabileceği bir istektir, 304 dahil.
Sınırlar
Collie bu sınırları aşan her şeyi keser veya reddeder, bu nedenle bu sınırlar içinde kalan bir durable agent hiçbir şey kaybetmez.
| ne | limit |
|---|---|
| Anlık görüntü başına workspace sayısı | 64 |
| Anlık görüntü başına sekme sayısı | 256 |
| Anlık görüntü başına bölme sayısı | 256 |
| Bölme başına açık ask sayısı | 50, önce en eskisi |
Bir permission seçeneği | 6 |
Bir choice ve bir choice alanının seçenekleri | 8 |
Bir form alanları | 6 |
| Anlık görüntü başına starter sayısı | 50 |
| Bölme başına belt düğmesi sayısı | 4, 16 karakterlik bir etiket |
| Bir kimlik | 1 ila 128 bayt, kontrol karakteri yok, boşluk yok, /, ? veya # karakterlerinden hiçbiri yok |
| Bir istek gövdesi | 64 KiB, aksi takdirde 413 too-large |
| Yanıtlar | hello 16 KiB, snapshot 4 MiB, events 8 MiB, conversations 1 MiB, items 8 MiB, bir POST 16 KiB |
| Yanıt başına olay sayısı | 1000. Geride kalan bir okuyucu güncel görünümü alır, en fazla en yeni 2000 öge |
Bir user, reply, thinking veya notice ögesinin metni | 64 KiB |
Bir markdown veya code ögesinin metni | 32 KiB |
| Telefonun gönderdiği metin | 32 KiB |
Bir link ögesi | Yalnızca https://, en fazla 2048 karakter |
| Bir geçmiş sayfası | 100 konuşma veya 1000 öge |
| Bir geçmiş imleci | 512 bayt yazdırılabilir ASCII, boşluk yok |
Sınırını aşan bir dize kesilir; kontrol karakterleri ve görünmeyen karakterleri kaldırılır. Sınırını aşan bir liste ilk girdilerini korur. Sınırını aşan bir geçmiş sayfası hiç okunmaz.
Sürümler ve açıklayıcı merhaba
Şu anda tek bir iletim protokolü sürümü vardır, 1, ve Collie 1..1 konuşur.
Sürüm 2 çıktığında, Collie bunu takip eden bir alt sürüm boyunca sürüm 1'i kabul edecek, ardından gelen alt sürümde ise desteği kaldıracaktır. Bir okuyucu bilmediği bir alanı, olay türünü, öge çeşidini veya kodu yok sayar. Sürüm 1 içine eklenen expiresAt veya decidedBy gibi bir alan isteğe bağlıdır. Yeni bir zorunlu alan, eski bir alan için yeni bir anlam veya kaldırılan bir alan yeni bir sürüm gerektirir.
Telefonun bilmediği türdeki bir istek, telefondan yanıtlanamayacak bir istek olarak, düğmeler olmadan gösterilir.
İki aralık kesişmediğinde, Collie dayanıklı aracıdan daha fazla bir şey okumaz. Dayanıklı aracının her dönemi için, dayanıklı aracının uyumsuzluğu kendi tarafında günlüğe kaydedebilmesi amacıyla, bu kez kendi sürümüyle bir hello daha gönderir. Dayanıklı aracı, her iki aralığı da belirten bir refusal ile 409 incompatible yanıtını verir. Bu, bildiren karşılamadır.
Collie reddettiği her aralık için günlüğüne bir satır yazar ve collie doctor her iki aralığı da gösterir. Dayanıklı aracının telefondaki ana ekranında aynı cümle yazar, örneğin "Dayanıklı aracı v2 iletim protokolünü konuşuyor, bu Collie v1 konuşuyor. Collie'yi veya aracının SDK'sini güncelleyin." Daha eski olan tarafı güncelleyin.
Kesin kuralların bulunduğu yer
Her biçim, kod ve kuralla birlikte sözleşme WIRE.md belgesidir.
Arkasındaki kararlar depoda bulunan kayıtlardır:
| kayıt | neye karar verdiği |
|---|---|
| ADR 0099 | Durable agent, ekranı olmayan bir çoğullayıcıdır |
| ADR 0100 | Bir ask veri olarak iletilir ve kimliğe göre yanıtlanır |
| ADR 0101 | Send ve stop, telefonun gördüğü sırayı adlandırır |
| ADR 0102 | Starter'lar, New sayfasındaki satırlardır |
| ADR 0103 | İki aktarım |
| ADR 0104 | Durable agent bir oturumdur ve çıkış işlemidir |
| ADR 0105 | SDK bir npm paketidir |
Bu sayfayı GitHub üzerinde düzenleyin