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

netgear_switch/transport/aio/nsdp_udp.py

@@ -0,0 +1,152 @@
+"""Asynchronous NSDP UDP transport (stdlib asyncio datagram endpoint).
+
+Mirrors the sync ``UdpNsdpClient`` but over ``loop.create_datagram_endpoint``.
+The datagram exchange is factored into an injectable ``transceive`` coroutine so
+read/write are unit-testable with a fake exchange (no real UDP), the async
+analogue of the sync client's ``sock_factory`` seam. As with the sync client,
+``client_port=0`` binds an unprivileged ephemeral port for the virtual face.
+"""
+from __future__ import annotations
+
+import asyncio
+import socket
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING
+
+from ...protocols.nsdp.client import NsdpError, check_result, read_interface_mac
+from ...protocols.nsdp.protocol import NSDPPacket, Op
+from ...protocols.nsdp.write import build_read_request, build_write_request
+
+if TYPE_CHECKING:
+    from ...protocols.nsdp.protocol import Tag, TLVEntry
+
+Transceive = Callable[..., Awaitable[bytes]]
+
+_DUMMY_MAC = b"\x00\x00\x00\x00\x00\x01"
+_BROADCAST_MAC = b"\x00" * 6
+
+
+class _OneShotProtocol(asyncio.DatagramProtocol):
+    """Resolves a future with the first datagram (or an error) received."""
+
+    def __init__(self, future: asyncio.Future[bytes]) -> None:
+        self._future = future
+
+    def datagram_received(self, data: bytes, _addr: object) -> None:
+        if not self._future.done():
+            self._future.set_result(data)
+
+    def error_received(self, exc: Exception) -> None:
+        if not self._future.done():
+            self._future.set_exception(exc)
+
+
+async def _udp_transceive(
+    payload: bytes,
+    addr: tuple[str, int],
+    *,
+    client_port: int,
+    interface: str | None,
+    timeout: float,
+) -> bytes:
+    loop = asyncio.get_running_loop()
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        if interface is not None:
+            sock.setsockopt(
+                socket.SOL_SOCKET, socket.SO_BINDTODEVICE, interface.encode() + b"\0"
+            )
+        sock.bind(("", client_port))
+        future: asyncio.Future[bytes] = loop.create_future()
+        transport, _proto = await loop.create_datagram_endpoint(
+            lambda: _OneShotProtocol(future), sock=sock
+        )
+    except BaseException:
+        # setsockopt/bind (or the endpoint handoff itself) failed before
+        # create_datagram_endpoint took ownership of the socket on success —
+        # nothing else will ever close it, so close it here to avoid an fd
+        # leak. Once the try above succeeds, only the transport (below) owns
+        # the socket and closes it.
+        sock.close()
+        raise
+    try:
+        transport.sendto(payload, addr)
+        return await asyncio.wait_for(future, timeout)
+    finally:
+        transport.close()
+
+
+class AsyncUdpNsdpClient:
+    """Async NSDP read+write client over UDP for a single switch."""
+
+    def __init__(
+        self,
+        host: str,
+        *,
+        interface: str | None = None,
+        client_mac: bytes | None = None,
+        client_port: int = 63321,
+        server_port: int = 63322,
+        timeout: float = 2.0,
+        transceive: Transceive = _udp_transceive,
+    ) -> None:
+        self.host = host
+        self._interface = interface
+        self._client_port = client_port
+        self._server_port = server_port
+        self._timeout = timeout
+        self._transceive = transceive
+        self._sequence = 0
+        if client_mac is not None:
+            self._client_mac = client_mac
+        elif interface is not None:
+            self._client_mac = read_interface_mac(interface)
+        else:
+            self._client_mac = _DUMMY_MAC
+
+    def _next_seq(self) -> int:
+        self._sequence = (self._sequence + 1) & 0xFFFF
+        return self._sequence
+
+    async def _exchange(self, request: NSDPPacket) -> NSDPPacket:
+        try:
+            data = await self._transceive(
+                request.encode(),
+                (self.host, self._server_port),
+                client_port=self._client_port,
+                interface=self._interface,
+                timeout=self._timeout,
+            )
+        except TimeoutError as exc:
+            raise NsdpError(f"NSDP request to {self.host} timed out") from exc
+        try:
+            return NSDPPacket.decode(data)
+        except ValueError as exc:
+            raise NsdpError(
+                f"malformed NSDP response from {self.host}: {exc}"
+            ) from exc
+
+    async def read(self, tags: list[Tag]) -> NSDPPacket:
+        req = build_read_request(
+            self._client_mac, _BROADCAST_MAC, self._next_seq(), tags
+        )
+        resp = await self._exchange(req)
+        if resp.op != Op.READ_RESPONSE:
+            raise NsdpError(f"expected READ_RESPONSE from {self.host}, got {resp.op}")
+        return resp
+
+    async def write(self, tlvs: list[TLVEntry], *, password: str) -> NSDPPacket:
+        req = build_write_request(
+            self._client_mac, _BROADCAST_MAC, self._next_seq(), password, tlvs
+        )
+        resp = await self._exchange(req)
+        # Guard the op-code before trusting result (symmetric with read()): a
+        # misrouted/duplicate UDP datagram (e.g. a stray READ_RESPONSE with
+        # result=0) must not silently pass check_result as a successful write.
+        if resp.op != Op.WRITE_RESPONSE:
+            raise NsdpError(
+                f"expected WRITE_RESPONSE from {self.host}, got {resp.op}"
+            )
+        check_result(resp)
+        return resp

