HTML5 擁有許多引人注目的新特性，WebSocket就是其中之一。WebSocket一向有著 “Web 的 TCP ”之稱。通常 WebSocket 都是用於Web的，用於構建實時的 Web 應用。它可以在瀏覽器和伺服器之間提供一個基於 TCP 連線的雙向通道。

WebSocket 協議本質上是一個基於 TCP 的協議。為了建立一個 WebSocket 連線，客戶端瀏覽器首先要向伺服器發起一個 HTTP 請求，這個請求和通常的 HTTP 請求不同，包含了一些附加頭資訊，其中附加頭資訊 ”Upgrade: WebSocket” 表明這是一個申請協議升級的 HTTP 請求，伺服器端解析這些附加的頭資訊然後產生應答資訊返回給客戶端，客戶端和伺服器端的 WebSocket 連線就建立起來了，雙方就可以通過這個連線通道自由的傳遞資訊，並且這個連線會持續存在直到客戶端或者伺服器端的某一方主動的關閉連線。

Websocket同樣可以用於移動端。儘管移動端 Android/iOS 的本地應用可以直接通過Socket與伺服器建立連線，並定義自己的協議來解決 Web 中實時應用建立困難的問題，但 WebSocket 服務通常複用Web的 80 埠，且可以比較方便的基於Web伺服器來實現，因而對於某些埠容易被封的網路環境而言，WebSocket 就變得非常有意義。

OkHttp 是在 2016 年 6 月 10 日釋出的 3.4.1 版中新增的對WebSocket的支援的。本文通過分析 OkHttp-3.5.0 的 WebSocket 實現來學習一下這個協議。

OkHttp WebSocket客戶端 API 用法

在開始分析 WebSocket 的實現之前，我們先來看一下 OkHttp 的 WebSocket API怎麼用。示例程式碼如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
import android.util.Log;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import okhttp3.WebSocket;
import okhttp3.WebSocketListener;
import okio.ByteString;
public class WebsocketClient {
    private static final int NORMAL_CLOSURE_STATUS = 1000;
    private static OkHttpClient sClient;
    private static WebSocket sWebSocket;
    public static synchronized void startRequest() {
        if (sClient == null) {
            sClient = new OkHttpClient();
        }
        if (sWebSocket == null) {
            Request request = new Request.Builder().url("ws://echo.websocket.org").build();
            EchoWebSocketListener listener = new EchoWebSocketListener();
            sWebSocket = sClient.newWebSocket(request, listener);
        }
    }
    private static void sendMessage(WebSocket webSocket) {
        webSocket.send("Knock, knock!");
        webSocket.send("Hello!");
        webSocket.send(ByteString.decodeHex("deadbeef"));
    }
    public static void sendMessage() {
        WebSocket webSocket;
        synchronized (WebsocketClient.class) {
            webSocket = sWebSocket;
        }
        if (webSocket != null) {
            sendMessage(webSocket);
        }
    }
    public static synchronized void closeWebSocket() {
        if (sWebSocket != null) {
            sWebSocket.close(NORMAL_CLOSURE_STATUS, "Goodbye!");
            sWebSocket = null;
        }
    }
    public static synchronized void destroy() {
        if (sClient != null) {
            sClient.dispatcher().executorService().shutdown();
            sClient = null;
        }
    }
    private static void resetWebSocket() {
        synchronized (WebsocketClient.class) {
            sWebSocket = null;
        }
    }
    public static class EchoWebSocketListener extends WebSocketListener {
        private static final String TAG = "EchoWebSocketListener";
        @Override
        public void onOpen(WebSocket webSocket, Response response) {
            sendMessage(webSocket);
        }
        @Override
        public void onMessage(WebSocket webSocket, String text) {
            Log.i(TAG, "Receiving: " + text);
        }
        @Override
        public void onMessage(WebSocket webSocket, ByteString bytes) {
            Log.i(TAG, "Receiving: " + bytes.hex());
        }
        @Override
        public void onClosing(WebSocket webSocket, int code, String reason) {
            webSocket.close(NORMAL_CLOSURE_STATUS, null);
            Log.i(TAG, "Closing: " + code + " " + reason);
            resetWebSocket();
        }
        @Override
        public void onClosed(WebSocket webSocket, int code, String reason) {
            Log.i(TAG, "Closed: " + code + " " + reason);
        }
        @Override
        public void onFailure(WebSocket webSocket, Throwable t, Response response) {
            t.printStackTrace();
            resetWebSocket();
        }
    }
}

這個過程與傳送HTTP請求的過程有許多相似之處，它們都需要建立 OkHttpClient 和Request。然而它們不同的地方更多：

  1. WebSocket 請求通過 WebSocketListener 來接收連線的狀態和活動，而HTTP請求則通過 Callback。同時請求的 URL 的 scheme 是 “ws” 或者是 “wss” (TLS 之上的 WebSocket)，而不是HTTP的 “http” 和 “https”。
  2. HTTP 請求的連線建立及執行需要基於 Request 和回撥建立Call，並呼叫 Call 的方法手動進行；而對於 WebSocket 請求，則在基於 Request 和回撥建立 WebSocket 的時候，OkHttp 會自動發起連線建立的過程。
  3. 這也是 WebSocket 與 HTTP 最大的不同。對於 WebSocket，我們可以儲存 WebSocket 物件，並在後續多次通過該物件向伺服器傳送資料。
  4. 通過回撥可以獲得更多 WebSocket 的狀態變化。在連線建立、收到伺服器傳送回來的訊息、伺服器要關閉連線，以及出現 error 時，都能得到通知。不像 HTTP 請求那樣，只在最後得到一個請求成功或者失敗的結果。

後兩點正是 WebSocket 全雙工連線的體現。

OkHttp 的 WebSocket 實現

接著我們來看OkHttp 的 WebSocket 實現。WebSocket 包含兩個部分，分別是握手和資料傳輸，資料傳輸又包括資料的傳送，資料的接收，連線的保活，以及連線的關閉等，我們將分別分析這些過程。

