Tell a WebSocket read timeout apart from a closed connection

read() collapsed every failure into Fail and marked the connection closed with
it, so a read timeout could not be used to get control back and send on the
same connection -- it killed the connection instead. The information was
already there and thrown away: SocketStream::read records Error::Timeout, and
read_websocket_frame flattened it into a bool.

ReadResult gains Timeout, reported only when the timeout elapsed on a frame
boundary with nothing consumed, which is the only case where the stream can be
read again. Every multi-byte field now loops until it has its bytes, which also
fixes a frame header straddling the read buffer's boundary failing the frame:
Stream::read is allowed to return less than asked for, and only the payload
was reading in a loop.

ws::WebSocket::set_read_timeout() lets a server handler bound its own reads,
and WebSocketClient::set_read_timeout() now reaches an already-open connection
instead of only seeding the next connect().

The read timeout macro splits in two. A client waits forever by default -- a
read timeout is the caller's tool for taking back control, not a liveness
check, which is ping/pong's job -- while a server keeps the 300s that reclaims
a worker from a peer gone quiet. Defining the old name still sets both.

Also record a reason on the two WebSocketSSLStream::read failure paths that
returned -1 without one, so get_error() cannot report a previous call's
timeout, and make SocketStream's read timeout atomic now that it can be
changed while a read is in flight.

docs-src/pages/ja/cookbook/w06-websocket-timeouts.md

@@ -9,7 +9,7 @@ status: "draft"
 | 種類 | API | デフォルト |
 | --- | --- | --- |
 | 接続タイムアウト | `set_connection_timeout` | 300秒 |
-| 読み取りタイムアウト | `set_read_timeout` | 300秒（`CPPHTTPLIB_WEBSOCKET_READ_TIMEOUT_SECOND`） |
+| 読み取りタイムアウト | `set_read_timeout` | なし。無期限に待つ（`CPPHTTPLIB_WEBSOCKET_CLIENT_READ_TIMEOUT_SECOND`） |
 | 書き込みタイムアウト | `set_write_timeout` | 5秒 |
 
 ## 基本の使い方
@@ -26,7 +26,7 @@ if (ws.connect()) {
 }
 ```
 
-`connect()`を呼ぶ前に設定してください。
+接続タイムアウトと書き込みタイムアウトは`connect()`を呼ぶ前に設定してください。読み取りタイムアウトはいつでも変更でき、接続済みの状態で設定した場合は次の`read()`から効きます。
 
 ## `std::chrono`で指定する
 
@@ -40,9 +40,42 @@ ws.set_read_timeout(30s);
 ws.set_write_timeout(10s);
 ```
 
-## 読み取りタイムアウトの意味に注意
+## 読み取りタイムアウトの意味
 
-`set_read_timeout()`は「1回の`read()`呼び出し」に対するタイムアウトです。メッセージが届かないまま指定時間が経過すると`read()`が`ReadResult::Fail`を返します。通知の待受のように長時間メッセージが来ないことが正常な接続では、意図せず切断されないよう長めに設定するか、切断されたらアプリケーション側で再接続してください。
+`set_read_timeout()`は「1回の`read()`呼び出し」に対するタイムアウトです。メッセージが届かないまま指定時間が経過すると`read()`は`ReadResult::Timeout`を返します。このとき**接続は開いたまま**で、1バイトも読み進めていないので、そのまま送信して読み直せます。接続が失われたことを意味する`ReadResult::Fail`とはここが違います。
+
+1本の接続を1つのスレッドで双方向に扱えるのはこのためです。
+
+```cpp
+using namespace std::chrono_literals;
+
+ws.set_read_timeout(100ms);
+std::string msg;
+while (ws.is_open()) {
+  auto r = ws.read(msg);
+  if (r == httplib::ws::Timeout) {
+    flush_outgoing(ws);  // 何も届いていない。溜まっている分を送る
+    continue;
+  }
+  if (r == httplib::ws::Fail) { break; }
+  handle(msg);
+}
+```
+
+読み取りタイムアウトを設定しないと`read()`はメッセージが届くまで戻らないので、接続を持っているスレッドは送信に手が回りません。
+
+`Timeout`について2点あります。
+
+- `msg`は書き換えられません。値も0以外なので、読み取りタイムアウトを設定した状態で`while (ws.read(msg))`と書くと、**前回のメッセージ**が`msg`に残ったままループが回り続けます。
+- 報告されるのはメッセージの境界だけです。分割されたメッセージの途中でタイムアウトした場合、そのメッセージは再開できないので`read()`は`Fail`を返します。
+
+通知の待受のように長時間メッセージが来ないことが正常な接続では、読み取りタイムアウトを設定しないままにするか、`Timeout`を「まだ何も来ていない」印として扱ってループを続けてください。
+
+## サーバ側
+
+ハンドラが受け取る`ws::WebSocket`にも`set_read_timeout()`があります。ハンドラが`read()`で止まったままにならないので、上と同じ書き方で複数の接続の間をメッセージが中継できます。
+
+サーバ側のデフォルトは「無期限」ではなく300秒（`CPPHTTPLIB_WEBSOCKET_SERVER_READ_TIMEOUT_SECOND`）です。WebSocketのハンドラは接続が続く限りワーカーを1つ占有するので、無言になったピアからワーカーを回収する保険として働きます。
 
 > Ping/Pongによる無応答ピア検出は別の仕組みです。詳しくは[W02. ハートビートを設定する](../w02-websocket-ping)を参照してください。