testprotocols 0.1.0__tar.gz → 0.2.0__tar.gz

{testprotocols-0.1.0/src/testprotocols.egg-info → testprotocols-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: testprotocols
-Version: 0.1.0
+Version: 0.2.0
 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.1.0 → testprotocols-0.2.0}/pyproject.toml

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

{testprotocols-0.1.0 → testprotocols-0.2.0}/src/testprotocols/__init__.py

@@ -47,7 +47,6 @@ from testprotocols.gateway_redundancy import GatewayRedundancy
 from testprotocols.http_client import HttpClient
 from testprotocols.http_server import HttpServer
 from testprotocols.hw_console import HwConsole
-from testprotocols.infra_controller import InfraController
 from testprotocols.interface_dhcp import InterfaceDhcp
 from testprotocols.ip_interface import IpInterface
 from testprotocols.ip_routing import IpRouting
@@ -136,7 +135,6 @@ __all__ = [
     "HttpClient",
     "HttpServer",
     "HwConsole",
-    "InfraController",
     "InterfaceDhcp",
     "IpInterface",
     "IpRouting",

{testprotocols-0.1.0 → testprotocols-0.2.0}/src/testprotocols/appliance_vlans.py

@@ -5,8 +5,8 @@ subnet/addressing and DHCP configuration, plus observed DHCP leases. This is the
 appliance counterpart to a Linux host's interface + DHCP-server surfaces — an
 appliance configures DHCP per VLAN, not via a host daemon.
 
-In scope: list/get/set VLAN configuration (incl. per-VLAN DHCP), and read DHCP
-leases.
+In scope: list/get/set/delete VLAN configuration (incl. per-VLAN DHCP), and read
+DHCP leases.
 
 Out of scope: WAN uplink status (see ``appliance_uplinks``), L3 firewall
 (see ``l3_firewall``), and host-style per-interface config (see ``ip_interface``).
@@ -38,6 +38,19 @@ class ApplianceVlans(Protocol):
         """Create or replace the VLAN identified by ``config.vlan_id``."""
         ...
 
+    def delete_vlan(self, vlan_id: int) -> None:
+        """Remove the LAN VLAN identified by *vlan_id*.
+
+        Per-object remove, completing the VLAN CRUD surface (mirrors
+        ``StaticRoutes.remove_static_route``). On management planes that model the
+        LAN as one config blob, a driver implements this as read-modify-write of
+        that module. Deleting a missing VLAN may raise or succeed by plane;
+        callers needing idempotence should check first (``get_vlan`` raises
+        KeyError when absent). A plane that cannot remove a required / last LAN
+        VLAN raises unsupported-capability.
+        """
+        ...
+
     def get_dhcp_leases(self, vlan_id: int | None = None) -> list[DhcpLease]:
         """Return current DHCP leases, optionally filtered to one *vlan_id*.
 

{testprotocols-0.1.0 → testprotocols-0.2.0}/src/testprotocols/devices/client.py

@@ -24,6 +24,7 @@ from testprotocols.ntp_client import NtpClient
 from testprotocols.packet_filter import PacketFilter
 from testprotocols.pcap_capture import PcapCapture
 from testprotocols.qoe_browser import QoeBrowser
+from testprotocols.reachability_responder import ReachabilityResponder
 from testprotocols.syslog_config import SyslogConfig
 from testprotocols.upnp_client import UpnpClient
 from testprotocols.vlan_client import VlanClient
@@ -124,8 +125,15 @@ class QoeMeasurementClientDevice(QoeClientDevice, Protocol):
     iperf_client: IperfClient
     iperf_server: IperfServer
     network_probe: NetworkProbe
+    responder: ReachabilityResponder
     pcap: PcapCapture
 
+    test_ip: str
+    """The client's test-plane address as a CIDR (e.g. ``"10.1.30.50/24"``), empty
+    if the client is not homed to a test segment. Vendor-neutral metadata the
+    driver resolves from its homing config — read it here rather than reaching into
+    a framework-specific config object."""
+
 
 register_device_type("linux_lan_client", LanClientDevice)
 register_device_type("linux_wlan_client", WlanClientDevice)

{testprotocols-0.1.0 → testprotocols-0.2.0}/src/testprotocols/devices/sdwan.py

@@ -8,8 +8,8 @@ from testprotocols.appliance_nat import ApplianceNat
 from testprotocols.appliance_uplinks import ApplianceUplinks
 from testprotocols.appliance_vlans import ApplianceVlans
 from testprotocols.bgp import Bgp
-from testprotocols.content_filtering import ContentFiltering
 from testprotocols.conntrack import Conntrack
+from testprotocols.content_filtering import ContentFiltering
 from testprotocols.devices import register_device_type
 from testprotocols.devices.base import BaseDeviceProtocol
 from testprotocols.ip_interface import IpInterface
@@ -93,5 +93,11 @@ class SdwanApplianceDevice(BaseDeviceProtocol, Protocol):
     lan: ApplianceVlans
     syslog: SyslogConfig
 
+    model: str
+    """Hardware model identifier (e.g. ``"MX250"``) — vendor-neutral metadata the
+    driver resolves from its management API / inventory. The coverage axis for
+    model-parameterised tests; read it here rather than reaching into a
+    framework-specific config object."""
+
 
 register_device_type("sdwan_appliance", SdwanApplianceDevice)

{testprotocols-0.1.0 → testprotocols-0.2.0}/src/testprotocols/models/qoe.py

@@ -29,3 +29,4 @@ class MeasurementSpec:
     completion: str = "networkidle"
     timeout_ms: int = 30000
     duration_s: int | None = None
+    force_quic: bool = True

testprotocols-0.2.0/src/testprotocols/network_probe.py

@@ -0,0 +1,49 @@
+"""Network reachability probe template.
+
+Defines the abstract contract for L3/L4 reachability checks initiated from
+a host toward an external target. Distinct from ``HttpClient`` (which is
+app-layer): a ``NetworkProbe`` verifies whether the SYN/ACK handshake
+completes, not whether an HTTP responder is configured at the far end.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class NetworkProbe(Protocol):
+    """Abstract contract for L3/L4 reachability probes."""
+
+    def tcp_can_connect(self, host: str, port: int, timeout: int = 5) -> bool:
+        """Attempt a TCP connection to *host*:*port* and return reachability.
+
+        Returns ``True`` if the three-way handshake completes within
+        *timeout* seconds, ``False`` otherwise (connection refused, no
+        route, filtered, timed out). The probe is read-only — no data is
+        sent on the connection — so it is safe to call against arbitrary
+        targets without side effects on the destination.
+        """
+        ...
+
+    def icmp_can_reach(self, host: str, count: int = 1, timeout: int = 5) -> bool:
+        """Attempt an ICMP echo to *host* and return reachability.
+
+        Returns ``True`` if at least one of *count* echo requests is answered
+        within *timeout* seconds, ``False`` otherwise (no route, filtered,
+        timed out). Read-only — echo requests have no side effect on the
+        destination.
+        """
+        ...
+
+    def udp_can_reach(self, host: str, port: int, timeout: int = 5) -> bool:
+        """Attempt a UDP exchange with *host*:*port* and return reachability.
+
+        UDP is connectionless and has no handshake, so a dropped datagram is
+        indistinguishable from a delivered one at the sender unless the far end
+        replies. This probe therefore reports reachability based on a **reply**
+        from a UDP responder at the target within *timeout* seconds — callers
+        that need a definitive verdict must ensure a responder is present. A
+        missing reply (no responder, no route, or filtered) is ``False``.
+        """
+        ...

{testprotocols-0.1.0 → testprotocols-0.2.0}/src/testprotocols/qoe_browser.py

@@ -27,8 +27,16 @@ class QoeBrowser(Protocol):
         scenario: str = "page_load",
         wait_until: str = "networkidle",
         timeout_ms: int = 30000,
+        force_quic: bool = True,
     ) -> QoEResult:
