Remote Editor プロトコル v1
最終更新日: 2026年7月9日
Arshes アプリと Remote Editor サーバーの間の通信プロトコルです。
用語
| 用語 | 説明 |
|---|---|
| Arshes アプリ | iOS / Android クライアント。シェーダーをコンパイルして描画します。 |
| サーバー | Remote Editor サーバー。Arshes アプリにシェーダーのコンパイルを要求し、結果を受け取ります。 |
トランスポート
Arshes アプリは WebSocket (RFC 6455) でサーバーに接続します。スキームは ws://(暗号化なし)と wss://(TLS)の両方に対応しています。
接続
エンドポイント
Arshes アプリは次のエンドポイントに接続します。
ws(s)://{host}:{port}/
| パラメータ | 説明 |
|---|---|
host |
サーバーのホスト名または IP アドレス |
port |
ポート番号(デフォルト: 10080) |
切断
どちらの側からも、WebSocket の close フレームを送って切断できます。Arshes アプリはいつでも切断することがあります(ユーザーが画面を離れたときや、iOS でアプリがバックグラウンドに入ったときなど)。
再接続
切断のあと、Arshes アプリはいつでも再接続することがあります(フォアグラウンドに戻ったときなど)。新しい接続はそのつど新しいセッションとして扱われ、アプリはハンドシェイクを最初からやり直します。
メッセージの形式
すべてのメッセージは、WebSocket のテキストフレームで JSON として送受信します。
{
"type": "<message type>",
"payload": { ... }
}
メッセージ
hello(Arshes アプリ → サーバー)
認証とプロトコルバージョンの合意を開始します。接続後に最初に送るメッセージでなければなりません。
{
"type": "hello",
"payload": {
"protocolVersion": 1,
"token": "<auth token>"
}
}
| フィールド | 型 | 説明 |
|---|---|---|
protocolVersion |
int | プロトコルバージョン |
token |
string | 認証トークン。トークンの入手方法はこのプロトコルの範囲外です(運用形態によります)。 |
helloResult(サーバー → Arshes アプリ)
ハンドシェイクの結果を返します。
成功時:
{
"type": "helloResult",
"payload": {
"code": "ok",
"protocolVersion": 1
}
}
失敗時:
{
"type": "helloResult",
"payload": {
"code": "unauthorized",
"message": "Invalid authentication token"
}
}
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
code |
string | 必須 | 結果コード |
protocolVersion |
int | 任意 | サーバーが採用したプロトコルバージョン。成功時にだけ含まれます。 |
message |
string | 任意 | 人が読むためのエラーの説明。失敗時にだけ含まれます。 |
結果コード:
| コード | 説明 |
|---|---|
ok |
ハンドシェイクに成功した |
unauthorized |
認証トークンが無効、または指定されていない |
unsupported_version |
要求されたプロトコルバージョンにサーバーが対応していない |
- 失敗時、サーバーは
helloResultを送ったあとに接続を閉じます。 - 確立済みの接続では再認証を行いません。
- 再接続時、Arshes アプリは
helloをもう一度送ります。
compileShader(サーバー → Arshes アプリ)
シェーダーのコンパイルを要求します。
{
"type": "compileShader",
"payload": {
"code": "<Slang shader code>",
"image": true
}
}
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
code |
string | 必須 | Slang シェーダーのソースコード |
image |
bool | 任意 | true のとき、Arshes アプリは描画結果の画像を compileResult に含めます。デフォルトは false です。 |
このメッセージを受け取ると、Arshes アプリはシェーダーをコンパイルし、結果を compileResult で返します。
compileResult(Arshes アプリ → サーバー)
シェーダーのコンパイル結果を返します。
{
"type": "compileResult",
"payload": {
"success": true,
"errorMessage": null,
"image": "<base64-encoded JPEG image>"
}
}
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
success |
bool | 必須 | コンパイルに成功した場合は true |
errorMessage |
string | 任意 | コンパイルエラーのメッセージ。失敗時にだけ含まれます。 |
image |
string | 任意 | 描画結果の JPEG を Base64 でエンコードしたもの。成功時で、かつ compileShader.image で要求された場合にだけ含まれます。 |
sendShader(Arshes アプリ → サーバー)
Arshes アプリからサーバーへ、現在のシェーダーコードを送ります。
{
"type": "sendShader",
"payload": {
"code": "<Slang shader code>"
}
}
| フィールド | 型 | 説明 |
|---|---|---|
code |
string | 現在編集中の Slang シェーダーコード |
syncShaderSpec(Arshes アプリ → サーバー)
シェーダー API の仕様をサーバーに送ります。ハンドシェイクの成功(code: "ok" の helloResult)のあとに送らなければなりません。
{
"type": "syncShaderSpec",
"payload": {
"entryPoints": [
{ "name": "...", "description": "...", "code": "..." }
],
"uniforms": [
{ "name": "...", "description": "...", "code": "..." }
],
"attributes": [
{ "description": "...", "code": "...", "format": "..." }
]
}
}
| フィールド | 型 | 説明 |
|---|---|---|
entryPoints |
EntryPoint[] | シェーダーのエントリポイント(fragment, vertex, compute) |
uniforms |
Uniform[] | 利用できる uniform 変数 |
attributes |
Attribute[] | 利用できるシェーダー属性 |
EntryPoint: { name: string, description: string, code: string }
Uniform: { name: string, description: string, code: string }
Attribute: { description: string, code: string, format: string }
シーケンス
ハンドシェイクと初回同期
Arshes app Server
| |
|--- WebSocket connect ------->|
|<-- connection established ---|
| |
|--- hello ------------------->|
|<-- helloResult --------------|
| |
|--- syncShaderSpec ---------->| (required)
| |
シェーダーのコンパイル
Server Arshes app
| |
|--- compileShader ----------->|
| |-- compile
| |
|<-- compileResult ------------|
| |
Arshes アプリからのシェーダー送信
Arshes app Server
| |
|--- sendShader -------------->| (user action)
| |
実装例
arshes-cli は、このプロトコルに準拠したコマンドラインの Remote Editor サーバーです。独自のサーバーを実装するときの参考にしてください。