testprotocols 0.1.0__py3-none-any.whl

testprotocols/models/switch.py

@@ -0,0 +1,297 @@
+"""Data models for the vendor-neutral L2 (access) switch capabilities.
+
+Field value-vocabularies are normalized ``StrEnum`` types owned here; records are
+plain ``@dataclass``es composing them. Shared STP/FDB vocab lives in
+``models/l2_common.py``; rule action/protocol enums are reused from
+``models/sdwan_appliance.py``. Vendor neutrality is part of the contract — no
+product name, vendor id, or ``native`` bucket appears in this module.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from testprotocols.models.l2_common import StpGuard
+from testprotocols.models.sdwan_appliance import RuleAction, RuleProtocol
+
+
+class PortMode(StrEnum):
+    """Switchport framing mode.
+
+    ``ACCESS`` and ``TRUNK`` are universal — all managed-switch drivers must support them.
+    ``ROUTED`` models a routed / "no-switchport" physical port and is only meaningful on
+    an L3 switch; an L2-only driver raises unsupported-capability if asked to set it.
+    """
+
+    ACCESS = "access"
+    TRUNK = "trunk"
+    ROUTED = "routed"  # routed / no-switchport port; L3Switch only
+
+
+class PortAdminState(StrEnum):
+    """Administrative enable/disable state of a port."""
+
+    ENABLED = "enabled"
+    DISABLED = "disabled"
+
+
+class LinkState(StrEnum):
+    """Observed per-port link state."""
+
+    UP = "up"
+    DOWN = "down"
+    DISABLED = "disabled"
+
+
+class Duplex(StrEnum):
+    """Port duplex mode (full, half, or auto-negotiated)."""
+
+    FULL = "full"
+    HALF = "half"
+    AUTO = "auto"
+
+
+class AggregationMode(StrEnum):
+    """Link-aggregation negotiation mode (LACP or static)."""
+
+    LACP = "lacp"
+    STATIC = "static"
+
+
+class PoeStatus(StrEnum):
+    """Observed Power-over-Ethernet delivery state for a port."""
+
+    DELIVERING = "delivering"
+    DISABLED = "disabled"
+    FAULT = "fault"
+    SEARCHING = "searching"
+    OFF = "off"
+
+
+class PoePriority(StrEnum):
+    """PoE port priority used when total power budget is constrained."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    LOW = "low"
+
+
+class AccessPolicyType(StrEnum):
+    """Port-level admission-control policy (open, MAC-based, or 802.1X)."""
+
+    OPEN = "open"
+    MAC_ALLOW_LIST = "mac_allow_list"
+    STICKY_MAC = "sticky_mac"
+    DOT1X = "dot1x"
+
+
+class AclDirection(StrEnum):
+    """Direction in which a port ACL is applied."""
+
+    INGRESS = "ingress"
+    EGRESS = "egress"
+
+
+class DiscoveryProtocol(StrEnum):
+    """Link-layer discovery. Only the open IEEE 802.1AB standard is a member;
+    a vendor's proprietary discovery normalizes onto the same LLDP-shaped read."""
+
+    LLDP = "lldp"
+
+
+class StormControlType(StrEnum):
+    """Traffic category that storm-control rate limiting is applied to."""
+
+    BROADCAST = "broadcast"
+    MULTICAST = "multicast"
+    UNKNOWN_UNICAST = "unknown_unicast"
+
+
+class QosTrustMode(StrEnum):
+    """Which QoS marking field the port trusts for inbound classification."""
+
+    DSCP = "dscp"
+    COS = "cos"
+    UNTRUSTED = "untrusted"
+
+
+class FhsTrustState(StrEnum):
+    """First-hop-security trust level assigned to a port."""
+
+    TRUSTED = "trusted"
+    UNTRUSTED = "untrusted"
+
+
+class FhsScope(StrEnum):
+    """Scope at which a first-hop-security feature (e.g. DHCP snooping) operates."""
+
+    GLOBAL = "global"
+    PER_VLAN = "per_vlan"
+
+
+class BindingSource(StrEnum):
+    """How a first-hop-security binding-table entry was learned."""
+
+    DYNAMIC_SNOOPING = "dynamic_snooping"
+    STATIC = "static"
+
+
+@dataclass
+class SwitchPort:
+    """A switchport — the first-class object of a switch."""
+
+    name: str
+    mode: PortMode
+    enabled: bool = True
+    native_vlan: int | None = None
+    allowed_vlans: list[int] = field(default_factory=list)
+    description: str = ""
+    voice_vlan: int | None = None
+    isolated: bool = False
+
+
+@dataclass
+class VlanDef:
+    """A VLAN id/name registry entry."""
+
+    vlan_id: int
+    name: str = ""
+
+
+@dataclass
+class StpPortConfig:
+    """Per-port spanning-tree configuration."""
+
+    port: str
+    guard: StpGuard = StpGuard.NONE
+    edge: bool = False
+    path_cost: int | None = None
+    priority: int | None = None
+
+
+@dataclass
+class LinkAggregationGroup:
+    """A link-aggregation group (LAG) by member ports + mode."""
+
+    name: str
+    member_ports: list[str]
+    mode: AggregationMode = AggregationMode.LACP
+
+
+@dataclass
+class PoePortStatus:
+    """Observed PoE state for a port."""
+
+    port: str
+    status: PoeStatus
+    draw_watts: float | None = None
+    priority: PoePriority | None = None
+
+
+@dataclass
+class AccessPolicy:
+    """Per-port access policy (802.1X / MAB / MAC limits)."""
+
+    port: str
+    policy_type: AccessPolicyType
+    allowed_macs: list[str] = field(default_factory=list)
+    max_macs: int | None = None
+    sticky: bool = False
+
+
+@dataclass
+class StormControlConfig:
+    """Per-port storm-control thresholds, keyed by traffic type.
+
+    Threshold units are driver-normalized (percent of line rate or pps); the
+    plugin maps the product's representation.
+    """
+
+    port: str
+    thresholds: dict[StormControlType, float] = field(default_factory=dict)
+
+
+@dataclass
+class SwitchAclRule:
+    """One ordered switch ACL rule — unified L2 + L3/L4 match.
+
+    Reuses ``RuleAction`` / ``RuleProtocol``; the L2 fields (``src_mac`` /
+    ``dst_mac`` / ``vlan``) and the IP 5-tuple are all optional, so the same
+    record serves both the L2 archetype and the L3 superset.
+    """
+
+    action: RuleAction
+    protocol: RuleProtocol = RuleProtocol.ANY
+    src_mac: str | None = None
+    dst_mac: str | None = None
+    vlan: int | None = None
+    src_cidr: str = "any"
+    dst_cidr: str = "any"
+    src_port: str = "any"
+    dst_port: str = "any"
+    comment: str = ""
+
+
+@dataclass
+class LldpNeighbor:
+    """A discovered link-layer neighbour (read-only)."""
+
+    local_port: str
+    remote_system: str
+    remote_port: str
+    protocol: DiscoveryProtocol = DiscoveryProtocol.LLDP
+    mgmt_address: str | None = None
+
+
+@dataclass
+class PortStatusEntry:
+    """Observed per-port link state and counters (read-only)."""
+
+    name: str
+    link_state: LinkState
+    speed_mbps: int | None = None
+    duplex: Duplex = Duplex.AUTO
+    rx_errors: int = 0
+    tx_errors: int = 0
+    rx_discards: int = 0
+    tx_discards: int = 0
+
+
+@dataclass
+class QosRule:
+    """A QoS classification rule (match -> DSCP/CoS marking).
+
+    ``match`` holds a vendor-neutral traffic-classifier expression (e.g. by
+    VLAN, protocol, or port) that the driver maps to its product's QoS
+    classifier; ``dscp`` and ``cos`` are the resulting mark values.
+    """
+
+    name: str
+    match: str
+    dscp: int | None = None
+    cos: int | None = None
+
+
+@dataclass
+class FhsBinding:
+    """A first-hop-security binding-table entry (DHCP snooping / DAI).
+
+    Note: a driver returning static bindings MUST set ``source=BindingSource.STATIC``
+    explicitly — static entries are immune to ageing and differ operationally from
+    snooped ones, so do not rely on the default for static tables.
+    """
+
+    mac: str
+    ip: str
+    vlan: int
+    port: str
+    source: BindingSource = BindingSource.DYNAMIC_SNOOPING
+
+
+@dataclass
+class NtpServer:
+    """An NTP server destination."""
+
+    host: str
+    prefer: bool = False

