1 // Copyright 2015 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_HTTP_BIDIRECTIONAL_STREAM_IMPL_H_ 6 #define NET_HTTP_BIDIRECTIONAL_STREAM_IMPL_H_ 7 8 #include <stdint.h> 9 10 #include <memory> 11 #include <vector> 12 13 #include "base/memory/scoped_refptr.h" 14 #include "net/base/load_timing_info.h" 15 #include "net/base/net_export.h" 16 #include "net/socket/next_proto.h" 17 #include "net/third_party/quiche/src/quiche/common/http/http_header_block.h" 18 #include "net/traffic_annotation/network_traffic_annotation.h" 19 20 namespace base { 21 class OneShotTimer; 22 } // namespace base 23 24 namespace net { 25 26 class IOBuffer; 27 class NetLogWithSource; 28 struct BidirectionalStreamRequestInfo; 29 struct NetErrorDetails; 30 31 // Exposes an interface to do HTTP/2 bidirectional streaming. 32 // Note that only one ReadData or SendData should be in flight until the 33 // operation completes synchronously or asynchronously. 34 // BidirectionalStreamImpl once created by HttpStreamFactory should be owned 35 // by BidirectionalStream. 36 class NET_EXPORT_PRIVATE BidirectionalStreamImpl { 37 public: 38 // Delegate to handle BidirectionalStreamImpl events. 39 class NET_EXPORT_PRIVATE Delegate { 40 public: 41 Delegate(); 42 43 Delegate(const Delegate&) = delete; 44 Delegate& operator=(const Delegate&) = delete; 45 46 // Called when the stream is ready for reading and writing. 47 // The delegate may call BidirectionalStreamImpl::ReadData to start reading, 48 // call BidirectionalStreamImpl::SendData to send data, 49 // or call BidirectionalStreamImpl::Cancel to cancel the stream. 50 // The delegate should not call BidirectionalStreamImpl::Cancel 51 // during this callback. 52 // |request_headers_sent| if true, request headers have been sent. If false, 53 // SendRequestHeaders() needs to be explicitly called. 54 virtual void OnStreamReady(bool request_headers_sent) = 0; 55 56 // Called when response headers are received. 57 // This is called at most once for the lifetime of a stream. 58 // The delegate may call BidirectionalStreamImpl::ReadData to start 59 // reading, call BidirectionalStreamImpl::SendData to send data, 60 // or call BidirectionalStreamImpl::Cancel to cancel the stream. 61 virtual void OnHeadersReceived( 62 const quiche::HttpHeaderBlock& response_headers) = 0; 63 64 // Called when read is completed asynchronously. |bytes_read| specifies how 65 // much data is available. 66 // The delegate may call BidirectionalStreamImpl::ReadData to continue 67 // reading, call BidirectionalStreamImpl::SendData to send data, 68 // or call BidirectionalStreamImpl::Cancel to cancel the stream. 69 virtual void OnDataRead(int bytes_read) = 0; 70 71 // Called when the entire buffer passed through SendData is sent. 72 // The delegate may call BidirectionalStreamImpl::ReadData to continue 73 // reading, or call BidirectionalStreamImpl::SendData to send data. 74 // The delegate should not call BidirectionalStreamImpl::Cancel 75 // during this callback. 76 virtual void OnDataSent() = 0; 77 78 // Called when trailers are received. This is called as soon as trailers 79 // are received, which can happen before a read completes. 80 // The delegate is able to continue reading if there is no pending read and 81 // EOF has not been received, or to send data if there is no pending send. 82 virtual void OnTrailersReceived( 83 const quiche::HttpHeaderBlock& trailers) = 0; 84 85 // Called when an error occurred. Do not call into the stream after this 86 // point. No other delegate functions will be called after this. 87 virtual void OnFailed(int status) = 0; 88 89 protected: 90 virtual ~Delegate(); 91 }; 92 93 BidirectionalStreamImpl(); 94 95 BidirectionalStreamImpl(const BidirectionalStreamImpl&) = delete; 96 BidirectionalStreamImpl& operator=(const BidirectionalStreamImpl&) = delete; 97 98 // |this| should not be destroyed during Delegate::OnHeadersSent or 99 // Delegate::OnDataSent. 100 virtual ~BidirectionalStreamImpl(); 101 102 // Starts the BidirectionalStreamImpl and sends request headers. 103 // |send_request_headers_automatically| if true, request headers will be sent 104 // automatically when stream is negotiated. If false, request headers will be 105 // sent only when SendRequestHeaders() is invoked or with next 106 // SendData/SendvData. 107 virtual void Start(const BidirectionalStreamRequestInfo* request_info, 108 const NetLogWithSource& net_log, 109 bool send_request_headers_automatically, 110 BidirectionalStreamImpl::Delegate* delegate, 111 std::unique_ptr<base::OneShotTimer> timer, 112 const NetworkTrafficAnnotationTag& traffic_annotation) = 0; 113 114 // Sends request headers to server. 115 // When |send_request_headers_automatically_| is 116 // false and OnStreamReady() is invoked with request_headers_sent = false, 117 // headers will be combined with next SendData/SendvData unless this 118 // method is called first, in which case headers will be sent separately 119 // without delay. 120 // (This method cannot be called when |send_request_headers_automatically_| is 121 // true nor when OnStreamReady() is invoked with request_headers_sent = true, 122 // since headers have been sent by the stream when stream is negotiated 123 // successfully.) 124 virtual void SendRequestHeaders() = 0; 125 126 // Reads at most |buf_len| bytes into |buf|. Returns the number of bytes read, 127 // ERR_IO_PENDING if the read is to be completed asynchronously, or an error 128 // code if any error occurred. If returns 0, there is no more data to read. 129 // This should not be called before Delegate::OnHeadersReceived is invoked, 130 // and should not be called again unless it returns with number greater than 131 // 0 or until Delegate::OnDataRead is invoked. 132 virtual int ReadData(IOBuffer* buf, int buf_len) = 0; 133 134 // Sends data. This should not be called be called before 135 // Delegate::OnHeadersSent is invoked, and should not be called again until 136 // Delegate::OnDataSent is invoked. If |end_stream| is true, the DATA frame 137 // will have an END_STREAM flag. 138 virtual void SendvData(const std::vector<scoped_refptr<IOBuffer>>& buffers, 139 const std::vector<int>& lengths, 140 bool end_stream) = 0; 141 142 // Returns the protocol used by this stream. If stream has not been 143 // established, return kProtoUnknown. 144 virtual NextProto GetProtocol() const = 0; 145 146 // Total number of bytes received over the network of SPDY data, headers, and 147 // push_promise frames associated with this stream, including the size of 148 // frame headers, after SSL decryption and not including proxy overhead. 149 virtual int64_t GetTotalReceivedBytes() const = 0; 150 151 // Total number of bytes sent over the network of SPDY frames associated with 152 // this stream, including the size of frame headers, before SSL encryption and 153 // not including proxy overhead. Note that some SPDY frames such as pings are 154 // not associated with any stream, and are not included in this value. 155 virtual int64_t GetTotalSentBytes() const = 0; 156 157 // Populates the connection establishment part of |load_timing_info|, and 158 // socket reuse info. Return true if LoadTimingInfo is obtained successfully 159 // and false otherwise. 160 virtual bool GetLoadTimingInfo(LoadTimingInfo* load_timing_info) const = 0; 161 162 // Get the network error details this stream is encountering. 163 // Fills in |details| if it is available; leaves |details| unchanged if it 164 // is unavailable. 165 virtual void PopulateNetErrorDetails(NetErrorDetails* details) = 0; 166 }; 167 168 } // namespace net 169 170 #endif // NET_HTTP_BIDIRECTIONAL_STREAM_IMPL_H_ 171