Added gravity, default_gravity and autoconnect_interface_gravity options and updated documentation

RNS/Discovery.py

@@ -430,6 +430,9 @@ class InterfaceDiscovery():
     AUTOCONNECT_TYPES  = ["BackboneInterface", "TCPServerInterface"]
     DISCOVERABLE_TYPES = ["BackboneInterface", "TCPServerInterface", "I2PInterface", "RNodeInterface", "WeaveInterface", "KISSInterface"]
 
+    AC_TRANSPORT_MODE  = RNS.Interfaces.Interface.Interface.MODE_GATEWAY
+    AC_GRAVITY         = 0
+
     discovery_lock     = Lock()
 
     def __init__(self, required_value=InterfaceAnnouncer.DEFAULT_STAMP_VALUE, callback=None, discover_interfaces=True):
@@ -723,14 +726,15 @@ class InterfaceDiscovery():
                                 interface.autoconnect_hash = endpoint_hash
                                 interface.autoconnect_source = info["network_id"]
                                 if RNS.Reticulum.autoconnect_interface_mode(): mode = RNS.Reticulum.autoconnect_interface_mode()
-                                else: mode = RNS.Interfaces.Interface.Interface.MODE_GATEWAY if RNS.Reticulum.transport_enabled() else None
+                                else: mode = self.AC_TRANSPORT_MODE if RNS.Reticulum.transport_enabled() else None
                                 internal_a = True if RNS.Reticulum.autoconnect_announces_to_internal() else None
+                                gravity    = RNS.Reticulum.autoconnect_interface_gravity() or self.AC_GRAVITY
                                 ar_target  = RNS.Reticulum.get_instance()._default_ar_target() if RNS.Reticulum.transport_enabled() else None
                                 ar_penalty = RNS.Reticulum.get_instance()._default_ar_penalty() if RNS.Reticulum.transport_enabled() else None
                                 ar_grace   = RNS.Reticulum.get_instance()._default_ar_grace() if RNS.Reticulum.transport_enabled() else None
                                 RNS.Reticulum.get_instance()._add_interface(interface, mode=mode, ifac_netname=ifac_netname, ifac_netkey=ifac_netkey, configured_bitrate=5E6,
                                                                             announce_rate_target=ar_target, announce_rate_grace=ar_grace, announce_rate_penalty=ar_penalty,
-                                                                            announces_to_internal=internal_a)
+                                                                            announces_to_internal=internal_a, gravity=gravity)
                                 self.monitor_interface(interface)
 
         except Exception as e:

RNS/Reticulum.py

@@ -262,12 +262,14 @@ class Reticulum:
         Reticulum.__discover_interfaces               = False
         Reticulum.__autoconnect_discovered_interfaces = False
         Reticulum.__autoconnect_interface_mode        = None
+        Reticulum.__autoconnect_interface_gravity     = None
         Reticulum.__autoconnect_announces_to_internal = None
         Reticulum.__required_discovery_value          = None
         Reticulum.__publish_blackhole                 = False
         Reticulum.__blackhole_update_interval         = RNS.Discovery.BlackholeUpdater.UPDATE_INTERVAL
         Reticulum.__blackhole_sources                 = []
         Reticulum.__interface_sources                 = []
+        Reticulum.__default_gravity                   = None
         Reticulum.__default_ar_target                 = None
         Reticulum.__default_ar_penalty                = None
         Reticulum.__default_ar_grace                  = None
@@ -568,6 +570,10 @@ class Reticulum:
                     if v == True:  Reticulum.__use_implicit_proof = True
                     if v == False: Reticulum.__use_implicit_proof = False
                 
+                if option == "default_gravity":
+                    v = self.config["reticulum"].as_int(option)
+                    Reticulum.__default_gravity = v
+
                 if option == "discover_interfaces":
                     v = self.config["reticulum"].as_bool(option)
                     if v == True:  Reticulum.__discover_interfaces = True
@@ -605,13 +611,13 @@ class Reticulum:
                         try: source_identity_hash = bytes.fromhex(hexhash)
                         except Exception as e: raise ValueError(f"Invalid identity hash for interface discovery source: {hexhash}")
                         if not source_identity_hash in Reticulum.__interface_sources: Reticulum.__interface_sources.append(source_identity_hash)
