CFTHROTTLE

Contents 1 Description 2 Syntax 3 Attributes 4 Notes 4.1 ACTION=THROTTLE 4.1.1 Quick Throttle Condition 4.2 ACTION=STATUS 5 Usage

Description

The CFTHROTTLE tag allows you to track repeated requests and gives you the necessary tools to determine if a request should be throttled or not.

The CFTHROTTLE tag does not do anything to the request, it merely gives you the information to do something with.

Syntax

<cfthrottle action="action" 
            token="item to track" 
            hitthreshold="number of hits" 
            hittimeperiod="time period between hits" 
            minhittime="time between requests">

Attributes

Attribute	Req/Opt	Default	Description
action	required	throttle	Permitted values are: THROTTLE (enables throttling); FLUSH (flushes all throttling history); STATUS (returns a variable containing the status of each item being tracked); SET (sets the number of items to retain in the throttling history)
history	optional	N/A	Use with an action of SET to set the number of items to retain in the throttling history.
token	optional	client IP address	Use with an action of THROTTLE to set the token used to track recurring requests.
hitthreshold	optional	N/A	Use with an action of THROTTLE to set the maximum number of times the requester as identified by the token can make requests within the HITTIMEPERIOD.
hittimeperiod	optional	10000	Use with an action of THROTTLE to set the time period (in milliseconds) within which the HITTHRESHOLD may not be exceeded.
minhittime	optional	500	Use with an action of THROTTLE to set the time period (in milliseconds) within which successive requests from any TOKEN are considered excessive.

Notes

CFTHROTTLE is used to throttle successive repeated requests that are made from a specific host or client. It is particularly useful to block things like badly behaving spiders, over-zealous search engines, or even attempts at denial of service (DOS) attacks.

ACTION=THROTTLE

A structure is returned that contains the following:

• THROTTLE - boolean as to whether the request should be throttled
• HITCOUNT - the number of hits this request has incurred since last period
• TOTALHITS - the total number of hits this request has made
• LASTHIT - the date since the last hit
• AGE - the date since the first hit

for example if you wanted to track a request, based purely on IP address using the defaults:

<cfthrottle token="#cgi.REMOTE_ADDR#">

<cfif CFTHROTTLE.throttle>
  <cfheader statuscode="503" statustext="Try backing off the time between requests">
  <cfheader name="Retry-After" value="180">
  <h1>503 Server very busy - back off and try again</h1>
  <cfexit method="request">
</cfif>

Quick Throttle Condition

Another way for a client to be throttled is to make serial requests in which the difference in milliseconds of two requests is less than the MINHITTIME attributes which defaults to 500ms. Successive requests from any TOKEN are considered excessive and therefore triggers a quick throttle (fast fail) whether or not the total hit count for the client has been exceeded.. When a quick throttle condition occurs, the hit is counted against the total hits for the token.

ACTION=STATUS

After executing with an action of THROTTLE, an array of structures CFTHROTTLE is returned. This structure has the:

• THROTTLE - boolean indicating whether or not the client has exceeded the parameters set by CFTHROTTLE
• HITCOUNT - the number of times the client has made requests within the HITTIMEPERIOD
• TOTALHITS - the total number of requests made by the client either since the server started or since the throttling history has been flushed
• LASTHIT - the number of milliseconds since the last request by the client
• AGE - the amount of time the token has been tracked

CFTHROTTLE is typically used in Application.cfc or Application.cfm to provide application-wide tracking and throttling of excessive requests.

Usage

Throttle based on the client IP if the client exceeds 50 hits within 10 seconds:

<cfthrottle action="throttle" token="#CGI.REMOTE_ADDR#" hitthreshold="50" hittimeperiod="10000">
<cfif CFTHROTTLE.throttle>
  <!--- decide to do something with this request --->
</cfif>

Retrieve and dump the current throttling statistics:

<cfthrottle action="status">
<cfdump var="#cfthrottle#">