# RPC 機能

*バージョン 2025.2.0 で追加。*

> **警告**
>
> この機能は [実験的機能](EXPERIMENTAL.html) のため、正式版では仕様が変更される可能性があります

## 概要

Sora では、 [DataChannel 経由のシグナリング](DATA_CHANNEL_SIGNALING.html) 利用時に、 JSON-RPC 2.0 over DataChannel で一部の HTTP API をクライアントから直接呼び出すことができます。

この RPC 機能を利用することで、アプリケーションサーバー経由で Sora の HTTP API を呼び出す場合と比べて、より低遅延に同等の操作を行えます。


## RPC 機能を利用する条件

- `sora.conf` で [data_channel_rpc](SORA_CONF.html#26f332) が `true` に設定されていること
- コネクションが [DataChannel 経由のシグナリング](DATA_CHANNEL_SIGNALING.html) を利用していること
- 認証成功時に [rpc_methods の払い出し](AUTH_WEBHOOK_RETURN.html#a2e307) で利用できる RPC メソッド名一覧が払い出されていること

## JSON-RPC 2.0 仕様

- JSON-RPC 2.0 の仕様に準拠しています
- `method` には HTTP API で指定するヘッダー名とは異なる形式で指定する必要があります- `2025.2.0/RequestSimulcastRid` のように `{RPC 経由での HTTP API の呼出が導入された Sora のバージョン}/{HTTP API 名}` の形式で指定します
- `params` には HTTP API 利用時の JSON を指定します- `params` に不要な項目が含まれている場合はエラーになります
  - `channel_id` と `connection_id` は Sora 側で現在接続しているコネクションの値を利用するため指定不要です
  - `receiver_connection_id` も同様に Sora 側で現在接続しているコネクションの値を利用するため指定不要です
- `id` を付けないことでレスポンスを返さない `Notification` として利用できます- これは Sora 側がレスポンスを返さないことを意味します

### RPC の型定義

```typescript
/* 
data_channel_rpc = true の場合に送信される RPC の型定義
JSON-RPC 2.0 準拠
https://www.jsonrpc.org/specification
DataChannel シグナリング
label: "rpc"
*/

// 2025.2.0 以降で利用可能な RPC メソッド
type rpcMethod =
  | "2025.2.0/RequestSimulcastRid"
  | "2025.2.0/RequestSpotlightRid"
  | "2025.2.0/ResetSpotlightRid"
  | "2025.2.0/PutSignalingNotifyMetadata"
  | "2025.2.0/PutSignalingNotifyMetadataItem";

type JSONRPCRequest = {
  jsonrpc: "2.0";
  // null 非推奨
  id?: number | string;
  method: rpcMethod;
  params?: Record<string, unknown> | unknown[];
};

type JSONRPCSuccess = {
  jsonrpc: "2.0";
  id: number | string;
  result: unknown;
};

// 予約済みエラーコード
type JSONRPCErrorCode =
  // JSON パースエラー
  | -32700
  // 不正なリクエスト
  | -32600
  // メソッドが見つからない
  | -32601
  // 不正なパラメータ
  | -32602
  // 内部エラー
  | -32603
  // -32000 ~ -32099: サーバーエラー、その他: アプリケーション定義
  | number;

type JSONRPCError = {
  jsonrpc: "2.0";
  id: number | string | null;
  error: {
    code: number;
    message: string;
    data?: unknown;
  };
};
```

## メソッド一覧

> **注釈**
>
> method は `{RPC 経由での HTTP API の呼出が導入された Sora のバージョン}/{HTTP API 名}` という形式になります。


### 2025.2.0/RequestSimulcastRid

[RequestSimulcastRid](API_SIMULCAST.html#7d26ab) API

```javascript
{
   "jsonrpc": "2.0",
   "method": "2025.2.0/RequestSimulcastRid",
   "params": {
      "sender_connection_id": "example_sender_connection_id",
      "rid": "r1"
   },
   "id": 1
}
```

`channel_id` と `receiver_connection_id` は Sora 側で設定するため指定不要です。また `sender_connection_id` はオプションです。

このメソッドを利用するには認証時の払い出しで `simulcast` と `simulcast_rpc_rids` を指定する必要があります。 RPC 経由で切り替えられる `rid` を `simulcast_rpc_rids` で指定してください。

```javascript
{
  "allowed": true,
  "simulcast": true,
  "simulcast_rpc_rids": ["none", "r0", "r1"],
  "rpc_methods": [
     "2025.2.0/RequestSimulcastRid"
  ]
}
```


### 2025.2.0/RequestSpotlightRid

[RequestSpotlightRid](API_SPOTLIGHT.html#5c2650) API

```javascript
{
   "jsonrpc": "2.0",
   "method": "2025.2.0/RequestSpotlightRid",
   "params": {
      "send_connection_id": "example_send_connection_id",
      "spotlight_focus_rid": "r1",
      "spotlight_unfocus_rid": "none"
   },
   "id": 1
}
```

`channel_id` と `recv_connection_id` は Sora 側で設定するため指定不要です。また `send_connection_id` はオプションです。


### 2025.2.0/ResetSpotlightRid

[ResetSpotlightRid](API_SPOTLIGHT.html#680344) API

```javascript
{
   "jsonrpc": "2.0",
   "method": "2025.2.0/ResetSpotlightRid",
   "params": {
      "send_connection_id": "example_send_connection_id"
   },
   "id": 1
}
```

`channel_id` と `recv_connection_id` は Sora 側で設定するため指定不要です。また `send_connection_id` はオプションです。


### 2025.2.0/PutSignalingNotifyMetadata

[PutSignalingNotifyMetadata](API_SIGNALING_NOTIFY_METADATA_EXT.html#a20c95) API

```javascript
{
  "jsonrpc": "2.0",
  "method": "2025.2.0/PutSignalingNotifyMetadata",
  "params": {
    "push": true,
    "metadata": {
      "example_key_1": "example_value_1",
      "example_key_2": "example_value_2"
    }
  },
  "id": 1
}
```

`channel_id` と `connection_id` は Sora 側で設定するため指定不要です。また、 `push` はオプションです。


### 2025.2.0/PutSignalingNotifyMetadataItem

[PutSignalingNotifyMetadataItem](API_SIGNALING_NOTIFY_METADATA_EXT.html#387c9c) API

```javascript
{
  "jsonrpc": "2.0",
  "method": "2025.2.0/PutSignalingNotifyMetadataItem",
  "params": {
     "push": true,
     "key": "example_key",
     "value": "example_value"
  },
  "id": 1
}
```

`channel_id` と `connection_id` は Sora 側で設定するため指定不要です。また、 `push` はオプションです。

## 利用できる RPC の指定

この機能を利用するには認証時の払い出しで RPC 機能で利用できるメソッド一覧を指定する必要があります。

```javascript
{
  "allowed": true,
  "rpc_methods": [
     "2025.2.0/RequestSpotlightRid",
     "2025.2.0/ResetSpotlightRid"
  ]
}
```

## "type": "offer" シグナリングメッセージでの確認

クライアントから利用できる RPC メソッド一覧は `"type": "offer"` のシグナリングメッセージの `rpc_methods` で確認することができます。

```javascript
{
  "type": "offer",
  "rpc_methods": [
     "2025.2.0/RequestSpotlightRid",
     "2025.2.0/ResetSpotlightRid"
  ]
}
```

## シーケンス図

```mermaid
sequenceDiagram
   participant C1 as Client1
   participant C2 as Client2
   participant S as Sora
   note over C1,S: C1, C2 共にWebRTC 確立済み
   C1 ->> S: JSON-RPC 2.0 Request<br>PutSignalingNotifyMetadataItem<br>push: true<br>over DataChannel
   note over S: シグナリング通知メタデータ拡張に項目を追加
   S ->> C1: JSON-RPC 2.0 Success Response<br>over DataChannel
   note over S: シグナリング通知メタデータ拡張によるプッシュ通知が発生
   S ->> C1: type: push<br>over DataChannel
   S ->> C2: type: push<br>over DataChannel
```