netgear_switch/transport/aio/snmp_pysnmp.py

@@ -0,0 +1,247 @@
+"""Asynchronous SNMP v2c client on pysnmp v7. pysnmp is imported lazily.
+
+Value parity: each pysnmp SMI value is normalized to the SAME plain Python type
+the net-snmp CLI client (Task 10) produces — int for integer-family, str for
+text/OID/IP, bytes for non-printable octet strings (Hex-STRING). Task 16's
+sync/async equivalence test compares these values, so they must match.
+
+pysnmp ships with no type stubs and is untyped under mypy --strict. Rather than
+a blanket `ignore_missing_imports` for the whole package, `_pysnmp_asyncio()`
+is the single lazy-import seam. It resolves the module dynamically via
+`importlib.import_module` (a plain `str -> ModuleType` call mypy can't follow
+into pysnmp's untyped internals), so no `type: ignore` is needed at all;
+everything downstream of this one seam is deliberately treated as `Any`, and
+the rest of the module is fully typed.
+"""
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+from ...protocols.snmp.client import ABSENT_TYPES, SnmpError, SnmpRow
+
+if TYPE_CHECKING:
+    from ...protocols.snmp.write import SetVarbind
+
+Triple = tuple[str, int | str | bytes, str]
+
+
+def _pysnmp_asyncio() -> Any:
+    """Lazily import pysnmp's v3arch asyncio hlapi module."""
+    return importlib.import_module("pysnmp.hlapi.v3arch.asyncio")
+
+# pysnmp class name -> net-snmp-style type token (parity with the CLI client).
+_TOKEN = {
+    "Integer": "INTEGER",
+    "Integer32": "INTEGER",
+    "Gauge32": "Gauge32",
+    "Unsigned32": "Gauge32",
+    "Counter32": "Counter32",
+    "Counter64": "Counter64",
+    "TimeTicks": "Timeticks",
+    "IpAddress": "IpAddress",
+    "ObjectIdentifier": "OID",
+    "ObjectIdentity": "OID",
+}
+_INT_CLASSES = frozenset(
+    {"Integer", "Integer32", "Gauge32", "Unsigned32", "Counter32",
+     "Counter64", "TimeTicks"}
+)
+_ABSENT_CLASSES = frozenset({"NoSuchObject", "NoSuchInstance", "EndOfMibView"})
+
+
+def _octet_value(raw: bytes) -> tuple[str | bytes, str]:
+    """Render an octet string as net-snmp does: printable -> STRING, else Hex."""
+    if raw == b"" or all(0x20 <= b < 0x7F for b in raw):
+        return raw.decode("ascii"), "STRING"
+    return raw, "Hex-STRING"
+
+
+def _normalize_varbind(name: Any, value: Any) -> Triple:
+    """Convert a pysnmp (name, value) varbind into a normalized SnmpRow triple."""
+    oid = str(name).lstrip(".")
+    cls = value.__class__.__name__
+    if cls in _ABSENT_CLASSES:
+        return oid, "", cls.upper()  # e.g. "NOSUCHOBJECT" ∈ ABSENT_TYPES
+    if cls in _INT_CLASSES:
+        return oid, int(value), _TOKEN[cls]
+    if cls == "OctetString":
+        norm, token = _octet_value(bytes(value.asOctets()))
+        return oid, norm, token
+    if cls in ("ObjectIdentifier", "ObjectIdentity"):
+        # NOT value.prettyPrint(): hlapi's get_cmd/bulk_walk_cmd auto-resolve
+        # an OBJECT IDENTIFIER *value* against their attached MIB view
+        # controller, so prettyPrint() can render a well-known prefix
+        # symbolically (e.g. "SNMPv2-SMI::enterprises.4526.10.100.14")
+        # instead of the plain numeric dotted OID str(value) always gives
+        # (confirmed empirically: str(value) == "1.3.6.1.4.1.4526.10.100.14",
+        # matching the net-snmp CLI client's numeric ("-On") output exactly).
+        return oid, str(value).lstrip("."), "OID"
+    if cls == "IpAddress":
+        return oid, value.prettyPrint(), "IpAddress"
+    return oid, value.prettyPrint(), cls  # textual fallback
+
+
+def _to_set_value(hlapi: Any, vb: SetVarbind) -> Any:
+    """Map a SetVarbind's type letter to the matching pysnmp SMI value object.
+
+    ``s`` and ``x`` both become OctetString (bytes on the wire); ``s`` str
+    values are latin-1 encoded (the inverse of the read normalizer). Kept as a
+    plain function taking ``hlapi`` so it is unit-testable with a fake module,
+    with no live pysnmp import.
+    """
+    if vb.type_letter == "i":
+        return hlapi.Integer32(int(vb.value))
+    if vb.type_letter == "u":
+        return hlapi.Gauge32(int(vb.value))
+    if vb.type_letter == "a":
+        return hlapi.IpAddress(str(vb.value))
+    if vb.type_letter in ("s", "x"):
+        data = (
+            vb.value
+            if isinstance(vb.value, bytes)
+            else str(vb.value).encode("latin-1")
+        )
+        return hlapi.OctetString(data)
+    raise SnmpError(f"unsupported SET type letter {vb.type_letter!r}")
+
+
+class PysnmpClient:
+    """Async SNMP v2c read/write client for a single switch."""
+
+    def __init__(
+        self,
+        host: str,
+        community: str,
+        *,
+        port: int = 161,
+        timeout: float = 2.0,
+        retries: int = 1,
+    ) -> None:
+        self.host = host
+        self.community = community
+        self.port = port
+        self.timeout = timeout
+        self.retries = retries
+
+    async def _do_get(self, oids: list[str]) -> list[Triple]:
+        hlapi = _pysnmp_asyncio()
+        engine = hlapi.SnmpEngine()
+        try:
+            target = await hlapi.UdpTransportTarget.create(
+                (self.host, self.port), timeout=self.timeout, retries=self.retries
+            )
+            err_ind, err_stat, _idx, binds = await hlapi.get_cmd(
+                engine, hlapi.CommunityData(self.community), target,
+                hlapi.ContextData(),
+                *[hlapi.ObjectType(hlapi.ObjectIdentity(o)) for o in oids],
+            )
+            if err_ind or err_stat:
+                raise SnmpError(f"GET {oids} on {self.host}: {err_ind or err_stat}")
+            return [_normalize_varbind(vb[0], vb[1]) for vb in binds]
+        finally:
+            engine.close_dispatcher()
+
+    async def _do_walk(self, base_oid: str) -> list[Triple]:
+        hlapi = _pysnmp_asyncio()
+        engine = hlapi.SnmpEngine()
+        rows: list[Triple] = []
+        try:
+            target = await hlapi.UdpTransportTarget.create(
+                (self.host, self.port), timeout=self.timeout, retries=self.retries
+            )
+            async for err_ind, err_stat, _idx, binds in hlapi.bulk_walk_cmd(
+                engine, hlapi.CommunityData(self.community), target,
+                hlapi.ContextData(), 0, 25,
+                hlapi.ObjectType(hlapi.ObjectIdentity(base_oid)),
+                lexicographicMode=False,
+            ):
+                if err_ind or err_stat:
+                    raise SnmpError(
+                        f"WALK {base_oid} on {self.host}: {err_ind or err_stat}"
+                    )
+                done = False
+                for vb in binds:
+                    oid, value, typ = _normalize_varbind(vb[0], vb[1])
+                    if typ == "ENDOFMIBVIEW":
+                        # Benign terminator (mirrors the sync client's
+                        # _END_OF_MIB_MARKERS): stop, keep rows so far.
+                        done = True
+                        break
+                    if typ.upper() in ABSENT_TYPES:
+                        raise SnmpError(
+                            f"absent OID in pysnmp WALK response: {oid}"
+                        )
+                    rows.append((oid, value, typ))
+                if done:
+                    break
+            return rows
+        finally:
+            engine.close_dispatcher()
+
+    async def get(self, oids: list[str]) -> list[SnmpRow]:
+        if not oids:
+            return []
+        try:
+            raw = await self._do_get(oids)
+        except SnmpError:
+            raise
+        except Exception as exc:
+            raise SnmpError(f"GET {oids} on {self.host} failed: {exc}") from exc
+        rows: list[SnmpRow] = []
+        for oid, value, typ in raw:
+            if typ.upper() in ABSENT_TYPES:
+                raise SnmpError(f"absent OID in pysnmp GET response: {oid}")
+            rows.append(SnmpRow(oid, value, typ))
+        return rows
+
+    async def walk(self, base_oid: str) -> list[SnmpRow]:
+        try:
+            raw = await self._do_walk(base_oid)
+        except SnmpError:
+            raise
+        except Exception as exc:
+            raise SnmpError(f"WALK {base_oid} on {self.host} failed: {exc}") from exc
+        return [
+            SnmpRow(oid, value, typ)
+            for oid, value, typ in raw
+            if typ.upper() not in ABSENT_TYPES
+        ]
+
+    async def _do_set(self, varbinds: list[SetVarbind]) -> None:
+        hlapi = _pysnmp_asyncio()
+        engine = hlapi.SnmpEngine()
+        try:
+            target = await hlapi.UdpTransportTarget.create(
+                (self.host, self.port), timeout=self.timeout, retries=self.retries
+            )
+            objects = [
+                hlapi.ObjectType(hlapi.ObjectIdentity(vb.oid), _to_set_value(hlapi, vb))
+                for vb in varbinds
+            ]
+            err_ind, err_stat, _idx, _binds = await hlapi.set_cmd(
+                engine, hlapi.CommunityData(self.community), target,
+                hlapi.ContextData(), *objects,
+            )
+            if err_ind or err_stat:
+                raise SnmpError(
+                    f"SET {[vb.oid for vb in varbinds]} on {self.host}: "
+                    f"{err_ind or err_stat}"
+                )
+        finally:
+            engine.close_dispatcher()
+
+    async def set(self, varbind: SetVarbind) -> None:
+        await self.set_many([varbind])
+
+    async def set_many(self, varbinds: list[SetVarbind]) -> None:
+        if not varbinds:
+            return
+        try:
+            await self._do_set(varbinds)
+        except SnmpError:
+            raise
+        except Exception as exc:
+            raise SnmpError(
+                f"SET {[vb.oid for vb in varbinds]} on {self.host} failed: {exc}"
+            ) from exc

