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

netgear_switch/transport/sync/nsdp_udp.py

@@ -0,0 +1,109 @@
+"""Synchronous NSDP UDP transport (stdlib sockets only).
+
+Binds a UDP client port and exchanges one request/response datagram with the
+switch over unicast (the ``query_ip`` pattern — preferred over broadcast
+discovery for a known host). ``client_port`` defaults to the real NSDP client
+port 63321, but the virtual face lets tests pass ``client_port=0`` to bind an
+unprivileged ephemeral port on loopback (so no root/CAP_NET_BIND_SERVICE and no
+SO_BINDTODEVICE are needed under test). Errors (timeout / malformed / bad
+password) surface as ``NsdpError``, never silently.
+"""
+from __future__ import annotations
+
+import socket
+from typing import TYPE_CHECKING, Any
+
+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 collections.abc import Callable
+
+    from ...protocols.nsdp.protocol import Tag, TLVEntry
+
+_DUMMY_MAC = b"\x00\x00\x00\x00\x00\x01"
+_BROADCAST_MAC = b"\x00" * 6
+
+
+class UdpNsdpClient:
+    """Sync 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,
+        sock_factory: Callable[..., Any] = socket.socket,
+    ) -> None:
+        self.host = host
+        self._interface = interface
+        self._client_port = client_port
+        self._server_port = server_port
+        self._timeout = timeout
+        self._sock_factory = sock_factory
+        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
+
+    def _exchange(self, request: NSDPPacket) -> NSDPPacket:
+        sock = self._sock_factory(socket.AF_INET, socket.SOCK_DGRAM)
+        try:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            if self._interface is not None:
+                sock.setsockopt(
+                    socket.SOL_SOCKET,
+                    socket.SO_BINDTODEVICE,
+                    self._interface.encode() + b"\0",
+                )
+            sock.bind(("", self._client_port))
+            sock.settimeout(self._timeout)
+            sock.sendto(request.encode(), (self.host, self._server_port))
+            try:
+                data, _addr = sock.recvfrom(4096)
+            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
+        finally:
+            sock.close()
+
+    def read(self, tags: list[Tag]) -> NSDPPacket:
+        req = build_read_request(
+            self._client_mac, _BROADCAST_MAC, self._next_seq(), tags
+        )
+        resp = self._exchange(req)
+        if resp.op != Op.READ_RESPONSE:
+            raise NsdpError(f"expected READ_RESPONSE from {self.host}, got {resp.op}")
+        return resp
+
+    def write(self, tlvs: list[TLVEntry], *, password: str) -> NSDPPacket:
+        req = build_write_request(
+            self._client_mac, _BROADCAST_MAC, self._next_seq(), password, tlvs
+        )
+        resp = 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/sync/snmp_netsnmp_cli.py

@@ -0,0 +1,257 @@
+"""Synchronous SNMP v2c client over the net-snmp CLI tools (subprocess).
+
+No Python SNMP package is used. The net-snmp binaries (snmpget/snmpbulkwalk)
+are a system requirement — install the OS `snmp` package
+(`apt-get install -y snmp`). Args are passed as a list; shell is never used.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from typing import TYPE_CHECKING, Any, Protocol
+
+from ...protocols.snmp.client import SnmpError, SnmpRow
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    from ...protocols.snmp.write import SetVarbind
+
+# -On numeric OIDs, -Oe enums-as-numbers, -OU no units, -Ln no stderr logging.
+_OUTPUT_FLAGS = ("-On", "-Oe", "-OU", "-Ln")
+
+# Type tokens net-snmp prints for integer-family values.
+_INT_TYPES = frozenset(
+    {
+        "INTEGER",
+        "Integer32",
+        "Gauge32",
+        "Gauge",
+        "Unsigned32",
+        "Counter32",
+        "Counter64",
+        "Counter",
+    }
+)
+
+_ABSENT_MARKERS = (
+    "no such object",
+    "no such instance",
+)
+
+# Benign terminator snmpbulkwalk appends once a walk reaches the end of the
+# agent's MIB tree. Not an error: skip the line and return the rows already
+# parsed so far.
+_END_OF_MIB_MARKERS = (
+    "no more variables left in this mib view",
+    "past the end of the mib tree",
+)
+
+_TIMETICKS_RE = re.compile(r"\((\d+)\)")
+
+
+def _format_set_value(vb: SetVarbind) -> str:
+    """Render a SetVarbind value as the string snmpset expects for its type.
+
+    ``x`` (hex/octets) is emitted as lowercase hex digits; every other type is
+    stringified directly (net-snmp parses ``i``/``u``/``s``/``a`` from text).
+    """
+    if vb.type_letter == "x":
+        data = (
+            vb.value
+            if isinstance(vb.value, bytes)
+            else str(vb.value).encode("latin-1")
+        )
+        return data.hex()
+    return str(vb.value)
+
+
+class _CompletedProcess(Protocol):
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+def _which(binary: str) -> str:
+    """Return the resolved path to a net-snmp binary or raise SnmpError."""
+    path = shutil.which(binary)
+    if path is None:
+        raise SnmpError(
+            f"net-snmp not installed: {binary!r} is not on PATH. "
+            "Install the `snmp` package (e.g. `apt-get install -y snmp`)."
+        )
+    return path
+
+
+def _normalize(snmp_type: str, value: str) -> int | str | bytes:
+    """Normalize one net-snmp scalar value to a plain Python value.
+
+    Mirrors the pysnmp client (Task 11) so SnmpRow values are transport-equal.
+    """
+    if snmp_type in _INT_TYPES:
+        try:
+            return int(value)
+        except ValueError as exc:
+            raise SnmpError(f"non-integer {snmp_type} value {value!r}") from exc
+    if snmp_type == "Timeticks":
+        m = _TIMETICKS_RE.search(value)
+        if m is None:
+            raise SnmpError(f"unparsable Timeticks value {value!r}")
+        return int(m.group(1))
+    if snmp_type == "STRING":
+        if len(value) >= 2 and value[0] == '"' and value[-1] == '"':
+            return value[1:-1]
+        return value
+    if snmp_type == "OID":
+        return value.lstrip(".")
+    # IpAddress and any other textual type: plain string.
+    return value
+
+
+def _split_typed(rest: str) -> tuple[str, str] | None:
+    """If `rest` looks like `<TYPE>: <value>` (or `<TYPE>:` with no value),
+    return `(snmp_type, value)`. Otherwise return None.
+
+    This is checked *before* any marker text so a STRING value that merely
+    contains marker words (e.g. `STRING: "no such object test"`) is always
+    parsed as a normal typed value, never mistaken for a marker line.
+    """
+    if ": " in rest:
+        snmp_type, value = rest.split(": ", 1)
+        return snmp_type.strip(), value.strip()
+    if rest.endswith(":"):
+        return rest[:-1].strip(), ""
+    return None
+
+
+def parse_netsnmp_lines(text: str) -> list[SnmpRow]:
+    """Parse `snmpget`/`snmpbulkwalk` output (-On -Oe -OU -Ln) into SnmpRows.
+
+    Raises SnmpError on a "No Such Object/Instance" line — an absent OID is
+    surfaced early, never returned as an empty/None row. The benign
+    "No more variables left in this MIB View .../ past the end of the MIB
+    tree" terminator that snmpbulkwalk appends at the end of a successful
+    walk is skipped rather than treated as an error, so previously parsed
+    rows are still returned. Multi-line Hex-STRING continuations are joined
+    into one bytes value.
+    """
+    rows: list[SnmpRow] = []
+    pending_oid: str | None = None
+    pending_hex: list[str] = []
+
+    def flush_hex() -> None:
+        nonlocal pending_oid
+        if pending_oid is not None:
+            data = bytes(
+                int(tok, 16) for chunk in pending_hex for tok in chunk.split()
+            )
+            rows.append(SnmpRow(pending_oid, data, "Hex-STRING"))
+            pending_oid = None
+            pending_hex.clear()
+
+    for raw in text.splitlines():
+        if not raw.strip():
+            continue
+        if " = " not in raw:
+            if pending_oid is not None:  # Hex-STRING continuation line
+                pending_hex.append(raw.strip())
+            continue
+        flush_hex()
+        oid_part, rest = raw.split(" = ", 1)
+        oid = oid_part.strip().lstrip(".")
+        rest = rest.strip()
+        if rest in ('""', ""):
+            rows.append(SnmpRow(oid, "", "STRING"))
+            continue
+        typed = _split_typed(rest)
+        if typed is not None:
+            snmp_type, value = typed
+            if snmp_type == "Hex-STRING":
+                pending_oid = oid
+                pending_hex = [value]
+                continue
+            rows.append(SnmpRow(oid, _normalize(snmp_type, value), snmp_type))
+            continue
+        rest_lower = rest.lower()
+        if any(marker in rest_lower for marker in _END_OF_MIB_MARKERS):
+            continue
+        if any(marker in rest_lower for marker in _ABSENT_MARKERS):
+            raise SnmpError(f"absent OID in net-snmp output: {oid} = {rest}")
+        raise SnmpError(f"unrecognized net-snmp output line: {oid} = {rest}")
+    flush_hex()
+    return rows
+
+
+class NetsnmpCliClient:
+    """Read-only sync SNMP client shelling out to net-snmp CLI tools."""
+
+    def __init__(
+        self,
+        host: str,
+        community: str,
+        *,
+        timeout: int = 10,
+        retries: int = 1,
+        runner: Callable[..., _CompletedProcess] = subprocess.run,
+    ) -> None:
+        self.host = host
+        self.community = community
+        self.timeout = timeout
+        self.retries = retries
+        self._runner = runner
+
+    def _base_args(self, binary: str) -> list[str]:
+        return [
+            _which(binary),
+            "-v2c",
+            "-c",
+            self.community,
+            *_OUTPUT_FLAGS,
+            "-t",
+            str(self.timeout),
+            "-r",
+            str(self.retries),
+        ]
+
+    def get(self, oids: list[str]) -> list[SnmpRow]:
+        if not oids:
+            return []
+        argv = [*self._base_args("snmpget"), self.host, *oids]
+        return self._invoke(argv)
+
+    def walk(self, base_oid: str) -> list[SnmpRow]:
+        argv = [*self._base_args("snmpbulkwalk"), self.host, base_oid]
+        return self._invoke(argv)
+
+    def set(self, varbind: SetVarbind) -> None:
+        self.set_many([varbind])
+
+    def set_many(self, varbinds: list[SetVarbind]) -> None:
+        if not varbinds:
+            return
+        triples: list[str] = []
+        for vb in varbinds:
+            triples += [vb.oid, vb.type_letter, _format_set_value(vb)]
+        argv = [*self._base_args("snmpset"), self.host, *triples]
+        # _invoke raises SnmpError on non-zero exit or any stderr (commitFailed,
+        # noSuchName, wrong type). The echoed varbinds it parses are discarded.
+        self._invoke(argv)
+
+    def _invoke(self, argv: Sequence[str]) -> list[SnmpRow]:
+        kwargs: dict[str, Any] = {
+            "capture_output": True,
+            "text": True,
+            "check": False,
+        }
+        try:
+            proc = self._runner(list(argv), **kwargs)
+        except OSError as exc:  # binary vanished between _which and run
+            raise SnmpError(f"failed to run {argv[0]!r}: {exc}") from exc
+        stderr = (proc.stderr or "").strip()
+        if proc.returncode != 0 or stderr:
+            raise SnmpError(
+                f"{argv[0]} exited {proc.returncode} for {self.host}: "
+                f"{stderr or 'unknown error'}"
+            )
+        return parse_netsnmp_lines(proc.stdout)

