testprotocols 0.1.0__py3-none-any.whl

testprotocols/http_server.py

@@ -0,0 +1,22 @@
+"""HTTP / Server template.
+
+Defines the abstract contract for HTTP server operations including
+starting and stopping an HTTP service.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class HttpServer(Protocol):
+    """Abstract contract for HTTP server operations."""
+
+    def start_http_service(self, port: str, ip_version: str) -> str:
+        """Start an HTTP service on *port* for *ip_version*."""
+        ...
+
+    def stop_http_service(self, port: str) -> None:
+        """Stop the HTTP service listening on *port*."""
+        ...

testprotocols/hw_console.py

@@ -0,0 +1,48 @@
+"""Hardware console template.
+
+Defines the abstract contract for managing physical hardware consoles,
+power cycling, and bootloader-level flashing of a device under test.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class HwConsole(Protocol):
+    """Abstract contract for hardware console and power management operations."""
+
+    def connect_to_consoles(self, device_name: str) -> None:
+        """Connect to all hardware consoles for the named device."""
+        ...
+
+    def disconnect_from_consoles(self) -> None:
+        """Disconnect from all hardware consoles."""
+        ...
+
+    def get_console(self, console_name: str) -> Any:
+        """Return the console object identified by *console_name*."""
+        ...
+
+    def get_interactive_consoles(self) -> dict[str, Any]:
+        """Return a mapping of console names to interactive console objects."""
+        ...
+
+    def power_cycle(self) -> None:
+        """Power cycle the device (power off, then power on)."""
+        ...
+
+    def wait_for_hw_boot(self) -> None:
+        """Block until the hardware has completed its boot sequence."""
+        ...
+
+    def flash_via_bootloader(
+        self,
+        image: str,
+        tftp_devices: dict[str, Any],
+        termination_sys: Any = None,
+        method: str | None = None,
+    ) -> None:
+        """Flash the given image to the device via the bootloader."""
+        ...

testprotocols/infra_controller.py

@@ -0,0 +1,28 @@
+"""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/interface_dhcp.py

@@ -0,0 +1,30 @@
+"""Per-SVI DHCP server/relay configuration (reuses appliance DHCP models)."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.sdwan_appliance import DhcpLease
+from testprotocols.models.switch_routing import InterfaceDhcpConfig
+
+
+@runtime_checkable
+class InterfaceDhcp(Protocol):
+    """Abstract contract for per-interface DHCP server/relay.
+
+    Best-effort lease read: a product without a true lease table may approximate
+    or raise unsupported-capability on ``get_dhcp_leases``.
+    """
+
+    def set_interface_dhcp(self, config: InterfaceDhcpConfig) -> None:
+        """Create or replace the DHCP config for ``config.interface``."""
+        ...
+
+    def get_interface_dhcp(self, interface: str) -> InterfaceDhcpConfig:
+        """Return the DHCP config for *interface*."""
+        ...
+
+    def get_dhcp_leases(self, interface: str | None = None) -> list[DhcpLease]:
+        """Return current DHCP leases (best-effort; a product without a true
+        lease table may approximate or raise unsupported-capability)."""
+        ...

testprotocols/ip_interface.py

