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