netgear_switch/virtual/__init__.py

@@ -0,0 +1,8 @@
+"""Virtual switch: an in-memory device state plus protocol "faces" onto it.
+
+``VirtualSwitchState`` (state.py) is the one authoritative in-memory device
+state; ``seed.py`` hand-authors a realistic instance for a given model; the
+``faces`` subpackage (Task 15+) serves that state over a real protocol (e.g.
+SNMP) so both transport clients can be tested against it end-to-end.
+"""
+from __future__ import annotations

netgear_switch/virtual/faces/__init__.py

@@ -0,0 +1,2 @@
+"""Protocol faces onto a VirtualSwitchState (e.g. an SNMP agent, Task 15)."""
+from __future__ import annotations

netgear_switch/virtual/faces/http.py

@@ -0,0 +1,164 @@
+"""A real ``http.server`` web-UI face serving a ``VirtualSwitchState``.
+
+Binds a ``ThreadingHTTPServer`` to an ephemeral TCP port on ``127.0.0.1`` and
+serves the login CGI + read/write CGI pages from device state via
+``virtual.web``. Both httpx transport clients (sync + async) are exercised
+end-to-end against it with no hardware.
+
+A real switch never fabricates a 200 for a capability it doesn't have, so
+this face 404s any request whose path is not one of this model's *populated*
+``HttpModelSpec`` fields, before ever calling into ``virtual.web`` — that
+module's ``render_page`` has a deliberately permissive catch-all (see its
+docstring) that is only safe to reach for a path this spec actually
+advertises.
+
+Teardown is deterministic: ``stop()`` calls ``shutdown()`` (unblocks
+``serve_forever``), joins the server thread, then ``server_close()`` closes the
+listening socket — so nothing leaks under ``-W error::ResourceWarning``.
+"""
+from __future__ import annotations
+
+import dataclasses
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import TYPE_CHECKING
+from urllib.parse import parse_qs
+
+from ...protocols.http.crypt import merge_hash_md5
+from ...protocols.http.endpoints import HttpModelSpec, LoginScheme
+from .. import web
+
+if TYPE_CHECKING:
+    from ..state import VirtualSwitchState
+
+# Every path-shaped field an HttpModelSpec may populate, other than
+# login_path (handled separately as the login handshake). A model that
+# leaves one of these None does not serve that endpoint at all.
+#
+# Derived from the dataclass itself (rather than hand-maintained) so a future
+# spec field ending in "_path" is picked up automatically instead of silently
+# 404ing forever; login_path is filtered back out since it is handled by the
+# login handshake, not the known-path gate.
+_PATH_FIELDS: tuple[str, ...] = tuple(
+    f.name
+    for f in dataclasses.fields(HttpModelSpec)
+    if f.name.endswith("_path") and f.name != "login_path"
+)
+
+
+def _known_paths(spec: HttpModelSpec) -> set[str]:
+    """The set of paths ``spec`` actually serves (populated fields only)."""
+    return {
+        value
+        for name in _PATH_FIELDS
+        if (value := getattr(spec, name)) is not None
+    }
+
+
+class VirtualHttpFace:
+    """A ``ThreadingHTTPServer`` web-UI face serving a ``VirtualSwitchState``."""
+
+    def __init__(
+        self,
+        state: VirtualSwitchState,
+        spec: HttpModelSpec,
+        *,
+        host: str = "127.0.0.1",
+        password: str = "password",
+        rand: str = "1234",
+    ) -> None:
+        self.state = state
+        self.spec = spec
+        self.host = host
+        self.password = password
+        self.rand = rand
+        self._known_paths = _known_paths(spec)
+        self._server: ThreadingHTTPServer | None = None
+        self._thread: threading.Thread | None = None
+        self._cookie = f"{spec.cookie_name}=virtualsid"
+        # ThreadingHTTPServer runs one thread per request; do_GET/do_POST
+        # mutate shared VirtualSwitchState via web.render_page/apply_form
+        # with no lock of their own, so two overlapping requests (e.g. a
+        # sync and an async client hitting the same VirtualSwitch) would
+        # race. Serialize just the render/apply critical section on this
+        # single lock rather than the whole request.
+        self._lock = threading.Lock()
+
+    def start(self) -> int:
+        face = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, *_args: object) -> None:  # silence stderr
+                return
+
+            def _body(self) -> dict[str, str]:
+                length = int(self.headers.get("Content-Length", "0"))
+                raw = self.rfile.read(length).decode() if length else ""
+                return {k: v[0] for k, v in parse_qs(raw).items()}
+
+            def _send(
+                self, text: str, status: int = 200, *, cookie: bool = False
+            ) -> None:
+                data = text.encode()
+                self.send_response(status)
+                self.send_header("Content-Type", "text/html")
+                self.send_header("Content-Length", str(len(data)))
+                if cookie:
+                    self.send_header("Set-Cookie", f"{face._cookie}; path=/")
+                self.end_headers()
+                self.wfile.write(data)
+
+            def do_GET(self) -> None:
+                path = self.path.split("?", 1)[0]
+                if path == face.spec.login_path:
+                    self._send(web.render_login(face.rand))
+                    return
+                if path not in face._known_paths:
+                    self._send("<html><body>Not Found</body></html>", 404)
+                    return
+                with face._lock:
+                    page = web.render_page(face.state, face.spec, path, {})
+                self._send(page)
+
+            def do_POST(self) -> None:
+                path = self.path.split("?", 1)[0]
+                form = self._body()
+                if path == face.spec.login_path:
+                    ok = face._login_response(form) == "OK"
+                    self._send("OK" if ok else "Login failed", cookie=ok)
+                    return
+                if path not in face._known_paths:
+                    self._send("<html><body>Not Found</body></html>", 404)
+                    return
+                with face._lock:
+                    web.apply_form(face.state, face.spec, path, form)
+                    page = web.render_page(face.state, face.spec, path, form)
+                self._send(page)
+
+        server = ThreadingHTTPServer((self.host, 0), Handler)
+        self._server = server
+        self._thread = threading.Thread(
+            target=server.serve_forever, name="virtual-http-face", daemon=True
+        )
+        self._thread.start()
+        return int(server.server_address[1])
+
+    def _login_response(self, form: dict[str, str]) -> str:
+        field = self.spec.password_field
+        supplied = form.get(field, "")
+        if self.spec.scheme is LoginScheme.CHEETAH_FORM:
+            ok = supplied == self.password
+        else:
+            ok = supplied == merge_hash_md5(self.password, self.rand)
+        return "OK" if ok else "Login failed"
+
+    def stop(self) -> None:
+        """Stop the serve thread and close the listening socket deterministically."""
+        if self._server is not None:
+            self._server.shutdown()
+        if self._thread is not None:
+            self._thread.join(timeout=5)
+            self._thread = None
+        if self._server is not None:
+            self._server.server_close()
+            self._server = None

