1// Copyright (c) 2012 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// HttpStreamBase is an interface for reading and writing data to an
6// HTTP-like stream that keeps the client agnostic of the actual underlying
7// transport layer.  This provides an abstraction for HttpStream and
8// WebSocketStream.
9
10#ifndef NET_HTTP_HTTP_STREAM_BASE_H_
11#define NET_HTTP_HTTP_STREAM_BASE_H_
12
13#include <string>
14
15#include "base/basictypes.h"
16#include "base/memory/scoped_ptr.h"
17#include "net/base/completion_callback.h"
18#include "net/base/net_export.h"
19#include "net/base/request_priority.h"
20#include "net/base/upload_progress.h"
21
22namespace net {
23
24class BoundNetLog;
25class HttpNetworkSession;
26class HttpRequestHeaders;
27struct HttpRequestInfo;
28class HttpResponseInfo;
29class IOBuffer;
30struct LoadTimingInfo;
31class SSLCertRequestInfo;
32class SSLInfo;
33
34class NET_EXPORT_PRIVATE HttpStreamBase {
35 public:
36  HttpStreamBase() {}
37  virtual ~HttpStreamBase() {}
38
39  // Initialize stream.  Must be called before calling SendRequest().
40  // |request_info| must outlive the HttpStreamBase.
41  // Returns a net error code, possibly ERR_IO_PENDING.
42  virtual int InitializeStream(const HttpRequestInfo* request_info,
43                               RequestPriority priority,
44                               const BoundNetLog& net_log,
45                               const CompletionCallback& callback) = 0;
46
47  // Writes the headers and uploads body data to the underlying socket.
48  // ERR_IO_PENDING is returned if the operation could not be completed
49  // synchronously, in which case the result will be passed to the callback
50  // when available. Returns OK on success.
51  // |response| must outlive the HttpStreamBase.
52  virtual int SendRequest(const HttpRequestHeaders& request_headers,
53                          HttpResponseInfo* response,
54                          const CompletionCallback& callback) = 0;
55
56  // Reads from the underlying socket until the response headers have been
57  // completely received. ERR_IO_PENDING is returned if the operation could
58  // not be completed synchronously, in which case the result will be passed
59  // to the callback when available. Returns OK on success.  The response
60  // headers are available in the HttpResponseInfo returned by GetResponseInfo
61  virtual int ReadResponseHeaders(const CompletionCallback& callback) = 0;
62
63  // Provides access to HttpResponseInfo (owned by HttpStream).
64  virtual const HttpResponseInfo* GetResponseInfo() const = 0;
65
66  // Reads response body data, up to |buf_len| bytes. |buf_len| should be a
67  // reasonable size (<2MB). The number of bytes read is returned, or an
68  // error is returned upon failure.  0 indicates that the request has been
69  // fully satisfied and there is no more data to read.
70  // ERR_CONNECTION_CLOSED is returned when the connection has been closed
71  // prematurely.  ERR_IO_PENDING is returned if the operation could not be
72  // completed synchronously, in which case the result will be passed to the
73  // callback when available. If the operation is not completed immediately,
74  // the socket acquires a reference to the provided buffer until the callback
75  // is invoked or the socket is destroyed.
76  virtual int ReadResponseBody(IOBuffer* buf, int buf_len,
77                               const CompletionCallback& callback) = 0;
78
79  // Closes the stream.
80  // |not_reusable| indicates if the stream can be used for further requests.
81  // In the case of HTTP, where we re-use the byte-stream (e.g. the connection)
82  // this means we need to close the connection; in the case of SPDY, where the
83  // underlying stream is never reused, it has no effect.
84  // TODO(mbelshe): We should figure out how to fold the not_reusable flag
85  //                into the stream implementation itself so that the caller
86  //                does not need to pass it at all.  We might also be able to
87  //                eliminate the SetConnectionReused() below.
88  virtual void Close(bool not_reusable) = 0;
89
90  // Indicates if the response body has been completely read.
91  virtual bool IsResponseBodyComplete() const = 0;
92
93  // Indicates that the end of the response is detectable. This means that
94  // the response headers indicate either chunked encoding or content length.
95  // If neither is sent, the server must close the connection for us to detect
96  // the end of the response.
97  // TODO(rch): Rename this method, so that it is clear why it exists
98  // particularly as it applies to QUIC and SPDY for which the end of the
99  // response is always findable.
100  virtual bool CanFindEndOfResponse() const = 0;
101
102  // A stream exists on top of a connection.  If the connection has been used
103  // to successfully exchange data in the past, error handling for the
104  // stream is done differently.  This method returns true if the underlying
105  // connection is reused or has been connected and idle for some time.
106  virtual bool IsConnectionReused() const = 0;
107  virtual void SetConnectionReused() = 0;
108
109  // Checks whether the current state of the underlying connection
110  // allows it to be reused.
111  virtual bool IsConnectionReusable() const = 0;
112
113  // Populates the connection establishment part of |load_timing_info|, and
114  // socket ID.  |load_timing_info| must have all null times when called.
115  // Returns false and does nothing if there is no underlying connection, either
116  // because one has yet to be assigned to the stream, or because the underlying
117  // socket has been closed.
118  //
119  // In practice, this means that this function will always succeed any time
120  // between when the full headers have been received and the stream has been
121  // closed.
122  virtual bool GetLoadTimingInfo(LoadTimingInfo* load_timing_info) const = 0;
123
124  // Get the SSLInfo associated with this stream's connection.  This should
125  // only be called for streams over SSL sockets, otherwise the behavior is
126  // undefined.
127  virtual void GetSSLInfo(SSLInfo* ssl_info) = 0;
128
129  // Get the SSLCertRequestInfo associated with this stream's connection.
130  // This should only be called for streams over SSL sockets, otherwise the
131  // behavior is undefined.
132  virtual void GetSSLCertRequestInfo(SSLCertRequestInfo* cert_request_info) = 0;
133
134  // HACK(willchan): Really, we should move the HttpResponseDrainer logic into
135  // the HttpStream implementation. This is just a quick hack.
136  virtual bool IsSpdyHttpStream() const = 0;
137
138  // In the case of an HTTP error or redirect, flush the response body (usually
139  // a simple error or "this page has moved") so that we can re-use the
140  // underlying connection. This stream is responsible for deleting itself when
141  // draining is complete.
142  virtual void Drain(HttpNetworkSession* session) = 0;
143
144 private:
145  DISALLOW_COPY_AND_ASSIGN(HttpStreamBase);
146};
147
148}  // namespace net
149
150#endif  // NET_HTTP_HTTP_STREAM_BASE_H_
151