src/net/http/http_stream_factory.h

   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 #ifndef NET_HTTP_HTTP_STREAM_FACTORY_H_
   6 #define NET_HTTP_HTTP_STREAM_FACTORY_H_
   7
   8 #include <list>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/basictypes.h"
  13 #include "base/memory/ref_counted.h"
  14 #include "base/strings/string16.h"
  15 #include "net/base/completion_callback.h"
  16 #include "net/base/load_states.h"
  17 #include "net/base/net_export.h"
  18 #include "net/base/request_priority.h"
  19 #include "net/http/http_server_properties.h"
  20 #include "net/socket/ssl_client_socket.h"
  21 // This file can be included from net/http even though
  22 // it is in net/websockets because it doesn't
  23 // introduce any link dependency to net/websockets.
  24 #include "net/websockets/websocket_handshake_stream_base.h"
  25
  26 class GURL;
  27
  28 namespace base {
  29 class Value;
  30 }
  31
  32 namespace net {
  33
  34 class AuthCredentials;
  35 class BoundNetLog;
  36 class HostMappingRules;
  37 class HostPortPair;
  38 class HttpAuthController;
  39 class HttpResponseInfo;
  40 class HttpServerProperties;
  41 class HttpStreamBase;
  42 class ProxyInfo;
  43 class SSLCertRequestInfo;
  44 class SSLInfo;
  45 struct HttpRequestInfo;
  46 struct SSLConfig;
  47
  48 // The HttpStreamRequest is the client's handle to the worker object which
  49 // handles the creation of an HttpStream.  While the HttpStream is being
  50 // created, this object is the creator's handle for interacting with the
  51 // HttpStream creation process.  The request is cancelled by deleting it, after
  52 // which no callbacks will be invoked.
  53 class NET_EXPORT_PRIVATE HttpStreamRequest {
  54  public:
  55   // The HttpStreamRequest::Delegate is a set of callback methods for a
  56   // HttpStreamRequestJob.  Generally, only one of these methods will be
  57   // called as a result of a stream request.
  58   class NET_EXPORT_PRIVATE Delegate {
  59    public:
  60     virtual ~Delegate() {}
  61
  62     // This is the success case for RequestStream.
  63     // |stream| is now owned by the delegate.
  64     // |used_ssl_config| indicates the actual SSL configuration used for this
  65     // stream, since the HttpStreamRequest may have modified the configuration
  66     // during stream processing.
  67     // |used_proxy_info| indicates the actual ProxyInfo used for this stream,
  68     // since the HttpStreamRequest performs the proxy resolution.
  69     virtual void OnStreamReady(
  70         const SSLConfig& used_ssl_config,
  71         const ProxyInfo& used_proxy_info,
  72         HttpStreamBase* stream) = 0;
  73
  74     // This is the success case for RequestWebSocketHandshakeStream.
  75     // |stream| is now owned by the delegate.
  76     // |used_ssl_config| indicates the actual SSL configuration used for this
  77     // stream, since the HttpStreamRequest may have modified the configuration
  78     // during stream processing.
  79     // |used_proxy_info| indicates the actual ProxyInfo used for this stream,
  80     // since the HttpStreamRequest performs the proxy resolution.
  81     virtual void OnWebSocketHandshakeStreamReady(
  82         const SSLConfig& used_ssl_config,
  83         const ProxyInfo& used_proxy_info,
  84         WebSocketHandshakeStreamBase* stream) = 0;
  85
  86     // This is the failure to create a stream case.
  87     // |used_ssl_config| indicates the actual SSL configuration used for this
  88     // stream, since the HttpStreamRequest may have modified the configuration
  89     // during stream processing.
  90     virtual void OnStreamFailed(int status,
  91                                 const SSLConfig& used_ssl_config) = 0;
  92
  93     // Called when we have a certificate error for the request.
  94     // |used_ssl_config| indicates the actual SSL configuration used for this
  95     // stream, since the HttpStreamRequest may have modified the configuration
  96     // during stream processing.
  97     virtual void OnCertificateError(int status,
  98                                     const SSLConfig& used_ssl_config,
  99                                     const SSLInfo& ssl_info) = 0;
 100
 101     // This is the failure case where we need proxy authentication during
 102     // proxy tunnel establishment.  For the tunnel case, we were unable to
 103     // create the HttpStream, so the caller provides the auth and then resumes
 104     // the HttpStreamRequest.
 105     //
 106     // For the non-tunnel case, the caller will discover the authentication
 107     // failure when reading response headers. At that point, he will handle the
 108     // authentication failure and restart the HttpStreamRequest entirely.
 109     //
 110     // Ownership of |auth_controller| and |proxy_response| are owned
 111     // by the HttpStreamRequest. |proxy_response| is not guaranteed to be usable
 112     // after the lifetime of this callback.  The delegate may take a reference
 113     // to |auth_controller| if it is needed beyond the lifetime of this
 114     // callback.
 115     //
 116     // |used_ssl_config| indicates the actual SSL configuration used for this
 117     // stream, since the HttpStreamRequest may have modified the configuration
 118     // during stream processing.
 119     virtual void OnNeedsProxyAuth(const HttpResponseInfo& proxy_response,
 120                                   const SSLConfig& used_ssl_config,
 121                                   const ProxyInfo& used_proxy_info,
 122                                   HttpAuthController* auth_controller) = 0;
 123
 124     // This is the failure for SSL Client Auth
 125     // Ownership of |cert_info| is retained by the HttpStreamRequest.  The
 126     // delegate may take a reference if it needs the cert_info beyond the
 127     // lifetime of this callback.
 128     virtual void OnNeedsClientAuth(const SSLConfig& used_ssl_config,
 129                                    SSLCertRequestInfo* cert_info) = 0;
 130
 131     // This is the failure of the CONNECT request through an HTTPS proxy.
 132     // Headers can be read from |response_info|, while the body can be read
 133     // from |stream|.
 134     //
 135     // |used_ssl_config| indicates the actual SSL configuration used for this
 136     // stream, since the HttpStreamRequest may have modified the configuration
 137     // during stream processing.
 138     //
 139     // |used_proxy_info| indicates the actual ProxyInfo used for this stream,
 140     // since the HttpStreamRequest performs the proxy resolution.
 141     //
 142     // Ownership of |stream| is transferred to the delegate.
 143     virtual void OnHttpsProxyTunnelResponse(
 144         const HttpResponseInfo& response_info,
 145         const SSLConfig& used_ssl_config,
 146         const ProxyInfo& used_proxy_info,
 147         HttpStreamBase* stream) = 0;
 148   };
 149
 150   virtual ~HttpStreamRequest() {}
 151
 152   // When a HttpStream creation process is stalled due to necessity
 153   // of Proxy authentication credentials, the delegate OnNeedsProxyAuth
 154   // will have been called.  It now becomes the delegate's responsibility
 155   // to collect the necessary credentials, and then call this method to
 156   // resume the HttpStream creation process.
 157   virtual int RestartTunnelWithProxyAuth(
 158       const AuthCredentials& credentials) = 0;
 159
 160   // Called when the priority of the parent transaction changes.
 161   virtual void SetPriority(RequestPriority priority) = 0;
 162
 163   // Returns the LoadState for the request.
 164   virtual LoadState GetLoadState() const = 0;
 165
 166   // Returns true if TLS/NPN was negotiated for this stream.
 167   virtual bool was_npn_negotiated() const = 0;
 168
 169   // Protocol negotiated with the server.
 170   virtual NextProto protocol_negotiated() const = 0;
 171
 172   // Returns true if this stream is being fetched over SPDY.
 173   virtual bool using_spdy() const = 0;
 174 };
 175
 176 // The HttpStreamFactory defines an interface for creating usable HttpStreams.
 177 class NET_EXPORT HttpStreamFactory {
 178  public:
 179   virtual ~HttpStreamFactory();
 180
 181   void ProcessAlternateProtocol(
 182       const base::WeakPtr<HttpServerProperties>& http_server_properties,
 183       const std::string& alternate_protocol_str,
 184       const HostPortPair& http_host_port_pair);
 185
 186   GURL ApplyHostMappingRules(const GURL& url, HostPortPair* endpoint);
 187
 188   // Virtual interface methods.
 189
 190   // Request a stream.
 191   // Will call delegate->OnStreamReady on successful completion.
 192   virtual HttpStreamRequest* RequestStream(
 193       const HttpRequestInfo& info,
 194       RequestPriority priority,
 195       const SSLConfig& server_ssl_config,
 196       const SSLConfig& proxy_ssl_config,
 197       HttpStreamRequest::Delegate* delegate,
 198       const BoundNetLog& net_log) = 0;
 199
 200   // Request a WebSocket handshake stream.
 201   // Will call delegate->OnWebSocketHandshakeStreamReady on successful
 202   // completion.
 203   virtual HttpStreamRequest* RequestWebSocketHandshakeStream(
 204       const HttpRequestInfo& info,
 205       RequestPriority priority,
 206       const SSLConfig& server_ssl_config,
 207       const SSLConfig& proxy_ssl_config,
 208       HttpStreamRequest::Delegate* delegate,
 209       WebSocketHandshakeStreamBase::CreateHelper* create_helper,
 210       const BoundNetLog& net_log) = 0;
 211
 212   // Requests that enough connections for |num_streams| be opened.
 213   virtual void PreconnectStreams(int num_streams,
 214                                  const HttpRequestInfo& info,
 215                                  RequestPriority priority,
 216                                  const SSLConfig& server_ssl_config,
 217                                  const SSLConfig& proxy_ssl_config) = 0;
 218
 219   // If pipelining is supported, creates a Value summary of the currently active
 220   // pipelines. Caller assumes ownership of the returned value. Otherwise,
 221   // returns an empty Value.
 222   virtual base::Value* PipelineInfoToValue() const = 0;
 223
 224   virtual const HostMappingRules* GetHostMappingRules() const = 0;
 225
 226   // Static settings
 227
 228   // Reset all static settings to initialized values. Used to init test suite.
 229   static void ResetStaticSettingsToInit();
 230
 231   // Turns spdy on or off.
 232   static void set_spdy_enabled(bool value) {
 233     spdy_enabled_ = value;
 234     if (!spdy_enabled_) {
 235       delete next_protos_;
 236       next_protos_ = NULL;
 237     }
 238   }
 239   static bool spdy_enabled() { return spdy_enabled_; }
 240
 241   // Controls whether or not we use the Alternate-Protocol header.
 242   static void set_use_alternate_protocols(bool value) {
 243     use_alternate_protocols_ = value;
 244   }
 245   static bool use_alternate_protocols() { return use_alternate_protocols_; }
 246
 247   // Controls whether or not we use ssl when in spdy mode.
 248   static void set_force_spdy_over_ssl(bool value) {
 249     force_spdy_over_ssl_ = value;
 250   }
 251   static bool force_spdy_over_ssl() {
 252     return force_spdy_over_ssl_;
 253   }
 254
 255   // Controls whether or not we use spdy without npn.
 256   static void set_force_spdy_always(bool value) {
 257     force_spdy_always_ = value;
 258   }
 259   static bool force_spdy_always() { return force_spdy_always_; }
 260
 261   // Add a URL to exclude from forced SPDY.
 262   static void add_forced_spdy_exclusion(const std::string& value);
 263   // Check if a HostPortPair is excluded from using spdy.
 264   static bool HasSpdyExclusion(const HostPortPair& endpoint);
 265
 266   // Sets http/1.1 as the only protocol supported via NPN or Alternate-Protocol.
 267   static void EnableNpnHttpOnly();
 268
 269   // Sets http/1.1, quic, and spdy/3 as the protocols supported via
 270   // NPN or Alternate-Protocol.
 271   static void EnableNpnSpdy3();
 272
 273   // Sets http/1.1, quic, spdy/3, and spdy/3.1 as the protocols
 274   // supported via NPN or Alternate-Protocol.
 275   static void EnableNpnSpdy31();
 276
 277   // Sets http/1.1, quic, spdy/2, spdy/3, and spdy/3.1 as the
 278   // protocols supported via NPN or Alternate-Protocol.
 279   static void EnableNpnSpdy31WithSpdy2();
 280
 281   // Sets http/1.1, quic, spdy/3, spdy/3.1, and spdy/4 (http/2) as the
 282   // protocols supported via NPN or Alternate-Protocol.
 283   static void EnableNpnSpdy4Http2();
 284
 285   // Sets the protocols supported by NPN (next protocol negotiation) during the
 286   // SSL handshake as well as by HTTP Alternate-Protocol.
 287   static void SetNextProtos(const std::vector<NextProto>& value);
 288   static bool has_next_protos() { return next_protos_ != NULL; }
 289   static const std::vector<std::string>& next_protos() {
 290     return *next_protos_;
 291   }
 292
 293  protected:
 294   HttpStreamFactory();
 295
 296  private:
 297   // |protocol| must be a valid protocol value.
 298   static bool IsProtocolEnabled(AlternateProtocol protocol);
 299   static void SetProtocolEnabled(AlternateProtocol protocol);
 300   static void ResetEnabledProtocols();
 301
 302   static std::vector<std::string>* next_protos_;
 303   static bool enabled_protocols_[NUM_VALID_ALTERNATE_PROTOCOLS];
 304   static bool spdy_enabled_;
 305   static bool use_alternate_protocols_;
 306   static bool force_spdy_over_ssl_;
 307   static bool force_spdy_always_;
 308   static std::list<HostPortPair>* forced_spdy_exclusions_;
 309
 310   DISALLOW_COPY_AND_ASSIGN(HttpStreamFactory);
 311 };
 312
 313 }  // namespace net
 314
 315 #endif  // NET_HTTP_HTTP_STREAM_FACTORY_H_