-        """Measure productivity-app QoE for *url* (e.g., page-load time)."""
+        """Measure productivity-app QoE for *url* (e.g., page-load time).
+
+        ``force_quic=True`` (default) forces HTTP/3/QUIC, as a QoE measurement
+        should. Set ``force_quic=False`` for a reachability/block probe: the
+        navigation runs over TCP/h2 (QUIC disabled), so a non-HTTP/3 site stays
+        reachable and a TCP/TLS-inspecting middlebox (e.g. content filtering)
+        actually sees the traffic.
+        """
         ...
 
     def measure_streaming(

testprotocols-0.2.0/src/testprotocols/reachability_responder.py

@@ -0,0 +1,55 @@
+"""Reachability responder template — the answerer counterpart to ``NetworkProbe``.
+
+``NetworkProbe`` *sends* reachability probes; a peer being probed must *answer*
+them or a "blocked" verdict is indistinguishable from "no listener". This
+capability stands up those answerers on the target's test interface:
+
+* **TCP** — a listener that accepts connections (a ``tcp_can_connect`` connect
+  probe completes the handshake on accept).
+* **UDP** — an echo responder (a content-based ``udp_can_reach`` probe sends a
+  token and is reachable iff it is echoed back).
+
+ICMP needs no responder (the kernel answers echo requests). The pairing is
+explicit and 1:1:
+
+    NetworkProbe.tcp_can_connect  <->  ReachabilityResponder.start_tcp_responder
+    NetworkProbe.udp_can_reach    <->  ReachabilityResponder.start_udp_responder
+    NetworkProbe.icmp_can_reach   <->  (none — kernel)
+
+Vendor-neutral contract; the listener mechanism (sockets / ``socat`` / a service)
+lives entirely in the per-plugin impl, exactly as ``NetworkProbe`` impls do.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ReachabilityResponder(Protocol):
+    """Abstract contract for standing up / tearing down reachability responders."""
+
+    def start_tcp_responder(self, port: int) -> None:
+        """Start a TCP responder on *port* that accepts connections.
+
+        A connect-only ``NetworkProbe.tcp_can_connect`` probe completes its
+        handshake against this listener, so an open path reads as reachable.
+        """
+        ...
+
+    def start_udp_responder(self, port: int) -> None:
+        """Start a UDP echo responder on *port*.
+
+        Reflects every datagram it receives back to the sender, so a peer's
+        content-based ``NetworkProbe.udp_can_reach`` probe gets its token echoed
+        when the path is open — making "blocked" distinguishable from
+        "no listener" on the connectionless protocol.
+        """
+        ...
+
+    def stop(self, port: int | None = None) -> None:
+        """Stop the responders on *port* (both protocols); ``None`` stops all.
+
+        No-op if none is running.
+        """
+        ...

{testprotocols-0.1.0 → testprotocols-0.2.0/src/testprotocols.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: testprotocols
-Version: 0.1.0
+Version: 0.2.0
 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.1.0 → testprotocols-0.2.0}/src/testprotocols.egg-info/SOURCES.txt

@@ -25,7 +25,6 @@ src/testprotocols/gateway_redundancy.py
 src/testprotocols/http_client.py
 src/testprotocols/http_server.py
 src/testprotocols/hw_console.py
-src/testprotocols/infra_controller.py
 src/testprotocols/interface_dhcp.py
 src/testprotocols/ip_interface.py
 src/testprotocols/ip_routing.py
@@ -55,6 +54,7 @@ src/testprotocols/py.typed
 src/testprotocols/qoe_browser.py
 src/testprotocols/radius_client.py
 src/testprotocols/radius_server.py
+src/testprotocols/reachability_responder.py
 src/testprotocols/routed_interfaces.py
 src/testprotocols/router.py
 src/testprotocols/routing_read.py
@@ -119,6 +119,7 @@ src/testprotocols/models/tr069.py
 src/testprotocols/models/traffic.py
 src/testprotocols/models/wan_edge.py
 src/testprotocols/models/wifi.py
+tests/test_appliance_vlans.py
 tests/test_cpe_templates.py
 tests/test_device_types.py
 tests/test_dhcp_templates.py

testprotocols-0.2.0/tests/test_appliance_vlans.py

@@ -0,0 +1,33 @@
+"""Protocol-conformance tests for ApplianceVlans (runtime_checkable structural check)."""
+
+from __future__ import annotations
+
+from testprotocols.appliance_vlans import ApplianceVlans
+
+
+class _Complete:
+    """Has every ApplianceVlans member, including delete_vlan."""
+
+    def list_vlans(self): ...
+    def get_vlan(self, vlan_id): ...
+    def set_vlan(self, config): ...
+    def delete_vlan(self, vlan_id): ...
+    def get_dhcp_leases(self, vlan_id=None): ...
+
+
+class _NoDelete:
+    """Missing delete_vlan — must NOT satisfy the protocol once delete_vlan is declared."""
+
+    def list_vlans(self): ...
+    def get_vlan(self, vlan_id): ...
+    def set_vlan(self, config): ...
+    def get_dhcp_leases(self, vlan_id=None): ...
+
+
+def test_complete_impl_satisfies_protocol():
+    assert isinstance(_Complete(), ApplianceVlans)
+
+
+def test_delete_vlan_is_required_by_protocol():
+    # runtime_checkable isinstance requires every declared member be present.
+    assert not isinstance(_NoDelete(), ApplianceVlans)

{testprotocols-0.1.0 → testprotocols-0.2.0}/tests/test_device_types.py

@@ -320,6 +320,7 @@ def test_qoe_measurement_client_aggregates_expected_capabilities() -> None:
         "iperf_client",
         "iperf_server",
         "network_probe",
+        "responder",
         "pcap",
         "syslog",
     }

testprotocols-0.1.0/src/testprotocols/infra_controller.py

@@ -1,28 +0,0 @@
-"""Infra-controller capability template.
-
-Abstract contract for environment/fabric control delegated by the test
-orchestrator to a hypervisor (vSphere). It reads and (for re-homing) moves a
-VM NIC's port-group, and asserts a named port-group is present. It does NOT
-create fabric — the lab carries the test VLANs already.
-"""
-
-from __future__ import annotations
-
-from typing import Protocol, runtime_checkable
-
-
-@runtime_checkable
-class InfraController(Protocol):
-    """Read / presence-check / move a VM NIC's port-group."""
-
-    def get_nic_portgroup(self, vm_name: str, nic_index: int) -> str:
-        """Return the portgroup name backing NIC *nic_index* on *vm_name*."""
-        ...
-
-    def ensure_port_group(self, name: str) -> None:
-        """Assert a portgroup named *name* exists (raise if absent). No create."""
-        ...
-
-    def set_nic_portgroup(self, vm_name: str, nic_index: int, portgroup: str) -> None:
-        """Repoint NIC *nic_index* on *vm_name* onto the named *portgroup*."""
-        ...

testprotocols-0.1.0/src/testprotocols/network_probe.py

@@ -1,27 +0,0 @@
-"""Network reachability probe template.
-
-Defines the abstract contract for L3/L4 reachability checks initiated from
-a host toward an external target. Distinct from ``HttpClient`` (which is
-app-layer): a ``NetworkProbe`` verifies whether the SYN/ACK handshake
-completes, not whether an HTTP responder is configured at the far end.
-"""
-
-from __future__ import annotations
-
-from typing import Protocol, runtime_checkable
-
-
-@runtime_checkable
-class NetworkProbe(Protocol):
-    """Abstract contract for L3/L4 reachability probes."""
-
-    def tcp_can_connect(self, host: str, port: int, timeout: int = 5) -> bool:
-        """Attempt a TCP connection to *host*:*port* and return reachability.
-
-        Returns ``True`` if the three-way handshake completes within
-        *timeout* seconds, ``False`` otherwise (connection refused, no
-        route, filtered, timed out). The probe is read-only — no data is
-        sent on the connection — so it is safe to call against arbitrary
-        targets without side effects on the destination.
-        """
-        ...