1 // Copyright 2012 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_BASE_NETWORK_DELEGATE_H_ 6 #define NET_BASE_NETWORK_DELEGATE_H_ 7 8 #include <stdint.h> 9 10 #include <optional> 11 #include <set> 12 #include <string> 13 14 #include "base/functional/callback.h" 15 #include "base/gtest_prod_util.h" 16 #include "base/threading/thread_checker.h" 17 #include "net/base/auth.h" 18 #include "net/base/completion_once_callback.h" 19 #include "net/base/net_export.h" 20 #include "net/cookies/canonical_cookie.h" 21 #include "net/cookies/cookie_inclusion_status.h" 22 #include "net/cookies/cookie_setting_override.h" 23 #include "net/cookies/site_for_cookies.h" 24 #include "net/first_party_sets/first_party_set_metadata.h" 25 #include "net/first_party_sets/first_party_sets_cache_filter.h" 26 #include "net/proxy_resolution/proxy_retry_info.h" 27 28 class GURL; 29 30 namespace url { 31 class Origin; 32 } 33 34 namespace net { 35 36 // NOTE: Layering violations! 37 // We decided to accept these violations (depending 38 // on other net/ submodules from net/base/), because otherwise NetworkDelegate 39 // would have to be broken up into too many smaller interfaces targeted to each 40 // submodule. Also, since the lower levels in net/ may callback into higher 41 // levels, we may encounter dangerous casting issues. 42 // 43 // NOTE: It is not okay to add any compile-time dependencies on symbols outside 44 // of net/base here, because we have a net_base library. Forward declarations 45 // are ok. 46 class CookieOptions; 47 class CookieInclusionStatus; 48 class HttpRequestHeaders; 49 class HttpResponseHeaders; 50 class IPEndPoint; 51 class URLRequest; 52 53 class NET_EXPORT NetworkDelegate { 54 public: 55 virtual ~NetworkDelegate(); 56 57 // Notification interface called by the network stack. Note that these 58 // functions mostly forward to the private virtuals. They also add some sanity 59 // checking on parameters. See the corresponding virtuals for explanations of 60 // the methods and their arguments. 61 int NotifyBeforeURLRequest(URLRequest* request, 62 CompletionOnceCallback callback, 63 GURL* new_url); 64 using OnBeforeStartTransactionCallback = 65 base::OnceCallback<void(int, const std::optional<HttpRequestHeaders>&)>; 66 int NotifyBeforeStartTransaction(URLRequest* request, 67 const HttpRequestHeaders& headers, 68 OnBeforeStartTransactionCallback callback); 69 int NotifyHeadersReceived( 70 URLRequest* request, 71 CompletionOnceCallback callback, 72 const HttpResponseHeaders* original_response_headers, 73 scoped_refptr<HttpResponseHeaders>* override_response_headers, 74 const IPEndPoint& remote_endpoint, 75 std::optional<GURL>* preserve_fragment_on_redirect_url); 76 void NotifyBeforeRedirect(URLRequest* request, 77 const GURL& new_location); 78 void NotifyResponseStarted(URLRequest* request, int net_error); 79 void NotifyCompleted(URLRequest* request, bool started, int net_error); 80 void NotifyURLRequestDestroyed(URLRequest* request); 81 void NotifyPACScriptError(int line_number, const std::u16string& error); 82 bool AnnotateAndMoveUserBlockedCookies( 83 const URLRequest& request, 84 const net::FirstPartySetMetadata& first_party_set_metadata, 85 CookieAccessResultList& maybe_included_cookies, 86 CookieAccessResultList& excluded_cookies); 87 bool CanSetCookie(const URLRequest& request, 88 const net::CanonicalCookie& cookie, 89 CookieOptions* options, 90 const net::FirstPartySetMetadata& first_party_set_metadata, 91 CookieInclusionStatus* inclusion_status); 92 93 // PrivacySetting is kStateDisallowed iff the given |url| has to be 94 // requested over connection that is not tracked by the server. 95 // 96 // Usually PrivacySetting is kStateAllowed, unless user privacy settings 97 // block cookies from being get or set. 98 // 99 // It may be set to kPartitionedStateAllowedOnly if the request allows 100 // partitioned state to be sent over the connection, but unpartitioned 101 // state should be blocked. 102 enum class PrivacySetting { 103 kStateAllowed, 104 kStateDisallowed, 105 // First-party requests will never have this setting. 106 kPartitionedStateAllowedOnly, 107 }; 108 PrivacySetting ForcePrivacyMode(const URLRequest& request) const; 109 110 bool CancelURLRequestWithPolicyViolatingReferrerHeader( 111 const URLRequest& request, 112 const GURL& target_url, 113 const GURL& referrer_url) const; 114 115 bool CanQueueReportingReport(const url::Origin& origin) const; 116 void CanSendReportingReports( 117 std::set<url::Origin> origins, 118 base::OnceCallback<void(std::set<url::Origin>)> result_callback) const; 119 bool CanSetReportingClient(const url::Origin& origin, 120 const GURL& endpoint) const; 121 bool CanUseReportingClient(const url::Origin& origin, 122 const GURL& endpoint) const; 123 124 protected: 125 // Adds the given ExclusionReason to all cookies in 126 // `mayble_included_cookies`, and moves the contents of 127 // `maybe_included_cookies` to `excluded_cookies`. 128 static void ExcludeAllCookies( 129 net::CookieInclusionStatus::ExclusionReason reason, 130 net::CookieAccessResultList& maybe_included_cookies, 131 net::CookieAccessResultList& excluded_cookies); 132 133 // Moves any cookie in `maybe_included_cookies` that has an ExclusionReason 134 // into `excluded_cookies`. 135 static void MoveExcludedCookies( 136 net::CookieAccessResultList& maybe_included_cookies, 137 net::CookieAccessResultList& excluded_cookies); 138 139 THREAD_CHECKER(thread_checker_); 140 141 private: 142 FRIEND_TEST_ALL_PREFIXES(NetworkDelegateTest, ExcludeAllCookies); 143 FRIEND_TEST_ALL_PREFIXES(NetworkDelegateTest, MoveExcludedCookies); 144 // This is the interface for subclasses of NetworkDelegate to implement. These 145 // member functions will be called by the respective public notification 146 // member function, which will perform basic sanity checking. 147 // 148 // Note that these member functions refer to URLRequests which may be canceled 149 // or destroyed at any time. Implementations which return ERR_IO_PENDING must 150 // also implement OnURLRequestDestroyed and OnCompleted to handle cancelation. 151 // See below for details. 152 // 153 // (NetworkDelegateImpl has default implementations of these member functions. 154 // NetworkDelegate implementations should consider subclassing 155 // NetworkDelegateImpl.) 156 157 // Called before a request is sent. Allows the delegate to rewrite the URL 158 // being fetched by modifying |new_url|. If set, the URL must be valid. The 159 // reference fragment from the original URL is not automatically appended to 160 // |new_url|; callers are responsible for copying the reference fragment if 161 // desired. 162 // 163 // Returns OK to continue with the request, ERR_IO_PENDING if the result is 164 // not ready yet, and any other status code to cancel the request. If 165 // returning ERR_IO_PENDING, call |callback| when the result is ready. Note, 166 // however, that a pending operation may be cancelled by 167 // OnURLRequestDestroyed. Once cancelled, |request| and |new_url| become 168 // invalid and |callback| may not be called. 169 // 170 // The default implementation returns OK (continue with request). 171 virtual int OnBeforeURLRequest(URLRequest* request, 172 CompletionOnceCallback callback, 173 GURL* new_url) = 0; 174 175 // Called right before the network transaction starts. Allows the delegate to 176 // read |headers| and modify them by passing a new copy to |callback| before 177 // they get sent out. 178 // 179 // Returns OK to continue with the request, ERR_IO_PENDING if the result is 180 // not ready yet, and any other status code to cancel the request. If 181 // returning ERR_IO_PENDING, call |callback| when the result is ready. Note, 182 // however, that a pending operation may be cancelled by OnURLRequestDestroyed 183 // or OnCompleted. Once cancelled, |request| and |headers| become invalid and 184 // |callback| may not be called. 185 // 186 // The default implementation returns OK (continue with request). 187 virtual int OnBeforeStartTransaction( 188 URLRequest* request, 189 const HttpRequestHeaders& headers, 190 OnBeforeStartTransactionCallback callback) = 0; 191 192 // Called for HTTP requests when the headers have been received. 193 // |original_response_headers| contains the headers as received over the 194 // network, these must not be modified. |override_response_headers| can be set 195 // to new values, that should be considered as overriding 196 // |original_response_headers|. 197 // If the response is a redirect, and the Location response header value is 198 // identical to |preserve_fragment_on_redirect_url|, then the redirect is 199 // never blocked and the reference fragment is not copied from the original 200 // URL to the redirection target. 201 // 202 // Returns OK to continue with the request, ERR_IO_PENDING if the result is 203 // not ready yet, and any other status code to cancel the request. If 204 // returning ERR_IO_PENDING, call |callback| when the result is ready. Note, 205 // however, that a pending operation may be cancelled by 206 // OnURLRequestDestroyed. Once cancelled, |request|, 207 // |original_response_headers|, |override_response_headers|, and 208 // |preserve_fragment_on_redirect_url| become invalid and |callback| may not 209 // be called. 210 virtual int OnHeadersReceived( 211 URLRequest* request, 212 CompletionOnceCallback callback, 213 const HttpResponseHeaders* original_response_headers, 214 scoped_refptr<HttpResponseHeaders>* override_response_headers, 215 const IPEndPoint& remote_endpoint, 216 std::optional<GURL>* preserve_fragment_on_redirect_url) = 0; 217 218 // Called right after a redirect response code was received. |new_location| is 219 // only valid for the duration of the call. 220 virtual void OnBeforeRedirect(URLRequest* request, 221 const GURL& new_location) = 0; 222 223 // This corresponds to URLRequestDelegate::OnResponseStarted. 224 virtual void OnResponseStarted(URLRequest* request, int net_error) = 0; 225 226 // Indicates that the URL request has been completed or failed. 227 // |started| indicates whether the request has been started. If false, 228 // some information like the socket address is not available. 229 virtual void OnCompleted(URLRequest* request, 230 bool started, 231 int net_error) = 0; 232 233 // Called when an URLRequest is being destroyed. Note that the request is 234 // being deleted, so it's not safe to call any methods that may result in 235 // a virtual method call. 236 virtual void OnURLRequestDestroyed(URLRequest* request) = 0; 237 238 // Corresponds to ProxyResolverJSBindings::OnError. 239 virtual void OnPACScriptError(int line_number, 240 const std::u16string& error) = 0; 241 242 // Called when reading cookies to allow the network delegate to block access 243 // to individual cookies, by adding the appropriate ExclusionReason and moving 244 // them to the `excluded_cookies` list. This method will never be invoked 245 // when LOAD_DO_NOT_SEND_COOKIES is specified. 246 // 247 // Returns false if the delegate has blocked access to all cookies; true 248 // otherwise. 249 virtual bool OnAnnotateAndMoveUserBlockedCookies( 250 const URLRequest& request, 251 const net::FirstPartySetMetadata& first_party_set_metadata, 252 net::CookieAccessResultList& maybe_included_cookies, 253 net::CookieAccessResultList& excluded_cookies) = 0; 254 255 // Called when a cookie is set to allow the network delegate to block access 256 // to the cookie. If the cookie is allowed, `inclusion_status` may be updated 257 // to include reason to warn about the given cookie according to the user 258 // cookie-blocking settings; Otherwise, `inclusion_status` may be updated with 259 // the proper exclusion reasons, if not then proper reasons need to be 260 // manually added in the caller. This method will never be invoked when 261 // LOAD_DO_NOT_SAVE_COOKIES is specified. 262 virtual bool OnCanSetCookie( 263 const URLRequest& request, 264 const CanonicalCookie& cookie, 265 CookieOptions* options, 266 const net::FirstPartySetMetadata& first_party_set_metadata, 267 CookieInclusionStatus* inclusion_status) = 0; 268 269 virtual PrivacySetting OnForcePrivacyMode( 270 const URLRequest& request) const = 0; 271 272 // Called when the |referrer_url| for requesting |target_url| during handling 273 // of the |request| is does not comply with the referrer policy (e.g. a 274 // secure referrer for an insecure initial target). 275 // Returns true if the request should be cancelled. Otherwise, the referrer 276 // header is stripped from the request. 277 virtual bool OnCancelURLRequestWithPolicyViolatingReferrerHeader( 278 const URLRequest& request, 279 const GURL& target_url, 280 const GURL& referrer_url) const = 0; 281 282 virtual bool OnCanQueueReportingReport(const url::Origin& origin) const = 0; 283 284 virtual void OnCanSendReportingReports( 285 std::set<url::Origin> origins, 286 base::OnceCallback<void(std::set<url::Origin>)> result_callback) 287 const = 0; 288 289 virtual bool OnCanSetReportingClient(const url::Origin& origin, 290 const GURL& endpoint) const = 0; 291 292 virtual bool OnCanUseReportingClient(const url::Origin& origin, 293 const GURL& endpoint) const = 0; 294 }; 295 296 } // namespace net 297 298 #endif // NET_BASE_NETWORK_DELEGATE_H_ 299