1 // Copyright 2012 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef NET_WEBSOCKETS_WEBSOCKET_FRAME_PARSER_H_ 6 #define NET_WEBSOCKETS_WEBSOCKET_FRAME_PARSER_H_ 7 8 #include <stddef.h> 9 #include <stdint.h> 10 11 #include <memory> 12 #include <vector> 13 14 #include "base/containers/span.h" 15 #include "net/base/net_export.h" 16 #include "net/websockets/websocket_errors.h" 17 #include "net/websockets/websocket_frame.h" 18 19 namespace net { 20 21 // Parses WebSocket frames from byte stream. 22 // 23 // Specification of WebSocket frame format is available at 24 // <http://tools.ietf.org/html/rfc6455#section-5>. 25 // This class does *NOT* unmask frame payload. 26 class NET_EXPORT WebSocketFrameParser { 27 public: 28 WebSocketFrameParser(); 29 30 WebSocketFrameParser(const WebSocketFrameParser&) = delete; 31 WebSocketFrameParser& operator=(const WebSocketFrameParser&) = delete; 32 33 ~WebSocketFrameParser(); 34 35 // Decodes the given byte stream and stores parsed WebSocket frames in 36 // |frame_chunks|. 37 // Each WebSocketFrameChunk's payload is a subspan of [data, data + length). 38 // Thus callers must take care of its lifecycle. 39 // 40 // If the parser encounters invalid payload length format, Decode() fails 41 // and returns false. Once Decode() has failed, the parser refuses to decode 42 // any more data and future invocations of Decode() will simply return false. 43 // 44 // Payload data of parsed WebSocket frames may be incomplete; see comments in 45 // websocket_frame.h for more details. 46 bool Decode(const char* data, 47 size_t length, 48 std::vector<std::unique_ptr<WebSocketFrameChunk>>* frame_chunks); 49 50 // Returns kWebSocketNormalClosure if the parser has not failed to decode 51 // WebSocket frames. Otherwise returns WebSocketError which is defined in 52 // websocket_errors.h. We can convert net::WebSocketError to net::Error by 53 // using WebSocketErrorToNetError(). websocket_error()54 WebSocketError websocket_error() const { return websocket_error_; } 55 56 private: 57 // Tries to decode a frame header from |data|. 58 // If successful, this function updates 59 // |current_frame_header_|, and |masking_key_| (if available) and returns 60 // the number of consumed bytes in |data|. 61 // If there is not enough data in the remaining buffer to parse a frame 62 // header, this function returns 0 without doing anything. 63 // This function may update |websocket_error_| if it observes a corrupt frame. 64 size_t DecodeFrameHeader(base::span<const char> data); 65 66 // Decodes frame payload and creates a WebSocketFrameChunk object. 67 // This function updates |frame_offset_| after 68 // parsing. This function returns a frame object even if no payload data is 69 // available at this moment, so the receiver could make use of frame header 70 // information. If the end of frame is reached, this function clears 71 // |current_frame_header_|, |frame_offset_| and |masking_key_|. 72 std::unique_ptr<WebSocketFrameChunk> DecodeFramePayload( 73 bool first_chunk, 74 base::span<const char>* data); 75 76 // Internal buffer to store the data to parse header. 77 std::vector<char> incomplete_header_buffer_; 78 79 // Frame header and masking key of the current frame. 80 // |masking_key_| is filled with zeros if the current frame is not masked. 81 std::unique_ptr<WebSocketFrameHeader> current_frame_header_; 82 83 // Amount of payload data read so far for the current frame. 84 uint64_t frame_offset_ = 0; 85 86 WebSocketError websocket_error_ = kWebSocketNormalClosure; 87 }; 88 89 } // namespace net 90 91 #endif // NET_WEBSOCKETS_WEBSOCKET_FRAME_PARSER_H_ 92