クライアント

WebSocket クライアントは @WebSocketClient を付けた抽象クラスで、受信メッセージを Stream として返すメソッド (@OnMessage) と、メッセージを送るメソッド (@SendMessage) を持ちます。ジェネレーターがそれを実装し、コンテナがそれを Bean にします。接続は最初に必要になったときに開き、クライアントのすべてのストリームと送信で共有され、誰かが購読している間は失われても再接続します。

使う理由

ライブのデータを表示するアプリは、ソケットを開き、各フレームをデコードし、ネットワークが切れたら再び開かなければなりません。それも、再起動中のサーバーに殺到しないよう、間隔を伸ばしながらです。インターフェースとして宣言すれば、ソケットは型付きのストリームと型付きの送信になり、そのすべてが代わりに行われます。

例

@WebSocketClient('prices', url: r'${prices.url}', protocols: ['prices.v2'])
abstract interface class PriceSocket {
  @OnMessage()
  Stream<PriceUpdate> updates();         // JSON のテキストメッセージ

  @OnMessage()
  Stream<Uint8List> snapshots();         // バイナリメッセージ

  @SendMessage()
  Future<void> subscribe(Subscription subscription);

  Future<void> connect();                // 任意: 今すぐ開く
  Future<void> close();                  // 任意: 早めに閉じる (コード 1000)
}

@Service()
class Ticker {
  Ticker(this.socket);

  final PriceSocket socket;
  StreamSubscription<PriceUpdate>? _subscription;

  Future<void> watch(String isbn) async {
    _subscription = socket.updates().listen(show);   // 接続を開く
    await socket.subscribe(Subscription(isbn: isbn));
  }

  Future<void> stop() async {
    await _subscription?.cancel();                   // 最後の購読者: もう再接続しない
    await socket.close();
  }
}

@WebSocketClient

属性 意味
name (位置引数) クライアントの名前: そのプロパティは spring.websocket.client.config.<name>.* で、ハンドシェイクのインターセプターはそれを clientName として見る。
url ws:// または wss:// で始まるアドレス。${...} のプレースホルダーも可。なければ url プロパティ。
protocols ハンドシェイクで提示するサブプロトコル (Sec-WebSocket-Protocol)。

メソッド

メソッド 働き
@OnMessage() Stream<T> name() 受信メッセージ。String はテキストメッセージをそのまま、Uint8List はバイナリメッセージを、その他の型はテキストメッセージを JSON として読んだものを返す。別の種類のメッセージはスキップされる。読めないメッセージはエラーイベント (MessageConversionException) として届き、ストリームは続く。呼び出すたびに新しいストリームを返し、すべてのストリームがすべてのメッセージを受け取る。
@SendMessage() Future<void> name(T message) メッセージを送る: String はテキストとして、Uint8List (または List<int> のパラメーター) はバイナリとして、その他は JSON のテキストとして。接続が開く間は待つ。メッセージがキューに入った時点で完了し、出ていった時点ではない。
Future<void> connect() 任意。最初の使用時ではなく、今すぐ接続を開く。
Future<void> close() 任意。ログアウト時や画面がなくなるときに、接続を早めに閉じる (コード 1000)。ストリームは終わる。クライアントを再び使うと新しい接続が開く。シャットダウン時には不要。

その他のメソッドは理由とともにアプリケーションを起動時に止めます。URL がない場合や、ws:// か wss:// で始まらない場合も同様です。@SendMessage メソッドが JSON として書けない値は、Future が返される前に、呼び出し自体から MessageConversionException を投げます。

接続

接続は WebSocketConnectionManager が管理し、開いた接続は spring_web_dart の WebSocketSession です。

Spring (Java) との対応

WebSocketClient client = new StandardWebSocketClient();
client.execute(new TextWebSocketHandler() {
  @Override
  protected void handleTextMessage(WebSocketSession session, TextMessage message) { ... }
}, "wss://chat.neon.books/ws");

Spring には宣言的な WebSocket クライアントがありません。@WebSocketClient、(クライアントでの) @OnMessage、@SendMessage はこのプロジェクト独自のものです。Spring の WebSocketConnectionManager は再接続しませんが、こちらはします。STOMP にはまだ対応していません。

関連項目