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 // Does the same as ExcludeAllCookies but will still include 134 // cookies that are partitioned if cookies are not disabled 135 // globally. 136 static void ExcludeAllCookiesExceptPartitioned( 137 net::CookieInclusionStatus::ExclusionReason reason, 138 net::CookieAccessResultList& maybe_included_cookies, 139 net::CookieAccessResultList& excluded_cookies); 140 141 // Moves any cookie in `maybe_included_cookies` that has an ExclusionReason 142 // into `excluded_cookies`. 143 static void MoveExcludedCookies( 144 net::CookieAccessResultList& maybe_included_cookies, 145 net::CookieAccessResultList& excluded_cookies); 146 147 THREAD_CHECKER(thread_checker_); 148 149 private: 150 FRIEND_TEST_ALL_PREFIXES(NetworkDelegateTest, ExcludeAllCookies); 151 FRIEND_TEST_ALL_PREFIXES(NetworkDelegateTest, MoveExcludedCookies); 152 // This is the interface for subclasses of NetworkDelegate to implement. These 153 // member functions will be called by the respective public notification 154 // member function, which will perform basic sanity checking. 155 // 156 // Note that these member functions refer to URLRequests which may be canceled 157 // or destroyed at any time. Implementations which return ERR_IO_PENDING must 158 // also implement OnURLRequestDestroyed and OnCompleted to handle cancelation. 159 // See below for details. 160 // 161 // (NetworkDelegateImpl has default implementations of these member functions. 162 // NetworkDelegate implementations should consider subclassing 163 // NetworkDelegateImpl.) 164 165 // Called before a request is sent. Allows the delegate to rewrite the URL 166 // being fetched by modifying |new_url|. If set, the URL must be valid. The 167 // reference fragment from the original URL is not automatically appended to 168 // |new_url|; callers are responsible for copying the reference fragment if 169 // desired. 170 // 171 // Returns OK to continue with the request, ERR_IO_PENDING if the result is 172 // not ready yet, and any other status code to cancel the request. If 173 // returning ERR_IO_PENDING, call |callback| when the result is ready. Note, 174 // however, that a pending operation may be cancelled by 175 // OnURLRequestDestroyed. Once cancelled, |request| and |new_url| become 176 // invalid and |callback| may not be called. 177 // 178 // The default implementation returns OK (continue with request). 179 virtual int OnBeforeURLRequest(URLRequest* request, 180 CompletionOnceCallback callback, 181 GURL* new_url) = 0; 182 183 // Called right before the network transaction starts. Allows the delegate to 184 // read |headers| and modify them by passing a new copy to |callback| before 185 // they get sent out. 186 // 187 // Returns OK to continue with the request, ERR_IO_PENDING if the result is 188 // not ready yet, and any other status code to cancel the request. If 189 // returning ERR_IO_PENDING, call |callback| when the result is ready. Note, 190 // however, that a pending operation may be cancelled by OnURLRequestDestroyed 191 // or OnCompleted. Once cancelled, |request| and |headers| become invalid and 192 // |callback| may not be called. 193 // 194 // The default implementation returns OK (continue with request). 195 virtual int OnBeforeStartTransaction( 196 URLRequest* request, 197 const HttpRequestHeaders& headers, 198 OnBeforeStartTransactionCallback callback) = 0; 199 200 // Called for HTTP requests when the headers have been received. 201 // |original_response_headers| contains the headers as received over the 202 // network, these must not be modified. |override_response_headers| can be set 203 // to new values, that should be considered as overriding 204 // |original_response_headers|. 205 // If the response is a redirect, and the Location response header value is 206 // identical to |preserve_fragment_on_redirect_url|, then the redirect is 207 // never blocked and the reference fragment is not copied from the original 208 // URL to the redirection target. 209 // 210 // Returns OK to continue with the request, ERR_IO_PENDING if the result is 211 // not ready yet, and any other status code to cancel the request. If 212 // returning ERR_IO_PENDING, call |callback| when the result is ready. Note, 213 // however, that a pending operation may be cancelled by 214 // OnURLRequestDestroyed. Once cancelled, |request|, 215 // |original_response_headers|, |override_response_headers|, and 216 // |preserve_fragment_on_redirect_url| become invalid and |callback| may not 217 // be called. 218 virtual int OnHeadersReceived( 219 URLRequest* request, 220 CompletionOnceCallback callback, 221 const HttpResponseHeaders* original_response_headers, 222 scoped_refptr<HttpResponseHeaders>* override_response_headers, 223 const IPEndPoint& remote_endpoint, 224 std::optional<GURL>* preserve_fragment_on_redirect_url) = 0; 225 226 // Called right after a redirect response code was received. |new_location| is 227 // only valid for the duration of the call. 228 virtual void OnBeforeRedirect(URLRequest* request, 229 const GURL& new_location) = 0; 230 231 // This corresponds to URLRequestDelegate::OnResponseStarted. 232 virtual void OnResponseStarted(URLRequest* request, int net_error) = 0; 233 234 // Indicates that the URL request has been completed or failed. 235 // |started| indicates whether the request has been started. If false, 236 // some information like the socket address is not available. 237 virtual void OnCompleted(URLRequest* request, 238 bool started, 239 int net_error) = 0; 240 241 // Called when an URLRequest is being destroyed. Note that the request is 242 // being deleted, so it's not safe to call any methods that may result in 243 // a virtual method call. 244 virtual void OnURLRequestDestroyed(URLRequest* request) = 0; 245 246 // Corresponds to ProxyResolverJSBindings::OnError. 247 virtual void OnPACScriptError(int line_number, 248 const std::u16string& error) = 0; 249 250 // Called when reading cookies to allow the network delegate to block access 251 // to individual cookies, by adding the appropriate ExclusionReason and moving 252 // them to the `excluded_cookies` list. This method will never be invoked 253 // when LOAD_DO_NOT_SEND_COOKIES is specified. 254 // 255 // Returns false if the delegate has blocked access to all cookies; true 256 // otherwise. 257 virtual bool OnAnnotateAndMoveUserBlockedCookies( 258 const URLRequest& request, 259 const net::FirstPartySetMetadata& first_party_set_metadata, 260 net::CookieAccessResultList& maybe_included_cookies, 261 net::CookieAccessResultList& excluded_cookies) = 0; 262 263 // Called when a cookie is set to allow the network delegate to block access 264 // to the cookie. If the cookie is allowed, `inclusion_status` may be updated 265 // to include reason to warn about the given cookie according to the user 266 // cookie-blocking settings; Otherwise, `inclusion_status` may be updated with 267 // the proper exclusion reasons, if not then proper reasons need to be 268 // manually added in the caller. This method will never be invoked when 269 // LOAD_DO_NOT_SAVE_COOKIES is specified. 270 virtual bool OnCanSetCookie( 271 const URLRequest& request, 272 const CanonicalCookie& cookie, 273 CookieOptions* options, 274 const net::FirstPartySetMetadata& first_party_set_metadata, 275 CookieInclusionStatus* inclusion_status) = 0; 276 277 virtual PrivacySetting OnForcePrivacyMode( 278 const URLRequest& request) const = 0; 279 280 // Called when the |referrer_url| for requesting |target_url| during handling 281 // of the |request| is does not comply with the referrer policy (e.g. a 282 // secure referrer for an insecure initial target). 283 // Returns true if the request should be cancelled. Otherwise, the referrer 284 // header is stripped from the request. 285 virtual bool OnCancelURLRequestWithPolicyViolatingReferrerHeader( 286 const URLRequest& request, 287 const GURL& target_url, 288 const GURL& referrer_url) const = 0; 289 290 virtual bool OnCanQueueReportingReport(const url::Origin& origin) const = 0; 291 292 virtual void OnCanSendReportingReports( 293 std::set<url::Origin> origins, 294 base::OnceCallback<void(std::set<url::Origin>)> result_callback) 295 const = 0; 296 297 virtual bool OnCanSetReportingClient(const url::Origin& origin, 298 const GURL& endpoint) const = 0; 299 300 virtual bool OnCanUseReportingClient(const url::Origin& origin, 301 const GURL& endpoint) const = 0; 302 }; 303 304 } // namespace net 305 306 #endif // NET_BASE_NETWORK_DELEGATE_H_ 307