-                
+
                 if option == "autoconnect_discovered_interfaces":
                     v = self.config["reticulum"].as_int(option)
                     if v > 0: Reticulum.__autoconnect_discovered_interfaces = v
-                
-                if option == "autoconnect_discovered_mode":
-                    v = None; dmode = str(self.config["reticulum"]["autoconnect_discovered_mode"]).lower()
+
+                if option == "autoconnect_interface_mode":
+                    v = None; dmode = str(self.config["reticulum"]["autoconnect_interface_mode"]).lower()
                     if   dmode == "full":         v = Interface.Interface.MODE_FULL
                     elif dmode == "access_point": v = Interface.Interface.MODE_ACCESS_POINT
                     elif dmode == "accesspoint":  v = Interface.Interface.MODE_ACCESS_POINT
@@ -625,6 +631,10 @@ class Reticulum:
                     elif dmode == "internal":     v = Interface.Interface.MODE_INTERNAL
                     if v != None: Reticulum.__autoconnect_interface_mode = v
 
+                if option == "autoconnect_interface_gravity":
+                    v = self.config["reticulum"].as_int(option)
+                    Reticulum.__autoconnect_interface_gravity = v
+
                 if option == "autoconnect_announces_to_internal":
                     v = self.config["reticulum"].as_bool(option)
                     if v > 0: Reticulum.__autoconnect_announces_to_internal = v
@@ -758,7 +768,7 @@ class Reticulum:
             elif c["mode"] == "internal":
                 interface_mode = Interface.Interface.MODE_INTERNAL
 
-        gravity = None
+        gravity = self._default_gravity()
         if "gravity" in c: gravity = c.as_int("gravity")
 
         ifac_size = None
@@ -1087,7 +1097,7 @@ class Reticulum:
             if interface != None and issubclass(type(interface), RNS.Interfaces.Interface.Interface):
                 
                 if mode == None:    mode = Interface.Interface.MODE_FULL
-                if gravity == None: gravity = 0
+                if gravity == None: gravity = self._default_gravity()
                 interface.mode = mode
                 interface.gravity = gravity
                 interface.OUT  = True
@@ -1129,6 +1139,9 @@ class Reticulum:
                 RNS.Transport.add_interface(interface)
                 interface.final_init()
 
+    def _default_gravity(self):
+        return self.__default_gravity or RNS.Interfaces.Interface.Interface.DEFAULT_GRAVITY
+
     def _default_ar_target(self):
         return self.__default_ar_target or RNS.Interfaces.Interface.Interface.DEFAULT_AR_TARGET
 
@@ -1840,6 +1853,10 @@ class Reticulum:
     def autoconnect_interface_mode():
         return Reticulum.__autoconnect_interface_mode
 
+    @staticmethod
+    def autoconnect_interface_gravity():
+        return Reticulum.__autoconnect_interface_gravity
+
     @staticmethod
     def autoconnect_announces_to_internal():
         return Reticulum.__autoconnect_announces_to_internal

RNS/Utilities/rnsd.py

@@ -173,6 +173,12 @@ instance_name = default
 # network_identity = ~/.reticulum/storage/identity/network
 
 
+# It is possible to configure the global default interface
+# gravity. This value will be used if an interface does
+# not have a specific gravity value in its configuration.
+
+# default_gravity = 0
+
 # You can configure whether Reticulum should discover
 # available interfaces from other Transport Instances over
 # the network. If this option is enabled, Reticulum will
@@ -220,7 +226,7 @@ instance_name = default
 # You can specify which mode discovered interfaces should
 # be created with when auto-connecting.
 
-# autoconnect_discovered_mode = gw
+# autoconnect_interface_mode = gw
 
 
 # It is possible to allow announces from auto-connected
@@ -231,6 +237,12 @@ instance_name = default
 # autoconnect_announces_to_internal = yes
 
 
