feat: add diag_owner flag to Container and document base methods

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: joamag

CHANGELOG.md

@@ -9,11 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-*
+* `diag_owner` flag in `Container` to restrict diagnostics to the owner base, avoiding port binding conflicts in multi-base setups
 
 ### Changed
 
-*
+* Add docstrings to `Container.add_base()`, `remove_base()` and `start_base()`
+* Pass `diag_owner=True` in `ProxyServer` container to prevent child clients from binding to the diag port
 
 ### Fixed
 

src/netius/base/container.py

@@ -37,6 +37,7 @@ class Container(Base):
 
     def __init__(self, *args, **kwargs):
         Base.__init__(self, *args, **kwargs)
+        self.diag_owner = kwargs.get("diag_owner", False)
         self.owner = None
         self.bases = []
 
@@ -150,15 +151,61 @@ def on_stop(self):
         self.call_all("on_stop")
 
     def add_base(self, base):
+        """
+        Adds a base structure to the container, applying the
+        container's shared poll, logger and thread identity to
+        the base before appending it to the internal list of
+        managed bases.
+
+        :type base: Base/Agent
+        :param base: The base structure (server, client or agent)
+        to be added to the container.
+        """
+
         self.apply_base(base)
         self.bases.append(base)
 
     def remove_base(self, base):
+        """
+        Removes a previously added base structure from the
+        container's internal list of managed bases. After this
+        call the base will no longer receive poll events, tick
+        callbacks or lifecycle notifications from the container.
+
+        :type base: Base/Agent
+        :param base: The base structure to be removed from the
+        container.
+        """
+
         self.bases.remove(base)
 
     def start_base(self, base):
+        """
+        Starts a single base structure by propagating the
+        container's logging level and logger and then calling
+        the base's load operation. If the container is configured
+        with `diag_owner` only the owner base will have its
+        diagnostics enabled, all other bases have it disabled
+        to avoid port binding conflicts.
+
+        :type base: Base/Agent
+        :param base: The base structure to be started under
+        the container.
+        """
+
+        # shares the container's logging level and logger with the base
+        # this is required to ensure that the base is properly configured
+        # to use the same logging configuration as the container (required for
+        # the proper propagation of the logging configuration to the bases)
         base.level = self.level
         base.logger = self.logger
+
+        # if the container is configured with `diag_owner` only the
+        # owner base will have its diagnostics enabled, all other bases
+        # have it disabled to avoid port binding conflicts
+        if self.diag_owner and not base == self.owner:
+            base.diag = False
+
         base.load()
 
     def start_all(self):

src/netius/servers/proxy.py

@@ -184,7 +184,7 @@ def __init__(
         self.raw_client.bind("data", self._on_raw_data)
         self.raw_client.bind("close", self._on_raw_close)
 
-        self.container = netius.Container(*args, **kwargs)
+        self.container = netius.Container(*args, diag_owner=True, **kwargs)
         self.container.add_base(self)
         self.container.add_base(self.http_client)
         self.container.add_base(self.raw_client)