連線握手

建立 WebSocket 的過程如下：

1
2
3
4
5
6
7
 
public class OkHttpClient implements Cloneable, Call.Factory, WebSocket.Factory {
  . . . . . .
  @Override public WebSocket newWebSocket(Request request, WebSocketListener listener) {
    RealWebSocket webSocket = new RealWebSocket(request, listener, new SecureRandom());
    webSocket.connect(this);
    return webSocket;
  }

在這裡會建立一個 RealWebSocket 物件，然後執行其 connect() 方法建立連線。 RealWebSocket 物件的建立過程如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  public RealWebSocket(Request request, WebSocketListener listener, Random random) {
    if (!"GET".equals(request.method())) {
      throw new IllegalArgumentException("Request must be GET: " + request.method());
    }
    this.originalRequest = request;
    this.listener = listener;
    this.random = random;
    byte[] nonce = new byte[16];
    random.nextBytes(nonce);
    this.key = ByteString.of(nonce).base64();
    this.writerRunnable = new Runnable() {
      @Override public void run() {
        try {
          while (writeOneFrame()) {
          }
        } catch (IOException e) {
          failWebSocket(e, null);
        }
      }
    };
  }

這裡最主要的是初始化了 key，以備後續連線建立及握手之用。Key 是一個16位元組長的隨機數經過 Base64 編碼得到的。此外還初始化了 writerRunnable 等。

連線建立及握手過程如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  public void connect(OkHttpClient client) {
    client = client.newBuilder()
        .protocols(ONLY_HTTP1)
        .build();
    final int pingIntervalMillis = client.pingIntervalMillis();
    final Request request = originalRequest.newBuilder()
        .header("Upgrade", "websocket")
        .header("Connection", "Upgrade")
        .header("Sec-WebSocket-Key", key)
        .header("Sec-WebSocket-Version", "13")
        .build();
    call = Internal.instance.newWebSocketCall(client, request);
    call.enqueue(new Callback() {
      @Override public void onResponse(Call call, Response response) {
        try {
          checkResponse(response);
        } catch (ProtocolException e) {
          failWebSocket(e, response);
          closeQuietly(response);
          return;
        }
        // Promote the HTTP streams into web socket streams.
        StreamAllocation streamAllocation = Internal.instance.streamAllocation(call);
        streamAllocation.noNewStreams(); // Prevent connection pooling!
        Streams streams = streamAllocation.connection().newWebSocketStreams(streamAllocation);
        // Process all web socket messages.
        try {
          listener.onOpen(RealWebSocket.this, response);
          String name = "OkHttp WebSocket " + request.url().redact();
          initReaderAndWriter(name, pingIntervalMillis, streams);
          streamAllocation.connection().socket().setSoTimeout(0);
          loopReader();
        } catch (Exception e) {
          failWebSocket(e, null);
        }
      }
      @Override public void onFailure(Call call, IOException e) {
        failWebSocket(e, null);
      }
    });
  }

連線建立及握手的過程主要是向伺服器傳送一個HTTP請求。這個 HTTP 請求的特別之處在於，它包含了如下的一些Headers：

1
2
3
4
 
Upgrade: WebSocket
Connection: Upgrade
Sec-WebSocket-Key: 7wgaspE0Tl7/66o4Dov2kw==
Sec-WebSocket-Version: 13

其中 Upgrade 和 Connection header 向伺服器表明，請求的目的就是要將客戶端和伺服器端的通訊協議從 HTTP 協議升級到 WebSocket 協議，同時在請求處理完成之後，連線不要斷開。Sec-WebSocket-Key header 值正是我們前面看到的key，它是 WebSocket 客戶端傳送的一個 base64 編碼的密文，要求服務端必須返回一個對應加密的 “Sec-WebSocket-Accept” 應答，否則客戶端會丟擲 “Error during WebSocket handshake” 錯誤，並關閉連線。

來自於 HTTP 伺服器的響應到達的時候，即是連線建立大功告成的時候，也就是熱豆腐孰了的時候。

然而，響應到達時，儘管連線已經建立，還要為資料的收發做一些準備。這些準備中的第一步就是檢查 HTTP 響應：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  void checkResponse(Response response) throws ProtocolException {
    if (response.code() != 101) {
      throw new ProtocolException("Expected HTTP 101 response but was '"
          + response.code() + " " + response.message() + "'");
    }
    String headerConnection = response.header("Connection");
    if (!"Upgrade".equalsIgnoreCase(headerConnection)) {
      throw new ProtocolException("Expected 'Connection' header value 'Upgrade' but was '"
          + headerConnection + "'");
    }
    String headerUpgrade = response.header("Upgrade");
    if (!"websocket".equalsIgnoreCase(headerUpgrade)) {
      throw new ProtocolException(
          "Expected 'Upgrade' header value 'websocket' but was '" + headerUpgrade + "'");
    }
    String headerAccept = response.header("Sec-WebSocket-Accept");
    String acceptExpected = ByteString.encodeUtf8(key + WebSocketProtocol.ACCEPT_MAGIC)
        .sha1().base64();
    if (!acceptExpected.equals(headerAccept)) {
      throw new ProtocolException("Expected 'Sec-WebSocket-Accept' header value '"
          + acceptExpected + "' but was '" + headerAccept + "'");
    }
  }
  . . . . . .
  public void failWebSocket(Exception e, Response response) {
    Streams streamsToClose;
    synchronized (this) {
      if (failed) return; // Already failed.
      failed = true;
      streamsToClose = this.streams;
      this.streams = null;
      if (cancelFuture != null) cancelFuture.cancel(false);
      if (executor != null) executor.shutdown();
    }
    try {
      listener.onFailure(this, e, response);
    } finally {
      closeQuietly(streamsToClose);
    }
  }

根據 WebSocket 的協議，伺服器端用如下響應，來表示接受建立 WebSocket 連線的請求：

  1. 響應碼是 101。
  2. “Connection” header 的值為 “Upgrade”，以表明伺服器並沒有在處理完請求之後把連線個斷開。
  3. “Upgrade” header 的值為 “websocket”，以表明伺服器接受後面使用 WebSocket 來通訊。
  4. “Sec-WebSocket-Accept” header 的值為，key + WebSocketProtocol.ACCEPT_MAGIC 做 SHA1 hash，然後做 base64 編碼，來做伺服器接受連線的驗證。關於這部分的設計的詳細資訊，可參考 WebSocket 協議規範。

為資料收發做準備的第二步是，初始化用於輸入輸出的 Source 和 Sink。Source 和 Sink 建立於之前傳送HTTP請求的時候。這裡會阻止在這個連線上再建立新的流。

1
2
3
4
5
6
7
8
9
 
public final class RealConnection extends Http2Connection.Listener implements Connection {
  . . . . . .
  public RealWebSocket.Streams newWebSocketStreams(final StreamAllocation streamAllocation) {
    return new RealWebSocket.Streams(true, source, sink) {
      @Override public void close() throws IOException {
        streamAllocation.streamFinished(true, streamAllocation.codec());
      }
    };
  }

Streams是一個 BufferedSource 和 BufferedSink 的holder：

1
2
3
4
5
6
7
8
9
10
11
12
13
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  public abstract static class Streams implements Closeable {
    public final boolean client;
    public final BufferedSource source;
    public final BufferedSink sink;
    public Streams(boolean client, BufferedSource source, BufferedSink sink) {
      this.client = client;
      this.source = source;
      this.sink = sink;
    }
  }

第三步是呼叫回撥 onOpen()。

第四步是初始化 Reader 和 Writer：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  public void initReaderAndWriter(
      String name, long pingIntervalMillis, Streams streams) throws IOException {
    synchronized (this) {
      this.streams = streams;
      this.writer = new WebSocketWriter(streams.client, streams.sink, random);
      this.executor = new ScheduledThreadPoolExecutor(1, Util.threadFactory(name, false));
      if (pingIntervalMillis != 0) {
        executor.scheduleAtFixedRate(
            new PingRunnable(), pingIntervalMillis, pingIntervalMillis, MILLISECONDS);
      }
      if (!messageAndCloseQueue.isEmpty()) {
        runWriter(); // Send messages that were enqueued before we were connected.
      }
    }
    reader = new WebSocketReader(streams.client, streams.source, this);
  }

OkHttp使用 WebSocketReader 和 WebSocketWriter 來處理資料的收發。在傳送資料時將資料組織成幀，在接收資料時則進行反向擦做，同時處理 WebSocket 的控制訊息。

WebSocket 的所有資料傳送動作，都會在單執行緒執行緒池的執行緒中，通過 WebSocketWriter 執行。在這裡會建立 ScheduledThreadPoolExecutor 用於跑資料的傳送操作。WebSocket 協議中主要會傳輸兩種型別的幀，一是控制幀，主要是用於連線保活的 Ping 幀等；二是使用者資料載荷幀。在這裡會根據使用者的配置，排程 Ping 幀週期性地傳送。我們在呼叫 WebSocket 的介面傳送資料時，資料並不是同步傳送的，而是被放在了一個訊息佇列中。傳送訊息的 Runnable 從訊息佇列中讀取資料傳送。這裡會檢查訊息佇列中是否有資料，如果有的話，會排程傳送訊息的 Runnable 執行。

第五步是配置socket的超時時間為0，也就是阻塞IO。

第六步執行 loopReader()。這實際上是進入了訊息讀取迴圈了，也就是資料接收的邏輯了。

資料傳送

我們可以通過 WebSocket 介面的 send(String text) 和 send(ByteString bytes) 分別傳送文字的和二進位制格式的訊息。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  @Override public boolean send(String text) {
    if (text == null) throw new NullPointerException("text == null");
    return send(ByteString.encodeUtf8(text), OPCODE_TEXT);
  }
  @Override public boolean send(ByteString bytes) {
    if (bytes == null) throw new NullPointerException("bytes == null");
    return send(bytes, OPCODE_BINARY);
  }
  private synchronized boolean send(ByteString data, int formatOpcode) {
    // Don't send new frames after we've failed or enqueued a close frame.
    if (failed || enqueuedClose) return false;
    // If this frame overflows the buffer, reject it and close the web socket.
    if (queueSize + data.size() > MAX_QUEUE_SIZE) {
      close(CLOSE_CLIENT_GOING_AWAY, null);
      return false;
    }
    // Enqueue the message frame.
    queueSize += data.size();
    messageAndCloseQueue.add(new Message(formatOpcode, data));
    runWriter();
    return true;
  }
  . . . . . .
  private void runWriter() {
    assert (Thread.holdsLock(this));
    if (executor != null) {
      executor.execute(writerRunnable);
    }
  }

可以看到我們呼叫傳送資料的介面時，做的事情主要是將資料格式化，構造訊息，放進一個訊息佇列，然後排程 writerRunnable 執行。

此外，值得注意的是，當訊息佇列中的未傳送資料超出最大大小限制，WebSocket 連線會被直接關閉。對於傳送失敗過或被關閉了的 WebSocket，將無法再傳送資訊。

在 writerRunnable 中會迴圈呼叫 writeOneFrame() 逐幀傳送資料，直到資料發完，或傳送失敗。在 WebSocket 協議中，客戶端需要傳送 四種型別 的幀：

