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