netgear_switch/transport/http/__init__.py

@@ -0,0 +1 @@
+"""httpx-backed HTTP web-UI transport (sync + async)."""

netgear_switch/transport/http/client.py

@@ -0,0 +1,217 @@
+"""httpx-backed web-UI clients implementing the session Protocols.
+
+One codebase: all URL/crypto/parse logic lives in the pure ``protocols.http``
+package; only the actual GET/POST differ between the sync ``httpx.Client`` and
+async ``httpx.AsyncClient``. Legacy Plus switches are HTTP-only, so ``base_url``
+is ``http://`` and TLS verification (when a model ever needs https) defaults to
+off for permissive legacy behaviour.
+
+httpx is an optional dependency (``[http]`` extra); it is imported at module
+top-level because this module lives under ``transport/http`` and is only ever
+imported lazily by ``_dispatch`` (function-local imports), exactly like the
+SNMP transports — ``import netgear_switch`` never reaches here.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx
+
+from ...errors import HttpAuthError, HttpError, HttpUnexpectedPageError
+from ...protocols.http.crypt import merge_hash_md5
+from ...protocols.http.endpoints import LoginScheme
+from ...protocols.http.parse import parse_login_rand
+
+if TYPE_CHECKING:
+    from types import TracebackType
+    from typing import Self
+
+    from ...protocols.http.endpoints import HttpModelSpec
+
+_TIMEOUT = 15.0
+
+
+def _login_body(
+    spec: HttpModelSpec, password: str, login_page_html: str
+) -> dict[str, str]:
+    """Build the login POST body for ``spec`` (pure; shared sync+async).
+
+    MERGE_HASH_CGI/GAMBIT hash the password with the page ``rand`` nonce;
+    CHEETAH_FORM posts the plaintext password. Raises ``HttpUnexpectedPageError``
+    if a required ``rand`` nonce is missing from the login page.
+    """
+    if spec.scheme is LoginScheme.CHEETAH_FORM:
+        return {spec.password_field: password}
+    rand = parse_login_rand(login_page_html) if spec.needs_rand else None
+    if spec.needs_rand and not rand:
+        raise HttpUnexpectedPageError(
+            f"no login 'rand' nonce on {spec.login_path} — not a {spec.model_key}?"
+        )
+    hashed = merge_hash_md5(password, rand or "")
+    return {spec.password_field: hashed}
+
+
+def _check_authed(spec: HttpModelSpec, cookies: httpx.Cookies) -> None:
+    if spec.cookie_name not in cookies:
+        raise HttpAuthError(
+            f"web-UI login failed for {spec.model_key} — no {spec.cookie_name} cookie "
+            "(check password, or switch may be locked out)"
+        )
+
+
+def _validate_response(
+    resp: httpx.Response, *, context: str, path: str | None = None
+) -> None:
+    """Raise on an HTTP-error status, or (if ``path`` given) a lost session.
+
+    Pure; shared by every sync/async GET/POST call site so status-code and
+    stale-session handling cannot drift between the two codebases.
+
+    ``context`` names the request for the status-code error (e.g. ``"GET
+    /login.cgi"``). ``path`` is only passed by mid-session reads that should
+    also detect the web-UI silently redirecting back to the login page.
+    """
+    if resp.status_code >= 400:
+        raise HttpError(f"{context} returned HTTP {resp.status_code}")
+    if path is not None and "redirect to login" in resp.text.lower():
+        raise HttpAuthError(f"session lost fetching {path}")
+
+
+class HttpClient:
+    """Synchronous httpx web-UI session (implements ``HttpSession``)."""
+
+    def __init__(
+        self,
+        host: str,
+        password: str,
+        spec: HttpModelSpec,
+        *,
+        verify_tls: bool = False,
+        transport: httpx.MockTransport | None = None,
+    ) -> None:
+        self._spec = spec
+        self._password = password
+        self._client = httpx.Client(
+            base_url=f"http://{host}",
+            timeout=_TIMEOUT,
+            verify=verify_tls,
+            transport=transport,
+            follow_redirects=True,
+        )
+        self._logged_in = False
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def login(self) -> None:
+        try:
+            page = self._client.get(self._spec.login_path)
+            _validate_response(page, context=f"GET {self._spec.login_path}")
+            body = _login_body(self._spec, self._password, page.text)
+            resp = self._client.post(self._spec.login_path, data=body)
+            _validate_response(resp, context=f"POST {self._spec.login_path}")
+        except httpx.HTTPError as exc:
+            raise HttpError(f"web-UI login transport error: {exc}") from exc
+        _check_authed(self._spec, self._client.cookies)
+        self._logged_in = True
+
+    def get_page(self, path: str) -> str:
+        if not self._logged_in:
+            self.login()
+        try:
+            resp = self._client.get(path)
+        except httpx.HTTPError as exc:
+            raise HttpError(f"GET {path} transport error: {exc}") from exc
+        _validate_response(resp, context=f"GET {path}", path=path)
+        return resp.text
+
+    def post_form(self, path: str, data: dict[str, str]) -> str:
+        if not self._logged_in:
+            self.login()
+        try:
+            resp = self._client.post(path, data=data)
+        except httpx.HTTPError as exc:
+            raise HttpError(f"POST {path} transport error: {exc}") from exc
+        _validate_response(resp, context=f"POST {path}")
+        return resp.text
+
+    def close(self) -> None:
+        self._client.close()
+
+
+class AsyncHttpClient:
+    """Asynchronous httpx web-UI session (implements ``AsyncHttpSession``)."""
+
+    def __init__(
+        self,
+        host: str,
+        password: str,
+        spec: HttpModelSpec,
+        *,
+        verify_tls: bool = False,
+        transport: httpx.MockTransport | None = None,
+    ) -> None:
+        self._spec = spec
+        self._password = password
+        self._client = httpx.AsyncClient(
+            base_url=f"http://{host}",
+            timeout=_TIMEOUT,
+            verify=verify_tls,
+            transport=transport,
+            follow_redirects=True,
+        )
+        self._logged_in = False
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def login(self) -> None:
+        try:
+            page = await self._client.get(self._spec.login_path)
+            _validate_response(page, context=f"GET {self._spec.login_path}")
+            body = _login_body(self._spec, self._password, page.text)
+            resp = await self._client.post(self._spec.login_path, data=body)
+            _validate_response(resp, context=f"POST {self._spec.login_path}")
+        except httpx.HTTPError as exc:
+            raise HttpError(f"web-UI login transport error: {exc}") from exc
+        _check_authed(self._spec, self._client.cookies)
+        self._logged_in = True
+
+    async def get_page(self, path: str) -> str:
+        if not self._logged_in:
+            await self.login()
+        try:
+            resp = await self._client.get(path)
+        except httpx.HTTPError as exc:
+            raise HttpError(f"GET {path} transport error: {exc}") from exc
+        _validate_response(resp, context=f"GET {path}", path=path)
+        return resp.text
+
+    async def post_form(self, path: str, data: dict[str, str]) -> str:
+        if not self._logged_in:
+            await self.login()
+        try:
+            resp = await self._client.post(path, data=data)
+        except httpx.HTTPError as exc:
+            raise HttpError(f"POST {path} transport error: {exc}") from exc
+        _validate_response(resp, context=f"POST {path}")
+        return resp.text
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

netgear_switch/transport/sync/__init__.py

@@ -0,0 +1 @@
+"""Synchronous SNMP transport implementations."""