<li><aclass="reference internal"href="#applying-the-filter"id="id4">Applying the Filter</a></li>
</ul>
</li>
</ul>
</div>
<p>The Throttler class provides a very simple way to limit an activity to be performed to a certain number of attempts
within a set period of time. This is most often used for performing rate limiting on API’s, or restricting the number
of attempts a user can make against a form to help prevent brute force attacks. The class itself can be used
for anything that you need to throttle based on actions within a set time interval.</p>
<divclass="section"id="overview">
<h2><aclass="toc-backref"href="#id1">Overview</a><aclass="headerlink"href="#overview"title="Permalink to this headline">¶</a></h2>
<p>The Throttler implements a simplified version of the <aclass="reference external"href="https://en.wikipedia.org/wiki/Token_bucket">Token Bucket</a>
algorithm. This basically treats each action that you want as a bucket. When you call the <codeclass="docutils literal"><spanclass="pre">check()</span></code> method,
you tell it how large the bucket is, and how many tokens it can hold and the time interval. Each <codeclass="docutils literal"><spanclass="pre">check()</span></code> call uses
1 of the available tokens, by default. Let’s walk through an example to make this clear.</p>
<p>Let’s say we want an action to happen once every second. The first call to the Throttler would look like the following.
The first parameter is the bucket name, the second parameter the number of tokens the bucket holds, and
the third being the amount of time it takes the bucket to refill:</p>
<p>Here we’re using one of the <aclass="reference internal"href="../general/common_functions.html"><spanclass="doc">global constants</span></a> for the time, to make it a little
more readable. This says that the bucket allows 60 actions every minute, or 1 action every second.</p>
<p>Let’s say that a third-party script was trying to hit a URL repeatedly. At first, it would be able to use all 60
of those tokens in less than a second. However, after that the Throttler would only allow one action per second,
potentially slowing down the requests enough that they attack is no longer worth it.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">For the Throttler class to work, the Cache library must be setup to use a handler other than dummy.
For best performance, an in-memory cache, like Redis or Memcached, is recommended.</p>
</div>
</div>
<divclass="section"id="rate-limiting">
<h2><aclass="toc-backref"href="#id2">Rate Limiting</a><aclass="headerlink"href="#rate-limiting"title="Permalink to this headline">¶</a></h2>
<p>The Throttler class does not do any rate limiting or request throttling on its own, but is the key to making
one work. An example <aclass="reference internal"href="../incoming/filters.html"><spanclass="doc">Filter</span></a> is provided that implements very simple rate limiting at
<p>When run, this method first grabs an instance of the throttler. Next it uses the IP address as the bucket name,
and sets things to limit them to one request per second. If the throttler rejects the check, returning false,
then we return a Response with the status code set to 429 - Too Many Attempts, and the script execution ends
before it ever hits the controller. This example will throttle based on a single IP address across all requests
made to the site, not per page.</p>
</div>
<divclass="section"id="applying-the-filter">
<h3><aclass="toc-backref"href="#id4">Applying the Filter</a><aclass="headerlink"href="#applying-the-filter"title="Permalink to this headline">¶</a></h3>
<p>We don’t necessarily need to throttle every page on the site. For many web applications this makes the most sense
to apply only to POST requests, though API’s might want to limit every request made by a user. In order to apply
this to incoming requests, you need to edit <strong>/application/Config/Filters.php</strong> and first add an alias to the
<p>Checks to see if there are any tokens left within the bucket, or if too many have
been used within the allotted time limit. During each check the available tokens
are reduced by $cost if successful.</p>
</dd></dl>
<dlclass="method">
<dtid="getTokentime">
<codeclass="descname">getTokentime</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink"href="#getTokentime"title="Permalink to this definition">¶</a></dt>
<trclass="field-odd field"><thclass="field-name">Returns:</th><tdclass="field-body">The number of seconds until another token should be available.</td>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
