
# Phoenix Channels クライアント

[Phoenix Channels](https://hexdocs.pm/phoenix/channels.html) は、Phoenix (Elixir) サーバーと、Supabase Realtime のようにその上に作られたサービスのリアルタイムプロトコルです。一つの WebSocket 接続の上に、多数の*トピック*を載せます。クライアントはトピック (`room:42`) に参加し、サーバーがそこに送るイベントを受け取り、自分のイベントをプッシュします。プッシュにはそれぞれ応答が返ります。スターターはこれをクライアントとして話します。`@PhoenixChannel` のインターフェースは、[`@WebSocketClient`](clients.md) と同じように宣言します。

## 使う理由

このプロトコルは、WebSocket の上に、すべてのメッセージを包むエンベロープ、参照でプッシュに対応付けられる応答、ハートビート、そして再接続のたびにすべてのトピックへの新しい参加を必要とします。手で書くと、トピックごとの状態機械になります。スターターがそれを持ちます。ストリームを購読するとトピックに参加し、アプリケーションが見るのはストリームと Future です。

## 例

```dart
@PhoenixChannel('chat', topic: 'room:{id}', url: r'${chat.url}')
abstract interface class Room {
  @OnEvent('new_msg')
  Stream<ChatMessage> messages(String id);

  @Push('new_msg')
  Future<Ack> send(String id, ChatMessage message);

  @Push('typing', reply: false)
  Future<void> typing(String id);

  Future<void> leave(String id);
}

@Service()
class Chat {
  Chat(this.room);            // the generated bean

  final Room room;

  // Listening joins room:42; it stays joined while someone listens.
  void open() => room.messages('42').listen(show);

  Future<Ack> say(String text) =>
      room.send('42', ChatMessage(from: 'me', text: text));
}
```

```properties
# lib/resources/application.properties: the socket's WebSocket endpoint, "/websocket" included.
chat.url=wss://chat.neon.books/socket/websocket
```

## メソッド

`@PhoenixChannel(name, topic:, url:, vsn:)`: `name` はクライアントの名前で、その設定 (`spring.websocket.client.config.<name>.*`) に使われます。`url` は、ソケットの WebSocket エンドポイントのアドレスで、`/websocket` を含みます。指定すると設定の `url` より優先され、どちらもなければ起動が失敗します。

| メソッド | すること |
|---|---|
| `@OnEvent('name') Stream<T> name(...)` | トピック上のその名前のイベント。すでに `T` であるペイロード (`String`、`Map<String, Object?>`) はそのまま渡され、それ以外の型は JSON として読まれる。読めないペイロードはエラーイベント (`MessageConversionException`) として届き、ストリームは続く。購読するとトピックに参加する。 |
| `@Push('name') Future<T> name(..., payload)` | イベントをプッシュする。必要なら先にトピックに参加し、サーバーの応答のレスポンスを `T` として読んで完了する。`Future<void>` は応答を待ち、そのレスポンスを無視する。トピックのパラメーター以外のパラメーターは一つまで。それがペイロードで、JSON として書かれる (なければ `{}`)。 |
| `@Push('name', reply: false) Future<void> name(...)` | サーバーが応答しないイベントについて同じ。送られた時点で完了する。 |
| `Future<void> leave(...)` | 任意。今すぐトピックを離れる。そのストリームは完了する。 |

プッシュは、`error` の応答では `PhoenixPushException` で失敗し (その `reply.response` が理由を示す)、`phoenix.push-timeout` 以内に応答がなければ `TimeoutException` で、トピックに参加できなければ `PhoenixJoinException` で失敗します。

それ以外のメソッドは、インターフェースのすべての問題を一つのメッセージに示して、起動時にアプリケーションを止めます。URL がない、または誤っている場合、未知の `vsn`、トピックが名指しするパラメーターのないメソッドも同じです。

## トピックと接続

- **トピック。** トピックの中の `{name}` は、呼び出されたメソッドの同じ名前のパラメーターで埋められます。そのため、一つのインターフェースがすべての部屋に使えます。`{name}` のないトピックにパラメーターは要りません。トピックと URL の中の `${...}` は、起動時に `Environment` から解決されます。
- **一つのトピックに一つのチャンネル:** 最初の購読者かプッシュで参加し、最後の購読者がキャンセルするか `leave` が呼ばれると離脱します。プッシュだけされたトピックは、`leave` まで参加したままです。
- **接続は一つ。** 同じ名前とアドレスのインターフェースは、ソケットを共有します。最初のトピックに参加するときに接続し、最後のトピックが離脱したとき、そしてアプリケーションが停止したときに閉じます。
- **再接続。** 失われた接続は、`@WebSocketClient` と同じように再び開かれます (`reconnect.*`)。その後、すべてのトピックが新しい参加ペイロードで参加し直し、ストリームは続きます。サーバーがチャンネルのクラッシュを報告したとき (`phx_error`) も同じです。
- **拒否された参加。** サーバーが拒否した、または応答しなかった参加は、ストリームのエラーイベント (`PhoenixJoinException`) になり、誰かが購読している間、`reconnect.*` の待機で再試行されます。
- **ハートビート。** ソケットは `phoenix.heartbeat-interval` ごとにハートビートを送ります。次のハートビートまでに応答がなければ接続を切り、その後、再び開きます。
- **終わるとき。** サーバーが完全に閉じた接続 (正常なクローズ、再試行されないコード、`reconnect.max-retries` に達した) は、ストリームを終わらせます。次の購読者が、もう一度始めます。

## 参加ペイロード

参加が送るものは、二つの場所から来ます。`@JoinPayload()` の付いたパラメーターは、どのメソッドにあっても、その呼び出しがトピックに参加するときに使われます。すでに参加しているトピックへの呼び出しは、それを無視します。そして、すべての `PhoenixJoinInterceptor` の Bean は、再接続の後のものも含めて、すべての参加のペイロードを変更できます。トークンはこうして加えます。

```dart
@OnEvent('new_msg')
Stream<ChatMessage> messagesSince(String id, @JoinPayload() RoomJoin join);

// The rooms want the user's current token when joined.
@Component()
class RoomAuth implements PhoenixJoinInterceptor {
  RoomAuth(this.tokens);

  final TokenStore tokens;

  @override
  Future<void> apply(PhoenixJoin join) async {
    if (join.topic.startsWith('room:')) {      // join.clientName: 'chat'
      join.payload['token'] = await tokens.current();
    }
  }
}
```

サーバーがソケットの URL の中にトークンを求める場合は、他のクライアントと同じく、[ハンドシェイクのインターセプター](client-configuration.md)が加えます。

## コードで: PhoenixSocket

インターフェースは、ライブラリが直接使える層の上にあります。`PhoenixSocketFactory` の Bean は、クライアント名のソケットを返します (名前とアドレスごとに一つで、アプリケーションが停止すると閉じられます)。ソケットは、トピックごとのチャンネルを返します。

```dart
@Service()
class Presence {
  Presence(PhoenixSocketFactory sockets, this.tokens)
    : _socket = sockets.socket(
        'chat',                                 // ...config.chat.url
        parameters: () async => {'token': await tokens.current()},
      );

  final TokenStore tokens;
  final PhoenixSocket _socket;

  Future<void> watch() async {
    final lobby = _socket.channel(
      'lobby',
      payload: () => {'user': 'ann'},           // asked at every join
    );
    lobby.on('presence_diff').listen(update);   // or lobby.messages
    lobby.states.listen(show);                  // joining, joined, errored...
    await lobby.join();                         // the reply's response
    final reply = await lobby.push('status', {'text': 'here'});
    await lobby.send('typing');                 // no reply awaited
    await lobby.leave();
  }
}
```

| `PhoenixChannelSession` | 意味 |
|---|---|
| `join()` | 参加し、参加の応答のレスポンスで完了する。拒否やタイムアウトでは `PhoenixJoinException`。 |
| `push(event, [payload])` | プッシュし、`PhoenixReply` で完了する。 |
| `send(event, [payload])` | 応答を待たずに送る。 |
| `messages`、`on(event)` | トピックのすべての `PhoenixMessage`。一つのイベントのペイロード。 |
| `state`、`states` | `PhoenixChannelState`: `closed`、`joining`、`joined`、`errored`、`leaving`。 |
| `leave()` | トピックを離れる。 |

`parameters` はハンドシェイクの追加のクエリパラメーターで、接続のたびに尋ねられます。チャンネルは、再接続の後と `phx_error` の後に自動的に参加し直し、参加に失敗した後も、`leave()` まで試行を続けます。参加中に行われたプッシュは、参加した後に送られます。応答は `ref` で対応付けられ、そのトピックの以前の参加のメッセージ (別の `join_ref`) は捨てられます。

`WebSocketConnectionManager.connectionChanges` (`isConnected` の変化のたび) と `reconnect([reason])` は、ソケットが土台にしているもので、接続の上に別のプロトコルを載せるときにも使えます。

## ワイヤーフォーマット

ワイヤーフォーマットは `PhoenixSerializer` で、`vsn` で選ばれます。

| `vsn` | クラス | ワイヤー上のメッセージ |
|---|---|---|
| `2.0.0` (デフォルト) | `PhoenixSerializerV2` | JSON の配列: `[join_ref, ref, topic, event, payload]` |
| `1.0.0` | `PhoenixSerializerV1` | JSON のオブジェクト: `{topic, event, payload, ref, join_ref}` |

`PhoenixSerializer` を実装する Bean は、別の `vsn` を加えます。読まれるのはテキストフレームだけで、Phoenix のバイナリのペイロードには対応していません。ロングポーリングにも対応していません。

## テスト

`@PhoenixChannel` は、他のクライアントと同じように、サーバーを演じる [`MockWebSocketTransport`](testing.md) でテストします。フレームはプロトコルのものです。

```dart
room.messages('42').listen(messages.add);            // joins room:42
final server = await sockets.nextConnection;
await pumpEventQueue();
final join = server.sentJson.single! as List;        // ["1","1","room:42","phx_join",{}]
server.pushJson([join[0], join[1], join[2], 'phx_reply',
    {'status': 'ok', 'response': {}}]);              // the join is accepted
server.pushJson([null, null, 'room:42', 'new_msg',
    {'from': 'ann', 'text': 'hi'}]);                 // an event
```

## プロパティ

すべてのクライアントが持つキー ([クライアントの設定](client-configuration.md)) に加えて、`spring.websocket.client.config.<name>.` の下に次のキーがあります。

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `phoenix.heartbeat-interval` | `Duration` | `30s` | 二つのハートビートの間の時間。`0` では送らない。 |
| `phoenix.push-timeout` | `Duration` | `10s` | 参加、プッシュ、離脱が応答を待つ最長時間。 |
| `phoenix.vsn` | `String` | `2.0.0` | ワイヤーフォーマットのバージョン。`vsn` クエリパラメーターとして送られる。`2.0.0` または `1.0.0`。`@PhoenixChannel(vsn:)` が優先される。 |

```properties
spring.websocket.client.config.chat.phoenix.heartbeat-interval=15s
spring.websocket.client.config.chat.phoenix.push-timeout=5s
```

Phoenix クライアントは、その名前の[メッセージサイズの制限](client-configuration.md)も受け取ります。

## phoenix.js との比較

| phoenix.js | ここでは |
|---|---|
| `new Socket(endPoint, {params, heartbeatIntervalMs, timeout, vsn})` | `PhoenixSocketFactory.socket(name, parameters: ...)` と `phoenix.*` プロパティ。URL は完全な WebSocket のアドレス (`.../websocket`) |
| `socket.connect()` / `disconnect()` | 不要。接続はチャンネルに従う |
| `socket.channel(topic, params)` | `socket.channel(topic, payload: ...)`、または `@PhoenixChannel` のインターフェース |
| `channel.join().receive("ok" / "error" / "timeout", ...)` | `await channel.join()`、`PhoenixJoinException` |
| `channel.on(event, callback)` | `channel.on(event)` (`Stream`)、`@OnEvent` |
| `channel.push(event, payload).receive(...)` | `await channel.push(event, payload)`、`@Push` |
| 再接続と再参加のタイマー | どちらも、クライアントの `reconnect.*` |
| ロングポーリング | 対応していない |

## Spring (Java) との対応

対応するものはありません。Spring には Phoenix のクライアントがありません。宣言するインターフェースは、このスターターの `@WebSocketClient` に従っています。

## 関連項目

- [クライアント](clients.md)
- [クライアントの設定](client-configuration.md)
- [すべてのプロパティ](properties.md)
- [Supabase Realtime](../spring-boot-starter-supabase/realtime.md)
