OLD | NEW |
(Empty) | |
| 1 // Copyright 2016 The Chromium Authors. All rights reserved. |
| 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_HTTP2_DECODER_HTTP2_FRAME_DECODER_LISTENER_H_ |
| 6 #define NET_HTTP2_DECODER_HTTP2_FRAME_DECODER_LISTENER_H_ |
| 7 |
| 8 // Http2FrameDecoderListener is the interface which the HTTP/2 decoder uses |
| 9 // to report the decoded frames to a listener. |
| 10 // |
| 11 // The general design is to assume that the listener will copy the data it needs |
| 12 // (e.g. frame headers) and will keep track of the implicit state of the |
| 13 // decoding process (i.e. the decoder maintains just the information it needs in |
| 14 // order to perform the decoding). Therefore, the parameters are just those with |
| 15 // (potentially) new data, not previously provided info about the current frame. |
| 16 // |
| 17 // The calls are described as if they are made in quick succession, i.e. one |
| 18 // after another, but of course the decoder needs input to decode, and the |
| 19 // decoder will only call the listener once the necessary input has been |
| 20 // provided. For example: OnDataStart can only be called once the 9 bytes of |
| 21 // of an HTTP/2 common frame header have been received. The decoder will call |
| 22 // the listener methods as soon as possible to avoid almost all buffering. |
| 23 // |
| 24 // The listener interface is designed so that it is possible to exactly |
| 25 // reconstruct the serialized frames, with the exception of reserved bits, |
| 26 // including in the frame header's flags and stream_id fields, which will have |
| 27 // been cleared before the methods below are called. |
| 28 |
| 29 #include <stddef.h> |
| 30 |
| 31 #include <type_traits> |
| 32 |
| 33 #include "net/http2/http2_constants.h" |
| 34 #include "net/http2/http2_structures.h" |
| 35 |
| 36 namespace net { |
| 37 |
| 38 // TODO(jamessynge): Consider sorting the methods by frequency of call, if that |
| 39 // helps at all. |
| 40 class Http2FrameDecoderListener { |
| 41 public: |
| 42 Http2FrameDecoderListener() {} |
| 43 virtual ~Http2FrameDecoderListener() {} |
| 44 |
| 45 // Called once the common frame header has been decoded for any frame, and |
| 46 // before any of the methods below, which will also be called. This method is |
| 47 // included in this interface only for the purpose of supporting SpdyFramer |
| 48 // semantics via an adapter. This is the only method that has a non-void |
| 49 // return type, and this is just so that Http2FrameDecoderAdapter (called |
| 50 // from SpdyFramer) can more readily pass existing tests that expect decoding |
| 51 // to stop if the headers alone indicate an error. Return false to stop |
| 52 // decoding just after decoding the header, else return true to continue |
| 53 // decoding. |
| 54 // TODO(jamessynge): Remove OnFrameHeader once done with supporting |
| 55 // SpdyFramer's exact states. |
| 56 virtual bool OnFrameHeader(const Http2FrameHeader& header) = 0; |
| 57 |
| 58 ////////////////////////////////////////////////////////////////////////////// |
| 59 |
| 60 // Called once the common frame header has been decoded for a DATA frame, |
| 61 // before examining the frame's payload, after which: |
| 62 // OnPadLength will be called if header.IsPadded() is true, i.e. if the |
| 63 // PADDED flag is set; |
| 64 // OnDataPayload will be called as the non-padding portion of the payload |
| 65 // is available until all of it has been provided; |
| 66 // OnPadding will be called if the frame is padded AND the Pad Length field |
| 67 // is greater than zero; |
| 68 // OnDataEnd will be called last. If the frame is unpadded and has no |
| 69 // payload, then this will be called immediately after OnDataStart. |
| 70 virtual void OnDataStart(const Http2FrameHeader& header) = 0; |
| 71 |
| 72 // Called when the next non-padding portion of a DATA frame's payload is |
| 73 // received. |
| 74 // |data| The start of |len| bytes of data. |
| 75 // |len| The length of the data buffer. Maybe zero in some cases, which does |
| 76 // not mean anything special. |
| 77 virtual void OnDataPayload(const char* data, size_t len) = 0; |
| 78 |
| 79 // Called after an entire DATA frame has been received. |
| 80 // If header.IsEndStream() == true, this is the last data for the stream. |
| 81 virtual void OnDataEnd() = 0; |
| 82 |
| 83 // Called once the common frame header has been decoded for a HEADERS frame, |
| 84 // before examining the frame's payload, after which: |
| 85 // OnPadLength will be called if header.IsPadded() is true, i.e. if the |
| 86 // PADDED flag is set; |
| 87 // OnHeadersPriority will be called if header.HasPriority() is true, i.e. if |
| 88 // the frame has the PRIORITY flag; |
| 89 // OnHpackFragment as the remainder of the non-padding payload is available |
| 90 // until all if has been provided; |
| 91 // OnPadding will be called if the frame is padded AND the Pad Length field |
| 92 // is greater than zero; |
| 93 // OnHeadersEnd will be called last; If the frame is unpadded and has no |
| 94 // payload, then this will be called immediately after OnHeadersStart; |
| 95 // OnHeadersEnd indicates the end of the HPACK block only if the frame |
| 96 // header had the END_HEADERS flag set, else the END_HEADERS should be |
| 97 // looked for on a subsequent CONTINUATION frame. |
| 98 virtual void OnHeadersStart(const Http2FrameHeader& header) = 0; |
| 99 |
| 100 // Called when a HEADERS frame is received with the PRIORITY flag set and |
| 101 // the priority fields have been decoded. |
| 102 virtual void OnHeadersPriority( |
| 103 const Http2PriorityFields& priority_fields) = 0; |
| 104 |
| 105 // Called when a fragment (i.e. some or all of an HPACK Block) is received; |
| 106 // this may be part of a HEADERS, PUSH_PROMISE or CONTINUATION frame. |
| 107 // |data| The start of |len| bytes of data. |
| 108 // |len| The length of the data buffer. Maybe zero in some cases, which does |
| 109 // not mean anything special, except that it simplified the decoder. |
| 110 virtual void OnHpackFragment(const char* data, size_t len) = 0; |
| 111 |
| 112 // Called after an entire HEADERS frame has been received. The frame is the |
| 113 // end of the HEADERS if the END_HEADERS flag is set; else there should be |
| 114 // CONTINUATION frames after this frame. |
| 115 virtual void OnHeadersEnd() = 0; |
| 116 |
| 117 // Called when an entire PRIORITY frame has been decoded. |
| 118 virtual void OnPriorityFrame(const Http2FrameHeader& header, |
| 119 const Http2PriorityFields& priority_fields) = 0; |
| 120 |
| 121 // Called once the common frame header has been decoded for a CONTINUATION |
| 122 // frame, before examining the frame's payload, after which: |
| 123 // OnHpackFragment as the frame's payload is available until all of it |
| 124 // has been provided; |
| 125 // OnContinuationEnd will be called last; If the frame has no payload, |
| 126 // then this will be called immediately after OnContinuationStart; |
| 127 // the HPACK block is at an end if and only if the frame header passed |
| 128 // to OnContinuationStart had the END_HEADERS flag set. |
| 129 virtual void OnContinuationStart(const Http2FrameHeader& header) = 0; |
| 130 |
| 131 // Called after an entire CONTINUATION frame has been received. The frame is |
| 132 // the end of the HEADERS if the END_HEADERS flag is set. |
| 133 virtual void OnContinuationEnd() = 0; |
| 134 |
| 135 // Called when Pad Length field has been read. Applies to DATA and HEADERS |
| 136 // frames. For PUSH_PROMISE frames, the Pad Length + 1 is provided in the |
| 137 // OnPushPromiseStart call as total_padding_length. |
| 138 virtual void OnPadLength(size_t pad_length) = 0; |
| 139 |
| 140 // Called when padding is skipped over. |
| 141 virtual void OnPadding(const char* padding, size_t skipped_length) = 0; |
| 142 |
| 143 // Called when an entire RST_STREAM frame has been decoded. |
| 144 // This is the only callback for RST_STREAM frames. |
| 145 virtual void OnRstStream(const Http2FrameHeader& header, |
| 146 Http2ErrorCode error_code) = 0; |
| 147 |
| 148 // Called once the common frame header has been decoded for a SETTINGS frame |
| 149 // without the ACK flag, before examining the frame's payload, after which: |
| 150 // OnSetting will be called in turn for each pair of settings parameter and |
| 151 // value found in the payload; |
| 152 // OnSettingsEnd will be called last; If the frame has no payload, |
| 153 // then this will be called immediately after OnSettingsStart. |
| 154 // The frame header is passed so that the caller can check the stream_id, |
| 155 // which should be zero, but that hasn't been checked by the decoder. |
| 156 virtual void OnSettingsStart(const Http2FrameHeader& header) = 0; |
| 157 |
| 158 // Called for each setting parameter and value within a SETTINGS frame. |
| 159 virtual void OnSetting(const Http2SettingFields& setting_fields) = 0; |
| 160 |
| 161 // Called after parsing the complete payload of SETTINGS frame (non-ACK). |
| 162 virtual void OnSettingsEnd() = 0; |
| 163 |
| 164 // Called when an entire SETTINGS frame, with the ACK flag, has been decoded. |
| 165 virtual void OnSettingsAck(const Http2FrameHeader& header) = 0; |
| 166 |
| 167 // Called just before starting to process the HPACK block of a PUSH_PROMISE |
| 168 // frame. The Pad Length field has already been decoded at this point, so |
| 169 // OnPadLength will not be called; note that total_padding_length is Pad |
| 170 // Length + 1. After OnPushPromiseStart: |
| 171 // OnHpackFragment as the remainder of the non-padding payload is available |
| 172 // until all if has been provided; |
| 173 // OnPadding will be called if the frame is padded AND the Pad Length field |
| 174 // is greater than zero (i.e. total_padding_length > 1); |
| 175 // OnPushPromiseEnd will be called last; If the frame is unpadded and has no |
| 176 // payload, then this will be called immediately after OnPushPromiseStart. |
| 177 virtual void OnPushPromiseStart(const Http2FrameHeader& header, |
| 178 const Http2PushPromiseFields& promise, |
| 179 size_t total_padding_length) = 0; |
| 180 |
| 181 // Called after all of the HPACK block fragment and padding of a PUSH_PROMISE |
| 182 // has been decoded and delivered to the listener. This call indicates the end |
| 183 // of the HPACK block if and only if the frame header had the END_HEADERS flag |
| 184 // set (i.e. header.IsEndHeaders() is true); otherwise the next block must be |
| 185 // a CONTINUATION frame with the same stream id (not the same promised stream |
| 186 // id). |
| 187 virtual void OnPushPromiseEnd() = 0; |
| 188 |
| 189 // Called when an entire PING frame, without the ACK flag, has been decoded. |
| 190 virtual void OnPing(const Http2FrameHeader& header, |
| 191 const Http2PingFields& ping) = 0; |
| 192 |
| 193 // Called when an entire PING frame, with the ACK flag, has been decoded. |
| 194 virtual void OnPingAck(const Http2FrameHeader& header, |
| 195 const Http2PingFields& ping) = 0; |
| 196 |
| 197 // Called after parsing a GOAWAY frame's header and fixed size fields, after |
| 198 // which: |
| 199 // OnGoAwayOpaqueData will be called as opaque data of the payload becomes |
| 200 // available to the decoder, until all of it has been provided to the |
| 201 // listener; |
| 202 // OnGoAwayEnd will be called last, after all the opaque data has been |
| 203 // provided to the listener; if there is no opaque data, then OnGoAwayEnd |
| 204 // will be called immediately after OnGoAwayStart. |
| 205 virtual void OnGoAwayStart(const Http2FrameHeader& header, |
| 206 const Http2GoAwayFields& goaway) = 0; |
| 207 |
| 208 // Called when the next portion of a GOAWAY frame's payload is received. |
| 209 // |data| The start of |len| bytes of opaque data. |
| 210 // |len| The length of the opaque data buffer. Maybe zero in some cases, |
| 211 // which does not mean anything special. |
| 212 virtual void OnGoAwayOpaqueData(const char* data, size_t len) = 0; |
| 213 |
| 214 // Called after finishing decoding all of a GOAWAY frame. |
| 215 virtual void OnGoAwayEnd() = 0; |
| 216 |
| 217 // Called when an entire WINDOW_UPDATE frame has been decoded. The |
| 218 // window_size_increment is required to be non-zero, but that has not been |
| 219 // checked. If header.stream_id==0, the connection's flow control window is |
| 220 // being increased, else the specified stream's flow control is being |
| 221 // increased. |
| 222 virtual void OnWindowUpdate(const Http2FrameHeader& header, |
| 223 uint32_t window_size_increment) = 0; |
| 224 |
| 225 // Called when an ALTSVC frame header and origin length have been parsed. |
| 226 // Either or both lengths may be zero. After OnAltSvcStart: |
| 227 // OnAltSvcOriginData will be called until all of the (optional) Origin |
| 228 // has been provided; |
| 229 // OnAltSvcValueData will be called until all of the Alt-Svc-Field-Value |
| 230 // has been provided; |
| 231 // OnAltSvcEnd will called last, after all of the origin and |
| 232 // Alt-Svc-Field-Value have been delivered to the listener. |
| 233 virtual void OnAltSvcStart(const Http2FrameHeader& header, |
| 234 size_t origin_length, |
| 235 size_t value_length) = 0; |
| 236 |
| 237 // Called when decoding the (optional) origin of an ALTSVC; |
| 238 // the field is uninterpreted. |
| 239 virtual void OnAltSvcOriginData(const char* data, size_t len) = 0; |
| 240 |
| 241 // Called when decoding the Alt-Svc-Field-Value of an ALTSVC; |
| 242 // the field is uninterpreted. |
| 243 virtual void OnAltSvcValueData(const char* data, size_t len) = 0; |
| 244 |
| 245 // Called after decoding all of a ALTSVC frame and providing to the listener |
| 246 // via the above methods. |
| 247 virtual void OnAltSvcEnd() = 0; |
| 248 |
| 249 // Called when the common frame header has been decoded, but the frame type |
| 250 // is unknown, after which: |
| 251 // OnUnknownPayload is called as the payload of the frame is provided to the |
| 252 // decoder, until all of the payload has been decoded; |
| 253 // OnUnknownEnd will called last, after the entire frame of the unknown type |
| 254 // has been decoded and provided to the listener. |
| 255 virtual void OnUnknownStart(const Http2FrameHeader& header) = 0; |
| 256 |
| 257 // Called when the payload of an unknown frame type is received. |
| 258 // |data| A buffer containing the data received. |
| 259 // |len| The length of the data buffer. |
| 260 virtual void OnUnknownPayload(const char* data, size_t len) = 0; |
| 261 |
| 262 // Called after decoding all of the payload of an unknown frame type. |
| 263 virtual void OnUnknownEnd() = 0; |
| 264 |
| 265 ////////////////////////////////////////////////////////////////////////////// |
| 266 // Below here are events indicating a problem has been detected during |
| 267 // decoding (i.e. the received frames are malformed in some way). |
| 268 |
| 269 // Padding field (uint8) has a value that is too large (i.e. the amount of |
| 270 // padding is greater than the remainder of the payload that isn't required). |
| 271 // From RFC Section 6.1, DATA: |
| 272 // If the length of the padding is the length of the frame payload or |
| 273 // greater, the recipient MUST treat this as a connection error |
| 274 // (Section 5.4.1) of type PROTOCOL_ERROR. |
| 275 // The same is true for HEADERS and PUSH_PROMISE. |
| 276 virtual void OnPaddingTooLong(const Http2FrameHeader& header, |
| 277 size_t missing_length) = 0; |
| 278 |
| 279 // Frame size error. Depending upon the effected frame, this may or may not |
| 280 // require terminating the connection, though that is probably the best thing |
| 281 // to do. |
| 282 // From RFC Section 4.2, Frame Size: |
| 283 // An endpoint MUST send an error code of FRAME_SIZE_ERROR if a frame |
| 284 // exceeds the size defined in SETTINGS_MAX_FRAME_SIZE, exceeds any limit |
| 285 // defined for the frame type, or is too small to contain mandatory frame |
| 286 // data. A frame size error in a frame that could alter the state of the |
| 287 // the entire connection MUST be treated as a connection error |
| 288 // (Section 5.4.1); this includes any frame carrying a header block |
| 289 // (Section 4.3) (that is, HEADERS, PUSH_PROMISE, and CONTINUATION), |
| 290 // SETTINGS, and any frame with a stream identifier of 0. |
| 291 virtual void OnFrameSizeError(const Http2FrameHeader& header) = 0; |
| 292 }; |
| 293 |
| 294 // Do nothing for each call. Useful for ignoring a frame that is invalid. |
| 295 class Http2FrameDecoderNoOpListener : public Http2FrameDecoderListener { |
| 296 public: |
| 297 Http2FrameDecoderNoOpListener() {} |
| 298 ~Http2FrameDecoderNoOpListener() override {} |
| 299 |
| 300 // TODO(jamessynge): Remove OnFrameHeader once done with supporting |
| 301 // SpdyFramer's exact states. |
| 302 bool OnFrameHeader(const Http2FrameHeader& header) override; |
| 303 |
| 304 void OnDataStart(const Http2FrameHeader& header) override {} |
| 305 void OnDataPayload(const char* data, size_t len) override {} |
| 306 void OnDataEnd() override {} |
| 307 void OnHeadersStart(const Http2FrameHeader& header) override {} |
| 308 void OnHeadersPriority(const Http2PriorityFields& priority) override {} |
| 309 void OnHpackFragment(const char* data, size_t len) override {} |
| 310 void OnHeadersEnd() override {} |
| 311 void OnPriorityFrame(const Http2FrameHeader& header, |
| 312 const Http2PriorityFields& priority) override {} |
| 313 void OnContinuationStart(const Http2FrameHeader& header) override {} |
| 314 void OnContinuationEnd() override {} |
| 315 void OnPadLength(size_t trailing_length) override {} |
| 316 void OnPadding(const char* padding, size_t skipped_length) override {} |
| 317 void OnRstStream(const Http2FrameHeader& header, |
| 318 Http2ErrorCode error_code) override {} |
| 319 void OnSettingsStart(const Http2FrameHeader& header) override {} |
| 320 void OnSetting(const Http2SettingFields& setting_fields) override {} |
| 321 void OnSettingsEnd() override {} |
| 322 void OnSettingsAck(const Http2FrameHeader& header) override {} |
| 323 void OnPushPromiseStart(const Http2FrameHeader& header, |
| 324 const Http2PushPromiseFields& promise, |
| 325 size_t total_padding_length) override {} |
| 326 void OnPushPromiseEnd() override {} |
| 327 void OnPing(const Http2FrameHeader& header, |
| 328 const Http2PingFields& ping) override {} |
| 329 void OnPingAck(const Http2FrameHeader& header, |
| 330 const Http2PingFields& ping) override {} |
| 331 void OnGoAwayStart(const Http2FrameHeader& header, |
| 332 const Http2GoAwayFields& goaway) override {} |
| 333 void OnGoAwayOpaqueData(const char* data, size_t len) override {} |
| 334 void OnGoAwayEnd() override {} |
| 335 void OnWindowUpdate(const Http2FrameHeader& header, |
| 336 uint32_t increment) override {} |
| 337 void OnAltSvcStart(const Http2FrameHeader& header, |
| 338 size_t origin_length, |
| 339 size_t value_length) override {} |
| 340 void OnAltSvcOriginData(const char* data, size_t len) override {} |
| 341 void OnAltSvcValueData(const char* data, size_t len) override {} |
| 342 void OnAltSvcEnd() override {} |
| 343 void OnUnknownStart(const Http2FrameHeader& header) override {} |
| 344 void OnUnknownPayload(const char* data, size_t len) override {} |
| 345 void OnUnknownEnd() override {} |
| 346 void OnPaddingTooLong(const Http2FrameHeader& header, |
| 347 size_t missing_length) override {} |
| 348 void OnFrameSizeError(const Http2FrameHeader& header) override {} |
| 349 }; |
| 350 |
| 351 static_assert(!std::is_abstract<Http2FrameDecoderNoOpListener>(), |
| 352 "Http2FrameDecoderNoOpListener ought to be concrete."); |
| 353 |
| 354 } // namespace net |
| 355 |
| 356 #endif // NET_HTTP2_DECODER_HTTP2_FRAME_DECODER_LISTENER_H_ |
OLD | NEW |