hivesolutions
diff --git a/‎CHANGELOG.md‎
Lines changed: 9 additions & 3 deletions b/‎CHANGELOG.md‎
Lines changed: 9 additions & 3 deletions
diff --git a/‎doc/architecture.md‎
Lines changed: 135 additions & 0 deletions b/‎doc/architecture.md‎
Lines changed: 135 additions & 0 deletions
diff --git a/‎doc/compat.md‎
Lines changed: 87 additions & 9 deletions b/‎doc/compat.md‎
Lines changed: 87 additions & 9 deletions
diff --git a/‎src/netius/base/agent.py‎
Lines changed: 91 additions & 0 deletions b/‎src/netius/base/agent.py‎
Lines changed: 91 additions & 0 deletions
@@ -9,15 +9,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-*
+* Base-compatible stub methods on `Agent` so that `Container` works with both old (`Base`) and new (`Agent`/`Protocol`) architectures without defensive guards
+* `ClientAgent.connect()` method with `_container_loop` support for protocol-based connections to join the container's shared poll
+* Event relay system in `ClientAgent._relay_protocol_events()` bridging protocol events to client-level observers
+* Container tests (`netius.test.base.container`) covering setup, event bindings, lifecycle, and cleanup
+* Data flow tests for `ReverseProxyServer` covering request routing, response relay, error handling, and lifecycle management
 
 ### Changed
 
-*
+* `Container.apply_base()` now sets `_container_loop` on non-`Base` objects to enable dual architecture multiplexing
+* `HTTPClient.method()` uses `_container_loop` as default loop when available for container integration
+* Proxy throttle methods use `self.reads()` / `self.writes()` since connections are owned by the proxy server
 
 ### Fixed
 
-*
+* `AttributeError` when running `ConsulProxyServer` due to `Agent` subclasses missing `load`, `unload`, `ticks`, and other `Base`-expected methods
 
 ## [1.21.0] - 2026-02-07
 
 