testprotocols/models/switch_routing.py

@@ -0,0 +1,122 @@
+"""Data models for the vendor-neutral L3 (distribution) switch capabilities.
+
+Composed by ``devices.switch.L3Switch`` (a strict superset of ``L2Switch``).
+Reuses ``DhcpMode`` / ``DhcpOption`` / ``DhcpReservation`` from
+``models/sdwan_appliance.py`` and ``RouteEntry`` / ``RouteOrigin`` from
+``models/wan_edge.py``. Scope is the **default VRF** — multi-VRF is deferred
+(GAPS.md). Vendor neutrality is part of the contract: no product name, vendor id,
+or ``native`` bucket appears here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from testprotocols.models.sdwan_appliance import (
+    DhcpMode,
+    DhcpOption,
+    DhcpReservation,
+)
+from testprotocols.models.wan_edge import RouteOrigin  # re-export
+
+__all__ = [
+    "DhcpMode",
+    "InterfaceDhcpConfig",
+    "InterfaceMode",
+    "OspfConfig",
+    "OspfInterfaceSettings",
+    "OspfVersion",
+    "RedundancyGroup",
+    "RedundancyRole",
+    "RouteOrigin",
+    "RoutedInterface",
+]
+
+
+class InterfaceMode(StrEnum):
+    """L3 interface kind."""
+
+    SVI = "svi"
+    ROUTED = "routed"
+    LOOPBACK = "loopback"
+
+
+class OspfVersion(StrEnum):
+    """Seeded standardized OSPF versions. ``OspfNetworkType`` / ``OspfAreaType``
+    grow on evidence (open taxonomy)."""
+
+    V2 = "v2"
+    V3 = "v3"
+
+
+class RedundancyRole(StrEnum):
+    """First-hop-redundancy role. ``ACTIVE_ACTIVE`` is a recorded candidate
+    (all-active gateways) — added on a driving test, not seeded."""
+
+    PRIMARY = "primary"
+    SPARE = "spare"
+
+
+@dataclass
+class RoutedInterface:
+    """An L3 interface — SVI, routed port, or loopback.
+
+    ``ip_address`` is the interface IP (the SVI IP for an SVI). Reuses the
+    appliance DHCP vocabulary via ``InterfaceDhcpConfig``; this record carries only the
+    L3 addressing identity.
+    """
+
+    name: str
+    mode: InterfaceMode
+    ip_address: str
+    subnet: str
+    vlan_id: int | None = None
+
+
+@dataclass
+class InterfaceDhcpConfig:
+    """Per-interface DHCP server/relay config (reuses appliance DHCP sub-models)."""
+
+    interface: str
+    mode: DhcpMode = DhcpMode.DISABLED
+    lease_seconds: int = 86400
+    dns_servers: list[str] = field(default_factory=list)
+    options: list[DhcpOption] = field(default_factory=list)
+    reservations: list[DhcpReservation] = field(default_factory=list)
+    reserved_ranges: list[tuple[str, str]] = field(default_factory=list)
+    relay_targets: list[str] = field(default_factory=list)
+
+
+@dataclass
+class OspfInterfaceSettings:
+    """Per-interface OSPF participation."""
+
+    interface: str
+    area: str
+    cost: int | None = None
+    passive: bool = False
+
+
+@dataclass
+class OspfConfig:
+    """Whole-config-replace OSPF configuration."""
+
+    enabled: bool
+    router_id: str
+    version: OspfVersion = OspfVersion.V2
+    areas: list[str] = field(default_factory=list)
+    interfaces: list[OspfInterfaceSettings] = field(default_factory=list)
+
+
+@dataclass
+class RedundancyGroup:
+    """A first-hop-redundancy group — virtual IP + role on an interface.
+
+    Behaviour is asserted via virtual-IP + role, not raw VRRP/HSRP internals.
+    """
+
+    group_id: int
+    virtual_ip: str
+    role: RedundancyRole
+    interface: str

testprotocols/models/tr069.py

@@ -0,0 +1,35 @@
+"""TR-069 ACS data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass
+class CpeConnectionStatus:
+    """ACS-side view of a CPE record.
+
+    Reflects what the ACS believes about the CPE — not a live probe.
+    All fields remain populated when the CPE is offline (from the
+    last successful Inform). ``last_inform_time`` is ``None`` only
+    when the ACS has never received an Inform from this CPE.
+
+    ``last_boot_time`` is set to the timestamp of the most recent
+    Boot Inform (CWMP informEvent "1 BOOT") the ACS received from
+    this CPE. Use it to confirm a reboot has actually completed —
+    comparing successive ``last_boot_time`` values against a baseline
+    is the most reliable post-reboot re-registration signal because
+    the ACS keeps the previous CPE record indefinitely (a presence
+    check via list_cpes() would trivially pass against the stale
+    pre-reboot record).
+    """
+
+    online: bool
+    last_inform_time: datetime | None = None
+    last_boot_time: datetime | None = None
+    cached_manufacturer: str | None = None
+    cached_model: str | None = None
+    cached_serial_number: str | None = None
+    cached_hardware_version: str | None = None
+    cached_software_version: str | None = None

