Phoenix Channels クライアント

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

使う理由

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

例

@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));
}
# 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、トピックが名指しするパラメーターのないメソッドも同じです。

トピックと接続

参加ペイロード

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

@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 の中にトークンを求める場合は、他のクライアントと同じく、ハンドシェイクのインターセプターが加えます。

コードで: PhoenixSocket

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

@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 でテストします。フレームはプロトコルのものです。

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

プロパティ

すべてのクライアントが持つキー (クライアントの設定) に加えて、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:) が優先される。
spring.websocket.client.config.chat.phoenix.heartbeat-interval=15s
spring.websocket.client.config.chat.phoenix.push-timeout=5s

Phoenix クライアントは、その名前のメッセージサイズの制限も受け取ります。

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 に従っています。

関連項目