@@ -0,0 +1,62 @@
+"""IP / Interface template.
+
+Defines the abstract contract for querying and configuring IP interface state.
+"""
+
+from __future__ import annotations
+
+from ipaddress import IPv4Address
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class IpInterface(Protocol):
+    """Abstract contract for IP interface operations."""
+
+    def get_interface_ipv4addr(self, interface: str) -> str:
+        """Return the IPv4 address assigned to *interface*."""
+        ...
+
+    def get_interface_ipv6addr(self, interface: str) -> str:
+        """Return the global IPv6 address assigned to *interface*."""
+        ...
+
+    def get_interface_link_local_ipv6addr(self, interface: str) -> str:
+        """Return the link-local IPv6 address of *interface*."""
+        ...
+
+    def get_interface_macaddr(self, interface: str) -> str:
+        """Return the MAC address of *interface*."""
+        ...
+
+    def get_interface_mask(self, interface: str) -> str:
+        """Return the subnet mask of *interface*."""
+        ...
+
+    def get_interface_mtu_size(self, interface: str) -> int:
+        """Return the MTU size of *interface*."""
+        ...
+
+    def is_link_up(self, interface: str, pattern: str = "BROADCAST,MULTICAST,UP") -> bool:
+        """Return True if *interface* flags match *pattern*."""
+        ...
+
+    def set_link_state(self, interface: str, state: str) -> None:
+        """Bring *interface* up or down according to *state*."""
+        ...
+
+    def enable_ipv6(self) -> None:
+        """Enable IPv6 on the device."""
+        ...
+
+    def disable_ipv6(self) -> None:
+        """Disable IPv6 on the device."""
+        ...
+
+    def set_static_ip(self, interface: str, ip_address: IPv4Address, netmask: IPv4Address) -> None:
+        """Assign a static IP address and netmask to *interface*."""
+        ...
+
+    def remove_static_ip(self, interface: str) -> None:
+        """Remove any static IP address configuration from *interface*."""
+        ...

testprotocols/ip_routing.py

@@ -0,0 +1,57 @@
+"""IP / Routing template.
+
+Defines the abstract contract for IP routing operations such as ping, traceroute,
+and default gateway management.
+"""
+
+from __future__ import annotations
+
+from ipaddress import IPv4Address
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class IpRouting(Protocol):
+    """Abstract contract for IP routing operations."""
+
+    def ping(
+        self,
+        ping_ip: str,
+        ping_count: int = 4,
+        ping_interface: str | None = None,
+        options: str = "",
+        timeout: int = 50,
+        json_output: bool = False,
+    ) -> bool | dict[str, Any]:
+        """Send ICMP echo requests to *ping_ip* and return success or parsed output."""
+        ...
+
+    def traceroute(
+        self,
+        host_ip: str | IPv4Address,
+        version: str = "",
+        options: str = "",
+        timeout: int = 60,
+    ) -> str | None:
+        """Run a traceroute to *host_ip* and return the output."""
+        ...
+
+    def add_route(self, destination: str, gw_interface: str) -> None:
+        """Add a static route to *destination* via *gw_interface*."""
+        ...
+
+    def delete_route(self, destination: str) -> None:
+        """Delete the static route to *destination*."""
+        ...
+
+    def get_default_gateway(self) -> IPv4Address:
+        """Return the current default gateway address."""
+        ...
+
+    def del_default_route(self, interface: str | None = None) -> None:
+        """Delete the default route, optionally scoped to *interface*."""
+        ...
+
+    def set_default_gw(self, ip_address: IPv4Address, interface: str) -> None:
+        """Set the default gateway to *ip_address* via *interface*."""
+        ...

testprotocols/iperf_client.py

