aioads 0.1.0.dev6__tar.gz → 0.1.0.dev8__tar.gz

{aioads-0.1.0.dev6 → 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.dev6 → 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.dev6 → aioads-0.1.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aioads
-Version: 0.1.0.dev6
+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.dev6 → aioads-0.1.0.dev8}/aioads/transport.py

@@ -7,6 +7,7 @@ import enum
 import logging
 import random
 import re
+import socket
 from abc import ABC
 from dataclasses import dataclass
 from dataclasses import field
@@ -210,6 +211,30 @@ 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
+    # idle-eviction) is never detected: no FIN/RST arrives, so the read loop
+    # blocks forever and the supervisor never reconnects. These force the kernel
+    # to probe an idle peer and to bound how long unacked writes wait, so a dead
+    # link surfaces as a socket error within ~KEEPALIVE_IDLE + KEEPALIVE_INTERVAL
+    # * KEEPALIVE_COUNT seconds.
+    KEEPALIVE_IDLE = 10
+    """Seconds of idle before the kernel starts sending keepalive probes (Linux: TCP_KEEPIDLE)."""
+    KEEPALIVE_INTERVAL = 3
+    """Seconds between keepalive probes (Linux: TCP_KEEPINTVL)."""
+    KEEPALIVE_COUNT = 3
+    """Unanswered probes before the connection is considered dead (Linux: TCP_KEEPCNT)."""
+    USER_TIMEOUT_MS = 15_000
+    """Milliseconds an unacked write may wait before the socket errors (Linux: TCP_USER_TIMEOUT)."""
 
     def __init__(
         self,
@@ -279,10 +304,43 @@ class AdsTcpTransport(BaseTransport, ITransport):
         reader, writer = await asyncio.wait_for(
             asyncio.open_connection(self.ip, self.port), self.CONNECT_TIMEOUT
         )
+
+        self._enable_keepalive(writer)
         async with self._stream_lock:
             self._stream = (reader, writer)
         self._state = ConnectionState.CONNECTED
 
+    def _enable_keepalive(self, writer: asyncio.StreamWriter) -> None:
+        """
+        Enable TCP keepalive so a half-open connection is detected 
+        even when no FIN/RST is ever sent.
+
+        The per-option settings beyond SO_KEEPALIVE are platform specific; each
+        is applied only when the running platform exposes it, so this stays a
+        no-op on systems that lack the knob rather than raising.
+        """
+
+        sock: socket.socket | None = writer.get_extra_info("socket")
+        if sock is None:
+            self.logger.warning(
+                "Failed to enable TCP keepalive: StreamWriter has no socket"
+            )
+            return
+
+        try:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+            for opt_name, value in (
+                ("TCP_KEEPIDLE", self.KEEPALIVE_IDLE),
+                ("TCP_KEEPINTVL", self.KEEPALIVE_INTERVAL),
+                ("TCP_KEEPCNT", self.KEEPALIVE_COUNT),
+                ("TCP_USER_TIMEOUT", self.USER_TIMEOUT_MS),
+            ):
+                opt = getattr(socket, opt_name, None)
+                if opt is not None:
+                    sock.setsockopt(socket.IPPROTO_TCP, opt, value)
+        except OSError as e:
+            self.logger.warning("Failed to enable TCP keepalive: %s", e)
+
     async def _teardown_stream(self, ex: BaseException):
         """
         Fail all in-flight requests and close the current stream (if any).
@@ -359,12 +417,19 @@ 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
+            except asyncio.CancelledError:  # pylint: disable=try-except-raise
                 # Except everything... except a cancellation event
                 raise
             except Exception as e:
@@ -376,13 +441,23 @@ 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
+                except asyncio.CancelledError:  # pylint: disable=try-except-raise
                     raise
                 except Exception as e:  # pylint: disable=broad-exception-caught
                     self.logger.info(

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

@@ -1,6 +1,6 @@
 [project]
 name = "aioads"
-version = "0.1.0.dev6"
+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.dev6 → aioads-0.1.0.dev8}/tests/unit/test_transport.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import logging
+import socket
 import unittest
 from unittest.mock import Mock
 
@@ -216,5 +217,136 @@ 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."""
+
+    def setUp(self) -> None:
+        self.transport = AdsTcpTransport(
+            src_address=make_ams_address(), ip="127.0.0.1"
+        )
+        # A real AF_INET TCP socket whose options we can read back. It does not
+        # need to be connected to accept these socket options.
+        self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self.addCleanup(self.sock.close)
+        # A StreamWriter exposes its underlying socket via get_extra_info("socket").
+        self.writer = Mock()
+        self.writer.get_extra_info.return_value = self.sock
+
+    def test_enable_keepalive_turns_on_so_keepalive(self) -> None:
+        # Act
+        self.transport._enable_keepalive(self.writer)
+
+        # Assert
+        self.assertEqual(
+            self.sock.getsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE), 1
+        )
+
+    @unittest.skipUnless(
+        hasattr(socket, "TCP_KEEPIDLE"), "platform lacks TCP keepalive tuning"
+    )
+    def test_enable_keepalive_applies_configured_tuning_values(self) -> None:
+        # Act
+        self.transport._enable_keepalive(self.writer)
+
+        # Assert — each kernel knob reflects the transport's configured constant
+        expected = [
+            ("TCP_KEEPIDLE", AdsTcpTransport.KEEPALIVE_IDLE),
+            ("TCP_KEEPINTVL", AdsTcpTransport.KEEPALIVE_INTERVAL),
+            ("TCP_KEEPCNT", AdsTcpTransport.KEEPALIVE_COUNT),
+            ("TCP_USER_TIMEOUT", AdsTcpTransport.USER_TIMEOUT_MS),
+        ]
+        for opt_name, value in expected:
+            opt = getattr(socket, opt_name, None)
+            if opt is None:
+                continue
+            with self.subTest(option=opt_name):
+                self.assertEqual(
+                    self.sock.getsockopt(socket.IPPROTO_TCP, opt), value
+                )
+
+    def test_enable_keepalive_without_socket_does_not_raise(self) -> None:
+        # Arrange — a StreamWriter without an underlying socket
+        self.writer.get_extra_info.return_value = None
+
+        # Act / Assert — keepalive is best-effort, so it is skipped quietly
+        try:
+            self.transport._enable_keepalive(self.writer)
+        except Exception as e:  # pragma: no cover - failure path
+            self.fail(f"_enable_keepalive must not raise when no socket: {e}")
+
+    def test_enable_keepalive_on_closed_socket_does_not_raise(self) -> None:
+        # Arrange — a closed socket makes setsockopt fail with OSError
+        self.sock.close()
+
+        # Act / Assert — keepalive is best-effort, so the error is swallowed
+        try:
+            self.transport._enable_keepalive(self.writer)
+        except OSError:
+            self.fail("_enable_keepalive must not propagate socket errors")
+
+
 if __name__ == "__main__":
     unittest.main()