mirror of
https://github.com/markqvist/Reticulum.git
synced 2026-11-20 06:56:26 -05:00
Updated docs
This commit is contained in:
parent
e0da9c381e
commit
c5d205ffea
3 changed files with 9 additions and 9 deletions
|
|
@ -284,7 +284,7 @@ For Developers
|
|||
|
||||
At some point during the ``1.6.x`` release cycle, RNS will move to using the ``required_only`` mode for *non-transport* instances by default. This means that applications will, in most cases, have to request what types of destinations they are interested in receiving announces from.
|
||||
|
||||
If your application is using only using the utility primitives included in RNS, or established protocols such as LXMF or LXST, **there is nothing you have to do**. The protocol primitives *themselves* request their required destination types, and this is the general pattern to follow here:
|
||||
If your application is only using the utility primitives included in RNS, or established protocols such as LXMF or LXST, **there is nothing you have to do**. The protocol primitives *themselves* request their required destination types, and this is the general pattern to follow here:
|
||||
|
||||
- If an application uses a common protocol or primitive, it is the importable primitive, protocol module, or relevant internal functionality that should request destination type requirements, at the point where they are actually needed.
|
||||
- Higher level application layers should not have to guess at or request destination types, unless it explicitly creates outbound destinations that are not covered by any already-used protocols or primitives.
|
||||
|
|
@ -301,7 +301,7 @@ You do not *have to* explicitly deregister destination type requirements. Reticu
|
|||
|
||||
RNS.Reticulum.get_instance().unwants_destination_type("my_app.service")
|
||||
|
||||
That's really all there is to it. If you already now want to make you application more CPU, memory and battery efficient, you can tell Reticulum to start serving only required destinations to it with only one line of additional code. A full setup of this functionality might look something like:
|
||||
That's really all there is to it. If you already now want to make you application more CPU, memory and battery efficient, you can tell Reticulum to start serving only required destinations to it with only a few lines of additional code. A full setup of this functionality might look something like:
|
||||
|
||||
.. code:: python
|
||||
|
||||
|
|
@ -320,7 +320,7 @@ In addition to the economic incentives created by stamps, Reticulum enforces a s
|
|||
|
||||
At the most basic level, the ``announce_cap`` mechanism limits the bandwidth any interface will allocate to propagating announces and other network upkeep traffic, and prioritises the local topology. Destinations that rapidly re-announce are down-prioritised in the transmission queue, so attempting to gain reach through announce spam has the exact *opposite* effect.
|
||||
|
||||
On top of this, per-destination announce rate control can be configured on any interface, or as instance-wide defaults. Once configured, announces *received* for any one destination will only be re-broadcast to other interfaces at the configured target rate, no matter how often they are received. A grace period allows occasional rate violations, and a configurable penalty extends the interval between propagated announces for destinations that repeatedly exceed their target.
|
||||
On top of this, per-destination announce rate control can be configured on any interface, or as instance-wide defaults. Once configured, announces *received* for any one destination will only be re-broadcast to other interfaces at the configured target rate, no matter how often they are received. The grace option allows occasional rate violations, and a configurable penalty extends the interval between propagated announces for destinations that repeatedly exceed their target.
|
||||
|
||||
The final layer protects against bursts of announces for *newly created* destinations. If an interface receives a large influx of announces for previously unknown destinations in a short amount of time, these are held in a bounded queue, while announces for known and established destinations continue to be processed without interruption. After the burst subsides, and an additional waiting period has passed, held announces are released slowly until the queue is cleared.
|
||||
|
||||
|
|
|
|||
|
|
@ -536,7 +536,7 @@ option. It will become mandatory and enabled by default in RNS
|
|||
<section id="id2">
|
||||
<h3>For Developers<a class="headerlink" href="#id2" title="Link to this heading">¶</a></h3>
|
||||
<p>At some point during the <code class="docutils literal notranslate"><span class="pre">1.6.x</span></code> release cycle, RNS will move to using the <code class="docutils literal notranslate"><span class="pre">required_only</span></code> mode for <em>non-transport</em> instances by default. This means that applications will, in most cases, have to request what types of destinations they are interested in receiving announces from.</p>
|
||||
<p>If your application is using only using the utility primitives included in RNS, or established protocols such as LXMF or LXST, <strong>there is nothing you have to do</strong>. The protocol primitives <em>themselves</em> request their required destination types, and this is the general pattern to follow here:</p>
|
||||
<p>If your application is only using the utility primitives included in RNS, or established protocols such as LXMF or LXST, <strong>there is nothing you have to do</strong>. The protocol primitives <em>themselves</em> request their required destination types, and this is the general pattern to follow here:</p>
|
||||
<ul class="simple">
|
||||
<li><p>If an application uses a common protocol or primitive, it is the importable primitive, protocol module, or relevant internal functionality that should request destination type requirements, at the point where they are actually needed.</p></li>
|
||||
<li><p>Higher level application layers should not have to guess at or request destination types, unless it explicitly creates outbound destinations that are not covered by any already-used protocols or primitives.</p></li>
|
||||
|
|
@ -549,7 +549,7 @@ option. It will become mandatory and enabled by default in RNS
|
|||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">RNS</span><span class="o">.</span><span class="n">Reticulum</span><span class="o">.</span><span class="n">get_instance</span><span class="p">()</span><span class="o">.</span><span class="n">unwants_destination_type</span><span class="p">(</span><span class="s2">"my_app.service"</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>That’s really all there is to it. If you already now want to make you application more CPU, memory and battery efficient, you can tell Reticulum to start serving only required destinations to it with only one line of additional code. A full setup of this functionality might look something like:</p>
|
||||
<p>That’s really all there is to it. If you already now want to make you application more CPU, memory and battery efficient, you can tell Reticulum to start serving only required destinations to it with only a few lines of additional code. A full setup of this functionality might look something like:</p>
|
||||
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">destination_type</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">REQUIRED_DESTINATION_TYPES</span><span class="p">:</span>
|
||||
<span class="n">RNS</span><span class="o">.</span><span class="n">Reticulum</span><span class="o">.</span><span class="n">get_instance</span><span class="p">()</span><span class="o">.</span><span class="n">wants_destination_type</span><span class="p">(</span><span class="n">destination_type</span><span class="p">)</span>
|
||||
|
||||
|
|
@ -563,7 +563,7 @@ option. It will become mandatory and enabled by default in RNS
|
|||
<h2>Ingress & Burst Control<a class="headerlink" href="#ingress-burst-control" title="Link to this heading">¶</a></h2>
|
||||
<p>In addition to the economic incentives created by stamps, Reticulum enforces a set of hydraulic limits on how much announce traffic any peer or destination can inject into the network. These mechanisms work automatically, require no operator configuration (but can be tuned, if required), and apply equally to all peers.</p>
|
||||
<p>At the most basic level, the <code class="docutils literal notranslate"><span class="pre">announce_cap</span></code> mechanism limits the bandwidth any interface will allocate to propagating announces and other network upkeep traffic, and prioritises the local topology. Destinations that rapidly re-announce are down-prioritised in the transmission queue, so attempting to gain reach through announce spam has the exact <em>opposite</em> effect.</p>
|
||||
<p>On top of this, per-destination announce rate control can be configured on any interface, or as instance-wide defaults. Once configured, announces <em>received</em> for any one destination will only be re-broadcast to other interfaces at the configured target rate, no matter how often they are received. A grace period allows occasional rate violations, and a configurable penalty extends the interval between propagated announces for destinations that repeatedly exceed their target.</p>
|
||||
<p>On top of this, per-destination announce rate control can be configured on any interface, or as instance-wide defaults. Once configured, announces <em>received</em> for any one destination will only be re-broadcast to other interfaces at the configured target rate, no matter how often they are received. The grace option allows occasional rate violations, and a configurable penalty extends the interval between propagated announces for destinations that repeatedly exceed their target.</p>
|
||||
<p>The final layer protects against bursts of announces for <em>newly created</em> destinations. If an interface receives a large influx of announces for previously unknown destinations in a short amount of time, these are held in a bounded queue, while announces for known and established destinations continue to be processed without interruption. After the burst subsides, and an additional waiting period has passed, held announces are released slowly until the queue is cleared.</p>
|
||||
<p>A node that connects to a public interface, announces a large number of bogus destinations, and then disconnects, will therefore never get those destinations into path tables at all. When the interface they arrived on disappears, the held announces are simply dropped and forgotten.</p>
|
||||
<p>Ingress control operates at the level of individual sub-interfaces, so one misbehaving client cannot disrupt announce processing for other clients connected to the same listener. Combined with stamps, these mechanisms are complementary:</p>
|
||||
|
|
|
|||
|
|
@ -261,7 +261,7 @@ If you are a developer, see the following section.
|
|||
|
||||
At some point during the `1.6.x` release cycle, RNS will move to using the `required_only` mode for *non-transport* instances by default. This means that applications will, in most cases, have to request what types of destinations they are interested in receiving announces from.
|
||||
|
||||
If your application is using only using the utility primitives included in RNS, or established protocols such as LXMF or LXST, **there is nothing you have to do**. The protocol primitives *themselves* request their required destination types, and this is the general pattern to follow here:
|
||||
If your application is only using the utility primitives included in RNS, or established protocols such as LXMF or LXST, **there is nothing you have to do**. The protocol primitives *themselves* request their required destination types, and this is the general pattern to follow here:
|
||||
|
||||
- If an application uses a common protocol or primitive, it is the importable primitive, protocol module, or relevant internal functionality that should request destination type requirements, at the point where they are actually needed.
|
||||
- Higher level application layers should not have to guess at or request destination types, unless it explicitly creates outbound destinations that are not covered by any already-used protocols or primitives.
|
||||
|
|
@ -278,7 +278,7 @@ You do not *have to* explicitly deregister destination type requirements. Reticu
|
|||
RNS.Reticulum.get_instance().unwants_destination_type("my_app.service")
|
||||
```
|
||||
|
||||
That’s really all there is to it. If you already now want to make you application more CPU, memory and battery efficient, you can tell Reticulum to start serving only required destinations to it with only one line of additional code. A full setup of this functionality might look something like:
|
||||
That’s really all there is to it. If you already now want to make you application more CPU, memory and battery efficient, you can tell Reticulum to start serving only required destinations to it with only a few lines of additional code. A full setup of this functionality might look something like:
|
||||
|
||||
```python
|
||||
for destination_type in self.REQUIRED_DESTINATION_TYPES:
|
||||
|
|
@ -295,7 +295,7 @@ In addition to the economic incentives created by stamps, Reticulum enforces a s
|
|||
|
||||
At the most basic level, the `announce_cap` mechanism limits the bandwidth any interface will allocate to propagating announces and other network upkeep traffic, and prioritises the local topology. Destinations that rapidly re-announce are down-prioritised in the transmission queue, so attempting to gain reach through announce spam has the exact *opposite* effect.
|
||||
|
||||
On top of this, per-destination announce rate control can be configured on any interface, or as instance-wide defaults. Once configured, announces *received* for any one destination will only be re-broadcast to other interfaces at the configured target rate, no matter how often they are received. A grace period allows occasional rate violations, and a configurable penalty extends the interval between propagated announces for destinations that repeatedly exceed their target.
|
||||
On top of this, per-destination announce rate control can be configured on any interface, or as instance-wide defaults. Once configured, announces *received* for any one destination will only be re-broadcast to other interfaces at the configured target rate, no matter how often they are received. The grace option allows occasional rate violations, and a configurable penalty extends the interval between propagated announces for destinations that repeatedly exceed their target.
|
||||
|
||||
The final layer protects against bursts of announces for *newly created* destinations. If an interface receives a large influx of announces for previously unknown destinations in a short amount of time, these are held in a bounded queue, while announces for known and established destinations continue to be processed without interruption. After the burst subsides, and an additional waiting period has passed, held announces are released slowly until the queue is cleared.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue