1 // Copyright 2021 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 QUICHE_BALSA_BALSA_VISITOR_INTERFACE_H_ 6 #define QUICHE_BALSA_BALSA_VISITOR_INTERFACE_H_ 7 8 #include <cstddef> 9 #include <memory> 10 11 #include "absl/strings/string_view.h" 12 #include "quiche/balsa/balsa_enums.h" 13 #include "quiche/balsa/balsa_headers.h" 14 #include "quiche/common/platform/api/quiche_export.h" 15 16 namespace quiche { 17 18 // By default the BalsaFrame instantiates a class derived from this interface 19 // that does absolutely nothing. If you'd prefer to have interesting 20 // functionality execute when any of the below functions are called by the 21 // BalsaFrame, then you should subclass it, and set an instantiation of your 22 // subclass as the current visitor for the BalsaFrame class using 23 // BalsaFrame::set_visitor(). 24 class QUICHE_EXPORT BalsaVisitorInterface { 25 public: ~BalsaVisitorInterface()26 virtual ~BalsaVisitorInterface() {} 27 28 // Summary: 29 // This is how the BalsaFrame passes you the raw input that it knows to be a 30 // part of the body. To be clear, every byte of the Balsa that isn't part of 31 // the header (or its framing), or trailers will be passed through this 32 // function. This includes data as well as chunking framing. 33 // Arguments: 34 // input - the raw input that is part of the body. 35 virtual void OnRawBodyInput(absl::string_view input) = 0; 36 37 // Summary: 38 // This is like OnRawBodyInput, but it will only include those parts of the 39 // body that would be stored by a program such as wget, i.e. the bytes 40 // indicating chunking will have been removed. Trailers will not be passed 41 // in through this function-- they'll be passed in through OnTrailerInput. 42 // Arguments: 43 // input - the part of the body. 44 virtual void OnBodyChunkInput(absl::string_view input) = 0; 45 46 // Summary: 47 // BalsaFrame passes the raw header data through this function. This is not 48 // cleaned up in any way. 49 // Arguments: 50 // input - raw header data. 51 virtual void OnHeaderInput(absl::string_view input) = 0; 52 53 // Summary: 54 // BalsaFrame passes the raw trailer data through this function. This is not 55 // cleaned up in any way. Note that trailers only occur in a message if 56 // there was a chunked encoding, and not always then. 57 // Arguments: 58 // input - raw trailer data. 59 virtual void OnTrailerInput(absl::string_view input) = 0; 60 61 // Summary: 62 // Since the BalsaFrame already has to parse the headers in order to 63 // determine proper framing, it might as well pass the parsed and cleaned-up 64 // results to whatever might need it. This function exists for that 65 // purpose-- parsed headers are passed into this function. 66 // Arguments: 67 // headers - contains the parsed headers in the order in which 68 // they occurred in the header. 69 virtual void ProcessHeaders(const BalsaHeaders& headers) = 0; 70 71 // Summary: 72 // Called when the trailers are framed and processed. This callback is only 73 // called when the trailers option is set in the framer. 74 // Arguments: 75 // trailers - contains the parsed headers in the order in which they 76 // occurred in the trailers. 77 virtual void OnTrailers(std::unique_ptr<BalsaHeaders> trailers) = 0; 78 79 // Summary: 80 // Called when the first line of the message is parsed, in this case, for a 81 // request. 82 // Arguments: 83 // line_input - the first line string, 84 // method_input - the method substring, 85 // request_uri_input - request uri substring, 86 // version_input - the version substring. 87 virtual void OnRequestFirstLineInput(absl::string_view line_input, 88 absl::string_view method_input, 89 absl::string_view request_uri, 90 absl::string_view version_input) = 0; 91 92 // Summary: 93 // Called when the first line of the message is parsed, in this case, for a 94 // response. 95 // Arguments: 96 // line_input - the first line string, 97 // version_input - the version substring, 98 // status_input - the status substring, 99 // reason_input - the reason substring. 100 virtual void OnResponseFirstLineInput(absl::string_view line_input, 101 absl::string_view version_input, 102 absl::string_view status_input, 103 absl::string_view reason_input) = 0; 104 105 // Summary: 106 // Called when a chunk length is parsed. 107 // Arguments: 108 // chunk length - the length of the next incoming chunk. 109 virtual void OnChunkLength(size_t chunk_length) = 0; 110 111 // Summary: 112 // BalsaFrame passes the raw chunk extension data through this function. 113 // The data is not cleaned up at all. 114 // Arguments: 115 // input - contains the bytes available for read. 116 virtual void OnChunkExtensionInput(absl::string_view input) = 0; 117 118 // Summary: 119 // Called when an interim response (response code 1xx) is framed and 120 // processed. This callback is mutually exclusive with ContinueHeaderDone(). 121 // Arguments: 122 // headers - contains the parsed headers in the order in which they occurred 123 // in the interim response. 124 virtual void OnInterimHeaders(std::unique_ptr<BalsaHeaders> headers) = 0; 125 126 // Summary: 127 // Called when the 100 Continue headers are framed and processed. This 128 // callback is mutually exclusive with OnInterimHeaders(). 129 // TODO(b/68801833): Remove this and update the OnInterimHeaders() comment. 130 virtual void ContinueHeaderDone() = 0; 131 132 // Summary: 133 // Called when the header is framed and processed. 134 virtual void HeaderDone() = 0; 135 136 // Summary: 137 // Called when the message is framed and processed. 138 virtual void MessageDone() = 0; 139 140 // Summary: 141 // Called when an error is detected 142 // Arguments: 143 // error_code - the error which is to be reported. 144 virtual void HandleError(BalsaFrameEnums::ErrorCode error_code) = 0; 145 146 // Summary: 147 // Called when something meriting a warning is detected 148 // Arguments: 149 // error_code - the warning which is to be reported. 150 virtual void HandleWarning(BalsaFrameEnums::ErrorCode error_code) = 0; 151 }; 152 153 } // namespace quiche 154 155 #endif // QUICHE_BALSA_BALSA_VISITOR_INTERFACE_H_ 156