Home | History | Annotate | Download | only in url_request 
      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_
    176