@@ -0,0 +1,135 @@
+# Architecture
+
+Netius is a networking library with its own event loop, a Protocol/Transport layer that is
+API-compatible with Python's asyncio, and a Container system for multiplexing multiple services
+on a shared poll.
+
+## Bi-directional asyncio Compatibility
+
+A core design principle of Netius is **bi-directional compatibility** with Python's asyncio. Rather
+than being a one-way wrapper, compatibility works in both directions across three layers:
+
+**Protocol layer** - Netius protocols (`Protocol`, `StreamProtocol`, `DatagramProtocol`) implement
+the same interface as `asyncio.Protocol`: `connection_made()`, `connection_lost()`,
+`data_received()`, `pause_writing()`, `resume_writing()`. A protocol written for Netius runs on
+asyncio's event loop with zero changes, and a protocol written for asyncio runs on Netius.
+
+**Transport layer** - Netius transports (`Transport`, `TransportStream`, `TransportDatagram`)
+implement the `asyncio.Transport` interface: `write()`, `close()`, `abort()`,
+`get_write_buffer_size()`, `get_extra_info()`. Internally they wrap Netius `Connection` objects, but
+protocols only see the standard interface. When running on asyncio, Python provides its own
+transports with the same API - protocols don't know the difference.
+
+**Event loop layer** - `CompatLoop` wraps a Netius `Base` loop and presents the full
+`asyncio.AbstractEventLoop` interface (`call_soon`, `create_connection`, `create_server`,
+`create_task`, `run_until_complete`, etc.). This means code that expects an asyncio loop - including
+third-party libraries - can run on Netius. Conversely, when `ASYNCIO=1` is set, Netius uses
+Python's native asyncio loop directly, with Netius protocols plugging in through the standard
+protocol/transport interfaces.
+
+This bi-directional design means Netius is not locked into its own ecosystem. Protocols are portable
+across loops, the transport API is interchangeable, and the loop itself can be either Netius or
+asyncio depending on deployment needs. The native Netius loop is the default for performance (see
+[compat.md](compat.md)), but asyncio is always available as a drop-in alternative.
+
+## Event Loop
+
+The event loop lives in `Base` (`netius.base.common`) and is built on OS-level I/O multiplexing:
+epoll (Linux), kqueue (macOS/BSD), poll (POSIX), or select (fallback).
+
+The core cycle in `Base.loop()`:
+
+```text
+while running:
+    ticks()              # timers, delayed callbacks, housekeeping
+    reads, writes, errors = poll.poll()
+    reads(sockets)       # dispatch readable sockets
+    writes(sockets)      # dispatch writable sockets
+    errors(sockets)      # dispatch error sockets
+```
+
+Each socket is registered via `sub_read(socket, owner=self)` - the `owner` is the `Base` that
+created the connection. This ownership is used by the Container for routing (see below).
+
+### Read Path
+
+```text
+poll -> on_read(socket) -> connection.recv()
+  -> on_data_base(connection, data) -> connection.set_data(data)
+    -> connection triggers "data" event
+```
+
+`Connection` is the Netius-native socket abstraction handling buffering, SSL, and flow control.
+
+## Protocol / Transport
+
+Netius protocols implement the same interface as `asyncio.Protocol`, so they run on either event
+loop unchanged.
+
+```text
+Protocol                  connection_made(), connection_lost(), pause/resume_writing
+  +-- StreamProtocol      data_received(), send()
+  +-- DatagramProtocol    datagram_received(), send_to()
+```
+
+`StreamProtocol` also exposes backward-compat delegation properties (`socket`, `renable`,
+`is_throttleable()`) that reach through to the underlying `Connection`.
+
+The `Transport` classes (`netius.base.transport`) wrap a `Connection` and bridge the two worlds:
+
+- Binds to `Connection` `"data"` / `"close"` events
+- Forwards to `protocol.data_received()` / `protocol.connection_lost()`
+- `transport.write(data)` calls `connection.send(data, delay=False)`
+
+Wiring is set up by `transport._set_compat(protocol)` which binds events and calls
+`protocol.connection_made(transport)`.
+
+## Agent
+
+`Agent` (`netius.base.agent`) is the entry point for protocol-based implementations.
+
+```text
+Agent                Base-compatible stubs (load, unload, ticks, on_start, on_stop)
+  +-- ClientAgent    connect(), event relay, thread-local caching, _container_loop
+  +-- ServerAgent
+```
+
+`ClientAgent.connect()` creates a protocol, calls `connect_stream(loop=self._container_loop)`,
+and relays protocol events (`"open"` -> `"connect"`, `"close"` -> `"close"`) so observers on the
+client receive events from all managed protocols.
+
+Agent provides Base-compatible stubs so it can participate in a Container without defensive guards.
+
+## Container
+
+The `Container` (`netius.base.container`) multiplexes multiple `Base` and `Agent` instances on a
+shared poll. Used by composite servers like `ProxyServer` (front-end server + back-end clients).
+
+```python
+def loop(self):
+    while self._running:
+        self.ticks()
+        result = self.poll.poll_owner()  # events grouped by owning Base
+        for base, (reads, writes, errors) in result.items():
+            base.reads(reads)
+            base.writes(writes)
+            base.errors(errors)
+```
+
+### Socket Ownership
+
+`Base.sub_read(socket)` registers `owner=self` in the poll. `poll_owner()` groups ready sockets
+by owner and returns a dict, so the Container routes each group to the correct Base.
+
+### _container_loop
+
+Agent-based objects need `_container_loop` (set to `Container.owner` by `apply_base()`) so that
+`connect_stream()` calls `owner.connect()` instead of `Container.connect()`. This ensures:
+
+1. Connections are owned by the right Base (eg ProxyServer)
+2. `poll_owner()` routes their events to that Base's `on_read()` -> `on_data_base()`
+3. Data reaches the transport -> protocol layer
+
+Without it, `connect_stream(loop=None)` falls back to `common.get_loop()` which returns the
+Container (as `Base._MAIN`). Connections owned by the Container would not be routed through the
+correct `on_data_base()` bridging path.
@@ -1,27 +1,105 @@
 # Compatibility with asyncio
 
