lvi-api-client 0.2.1__tar.gz → 0.2.4__tar.gz

{lvi_api_client-0.2.1 → lvi_api_client-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lvi-api-client
-Version: 0.2.1
+Version: 0.2.4
 Summary: LogicVein API Client Library
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown

lvi_api_client-0.2.4/VERSION

@@ -0,0 +1 @@
+0.2.4

{lvi_api_client-0.2.1 → lvi_api_client-0.2.4}/src/logicvein/lvi_api_client.py

@@ -3863,18 +3863,40 @@ class LogicVeinAPIClient:
         return False
 
     def associate_monitor_set(self, set_id: int, host_queries: List[str]) -> bool:
-        """Associate a monitor set with device(s).
+        """Deploy a monitor set to the devices that match every one of the given queries.
 
-        Calls Collection.associateMonitorSet. Returns null on success.
+        Calls Collection.associateMonitorSet. The server answers null whether or not any device
+        matched, so check :meth:`get_monitors_for_host` to know what was deployed.
+
+        The server combines the queries with AND, so one entry for each device matches none of
+        them. Name several devices in one entry, each with its network:
+        ``['ipCsv=192.0.2.1@Default,192.0.2.2@Default']``. An address with no network of its own is
+        not looked up in the network named after a later one. Another query can narrow it:
+        ``['ipCsv=192.0.2.1@Default,192.0.2.2@Default', 'ipAddress=192.0.2.1']``.
+
+        With no queries the server deploys to every device, so that is refused here rather than
+        passed on from an empty list.
 
         Args:
             set_id (int): The ID of the monitor set to associate.
-            host_queries (List[str]): List of host query strings in format 'ipCsv=IP@NetworkName'.
-                Example: ['ipCsv=192.168.1.6@Default']
+            host_queries (List[str]): The queries, at least one, none of them blank, and at most
+                one of them an ``ipCsv`` query.
 
         Returns:
-            bool: True if successful (result is null), otherwise False.
-        """
+            bool: True if the server answered without an error, otherwise False. This does not
+            mean any device matched.
+
+        Raises:
+            ValueError: If there is no query, a query is blank, or more than one is ``ipCsv``.
+                Nothing is sent.
+        """
+        if not host_queries or any(not query.strip() for query in host_queries):
+            raise ValueError("host_queries needs at least one query and no blank ones: none would match every device")
+        if sum(query.strip().startswith("ipCsv=") for query in host_queries) > 1:
+            raise ValueError(
+                "Queries combine with AND, so several ipCsv queries cannot name several devices. "
+                "List them in one: ipCsv=IP@Network,IP@Network"
+            )
         response = self.call("Collection.associateMonitorSet", setId=set_id, hostQueries=host_queries)
 
         if response and isinstance(response, dict) and "result" in response and response["result"] in (None, "None"):
@@ -3887,14 +3909,22 @@ class LogicVeinAPIClient:
         Calls Collection.addMonitorsToSet. The setId must be provided both as a top-level
         parameter and within each monitor object. Returns the saved monitors with assigned IDs.
 
+        This always adds: the server stores a new monitor even for a name already in the
+        set, or with the ID of an existing monitor, and leaves the old one as it was. Use
+        :meth:`save_monitor` to change one.
+
+        The server answers success but stores neither ``disabled`` nor ``hostSpecific`` as true,
+        here or in :meth:`save_monitor`. To stop a monitor on a device, use
+        :meth:`disable_monitor_for_host`.
+
         Each monitor object should have:
             {
                 "monitorId": int - Use -1 for new monitors; assigned ID returned in response,
                 "monitorName": str - Monitor name,
                 "setId": int - Must match set_id,
                 "monitorType": str - Type (e.g. "snmp", "tcp", "icmp", "telegraf", "web", "catchalltrap"),
-                "disabled": bool - Whether the monitor is disabled,
-                "hostSpecific": bool - Whether the monitor is host-specific,
+                "disabled": bool - Stored as false whatever is sent,
+                "hostSpecific": bool - Stored as false whatever is sent,
                 "managedNetworks": list[str] - Networks the monitor belongs to,
                 "retentionPolicy": str - Data retention (e.g. "THREE_MONTHS"),
                 "json": dict - Monitor-type-specific config (OIDs, pollingPeriod, table, triggers, etc.),
@@ -3905,7 +3935,7 @@ class LogicVeinAPIClient:
 
         Args:
             set_id (int): The monitor set ID to add monitors to.
-            monitors (List[Dict[str, Any]]): List of monitor objects to add/update.
+            monitors (List[Dict[str, Any]]): List of monitor objects to add.
 
         Returns:
             List[Dict[str, Any]]: List of saved monitor objects with assigned monitorIds.
@@ -3936,6 +3966,222 @@ class LogicVeinAPIClient:
             return True
         return False
 
+    def create_monitor_set(
+        self, set_name: str, managed_networks: List[str], smart_set: bool = False
+    ) -> Optional[Dict[str, Any]]:
+        """Create a monitor set.
+
+        A name already taken in those networks makes the server answer HTTP 500, which
+        raises, and stores nothing.
+
+        Args:
+            set_name (str): The set's name. Use :meth:`is_monitor_set_name_unique` to check it first.
+            managed_networks (List[str]): The networks the set belongs to, at least one.
+            smart_set (bool): Whether this is a smart set, one applied automatically to newly
+                discovered devices.
+
+        Returns:
+            Dict[str, Any]: The saved set (``setId``, ``setName``, ``smartSet``,
+            ``managedNetworks``), or None on failure.
+
+        Raises:
+            ValueError: If no network is given. An empty list was not tried against a
+                server, as a failed rule set save with no networks leaves a row that
+                cannot be removed.
+        """
+        if not managed_networks:
+            raise ValueError("A monitor set needs at least one managed network")
+        return self._save_monitor_set(
+            {"setId": -1, "setName": set_name, "smartSet": smart_set, "managedNetworks": managed_networks}
+        )
+
+    def update_monitor_set(
+        self,
+        set_id: int,
+        set_name: Optional[str] = None,
+        managed_networks: Optional[List[str]] = None,
+        smart_set: Optional[bool] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Change a monitor set, keeping what is not given.
+
+        Args:
+            set_id (int): The ID of the set.
+            set_name (Optional[str]): A new name, or None to keep it.
+            managed_networks (Optional[List[str]]): New networks, at least one, or None to keep them.
+            smart_set (Optional[bool]): Whether it is a smart set, or None to keep it.
+
+        Returns:
+            Dict[str, Any]: The saved set, or None on failure.
+
+        Raises:
+            ValueError: If the set does not exist, or an empty list of networks is given.
+        """
+        if managed_networks is not None and not managed_networks:
+            raise ValueError("A monitor set needs at least one managed network")
+        monitor_set = self.get_monitor_set(set_id)
+        if not monitor_set:
+            raise ValueError(f"Monitor set {set_id} does not exist")
+        changes = {"setName": set_name, "managedNetworks": managed_networks, "smartSet": smart_set}
+        return self._save_monitor_set({**monitor_set, **{k: v for k, v in changes.items() if v is not None}})
+
+    def _save_monitor_set(self, monitor_set: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """Save a monitor set record.
+
+        Args:
+            monitor_set (Dict[str, Any]): The whole record. A ``setId`` of -1 creates a set.
+
+        Returns:
+            Dict[str, Any]: The saved set, or None on failure.
+        """
+        response = self.call("Collection.saveMonitorSet", monitorSet=monitor_set)
+        if response and isinstance(response, dict) and "result" in response:
+            return response["result"]
+        return None
+
+    def delete_monitor_sets(self, set_ids: List[int]) -> bool:
+        """Delete monitor sets, with their monitors.
+
+        This also takes those monitors off the devices they were deployed to. The server
+        answers success for a set that does not exist, so True does not show that one did.
+
+        Args:
+            set_ids (List[int]): The IDs of the sets to delete.
+
+        Returns:
+            bool: True if successful (result is null), otherwise False.
+        """
+        response = self.call("Collection.deleteMonitorSets", setIds=set_ids)
+        return bool(response and isinstance(response, dict) and "result" in response and response["result"] is None)
+
+    def is_monitor_set_name_unique(self, set_name: str, managed_networks: List[str], ignore_set_id: int = -1) -> bool:
+        """Check whether a monitor set name is free in some networks.
+
+        Args:
+            set_name (str): The name to check.
+            managed_networks (List[str]): The networks to check it in.
+            ignore_set_id (int): A set to leave out, such as the one being renamed. -1 for none.
+
+        Returns:
+            bool: True if the name is free.
+
+        Raises:
+            ValueError: If the server's answer is not true or false.
+        """
+        response = self.call(
+            "Collection.isMonitorSetNameUnique",
+            setName=set_name,
+            managedNetworks=managed_networks,
+            ignoreSetId=ignore_set_id,
+        )
+        unique = response.get("result") if isinstance(response, dict) else None
+        if not isinstance(unique, bool):
+            raise ValueError(f"Collection.isMonitorSetNameUnique did not answer true or false for {set_name}")
+        return unique
+
+    def save_monitor(self, monitor: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """Update a monitor in place.
+
+        The monitor keeps its ID, and a device it is deployed to gets the change. A change to
+        ``disabled`` or ``isHostSpecific`` is answered with success and not stored, and a changed
+        ``monitorType`` is answered with HTTP 500, which raises.
+
+        Args:
+            monitor (Dict[str, Any]): The whole record as :meth:`get_monitors_for_set` returns
+                it, with the changes made.
+
+        Returns:
+            Dict[str, Any]: The saved monitor, or None on failure.
+        """
+        response = self.call("Collection.saveMonitor", monitor=monitor)
+        if response and isinstance(response, dict) and "result" in response:
+            return response["result"]
+        return None
+
+    def get_monitors_for_host(self, device_uuid: str, network: str) -> List[Dict[str, Any]]:
+        """Get the monitors deployed to a device.
+
+        Args:
+            device_uuid (str): UUID of the device.
+            network (str): Network the device belongs to.
+
+        Returns:
+            List[Dict[str, Any]]: The monitors, each with ``monitorId``, ``monitorName``, ``setId``
+            and ``disabled``, which is the state on this device. The list is empty only when the
+            server says the device has none,
+            which it also says for a device that does not exist.
+
+        Raises:
+            ValueError: If the server's answer is not a list. Callers check this list before
+                deploying, so a failed read must not look like no monitors.
+        """
+        response = self.call("Collection.getMonitorsForHost", uuid=device_uuid, network=network)
+        monitors = response.get("result") if isinstance(response, dict) else None
+        if not isinstance(monitors, list):
+            raise ValueError(f"Collection.getMonitorsForHost did not return a list for device {device_uuid}")
+        return monitors
+
+    def disable_monitor_for_host(self, monitor_id: int, device_uuid: str, network: str) -> bool:
+        """Stop a deployed monitor on one device, leaving it deployed and other devices as they are.
+
+        Deploying the set again keeps the monitor disabled, and repeating this does no harm.
+
+        Args:
+            monitor_id (int): ID of the monitor.
+            device_uuid (str): UUID of the device.
+            network (str): Network the device belongs to.
+
+        Returns:
+            bool: True if the device now shows the monitor disabled. False if it does not, as for
+            a monitor not deployed to that device.
+
+        Raises:
+            ValueError: If the device's monitors cannot be read afterwards.
+        """
+        return self._set_monitor_disabled_for_host("disableMonitorForHost", monitor_id, device_uuid, network, True)
+
+    def enable_monitor_for_host(self, monitor_id: int, device_uuid: str, network: str) -> bool:
+        """Start a monitor again on a device where it was disabled.
+
+        Repeating this does no harm.
+
+        Args:
+            monitor_id (int): ID of the monitor.
+            device_uuid (str): UUID of the device.
+            network (str): Network the device belongs to.
+
+        Returns:
+            bool: True if the device now shows the monitor enabled. False if it does not, as for
+            a monitor not deployed to that device.
+
+        Raises:
+            ValueError: If the device's monitors cannot be read afterwards.
+        """
+        return self._set_monitor_disabled_for_host("enableMonitorForHost", monitor_id, device_uuid, network, False)
+
+    def _set_monitor_disabled_for_host(
+        self, method: str, monitor_id: int, device_uuid: str, network: str, disabled: bool
+    ) -> bool:
+        """Call a per-device enable or disable, and read back whether it took effect.
+
+        The server answers null to these whatever happens, even for an unknown monitor or
+        device or the wrong network, so only the device's own monitors can show the outcome.
+
+        Args:
+            method (str): The method's name under Collection.
+            monitor_id (int): ID of the monitor.
+            device_uuid (str): UUID of the device.
+            network (str): Network the device belongs to.
+            disabled (bool): The state the call should leave.
+
+        Returns:
+            bool: Whether the device shows the monitor in that state.
+        """
+        self.call(f"Collection.{method}", monitorId=monitor_id, uuid=device_uuid, network=network)
+        return any(
+            monitor.get("monitorId") == monitor_id and monitor.get("disabled") is disabled
+            for monitor in self.get_monitors_for_host(device_uuid, network)
+        )
+
     def validate_monitor_sets_against_device(
         self, monitor_set_ids: List[int], host_queries: List[str]
     ) -> Dict[str, Any]:

{lvi_api_client-0.2.1 → lvi_api_client-0.2.4}/src/lvi_api_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lvi-api-client
-Version: 0.2.1
+Version: 0.2.4
 Summary: LogicVein API Client Library
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown

{lvi_api_client-0.2.1 → lvi_api_client-0.2.4}/tests/test_server_request_shapes.py

@@ -329,6 +329,96 @@ class TestTriggers:
         assert server.sent("Scheduler.deleteTrigger") == {"triggerId": 3}
 
 
+class TestMonitorSets:
+    SET = {"setId": 5, "setName": "s1", "smartSet": False, "managedNetworks": ["n1"]}
+
+    def test_a_new_set_is_saved_with_an_id_of_minus_one(self, connect):
+        client, server = connect({"Collection.saveMonitorSet": self.SET})
+        assert client.create_monitor_set("s1", ["n1"]) == self.SET
+        assert server.sent("Collection.saveMonitorSet") == {
+            "monitorSet": {"setId": -1, "setName": "s1", "smartSet": False, "managedNetworks": ["n1"]}
+        }
+
+    def test_a_new_smart_set_says_so(self, connect):
+        client, server = connect({"Collection.saveMonitorSet": self.SET})
+        client.create_monitor_set("s1", ["n1"], smart_set=True)
+        assert server.sent("Collection.saveMonitorSet")["monitorSet"]["smartSet"] is True
+
+    def test_a_new_set_with_no_networks_sends_nothing(self, connect):
+        client, server = connect()
+        with pytest.raises(ValueError):
+            client.create_monitor_set("s1", [])
+        assert server.requests == []
+
+    def test_an_update_keeps_what_it_is_not_given(self, connect):
+        client, server = connect({"Collection.getMonitorSet": self.SET, "Collection.saveMonitorSet": self.SET})
+        client.update_monitor_set(5, set_name="s2")
+        assert server.sent("Collection.saveMonitorSet") == {"monitorSet": {**self.SET, "setName": "s2"}}
+
+    def test_an_update_can_clear_smart_set(self, connect):
+        stored = {**self.SET, "smartSet": True}
+        client, server = connect({"Collection.getMonitorSet": stored, "Collection.saveMonitorSet": self.SET})
+        client.update_monitor_set(5, smart_set=False)
+        assert server.sent("Collection.saveMonitorSet")["monitorSet"]["smartSet"] is False
+
+    @pytest.mark.parametrize(
+        "stored, args",
+        [
+            pytest.param(None, {"set_name": "s2"}, id="no such set"),
+            pytest.param(SET, {"managed_networks": []}, id="no networks"),
+        ],
+    )
+    def test_an_update_that_cannot_apply_saves_nothing(self, connect, stored, args):
+        client, server = connect({"Collection.getMonitorSet": stored})
+        with pytest.raises(ValueError):
+            client.update_monitor_set(5, **args)
+        assert "Collection.saveMonitorSet" not in [name for name, _ in server.requests]
+
+    @pytest.mark.parametrize("answer, expected", [(None, True), (False, False)])
+    def test_a_delete_is_by_set_ids_and_null_is_success(self, connect, answer, expected):
+        client, server = connect({"Collection.deleteMonitorSets": answer})
+        assert client.delete_monitor_sets([5, 6]) is expected
+        assert server.sent("Collection.deleteMonitorSets") == {"setIds": [5, 6]}
+
+    @pytest.mark.parametrize("answer", [True, False])
+    def test_a_name_check_sends_its_scope_and_returns_the_answer(self, connect, answer):
+        client, server = connect({"Collection.isMonitorSetNameUnique": answer})
+        assert client.is_monitor_set_name_unique("s1", ["n1"], ignore_set_id=5) is answer
+        assert server.sent("Collection.isMonitorSetNameUnique") == {
+            "setName": "s1",
+            "managedNetworks": ["n1"],
+            "ignoreSetId": 5,
+        }
+
+    def test_a_name_check_with_no_answer_raises_rather_than_reading_as_taken(self, connect):
+        client, _ = connect({"Collection.isMonitorSetNameUnique": None})
+        with pytest.raises(ValueError):
+            client.is_monitor_set_name_unique("s1", ["n1"])
+
+    def test_a_monitor_is_saved_as_a_whole_record(self, connect):
+        monitor = {"monitorId": 3, "monitorName": "m1", "setId": 5, "json": {"port": 22}}
+        client, server = connect({"Collection.saveMonitor": monitor})
+        assert client.save_monitor(monitor) == monitor
+        assert server.sent("Collection.saveMonitor") == {"monitor": monitor}
+
+    def test_a_devices_monitors_are_read_by_uuid_and_network(self, connect):
+        rows = [{"monitorId": 3, "monitorName": "m1", "setId": 5}]
+        client, server = connect({"Collection.getMonitorsForHost": rows})
+        assert client.get_monitors_for_host("u1", "n1") == rows
+        assert server.sent("Collection.getMonitorsForHost") == {"uuid": "u1", "network": "n1"}
+
+    def test_a_device_with_no_monitors_gives_an_empty_list(self, connect):
+        client, _ = connect({"Collection.getMonitorsForHost": []})
+        assert client.get_monitors_for_host("u1", "n1") == []
+
+    @pytest.mark.parametrize("answer", [None, {"result": None}, {}, "<html>error</html>"])
+    def test_an_answer_that_is_not_a_list_raises_rather_than_reading_as_no_monitors(self, connect, answer):
+        client, _ = connect()
+        with patch.object(client, "call", return_value=answer):
+            with pytest.raises(ValueError):
+                client.get_monitors_for_host("u1", "n1")
+
+
 class TestCreateRuleSet:
     def test_an_agreeing_document_is_sent_unchanged(self, connect):
         client, server = connect(SAVED)
@@ -453,3 +543,80 @@ class TestCreateRuleSet:
         with pytest.raises(ValueError):
             client.create_rule_set(name, adapter, document, **arguments)
         assert server.requests == []
+
+
+class TestMonitorStateOnADevice:
+    """On a real server these answer null whatever happens, so the device's monitors decide."""
+
+    @pytest.mark.parametrize(
+        "call, method, disabled",
+        [
+            ("disable_monitor_for_host", "Collection.disableMonitorForHost", True),
+            ("enable_monitor_for_host", "Collection.enableMonitorForHost", False),
+        ],
+    )
+    def test_the_request_and_a_read_back_of_the_device(self, connect, call, method, disabled):
+        client, server = connect(
+            {method: None, "Collection.getMonitorsForHost": [{"monitorId": 7, "disabled": disabled}]}
+        )
+        assert getattr(client, call)(7, "u1", "n1") is True
+        assert server.requests == [
+            (method, {"monitorId": 7, "uuid": "u1", "network": "n1"}),
+            ("Collection.getMonitorsForHost", {"uuid": "u1", "network": "n1"}),
+        ]
+
+    @pytest.mark.parametrize(
+        "call, rows",
+        [
+            pytest.param("disable_monitor_for_host", [{"monitorId": 7, "disabled": False}], id="disable did not take"),
+            pytest.param("enable_monitor_for_host", [{"monitorId": 7, "disabled": True}], id="enable did not take"),
+            pytest.param("disable_monitor_for_host", [], id="not on the device"),
+            pytest.param("disable_monitor_for_host", [{"monitorId": 8, "disabled": True}], id="another monitor"),
+            pytest.param(
+                "enable_monitor_for_host", [{"monitorId": 8, "disabled": False}], id="another monitor, enable"
+            ),
+        ],
+    )
+    def test_a_null_answer_is_not_success(self, connect, call, rows):
+        client, _ = connect({"Collection.getMonitorsForHost": rows})
+        assert getattr(client, call)(7, "u1", "n1") is False
+
+    def test_a_failed_read_raises(self, connect):
+        client, _ = connect({"Collection.getMonitorsForHost": None})
+        with pytest.raises(ValueError):
+            client.disable_monitor_for_host(7, "u1", "n1")
+
+
+class TestDeployingASet:
+    """On a real server several ipCsv queries match nothing, and no query matches every device."""
+
+    @pytest.mark.parametrize(
+        "queries",
+        [
+            pytest.param(["ipCsv=192.0.2.1@n1"], id="one device"),
+            pytest.param(["ipCsv=192.0.2.1@n1,192.0.2.2@n1"], id="several devices in one entry"),
+            pytest.param(["ipCsv=192.0.2.1@n1,192.0.2.2@n1", "ipAddress=192.0.2.1"], id="narrowed by another query"),
+            pytest.param(["sysObjectID=1.3.6.1.4.1.9.1.324", "sysDescr=*C2950*"], id="other queries together"),
+        ],
+    )
+    def test_queries_the_server_can_act_on_are_sent_as_given(self, connect, queries):
+        client, server = connect({"Collection.associateMonitorSet": None})
+        assert client.associate_monitor_set(2, queries) is True
+        assert server.sent("Collection.associateMonitorSet") == {"setId": 2, "hostQueries": queries}
+
+    @pytest.mark.parametrize(
+        "queries",
+        [
+            pytest.param([], id="no queries"),
+            pytest.param([""], id="a blank query"),
+            pytest.param(["  "], id="a query of spaces"),
+            pytest.param(["ipCsv=192.0.2.1@n1", ""], id="a blank among others"),
+            pytest.param(["ipCsv=192.0.2.1@n1", "ipCsv=192.0.2.2@n1"], id="one entry per device"),
+            pytest.param(["ipCsv=192.0.2.1@n1", " ipCsv=192.0.2.2@n1"], id="one entry per device, spaced"),
+        ],
+    )
+    def test_queries_that_would_match_everything_or_nothing_are_never_sent(self, connect, queries):
+        client, server = connect({"Collection.associateMonitorSet": None})
+        with pytest.raises(ValueError):
+            client.associate_monitor_set(2, queries)
+        assert server.requests == []

lvi_api_client-0.2.1/VERSION

@@ -1 +0,0 @@
-0.2.1