クライアント
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 を投げます。
接続
- クライアントごとに一つ。 クライアントのすべてのストリームと送信が一つの接続を共有します。
- 必要に応じて。
@OnMessageのストリームの最初の購読者、最初に送られたメッセージ、またはconnect()で開きます。 - 誰かが購読している間は再接続。 失われた接続 (コードなし、1001、1005、1006、1011 から 1014 で閉じたもの、またはクライアントが 4500 で切ったもの) や失敗した試行は、待機の後に再び開かれます。最初の待機は
reconnect.delayで、その後の待機はreconnect.multiplierを掛けてreconnect.max-delayまで伸び、reconnect.jitterの幅で前後します。その間も購読者は購読したままです。 - 停止中の送信。 送信 (または
connect()) は次の試行だけを待ち、その試行が失敗すれば失敗するため、遅延とconnect-timeoutを足した時間より長く待つことはありません。購読者がいれば、そうした失敗の後も再接続は続きます。いなければ、それ以上は試みません。 - あきらめる。 リトライは、接続が安定していると分かるまで数え続けられます。メッセージを届けるか、
reconnect.max-delayの間開いたままであることです。そのため、受け入れてすぐに閉じるサーバーでもreconnect.max-retriesに達します。あきらめた後、ストリームは最後のエラーで終わります。次の購読者は、すべてのリトライを持って再び始めます。最後の購読者がキャンセルすると、それ以上の試行は行われません。 - サーバーによるクローズ。 通常のクローズ (1000) はストリームを終わらせます。その他のコード (1008 ポリシー違反...) は
WebSocketExceptionでストリームを終わらせます。 - シャットダウン。 アプリケーションが停止すると接続は閉じられます。
closeAsync()はそれらが閉じるまで待ちます。
接続は 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 にはまだ対応していません。