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_BASE_NETWORK_DELEGATE_H_ 6 #define NET_BASE_NETWORK_DELEGATE_H_ 7 8 #include <string> 9 10 #include "base/callback.h" 11 #include "base/strings/string16.h" 12 #include "base/threading/non_thread_safe.h" 13 #include "net/base/auth.h" 14 #include "net/base/completion_callback.h" 15 #include "net/cookies/canonical_cookie.h" 16 17 class GURL; 18 19 namespace base { 20 class FilePath; 21 } 22 23 namespace net { 24 25 // NOTE: Layering violations! 26 // We decided to accept these violations (depending 27 // on other net/ submodules from net/base/), because otherwise NetworkDelegate 28 // would have to be broken up into too many smaller interfaces targeted to each 29 // submodule. Also, since the lower levels in net/ may callback into higher 30 // levels, we may encounter dangerous casting issues. 31 // 32 // NOTE: It is not okay to add any compile-time dependencies on symbols outside 33 // of net/base here, because we have a net_base library. Forward declarations 34 // are ok. 35 class CookieOptions; 36 class HttpRequestHeaders; 37 class HttpResponseHeaders; 38 class ProxyInfo; 39 class ProxyServer; 40 class ProxyService; 41 class SocketStream; 42 class URLRequest; 43 44 class NET_EXPORT NetworkDelegate : public base::NonThreadSafe { 45 public: 46 // AuthRequiredResponse indicates how a NetworkDelegate handles an 47 // OnAuthRequired call. It's placed in this file to prevent url_request.h 48 // from having to include network_delegate.h. 49 enum AuthRequiredResponse { 50 AUTH_REQUIRED_RESPONSE_NO_ACTION, 51 AUTH_REQUIRED_RESPONSE_SET_AUTH, 52 AUTH_REQUIRED_RESPONSE_CANCEL_AUTH, 53 AUTH_REQUIRED_RESPONSE_IO_PENDING, 54 }; 55 typedef base::Callback<void(AuthRequiredResponse)> AuthCallback; 56 57 virtual ~NetworkDelegate() {} 58 59 // Notification interface called by the network stack. Note that these 60 // functions mostly forward to the private virtuals. They also add some sanity 61 // checking on parameters. See the corresponding virtuals for explanations of 62 // the methods and their arguments. 63 int NotifyBeforeURLRequest(URLRequest* request, 64 const CompletionCallback& callback, 65 GURL* new_url); 66 void NotifyResolveProxy(const GURL& url, 67 int load_flags, 68 const ProxyService& proxy_service, 69 ProxyInfo* result); 70 void NotifyProxyFallback(const ProxyServer& bad_proxy, 71 int net_error); 72 int NotifyBeforeSendHeaders(URLRequest* request, 73 const CompletionCallback& callback, 74 HttpRequestHeaders* headers); 75 void NotifyBeforeSendProxyHeaders(URLRequest* request, 76 const ProxyInfo& proxy_info, 77 HttpRequestHeaders* headers); 78 void NotifySendHeaders(URLRequest* request, 79 const HttpRequestHeaders& headers); 80 int NotifyHeadersReceived( 81 URLRequest* request, 82 const CompletionCallback& callback, 83 const HttpResponseHeaders* original_response_headers, 84 scoped_refptr<HttpResponseHeaders>* override_response_headers, 85 GURL* allowed_unsafe_redirect_url); 86 void NotifyBeforeRedirect(URLRequest* request, 87 const GURL& new_location); 88 void NotifyResponseStarted(URLRequest* request); 89 void NotifyRawBytesRead(const URLRequest& request, int bytes_read); 90 void NotifyCompleted(URLRequest* request, bool started); 91 void NotifyURLRequestDestroyed(URLRequest* request); 92 void NotifyPACScriptError(int line_number, const base::string16& error); 93 AuthRequiredResponse NotifyAuthRequired(URLRequest* request, 94 const AuthChallengeInfo& auth_info, 95 const AuthCallback& callback, 96 AuthCredentials* credentials); 97 bool CanGetCookies(const URLRequest& request, 98 const CookieList& cookie_list); 99 bool CanSetCookie(const URLRequest& request, 100 const std::string& cookie_line, 101 CookieOptions* options); 102 bool CanAccessFile(const URLRequest& request, 103 const base::FilePath& path) const; 104 bool CanThrottleRequest(const URLRequest& request) const; 105 bool CanEnablePrivacyMode(const GURL& url, 106 const GURL& first_party_for_cookies) const; 107 108 int NotifyBeforeSocketStreamConnect(SocketStream* socket, 109 const CompletionCallback& callback); 110 111 bool CancelURLRequestWithPolicyViolatingReferrerHeader( 112 const URLRequest& request, 113 const GURL& target_url, 114 const GURL& referrer_url) const; 115 116 private: 117 // This is the interface for subclasses of NetworkDelegate to implement. These 118 // member functions will be called by the respective public notification 119 // member function, which will perform basic sanity checking. 120 121 // Called before a request is sent. Allows the delegate to rewrite the URL 122 // being fetched by modifying |new_url|. If set, the URL must be valid. The 123 // reference fragment from the original URL is not automatically appended to 124 // |new_url|; callers are responsible for copying the reference fragment if 125 // desired. 126 // |callback| and |new_url| are valid only until OnURLRequestDestroyed is 127 // called for this request. Returns a net status code, generally either OK to 128 // continue with the request or ERR_IO_PENDING if the result is not ready yet. 129 // A status code other than OK and ERR_IO_PENDING will cancel the request and 130 // report the status code as the reason. 131 // 132 // The default implementation returns OK (continue with request). 133 virtual int OnBeforeURLRequest(URLRequest* request, 134 const CompletionCallback& callback, 135 GURL* new_url); 136 137 // Called as the proxy is being resolved for |url|. Allows the delegate to 138 // override the proxy resolution decision made by ProxyService. The delegate 139 // may override the decision by modifying the ProxyInfo |result|. 140 virtual void OnResolveProxy(const GURL& url, 141 int load_flags, 142 const ProxyService& proxy_service, 143 ProxyInfo* result); 144 145 // Called when use of |bad_proxy| fails due to |net_error|. |net_error| is 146 // the network error encountered, if any, and OK if the fallback was 147 // for a reason other than a network error (e.g. the proxy service was 148 // explicitly directed to skip a proxy). 149 virtual void OnProxyFallback(const ProxyServer& bad_proxy, 150 int net_error); 151 152 // Called right before the HTTP headers are sent. Allows the delegate to 153 // read/write |headers| before they get sent out. |callback| and |headers| are 154 // valid only until OnCompleted or OnURLRequestDestroyed is called for this 155 // request. 156 // See OnBeforeURLRequest for return value description. Returns OK by default. 157 virtual int OnBeforeSendHeaders(URLRequest* request, 158 const CompletionCallback& callback, 159 HttpRequestHeaders* headers); 160 161 // Called after a proxy connection. Allows the delegate to read/write 162 // |headers| before they get sent out. |headers| is valid only until 163 // OnCompleted or OnURLRequestDestroyed is called for this request. 164 virtual void OnBeforeSendProxyHeaders(URLRequest* request, 165 const ProxyInfo& proxy_info, 166 HttpRequestHeaders* headers); 167 168 // Called right before the HTTP request(s) are being sent to the network. 169 // |headers| is only valid until OnCompleted or OnURLRequestDestroyed is 170 // called for this request. 171 virtual void OnSendHeaders(URLRequest* request, 172 const HttpRequestHeaders& headers); 173 174 // Called for HTTP requests when the headers have been received. 175 // |original_response_headers| contains the headers as received over the 176 // network, these must not be modified. |override_response_headers| can be set 177 // to new values, that should be considered as overriding 178 // |original_response_headers|. 179 // If the response is a redirect, and the Location response header value is 180 // identical to |allowed_unsafe_redirect_url|, then the redirect is never 181 // blocked and the reference fragment is not copied from the original URL 182 // to the redirection target. 183 // 184 // |callback|, |original_response_headers|, and |override_response_headers| 185 // are only valid until OnURLRequestDestroyed is called for this request. 186 // See OnBeforeURLRequest for return value description. Returns OK by default. 187 virtual int OnHeadersReceived( 188 URLRequest* request, 189 const CompletionCallback& callback, 190 const HttpResponseHeaders* original_response_headers, 191 scoped_refptr<HttpResponseHeaders>* override_response_headers, 192 GURL* allowed_unsafe_redirect_url); 193 194 // Called right after a redirect response code was received. 195 // |new_location| is only valid until OnURLRequestDestroyed is called for this 196 // request. 197 virtual void OnBeforeRedirect(URLRequest* request, 198 const GURL& new_location); 199 200 // This corresponds to URLRequestDelegate::OnResponseStarted. 201 virtual void OnResponseStarted(URLRequest* request); 202 203 // Called every time we read raw bytes. 204 virtual void OnRawBytesRead(const URLRequest& request, int bytes_read); 205 206 // Indicates that the URL request has been completed or failed. 207 // |started| indicates whether the request has been started. If false, 208 // some information like the socket address is not available. 209 virtual void OnCompleted(URLRequest* request, bool started); 210 211 // Called when an URLRequest is being destroyed. Note that the request is 212 // being deleted, so it's not safe to call any methods that may result in 213 // a virtual method call. 214 virtual void OnURLRequestDestroyed(URLRequest* request); 215 216 // Corresponds to ProxyResolverJSBindings::OnError. 217 virtual void OnPACScriptError(int line_number, 218 const base::string16& error); 219 220 // Called when a request receives an authentication challenge 221 // specified by |auth_info|, and is unable to respond using cached 222 // credentials. |callback| and |credentials| must be non-NULL, and must 223 // be valid until OnURLRequestDestroyed is called for |request|. 224 // 225 // The following return values are allowed: 226 // - AUTH_REQUIRED_RESPONSE_NO_ACTION: |auth_info| is observed, but 227 // no action is being taken on it. 228 // - AUTH_REQUIRED_RESPONSE_SET_AUTH: |credentials| is filled in with 229 // a username and password, which should be used in a response to 230 // |auth_info|. 231 // - AUTH_REQUIRED_RESPONSE_CANCEL_AUTH: The authentication challenge 232 // should not be attempted. 233 // - AUTH_REQUIRED_RESPONSE_IO_PENDING: The action will be decided 234 // asynchronously. |callback| will be invoked when the decision is made, 235 // and one of the other AuthRequiredResponse values will be passed in with 236 // the same semantics as described above. 237 virtual AuthRequiredResponse OnAuthRequired( 238 URLRequest* request, 239 const AuthChallengeInfo& auth_info, 240 const AuthCallback& callback, 241 AuthCredentials* credentials); 242 243 // Called when reading cookies to allow the network delegate to block access 244 // to the cookie. This method will never be invoked when 245 // LOAD_DO_NOT_SEND_COOKIES is specified. 246 virtual bool OnCanGetCookies(const URLRequest& request, 247 const CookieList& cookie_list); 248 249 // Called when a cookie is set to allow the network delegate to block access 250 // to the cookie. This method will never be invoked when 251 // LOAD_DO_NOT_SAVE_COOKIES is specified. 252 virtual bool OnCanSetCookie(const URLRequest& request, 253 const std::string& cookie_line, 254 CookieOptions* options); 255 256 // Called when a file access is attempted to allow the network delegate to 257 // allow or block access to the given file path. Returns true if access is 258 // allowed. 259 virtual bool OnCanAccessFile(const URLRequest& request, 260 const base::FilePath& path) const; 261 262 // Returns true if the given request may be rejected when the 263 // URLRequestThrottlerManager believes the server servicing the 264 // request is overloaded or down. 265 virtual bool OnCanThrottleRequest(const URLRequest& request) const; 266 267 // Returns true if the given |url| has to be requested over connection that 268 // is not tracked by the server. Usually is false, unless user privacy 269 // settings block cookies from being get or set. 270 virtual bool OnCanEnablePrivacyMode( 271 const GURL& url, 272 const GURL& first_party_for_cookies) const; 273 274 // Called before a SocketStream tries to connect. 275 // See OnBeforeURLRequest for return value description. Returns OK by default. 276 virtual int OnBeforeSocketStreamConnect( 277 SocketStream* socket, const CompletionCallback& callback); 278 279 // Called when the |referrer_url| for requesting |target_url| during handling 280 // of the |request| is does not comply with the referrer policy (e.g. a 281 // secure referrer for an insecure initial target). 282 // Returns true if the request should be cancelled. Otherwise, the referrer 283 // header is stripped from the request. 284 virtual bool OnCancelURLRequestWithPolicyViolatingReferrerHeader( 285 const URLRequest& request, 286 const GURL& target_url, 287 const GURL& referrer_url) const; 288 }; 289 290 } // namespace net 291 292 #endif // NET_BASE_NETWORK_DELEGATE_H_ 293