durableの通信プロトコル（実験的機能）

実験的。 ワイヤの変更や、機能の削除が今後のマイナーリリースで行われる可能性があります。変更がどのように届くかについてはバージョンと情報通知用helloを参照してください。

durableワイヤは、Collieがdurable agentと通信するためのプロトコルです。このページでは、SDKを使わずにdurable agentを作成する開発者や、SDKの内部動作を把握したい開発者向けに解説します。厳密なルールはWIRE.mdに記載されており、このページと当該ファイルの内容が異なる場合はWIRE.mdが正となります。durable SDKがこれらすべてを自動で処理します。

送受信されるデータ

Collieが接続し、durable agentが待受を行います。各やり取りはJSONボディを伴う1つのHTTPリクエストです。

durable agentはプライベートなUnixソケット、またはURL（トランスポート）のTLS配下で待受を行います。Collieはこれをポーリングします。プッシュ通知、WebSocket、ストリームはありません。すべてのパスは/session/v1で始まります。これは固定の名前であり、バージョンではありません。最初のhelloを除くすべての呼び出しでは、ヘッダーX-Collie-Sessionでバージョンを渡します。リクエストボディは最大64 KiBの1つのJSONオブジェクトであり、空のPOSTボディは{}として読み取られます。

すべてのエラーはcodeを含むJSONボディであり、409 staleや404 no-such-paneなどがあります。その他のパスは404 not-foundを返します。上限を超えた応答は読み取られず、応答が途切れたPOSTの結果は不明になります（リクエストID）。

Helloとエポック

helloはdurable agentの識別情報を表し、エポックはCollieが通信しているインスタンスの起動回次を表します。

Collieはまずバージョンヘッダーを付けずにhelloを呼び出し、双方が対応する最も高いバージョンを選択して、以後のすべての呼び出しでそれを送信します。readyがfalseの間は、hello以外のすべてのルートが503 startingを返し、スマートフォン側ではdurable agentが起動中として表示されます。durable agentは、すべての会話が再表示され、すべての未解決のaskが再提起された後にのみreadyを設定するため、再起動によって中途半端なレイアウトが表示されることはありません。

スナップショットのETagは"<epoch>-<rev>"です。閲覧者に見える変更が発生するたびにrevが増加するため、304の処理コストはdurable agent側でほぼゼロです。新しいepochは、durable agentが再起動したことをCollieに伝えます。Collieは新しいスナップショットを読み取るまで、保持しているペインを表示し続けます。その後、各ペインを以前のカーソルで読み取り、1回の応答でペインの現在のビュー全体を取得します。

読み取りが成功した後に1回失敗した場合、そのポーリングでは最後のスナップショットが維持されます。2回連続で失敗すると、durable agentは到達不能として表示されます。プライバシーチェックに失敗したソケットパスは、直ちに到達不能となります。

AskとAnswer

askは質問カードであり、durable agentのaskイベントからask-closedまで未解決のまま開かれます。

決定後に行われたタップは、最初の結果とともに409 decidedを受け取り、何も実行されません。その後、カードには最初に誰が決定したかが表示されます（「durable agent側で決定済み」、「回答前にタイムアウトしました」、または別のタップの後は「回答済みです。このカードは次回の更新で消去されます。」）。durable agentが認識しなくなったaskは200 too-lateを返します。再起動後にdurable agentが同じIDで再度提起する可能性があるため、カードには「処理されませんでした。質問はすぐに再表示される場合があります。」と表示されます。

askにはpermission、choice、text、formの4種類があります。それぞれ応答の形式が異なり、SDKの質問に記載されています。

リクエストID

スマートフォンからの各操作にはリクエストIDが付与されるため、実行は最大1回に限られます。

スマートフォンはインテントごとに1つのリクエストIDを生成し、CollieはそのIDを渡す前に自身のレシートを書き込みます。durable agentは自エポックの直近500件以上のIDを保持します。完了済みIDの再送にはreplayed: trueを付けて最初の応答が再送され、何も実行されません。同じIDでペイロードが異なる場合は409 request-id-reusedが返されます。

Collieが独自にPOSTを再試行することはありません。タイムアウト、接続切断、または5xxが返されたPOSTの結果は不明となります。その場合、回答用のカードには「Not sure the answer arrived. Try again sends it once more.」と表示されます。「Try again」を押すと同一のリクエストIDが送信され、durable agentのメモリが再試行に応答します。

再試行時にaskがすでに閉じられているかターンが遷移していた場合、最初の試行が成功したかどうかを判断できません。その場合、Collieはスマートフォンに「maybe applied」と応答し、カードには「May already be applied. Check the chat.」と表示され、操作が3回送信されることはありません。

トランスポート

durable agentは、Collieが稼働するマシン上のプライベートソケット、またはトークン認証を伴うTLSのいずれかのトランスポートを使用します。

ルート、ボディ、バージョンヘッダー、ETag、エラーコードなど、送受信されるバイトデータはどちらも同一です。異なるのは、どの主体がdurable agentにアクセスできるかという点のみです。

各タイムアウトは、接続から最後のバイトまでの通信全体に対する期限です。TLS経由の場合、ポーリングはすべてホストの課金対象となる可能性があり、これには304も含まれます。

制限事項

Collieはこれらの制限を超えたものを切断または拒否するため、制限内に収まっているdurable agentでデータが失われることはありません。

制限長を超えた文字列は切り詰められ、制御文字や不可視文字は削除されます。制限数を超えたリストは先頭のエントリが保持されます。制限サイズを超えた履歴ページは一切読み込まれません。

バージョンと情報通知用hello

現在の通信プロトコルバージョンは1のみであり、Collieは1..1を使用します。

バージョン2のリリース後、Collieは1マイナーリリースの間バージョン1を受け付け、その次のマイナーリリースでサポートを終了します。リーダーは未知のフィールド、イベント種別、アイテム種別、コードを無視します。expiresAtやdecidedByなど、バージョン1内で追加されたフィールドは任意です。新しい必須フィールド、既存フィールドの意味変更、フィールドの削除には新しいバージョンが必要です。

スマートフォンが認識できない種類の問い合わせは、端末から回答できないものとしてボタンなしで表示されます。

2つの範囲が重複しない場合、Collieはdurable agentからの読み込みを停止します。durable agentのエポックごとに1回だけ、Collieは自身のバージョンを含めてhelloを再度送信し、durable agent側で不整合をログに記録できるようにします。durable agentは両方の範囲を指定したrefusalとともに409 incompatibleを返します。これが通知用hello（telling hello）です。

Collieは拒絶した範囲ごとにログへ1行出力し、collie doctorに両方の範囲を表示します。スマートフォンのdurable agent画面にも同様のメッセージ（例:「The durable agent speaks wire v2, this Collie speaks v1. Update Collie, or the agent's SDK.」）が表示されます。古い側を更新してください。

詳細な仕様の記載場所

WIRE.mdがコントラクトであり、すべての形状、コード、ルールを定義しています。

その背景にある設計判断は、リポジトリ内のレコードに記載されています。