python-netgear-switch-library 0.0.post154__py3-none-any.whl

netgear_switch/nsdp_read.py

@@ -0,0 +1,221 @@
+"""Model-driven NSDP read operations over a sync or async client.
+
+Parallel to ``snmp_read.py``. Maps NSDP TLVs onto the SAME public ``models``
+types. NSDP genuinely exposes only port link/speed, byte/CRC statistics, VLAN
+membership, PVID and management IP on these Plus switches; MAC/FDB, LLDP,
+sensors and PoE are not in the protocol, so those ops raise
+``UnsupportedCapabilityError`` rather than fabricating empty results.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .errors import UnsupportedCapabilityError
+from .models import IpMode, MgmtIpConfig, PortStats, PortStatus, VLANInfo
+from .protocols.nsdp.parsers import parse_device
+from .protocols.nsdp.protocol import Tag
+from .protocols.nsdp.types import LinkSpeed
+from .registry import Backend
+
+if TYPE_CHECKING:
+    from .models import LLDPNeighbor, MacEntry, PoEStatus, Sensor
+    from .protocols.nsdp.client import AsyncNsdpClient, NsdpClient
+    from .protocols.nsdp.types import NsdpDevice
+    from .registry import SwitchModel
+
+_NO_MACS = "NSDP exposes no MAC/FDB table (Plus switches have no remote FDB)"
+_NO_LLDP = "NSDP exposes no LLDP neighbours on these Plus switches"
+_NO_SENSORS = "NSDP exposes no environmental sensors on these Plus switches"
+_NO_POE = "NSDP exposes no PoE status; use the HTTP backend (Slice 6) for PoE"
+
+# Every read-tag ``parse_device`` knows how to decode, requested together so
+# ``get_device()``/``nsdp_device()`` returns the COMPLETE NsdpDevice in one
+# round trip -- identity, mgmt IP, per-port status/stats, VLANs/PVIDs, and the
+# QoS/mirroring/IGMP/broadcast-filtering/loop-detection tags (see parsers.py).
+_FULL_DEVICE_TAGS = [
+    Tag.MODEL,
+    Tag.MAC,
+    Tag.HOSTNAME,
+    Tag.IP_ADDRESS,
+    Tag.NETMASK,
+    Tag.GATEWAY,
+    Tag.FIRMWARE_VER_1,
+    Tag.DHCP_MODE,
+    Tag.PORT_COUNT,
+    Tag.SERIAL_NUMBER,
+    Tag.VLAN_ENGINE,
+    Tag.PORT_STATUS,
+    Tag.PORT_STATISTICS,
+    Tag.VLAN_MEMBERS,
+    Tag.PORT_PVID,
+    Tag.QOS_ENGINE,
+    Tag.PORT_MIRRORING,
+    Tag.IGMP_SNOOPING,
+    Tag.BROADCAST_FILTERING,
+    Tag.LOOP_DETECTION,
+]
+
+
+def _require_nsdp(model: SwitchModel) -> None:
+    if Backend.NSDP not in model.backends:
+        raise UnsupportedCapabilityError(f"model {model.key!r} has no NSDP backend")
+
+
+def _ports(dev: NsdpDevice) -> list[PortStatus]:
+    return [
+        PortStatus(
+            port=s.port_id,
+            name=None,  # NSDP PORT_STATUS carries no port name
+            # NSDP PORT_STATUS reports link speed only; it cannot distinguish an
+            # admin-disabled port from a link-down one, so admin_enabled is
+            # reported True (the honest "not administratively removed" default).
+            admin_enabled=True,
+            link_up=s.speed is not LinkSpeed.DOWN,
+            speed_mbps=s.speed.speed_mbps or None,
+        )
+        for s in dev.port_status
+    ]
+
+
+def _stats(dev: NsdpDevice) -> list[PortStats]:
+    return [
+        PortStats(
+            port=s.port_id,
+            rx_bytes=s.bytes_received,
+            tx_bytes=s.bytes_sent,
+            rx_packets=None,  # NSDP PORT_STATISTICS has no packet counters
+            tx_packets=None,
+            rx_errors=s.crc_errors,
+            tx_errors=None,
+        )
+        for s in dev.port_statistics
+    ]
+
+
+def _vlans(dev: NsdpDevice) -> list[VLANInfo]:
+    return [
+        VLANInfo(
+            vlan_id=m.vlan_id,
+            name=None,  # NSDP VLAN_MEMBERS carries no VLAN name
+            member_ports=m.member_ports,
+            tagged_ports=m.tagged_ports,
+            untagged_ports=m.untagged_ports,
+        )
+        for m in dev.vlan_members
+    ]
+
+
+def _mgmt(dev: NsdpDevice) -> MgmtIpConfig:
+    if dev.dhcp_enabled is None:
+        mode = IpMode.UNKNOWN
+    else:
+        mode = IpMode.DHCP if dev.dhcp_enabled else IpMode.STATIC
+    return MgmtIpConfig(
+        mode=mode, address=dev.ip, netmask=dev.netmask, gateway=dev.gateway,
+        # NSDP always echoes the device MAC (Tag.MAC, with a server_mac
+        # fallback -- see parse_device), so this is honestly always
+        # populated, never a guess. Uppercased to match the SNMP-backend
+        # formatting (parse.parse_base_mac / _format_mac_bytes) so the public
+        # field has one consistent case across backends.
+        base_mac=dev.mac.upper(),
+    )
+
+
+class NsdpReader:
+    """Synchronous NSDP read facade over one switch."""
+
+    def __init__(self, client: NsdpClient, model: SwitchModel) -> None:
+        _require_nsdp(model)
+        self.client = client
+        self.model = model
+
+    def _device(self, tags: list[Tag]) -> NsdpDevice:
+        return parse_device(self.client.read(tags))
+
+    def get_ports(self) -> list[PortStatus]:
+        return _ports(self._device([Tag.PORT_COUNT, Tag.PORT_STATUS]))
+
+    def get_stats(self) -> list[PortStats]:
+        return _stats(self._device([Tag.PORT_STATISTICS]))
+
+    def get_vlans(self) -> list[VLANInfo]:
+        return _vlans(self._device([Tag.PORT_COUNT, Tag.VLAN_MEMBERS]))
+
+    def get_pvids(self) -> list[tuple[int, int]]:
+        dev = self._device([Tag.PORT_PVID])
+        return [(p.port_id, p.vlan_id) for p in dev.port_pvids]
+
+    def get_mgmt_ip(self) -> MgmtIpConfig:
+        return _mgmt(
+            self._device([Tag.IP_ADDRESS, Tag.NETMASK, Tag.GATEWAY, Tag.DHCP_MODE])
+        )
+
+    def get_device(self) -> NsdpDevice:
+        """Return the COMPLETE raw ``NsdpDevice`` for this switch: every tag
+        ``parse_device`` knows how to decode, in one round trip. Unlike the
+        other ``get_*`` ops above, this returns the NSDP-native shape
+        (including the raw port-status speed byte) rather than mapping onto
+        the shared ``models`` types -- callers that need the full protocol
+        surface (e.g. gdoc2netcfg's DiscoveryDB) use this instead of the
+        per-field ops."""
+        return self._device(_FULL_DEVICE_TAGS)
+
+    def get_macs(self) -> list[MacEntry]:
+        raise UnsupportedCapabilityError(_NO_MACS)
+
+    def get_lldp(self) -> list[LLDPNeighbor]:
+        raise UnsupportedCapabilityError(_NO_LLDP)
+
+    def get_sensors(self) -> list[Sensor]:
+        raise UnsupportedCapabilityError(_NO_SENSORS)
+
+    def get_poe(self) -> list[PoEStatus]:
+        raise UnsupportedCapabilityError(_NO_POE)
+
+
+class AsyncNsdpReader:
+    """Asynchronous NSDP read facade (mirror of NsdpReader)."""
+
+    def __init__(self, client: AsyncNsdpClient, model: SwitchModel) -> None:
+        _require_nsdp(model)
+        self.client = client
+        self.model = model
+
+    async def _device(self, tags: list[Tag]) -> NsdpDevice:
+        return parse_device(await self.client.read(tags))
+
+    async def get_ports(self) -> list[PortStatus]:
+        return _ports(await self._device([Tag.PORT_COUNT, Tag.PORT_STATUS]))
+
+    async def get_stats(self) -> list[PortStats]:
+        return _stats(await self._device([Tag.PORT_STATISTICS]))
+
+    async def get_vlans(self) -> list[VLANInfo]:
+        return _vlans(await self._device([Tag.PORT_COUNT, Tag.VLAN_MEMBERS]))
+
+    async def get_pvids(self) -> list[tuple[int, int]]:
+        dev = await self._device([Tag.PORT_PVID])
+        return [(p.port_id, p.vlan_id) for p in dev.port_pvids]
+
+    async def get_mgmt_ip(self) -> MgmtIpConfig:
+        return _mgmt(
+            await self._device(
+                [Tag.IP_ADDRESS, Tag.NETMASK, Tag.GATEWAY, Tag.DHCP_MODE]
+            )
+        )
+
+    async def get_device(self) -> NsdpDevice:
+        """Async twin of ``NsdpReader.get_device`` -- see there."""
+        return await self._device(_FULL_DEVICE_TAGS)
+
+    async def get_macs(self) -> list[MacEntry]:
+        raise UnsupportedCapabilityError(_NO_MACS)
+
+    async def get_lldp(self) -> list[LLDPNeighbor]:
+        raise UnsupportedCapabilityError(_NO_LLDP)
+
+    async def get_sensors(self) -> list[Sensor]:
+        raise UnsupportedCapabilityError(_NO_SENSORS)
+
+    async def get_poe(self) -> list[PoEStatus]:
+        raise UnsupportedCapabilityError(_NO_POE)

netgear_switch/nsdp_write.py

@@ -0,0 +1,315 @@
+"""Model-driven NSDP write/control over a write-capable sync or async client.
+
+Parallel to ``snmp_write.py``. Every write performs the NSDP WRITE_REQUEST
+(v1-authenticated) then re-reads to verify (``WriteVerificationError`` with
+before/after on mismatch; a bad password / transport error surfaces as
+``NsdpError`` from the client first). Disruptive per-port writes to a
+``protected_ports`` port are refused unless ``force=True``. Writes NSDP has no
+tag for (PoE, per-port admin, VLAN create/delete) raise
+``UnsupportedCapabilityError`` — never a silent no-op.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .errors import (
+    ProtectedPortError,
+    UnsupportedCapabilityError,
+    WriteVerificationError,
+)
+from .models import VlanMode
+from .nsdp_read import AsyncNsdpReader, NsdpReader
+from .protocols.nsdp.protocol import Tag
+from .protocols.nsdp.write import ipv4_tlv, pvid_tlv, vlan_members_tlv
+from .registry import Backend
+
+if TYPE_CHECKING:
+    from .models import VLANInfo
+    from .protocols.nsdp.client import AsyncNsdpWriteClient, NsdpWriteClient
+    from .registry import SwitchModel
+    from .snmp_write import PoeCycleTimeouts
+
+_NO_POE = "NSDP has no PoE control tag; use the HTTP backend (Slice 6) for PoE"
+_NO_PORT_ADMIN = (
+    "no per-port admin-enable is available on these Plus models: NSDP has no "
+    "admin-enable tag, and the web UI has no grounded port-enable endpoint "
+    "(UNVERIFIED-pending-capture)"
+)
+_NO_VLAN_LIFECYCLE = (
+    "NSDP has no VLAN create/destroy tag on these Plus models; only VLAN "
+    "membership/PVID are writable over NSDP"
+)
+
+
+def _require_nsdp(model: SwitchModel) -> None:
+    if Backend.NSDP not in model.backends:
+        raise UnsupportedCapabilityError(f"model {model.key!r} has no NSDP backend")
+
+
+def _members_after(
+    current: VLANInfo | None, port: int, mode: VlanMode
+) -> tuple[set[int], set[int]]:
+    """Read-modify-write the (members, tagged) sets for one membership change."""
+    members = set(current.member_ports) if current is not None else set()
+    tagged = set(current.tagged_ports) if current is not None else set()
+    if mode is VlanMode.EXCLUDED:
+        members.discard(port)
+        tagged.discard(port)
+    else:
+        members.add(port)
+        tagged.add(port) if mode is VlanMode.TAGGED else tagged.discard(port)
+    return members, tagged
+
+
+def _membership_ok(after: VLANInfo | None, port: int, mode: VlanMode) -> bool:
+    if after is None:
+        return mode is VlanMode.EXCLUDED
+    in_members = port in after.member_ports
+    in_tagged = port in after.tagged_ports
+    if mode is VlanMode.EXCLUDED:
+        return not in_members
+    return in_members and (in_tagged == (mode is VlanMode.TAGGED))
+
+
+class NsdpWriter:
+    """Synchronous NSDP write facade over one switch."""
+
+    def __init__(
+        self,
+        client: NsdpWriteClient,
+        model: SwitchModel,
+        *,
+        password: str,
+        protected_ports: frozenset[int] = frozenset(),
+    ) -> None:
+        _require_nsdp(model)
+        self.client = client
+        self.model = model
+        self._password = password
+        self.protected_ports = protected_ports
+        self._reader = NsdpReader(client, model)
+
+    def _guard(self, port: int, force: bool) -> None:
+        if port in self.protected_ports and not force:
+            raise ProtectedPortError(
+                f"port {port} is protected; pass force=True to override"
+            )
+
+    def _vlan(self, vlan: int) -> VLANInfo | None:
+        return next((v for v in self._reader.get_vlans() if v.vlan_id == vlan), None)
+
+    def set_pvid(self, port: int, vlan: int, *, force: bool = False) -> None:
+        # UNVERIFIED pending a hardware capture: PORT_PVID (0x3000) is documented
+        # READ-ONLY in the reference spec, so a real switch may reject this write
+        # (verify-after-write below is the guard). Same house style as
+        # snmp_write.py:set_mgmt_ip's unverified-OID note.
+        self._guard(port, force)
+        before = dict(self._reader.get_pvids())
+        self.client.write([pvid_tlv(port, vlan)], password=self._password)
+        after = dict(self._reader.get_pvids())
+        if after.get(port) != vlan:
+            raise WriteVerificationError(
+                f"PVID for port {port} did not read back as {vlan}",
+                before=before.get(port), after=after.get(port),
+            )
+
+    def set_vlan_membership(
+        self, vlan: int, port: int, mode: VlanMode, *, force: bool = False
+    ) -> None:
+        # UNVERIFIED pending a hardware capture: VLAN_MEMBERS (0x2800) is
+        # documented READ-ONLY in the reference spec, so a real switch may reject
+        # this write (verify-after-write below is the guard). Same house style as
+        # snmp_write.py:set_mgmt_ip's unverified-OID note.
+        self._guard(port, force)
+        before = self._vlan(vlan)
+        members, tagged = _members_after(before, port, mode)
+        self.client.write(
+            [vlan_members_tlv(vlan, members, tagged, self.model.port_count)],
+            password=self._password,
+        )
+        after = self._vlan(vlan)
+        if not _membership_ok(after, port, mode):
+            raise WriteVerificationError(
+                f"VLAN {vlan} membership for port {port} did not read back as {mode}",
+                before=before, after=after,
+            )
+
+    def set_mgmt_ip(
+        self, address: str, netmask: str, gateway: str, *, force: bool = False
+    ) -> None:
+        # Force-gated: a wrong management-IP write can strand the switch.
+        # UNVERIFIED pending a hardware capture: the NSDP write path + v1 auth are
+        # unconfirmed against real hardware (verify-after-write below is the
+        # guard), same house style as snmp_write.py:set_mgmt_ip. (IP/netmask/
+        # gateway are R/W in the reference spec, unlike PVID/VLAN_MEMBERS.)
+        if not force:
+            raise ProtectedPortError(
+                "set_mgmt_ip can strand the switch; pass force=True to override"
+            )
+        before = self._reader.get_mgmt_ip()
+        self.client.write(
+            [
+                ipv4_tlv(Tag.IP_ADDRESS, address),
+                ipv4_tlv(Tag.NETMASK, netmask),
+                ipv4_tlv(Tag.GATEWAY, gateway),
+            ],
+            password=self._password,
+        )
+        after = self._reader.get_mgmt_ip()
+        if (after.address, after.netmask, after.gateway) != (address, netmask, gateway):
+            raise WriteVerificationError(
+                "management IP did not read back as written",
+                before=before, after=after,
+            )
+
+    def set_poe(self, port: int, on: bool, *, force: bool = False) -> None:
+        raise UnsupportedCapabilityError(_NO_POE)
+
+    def cycle_poe(
+        self, port: int, *, force: bool = False,
+        timeouts: PoeCycleTimeouts | None = None,
+    ) -> None:
+        # timeouts accepted-but-unused: matches SnmpWriter's signature so the
+        # facade's SnmpWriter | NsdpWriter union call site typechecks; NSDP has
+        # no PoE control tag at all, so there is nothing to time.
+        raise UnsupportedCapabilityError(_NO_POE)
+
+    def clear_poe_fault(
+        self, port: int, *, force: bool = False,
+        timeouts: PoeCycleTimeouts | None = None,
+    ) -> None:
+        raise UnsupportedCapabilityError(_NO_POE)
+
+    def set_port_enabled(
+        self, port: int, enabled: bool, *, force: bool = False
+    ) -> None:
+        raise UnsupportedCapabilityError(_NO_PORT_ADMIN)
+
+    def create_vlan(self, vlan: int, name: str, *, force: bool = False) -> None:
+        raise UnsupportedCapabilityError(_NO_VLAN_LIFECYCLE)
+
+    def delete_vlan(self, vlan: int, *, force: bool = False) -> None:
+        raise UnsupportedCapabilityError(_NO_VLAN_LIFECYCLE)
+
+
+class AsyncNsdpWriter:
+    """Asynchronous NSDP write facade (mirror of NsdpWriter)."""
+
+    def __init__(
+        self,
+        client: AsyncNsdpWriteClient,
+        model: SwitchModel,
+        *,
+        password: str,
+        protected_ports: frozenset[int] = frozenset(),
+    ) -> None:
+        _require_nsdp(model)
+        self.client = client
+        self.model = model
+        self._password = password
+        self.protected_ports = protected_ports
+        self._reader = AsyncNsdpReader(client, model)
+
+    def _guard(self, port: int, force: bool) -> None:
+        if port in self.protected_ports and not force:
+            raise ProtectedPortError(
+                f"port {port} is protected; pass force=True to override"
+            )
+
+    async def _vlan(self, vlan: int) -> VLANInfo | None:
+        vlans = await self._reader.get_vlans()
+        return next((v for v in vlans if v.vlan_id == vlan), None)
+
+    async def set_pvid(self, port: int, vlan: int, *, force: bool = False) -> None:
+        # UNVERIFIED pending a hardware capture: PORT_PVID (0x3000) is documented
+        # READ-ONLY in the reference spec, so a real switch may reject this write
+        # (verify-after-write below is the guard). Same house style as
+        # snmp_write.py:set_mgmt_ip's unverified-OID note.
+        self._guard(port, force)
+        before = dict(await self._reader.get_pvids())
+        await self.client.write([pvid_tlv(port, vlan)], password=self._password)
+        after = dict(await self._reader.get_pvids())
+        if after.get(port) != vlan:
+            raise WriteVerificationError(
+                f"PVID for port {port} did not read back as {vlan}",
+                before=before.get(port), after=after.get(port),
+            )
+
+    async def set_vlan_membership(
+        self, vlan: int, port: int, mode: VlanMode, *, force: bool = False
+    ) -> None:
+        # UNVERIFIED pending a hardware capture: VLAN_MEMBERS (0x2800) is
+        # documented READ-ONLY in the reference spec, so a real switch may reject
+        # this write (verify-after-write below is the guard). Same house style as
+        # snmp_write.py:set_mgmt_ip's unverified-OID note.
+        self._guard(port, force)
+        before = await self._vlan(vlan)
+        members, tagged = _members_after(before, port, mode)
+        await self.client.write(
+            [vlan_members_tlv(vlan, members, tagged, self.model.port_count)],
+            password=self._password,
+        )
+        after = await self._vlan(vlan)
+        if not _membership_ok(after, port, mode):
+            raise WriteVerificationError(
+                f"VLAN {vlan} membership for port {port} did not read back as {mode}",
+                before=before, after=after,
+            )
+
+    async def set_mgmt_ip(
+        self, address: str, netmask: str, gateway: str, *, force: bool = False
+    ) -> None:
+        # Force-gated: a wrong management-IP write can strand the switch.
+        # UNVERIFIED pending a hardware capture: the NSDP write path + v1 auth are
+        # unconfirmed against real hardware (verify-after-write below is the
+        # guard), same house style as snmp_write.py:set_mgmt_ip. (IP/netmask/
+        # gateway are R/W in the reference spec, unlike PVID/VLAN_MEMBERS.)
+        if not force:
+            raise ProtectedPortError(
+                "set_mgmt_ip can strand the switch; pass force=True to override"
+            )
+        before = await self._reader.get_mgmt_ip()
+        await self.client.write(
+            [
+                ipv4_tlv(Tag.IP_ADDRESS, address),
+                ipv4_tlv(Tag.NETMASK, netmask),
+                ipv4_tlv(Tag.GATEWAY, gateway),
+            ],
+            password=self._password,
+        )
+        after = await self._reader.get_mgmt_ip()
+        if (after.address, after.netmask, after.gateway) != (address, netmask, gateway):
+            raise WriteVerificationError(
+                "management IP did not read back as written",
+                before=before, after=after,
+            )
+
+    async def set_poe(self, port: int, on: bool, *, force: bool = False) -> None:
+        raise UnsupportedCapabilityError(_NO_POE)
+
+    async def cycle_poe(
+        self, port: int, *, force: bool = False,
+        timeouts: PoeCycleTimeouts | None = None,
+    ) -> None:
+        # timeouts accepted-but-unused: matches AsyncSnmpWriter's signature so
+        # the facade's AsyncSnmpWriter | AsyncNsdpWriter union call site
+        # typechecks; NSDP has no PoE control tag at all, so there is nothing
+        # to time.
+        raise UnsupportedCapabilityError(_NO_POE)
+
+    async def clear_poe_fault(
+        self, port: int, *, force: bool = False,
+        timeouts: PoeCycleTimeouts | None = None,
+    ) -> None:
+        raise UnsupportedCapabilityError(_NO_POE)
+
+    async def set_port_enabled(
+        self, port: int, enabled: bool, *, force: bool = False
+    ) -> None:
+        raise UnsupportedCapabilityError(_NO_PORT_ADMIN)
+
+    async def create_vlan(self, vlan: int, name: str, *, force: bool = False) -> None:
+        raise UnsupportedCapabilityError(_NO_VLAN_LIFECYCLE)
+
+    async def delete_vlan(self, vlan: int, *, force: bool = False) -> None:
+        raise UnsupportedCapabilityError(_NO_VLAN_LIFECYCLE)

netgear_switch/protocols/__init__.py

@@ -0,0 +1 @@
+"""SNMP protocol logic (pure, I/O-free)."""

netgear_switch/protocols/http/__init__.py

@@ -0,0 +1 @@
+"""Pure (I/O-free) HTTP web-UI protocol layer: crypto, endpoints, parsers, forms."""

netgear_switch/protocols/http/crypt.py

@@ -0,0 +1,29 @@
+"""Pure Netgear web-UI login crypto (no I/O).
+
+The Plus family authenticates with ``md5(merge(password, rand))`` where
+``rand`` is a per-page nonce scraped from the login form and ``merge``
+interleaves the two strings character by character. GROUNDED against
+``rcfiles/bin/netgear-smp-vlan`` and ``py_netgear_plus/netgear_crypt.py``.
+"""
+from __future__ import annotations
+
+import hashlib
+
+
+def merge(str1: str, str2: str) -> str:
+    """Interleave two strings character by character (Netgear login scheme)."""
+    out: list[str] = []
+    i = j = 0
+    while i < len(str1) or j < len(str2):
+        if i < len(str1):
+            out.append(str1[i])
+            i += 1
+        if j < len(str2):
+            out.append(str2[j])
+            j += 1
+    return "".join(out)
+
+
+def merge_hash_md5(password: str, rand: str) -> str:
+    """Return ``md5(merge(password, rand))`` as lowercase hex (Plus login hash)."""
+    return hashlib.md5(merge(password, rand).encode()).hexdigest()