@@ -0,0 +1,47 @@
+"""Traffic / IperfClient template.
+
+Defines the abstract contract for iperf client operations including
+sending traffic and collecting logs.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class IperfClient(Protocol):
+    """Abstract contract for iperf client (traffic sender) operations."""
+
+    def start_traffic_sender(
+        self,
+        host: str,
+        traffic_port: int,
+        bandwidth: int | None = None,
+        bind_to_ip: str | None = None,
+        direction: str | None = None,
+        ip_version: int | None = None,
+        udp_protocol: bool = False,
+        time: int = 10,
+        client_port: int | None = None,
+        udp_only: bool | None = None,
+    ) -> tuple[int, str]:
+        """Start an iperf traffic sender towards *host* on *traffic_port*.
+
+        Returns a tuple of (pid, log_file_path).
+        """
+        ...
+
+    def stop_traffic(self, pid: int | None = None) -> bool:
+        """Stop a running iperf traffic sender.
+
+        Parameters
+        ----------
+        pid:
+            Process ID to stop.  If *None*, stop the most recently started sender.
+        """
+        ...
+
+    def get_iperf_logs(self, log_file: str) -> str:
+        """Return the iperf log contents from *log_file*."""
+        ...

testprotocols/iperf_generator.py

@@ -0,0 +1,42 @@
+"""Traffic / IperfGenerator template.
+
+Defines the abstract contract for a higher-level iperf traffic generator
+that manages flows and returns structured results.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.traffic import TrafficResult, TrafficSpec
+
+
+@runtime_checkable
+class IperfGenerator(Protocol):
+    """Abstract contract for iperf-based traffic flow management."""
+
+    @property
+    def server_ip(self) -> str:
+        """IP address of the iperf server."""
+        ...
+
+    @property
+    def active_flows(self) -> list[str]:
+        """List of currently active traffic flow IDs."""
+        ...
+
+    def start_traffic(self, spec: TrafficSpec) -> str:
+        """Start a traffic flow defined by *spec* and return its flow ID."""
+        ...
+
+    def stop_traffic(self, flow_id: str) -> TrafficResult:
+        """Stop the traffic flow identified by *flow_id* and return its result."""
+        ...
+
+    def stop_all_traffic(self) -> dict[str, TrafficResult]:
+        """Stop all active traffic flows and return a mapping of flow_id to result."""
+        ...
+
+    def run_traffic(self, spec: TrafficSpec) -> TrafficResult:
+        """Run a traffic flow defined by *spec* to completion and return the result."""
+        ...

testprotocols/iperf_server.py

@@ -0,0 +1,41 @@
+"""Traffic / IperfServer template.
+
+Defines the abstract contract for iperf server operations including
+receiving traffic and collecting logs.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class IperfServer(Protocol):
+    """Abstract contract for iperf server (traffic receiver) operations."""
+
+    def start_traffic_receiver(
+        self,
+        traffic_port: int,
+        bind_to_ip: str | None = None,
+        ip_version: int | None = None,
+        udp_only: bool | None = None,
+    ) -> tuple[int, str]:
+        """Start an iperf traffic receiver on *traffic_port*.
+
+        Returns a tuple of (pid, log_file_path).
+        """
+        ...
+
+    def stop_traffic(self, pid: int | None = None) -> bool:
+        """Stop a running iperf traffic receiver.
+
+        Parameters
+        ----------
+        pid:
+            Process ID to stop.  If *None*, stop the most recently started receiver.
+        """
+        ...
+
+    def get_iperf_logs(self, log_file: str) -> str:
+        """Return the iperf log contents from *log_file*."""
+        ...

testprotocols/l3_firewall.py

@@ -0,0 +1,74 @@
+"""L3 firewall template — managed SD-WAN appliance edition.
+
+Defines the abstract contract for a managed SD-WAN appliance's L3 firewall:
+**ordered allow/deny policy lists** for outbound (LAN→WAN) and inbound (WAN→LAN)
+traffic. A managed appliance exposes each direction as a single ordered list
+that is read and replaced as a whole — distinct from
+``packet_filter.PacketFilter`` (netfilter INPUT/OUTPUT/FORWARD chains, add/remove
+a rule by name), which models a Linux host's stateless filter.
+
+In scope: read and replace the outbound, inbound, and site-to-site VPN
+ordered rule lists.
+
+Out of scope: L7 / application-aware rules (see ``l7_firewall``), URL / category
+filtering (see ``content_filtering``), NAT and port-forwarding (see
+``appliance_nat``), and netfilter-chain filtering (see ``packet_filter``).
+
+Rules are transport-agnostic ``L3Rule`` records; the driver translates them
+into its product's API. Value vocabularies (``action``, ``protocol``) are the
+normalized sets in ``models.sdwan_appliance``.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.sdwan_appliance import L3Rule
+
+
+@runtime_checkable
+class L3Firewall(Protocol):
+    """Abstract contract for an appliance's ordered L3 firewall policy."""
+
+    def set_outbound_rules(self, rules: list[L3Rule]) -> None:
+        """Replace the ordered outbound (LAN→WAN) policy with *rules*.
+
+        The list is the complete policy in evaluation order; the driver
+        replaces the appliance's outbound ruleset wholesale.
+        """
+        ...
+
+    def get_outbound_rules(self) -> list[L3Rule]:
+        """Return the outbound (LAN→WAN) rules in evaluation order."""
+        ...
+
+    def set_inbound_rules(self, rules: list[L3Rule]) -> None:
+        """Replace the ordered inbound (WAN→LAN) policy with *rules*.
+
+        The list is the complete policy in evaluation order; the driver
+        replaces the appliance's inbound ruleset wholesale.
+
+        Conformance note: not every appliance family exposes a generic
+        inbound rule list — some offer only an implicit stateful deny plus
+        NAT-scoped inbound allowances. Such drivers raise
+        unsupported-capability here rather than approximating.
+        """
+        ...
+
+    def get_inbound_rules(self) -> list[L3Rule]:
+        """Return the inbound (WAN→LAN) rules in evaluation order."""
+        ...
+
+    def set_vpn_rules(self, rules: list[L3Rule]) -> None:
+        """Replace the ordered site-to-site VPN policy with *rules*.
+
+        The list is the complete policy, in evaluation order, governing
+        traffic traversing the site-to-site VPN overlay. On some products
+        this rule set is scoped wider than a single device (e.g.
+        fleet-wide); that is a driver/testbed concern, not a contract one.
+        """
+        ...
+
+    def get_vpn_rules(self) -> list[L3Rule]:
+        """Return the site-to-site VPN rules in evaluation order."""
+        ...

testprotocols/l7_firewall.py

@@ -0,0 +1,32 @@
+"""L7 firewall template — application-aware allow/deny for a managed appliance.
+
+Defines the abstract contract for an SD-WAN appliance's L7 (application-aware)
+firewall: an ordered list of rules that match by application, application
+category, host, port, or IP range and allow/deny accordingly. Like
+``l3_firewall.L3Firewall`` the policy is read and replaced as a whole list.
+
+In scope: read and replace the ordered L7 rule list.
+
+Out of scope: L3 5-tuple filtering (see ``l3_firewall``), URL / content-category
+blocking (see ``content_filtering``), and traffic shaping (see
+``traffic_shaping``).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.sdwan_appliance import L7Rule
+
+
+@runtime_checkable
+class L7Firewall(Protocol):
+    """Abstract contract for an appliance's ordered L7 firewall policy."""
+
+    def set_rules(self, rules: list[L7Rule]) -> None:
+        """Replace the ordered L7 policy with *rules* (complete, in order)."""
+        ...
+
+    def get_rules(self) -> list[L7Rule]:
+        """Return the L7 rules in evaluation order."""
+        ...

testprotocols/link_aggregation.py

@@ -0,0 +1,24 @@
+"""Link-aggregation (LAG) configuration by member ports + mode."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch import LinkAggregationGroup
+
+
+@runtime_checkable
+class LinkAggregation(Protocol):
+    """Abstract contract for LAG configuration."""
+
+    def list_groups(self) -> list[LinkAggregationGroup]:
+        """Return every aggregation group."""
+        ...
+
+    def set_group(self, group: LinkAggregationGroup) -> None:
+        """Create or replace the group ``group.name``."""
+        ...
+
+    def remove_group(self, name: str) -> None:
+        """Remove the group *name*."""
+        ...

testprotocols/mac_table.py

@@ -0,0 +1,20 @@
+"""Read-only forwarding-database (FDB / MAC address-table) read."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.l2_common import MacTableEntry
+
+
+@runtime_checkable
+class MacTable(Protocol):
+    """Abstract contract for the FDB read.
+
+    A product with no FDB API raises unsupported-capability. A raw-dump white-box
+    extension is a LEVELS.md candidate (``MacTableWhiteBox``).
+    """
+
+    def get_mac_table(self, vlan: int | None = None) -> list[MacTableEntry]:
+        """Return FDB entries, optionally filtered to one *vlan*."""
+        ...