-As part of the effort to make Netius more compatible with asyncio, the following
-changes have been made:
+The `netius.base.compat` module allows Netius protocols to run on different event loops. Each
+bootstrap function (`connect_stream`, `serve_stream`, `build_datagram`) dispatches to a **native**
+or **compat** variant based on runtime configuration.
 
-- The `netius` module provides a `COMPAT` mode that allows it to be used to allows Netius protocols
-to be used with asyncio. This mode is enabled by setting the `COMPAT` environment variable to `True`.
+## Execution Modes
 
-## Testing
+### Native (Default)
 
-To run the echo server Protocol implementation using netius run:
+Uses the Netius event loop directly. Fastest path - pure callbacks, no asyncio overhead.
 
 ```bash
-PYTHONPATH=. python3 netius/servers/echo.py 
+PYTHONPATH=. python3 netius/servers/echo.py
 ```
 
-To use the compat version meaning that an asyncio-like interface will be used underneath the hoods use:
+### Compat
+
+Wraps the Netius event loop in `CompatLoop` to present an `asyncio.AbstractEventLoop` interface.
+Allows third-party asyncio protocols to run on Netius event loop.
 
 ```bash
 COMPAT=1 PYTHONPATH=. python3 netius/servers/echo.py
 ```
 
-To use the compat version and make use of the native asyncio event loop use the following:
+### Asyncio
+
+Replaces the Netius event loop with Python's native asyncio loop. Netius protocols work because
+they implement the standard asyncio Protocol interface. Implies compat mode.
 
 ```bash
 COMPAT=1 ASYNCIO=1 PYTHONPATH=. python3 netius/servers/echo.py
 ```
+
+## Dispatch
+
+`is_compat()` returns `True` when `COMPAT=1` or `ASYNCIO=1` is set:
+
+```python
+def connect_stream(*args, **kwargs):
+    if is_compat():
+        return _connect_stream_compat(...)
+    else:
+        return _connect_stream_native(...)
+```
+
+The same pattern applies to `serve_stream()` and `build_datagram()`.
+
+## Native Path
+
+Calls `Base.connect()` / `Base.serve()` directly with callbacks:
+
+```python
+def _connect_stream_native(..., loop=None):
+    loop = loop or common.get_loop()
+    protocol = protocol_factory()
+    loop.connect(host, port, ssl=ssl, callback=on_complete)
+    # on_complete creates TransportStream, wires protocol
+```
+
+No futures, no coroutines, no translation layer. SSL parameters go straight to `Base.connect()`
+which wraps the socket at the OS level.
+
+## Compat Path
+
+Routes through the asyncio API exposed by `CompatLoop`:
+
+```python
+def _connect_stream_compat(..., loop=None):
+    loop = loop or common.get_loop()
+    protocol = protocol_factory()
+    connect = loop.create_connection(build_protocol, host=host, port=port, ssl=ssl)
+    future = loop.create_task(connect)
+    future.add_done_callback(on_connect)
+```
+
+`CompatLoop.create_connection()` internally calls `Base.connect()` but wraps the result in a
+Future and wires the protocol inside a generator-based coroutine.
+
+## CompatLoop
+
+Wraps a Netius `Base` loop and translates asyncio API calls:
+
+| asyncio API                  | Netius equivalent                          |
+| ---------------------------- | ------------------------------------------ |
+| `call_soon(cb)`              | `Base.delay(cb, immediately=True)`         |
+| `call_later(delay, cb)`      | `Base.delay(cb, timeout=delay)`            |
+| `create_future()`            | `Base.build_future()`                      |
+| `create_task(coroutine)`     | `Base.ensure(coroutine)` wrapped in `Task` |
+| `create_connection(...)`     | `Base.connect(...)` wrapped in a Future    |
+| `create_server(...)`         | `Base.serve(...)` wrapped in a Future      |
+| `run_until_complete(future)` | `Base.run_coroutine(future)`               |
+| `run_forever()`              | `Base.run_forever()`                       |
+| `stop()`                     | `Base.pause()`                             |
+
+Attributes not explicitly implemented fall through to the underlying `Base` via `__getattr__`.
+
+## Why Native is Faster
+
+1. **No Future/Task overhead.** Native uses direct callbacks. Compat allocates a Future, creates a Task, and dispatches through done-callbacks for every operation.
+2. **No translation layer.** Native calls `Base.connect()` directly. Compat routes every call through `CompatLoop` which translates asyncio API into Netius equivalents.
+3. **No coroutine frames.** Compat's `_create_connection()` and `_create_server()` are generator coroutines (`yield future`). Native is purely callback-driven.
+4. **Direct SSL.** Native passes SSL parameters to `Base.connect()` for OS-level wrapping. Compat constructs an `ssl.SSLContext` and routes through asyncio's SSL layer.
+
+The difference accumulates under high connection rates where per-connection overhead matters.
@@ -30,6 +30,7 @@
 
 import threading
 
