net/url_request/url_request_throttler_entry.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_URL_REQUEST_URL_REQUEST_THROTTLER_ENTRY_H_
   6 #define NET_URL_REQUEST_URL_REQUEST_THROTTLER_ENTRY_H_
   7
   8 #include <queue>
   9 #include <string>
  10
  11 #include "base/basictypes.h"
  12 #include "base/time/time.h"
  13 #include "net/base/backoff_entry.h"
  14 #include "net/base/net_log.h"
  15 #include "net/url_request/url_request_throttler_entry_interface.h"
  16
  17 namespace net {
  18
  19 class URLRequestThrottlerManager;
  20
  21 // URLRequestThrottlerEntry represents an entry of URLRequestThrottlerManager.
  22 // It analyzes requests of a specific URL over some period of time, in order to
  23 // deduce the back-off time for every request.
  24 // The back-off algorithm consists of two parts. Firstly, exponential back-off
  25 // is used when receiving 5XX server errors or malformed response bodies.
  26 // The exponential back-off rule is enforced by URLRequestHttpJob. Any
  27 // request sent during the back-off period will be cancelled.
  28 // Secondly, a sliding window is used to count recent requests to a given
  29 // destination and provide guidance (to the application level only) on whether
  30 // too many requests have been sent and when a good time to send the next one
  31 // would be. This is never used to deny requests at the network level.
  32 class NET_EXPORT URLRequestThrottlerEntry
  33     : public URLRequestThrottlerEntryInterface {
  34  public:
  35   // Sliding window period.
  36   static const int kDefaultSlidingWindowPeriodMs;
  37
  38   // Maximum number of requests allowed in sliding window period.
  39   static const int kDefaultMaxSendThreshold;
  40
  41   // Number of initial errors to ignore before starting exponential back-off.
  42   static const int kDefaultNumErrorsToIgnore;
  43
  44   // Initial delay for exponential back-off.
  45   static const int kDefaultInitialDelayMs;
  46
  47   // Factor by which the waiting time will be multiplied.
  48   static const double kDefaultMultiplyFactor;
  49
  50   // Fuzzing percentage. ex: 10% will spread requests randomly
  51   // between 90%-100% of the calculated time.
  52   static const double kDefaultJitterFactor;
  53
  54   // Maximum amount of time we are willing to delay our request.
  55   static const int kDefaultMaximumBackoffMs;
  56
  57   // Time after which the entry is considered outdated.
  58   static const int kDefaultEntryLifetimeMs;
  59
  60   // Name of the header that sites can use to opt out of exponential back-off
  61   // throttling.
  62   static const char kExponentialThrottlingHeader[];
  63
  64   // Value for exponential throttling header that can be used to opt out of
  65   // exponential back-off throttling.
  66   static const char kExponentialThrottlingDisableValue[];
  67
  68   // The manager object's lifetime must enclose the lifetime of this object.
  69   URLRequestThrottlerEntry(URLRequestThrottlerManager* manager,
  70                            const std::string& url_id);
  71
  72   // The life span of instances created with this constructor is set to
  73   // infinite, and the number of initial errors to ignore is set to 0.
  74   // It is only used by unit tests.
  75   URLRequestThrottlerEntry(URLRequestThrottlerManager* manager,
  76                            const std::string& url_id,
  77                            int sliding_window_period_ms,
  78                            int max_send_threshold,
  79                            int initial_backoff_ms,
  80                            double multiply_factor,
  81                            double jitter_factor,
  82                            int maximum_backoff_ms);
  83
  84   // Used by the manager, returns true if the entry needs to be garbage
  85   // collected.
  86   bool IsEntryOutdated() const;
  87
  88   // Causes this entry to never reject requests due to back-off.
  89   void DisableBackoffThrottling();
  90
  91   // Causes this entry to NULL its manager pointer.
  92   void DetachManager();
  93
  94   // Implementation of URLRequestThrottlerEntryInterface.
  95   virtual bool ShouldRejectRequest(const URLRequest& request) const OVERRIDE;
  96   virtual int64 ReserveSendingTimeForNextRequest(
  97       const base::TimeTicks& earliest_time) OVERRIDE;
  98   virtual base::TimeTicks GetExponentialBackoffReleaseTime() const OVERRIDE;
  99   virtual void UpdateWithResponse(
 100       const std::string& host,
 101       const URLRequestThrottlerHeaderInterface* response) OVERRIDE;
 102   virtual void ReceivedContentWasMalformed(int response_code) OVERRIDE;
 103
 104  protected:
 105   virtual ~URLRequestThrottlerEntry();
 106
 107   void Initialize();
 108
 109   // Returns true if the given response code is considered an error for
 110   // throttling purposes.
 111   bool IsConsideredError(int response_code);
 112
 113   // Equivalent to TimeTicks::Now(), virtual to be mockable for testing purpose.
 114   virtual base::TimeTicks ImplGetTimeNow() const;
 115
 116   // Used internally to handle the opt-out header.
 117   void HandleThrottlingHeader(const std::string& header_value,
 118                               const std::string& host);
 119
 120   // Retrieves the back-off entry object we're using. Used to enable a
 121   // unit testing seam for dependency injection in tests.
 122   virtual const BackoffEntry* GetBackoffEntry() const;
 123   virtual BackoffEntry* GetBackoffEntry();
 124
 125   // Returns true if |load_flags| contains a flag that indicates an
 126   // explicit request by the user to load the resource. We never
 127   // throttle requests with such load flags.
 128   static bool ExplicitUserRequest(const int load_flags);
 129
 130   // Used by tests.
 131   base::TimeTicks sliding_window_release_time() const {
 132     return sliding_window_release_time_;
 133   }
 134
 135   // Used by tests.
 136   void set_sliding_window_release_time(const base::TimeTicks& release_time) {
 137     sliding_window_release_time_ = release_time;
 138   }
 139
 140   // Valid and immutable after construction time.
 141   BackoffEntry::Policy backoff_policy_;
 142
 143  private:
 144   // Timestamp calculated by the sliding window algorithm for when we advise
 145   // clients the next request should be made, at the earliest. Advisory only,
 146   // not used to deny requests.
 147   base::TimeTicks sliding_window_release_time_;
 148
 149   // A list of the recent send events. We use them to decide whether there are
 150   // too many requests sent in sliding window.
 151   std::queue<base::TimeTicks> send_log_;
 152
 153   const base::TimeDelta sliding_window_period_;
 154   const int max_send_threshold_;
 155
 156   // True if DisableBackoffThrottling() has been called on this object.
 157   bool is_backoff_disabled_;
 158
 159   // Access it through GetBackoffEntry() to allow a unit test seam.
 160   BackoffEntry backoff_entry_;
 161
 162   // Weak back-reference to the manager object managing us.
 163   URLRequestThrottlerManager* manager_;
 164
 165   // Canonicalized URL string that this entry is for; used for logging only.
 166   std::string url_id_;
 167
 168   BoundNetLog net_log_;
 169
 170   DISALLOW_COPY_AND_ASSIGN(URLRequestThrottlerEntry);
 171 };
 172
 173 }  // namespace net
 174
 175 #endif  // NET_URL_REQUEST_URL_REQUEST_THROTTLER_ENTRY_H_