XRPC
XRPC は、汎用のサーバー間メッセージング プロトコルです。 AT プロトコルのために作成されましたが、複数のユースケースに適用できる (ATP 固有のセマンティクスを含まない) 汎用通信レイヤーです。 リポジトリ データレイヤーとソーシャル アプリケーションは、XRPC 上のレイヤーとして動作します。
code┌─────────────────────┐
│ Social Applications │ Application semantics
└─┰──────────┰────────┘
┃ ┃
┃ ┌───────▽────────┐
┃ │ Repositories │ Block & record storage
┃ └───────┰────────┘
┃ ┃
┌─▽──────────▽────────┐
│ XRPC │ Wire protocol
└─────────────────────┘
特徴
コントラクト指向。XRPCのすべての「メソッド」は、受け入れられる入力と出力を定義するスキーマによって宣言されます。スキーマはグローバルに識別され、機械可読のドキュメントとして公開されます。これにより、サービスのオープンネットワークにおける正しさと一貫性を確保することができます。
HTTPベース。XRPCのメソッドは、動作に応じてGETまたはPOSTメソッドを使用し、HTTP/Sを使用して転送されます。これにより、XRPCは理解しやすく、既存の技術スタックに簡単に統合できます。
キャッシュ可能。 XRPC の "query" メソッドは、一般的な HTTP ベースのキャッシュ技術でうまくキャッシュできるように設計されています。
複数のエンコーディングのサポート。 XRPC は、構造化データ (JSON) と非構造化バイナリ BLOB をサポートしています。
TODO
Authentication 認証
スキーマのバージョン管理と拡張性
getSchema の定義
仕様
XRPC は、HTTP/S を介したクライアントからサーバーへのメッセージングおよびサーバーからサーバーへのメッセージングをサポートします。 各ユーザーには、ネットワーク内でエージェントとして機能する「Personal Data Server (PDS)」を持っており、通信の大部分 (すべてではないにしても) は PDS を介してルーティングされることを意味します。
code┌────────┐ ┌────────┐
│ Server │ ◀──XRPC──▶ │ Server │
└────────┘ └────────┘
▲
│
XRPC
│
▼
┌────────┐
│ Client │
└────────┘
メソッド
XRPC "methods" には次の属性(attributes)があります。
ID: メソッドの入力と出力のためのスキーマのID。
Type: Query (変化しない、キャッシュ可能）または Procedure（変化あり、キャッシュ不可能）。
Parameters: URI query セグメントでエンコードされます。キャッシュに影響する。
Input: The request body.
Output: The response body.
メソッドの呼び出しは、リクエストの ID、パラメーター、入力、および特定の HTTP ヘッダーを指定する必要があります。 同様に、戻り値も HTTP responseに関する何らかの情報を提供しなければなりません。 したがって、XRPC は、API で使用される場合、HTTP のセマンティクスを完全に抽象化するわけではありません。
メソッドID
メソッドIDの例:
jscom.example.status()
io.social.getFeed()
net.users.bob.ping()
メソッドスキーマ
スキーマの配布
メソッド スキーマは、機械で読み取り可能で、ネットワークからアクセスできるように設計されています。 スキーマがネットワーク上で利用可能であることは現在のところ必須ではありませんが、メソッドの消費者が単一の正規の信頼できる表現を利用できるように、スキーマを公開することを強くお勧めします。
スキーマを取得するには、組み込みの getSchema メソッドにリクエストを送信する必要があります。 この要求は、NSID のauthorityに送信されます。
組み込みメソッド
getSchema
TODO
Requests
HTTP メソッド
使用される HTTP メソッドは、メソッド スキーマで指定されたタイプに依存します。
type| Type | Method |
| `query` | `GET` |
| `procedure` | `POST` |
Path
すべてのリクエストは、ターゲットサーバーの /xrpc/{methodId} パスに送信されます。たとえば、 io.social.getFeed メソッドの呼び出しは、 /xrpc/io.social.getFeed パスに送信されることになります。
パラメータ（メソッドスキーマで指定されたもの）は、クエリパラメータとしてエンコードされます。値は、擬似JavaScriptで以下のアルゴリズムを使ってエンコードする必要があります：
jsfunction encodeParam (paramType, value) {
if (paramType === 'boolean') {
return value ? 'true' : 'false'
} else {
return encodeURIComponent(value)
}
}
メソッドスキーマでデフォルト値が指定されている場合は、一貫したキャッシュ動作を保証するために、リクエストにその値を含める必要があります。
Headers
headers| Header | 用途 |
| `Content-Type` | リクエスト本文のエンコーディングが存在する場合は、それを指定する必要があります。 |
| `Authorization` | 認証データがある場合は、それを指定できます。詳しくは、「認証」を参照してください。 |
Responses
レスポンスタイプは、HTTPステータスコードによって識別されます。
200 Request successful リクエスト成功
リクエストは成功しました。期待:
Content-Type ヘッダがセットされていること。
レスポンスbodyはメソッドのインターフェイスによって異なります。
`400' Invalid request 無効なリクエスト
リクエストは無効であり、処理されませんでした。
'401' Authentication required 認証が必要
認証がなければ、リクエストは処理できません。 期待:
WWW-Authenticate ヘッダーに認証チャレンジを設定する必要があります。詳細については、Authentication(認証)を参照してください。
403 Forbidden 禁止
ユーザーがメソッドにアクセスするために必要な権限が不足している。
404 XRPC not supported XRPCはサポートされていません
404応答の解釈は、XRPCに固有のものです。404は、サーバが指定された場所(/xrpc)でリソースを提供していないことを示します。これは、サーバがXRPCをサポートしていないことを意味します。
指定されたプロシージャ(手順)が実装されていないことを示すには、 501 応答を使用します。
413 Payload too large ペイロードが大きすぎる
リクエストのペイロードが、サーバーが処理しようとしているサイズを超えています。 ペイロードのサイズ制限は、各サーバーによって決定されます。
429 Rate limit exceeded レート制限を超過した
クライアントが送信したリクエストが多すぎます。 レート制限は、各サーバーによって決定されます。 期待:
Retry-After ヘッダーには、次のリクエストまでに経過する必要がある時間が表示される場合があります。
500 Internal server error 内部サーバーエラー
処理中にサーバーが予期しない状態になりました。
501 Method not implemented メソッド未実装
サーバーは要求されたメソッドを実装していません。
502 A request to upstream failed 上流へのリクエストに失敗しました
プロシージャ(手順)の実行は、失敗した他のサーバーへの呼び出しに依存しています。
503 Not enough resources 充分なリソースがありません
サーバーの負荷が高く、リクエストを完了することができません。
504 A request to upstream timed out 上流への要求がタイムアウトした
プロシージャの実行は、タイムアウトした別のサーバーへの呼び出しに依存しています。
残りのコード
明示的に列挙されていない応答コードは、次のように処理する必要があります。
1xx は 404 として扱う
2xx は 200 として扱う
3xx は 404 として扱う (リダイレクトはサポートされていません)
4xx は 400 として扱う
5xx は 500 として扱う
Authentication
TODO
カスタムエラーコードと説明
200 以外 (エラー) の応答では、サービスは次のスキーマに一致する JSON 本文で応答する場合があります。
tsinterface XrpcErrorDescription {
error?: string
message?: string
}
応答本文の error フィールドは、メソッドのLexicon スキーマで定義されたエラー名にマップする必要があります。 これにより、クライアント ソフトウェアによるより具体的なエラー処理が可能になります。 これは、詳細な情報が役立つ 400、500、および 502 応答で特に推奨されます。