network_delegate.h 13 KB

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