XRPC

XRPC は、汎用のサーバー間メッセージング プロトコルです。 AT プロトコルのために作成されましたが、複数のユースケースに適用できる (ATP 固有のセマンティクスを含まない) 汎用通信レイヤーです。 リポジトリ データレイヤーとソーシャル アプリケーションは、XRPC 上のレイヤーとして動作します。

code: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 認証

スキーマのバージョン管理と拡張性

仕様

XRPC は、HTTP/S を介したクライアントからサーバーへのメッセージングおよびサーバーからサーバーへのメッセージングをサポートします。 各ユーザーには、ネットワーク内でエージェントとして機能する「Personal Data Server (PDS)」を持っており、通信の大部分 (すべてではないにしても) は PDS を介してルーティングされることを意味します。

code: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の例:

code:js

com.example.status()

io.social.getFeed()

net.users.bob.ping()

メソッドスキーマ

スキーマの配布

メソッド スキーマは、機械で読み取り可能で、ネットワークからアクセスできるように設計されています。 スキーマがネットワーク上で利用可能であることは現在のところ必須ではありませんが、メソッドの消費者が単一の正規の信頼できる表現を利用できるように、スキーマを公開することを強くお勧めします。

組み込みメソッド

getSchema

TODO

Requests

HTTP メソッド

使用される HTTP メソッドは、メソッド スキーマで指定されたタイプに依存します。

table:type

Type Method

Path

パラメータ（メソッドスキーマで指定されたもの）は、クエリパラメータとしてエンコードされます。値は、擬似JavaScriptで以下のアルゴリズムを使ってエンコードする必要があります：

code:js

function encodeParam (paramType, value) {

if (paramType === 'boolean') {

return value ? 'true' : 'false'

} else {

return encodeURIComponent(value)

}

}

メソッドスキーマでデフォルト値が指定されている場合は、一貫したキャッシュ動作を保証するために、リクエストにその値を含める必要があります。

Headers

table:headers

Header 用途

Responses

レスポンスタイプは、HTTPステータスコードによって識別されます。

リクエストは成功しました。期待:

レスポンスbodyはメソッドのインターフェイスによって異なります。

リクエストは無効であり、処理されませんでした。

認証がなければ、リクエストは処理できません。 期待:

ユーザーがメソッドにアクセスするために必要な権限が不足している。

404応答の解釈は、XRPCに固有のものです。404は、サーバが指定された場所(/xrpc)でリソースを提供していないことを示します。これは、サーバがXRPCをサポートしていないことを意味します。

リクエストのペイロードが、サーバーが処理しようとしているサイズを超えています。 ペイロードのサイズ制限は、各サーバーによって決定されます。

クライアントが送信したリクエストが多すぎます。 レート制限は、各サーバーによって決定されます。 期待:

処理中にサーバーが予期しない状態になりました。

サーバーは要求されたメソッドを実装していません。

プロシージャ(手順)の実行は、失敗した他のサーバーへの呼び出しに依存しています。

サーバーの負荷が高く、リクエストを完了することができません。

プロシージャの実行は、タイムアウトした別のサーバーへの呼び出しに依存しています。

残りのコード

明示的に列挙されていない応答コードは、次のように処理する必要があります。

Authentication

TODO

カスタムエラーコードと説明

200 以外 (エラー) の応答では、サービスは次のスキーマに一致する JSON 本文で応答する場合があります。

code: ts

interface XrpcErrorDescription {

error?: string

message?: string

}