+# You can configure the gravity for discovered interfaces
+# that are auto-connected.
+
+# autoconnect_interface_gravity = 0
+
+
 # When Transport is enabled, it is possible to allow the
 # Transport Instance to respond to probe requests from
 # the rnprobe utility. This can be a useful tool to test

docs/manual/_sources/interfaces.rst.txt

@@ -1200,6 +1200,15 @@ These can be used to control various aspects of interface behaviour.
        expected to connect momentarily, use the network, and then
        disappear again.
 
+     - See the :ref:`Interface Modes<interfaces-modes>` section
+       below for a reference on additional modes.
+
+ * | The ``gravity`` option specifies the pathing affinity of an interface.
+     If not set specifically, and unless otherwise configured by
+     ``default_gravity`` or ``autoconnect_interface_gravity``,
+     it defaults to ``0``. Positive values increase pathing affinity,
+     and negative values decrease it.
+
  * | The ``outgoing`` option sets whether an interface is allowed
      to transmit. Defaults to ``True``. If set to ``False`` or ``No``
      the interface will only receive data, and never transmit.

docs/manual/interfaces.html

@@ -1335,10 +1335,20 @@ someone is actually using them. An example of this could
 be a radio interface serving a wide area, where users are
 expected to connect momentarily, use the network, and then
 disappear again.</p></li>
+<li><p>See the <a class="reference internal" href="#interfaces-modes"><span class="std std-ref">Interface Modes</span></a> section
+below for a reference on additional modes.</p></li>
 </ul>
 </div></blockquote>
 </li>
 <li><div class="line-block">
+<div class="line">The <code class="docutils literal notranslate"><span class="pre">gravity</span></code> option specifies the pathing affinity of an interface.
+If not set specifically, and unless otherwise configured by
+<code class="docutils literal notranslate"><span class="pre">default_gravity</span></code> or <code class="docutils literal notranslate"><span class="pre">autoconnect_interface_gravity</span></code>,
+it defaults to <code class="docutils literal notranslate"><span class="pre">0</span></code>. Positive values increase pathing affinity,
+and negative values decrease it.</div>
+</div>
+</li>
+<li><div class="line-block">
 <div class="line">The <code class="docutils literal notranslate"><span class="pre">outgoing</span></code> option sets whether an interface is allowed
 to transmit. Defaults to <code class="docutils literal notranslate"><span class="pre">True</span></code>. If set to <code class="docutils literal notranslate"><span class="pre">False</span></code> or <code class="docutils literal notranslate"><span class="pre">No</span></code>
 the interface will only receive data, and never transmit.</div>

docs/markdown/interfaces.md

@@ -1131,6 +1131,14 @@ These can be used to control various aspects of interface behaviour.
 >   >   be a radio interface serving a wide area, where users are
 >   >   expected to connect momentarily, use the network, and then
 >   >   disappear again.
+>   > - See the [Interface Modes](#interfaces-modes) section
+>   >   below for a reference on additional modes.
+> * The `gravity` option specifies the pathing affinity of an interface.
+>   If not set specifically, and unless otherwise configured by
+>   `default_gravity` or `autoconnect_interface_gravity`,
+>   it defaults to `0`. Positive values increase pathing affinity,
+>   and negative values decrease it.
+>   
 > * The `outgoing` option sets whether an interface is allowed
 >   to transmit. Defaults to `True`. If set to `False` or `No`
 >   the interface will only receive data, and never transmit.

docs/source/interfaces.rst

@@ -1200,6 +1200,15 @@ These can be used to control various aspects of interface behaviour.
        expected to connect momentarily, use the network, and then
        disappear again.
 
+     - See the :ref:`Interface Modes<interfaces-modes>` section
+       below for a reference on additional modes.
+
+ * | The ``gravity`` option specifies the pathing affinity of an interface.
+     If not set specifically, and unless otherwise configured by
+     ``default_gravity`` or ``autoconnect_interface_gravity``,
+     it defaults to ``0``. Positive values increase pathing affinity,
+     and negative values decrease it.
+
  * | The ``outgoing`` option sets whether an interface is allowed
      to transmit. Defaults to ``True``. If set to ``False`` or ``No``
      the interface will only receive data, and never transmit.