# モード機能

## 概要

モード機能 は、指定されているモードごとに Sora の挙動を変更する機能です。

## 目的

Sora 自体は認証の機能を持っていないため、メンテナンス時に一時的に接続をブロックするといった仕組みがありません。
接続をブロックする場合は、認証サーバー側で処理をすることになり不便でした。

そこで、Sora 側にモード機能を持たせることで、モードを切り替えることで接続を気軽にブロックできる機能を追加します。

## モード

### ノーマルモード

このモードは何もせず、すべての新規接続を受け入れます。


### 新規コネクションブロックモード

このモードは新規の接続をブロックします。すでに接続しているコネクションはそのままです。


### 新規セッションブロックモード

このモードは新規セッションの作成をブロックします。すでに接続しているセッションやコネクションはそのままです。

そのためセッション(チャネルに 1 人以上接続しているアクティブな状態)が存在する場合は接続できますが、セッションが存在しない場合は新規の接続をブロックします。

## API

### ChangeMode API

モード変更 API です。指定するモードには 3 種類あります。

- normal
- block_new_session
- block_new_connection

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000 \
    -H "x-sora-target: Sora_20211215.ChangeMode" \
    --json '{"mode":"block_new_session"}' \
    | jq .
{
    "mode": "block_new_session"
}
```

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000 \
    -H "x-sora-target: Sora_20211215.ChangeMode" \
    --json '{"mode":"block_new_connection"}' \
    | jq .
{
    "mode": "block_new_connection"
}
```

詳細は [ChangeMode](API_MODE.html#3af05f) をご確認ください。

### GetMode API

モード取得 API です。

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000 \
    -H "x-sora-target: Sora_20211215.GetMode" \
    | jq .
{
    "mode": "normal"
}
```

詳細は [GetMode](API_MODE.html#c0c2e7) をご確認ください。

## クラスター機能

### チャネル ID のノード割り当て

クラスター機能を利用した場合、
`mode` が [新規セッションブロックモード](MODE.html#041e1c) または [新規コネクションブロックモード](MODE.html#0b67d3) のノードに対して、
新規のチャネル ID を割り当てません。

## シーケンス図

### block_new_connection

```mermaid
sequenceDiagram
    participant C1 as クライアント1
    participant C2 as クライアント2
    participant S as Sora
    participant A as アプリケーションサーバー
    note over S: Sora 起動
    note over S: モード: normal
    C1->>S: "type": "connect"
    note over C1,S: クライアント1 WebRTC 確立

    A->>S: ChangeMode API<br/>mode=block_new_connection
    note over S: モード: block_new_connection
    break 接続失敗
        C2->>S: "type": "connect"
    end

    A->>S: ChangeMode API<br/>mode=normal
    note over S: モード: normal
    C2->>S: "type": "connect"
    note over C2,S: クライアント2 WebRTC 確立
```

### block_new_session

```mermaid
sequenceDiagram
    participant C1 as クライアント1
    participant C2 as クライアント2
    participant C3 as クライアント3
    participant S as Sora
    participant A as アプリケーションサーバー
    note over S: Sora 起動
    note over S: モード: normal
    C1->>S: "type": "connect"<br/>channel_id=spam
    note over C1,S: クライアント1 WebRTC 確立

    A->>S: ChangeMode API<br/>mode=block_new_session
    note over S: モード: block_new_session
    break 接続失敗
        C2->>S: "type": "connect"<br/>channel_id=ham
    end
    C3->>S: "type": "connect"<br/>channel_id=spam
    note over C3,S: クライアント3 WebRTC 確立
```