aioads 0.1.0.dev7__tar.gz → 0.1.0.dev8__tar.gz

{aioads-0.1.0.dev7 → aioads-0.1.0.dev8}/.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
         python-version: ["3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
 

{aioads-0.1.0.dev7 → aioads-0.1.0.dev8}/.github/workflows/publish.yml

@@ -18,7 +18,7 @@ jobs:
     name: Build distribution
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
 

{aioads-0.1.0.dev7 → aioads-0.1.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aioads
-Version: 0.1.0.dev7
+Version: 0.1.0.dev8
 Summary: An asynchronous Python library for communicating with Beckhoff TwinCAT PLCs
 Author-email: MkKiefer <102972583+MkKiefer@users.noreply.github.com>
 License: MIT

{aioads-0.1.0.dev7 → aioads-0.1.0.dev8}/aioads/transport.py

@@ -211,6 +211,14 @@ class AdsTcpTransport(BaseTransport, ITransport):
     CONNECT_TIMEOUT = 30.0
     RECONNECT_INITIAL_BACKOFF = 1.0
     RECONNECT_MAX_BACKOFF = 30.0
+    RECONNECT_STABILITY_THRESHOLD = 10.0
+    """Seconds a connection must stay up before the reconnect backoff resets.
+
+    The peer may accept the TCP handshake and close immediately (e.g. the
+    Beckhoff single-connection lockout). Such a connect must count as a
+    failure for backoff purposes, otherwise the supervisor spins in a
+    zero-delay connect/drop loop and pins a CPU core.
+    """
 
     # TCP keepalive / liveness tuning.
     # Without these, a half-open connection (peer power-cut, cable pull, NAT
@@ -409,9 +417,16 @@ class AdsTcpTransport(BaseTransport, ITransport):
         trigger competing reconnect attempts. Senders fail fast instead (see
         :meth:`request`), which also respects the Beckhoff single-connection
         backoff/lockout behavior.
+
+        The backoff resets only after a connection stayed up for
+        RECONNECT_STABILITY_THRESHOLD seconds, not on connect success: a peer
+        that accepts the handshake and closes right away would otherwise reset
+        the backoff every cycle and turn this loop into a busy spin.
         """
         backoff = self.RECONNECT_INITIAL_BACKOFF
+        loop = asyncio.get_running_loop()
         while self._state is not ConnectionState.CLOSED:
+            connected_at = loop.time()
             try:
                 await self._read_loop()
             except asyncio.CancelledError:  # pylint: disable=try-except-raise
@@ -426,11 +441,21 @@ class AdsTcpTransport(BaseTransport, ITransport):
             self._state = ConnectionState.RECONNECTING
             await self._teardown_stream(ConnectionError("Connection lost"))
 
+            uptime = loop.time() - connected_at
+            if uptime >= self.RECONNECT_STABILITY_THRESHOLD:
+                backoff = self.RECONNECT_INITIAL_BACKOFF
+            else:
+                self.logger.info(
+                    "Connection only lasted %.1fs, backing off %.1fs before reconnecting",
+                    uptime, backoff,
+                )
+                await asyncio.sleep(backoff + random.uniform(0, backoff))
+                backoff = min(backoff * 2, self.RECONNECT_MAX_BACKOFF)
+
             while self._state is not ConnectionState.CLOSED:
                 try:
                     await self._open()
                     self.logger.info("Reconnected to the remote")
-                    backoff = self.RECONNECT_INITIAL_BACKOFF
                     break
                 except asyncio.CancelledError:  # pylint: disable=try-except-raise
                     raise

{aioads-0.1.0.dev7 → aioads-0.1.0.dev8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aioads"
-version = "0.1.0.dev7"
+version = "0.1.0.dev8"
 description = "An asynchronous Python library for communicating with Beckhoff TwinCAT PLCs"
 authors = [
     { name = "MkKiefer", email = "102972583+MkKiefer@users.noreply.github.com" },

aioads-0.1.0.dev8/tests/integration/test_memory.py

@@ -0,0 +1,192 @@
+"""
+Integration tests that watch the Python heap for memory leaks.
+
+Measurements use `tracemalloc` from the standard library, so only allocations
+made by Python code are counted (which is all of aioads). `gc.collect()` runs
+before every snapshot so the numbers only contain objects that are still
+reachable, not garbage awaiting collection.
+
+Reported parts per lifecycle:
+1. Startup cost   - connect + datatype upload + first symbol cache fill.
+2. Runtime cost   - steady-state growth over many reads (the leak signal)
+                    plus the transient peak a batch of reads needs on top.
+3. Cleanup residue - what is still allocated after disconnect, relative to
+                    the pre-connect baseline.
+
+The residue of a single lifecycle legitimately contains one-time allocations
+(module-level loggers, enum value caches, interned strings), so the decisive
+leak check is `test_connect_cycles_do_not_leak`: after the first cycle has
+absorbed those one-time costs, further cycles must not grow the heap.
+
+Like the performance tests, the budgets below are generous upper bounds, not
+benchmarks. A failure means a leak or a pathological regression, not a small
+change. Adjust the constants when they no longer match the test environment.
+"""
+import gc
+import tracemalloc
+
+import unittest
+
+from tests.integration.config import CONFIG_PATH
+from tests.integration.config import create_client
+from tests.integration.config import load_config
+
+# Upper bound for connect + datatype upload + first cache fill. Depends on the
+# size of the PLC project, so this is a loose sanity bound only.
+STARTUP_MAX_BYTES = 20 * 1024 * 1024
+
+# Reads executed before measuring, to let lazy one-time allocations
+# (struct caches, buffers growing to working size) settle.
+WARMUP_READS = 25
+
+# Reads in the measured window. Each iteration performs one single-symbol read
+# and one multi-symbol read. Steady-state reads must not accumulate memory, so
+# the growth budget is small and independent of the read count.
+MEASURED_READS = 1500
+RUNTIME_GROWTH_MAX_BYTES = 16 * 1024
+
+# Transient memory a batch of reads may need on top of the steady state
+# (request/response buffers, parsed values before they are dropped).
+RUNTIME_PEAK_MAX_BYTES = 8 * 1024 * 1024
+
+# Allowed leftover after disconnecting a single client, relative to the
+# pre-connect baseline. Covers legitimate one-time allocations that persist
+# for the lifetime of the interpreter.
+RESIDUE_MAX_BYTES = 1 * 1024 * 1024
+
+# Full connect/read/disconnect cycles in the measured window and their total
+# growth budget. Growth proportional to the cycle count means a real leak.
+MEASURED_CYCLES = 5
+CYCLE_GROWTH_MAX_BYTES = 64 * 1024
+
+
+def _heap_bytes() -> int:
+    """Collect garbage and return the currently traced heap size."""
+    gc.collect()
+    return tracemalloc.get_traced_memory()[0]
+
+
+def _fmt(num_bytes: int) -> str:
+    """Format a byte count as a signed KiB value for readable reports."""
+    return f"{num_bytes / 1024:+,.1f} KiB"
+
+
+@unittest.skipUnless(
+    CONFIG_PATH.exists(),
+    "Integration config missing: copy config.example.toml to config.toml",
+)
+class TestMemory(unittest.IsolatedAsyncioTestCase):
+    """
+    Memory lifecycle tests for reading symbols by name.
+
+    Does not use `IntegrationTestCase`: these tests must control the client
+    lifecycle themselves to measure connect and disconnect.
+    """
+
+    async def asyncSetUp(self) -> None:
+        self.config = load_config()
+        self.symbol_single = self.config["symbols"]["single"]
+        self.symbols_multiple = set(self.config["symbols"]["multiple"])
+        # Trigger lazy imports (e.g. MQTT transports) before any baseline is
+        # taken, so module-level memory is not attributed to the client.
+        create_client(self.config)
+        tracemalloc.start()
+
+    async def asyncTearDown(self) -> None:
+        tracemalloc.stop()
+
+    async def _read_once(self, client) -> None:
+        """One iteration of the read patterns under test."""
+        await client.read_symbol_by_name(self.symbol_single)
+        await client.read_symbols_by_names(self.symbols_multiple)
+
+    async def test_read_symbols_memory_lifecycle(self) -> None:
+        """Measure startup cost, runtime growth and cleanup residue."""
+        baseline = _heap_bytes()
+
+        # Part 1: startup - connect (datatype upload) + first cache fill.
+        client = create_client(self.config)
+        await client.connect()
+        await self._read_once(client)
+        startup_cost = _heap_bytes() - baseline
+
+        # Part 2: runtime - steady-state growth and transient peak.
+        for _ in range(WARMUP_READS):
+            await self._read_once(client)
+        before_reads = _heap_bytes()
+        tracemalloc.reset_peak()
+        for _ in range(MEASURED_READS):
+            await self._read_once(client)
+        runtime_peak = tracemalloc.get_traced_memory()[1] - before_reads
+        runtime_growth = _heap_bytes() - before_reads
+
+        # Part 3: cleanup - disconnect, drop the client, measure the residue.
+        await client.disconnect()
+        del client
+        residue = _heap_bytes() - baseline
+
+        print(
+            f"\nMemory lifecycle report"
+            f"\n  1. startup (connect + first caching): {_fmt(startup_cost)}"
+            f"\n  2. runtime growth over {MEASURED_READS} reads: "
+            f"{_fmt(runtime_growth)} "
+            f"({runtime_growth / MEASURED_READS:+.1f} B/read), "
+            f"transient peak {_fmt(runtime_peak)}"
+            f"\n  3. cleanup residue vs. baseline: {_fmt(residue)}"
+        )
+
+        with self.subTest(part="1-startup"):
+            self.assertLessEqual(
+                startup_cost,
+                STARTUP_MAX_BYTES,
+                f"Startup allocated {_fmt(startup_cost)}",
+            )
+        with self.subTest(part="2-runtime"):
+            self.assertLessEqual(
+                runtime_growth,
+                RUNTIME_GROWTH_MAX_BYTES,
+                f"{MEASURED_READS} reads grew the heap by {_fmt(runtime_growth)} "
+                f"({runtime_growth / MEASURED_READS:+.1f} B/read), "
+                f"reads are accumulating memory",
+            )
+            self.assertLessEqual(
+                runtime_peak,
+                RUNTIME_PEAK_MAX_BYTES,
+                f"Reads transiently needed {_fmt(runtime_peak)} on top of "
+                f"the steady state",
+            )
+        with self.subTest(part="3-cleanup"):
+            self.assertLessEqual(
+                residue,
+                RESIDUE_MAX_BYTES,
+                f"{_fmt(residue)} still allocated after disconnect",
+            )
+
+    async def test_connect_cycles_do_not_leak(self) -> None:
+        """Repeated connect/read/disconnect cycles must not grow the heap."""
+        async def one_cycle() -> None:
+            client = create_client(self.config)
+            await client.connect()
+            await self._read_once(client)
+            await client.disconnect()
+
+        # The first cycle absorbs one-time allocations that live for the
+        # rest of the interpreter (loggers, enum caches, interned strings).
+        await one_cycle()
+        baseline = _heap_bytes()
+
+        for _ in range(MEASURED_CYCLES):
+            await one_cycle()
+        growth = _heap_bytes() - baseline
+
+        print(
+            f"\nConnect cycle report: {MEASURED_CYCLES} cycles grew the heap "
+            f"by {_fmt(growth)} ({growth / MEASURED_CYCLES:+,.0f} B/cycle)"
+        )
+        self.assertLessEqual(
+            growth,
+            CYCLE_GROWTH_MAX_BYTES,
+            f"{MEASURED_CYCLES} connect/read/disconnect cycles grew the heap "
+            f"by {_fmt(growth)} ({growth / MEASURED_CYCLES:+,.0f} B/cycle), "
+            f"the client lifecycle is leaking",
+        )

{aioads-0.1.0.dev7 → aioads-0.1.0.dev8}/tests/unit/test_transport.py

@@ -217,6 +217,69 @@ class TestAdsTcpTransport(unittest.IsolatedAsyncioTestCase):
         self.assertIsInstance(ctx.exception.__cause__, asyncio.IncompleteReadError)
 
 
+class TestAdsTcpTransportReconnect(unittest.IsolatedAsyncioTestCase):
+    """Reconnect supervision against a peer that accepts and instantly closes.
+
+    This models a PLC that completes the TCP handshake but rejects the
+    connection right away (e.g. the Beckhoff single-connection lockout).
+    Every connect *succeeds*, so only the stability-based backoff stands
+    between the supervisor and a zero-delay reconnect spin.
+    """
+
+    async def asyncSetUp(self) -> None:
+        self.accept_count = 0
+
+        async def accept_and_reject(
+            _reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+        ) -> None:
+            self.accept_count += 1
+            writer.close()
+
+        self.server = await asyncio.start_server(
+            accept_and_reject, "127.0.0.1", 0
+        )
+        port = self.server.sockets[0].getsockname()[1]
+
+        self.transport = AdsTcpTransport(
+            src_address=make_ams_address(), ip="127.0.0.1", port=port
+        )
+        # Shrink the backoff so several reconnect cycles fit into a short
+        # observation window without slowing down the suite.
+        self.transport.RECONNECT_INITIAL_BACKOFF = 0.05
+        self.transport.RECONNECT_MAX_BACKOFF = 0.2
+
+    async def asyncTearDown(self) -> None:
+        await self.transport.disconnect()
+        self.server.close()
+        await self.server.wait_closed()
+
+    async def test_reconnect_attempts_stay_bounded_when_peer_rejects_instantly(
+        self,
+    ) -> None:
+        # Arrange
+        window = 0.5
+        # The backoff must sleep at least 0.05 + 0.1 + 0.2 + 0.2 = 0.55s
+        # (before jitter) after the initial connect, so at most five accepts
+        # fit into the window. Anything near the bound still proves
+        # throttling; the unthrottled bug produced thousands per second.
+        max_expected_accepts = 6
+
+        # Act
+        await self.transport.connect()
+        await asyncio.sleep(window)
+
+        # Assert
+        self.assertLessEqual(
+            self.accept_count,
+            max_expected_accepts,
+            msg=(
+                f"Expected at most {max_expected_accepts} connection attempts "
+                f"in {window}s but the peer accepted {self.accept_count} — "
+                f"the reconnect backoff is not throttling"
+            ),
+        )
+
+
 class TestAdsTcpTransportKeepalive(unittest.TestCase):
     """TCP keepalive / liveness configuration applied to the active socket."""