netgear_switch/virtual/faces/mibview.py

@@ -0,0 +1,92 @@
+# src/netgear_switch/virtual/faces/mibview.py
+"""Pure OID responder over VirtualSwitchState.oid_map().
+
+No pysnmp, no network: a sorted (oid_tuple, snmp_type, value) list answering
+exact-match GET and lexicographic GETNEXT with bisect. Task 15 wires this into
+the real pysnmp command responder.
+"""
+from __future__ import annotations
+
+import bisect
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..state import VirtualSwitchState
+
+_Entry = tuple[tuple[int, ...], str, str]  # (oid_tuple, snmp_type, value)
+
+
+def _oid_to_tuple(oid: str) -> tuple[int, ...]:
+    return tuple(int(part) for part in oid.lstrip(".").split("."))
+
+
+class StateMibView:
+    """Sorted view of a switch's OID map supporting GET and GETNEXT."""
+
+    def __init__(self, state: VirtualSwitchState) -> None:
+        self._state = state
+        self._load()
+
+    def _load(self) -> None:
+        entries: list[_Entry] = [
+            (_oid_to_tuple(oid), snmp_type, value)
+            for oid, (snmp_type, value) in self._state.oid_map().items()
+        ]
+        entries.sort(key=lambda e: e[0])
+        self._entries = entries
+        self._oids = [e[0] for e in entries]  # parallel key list for bisect
+
+    def get(self, oid: tuple[int, ...]) -> _Entry | None:
+        i = bisect.bisect_left(self._oids, oid)
+        if i < len(self._oids) and self._oids[i] == oid:
+            return self._entries[i]
+        return None  # caller maps None -> NoSuchInstance
+
+    def get_next(self, oid: tuple[int, ...]) -> _Entry | None:
+        # bisect_right -> index of the first OID strictly greater than `oid`.
+        i = bisect.bisect_right(self._oids, oid)
+        if i < len(self._oids):
+            return self._entries[i]
+        return None  # caller maps None -> endOfMibView
+
+    def rebuild(self) -> None:
+        """Recompute the sorted view from current state (call after a write)."""
+        self._load()
+
+    def apply_write(self, oid: str, value: int | bytes | str) -> None:
+        """Mutate the underlying state then rebuild so reads reflect the write."""
+        self._state.apply_write(oid, value)
+        self.rebuild()
+
+    def apply_write_uncommitted(self, oid: str, value: int | bytes | str) -> None:
+        """Mutate the underlying state WITHOUT rebuilding the sorted view.
+
+        For an atomic multi-varbind SET (``faces/snmp.py``'s
+        ``write_variables``): the (relatively expensive) ``rebuild()`` is
+        deferred until the whole PDU has committed successfully, once, rather
+        than once per varbind. Callers MUST call ``rebuild()`` themselves
+        once every varbind in the PDU has applied without error.
+        """
+        self._state.apply_write(oid, value)
+
+    def snapshot_state(self) -> VirtualSwitchState:
+        """Snapshot the underlying state, for atomic multi-varbind SET rollback.
+
+        See ``VirtualSwitchState.snapshot``/``restore_state``.
+        """
+        return self._state.snapshot()
+
+    def restore_state(self, snapshot: VirtualSwitchState) -> None:
+        """Restore the underlying state in place from a prior
+        ``snapshot_state()`` result, discarding any writes applied since.
+
+        The sorted view itself needs no rebuild after a restore: if the
+        caller took the snapshot before making any changes and only ever
+        reaches this on a failed atomic SET, the state (and thus the view)
+        is back to exactly what it was before that SET began.
+        """
+        self._state.restore(snapshot)
+
+    def is_writable_oid(self, oid: str) -> bool:
+        """Passthrough to ``VirtualSwitchState.is_writable_oid`` (see there)."""
+        return self._state.is_writable_oid(oid)