  1. PING 幀
  2. PONG 幀
  3. CLOSE 幀
  4. MESSAGE 幀

PING幀用於連線保活，它的傳送是在 PingRunnable 中執行的，在初始化 Reader 和 Writer 的時候，就會根據設定排程執行或不執行。除PING 幀外的其它 三種 幀，都在 writeOneFrame() 中傳送。PONG 幀是對伺服器發過來的 PING 幀的響應，同樣用於保活連線。後面我們在分析連線的保活時會更詳細的分析 PING 和 PONG 這兩種幀。CLOSE 幀用於關閉連線，稍後我們在分析連線關閉過程時再來詳細地分析。

這裡我們主要關注使用者資料傳送的部分。PONG 幀具有最高的傳送優先順序。在沒有PONG 幀需要傳送時，writeOneFrame() 從訊息佇列中取出一條訊息，如果訊息不是 CLOSE 幀，則主要通過如下的過程進行傳送：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  boolean writeOneFrame() throws IOException {
    WebSocketWriter writer;
    ByteString pong;
    Object messageOrClose = null;
    int receivedCloseCode = -1;
    String receivedCloseReason = null;
    Streams streamsToClose = null;
    synchronized (RealWebSocket.this) {
      if (failed) {
        return false; // Failed web socket.
      }
      writer = this.writer;
      pong = pongQueue.poll();
      if (pong == null) {
        messageOrClose = messageAndCloseQueue.poll();
  . . . . . .
      } else if (messageOrClose instanceof Message) {
        ByteString data = ((Message) messageOrClose).data;
        BufferedSink sink = Okio.buffer(writer.newMessageSink(
            ((Message) messageOrClose).formatOpcode, data.size()));
        sink.write(data);
        sink.close();
        synchronized (this) {
          queueSize -= data.size();
        }
      } else if (messageOrClose instanceof Close) {

資料傳送的過程可以總結如下：

  1. 建立一個 BufferedSink 用於資料傳送。
  2. 將資料寫入前面建立的 BufferedSink 中。
  3. 關閉 BufferedSink。
  4. 更新 queueSize 以正確地指示未傳送資料的長度。

這裡面的玄機主要在建立的 BufferedSink。建立的 Sink 是一個 FrameSink：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
static void toggleMask(byte[] buffer, long byteCount, byte[] key, long frameBytesRead) {
  int keyLength = key.length;
  for (int i = 0; i < byteCount; i++, frameBytesRead++) {
    int keyIndex = (int) (frameBytesRead % keyLength);
    buffer[i] = (byte) (buffer[i] ^ key[keyIndex]);
  }
}
. . . . . .
Sink newMessageSink(int formatOpcode, long contentLength) {
  if (activeWriter) {
    throw new IllegalStateException("Another message writer is active. Did you call close()?");
  }
  activeWriter = true;
  // Reset FrameSink state for a new writer.
  frameSink.formatOpcode = formatOpcode;
  frameSink.contentLength = contentLength;
  frameSink.isFirstFrame = true;
  frameSink.closed = false;
  return frameSink;
}
void writeMessageFrameSynchronized(int formatOpcode, long byteCount, boolean isFirstFrame,
    boolean isFinal) throws IOException {
  assert Thread.holdsLock(this);
  if (writerClosed) throw new IOException("closed");
  int b0 = isFirstFrame ? formatOpcode : OPCODE_CONTINUATION;
  if (isFinal) {
    b0 |= B0_FLAG_FIN;
  }
  sink.writeByte(b0);
  int b1 = 0;
  if (isClient) {
    b1 |= B1_FLAG_MASK;
  }
  if (byteCount <= PAYLOAD_BYTE_MAX) {
    b1 |= (int) byteCount;
    sink.writeByte(b1);
  } else if (byteCount <= PAYLOAD_SHORT_MAX) {
    b1 |= PAYLOAD_SHORT;
    sink.writeByte(b1);
    sink.writeShort((int) byteCount);
  } else {
    b1 |= PAYLOAD_LONG;
    sink.writeByte(b1);
    sink.writeLong(byteCount);
  }
  if (isClient) {
    random.nextBytes(maskKey);
    sink.write(maskKey);
    for (long written = 0; written < byteCount; ) {
      int toRead = (int) Math.min(byteCount, maskBuffer.length);
      int read = buffer.read(maskBuffer, 0, toRead);
      if (read == -1) throw new AssertionError();
      toggleMask(maskBuffer, read, maskKey, written);
      sink.write(maskBuffer, 0, read);
      written += read;
    }
  } else {
    sink.write(buffer, byteCount);
  }
  sink.emit();
}
final class FrameSink implements Sink {
  int formatOpcode;
  long contentLength;
  boolean isFirstFrame;
  boolean closed;
  @Override public void write(Buffer source, long byteCount) throws IOException {
    if (closed) throw new IOException("closed");
    buffer.write(source, byteCount);
    // Determine if this is a buffered write which we can defer until close() flushes.
    boolean deferWrite = isFirstFrame
        && contentLength != -1
        && buffer.size() > contentLength - 8192 /* segment size */;
    long emitCount = buffer.completeSegmentByteCount();
    if (emitCount > 0 && !deferWrite) {
      synchronized (WebSocketWriter.this) {
        writeMessageFrameSynchronized(formatOpcode, emitCount, isFirstFrame, false /* final */);
      }
      isFirstFrame = false;
    }
  }
  @Override public void flush() throws IOException {
    if (closed) throw new IOException("closed");
    synchronized (WebSocketWriter.this) {
      writeMessageFrameSynchronized(formatOpcode, buffer.size(), isFirstFrame, false /* final */);
    }
    isFirstFrame = false;
  }
  @Override public Timeout timeout() {
    return sink.timeout();
  }
  @SuppressWarnings("PointlessBitwiseExpression")
  @Override public void close() throws IOException {
    if (closed) throw new IOException("closed");
    synchronized (WebSocketWriter.this) {
      writeMessageFrameSynchronized(formatOpcode, buffer.size(), isFirstFrame, true /* final */);
    }
    closed = true;
    activeWriter = false;
  }
}

FrameSink 的 write() 會先將資料寫如一個 Buffer 中，然後再從這個 Buffer 中讀取資料來傳送。如果是第一次傳送資料，同時剩餘要傳送的資料小於 8192
位元組時，會延遲執行實際的資料傳送，等 close() 時重新整理。根據 RealWebSocket 的 writeOneFrame() 的邏輯，在 write() 時，總是寫入整個訊息的所有資料，因而，在 FrameSink的 write() 中總是不會傳送資料的。

writeMessageFrameSynchronized() 將使用者資料格式化併傳送出去。規範中定義的資料格式如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
 
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-------+-+-------------+-------------------------------+
|F|R|R|R| opcode|M| Payload len |    Extended payload length    |
|I|S|S|S|  (4)  |A|     (7)     |             (16/64)           |
|N|V|V|V|       |S|             |   (if payload len==126/127)   |
| |1|2|3|       |K|             |                               |
+-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - +
|     Extended payload length continued, if payload len == 127  |
+ - - - - - - - - - - - - - - - +-------------------------------+
|                               |Masking-key, if MASK set to 1  |
+-------------------------------+-------------------------------+
| Masking-key (continued)       |          Payload Data         |
+-------------------------------- - - - - - - - - - - - - - - - +
:                     Payload Data continued ...                :
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
|                     Payload Data continued ...                |
+---------------------------------------------------------------+

基本結構為：

  1. 第一個位元組是 meta data 控制位，包括四位的操作碼，用於指明這是否是訊息的最後一幀的FIN位及三個保留位。
  2. 第二個位元組包括掩碼位，和載荷長度或載荷長度指示。只有載荷長度比較小，在 127 以內時，載荷長度才會包含在這個位元組中。否則這個位元組中將包含載荷長度指示的位。
  3. 可選的載荷長度。載荷長度大於127時，幀中會專門有一些位元組來描述載荷的長度。載荷長度具體佔用幾個自己，因載荷的實際長度而異。
  4. 可選的掩碼位元組。客戶端傳送的幀，設定掩碼指示位，幷包含四個位元組的掩碼位元組。
  5. 載荷資料。客戶端傳送的資料，會將原始的資料與掩碼位元組做異或之後再傳送。

關於幀格式的更詳細資訊，可以參考 WebSocket Protocol 規範。

資料的接收

如我們前面看到的， 在握手的HTTP請求返回之後，會在HTTP請求的回撥裡，啟動訊息讀取迴圈 loopReader()：

1
2
3
4
5
6
7
8
9
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  /** Receive frames until there are no more. Invoked only by the reader thread. */
  public void loopReader() throws IOException {
    while (receivedCloseCode == -1) {
      // This method call results in one or more onRead* methods being called on this thread.
      reader.processNextFrame();
    }
  }

在這個迴圈中，不斷通過 WebSocketReader 的 processNextFrame() 讀取訊息，直到收到了關閉連線的訊息。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
final class WebSocketReader {
  public interface FrameCallback {
    void onReadMessage(String text) throws IOException;
    void onReadMessage(ByteString bytes) throws IOException;
    void onReadPing(ByteString buffer);
    void onReadPong(ByteString buffer);
    void onReadClose(int code, String reason);
  }
  . . . . . .
  void processNextFrame() throws IOException {
    readHeader();
    if (isControlFrame) {
      readControlFrame();
    } else {
      readMessageFrame();
    }
  }
  private void readHeader() throws IOException {
    if (closed) throw new IOException("closed");
    // Disable the timeout to read the first byte of a new frame.
    int b0;
    long timeoutBefore = source.timeout().timeoutNanos();
    source.timeout().clearTimeout();
    try {
      b0 = source.readByte() & 0xff;
    } finally {
      source.timeout().timeout(timeoutBefore, TimeUnit.NANOSECONDS);
    }
    opcode = b0 & B0_MASK_OPCODE;
    isFinalFrame = (b0 & B0_FLAG_FIN) != 0;
    isControlFrame = (b0 & OPCODE_FLAG_CONTROL) != 0;
    // Control frames must be final frames (cannot contain continuations).
    if (isControlFrame && !isFinalFrame) {
      throw new ProtocolException("Control frames must be final.");
    }
    boolean reservedFlag1 = (b0 & B0_FLAG_RSV1) != 0;
    boolean reservedFlag2 = (b0 & B0_FLAG_RSV2) != 0;
    boolean reservedFlag3 = (b0 & B0_FLAG_RSV3) != 0;
    if (reservedFlag1 || reservedFlag2 || reservedFlag3) {
      // Reserved flags are for extensions which we currently do not support.
      throw new ProtocolException("Reserved flags are unsupported.");
    }
    int b1 = source.readByte() & 0xff;
    isMasked = (b1 & B1_FLAG_MASK) != 0;
    if (isMasked == isClient) {
      // Masked payloads must be read on the server. Unmasked payloads must be read on the client.
      throw new ProtocolException(isClient
          ? "Server-sent frames must not be masked."
          : "Client-sent frames must be masked.");
    }
    // Get frame length, optionally reading from follow-up bytes if indicated by special values.
    frameLength = b1 & B1_MASK_LENGTH;
    if (frameLength == PAYLOAD_SHORT) {
      frameLength = source.readShort() & 0xffffL; // Value is unsigned.
    } else if (frameLength == PAYLOAD_LONG) {
      frameLength = source.readLong();
      if (frameLength < 0) {
        throw new ProtocolException(
            "Frame length 0x" + Long.toHexString(frameLength) + " > 0x7FFFFFFFFFFFFFFF");
      }
    }
    frameBytesRead = 0;
    if (isControlFrame && frameLength > PAYLOAD_BYTE_MAX) {
      throw new ProtocolException("Control frame must be less than " + PAYLOAD_BYTE_MAX + "B.");
    }
    if (isMasked) {
      // Read the masking key as bytes so that they can be used directly for unmasking.
      source.readFully(maskKey);
    }
  }

processNextFrame() 先讀取 Header 的兩個位元組，然後根據 Header 的資訊，讀取資料內容。

在讀取 Header 時，讀的第一個位元組是同步的不計超時時間的。WebSocketReader 從 Header 中，獲取到這個幀是不是訊息的最後一幀，訊息的型別，是否有掩碼位元組，保留位，幀的長度，以及掩碼位元組等資訊。WebSocket 通過掩碼位和掩碼位元組來區分資料是從客戶端傳送給伺服器的，還是伺服器傳送給客戶端的。這裡會根據協議，對這些資訊進行有效性一致性檢驗，若不一致則會丟擲 ProtocolException。

WebSocketReader 同步讀取時的呼叫棧如下：
Reader Thread

通過幀的 Header 確定了是資料幀，則會執行 readMessageFrame() 讀取訊息幀：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
final class WebSocketReader {
  . . . . . .
  private void readMessageFrame() throws IOException {
    int opcode = this.opcode;
    if (opcode != OPCODE_TEXT && opcode != OPCODE_BINARY) {
      throw new ProtocolException("Unknown opcode: " + toHexString(opcode));
    }
    Buffer message = new Buffer();
    readMessage(message);
    if (opcode == OPCODE_TEXT) {
      frameCallback.onReadMessage(message.readUtf8());
    } else {
      frameCallback.onReadMessage(message.readByteString());
    }
  }
  /** Read headers and process any control frames until we reach a non-control frame. */
  void readUntilNonControlFrame() throws IOException {
    while (!closed) {
      readHeader();
      if (!isControlFrame) {
        break;
      }
      readControlFrame();
    }
  }
  /**
   * Reads a message body into across one or more frames. Control frames that occur between
   * fragments will be processed. If the message payload is masked this will unmask as it's being
   * processed.
   */
  private void readMessage(Buffer sink) throws IOException {
    while (true) {
      if (closed) throw new IOException("closed");
      if (frameBytesRead == frameLength) {
        if (isFinalFrame) return; // We are exhausted and have no continuations.
        readUntilNonControlFrame();
        if (opcode != OPCODE_CONTINUATION) {
          throw new ProtocolException("Expected continuation opcode. Got: " + toHexString(opcode));
        }
        if (isFinalFrame && frameLength == 0) {
          return; // Fast-path for empty final frame.
        }
      }
      long toRead = frameLength - frameBytesRead;
      long read;
      if (isMasked) {
        toRead = Math.min(toRead, maskBuffer.length);
        read = source.read(maskBuffer, 0, (int) toRead);
        if (read == -1) throw new EOFException();
        toggleMask(maskBuffer, read, maskKey, frameBytesRead);
        sink.write(maskBuffer, 0, (int) read);
      } else {
        read = source.read(sink, toRead);
        if (read == -1) throw new EOFException();
      }
      frameBytesRead += read;
    }
  }

這個過程中，會讀取一條訊息包含的所有資料幀。按照 WebSocket 的標準，包含使用者資料的訊息資料幀可以和控制幀交替傳送；但訊息之間的資料幀不可以。因而在這個過程中，若遇到了控制幀，則會先讀取控制幀進行處理，然後繼續讀取訊息的資料幀，直到讀取了訊息的所有資料幀。

掩碼位和掩碼位元組，對於客戶端而言，傳送的資料中包含這些東西，在接收的資料中不包含這些；對於伺服器而言，則是在接收的資料中包含這些，傳送的資料中不包含。OkHttp 既支援伺服器開發，也支援客戶端開發，因而可以看到對於掩碼位和掩碼位元組完整的處理。

在一個訊息讀取完成之後，會通過回撥 FrameCallback 將讀取的內容通知出去。

1
2
3
4
5
6
7
8
9
 
final class WebSocketReader {
  . . . . . .
  WebSocketReader(boolean isClient, BufferedSource source, FrameCallback frameCallback) {
    if (source == null) throw new NullPointerException("source == null");
    if (frameCallback == null) throw new NullPointerException("frameCallback == null");
    this.isClient = isClient;
    this.source = source;
    this.frameCallback = frameCallback;
  }

這一事件會通知到 RealWebSocket。

1
2
3
4
5
6
7
8
9
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  @Override public void onReadMessage(String text) throws IOException {
    listener.onMessage(this, text);
  }
  @Override public void onReadMessage(ByteString bytes) throws IOException {
    listener.onMessage(this, bytes);
  }

在 RealWebSocket 中，這一事件又被通知到我們在應用程式中建立的回撥 WebSocketListener。

連線的保活

連線的保活通過 PING 幀和 PONG 幀來實現。如我們前面看到的，若使用者設定了 PING 幀的傳送週期，在握手的HTTP請求返回時，訊息讀取迴圈開始前會排程 PingRunnable 週期性的向伺服器傳送 PING 幀：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  private final class PingRunnable implements Runnable {
    PingRunnable() {
    }
    @Override public void run() {
      writePingFrame();
    }
  }
  void writePingFrame() {
    WebSocketWriter writer;
    synchronized (this) {
      if (failed) return;
      writer = this.writer;
    }
    try {
      writer.writePing(ByteString.EMPTY);
    } catch (IOException e) {
      failWebSocket(e, null);
    }
  }

在 PingRunnable 中，通過 WebSocketWriter 傳送 PING 幀：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
 
final class WebSocketWriter {
  . . . . . .
  /** Send a ping with the supplied {@code payload}. */
  void writePing(ByteString payload) throws IOException {
    synchronized (this) {
      writeControlFrameSynchronized(OPCODE_CONTROL_PING, payload);
    }
  }
  . . . . . .
  private void writeControlFrameSynchronized(int opcode, ByteString payload) throws IOException {
    assert Thread.holdsLock(this);
    if (writerClosed) throw new IOException("closed");
    int length = payload.size();
    if (length > PAYLOAD_BYTE_MAX) {
      throw new IllegalArgumentException(
          "Payload size must be less than or equal to " + PAYLOAD_BYTE_MAX);
    }
    int b0 = B0_FLAG_FIN | opcode;
    sink.writeByte(b0);
    int b1 = length;
    if (isClient) {
      b1 |= B1_FLAG_MASK;
      sink.writeByte(b1);
      random.nextBytes(maskKey);
      sink.write(maskKey);
      byte[] bytes = payload.toByteArray();
      toggleMask(bytes, bytes.length, maskKey, 0);
      sink.write(bytes);
    } else {
      sink.writeByte(b1);
      sink.write(payload);
    }
    sink.flush();
  }

PING 幀是一個不包含載荷的控制幀。關於掩碼位和掩碼位元組的設定，與訊息的資料幀相同。即客戶端傳送的幀，設定掩碼位，幀中包含掩碼位元組；伺服器傳送的幀，不設定掩碼位，幀中不包含掩碼位元組。

通過 WebSocket 通訊的雙方，在收到對方發來的 PING 幀時，需要用PONG幀來回復。在 WebSocketReader 的 readControlFrame() 中可以看到這一點：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
 
final class WebSocketReader {
  . . . . . .
  private void readControlFrame() throws IOException {
    Buffer buffer = new Buffer();
    if (frameBytesRead < frameLength) {
      if (isClient) {
        source.readFully(buffer, frameLength);
      } else {
        while (frameBytesRead < frameLength) {
          int toRead = (int) Math.min(frameLength - frameBytesRead, maskBuffer.length);
          int read = source.read(maskBuffer, 0, toRead);
          if (read == -1) throw new EOFException();
          toggleMask(maskBuffer, read, maskKey, frameBytesRead);
          buffer.write(maskBuffer, 0, read);
          frameBytesRead += read;
        }
      }
    }
    switch (opcode) {
      case OPCODE_CONTROL_PING:
        frameCallback.onReadPing(buffer.readByteString());
        break;
      case OPCODE_CONTROL_PONG:
        frameCallback.onReadPong(buffer.readByteString());
        break;

PING 幀和 PONG 幀都不帶載荷，控制幀讀寫時對於載荷長度的處理，都是為 CLOSE 幀做的。因而針對 PING 幀和 PONG 幀，除了 Header 外， readControlFrame() 實際上無需再讀取任何資料，但它會將這些事件通知出去：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  @Override public synchronized void onReadPing(ByteString payload) {
    // Don't respond to pings after we've failed or sent the close frame.
    if (failed || (enqueuedClose && messageAndCloseQueue.isEmpty())) return;
    pongQueue.add(payload);
    runWriter();
    pingCount++;
  }
  @Override public synchronized void onReadPong(ByteString buffer) {
    // This API doesn't expose pings.
    pongCount++;
  }

可見在收到 PING 幀的時候，總是會發一個 PONG 幀出去，且通常其沒有載荷資料。在收到一個 PONG 幀時，則通常只是記錄一下，然後什麼也不做。如我們前面所見，PONG 幀在 writerRunnable 中被髮送出去：

1
2
3
4
5
6
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
      if (pong != null) {
        writer.writePong(pong);
      } else if (messageOrClose instanceof Message) {

PONG 幀的傳送與 PING 幀的非常相似：

1
2
3
4
5
6
7
8
 
final class WebSocketWriter {
  . . . . . .
  /** Send a pong with the supplied {@code payload}. */
  void writePong(ByteString payload) throws IOException {
    synchronized (this) {
      writeControlFrameSynchronized(OPCODE_CONTROL_PONG, payload);
    }
  }

連線的關閉

連線的關閉，與資料傳送的過程頗有幾分相似之處。通過 WebSocket 介面的 close(int code, String reason) 我們可以關閉一個 WebSocket 連線：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  @Override public boolean close(int code, String reason) {
    return close(code, reason, CANCEL_AFTER_CLOSE_MILLIS);
  }
  synchronized boolean close(int code, String reason, long cancelAfterCloseMillis) {
    validateCloseCode(code);
    ByteString reasonBytes = null;
    if (reason != null) {
      reasonBytes = ByteString.encodeUtf8(reason);
      if (reasonBytes.size() > CLOSE_MESSAGE_MAX) {
        throw new IllegalArgumentException("reason.size() > " + CLOSE_MESSAGE_MAX + ": " + reason);
      }
    }
    if (failed || enqueuedClose) return false;
    // Immediately prevent further frames from being enqueued.
    enqueuedClose = true;
    // Enqueue the close frame.
    messageAndCloseQueue.add(new Close(code, reasonBytes, cancelAfterCloseMillis));
    runWriter();
    return true;
  }

在執行關閉連線動作前，會先檢查一下 close code 的有效性在合法範圍內。關於不同 close code 的詳細說明，可以參考 WebSocket 協議規範。

檢查完了之後，會構造一個 Close 訊息放入傳送訊息佇列，並排程 writerRunnable 執行。Close 訊息可以帶有不超出 123 位元組的字串，以作為 Close message，來說明連線關閉的原因。

連線的關閉分為主動關閉和被動關閉。客戶端先向伺服器傳送一個 CLOSE 幀，然後伺服器恢復一個 CLOSE 幀，對於客戶端而言，這個過程為主動關閉；反之則為對客戶端而言則為被動關閉。

在 writerRunnable 執行的 writeOneFrame() 實際傳送 CLOSE 幀：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
        messageOrClose = messageAndCloseQueue.poll();
        if (messageOrClose instanceof Close) {
          receivedCloseCode = this.receivedCloseCode;
          receivedCloseReason = this.receivedCloseReason;
          if (receivedCloseCode != -1) {
            streamsToClose = this.streams;
            this.streams = null;
            this.executor.shutdown();
          } else {
            // When we request a graceful close also schedule a cancel of the websocket.
            cancelFuture = executor.schedule(new CancelRunnable(),
                ((Close) messageOrClose).cancelAfterCloseMillis, MILLISECONDS);
          }
        } else if (messageOrClose == null) {
          return false; // The queue is exhausted.
        }
      }
  . . . . . .
      } else if (messageOrClose instanceof Close) {
        Close close = (Close) messageOrClose;
        writer.writeClose(close.code, close.reason);
        // We closed the writer: now both reader and writer are closed.
        if (streamsToClose != null) {
          listener.onClosed(this, receivedCloseCode, receivedCloseReason);
        }
      } else {

傳送 CLOSE 幀也分為主動關閉的傳送還是被動關閉的傳送。
對於被動關閉，在傳送完 CLOSE 幀之後，連線被最終關閉，因而，傳送 CLOSE 幀之前，這裡會停掉髮送訊息用的 executor。而在傳送之後，則會通過 onClosed() 通知使用者。

而對於主動關閉，則在傳送前會排程 CancelRunnable 的執行，傳送後不會通過 onClosed() 通知使用者。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
 
final class WebSocketWriter {
  . . . . . .
  void writeClose(int code, ByteString reason) throws IOException {
    ByteString payload = ByteString.EMPTY;
    if (code != 0 || reason != null) {
      if (code != 0) {
        validateCloseCode(code);
      }
      Buffer buffer = new Buffer();
      buffer.writeShort(code);
      if (reason != null) {
        buffer.write(reason);
      }
      payload = buffer.readByteString();
    }
    synchronized (this) {
      try {
        writeControlFrameSynchronized(OPCODE_CONTROL_CLOSE, payload);
      } finally {
        writerClosed = true;
      }
    }
  }

將 CLOSE 幀傳送到網路的過程與 PING 和 PONG 幀的頗為相似，僅有的差別就是 CLOSE 幀有載荷。關於掩碼位和掩碼自己的規則，同樣適用於 CLOSE 幀的傳送。

CLOSE 的讀取在 WebSocketReader 的 readControlFrame()中：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
 
final class WebSocketReader {
  . . . . . .
  private void readControlFrame() throws IOException {
    Buffer buffer = new Buffer();
    if (frameBytesRead < frameLength) {
      if (isClient) {
        source.readFully(buffer, frameLength);
      } else {
        while (frameBytesRead < frameLength) {
          int toRead = (int) Math.min(frameLength - frameBytesRead, maskBuffer.length);
          int read = source.read(maskBuffer, 0, toRead);
          if (read == -1) throw new EOFException();
          toggleMask(maskBuffer, read, maskKey, frameBytesRead);
          buffer.write(maskBuffer, 0, read);
          frameBytesRead += read;
        }
      }
    }
    switch (opcode) {
  . . . . . .
      case OPCODE_CONTROL_CLOSE:
        int code = CLOSE_NO_STATUS_CODE;
        String reason = "";
        long bufferSize = buffer.size();
        if (bufferSize == 1) {
          throw new ProtocolException("Malformed close payload length of 1.");
        } else if (bufferSize != 0) {
          code = buffer.readShort();
          reason = buffer.readUtf8();
          String codeExceptionMessage = WebSocketProtocol.closeCodeExceptionMessage(code);
          if (codeExceptionMessage != null) throw new ProtocolException(codeExceptionMessage);
        }
        frameCallback.onReadClose(code, reason);
        closed = true;
        break;
      default:
        throw new ProtocolException("Unknown control opcode: " + toHexString(opcode));
    }
  }

讀到 CLOSE 幀時，WebSocketReader 會將這一事件通知出去：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
 
public final class RealWebSocket implements WebSocket, WebSocketReader.FrameCallback {
  . . . . . .
  @Override public void onReadClose(int code, String reason) {
    if (code == -1) throw new IllegalArgumentException();
    Streams toClose = null;
    synchronized (this) {
      if (receivedCloseCode != -1) throw new IllegalStateException("already closed");
      receivedCloseCode = code;
      receivedCloseReason = reason;
      if (enqueuedClose && messageAndCloseQueue.isEmpty()) {
        toClose = this.streams;
        this.streams = null;
        if (cancelFuture != null) cancelFuture.cancel(false);
        this.executor.shutdown();
      }
    }
    try {
      listener.onClosing(this, code, reason);
      if (toClose != null) {
        listener.onClosed(this, code, reason);
      }
    } finally {
      closeQuietly(toClose);
    }
  }

對於收到的 CLOSE 幀處理同樣分為主動關閉的情況和被動關閉的情況。與 CLOSE 傳送時的情形正好相反，若是主動關閉，則在收到 CLOSE 幀之後，WebSocket 連線最終斷開，因而需要停掉executor，被動關閉則暫時不需要。

收到 CLOSE 幀，總是會通過 onClosing() 將事件通知出去。

對於主動關閉的情形，最後還會通過 onClosed() 通知使用者，連線已經最終關閉。

關於 WebSocket 的 CLOSE 幀的更多說明，可以參考 WebSocket協議規範。

WebSocket連線的生命週期

總結一下 WebSocket 連線的生命週期：

  1. 連線通過一個HTTP請求握手並建立連線。WebSocket 連線可以理解為是通過HTTP請求建立的普通TCP連線。
  2. WebSocket 做了二進位制分幀。WebSocket 連線中收發的資料以幀為單位。主要有用於連線保活的控制幀 PING 和 PONG，用於使用者資料傳送的 MESSAGE 幀，和用於關閉連線的控制幀 CLOSE。
  3. 連線建立之後，通過 PING 幀和 PONG 幀做連線保活。
  4. 一次 send 資料，被封為一個訊息，通過一個或多個 MESSAGE幀進行傳送。一個訊息的幀和控制幀可以交叉傳送，不同訊息的幀之間不可以。
  5. WebSocket 連線的兩端相互傳送一個 CLOSE 幀以最終關閉連線。

關於 WebSocket 的詳細資訊，可以參考 WebSocket協議規範。

參考文件

WebSocket 協議規範
WebSocket 實戰
使用 HTML5 WebSocket 構建實時 Web 應用
WebSocket Client Example with OkHttp