# マルチ転送フィルター機能

> **注意**
>
> この機能を利用する場合は事前にサポートまでご連絡ください

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

## 概要

マルチ転送フィルター機能は、転送フィルターに名前 (`name`) と優先度 (`priority`) を指定することで、
1 チャネルや 1 コネクションに複数の転送フィルターを設定できる機能です。

## 認証接続時と認証成功時/セッション生成時の払い出しの注意点

- `forwarding_filter` は非推奨となります
- `forwarding_filter` は 2025 年 12 月リリース予定の Sora にて廃止します
- `forwarding_filter` と `forwarding_filters` の両方を指定した場合 `forwarding_filters` が優先されます
- `forwarding_filter` でも `name` と `priority` を指定できます
- `forwarding_filters` で `name` が重複した場合はエラーになります
- `forwarding_filters` で `name` と `priority` が未指定の場合は `default` と `32767` として扱われます- ただし未指定が複数ある場合は `name` の `default` が重複としていると判断されエラーになります

## 仕様

- マルチ転送フィルターは 1 チャネルや 1 コネクションに対して複数の転送フィルターを設定できる機能です
- 複数の転送フィルターを設定する場合は、 `name` と `priority` を指定して転送フィルターを追加します- `name` は既に設定済の転送フィルターと重複することはできません
  - `name` と `priority` のどちらかだけを指定することはできません
- 転送フィルターは転送を判定するタイミングで、指定されている全ての転送フィルターを判定します- ただし判定するタイミングで、優先度が高いものから判定します
- 転送フィルター追加時に名前 (`name`) と優先度 (`priority`) を指定することができます
- 転送フィルター更新時に名前 (`name`) と優先度 (`priority`) を指定することができます
- 転送フィルター削除時に名前 (`name`) を指定して削除することができます
- 名前は任意の文字列 (最大 255 バイト) が指定できます
- 名前は重複できません- `channel_id` または `connection_id` 単位でユニークな名前が必要
  - 名前が重複している場合はエラーになります
- 優先度は 0-32767 (16#7FFF) の間で指定してください
- 優先度が一番高いのは 0 で、数値が大きいほど優先度が低くなります
- 優先度は重複できます- 優先度が同じ場合は `allow` が優先されます
  - `block` のみの場合は OR で判定します
  - `allow` のみの場合は OR で判定します
  - `block` / `block` / `allow` なら `allow` のみで判定します
- `name` と `priority` を指定しない場合はデフォルト値が設定されます- `name` は `"default"` です
  - `priority` は `32767` です

## 性能

1 チャネルや 1 コネクションに対して数千などのフィルターを設定しない限り、性能が劣化することはありません。


## 認証成功時の払い出し

```javascript
forwarding_filters: [
   {
      "name": "client-id-carol-allow",
      "priority": 0,
      "action": "allow",
      "rules": [
         [
            {
               "field": "client_id",
               "operator": "is_in",
               "values": [
                  "carol"
               ]
            }
         ]
      ]
   },
   {
      "name": "default",
      "priority": 32767,
      "action": "block",
      "rules": [
         [
            {
               "field": "kind",
               "operator": "is_in",
               "values": [
                  "audio",
                  "video"
               ]
            }
         ]
      ]
   }
]
```


## セッション生成時の払い出し

```javascript
forwarding_filters: [
   {
      "action": "block",
      "name": "client-id-alice-block",
      "priority": 0,
      "rules": [
         [
            {
               "field": "client_id",
               "operator": "is_in",
               "values": [
                  "alice"
               ]
            }
         ]
      ]
   },
   {
      "action": "block",
      "name": "client-id-bob-block",
      "priority": 0,
      "rules": [
         [
            {
               "field": "client_id",
               "operator": "is_in",
               "values": [
                  "bob"
               ]
            }
         ]
      ]
   },
   {
      "action": "block",
      "name": "default",
      "priority": 32767,
      "rules": [
         [
            {
               "field": "kind",
               "operator": "is_in",
               "values": [
                  "audio"
               ]
            }
         ]
      ]
   }
]
```