+from . import compat
 from . import legacy
 from . import observer
 
@@ -49,8 +50,26 @@ class Agent(observer.Observable):
 
     For complex protocols instantiation may be useful to provided extra
     flexibility and context for abstract operations.
+
+    Provides Base-compatible stub methods so that Agents can be added
+    to a Container alongside Base-derived objects without requiring
+    the Container to use defensive guards. The new code (Agent) adapts
+    to the old code (Container), keeping retro-compatibility.
     """
 
+    _container_loop = None
+    """ Reference to the container's owner (a Base instance) set by
+    `Container.apply_base()` when this agent is added to a container,
+    enables protocol connections to join the container's shared poll """
+
+    @property
+    def name(self):
+        return self.__class__.__name__
+
+    @property
+    def connections(self):
+        return []
+
     @classmethod
     def cleanup_s(cls):
         pass
@@ -62,6 +81,27 @@ def cleanup(self, destroy=True):
     def destroy(self):
         observer.Observable.destroy(self)
 
+    def load(self):
+        pass
+
+    def unload(self):
+        pass
+
+    def ticks(self):
+        pass
+
+    def on_start(self):
+        pass
+
+    def on_stop(self):
+        pass
+
+    def connections_dict(self, full=False, parent=False):
+        return dict()
+
+    def info_dict(self, full=False):
+        return dict(name=self.name)
+
 
 class ClientAgent(Agent):
 
@@ -89,6 +129,57 @@ def get_client_s(cls, *args, **kwargs):
         cls._clients[tid] = client
         return client
 
+    def connect(self, host, port, ssl=False, *args, **kwargs):
+        """
+        Creates a new protocol based connection to the provided
+        host and port, using the container's shared event loop when
+        available (dual architecture support).
+
+        :type host: String
+        :param host: The hostname or IP address of the remote
+        host to which the connection should be made.
+        :type port: int
+        :param port: The port number of the remote host to
+        which the connection should be made.
+        :type ssl: bool
+        :param ssl: If the connection should be established using
+        a secure SSL/TLS channel.
+        :rtype: Protocol
+        :return: The protocol instance that represents the newly
+        created connection.
+        """
+
+        cls = self.__class__
+        protocol = cls.protocol()
+        compat.connect_stream(
+            lambda: protocol,
+            host=host,
+            port=port,
+            ssl=ssl,
+            loop=self._container_loop,
+            *args,
+            **kwargs
+        )
+        self._relay_protocol_events(protocol)
+        return protocol
+
+    def _relay_protocol_events(self, protocol):
+        """
+        Relays protocol events through this client agent so that
+        observers that bind on the client (eg proxy servers) receive
+        events from all managed protocols.
+
+        Subclasses should override this method and call the parent
+        implementation to add protocol-specific event relays.
+
+        :type protocol: Protocol
+        :param protocol: The protocol instance whose events should
+        be relayed through this client agent.
+        """
+
+        protocol.bind("open", lambda protocol: self.trigger("connect", self, protocol))
+        protocol.bind("close", lambda protocol: self.trigger("close", self, protocol))
+
 
 class ServerAgent(Agent):
     pass