testprotocols/models/traffic.py

@@ -0,0 +1,29 @@
+"""Traffic generation specification and result data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class TrafficSpec:
+    """Holds parameters for a traffic generation run (destination, bandwidth, protocol, etc.)."""
+
+    destination: str
+    bandwidth_mbps: float
+    protocol: str = "udp"
+    dscp: int = 0
+    duration_s: int = 30
+    parallel_streams: int = 1
+    port: int | None = None
+
+
+@dataclass
+class TrafficResult:
+    """Holds measured outcomes from a traffic generation run."""
+
+    sent_mbps: float = 0.0
+    received_mbps: float = 0.0
+    loss_percent: float = 0.0
+    jitter_ms: float | None = None
+    dscp_marking: int = 0

testprotocols/models/wan_edge.py

@@ -0,0 +1,116 @@
+"""WAN edge device data models for links, routes, SLA, flows, VPN, and shaping."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any
+
+
+@dataclass
+class PathMetrics:
+    """Holds measured path quality metrics for a WAN link."""
+
+    latency_ms: float
+    jitter_ms: float
+    loss_percent: float
+    link_name: str
+    mos: float | None = None
+
+
+@dataclass
+class LinkStatus:
+    """Holds the current operational state and IP address of a WAN link."""
+
+    name: str
+    state: str  # "up" | "down" | "degraded"
+    ip_address: str
+
+
+class RouteOrigin(StrEnum):
+    """How a route was learned. Seeded with the standardized origins; ``ISIS`` /
+    ``RIP`` grow on evidence (see GAPS.md). ``UNKNOWN`` is the back-compat default
+    for callers that do not classify the route."""
+
+    UNKNOWN = "unknown"
+    STATIC = "static"
+    CONNECTED = "connected"
+    OSPF = "ospf"
+    BGP = "bgp"
+    LOCAL = "local"
+
+
+@dataclass
+class RouteEntry:
+    """A single routing-table entry: destination, gateway, interface, metric, origin.
+
+    ``origin`` is default-backed so the WAN-edge ``Router.get_routing_table`` and
+    ``Bgp.get_learned_routes`` producers stay source-compatible; the switch
+    ``RoutingRead`` populates it. See SPLITS.md.
+    """
+
+    destination: str
+    gateway: str
+    interface: str
+    metric: int
+    origin: RouteOrigin = RouteOrigin.UNKNOWN
+
+
+@dataclass
+class SLAPolicy:
+    """Holds SLA thresholds for latency, jitter, and packet loss."""
+
+    name: str
+    max_latency_ms: float = 150.0
+    max_jitter_ms: float = 30.0
+    max_loss_percent: float = 10.0
+
+
+@dataclass
+class LinkHealthReport:
+    """Holds a summary of link health including state, routing, metrics, and SLA compliance."""
+
+    state: str
+    route_installed: bool
+    avg_rtt_ms: float | None
+    jitter_ms: float | None
+    loss_percent: float
+    sla_compliant: bool
+    mos: float | None = None
+
+
+@dataclass
+class AppFlow:
+    """Holds per-application flow data observed on a WAN interface."""
+
+    application: str
+    category: str
+    src_ip: str
+    dst_ip: str
+    wan_interface: str
+    bytes_sent: int
+    bytes_received: int
+
+
+@dataclass
+class VPNPeerStatus:
+    """Holds the reachability and uplink state of a VPN peer."""
+
+    peer_id: str
+    peer_name: str
+    reachability: str
+    uplink: str
+
+
+@dataclass
+class TrafficShapingRule:
+    """Holds a traffic shaping rule.
+
+    Includes match criteria and optional DSCP, bandwidth, or priority.
+    """
+
+    name: str
+    match: dict[str, Any]
+    dscp_tag: int | None = None
+    bandwidth_limit_kbps: int | None = None
+    priority: str | None = None