evennia/docs/latest/api/evennia.server.throttle.html
Evennia docbuilder action 243d596662 Updated HTML docs.
2025-08-15 18:14:21 +00:00

341 lines
No EOL
22 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>evennia.server.throttle &#8212; Evennia latest documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
<link rel="stylesheet" type="text/css" href="../_static/nature.css?v=279e0f84" />
<link rel="stylesheet" type="text/css" href="../_static/custom.css?v=e4a91a55" />
<script src="../_static/documentation_options.js?v=c6e86fd7"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="evennia.server.validators" href="evennia.server.validators.html" />
<link rel="prev" title="evennia.server.signals" href="evennia.server.signals.html" />
</head><body>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="evennia.server.validators.html" title="evennia.server.validators"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="evennia.server.signals.html" title="evennia.server.signals"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="../Evennia-API.html" >API Summary</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="evennia-api.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="evennia.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-4"><a href="evennia.server.html" accesskey="U">evennia.server</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.server.throttle</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="module-evennia.server.throttle">
<span id="evennia-server-throttle"></span><h1>evennia.server.throttle<a class="headerlink" href="#module-evennia.server.throttle" title="Link to this heading"></a></h1>
<dl class="py class">
<dt class="sig sig-object py" id="evennia.server.throttle.Throttle">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">evennia.server.throttle.</span></span><span class="sig-name descname"><span class="pre">Throttle</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/server/throttle.html#Throttle"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.server.throttle.Throttle" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></p>
<p>Keeps a running count of failed actions per IP address.</p>
<p>Available methods indicate whether or not the number of failures exceeds a
particular threshold.</p>
<p>This version of the throttle is usable by both the terminal server as well
as the web server, imposes limits on memory consumption by using deques
with length limits instead of open-ended lists, and uses native Django
caches for automatic key eviction and persistence configurability.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="evennia.server.throttle.Throttle.error_msg">
<span class="sig-name descname"><span class="pre">error_msg</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'Too</span> <span class="pre">many</span> <span class="pre">failed</span> <span class="pre">attempts;</span> <span class="pre">you</span> <span class="pre">must</span> <span class="pre">wait</span> <span class="pre">a</span> <span class="pre">few</span> <span class="pre">minutes</span> <span class="pre">before</span> <span class="pre">trying</span> <span class="pre">again.'</span></em><a class="headerlink" href="#evennia.server.throttle.Throttle.error_msg" title="Link to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.server.throttle.Throttle.__init__">
<span class="sig-name descname"><span class="pre">__init__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/server/throttle.html#Throttle.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.server.throttle.Throttle.__init__" title="Link to this definition"></a></dt>
<dd><p>Allows setting of throttle parameters.</p>
<dl class="field-list simple">
<dt class="field-odd">Keyword Arguments<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>name</strong> (<em>str</em>) Name of this throttle.</p></li>
<li><p><strong>limit</strong> (<em>int</em>) Max number of failures before imposing limiter. If <strong>None</strong>,
the throttle is disabled.</p></li>
<li><p><strong>timeout</strong> (<em>int</em>) number of timeout seconds after
max number of tries has been reached.</p></li>
<li><p><strong>cache_size</strong> (<em>int</em>) Max number of attempts to record per IP within a
rolling window; this is NOT the same as the limit after which
the throttle is imposed!</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.server.throttle.Throttle.get_cache_key">
<span class="sig-name descname"><span class="pre">get_cache_key</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/server/throttle.html#Throttle.get_cache_key"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.server.throttle.Throttle.get_cache_key" title="Link to this definition"></a></dt>
<dd><p>Creates a prefixed key containing arbitrary terms to prevent key
collisions in the same namespace.</p>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.server.throttle.Throttle.touch">
<span class="sig-name descname"><span class="pre">touch</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/server/throttle.html#Throttle.touch"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.server.throttle.Throttle.touch" title="Link to this definition"></a></dt>
<dd><p>Refreshes the timeout on a given key and ensures it is recorded in the
key register.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>key</strong> (<em>str</em>) Key of entry to renew.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.server.throttle.Throttle.get">
<span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">ip</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/server/throttle.html#Throttle.get"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.server.throttle.Throttle.get" title="Link to this definition"></a></dt>
<dd><p>Convenience function that returns the storage table, or part of.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>ip</strong> (<em>str</em><em>, </em><em>optional</em>) IP address of requestor</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><p><em>storage (dict)</em> </p>
<dl class="simple">
<dt>When no IP is provided, returns a dict of all</dt><dd><p>current IPs being tracked and the timestamps of their recent
failures.</p>
</dd>
<dt>timestamps (deque): When an IP is provided, returns a deque of</dt><dd><p>timestamps of recent failures only for that IP.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.server.throttle.Throttle.update">
<span class="sig-name descname"><span class="pre">update</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">ip</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">failmsg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'Exceeded</span> <span class="pre">threshold.'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/server/throttle.html#Throttle.update"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.server.throttle.Throttle.update" title="Link to this definition"></a></dt>
<dd><p>Store the time of the latest failure.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>ip</strong> (<em>str</em>) IP address of requestor</p></li>
<li><p><strong>failmsg</strong> (<em>str</em><em>, </em><em>optional</em>) Message to display in logs upon activation
of throttle.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>None</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.server.throttle.Throttle.remove">
<span class="sig-name descname"><span class="pre">remove</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">ip</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/server/throttle.html#Throttle.remove"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.server.throttle.Throttle.remove" title="Link to this definition"></a></dt>
<dd><p>Clears data stored for an IP from the throttle.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>ip</strong> (<em>str</em>) IP to clear.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.server.throttle.Throttle.record_ip">
<span class="sig-name descname"><span class="pre">record_ip</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">ip</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/server/throttle.html#Throttle.record_ip"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.server.throttle.Throttle.record_ip" title="Link to this definition"></a></dt>
<dd><p>Tracks keys as they are added to the cache (since there is no way to
get a list of keys after-the-fact).</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>ip</strong> (<em>str</em>) IP being added to cache. This should be the original
IP, not the cache-prefixed key.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.server.throttle.Throttle.unrecord_ip">
<span class="sig-name descname"><span class="pre">unrecord_ip</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">ip</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/server/throttle.html#Throttle.unrecord_ip"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.server.throttle.Throttle.unrecord_ip" title="Link to this definition"></a></dt>
<dd><p>Forces removal of a key from the key registry.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>ip</strong> (<em>str</em>) IP to remove from list of keys.</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt class="sig sig-object py" id="evennia.server.throttle.Throttle.check">
<span class="sig-name descname"><span class="pre">check</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">ip</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../_modules/evennia/server/throttle.html#Throttle.check"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#evennia.server.throttle.Throttle.check" title="Link to this definition"></a></dt>
<dd><p>This will check the sessions address against the
storage dictionary to check they havent spammed too many
fails recently.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>ip</strong> (<em>str</em>) IP address of requestor</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><p><em>throttled (bool)</em> </p>
<dl class="simple">
<dt>True if throttling is active,</dt><dd><p>False otherwise.</p>
</dd>
</dl>
</p>
</dd>
</dl>
</dd></dl>
</dd></dl>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo of Evennia"/>
</a></p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">evennia.server.throttle</a><ul>
<li><a class="reference internal" href="#evennia.server.throttle.Throttle"><code class="docutils literal notranslate"><span class="pre">Throttle</span></code></a><ul>
<li><a class="reference internal" href="#evennia.server.throttle.Throttle.error_msg"><code class="docutils literal notranslate"><span class="pre">Throttle.error_msg</span></code></a></li>
<li><a class="reference internal" href="#evennia.server.throttle.Throttle.__init__"><code class="docutils literal notranslate"><span class="pre">Throttle.__init__()</span></code></a></li>
<li><a class="reference internal" href="#evennia.server.throttle.Throttle.get_cache_key"><code class="docutils literal notranslate"><span class="pre">Throttle.get_cache_key()</span></code></a></li>
<li><a class="reference internal" href="#evennia.server.throttle.Throttle.touch"><code class="docutils literal notranslate"><span class="pre">Throttle.touch()</span></code></a></li>
<li><a class="reference internal" href="#evennia.server.throttle.Throttle.get"><code class="docutils literal notranslate"><span class="pre">Throttle.get()</span></code></a></li>
<li><a class="reference internal" href="#evennia.server.throttle.Throttle.update"><code class="docutils literal notranslate"><span class="pre">Throttle.update()</span></code></a></li>
<li><a class="reference internal" href="#evennia.server.throttle.Throttle.remove"><code class="docutils literal notranslate"><span class="pre">Throttle.remove()</span></code></a></li>
<li><a class="reference internal" href="#evennia.server.throttle.Throttle.record_ip"><code class="docutils literal notranslate"><span class="pre">Throttle.record_ip()</span></code></a></li>
<li><a class="reference internal" href="#evennia.server.throttle.Throttle.unrecord_ip"><code class="docutils literal notranslate"><span class="pre">Throttle.unrecord_ip()</span></code></a></li>
<li><a class="reference internal" href="#evennia.server.throttle.Throttle.check"><code class="docutils literal notranslate"><span class="pre">Throttle.check()</span></code></a></li>
</ul>
</li>
</ul>
</li>
</ul>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="evennia.server.signals.html"
title="previous chapter">evennia.server.signals</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="evennia.server.validators.html"
title="next chapter">evennia.server.validators</a></p>
</div>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/api/evennia.server.throttle.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com/docs/latest/index.html">Documentation Top</a> </li>
<li><a href="https://www.evennia.com">Evennia Home</a> </li>
<li><a href="https://github.com/evennia/evennia">Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
<h3>Doc Versions</h3>
<ul>
<li>
<a href="https://www.evennia.com/docs/latest/index.html">latest (main branch)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/5.x/index.html">v5.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/4.x/index.html">v4.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/3.x/index.html">v3.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/2.x/index.html">v2.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/1.x/index.html">v1.0.0 branch (outdated)</a>
</li>
<li>
<a href="https://www.evennia.com/docs/0.x/index.html">v0.9.5 branch (outdated)</a>
</li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="evennia.server.validators.html" title="evennia.server.validators"
>next</a> |</li>
<li class="right" >
<a href="evennia.server.signals.html" title="evennia.server.signals"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="../Evennia-API.html" >API Summary</a> &#187;</li>
<li class="nav-item nav-item-2"><a href="evennia-api.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-3"><a href="evennia.html" >evennia</a> &#187;</li>
<li class="nav-item nav-item-4"><a href="evennia.server.html" >evennia.server</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">evennia.server.throttle</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2024, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
</div>
</body>
</html>