testprotocols 0.5.0__tar.gz → 0.5.2__tar.gz

{testprotocols-0.5.0/src/testprotocols.egg-info → testprotocols-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: testprotocols
-Version: 0.5.0
+Version: 0.5.2
 Summary: Common Test Resource Layer — capability and device protocols for telco testing.
 Author-email: Alottabits <rjvisser@alottabits.com>
 Maintainer-email: Alottabits <rjvisser@alottabits.com>

{testprotocols-0.5.0 → testprotocols-0.5.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "testprotocols"
-version = "0.5.0"
+version = "0.5.2"
 description = "Common Test Resource Layer — capability and device protocols for telco testing."
 requires-python = ">=3.12"
 dependencies = []

{testprotocols-0.5.0 → testprotocols-0.5.2}/src/testprotocols/devices/client.py

@@ -134,6 +134,14 @@ class QoeMeasurementClientDevice(QoeClientDevice, Protocol):
     driver resolves from its homing config — read it here rather than reaching into
     a framework-specific config object."""
 
+    attachment_segment: str
+    """The declared segment LABEL of a guest-attached client (a client whose
+    test leg sits on a segment the testbed does not manage), empty for managed
+    homing or when undeclared. A stable role name (e.g. ``"provider-vpn"``),
+    never an address: it lets tests resolve "the client on segment X" by
+    declaration when address facts are foreign-owned or discovered late.
+    Vendor-neutral metadata from the driver's attachment config."""
+
 
 register_device_type("linux_lan_client", LanClientDevice)
 register_device_type("linux_wlan_client", WlanClientDevice)

testprotocols-0.5.2/src/testprotocols/dhcp_client.py

@@ -0,0 +1,57 @@
+"""DHCP / Client template.
+
+Defines the abstract contract for DHCP client operations including lease
+release and renewal for both IPv4 and IPv6, and the scoped lease observation
+that validates a served scope's option contents from the client side.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.dhcp import DhcpLeaseObservation
+
+
+@runtime_checkable
+class DhcpClient(Protocol):
+    """Abstract contract for DHCP client operations."""
+
+    def release_dhcp(self, interface: str) -> None:
+        """Release the DHCPv4 lease on *interface*."""
+        ...
+
+    def renew_dhcp(self, interface: str) -> None:
+        """Renew the DHCPv4 lease on *interface*."""
+        ...
+
+    def release_ipv6(self, interface: str, stateless: bool = False) -> None:
+        """Release the DHCPv6 lease on *interface*."""
+        ...
+
+    def renew_ipv6(self, interface: str, stateless: bool = False) -> None:
+        """Renew the DHCPv6 lease on *interface*."""
+        ...
+
+    def observe_lease(
+        self, interface: str, request_options: Sequence[int] = ()
+    ) -> DhcpLeaseObservation:
+        """Obtain a fresh DHCPv4 lease on *interface* as a scoped observation.
+
+        Performs a full DHCP exchange that explicitly requests every option
+        code in *request_options* (on top of the core lease parameters — a
+        DHCP server only answers the options a client asks for), WITHOUT
+        altering the interface's configured addressing: the lease exists as
+        an observation record, not as interface state. Returns the received
+        lease with its raw option values. The caller closes the observation
+        with :meth:`release_observed_lease`. Raises if no lease is granted.
+        """
+        ...
+
+    def release_observed_lease(self, interface: str) -> None:
+        """Release the lease obtained by :meth:`observe_lease` (idempotent).
+
+        Sends a DHCP release for the observed lease and discards the
+        observation record. A no-op when no observed lease is outstanding.
+        """
+        ...

{testprotocols-0.5.0 → testprotocols-0.5.2}/src/testprotocols/ip_interface.py

@@ -37,6 +37,18 @@ class IpInterface(Protocol):
         """Return the MTU size of *interface*."""
         ...
 
+    def set_interface_mtu_size(self, interface: str, mtu: int) -> None:
+        """Set the MTU of *interface* to *mtu* bytes.
+
+        The write counterpart to :meth:`get_interface_mtu_size`. Lowering the
+        MTU also lowers the MSS the host advertises on that interface, so it
+        governs TCP segment size in *both* directions of a flow — unlike a
+        per-socket ``TCP_MAXSEG``, which caps only the local send. Stateless
+        in contract: a caller that needs to revert captures the prior via
+        :meth:`get_interface_mtu_size` and restores it itself.
+        """
+        ...
+
     def is_link_up(self, interface: str, pattern: str = "BROADCAST,MULTICAST,UP") -> bool:
         """Return True if *interface* flags match *pattern*."""
         ...

{testprotocols-0.5.0 → testprotocols-0.5.2}/src/testprotocols/iperf_client.py

@@ -29,6 +29,7 @@ class IperfClient(Protocol):
         omit_s: int | None = None,
         json_output: bool = False,
         window: str | None = None,
+        parallel: int | None = None,
     ) -> tuple[int, str]:
         """Start an iperf traffic sender towards *host* on *traffic_port*.
 
@@ -36,6 +37,9 @@ class IperfClient(Protocol):
 
         - ``reverse``: iperf3 reverse mode (``-R``) — the listening receiver
           transmits; the sender still initiates the connection.
+        - ``parallel``: run the session over N parallel streams (``-P <n>``).
+          The end-of-test ``sum``/``sum_received`` summaries aggregate across
+          the streams, so a multi-stream session reports ONE aggregate rate.
         - ``omit_s``: skip the first N seconds (``-O <n>``, the TCP slow-start
           ramp); omitted seconds extend the wall clock and are excluded from
           the end-of-test summary.

{testprotocols-0.5.0 → testprotocols-0.5.2}/src/testprotocols/models/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from testprotocols.models.dhcp import DHCPTraceData, DHCPV6TraceData
+from testprotocols.models.dhcp import DhcpLeaseObservation, DHCPTraceData, DHCPV6TraceData
 from testprotocols.models.firewall import (
     Connection,
     ConntrackStats,
@@ -172,6 +172,7 @@ __all__ = [
     # tr069
     "CpeConnectionStatus",
     # dhcp
+    "DhcpLeaseObservation",
     "DHCPTraceData",
     "DHCPV6TraceData",
     "DhcpLease",

testprotocols-0.5.2/src/testprotocols/models/dhcp.py

@@ -0,0 +1,65 @@
+"""DHCP and DHCPv6 packet trace data models."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from testprotocols.models.networking import IPAddresses
+
+
+@dataclass(frozen=True)
+class DhcpLeaseObservation:
+    """A DHCPv4 lease obtained as a scoped observation, with its received options.
+
+    Produced by :meth:`testprotocols.dhcp_client.DhcpClient.observe_lease` —
+    the lease a server granted to a client that explicitly requested a set of
+    option codes, read from the client's own lease records (data-plane truth).
+
+    The typed fields surface the core lease parameters. ``options`` carries the
+    raw client-reported value string of every other option present in the
+    lease, keyed by option code, exactly as the client recorded it — no
+    normalization; value-comparison semantics belong to the caller.
+    """
+
+    address: str
+    """The leased IPv4 address (dotted quad)."""
+
+    subnet_mask: str = ""
+    """Received subnet mask, option 1 (dotted quad; empty if absent)."""
+
+    gateway: str = ""
+    """First received router, option 3 (dotted quad; empty if absent)."""
+
+    dns_servers: tuple[str, ...] = ()
+    """Received DNS servers, option 6, in server order."""
+
+    lease_time_s: int = 0
+    """Received lease time in seconds, option 51 (0 if absent)."""
+
+    server: str = ""
+    """The DHCP server identifier, option 54 (dotted quad; empty if absent)."""
+
+    options: Mapping[int, str] = field(default_factory=dict)
+    """Raw received value per option code, as reported by the client."""
+
+
+@dataclass
+class DHCPTraceData:
+    """Holds a captured DHCPv4 packet with source/destination addresses and message type."""
+
+    source: IPAddresses
+    destination: IPAddresses
+    dhcp_packet: dict[str, Any]
+    dhcp_message_type: int
+
+
+@dataclass
+class DHCPV6TraceData:
+    """Holds a captured DHCPv6 packet with source/destination addresses and message type."""
+
+    source: IPAddresses
+    destination: IPAddresses
+    dhcpv6_packet: dict[str, Any]
+    dhcpv6_message_type: int

{testprotocols-0.5.0 → testprotocols-0.5.2/src/testprotocols.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: testprotocols
-Version: 0.5.0
+Version: 0.5.2
 Summary: Common Test Resource Layer — capability and device protocols for telco testing.
 Author-email: Alottabits <rjvisser@alottabits.com>
 Maintainer-email: Alottabits <rjvisser@alottabits.com>

{testprotocols-0.5.0 → testprotocols-0.5.2}/tests/test_dhcp_templates.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from testprotocols.dhcp_client import DhcpClient
 from testprotocols.dhcp_server import DhcpServer
+from testprotocols.models.dhcp import DhcpLeaseObservation
 
 # ---------------------------------------------------------------------------
 # DhcpClient
@@ -16,11 +17,30 @@ def test_dhcp_client_is_runtime_checkable() -> None:
 
 def test_dhcp_client_protocol_shape() -> None:
     """DhcpClient declares the expected method set."""
-    expected = {"release_dhcp", "renew_dhcp", "release_ipv6", "renew_ipv6"}
+    expected = {
+        "release_dhcp",
+        "renew_dhcp",
+        "release_ipv6",
+        "renew_ipv6",
+        "observe_lease",
+        "release_observed_lease",
+    }
     actual = set(DhcpClient.__protocol_attrs__)
     assert expected <= actual, f"missing: {expected - actual}"
 
 
+def test_dhcp_lease_observation_defaults() -> None:
+    """Only the address is mandatory; every other field has an empty default."""
+    obs = DhcpLeaseObservation(address="192.0.2.10")
+    assert obs.address == "192.0.2.10"
+    assert obs.subnet_mask == ""
+    assert obs.gateway == ""
+    assert obs.dns_servers == ()
+    assert obs.lease_time_s == 0
+    assert obs.server == ""
+    assert dict(obs.options) == {}
+
+
 # ---------------------------------------------------------------------------
 # DhcpServer
 # ---------------------------------------------------------------------------

{testprotocols-0.5.0 → testprotocols-0.5.2}/tests/test_ip_interface.py

@@ -18,6 +18,7 @@ def test_ip_interface_protocol_shape() -> None:
         "get_interface_macaddr",
         "get_interface_mask",
         "get_interface_mtu_size",
+        "set_interface_mtu_size",
         "is_link_up",
         "set_link_state",
         "enable_ipv6",

testprotocols-0.5.0/src/testprotocols/dhcp_client.py

@@ -1,30 +0,0 @@
-"""DHCP / Client template.
-
-Defines the abstract contract for DHCP client operations including lease
-release and renewal for both IPv4 and IPv6.
-"""
-
-from __future__ import annotations
-
-from typing import Protocol, runtime_checkable
-
-
-@runtime_checkable
-class DhcpClient(Protocol):
-    """Abstract contract for DHCP client operations."""
-
-    def release_dhcp(self, interface: str) -> None:
-        """Release the DHCPv4 lease on *interface*."""
-        ...
-
-    def renew_dhcp(self, interface: str) -> None:
-        """Renew the DHCPv4 lease on *interface*."""
-        ...
-
-    def release_ipv6(self, interface: str, stateless: bool = False) -> None:
-        """Release the DHCPv6 lease on *interface*."""
-        ...
-
-    def renew_ipv6(self, interface: str, stateless: bool = False) -> None:
-        """Renew the DHCPv6 lease on *interface*."""
-        ...

testprotocols-0.5.0/src/testprotocols/models/dhcp.py

@@ -1,28 +0,0 @@
-"""DHCP and DHCPv6 packet trace data models."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any
-
-from testprotocols.models.networking import IPAddresses
-
-
-@dataclass
-class DHCPTraceData:
-    """Holds a captured DHCPv4 packet with source/destination addresses and message type."""
-
-    source: IPAddresses
-    destination: IPAddresses
-    dhcp_packet: dict[str, Any]
-    dhcp_message_type: int
-
-
-@dataclass
-class DHCPV6TraceData:
-    """Holds a captured DHCPv6 packet with source/destination addresses and message type."""
-
-    source: IPAddresses
-    destination: IPAddresses
-    dhcpv6_packet: dict[str, Any]
-    dhcpv6_message_type: int