Das Übertragungsprotokoll für persistente Agenten (experimentell)

Experimentell. Die Leitung kann sich in einem späteren Minor-Release ändern oder das Feature kann entfernt werden. Versionen und das aussagekräftige Hello beschreibt, wie Sie eine Änderung erreicht.

Die Durable-Leitung ist die Art und Weise, wie Collie mit einem Durable-Agenten kommuniziert. Diese Seite erklärt sie für Entwickler, die einen Durable-Agenten ohne das SDK schreiben oder wissen möchten, was das SDK tut. Die genauen Regeln stehen in WIRE.md, und wo sich diese Seite und jene Datei unterscheiden, gilt WIRE.md. Das Durable-SDK übernimmt das alles für Sie.

Was übertragen wird

Collie wählt an und der langlebige Agent lauscht, und jeder Austausch ist eine HTTP-Anfrage mit einem JSON-Body.

Der langlebige Agent lauscht an einem privaten Unix-Socket oder hinter TLS unter einer URL (Transportwege). Collie pollt ihn: Es gibt keinen Push, kein WebSocket und keinen Stream. Jeder Pfad beginnt mit /session/v1, was ein fester Name ist, nicht die Version. Jeder Aufruf außer dem ersten hello überträgt die Version im Header X-Collie-Session. Ein Anfrage-Body ist ein einzelnes JSON-Objekt von höchstens 64 KiB, und ein leerer POST-Body liest sich als {}.

Jeder Fehler ist ein JSON-Body mit einem code, wie etwa 409 stale oder 404 no-such-pane. Jeder andere Pfad antwortet mit 404 not-found. Eine Antwort über ihrem Limit wird nicht gelesen, und ein POST, dessen Antwort abgeschnitten wird, hat ein unbekanntes Ergebnis (Anfrage-IDs).

Hello und Epoche

hello gibt an, wer der langlebige Agent ist, und die Epoche gibt an, mit welchem Start von ihm Collie spricht.

Collie ruft zuerst hello ohne den Versions-Header auf, wählt die höchste von beiden Seiten unterstützte Version und sendet sie bei jedem späteren Aufruf mit. Solange ready false ist, antwortet jede Route außer hello mit 503 starting, und das Telefon zeigt den Durable Agent als startend an. Ein Durable Agent setzt ready erst, wenn jede Konversation wieder angezeigt und jede offene Anfrage erneut gestellt wurde, sodass ein Neustart niemals ein halbes Layout anzeigt.

Der ETag des Snapshots ist "<epoch>-<rev>". rev erhöht sich bei jeder für Leser sichtbaren Änderung, sodass ein 304 den Durable Agent fast nichts kostet. Eine neue Epoche signalisiert Collie, dass der Durable Agent neu gestartet wurde. Collie zeigt die vorhandenen Bereiche weiter an, bis der neue Snapshot gelesen wird. Danach liest es jeden Bereich mit seinem alten Cursor und erhält die gesamte aktuelle Ansicht des Bereichs in einer einzigen Antwort.

Ein einzelner Lesefehler nach einem erfolgreichen Lesevorgang behält den letzten Snapshot für diese Abfrage bei. Zwei aufeinanderfolgende Fehler zeigen den Durable Agent als nicht erreichbar an. Ein Socket-Pfad, der die Berechtigungsprüfung nicht besteht, ist sofort nicht erreichbar.

Anfragen und Antworten

Eine Anfrage ist eine Fragekarte und bleibt vom ask-Ereignis des Durable Agents bis zu dessen ask-closed offen.

Ein Tippen nach der Entscheidung liefert 409 decided mit dem ersten Ergebnis, und nichts wird ausgeführt. Die Karte zeigt dann an, wer zuerst entschieden hat: "Im Durable Agent entschieden.", "Zeit vor einer Antwort abgelaufen." oder nach einem weiteren Tippen "Bereits beantwortet. Diese Karte verschwindet bei der nächsten Aktualisierung." Eine Anfrage, die der Durable Agent nicht mehr kennt, liefert 200 too-late. Die Karte zeigt dann "Nicht angenommen. Die Frage wird möglicherweise gleich wieder angezeigt.", da der Durable Agent sie nach einem Neustart unter derselben ID erneut stellen kann.

Eine Anfrage ist eine von vier Arten: permission, choice, text oder form. Jede hat ihr eigenes Antwortformat, aufgeführt bei Fragen des SDK.

Anfrage-IDs

