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