# シグナリング通知メタデータ

## 概要

`signaling_notify_metadata` はクライアントの状態が変化したときに送られる、シグナリング通知に含まれるメタデータです。

シグナリング接続時、または認証ウェブフック成功の戻り値に `signaling_notify_metadata` で JSON 値を指定することで利用できるようになります。

新しく参加した際に、すでにそのチャネルに参加しているクライアントの `signaling_notify_metadata` の値がリストで共有されます。

## 注意

### シグナリング通知メタデータの認証成功時払い出しによる上書き

接続時に指定したシグナリング通知メタデータは、認証成功時に `signaling_notify_metadata` の払い出しによって上書きされます。

詳細は [接続時のシグナリング通知メタデータを認証払い出し時のシグナリング通知メタデータで上書き](SIGNALING_NOTIFY_METADATA.html#2f3416) をご確認ください。

### シグナリング通知メタデータ拡張

[シグナリング通知メタデータ拡張機能](SIGNALING_NOTIFY_METADATA_EXT.html) を有効にしている場合、
`metadata` はシグナリング通知メタデータ拡張で利用されるため、
`signaling_notify_metadata` で指定した値は `metadata` には含まれません。

- 接続時に指定したシグナリング通知メタデータは `authn_metadata` として含まれます
- 認証成功時に払い出したシグナリング通知メタデータは `authz_metadata` として含まれます

## 設定

`sora.conf` で [signaling_notify_metadata](SORA_CONF.html#2d9340) を `false` を指定することで、
シグナリング通知時に `metadata` や `authn_metadata` や `authz_metadata` を含まなくなります。

設定を行ったときの出力例は [sora.conf の設定内容と connection.created 出力の例](SIGNALING_NOTIFY.html#2729eb) をご確認ください。

## シグナリング接続時での指定

`"type": "connect"` 接続時に `signaling_notify_metadata` で JSON 値を指定できます。

```javascript
{
  "type": "connect",
  "role": "sendrecv",
  "channel_id": "sora",
  "signaling_notify_metadata": {"authn": true}
}
```

シグナリング接続時に指定した値は、通知時に `metadata` として通知されます。
また `authn_metadata` としても通知されます。

`"data"` にはすでにそのチャネルに参加しているクライアントの情報がリストで含まれます。

```javascript
{
  "type": "notify",
  "event_type": "connection.created",
  "authn_metadata": {"authn": true},
  "metadata": {"authn": true},
  "data": [
    {
      "connection_id": "KKBFZTQXDD6H7FD2NYCQX8S474",
      "authz_metadata": "xyz",
      "metadata": "xyz"
    },
    {
      "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
      "authn_metadata": 10,
      "metadata": 10
    }
  ]
}
```

### シグナリング接続時に指定できるシグナリング通知メタデータのサイズ制限

> **重要**
>
> シグナリング接続時に指定できるシグナリング通知メタデータのサイズのデフォルトは 64 KiB (65536 バイト) です。

メタデータのサイズはエンコード済みの JSON 、つまり文字列としてサイズを計算します。

例えば `{"a":"b"}` の場合は 9 バイトで、 `{"a":"b","c":1200}` は 18 バイトです。

最大値を変更したい場合は `sora.conf` の [signaling_notify_authn_metadata_max_size](SORA_CONF.html#a8c147) を変更してください。

また、シグナリング通知メタデータを接続時に指定できなくする場合は [signaling_notify_authn_metadata_max_size](SORA_CONF.html#a8c147) を `0` にしてください。

## 認証ウェブフックの戻り値での指定

認証ウェブフックでの戻り値は、シグナリング接続時に指定した値を上書きします。

```javascript
{
  "allowed": true,
  "signaling_notify_metadata": "authz"
}
```

認証ウェブフックの戻り値で指定した値は、通知時に `metadata` としても通知されます。
また `authz_metadata` としても通知されます。

`"data"` にはすでにそのチャネルに参加しているクライアントの情報がリストで含まれます。

```javascript
{
  "type": "notify",
  "event_type": "connection.created",
  "authn_metadata": "authz",
  "metadata": "authz",
  "data": [
    {
      "connection_id": "KKBFZTQXDD6H7FD2NYCQX8S474",
      "authz_metadata": "xyz",
      "metadata": "xyz"
    },
    {
      "connection_id": "4D40YWH56N5S99QHJV6GAPNHB0",
      "authn_metadata": 10,
      "metadata": 10
    }
  ]
}
```

すでに参加しており、他のクライアントが参加してきた場合や離脱した場合は以下の通りになります。

```javascript
{
  "type": "notify",
  "authz_metadata": {"username": "alice"},
  "metadata": {"username": "alice"}
}
```

### 認証成功時払い出しのシグナリング通知メタデータのサイズ制限

制限はありません。


## 接続時のシグナリング通知メタデータを認証払い出し時のシグナリング通知メタデータで上書き

接続時に指定したシグナリング通知メタデータは、
認証成功時の払い出しのシグナリング通知メタデータで上書きされます。

### 接続時に指定したシグナリング通知メタデータ

接続時に指定したシグナリング通知メタデータを `"authn"` と指定しています。

```javascript
{
  "type": "connect",
  "role": "sendrecv",
  "channel_id": "sora",
  "signaling_notify_metadata": {"authn": true}
}
```

### 認証成功時に払い出したシグナリング通知メタデータ

認証成功時にシグナリング通知メタデータを `"authz"` と払い出しています。

```javascript
{
  "allowed": true,
  "signaling_notify_metadata": "authz"
}
```

### クライアントへ送られるシグナリング通知メタデータ

認証成功時に払い出したシグナリング通知メタデータである `"authz"` が `metadata` として通知されます。

```javascript
{
  "type": "notify",
  "event_type": "connection.created",
  "authn_metadata": {"authn": true},
  "authz_metadata": "authz",
  "metadata": "authz",
  "data": []
}
```