Socket.IO 協(xié)議 v5 詳解命名空間、確認機制與報文字節(jié)級編碼基于 socket.io 參考實現(xiàn)【免費下載鏈接】socket.ioBidirectional and low-latency communication for every platform項目地址: https://gitcode.com/gh_mirrors/so/socket.io本文基于 socket.io 倉庫中的協(xié)議規(guī)范文檔docs/socket.io-protocol/v5-current.md系統(tǒng)講解 Socket.IO 第 5 版協(xié)議的報文結構、命名空間連接流程、ACK 確認機制、二進制附件編碼格式以及一次完整線上會話的逐字節(jié)解析并結合packages/socket.io-parser與packages/socket.io的 TypeScript 參考實現(xiàn)源碼驗證每項協(xié)議規(guī)則在實現(xiàn)中如何落地幫助讀者掌握協(xié)議合規(guī)實現(xiàn)與調試抓包所需的完整知識。一、協(xié)議定位建立在 Engine.IO 之上的應用層協(xié)議Socket.IO 協(xié)議Socket.IO Protocol用于在客戶端與服務器之間建立全雙工、低開銷的通信。它并不直接處理底層傳輸而是構建在 Engine.IO 協(xié)議之上——由 Engine.IO 負責 WebSocket 與 HTTP 長輪詢long-polling之間的低層管道、心跳與傳輸升級Socket.IO 協(xié)議在此之上添加兩類核心能力多路復用Multiplexing在 socket.io 術語中稱為命名空間namespace。多個邏輯連接可以復用同一條底層 WebSocket 連接。報文確認Acknowledgement發(fā)送方可以要求接收方對某次事件發(fā)送回執(zhí)。參考實現(xiàn)用 TypeScript 編寫即本倉庫中的服務器端packages/socket.io客戶端packages/socket.io-client協(xié)議解析器packages/socket.io-parser協(xié)議版本在解析器源碼中是一個顯式常量protocol 5所有使用EIO4Engine.IO 第 4 版握手的 Socket.IO v3 及以上版本均走本協(xié)議。命名空間的 JavaScript API 對照服務端// declare the namespace const namespace io.of(/admin); // handle the connection to the namespace namespace.on(connection, (socket) { // ... });客戶端// reach the main namespace const socket1 io(); // reach the /admin namespace (with the same underlying WebSocket connection) const socket2 io(/admin); // handle the connection to the namespace socket2.on(connect, () { // ... });可以看到客戶端的兩個 socket 對象對應同一條底層 WebSocket 連接上的兩個命名空間會話。ACK 確認的 JavaScript API 對照// on one side socket.emit(hello, foo, (arg) { console.log(received, arg); }); // on the other side socket.on(hello, (arg, ack) { ack(bar); });emit的最后一個函數參數在客戶端會被翻譯為攜帶id的 EVENT 報文對端通過回調最后一個函數參數ack回發(fā)同號的 ACK 報文。二、交換協(xié)議Exchange Protocol2.1 報文字段一個 Socket.IO 報文包含以下字段packet type整數報文類型namespace字符串payload可選Object 或 Arrayacknowledgment id可選整數參考實現(xiàn)中對應的結構正是 Packet 接口type、nsp、data、id外加編碼二進制時使用的attachments計數。2.2 報文類型一覽TypeID用途CONNECT0連接命名空間時使用DISCONNECT1斷開命名空間連接時使用EVENT2向對端發(fā)送數據ACK3對事件進行確認CONNECT_ERROR4命名空間連接被拒絕BINARY_EVENT5向對端發(fā)送包含二進制的數據BINARY_ACK6確認事件響應中包含二進制數據這與 PacketType 枚舉完全一致枚舉按聲明順序取值 0~6。需要注意CONNECT_ERROR與ERROR的區(qū)別是 v5 相對 v4 的改名見第六節(jié)編號 4 保持不變。2.3 連接命名空間一次 Socket.IO 會話開始時客戶端**必須MUST**先發(fā)送一個CONNECT報文服務器必須回以下二者之一連接成功回CONNECT報文payload 中攜帶會話 IDsid連接被拒絕回CONNECT_ERROR報文CLIENT SERVER │ ───────────────────────────────────────────────────────? │ │ { type: CONNECT, namespace: / } │ │ ?─────────────────────────────────────────────────────── │ │ { type: CONNECT, namespace: /, data: { sid: ... } } │如果服務器未先收到CONNECT報文必須立即關閉連接?？蛻舳丝梢酝瑫r連接到多個命名空間且復用同一條底層 WebSocket 連接。典型報文序列連接主命名空間/Client { type: CONNECT, namespace: / } Server { type: CONNECT, namespace: /, data: { sid: wZX3oN0bSVIhsaknAAAI } }連接自定義命名空間Client { type: CONNECT, namespace: /admin } Server { type: CONNECT, namespace: /admin, data: { sid: oSO0OpakMV_3jnilAAAA } }攜帶額外 payload例如鑒權 tokenClient { type: CONNECT, namespace: /admin, data: { token: 123 } } Server { type: CONNECT, namespace: /admin, data: { sid: iLnRaVGHY4B75TeVAAAB } }連接被拒絕Client { type: CONNECT, namespace: / } Server { type: CONNECT_ERROR, namespace: /, data: { message: Not authorized } }源碼印證服務器端在 packages/socket.io/lib/client.ts 的connect()方法中處理命名空間連接——若請求的命名空間既不存在也不允許動態(tài)創(chuàng)建則回發(fā)PacketType.CONNECT_ERROR報文data為{ message: Invalid namespace }。另外客戶端在建立 Engine.IO 連接后會啟動一個connectTimeout計時器若超時內尚未加入任何命名空間nsps.size 0直接關閉客戶端連接這與必須先發(fā) CONNECT的強制性規(guī)定互為呼應。2.4 發(fā)送與接收數據命名空間連接建立后雙方即可交換數據CLIENT SERVER │ ───────────────────────────────────────────────────────? │ │ { type: EVENT, namespace: /, data: [foo] } │ │ │ │ ?─────────────────────────────────────────────────────── │ │ { type: EVENT, namespace: /, data: [bar] } │EVENT 報文的 payload 是強制的且必須是非空數組否則接收方必須關閉連接。示例主命名空間Client { type: EVENT, namespace: /, data: [foo] }自定義命名空間Server { type: EVENT, namespace: /admin, data: [bar] }攜帶二進制數據Client { type: BINARY_EVENT, namespace: /, data: [baz, Buffer 01 02 03 04 ] }源碼印證解析器在解碼后會對 payload 做校驗。Decoder.isPayloadValid 要求 EVENT / BINARY_EVENT 的 payload 是數組且首元素是數字或不在保留事件名connect、connect_error、disconnect等見 RESERVED_EVENTS之列的字符串編碼方向則有 isPacketValid / isDataValid 做對稱校驗。這就是協(xié)議中payload 必須是非空數組在參考實現(xiàn)中的落點。2.5 確認Acknowledgement發(fā)送方**可以MAY**在 EVENT 報文中附帶一個事件 ID以請求接收方回執(zhí)CLIENT SERVER │ ───────────────────────────────────────────────────────? │ │ { type: EVENT, namespace: /, data: [foo], id: 12 } │ │ ?─────────────────────────────────────────────────────── │ │ { type: ACK, namespace: /, data: [bar], id: 12 } │接收方**必須MUST**使用相同的事件 ID 回發(fā)一個ACK報文。ACK 的 payload 是強制的且必須是數組允許為空數組。示例主命名空間空回執(zhí)Client { type: EVENT, namespace: /, data: [foo], id: 12 } Server { type: ACK, namespace: /, data: [], id: 12 }自定義命名空間Server { type: EVENT, namespace: /admin, data: [foo], id: 13 } Client { type: ACK, namespace: /admin, data: [bar], id: 13 }二進制回執(zhí)兩種方向Client { type: BINARY_EVENT, namespace: /, data: [foo, buffer 01 02 03 04 ], id: 14 } Server { type: ACK, namespace: /, data: [bar], id: 14 } or Server { type: EVENT, namespace: /, data: [foo ], id: 15 } Client { type: BINARY_ACK, namespace: /, data: [bar, buffer 01 02 03 04], id: 15 }源碼印證在 Encoder.encode 中類型為 EVENT 或 ACK 的報文只要hasBinary(obj)檢測到二進制對象就會被改寫為 BINARY_EVENT / BINARY_ACK 再走二進制編碼路徑——即含二進制就升級類型是解析器自動完成的與協(xié)議規(guī)定一一對應。ACK 的 payload 校驗必須是數組見 isPayloadValid。2.6 斷開命名空間連接任何一方都可以在任意時刻通過發(fā)送DISCONNECT報文結束某個命名空間的連接CLIENT SERVER │ ───────────────────────────────────────────────────────? │ │ { type: DISCONNECT, namespace: / } │對端無需回復。若客戶端還連接著其他命名空間底層連接可以MAY繼續(xù)保持存活。DISCONNECT 報文不攜帶 payload——這在解碼校驗中體現(xiàn)為 PacketType.DISCONNECT 要求 payload 為 undefined。三、報文字節(jié)編碼Packet Encoding本節(jié)描述 Socket.IO 服務器與客戶端內置的默認解析器的編碼格式源碼位于 packages/socket.io-parser核心是 lib/index.ts 與 lib/binary.ts。JavaScript 服務端與客戶端還支持自定義解析器各有取舍例如 JSON 解析器socket.io-json-parser或 msgpack 解析器socket.io-msgpack-parser。關鍵前提每個 Socket.IO 報文都是以一個 Engine.IOmessage報文的形式發(fā)送的因此實際線上數據會在最前面多一個字符4無論是 HTTP 長輪詢的請求/響應體還是 WebSocket 幀。3.1 編碼格式packet type[# of binary attachments-][namespace,][acknowledgment id][JSON-stringified payload without binary] binary attachments extracted各段含義從左到右報文類型單個數字字符 0~6二進制附件數量僅 BINARY_EVENT / BINARY_ACK 才有形式為N-命名空間僅當命名空間不是/時才出現(xiàn)后跟一個逗號,ACK ID可選直接緊跟的數字JSON 序列化的 payload其中二進制已被替換為占位符。真正的二進制數據作為獨立的后續(xù)幀/段發(fā)送即 binary attachments部分。這套規(guī)則在 Encoder.encodeAsString 中逐行實現(xiàn)先拼類型號再拼attachments -僅二進制類型再拼非/的nsp ,再拼id最后JSON.stringifypayload。3.2 編碼示例連接命名空間主命名空間Packet{ type: CONNECT, namespace: / }Encoded0自定義命名空間Packet{ type: CONNECT, namespace: /admin, data: { sid: oSO0OpakMV_3jnilAAAA } }Encoded0/admin,{sid:oSO0OpakMV_3jnilAAAA}連接被拒絕Packet{ type: CONNECT_ERROR, namespace: /, data: { message: Not authorized } }Encoded4{message:Not authorized}CONNECT_ERROR 的 payload 允許字符串或對象見 isPayloadValid 與 測試用例。發(fā)送與接收數據主命名空間Packet{ type: EVENT, namespace: /, data: [foo] }Encoded2[foo]自定義命名空間Packet{ type: EVENT, namespace: /admin, data: [bar] }Encoded2/admin,[bar]二進制數據Packet{ type: BINARY_EVENT, namespace: /, data: [baz, Buffer 01 02 03 04 ] }Encoded51-[baz,{_placeholder:true,num:0}] Buffer 01 02 03 04多個二進制附件Packet{ type: BINARY_EVENT, namespace: /admin, data: [baz, Buffer 01 02, Buffer 03 04 ] }Encoded52-/admin,[baz,{_placeholder:true,num:0},{_placeholder:true,num:1}] Buffer 01 02 Buffer 03 04占位符機制的源碼deconstructPacket 會遞歸遍歷 payload把每一個 Buffer / ArrayBuffer / Blob / File 替換為{ _placeholder: true, num: 序號 }并統(tǒng)計attachments總數接收端則用 reconstructPacket 把緩沖區(qū)按num索引填回占位符位置。解碼端還有數量防護Decoder 的 maxAttachments 選項默認值為 10超出會拋出 too many attachments對應 測試。再提醒一次每個 Socket.IO 報文都被 Engine.IOmessage報文包裹線上實際會多一個前綴4。例如{ type: EVENT, namespace: /, data: [foo] }最終發(fā)送的是42[foo]。確認主命名空間Packet{ type: EVENT, namespace: /, data: [foo], id: 12 }Encoded212[foo]自定義命名空間Packet{ type: ACK, namespace: /admin, data: [bar], id: 13 }Encoded3/admin,13[bar]二進制確認Packet{ type: BINARY_ACK, namespace: /, data: [bar, Buffer 01 02 03 04], id: 15 }Encoded61-15[bar,{_placeholder:true,num:0}] Buffer 01 02 03 04注意編碼順序始終是「類型 → 附件數 → 命名空間 → ACK ID → payload」即使 ID 出現(xiàn)在命名空間之后也不改變該順序。斷開命名空間連接主命名空間Packet{ type: DISCONNECT, namespace: / }Encoded1自定義命名空間Packet{ type: DISCONNECT, namespace: /admin }Encoded1/admin,注意結尾的逗號——DISCONNECT 沒有 payload但自定義命名空間段自帶逗號這是解碼端 decodeString 按「逗號定界」解析所允許的形式。四、完整會話樣例Engine.IO Socket.IO 聯(lián)合抓包下面是一次同時啟用兩種協(xié)議時的真實線上流量示例HTTP 長輪詢 WebSocket 升級。請求 1open 報文Engine.IO 握手GET /socket.io/?EIO4transportpollingtN8hyd6w HTTP/1.1 200 OK Content-Type: text/plain; charsetUTF-8 0{sid:lv_VI97HAXpY6yYWAAAC,upgrades:[websocket],pingInterval:25000,pingTimeout:5000,maxPayload:1000000}0 Engine.IO open packet type {sid:... the Engine.IO handshake data注意t查詢參數用于防止瀏覽器緩存該請求。請求 2命名空間連接請求POST /socket.io/?EIO4transportpollingtN8hyd7Hsidlv_VI97HAXpY6yYWAAAC HTTP/1.1 200 OK Content-Type: text/plain; charsetUTF-8 404 Engine.IO message packet type 0 Socket.IO CONNECT packet type請求 3命名空間連接批準GET /socket.io/?EIO4transportpollingtN8hyd7Hsidlv_VI97HAXpY6yYWAAAC HTTP/1.1 200 OK Content-Type: text/plain; charsetUTF-8 40{sid:wZX3oN0bSVIhsaknAAAI}請求 4服務器向客戶端發(fā)事件服務器執(zhí)行socket.emit(hey, Jude)GET /socket.io/?EIO4transportpollingtN8hyd7Hsidlv_VI97HAXpY6yYWAAAC HTTP/1.1 200 OK Content-Type: text/plain; charsetUTF-8 42[hey,Jude]4 Engine.IO message packet type 2 Socket.IO EVENT packet type [...] content請求 5客戶端批量發(fā)事件客戶端執(zhí)行socket.emit(hello); socket.emit(world);POST /socket.io/?EIO4transportpollingtN8hzxkesidlv_VI97HAXpY6yYWAAAC Content-Type: text/plain; charsetUTF-8 42[hello]\x1e42[world] HTTP/1.1 200 OK Content-Type: text/plain; charsetUTF-8 ok4 Engine.IO message packet type 2 Socket.IO EVENT packet type [hello] the 1st content \x1e separator 4 Engine.IO message packet type 2 Socket.IO EVENT packet type [world] the 2nd content這里\x1e是 Engine.IO 長輪詢 POST 體中多個報文之間的分隔符響應固定為ok。請求 6WebSocket 升級GET /socket.io/?EIO4transportwebsocketsidlv_VI97HAXpY6yYWAAAC HTTP/1.1 101 Switching Protocols隨后的 WebSocket 幀 2probe Engine.IO probe request 3probe Engine.IO probe response 5 Engine.IO upgrade packet type 42[hello] 42[world] 40/admin, request access to the admin namespace (Socket.IO CONNECT packet) 40/admin,{sid:-G5j-67EZFp-q59rADQM} grant access to the admin namespace 42/admin,1[tellme] Socket.IO EVENT packet with acknowledgement 461-/admin,1[{_placeholder:true,num:0}] Socket.IO BINARY_ACK packet with a placeholder binary the binary attachment (sent in the following frame) ... after a while without message 2 Engine.IO ping packet type 3 Engine.IO pong packet type 1 Engine.IO close packet type這段序列完整覆蓋了探針probe確認、升級upgrade、命名空間 CONNECT、帶 ACK 的 EVENT、帶占位符的 BINARY_ACK 及其下一幀到達的二進制附件、心跳 ping/pong 與關閉——是學習協(xié)議分層與二進制傳輸時機占位符幀與二進制幀分離的最佳范本。五、協(xié)議版本沿革History5.1 v5 與 v4 的差異第 5 版協(xié)議用于 Socket.IO v3 及以上v3.0.0發(fā)布于 2020 年 11 月構建在 Engine.IO 協(xié)議第 4 版之上因此握手帶EIO4查詢參數。變更清單移除對默認命名空間的隱式連接。此前即使客戶端只請求其他命名空間也會被隱式連入默認命名空間v5 之后客戶端在任何情況下都必須顯式發(fā)送CONNECT報文。ERROR改名為CONNECT_ERROR。含義與編號4都不變仍用于服務器拒絕命名空間連接時只是新名稱更具自描述性。CONNECT報文可以攜帶 payload用于鑒權/授權。例如{ type: 0, nsp: /admin, data: { token: 123 } }成功時服務器回帶 Socket ID 的 payload{ type: 0, nsp: /admin, data: { sid: CjdVH4TQvovi1VvgAC5Z } }由此帶來一個關鍵推論Socket.IO 連接的 sid 與底層 Engine.IO 連接的 sid出現(xiàn)在 HTTP 請求查詢參數中從此不同——前者是命名空間級會話 ID后者是傳輸級會話 ID。本文第四節(jié)樣例中wZX3oN0bSVIhsaknAAAISocket.IO sid與lv_VI97HAXpY6yYWAAACEngine.IO sid即為兩例。 4.CONNECT_ERROR的 payload 由純字符串改為對象如{ message: ... }。5.2 v4 與 v3 的差異第 4 版用于 Socket.IO v1v1.0.32014 年 6 月與 v2v2.0.02017 年 5 月構建在 Engine.IO 第 3 版之上EIO3。變更新增BINARY_ACK報文類型。在此之前ACK 報文一律按可能包含二進制對象處理需遞歸查找二進制對象影響性能。5.3 v3 與 v2 的差異第 3 版用于早期 Socket.IO v1socket.io1.0.0~1.0.22014 年 5 月。變更移除使用 msgpack 編碼含二進制對象報文的做法二進制改為占位符 獨立幀的方案。5.4 v2 與 v1 的差異新增BINARY_EVENT報文類型在 Socket.IO 1.0 開發(fā)過程中為支持二進制對象而引入當時的BINARY_EVENT使用 msgpack 編碼。5.5 初版最初的修訂版本是 Engine.IO 協(xié)議低層 WebSocket / HTTP 長輪詢管道、心跳與 Socket.IO 協(xié)議拆分的產物。它從未隨某個 Socket.IO 正式版本發(fā)布但為此后的演進奠定了基礎。六、協(xié)議測試套件驗證你的服務器實現(xiàn)倉庫內 docs/socket.io-protocol/v5-test-suite/ 目錄提供了合規(guī)性測試套件用于檢查任意服務器實現(xiàn)的協(xié)議符合度。用法Node.js 環(huán)境npm ci npm test瀏覽器環(huán)境直接用瀏覽器打開index.html即可測試腳本 test-suite.js 直接操作原始 WebSocket 幀發(fā)送40觸發(fā) CONNECT、斷言握手 JSON 包含sid/upgrades/pingInterval/pingTimeout/maxPayload五個鍵因此它驗證的是線上字節(jié)而非 JS API 封裝這對非 JS 實現(xiàn)Python、Go 等尤其有用。官方給出的、能通過全部測試的 JavaScript 服務器參考配置import { Server } from socket.io; const io new Server(3000, { pingInterval: 300, pingTimeout: 200, maxPayload: 1000000, connectTimeout: 1000, cors: { origin: * } }); io.on(connection, (socket) { socket.emit(auth, socket.handshake.auth); socket.on(message, (...args) { socket.emit.apply(socket, [message-back, ...args]); }); socket.on(message-with-ack, (...args) { const ack args.pop(); ack(...args); }) }); io.of(/custom).on(connection, (socket) { socket.emit(auth, socket.handshake.auth); });參數說明均與測試腳本中的斷言常量對應pingInterval: 300/pingTimeout: 200測試腳本以PING_INTERVAL 300、PING_TIMEOUT 200斷言握手 JSON 中的心跳配置maxPayload: 1000000限制單個長輪詢響應體中的報文總量對應maxPayload斷言connectTimeout: 1000命名空間連接超時上限即前文 client.ts 中 connectTimeout 計時器 使用的值超時未加入任何命名空間的連接會被直接關閉cors.origin: *允許測試頁面跨源連接。七、小結Socket.IO 協(xié)議 v5 用極簡的數字前綴編碼承載了四類語義命名空間連接0/4、數據事件2/5、確認3/6與斷開1配合二進制占位符 獨立附件幀的設計在可讀性與二進制支持之間取得平衡。理解4前綴的 Engine.IO 包裹層、CONNECT 顯式握手與 sid 的雙層結構是閱讀抓包、實現(xiàn)多語言服務器或排查connect_error問題的關鍵而解析器源碼 packages/socket.io-parser/lib/index.ts 與 binary.ts 以及 協(xié)議測試套件 則是逐條驗證協(xié)議規(guī)則的可靠依據?！久赓M下載鏈接】socket.ioBidirectional and low-latency communication for every platform項目地址: https://gitcode.com/gh_mirrors/so/socket.io創(chuàng)作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考