Jede Aktion vom Smartphone hat eine Anforderungs-ID, sodass sie höchstens einmal ausgeführt wird.

Das Smartphone erzeugt eine Anforderungs-ID pro Absicht, und Collie schreibt eine eigene Quittung, bevor es die ID weitergibt. Der Durable Agent behält mindestens die letzten 500 IDs seiner Epoche. Eine Wiederholung einer abgeschlossenen ID erhält die erste Antwort erneut mit replayed: true und führt nichts aus. Dieselbe ID mit einer anderen Nutzlast erhält 409 request-id-reused.

Collie wiederholt einen POST niemals von selbst. Ein POST mit Zeitüberschreitung, Verbindungsabbruch oder einem 5xx-Fehler hat ein unbekanntes Ergebnis. Bei einer Antwort meldet die Karte dann: "Not sure the answer arrived. Try again sends it once more.", und "Try again" sendet dieselbe Anforderungs-ID, sodass der Speicher des Durable Agent eine Wiederholung beantwortet.

Ein Wiederholungsversuch, der die Anfrage geschlossen oder den Spielzug weitergerückt vorfindet, kann nicht feststellen, ob der erste Versuch ankam. Collie antwortet dem Smartphone dann "maybe applied", die Karte meldet "May already be applied. Check the chat.", und die Aktion wird kein drittes Mal gesendet.

Transportwege

Ein Durable Agent verwendet einen von zwei Transportwegen: einen privaten Socket auf dem Rechner von Collie oder TLS mit einem Token.

Die Bytes sind bei beiden identisch: die Routen, die Nachrichtenkörper, der Versions-Header, das ETag und die Fehlercodes. Nur wer den Durable Agent erreichen darf, unterscheidet sich.

Jeder Timeout ist eine Frist für den gesamten Austausch, vom Verbindungsaufbau bis zum letzten Byte. Über TLS ist jedes Polling eine Anfrage, die Ihr Host eventuell abrechnet, inklusive eines 304.

Einschränkungen

Collie schneidet alles ab oder lehnt alles ab, was über diesen Grenzen liegt. Ein Durable Agent, der innerhalb der Grenzen bleibt, verliert nichts.

Eine Zeichenkette, die ihr Limit überschreitet, wird gekürzt, und ihre Steuerzeichen sowie unsichtbaren Zeichen werden entfernt. Eine Liste, die ihr Limit überschreitet, behält ihre ersten Einträge. Eine Verlaufsseite, die ihr Limit überschreitet, wird gar nicht erst gelesen.

Versionen und das aussagekräftige Hello

Aktuell gibt es eine Übertragungsversion, 1, und Collie spricht 1..1.

Wenn Version 2 erscheint, akzeptiert Collie Version 1 noch für ein Minor-Release danach; das darauffolgende Minor-Release entfernt die Unterstützung. Ein Reader ignoriert Felder, Ereignistypen, Elementarten oder Codes, die er nicht kennt. Ein innerhalb von Version 1 hinzugefügtes Feld wie expiresAt oder decidedBy ist optional. Ein neues Pflichtfeld, eine neue Bedeutung für ein bestehendes Feld oder ein entferntes Feld erfordert eine neue Version.

Eine Anfrage einer Art, die das Telefon nicht kennt, wird als eine Anfrage dargestellt, die nicht vom Telefon aus beantwortet werden kann, ohne Schaltflächen.

Wenn die beiden Bereiche sich nicht überschneiden, liest Collie nichts mehr vom persistenten Agenten. Einmal pro Epoche des persistenten Agenten sendet es ein weiteres hello, diesmal mit seiner eigenen Version, damit der persistente Agent die Diskrepanz auf seiner Seite protokollieren kann. Der persistente Agent antwortet mit 409 incompatible und einem refusal, das beide Bereiche benennt. Dies ist das aufschlussreiche Hello.

Collie schreibt für jeden abgelehnten Bereich eine Zeile in sein Protokoll, und collie doctor zeigt beide Bereiche an. Die Startansicht des persistenten Agenten auf dem Telefon zeigt denselben Satz, zum Beispiel „Der persistente Agent spricht Übertragungsversion v2, dieses Collie spricht v1. Aktualisieren Sie Collie oder das SDK des Agenten.“ Aktualisieren Sie die ältere Seite.

Fundort der genauen Regeln

WIRE.md ist der Vertrag mit jeder Form, jedem Code und jeder Regel.

Die Entscheidungen dahinter sind Datensätze im Repository: