testprotocols 0.1.0__py3-none-any.whl

testprotocols/pdu_controller.py

@@ -0,0 +1,26 @@
+"""PDU / Controller template.
+
+Defines the abstract contract for Power Distribution Unit controller
+operations including power cycling.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PduController(Protocol):
+    """Abstract contract for PDU controller operations."""
+
+    def power_on(self) -> bool:
+        """Power on the outlet and return True on success."""
+        ...
+
+    def power_off(self) -> bool:
+        """Power off the outlet and return True on success."""
+        ...
+
+    def power_cycle(self) -> bool:
+        """Power cycle the outlet and return True on success."""
+        ...

testprotocols/port_poe.py

@@ -0,0 +1,25 @@
+"""Per-port PoE configuration and status read."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch import PoePortStatus, PoePriority
+
+
+@runtime_checkable
+class PortPoe(Protocol):
+    """Abstract contract for per-port PoE."""
+
+    def set_enabled(self, port: str, enabled: bool) -> None:
+        """Enable or disable PoE on *port*."""
+        ...
+
+    def set_priority(self, port: str, priority: PoePriority) -> None:
+        """Set PoE priority on *port*. Products without a priority knob raise
+        unsupported-capability."""
+        ...
+
+    def get_status(self, port: str) -> PoePortStatus:
+        """Return live PoE status/draw for *port*."""
+        ...

testprotocols/port_security.py

@@ -0,0 +1,25 @@
+"""Per-port access policy — 802.1X / MAB / MAC limit / sticky.
+
+The access policy references RADIUS servers *by name* from the composed
+``radius`` (``RadiusClient``) registry; address/port/secret resolution is the
+driver's concern.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch import AccessPolicy
+
+
+@runtime_checkable
+class PortSecurity(Protocol):
+    """Abstract contract for per-port access policy."""
+
+    def set_access_policy(self, policy: AccessPolicy) -> None:
+        """Apply the access policy for ``policy.port``."""
+        ...
+
+    def get_access_policy(self, port: str) -> AccessPolicy:
+        """Return the access policy for *port*."""
+        ...

testprotocols/port_status.py

@@ -0,0 +1,23 @@
+"""Read-only per-port link state, speed/duplex, and counters."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch import PortStatusEntry
+
+
+@runtime_checkable
+class PortStatus(Protocol):
+    """Abstract contract for per-port status read.
+
+    Replaces the host-shaped ``ip_interface`` read for this archetype.
+    """
+
+    def list_port_status(self) -> list[PortStatusEntry]:
+        """Return status for every port."""
+        ...
+
+    def get_port_status(self, name: str) -> PortStatusEntry:
+        """Return status for port *name*. Raises KeyError if absent."""
+        ...

testprotocols/qoe_browser.py

@@ -0,0 +1,62 @@
+"""Traffic / QoeBrowser template.
+
+Defines the abstract contract for browser-based Quality of Experience (QoE)
+measurement operations.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.qoe import MeasurementSpec, QoEResult
+
+
+@runtime_checkable
+class QoeBrowser(Protocol):
+    """Abstract contract for browser-based QoE measurement."""
+
+    def measure(self, url: str, spec: MeasurementSpec) -> QoEResult:
+        """Run a generic QoE measurement against *url* using *spec*."""
+        ...
+
+    def measure_productivity(
+        self,
+        url: str,
+        *,
+        spec: MeasurementSpec | None = None,
+        scenario: str = "page_load",
+        wait_until: str = "networkidle",
+        timeout_ms: int = 30000,
+    ) -> QoEResult:
+        """Measure productivity-app QoE for *url* (e.g., page-load time)."""
+        ...
+
+    def measure_streaming(
+        self,
+        stream_url: str,
+        *,
+        spec: MeasurementSpec | None = None,
+        duration_s: int = 30,
+    ) -> QoEResult:
+        """Measure streaming QoE for *stream_url* over *duration_s* seconds."""
+        ...
+
+    def measure_conferencing(
+        self,
+        session_url: str,
+        *,
+        spec: MeasurementSpec | None = None,
+        duration_s: int = 60,
+    ) -> QoEResult:
+        """Measure conferencing QoE for *session_url* over *duration_s* seconds."""
+        ...
+
+    def attempt_outbound_connection(
+        self,
+        host: str,
+        port: int,
+        *,
+        timeout_s: float = 5.0,
+    ) -> bool:
+        """Attempt a TCP connection to *host*:*port* and return True if successful."""
+        ...

testprotocols/radius_client.py

@@ -0,0 +1,78 @@
+"""RADIUS / RadiusClient template.
+
+Defines the abstract contract for a device that authenticates upstream
+to one or more RADIUS servers (e.g. a WiFi AP doing 802.1X, a wired
+switch doing port-based authentication, a VPN concentrator).
+
+The device maintains a registry of known servers indexed by a logical
+*name*. Consumers (e.g. WifiBss) reference servers by name only — the
+underlying address/port/secret resolution is the driver's responsibility.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.radius import RadiusServerConfig
+
+
+@runtime_checkable
+class RadiusClient(Protocol):
+    """Abstract contract for a RADIUS-authenticating device."""
+
+    def add_server(
+        self,
+        name: str,
+        address: str,
+        secret: str,
+        port: int = 1812,
+        acct_port: int | None = None,
+    ) -> None:
+        """Register a RADIUS server under *name*.
+
+        *port* is the auth port (default 1812). *acct_port* (typically 1813)
+        may be None to disable accounting on this server. Raises ValueError
+        if *name* is already registered.
+        """
+        ...
+
+    def update_server(
+        self,
+        name: str,
+        *,
+        address: str | None = None,
+        secret: str | None = None,
+        port: int | None = None,
+        acct_port: int | None = None,
+    ) -> None:
+        """Update one or more fields of an already-registered server.
+
+        Only fields passed (non-None) are changed. Raises KeyError if *name*
+        is not registered.
+        """
+        ...
+
+    def remove_server(self, name: str) -> None:
+        """Unregister the RADIUS server identified by *name*. Raises KeyError if absent."""
+        ...
+
+    def list_servers(self) -> list[RadiusServerConfig]:
+        """Return all registered RADIUS servers (without secrets)."""
+        ...
+
+    def get_server(self, name: str) -> RadiusServerConfig:
+        """Return the registered RADIUS server identified by *name* (without secret).
+
+        Raises KeyError if *name* is not registered.
+        """
+        ...
+
+    def test_server_reachable(self, name: str, timeout: float = 5.0) -> bool:
+        """Probe the registered server: return True if it responds to an Access-Request
+        within *timeout* seconds.
+
+        Drivers typically send an Access-Request with a sentinel user; the
+        server's response (Access-Accept, Access-Reject, or any RADIUS reply)
+        counts as reachable. No reply within timeout returns False.
+        """
+        ...

testprotocols/radius_server.py

@@ -0,0 +1,130 @@
+"""RADIUS / RadiusServer template.
+
+Defines the abstract contract for a controllable RADIUS server used as
+the AAA backend in a testbed (e.g. FreeRADIUS in a container, exercised
+by WPA-Enterprise / 802.1X / VPN scenarios).
+
+Tests use this template to provision EAP-capable users, inspect active
+sessions, drive RFC 5176 dynamic-authorization (CoA / Disconnect) flows,
+and read accounting records produced by NAS devices (APs, switches).
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.radius import (
+    RadiusAccountingRecord,
+    RadiusSession,
+    RadiusUser,
+)
+
+
+@runtime_checkable
+class RadiusServer(Protocol):
+    """Abstract contract for a controllable RADIUS server."""
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        """Start the RADIUS daemon."""
+        ...
+
+    def stop(self) -> None:
+        """Stop the RADIUS daemon."""
+        ...
+
+    def get_status(self) -> str:
+        """Return the daemon status. Typical values: ``"running"``, ``"stopped"``, ``"error"``."""
+        ...
+
+    # ------------------------------------------------------------------
+    # User provisioning
+    # ------------------------------------------------------------------
+
+    def add_user(
+        self,
+        username: str,
+        password: str,
+        eap_methods: list[str] | None = None,
+        attributes: dict[str, str] | None = None,
+    ) -> None:
+        """Provision a user authorised to authenticate.
+
+        *eap_methods* lists the EAP methods this user may use (e.g.
+        ``["PEAP-MSCHAPv2", "TTLS-PAP"]``); None means the server's default
+        method set. *attributes* is a dict of RADIUS attributes returned in
+        the Access-Accept reply (e.g. ``{"Tunnel-Private-Group-Id": "42"}``
+        for VLAN assignment, ``{"Session-Timeout": "3600"}``).
+
+        Raises ValueError if *username* is already provisioned.
+        """
+        ...
+
+    def remove_user(self, username: str) -> None:
+        """Remove the provisioned user. Raises KeyError if absent."""
+        ...
+
+    def list_users(self) -> list[RadiusUser]:
+        """Return all provisioned users (without passwords)."""
+        ...
+
+    def get_user(self, username: str) -> RadiusUser:
+        """Return the provisioned user (without password). Raises KeyError if absent."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Active sessions
+    # ------------------------------------------------------------------
+
+    def get_active_sessions(self) -> list[RadiusSession]:
+        """Return currently authenticated NAS sessions tracked by the server."""
+        ...
+
+    # ------------------------------------------------------------------
+    # Dynamic authorization (RFC 5176)
+    # ------------------------------------------------------------------
+
+    def send_coa(self, session_id: str, attributes: dict[str, str]) -> bool:
+        """Send a Change-of-Authorization request to the NAS for *session_id*.
+
+        *attributes* are the RADIUS attributes to apply (e.g. a new VLAN
+        assignment, a new Filter-Id). Returns True on CoA-ACK, False on
+        CoA-NAK or no response within the driver's timeout.
+        """
+        ...
+
+    def send_disconnect(self, session_id: str) -> bool:
+        """Send a Disconnect-Message to the NAS for *session_id*.
+
+        Returns True on Disconnect-ACK, False on Disconnect-NAK or no
+        response within the driver's timeout.
+        """
+        ...
+
+    # ------------------------------------------------------------------
+    # Accounting
+    # ------------------------------------------------------------------
+
+    def get_accounting_records(
+        self,
+        username: str | None = None,
+        nas_address: str | None = None,
+        since: float | None = None,
+    ) -> list[RadiusAccountingRecord]:
+        """Return accounting records, optionally filtered.
+
+        *since* is a Unix timestamp; only records at or after that time are
+        returned. Filters compose (AND).
+        """
+        ...
+
+    def clear_accounting(self) -> None:
+        """Discard all stored accounting records.
+
+        Tests typically call this at scenario start so subsequent
+        ``get_accounting_records()`` returns only what the scenario produced.
+        """
+        ...

testprotocols/routed_interfaces.py

@@ -0,0 +1,29 @@
+"""Routed-interface (SVI / routed port / loopback) configuration."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.switch_routing import RoutedInterface
+
+
+@runtime_checkable
+class RoutedInterfaces(Protocol):
+    """Abstract contract for L3 interface configuration.
+
+    Scope is the default VRF; multi-VRF is deferred (GAPS.md). A product whose
+    SVIs are gateway-anchored or standalone-only raises unsupported-capability on
+    the unsupported facets.
+    """
+
+    def list_interfaces(self) -> list[RoutedInterface]:
+        """Return every routed interface."""
+        ...
+
+    def get_interface(self, name: str) -> RoutedInterface:
+        """Return the routed interface *name*. Raises KeyError if absent."""
+        ...
+
+    def set_interface(self, interface: RoutedInterface) -> None:
+        """Create or replace the routed interface ``interface.name``."""
+        ...

testprotocols/router.py

@@ -0,0 +1,53 @@
+"""Router / WAN edge template.
+
+Defines the abstract contract for **reading** a WAN edge router's state:
+interface status, path metrics, link health, telemetry, and the routing
+table. The surface is read-only so it holds for every WAN-edge archetype —
+including API-managed appliances, whose management planes expose reads but
+no link administration. Forced link-down lives on ``wan_link_admin``
+(host-substrate only; see SPLITS.md).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from testprotocols.models.wan_edge import (
+    LinkHealthReport,
+    LinkStatus,
+    PathMetrics,
+    RouteEntry,
+)
+
+
+@runtime_checkable
+class Router(Protocol):
+    """Abstract contract for reading WAN edge router state."""
+
+    def get_active_wan_interface(self, flow_dst: str | None = None) -> str | None:
+        """Return the name of the active WAN interface, or ``None`` if no uplink
+        is currently active (for a given ``flow_dst``, if there is no active path
+        to it). "No active uplink" is an expected operational state — e.g. while
+        a failover test has every uplink impaired — not an error; use
+        ``get_wan_interface_status`` for per-uplink detail."""
+        ...
+
+    def get_wan_interface_status(self) -> dict[str, LinkStatus]:
+        """Return a mapping of WAN interface names to their current link status."""
+        ...
+
+    def get_wan_path_metrics(self) -> dict[str, PathMetrics]:
+        """Return a mapping of WAN interface names to measured path metrics."""
+        ...
+
+    def get_link_health(self, wan_label: str) -> LinkHealthReport:
+        """Return a comprehensive health report for the named WAN link."""
+        ...
+
+    def get_telemetry(self) -> dict[str, Any]:
+        """Return a dict of current device telemetry data."""
+        ...
+
+    def get_routing_table(self) -> list[RouteEntry]:
+        """Return the current routing table as a list of RouteEntry records."""
+        ...

testprotocols/routing_read.py

@@ -0,0 +1,22 @@
+"""Read-only routing-table (RIB) read for a switch — RouteEntry, shared with Router."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from testprotocols.models.wan_edge import RouteEntry
+
+
+@runtime_checkable
+class RoutingRead(Protocol):
+    """Abstract contract for the switch routing-table read.
+
+    The config-view read (connected/static/configured routes) is universal; the
+    dynamic-learned RIB facet is best-effort — a product that is config-only on
+    routing state raises unsupported-capability for the learned routes.
+    """
+
+    def get_routing_table(self) -> list[RouteEntry]:
+        """Return the routing table as RouteEntry records (origin-classified
+        where the product exposes it)."""
+        ...

testprotocols/sdwan_policy_manager.py

@@ -0,0 +1,64 @@
+"""SD-WAN policy manager template.
+
+Defines the abstract contract for SD-WAN path/policy management: generic
+policy application, SLA policies, and application-flow visibility.
+
+Firewall-rule administration is **not** here — it moved to the dedicated
+``l3_firewall`` / ``l7_firewall`` capabilities (coherent-domain split; see
+SPLITS.md). Typed path steering (``set_uplink_selection`` /
+``get_uplink_selection`` over ordered ``UplinkSelectionRule``s; performance
+classes reuse ``SLAPolicy`` by name) landed 2026-06-12; ``apply_policy``
+remains the generic escape hatch for vendor-shaped policies beyond that
+surface. Application-match steering grows on evidence.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from testprotocols.models.sdwan_appliance import UplinkSelectionRule
+from testprotocols.models.wan_edge import AppFlow, SLAPolicy
+
+
+@runtime_checkable
+class SdwanPolicyManager(Protocol):
+    """Abstract contract for SD-WAN policy management operations."""
+
+    def apply_policy(self, policy: dict[str, Any]) -> None:
+        """Apply a generic SD-WAN policy specified as a dict."""
+        ...
+
+    def remove_policy(self, name: str) -> None:
+        """Remove the SD-WAN policy with the given name."""
+        ...
+
+    def configure_sla_policy(self, policy: SLAPolicy) -> None:
+        """Configure an SLA policy on the SD-WAN device."""
+        ...
+
+    def remove_sla_policy(self, name: str) -> None:
+        """Remove the SLA policy with the given name."""
+        ...
+
+    def get_application_flows(
+        self,
+        since_s: int = 60,
+        app_filter: str | None = None,
+    ) -> list[AppFlow]:
+        """Return application flows observed in the last *since_s* seconds."""
+        ...
+
+    def set_uplink_selection(self, rules: list[UplinkSelectionRule]) -> None:
+        """Replace the ordered uplink-selection rule list with *rules*.
+
+        The list is the complete steering policy in evaluation order. A rule
+        referencing a ``performance_class`` requires the named ``SLAPolicy``
+        to be configured (``configure_sla_policy``); products that cannot
+        express arbitrary performance thresholds raise unsupported-capability
+        for such rules rather than approximating.
+        """
+        ...
+
+    def get_uplink_selection(self) -> list[UplinkSelectionRule]:
+        """Return the uplink-selection rules in evaluation order."""
+        ...