woninet 2.0.2__tar.gz → 2.1.0__tar.gz

{woninet-2.0.2 → woninet-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: woninet
-Version: 2.0.2
+Version: 2.1.0
 Summary: A Python-based ARP+ICMP network monitoring tool
 Author-email: Alireza Teymuri <teymuri.alireza98@gmail.com>
 License-Expression: MIT
@@ -23,6 +23,7 @@ Requires-Dist: matplotlib<3.12,>=3.11.0
 Provides-Extra: test
 Requires-Dist: pytest<9.2,>=9.1.1; extra == "test"
 Requires-Dist: httpx<0.29,>=0.28.1; extra == "test"
+Requires-Dist: ruff<0.16,>=0.15.11; extra == "test"
 Dynamic: license-file
 
 # woninet
@@ -71,6 +72,8 @@ IPs and filters out Wi‑Fi ARP‑delay noise.)
 
 ### Unix/Linux
 
+1. **Method 1 (recommended (Uses the `icmplib` module)):**
+
 Create and activate a virtual environment:
 
 ```shell
@@ -96,7 +99,28 @@ Then run:
 woninet --help
 ```
 
-#### macOS/Windows
+2. **Method 2 (Uses the system's `ping` command as a fallback):**
+
+Create and activate a virtual environment:
+
+```shell
+python3 -m venv venv
+source venv/bin/activate
+```
+
+Install from PyPI:
+
+```shell
+pip install woninet
+```
+
+Then run:
+
+```shell
+woninet --help
+```
+
+### macOS/Windows
 
 Install from PyPI:
 
@@ -173,7 +197,7 @@ sudo ../venv/bin/python3 -m woninet
 ## Configuration
 
 You can define alert rules in a JSON file. Rename the example file at
-`woninet/config.example.json` to `config.json`. The application will load the alert
+`config.example.json` to `config.json`. The application will load the alert
 rules from that file at startup.
 
 ### Example:
@@ -200,6 +224,11 @@ rules from that file at startup.
             "metric": "packet_loss",
             "threshold": 0.0,
             "consecutive_checks": 1
+        },
+        {
+            "metric": "jitter",
+            "threshold": 40.0,
+            "consecutive_checks": 3
         }
     ]
 }
@@ -224,7 +253,7 @@ Higher values may increase system load and latency.
 
 #### Alert Rules
 
-- **metric**: The metric name to evaluate (`latency` or `packet_loss`)
+- **metric**: The metric name to evaluate (`latency`, `packet_loss` or `jitter`)
 - **threshold**: The value that triggers the alert. For latency, this is in milliseconds.
 For packet loss, this is a percentage (0.0-100.0).
 - **consecutive_checks**: The number of consecutive evaluations required before the alert
@@ -235,10 +264,11 @@ state changes. Higher values reduce false positives.
 - **Packet Loss**: Values are in the range [0.0, 100.0]. A value of 100.0 indicates 100%
 packet loss. A value of 0.0 will trigger on any packet loss.
 - **Latency**: All latency thresholds are evaluated in milliseconds.
+- **Jitter**: All jitter thresholds are evaluated in milliseconds.
 
 ## Usage
 
-This [guide](./docs/usage.md) explains common ways to run *woninet* and how to resolve common issues.
+This [guide](https://github.com/teymuri-alireza/woninet/blob/main/docs/usage.md) explains common ways to run *woninet* and how to resolve common issues.
 
 ## Testing
 
@@ -263,10 +293,10 @@ The test suite currently focuses on API behavior and core logic, and it uses pyt
 
 ## Documentation
 
-if you have any question or need clarification, check the [documentation](./docs/documentation.md) guide.
+if you have any question or need clarification, check the [documentation](.https://github.com/teymuri-alireza/woninet/blob/main/docs/documentation.md) guide.
 
 ## Contribution
 
 Thanks for considering contributing to *woninet!*
 To help us maintain code quality, stability, and a predictable release process, please review
-and follow the guidelines in our [Contributing Guide.](./CONTRIBUTING.md)
+and follow the guidelines in our [Contributing Guide.](https://github.com/teymuri-alireza/woninet/blob/main/CONTRIBUTING.md)

{woninet-2.0.2 → woninet-2.1.0}/README.md

@@ -44,6 +44,8 @@ IPs and filters out Wi‑Fi ARP‑delay noise.)
 
 ### Unix/Linux
 
+1. **Method 1 (recommended (Uses the `icmplib` module)):**
+
 Create and activate a virtual environment:
 
 ```shell
@@ -69,7 +71,28 @@ Then run:
 woninet --help
 ```
 
-#### macOS/Windows
+2. **Method 2 (Uses the system's `ping` command as a fallback):**
+
+Create and activate a virtual environment:
+
+```shell
+python3 -m venv venv
+source venv/bin/activate
+```
+
+Install from PyPI:
+
+```shell
+pip install woninet
+```
+
+Then run:
+
+```shell
+woninet --help
+```
+
+### macOS/Windows
 
 Install from PyPI:
 
@@ -146,7 +169,7 @@ sudo ../venv/bin/python3 -m woninet
 ## Configuration
 
 You can define alert rules in a JSON file. Rename the example file at
-`woninet/config.example.json` to `config.json`. The application will load the alert
+`config.example.json` to `config.json`. The application will load the alert
 rules from that file at startup.
 
 ### Example:
@@ -173,6 +196,11 @@ rules from that file at startup.
             "metric": "packet_loss",
             "threshold": 0.0,
             "consecutive_checks": 1
+        },
+        {
+            "metric": "jitter",
+            "threshold": 40.0,
+            "consecutive_checks": 3
         }
     ]
 }
@@ -197,7 +225,7 @@ Higher values may increase system load and latency.
 
 #### Alert Rules
 
-- **metric**: The metric name to evaluate (`latency` or `packet_loss`)
+- **metric**: The metric name to evaluate (`latency`, `packet_loss` or `jitter`)
 - **threshold**: The value that triggers the alert. For latency, this is in milliseconds.
 For packet loss, this is a percentage (0.0-100.0).
 - **consecutive_checks**: The number of consecutive evaluations required before the alert
@@ -208,10 +236,11 @@ state changes. Higher values reduce false positives.
 - **Packet Loss**: Values are in the range [0.0, 100.0]. A value of 100.0 indicates 100%
 packet loss. A value of 0.0 will trigger on any packet loss.
 - **Latency**: All latency thresholds are evaluated in milliseconds.
+- **Jitter**: All jitter thresholds are evaluated in milliseconds.
 
 ## Usage
 
-This [guide](./docs/usage.md) explains common ways to run *woninet* and how to resolve common issues.
+This [guide](https://github.com/teymuri-alireza/woninet/blob/main/docs/usage.md) explains common ways to run *woninet* and how to resolve common issues.
 
 ## Testing
 
@@ -236,10 +265,10 @@ The test suite currently focuses on API behavior and core logic, and it uses pyt
 
 ## Documentation
 
-if you have any question or need clarification, check the [documentation](./docs/documentation.md) guide.
+if you have any question or need clarification, check the [documentation](.https://github.com/teymuri-alireza/woninet/blob/main/docs/documentation.md) guide.
 
 ## Contribution
 
 Thanks for considering contributing to *woninet!*
 To help us maintain code quality, stability, and a predictable release process, please review
-and follow the guidelines in our [Contributing Guide.](./CONTRIBUTING.md)
+and follow the guidelines in our [Contributing Guide.](https://github.com/teymuri-alireza/woninet/blob/main/CONTRIBUTING.md)

{woninet-2.0.2 → woninet-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "woninet"
-version = "2.0.2"
+version = "2.1.0"
 description = "A Python-based ARP+ICMP network monitoring tool"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -52,4 +52,5 @@ woninet = "woninet.main:main"
 test = [
     "pytest>=9.1.1,<9.2",
     "httpx>=0.28.1,<0.29",
+    "ruff>=0.15.11,<0.16",
 ]

{woninet-2.0.2 → woninet-2.1.0}/tests/test_alert_events.py

@@ -71,6 +71,40 @@ def test_packet_loss_trigger_alert_event(db_session):
     assert packet_loss.event_type == "trigger"
 
 
+def test_jitter_trigger_alert_event(db_session):
+    storage = StorageEngine(session_factory=lambda: db_session)
+
+    metric = MetricRecord(device_ip="192.168.1.10", metric="jitter", value=60.0)
+    storage.store_metric(metric)
+
+    alert_rule = {"metric": "jitter", "threshold": 40.0, "consecutive_checks": 0}
+
+    alert = AlertEngine(
+        storage=storage,
+        rules=[
+            AlertRule(
+                alert_rule["metric"],
+                alert_rule["threshold"],
+                alert_rule["consecutive_checks"],
+            )
+        ],
+    )
+
+    alert.evaluate(
+        ip="192.168.1.10",
+        metrics_list=[
+            MetricRecord(device_ip="192.168.1.10", metric="jitter", value=60.0),
+        ],
+        default_consecutive_checks={
+            "jitter": 0,
+        },
+    )
+
+    jitter = storage.get_recent_alert_events()[0]
+
+    assert jitter.event_type == "trigger"
+
+
 def test_latency_recover_alert_event(db_session):
     storage = StorageEngine(session_factory=lambda: db_session)
 
@@ -149,3 +183,43 @@ def test_packet_loss_recover_alert_event(db_session):
     packet_loss = storage.get_recent_alert_events()[0]
 
     assert packet_loss.event_type == "recover"
+
+
+def test_jitter_recover_alert_event(db_session):
+    storage = StorageEngine(session_factory=lambda: db_session)
+
+    metric = MetricRecord(device_ip="192.168.1.10", metric="jitter", value=20.0)
+    storage.store_metric(metric)
+
+    state = storage.get_or_create_alert_state(
+        ip="192.168.1.10", metric="jitter", consecutive_checks=0
+    )
+    state.state = "warning"
+    storage.update_alert_state(state)
+
+    alert_rule = {"metric": "jitter", "threshold": 40.0, "consecutive_checks": 0}
+
+    alert = AlertEngine(
+        storage=storage,
+        rules=[
+            AlertRule(
+                alert_rule["metric"],
+                alert_rule["threshold"],
+                alert_rule["consecutive_checks"],
+            )
+        ],
+    )
+
+    alert.evaluate(
+        ip="192.168.1.10",
+        metrics_list=[
+            MetricRecord(device_ip="192.168.1.10", metric="jitter", value=20.0),
+        ],
+        default_consecutive_checks={
+            "jitter": 0,
+        },
+    )
+
+    jitter = storage.get_recent_alert_events()[0]
+
+    assert jitter.event_type == "recover"

woninet-2.1.0/tests/test_api.py

@@ -0,0 +1,37 @@
+def test_dashboard_endpoint(client):
+    response = client.get("/")
+    assert response.status_code == 200
+
+
+def test_devices_api_returns_mocked_devices(client):
+    response = client.get("/api/devices")
+
+    assert response.status_code == 200
+    assert response.json()["devices"][0]["ip"] == "192.168.1.10"
+
+
+def test_device_info_api_returns_mocked_device(client):
+    response = client.get("/api/devices/192.168.100.1")
+
+    assert response.status_code == 200
+    assert response.json()["device"]["ip"] == "192.168.100.1"
+
+
+def test_device_info_page_returns_mocked_device(client):
+    response = client.get("/devices/192.168.100.2")
+
+    assert response.status_code == 200
+
+
+def test_device_info_page_returns_unknown_device(client):
+    response = client.get("/devices/192.168.100.10")
+
+    assert response.status_code == 404
+
+
+def test_stats_api_returns_mocked_devices(client):
+    response = client.get("/api/stats")
+
+    assert response.status_code == 200
+    assert response.json()["health"]["engine_alive"]
+    assert response.json()["identity"]["server_ip"] == "192.168.200.100"

woninet-2.1.0/tests/test_system_ping.py

@@ -0,0 +1,121 @@
+import re
+
+
+def _parse_ping_output(output: str, os_name: str):
+    if os_name != "Windows":
+        avg_rtt_regex = r"rtt min/avg/max/mdev = [\d\.]+/([\d\.]+)/[\d\.]+/[\d\.]+ ms"
+
+        packet_loss_regex = r"([\d\.]+)% packet loss"
+
+        per_ping_time_regex = r"time[=<]([\d\.]+) ?ms"
+    else:
+        avg_rtt_regex = r"Average = ([\d\.]+)ms"
+
+        packet_loss_regex = r"\(([^\)]+)% loss\)"
+
+        per_ping_time_regex = r"time[=<]([\d\.]+)ms"
+
+    avg_rtt = 0
+    packet_loss = 0.0
+    per_ping_times = []
+    for line in output.splitlines():
+        m = re.search(avg_rtt_regex, line)
+        if m:
+            try:
+                avg_rtt = float(m.group(1))
+            except ValueError:
+                avg_rtt = 0
+            continue
+
+        m = re.search(packet_loss_regex, line)
+        if m:
+            try:
+                packet_loss = float(m.group(1))
+            except ValueError:
+                packet_loss = 0.0
+
+        m = re.search(per_ping_time_regex, line)
+        if m:
+            try:
+                per_ping_times.append(float(m.group(1)))
+            except ValueError:
+                pass
+
+    jitter = 0.0
+    if len(per_ping_times) >= 2:
+        diffs = [
+            abs(per_ping_times[i] - per_ping_times[i - 1])
+            for i in range(1, len(per_ping_times))
+        ]
+        jitter = round(sum(diffs) / len(diffs), 3)
+
+    return avg_rtt, packet_loss, jitter
+
+
+def test_successful_parse_output_on_linux():
+    sample_output = """
+    PING 192.168.1.1 (192.168.1.1) 56(84) bytes of data.
+    64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=2.67 ms
+    64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=6.38 ms
+
+    --- 192.168.1.1 ping statistics ---
+    2 packets transmitted, 2 received, 0% packet loss, time 1002ms
+    rtt min/avg/max/mdev = 2.672/4.524/6.376/1.852 ms
+    """
+
+    avg_rtt, packet_loss, jitter = _parse_ping_output(sample_output, "Linux")
+
+    assert avg_rtt == 4.524
+    assert packet_loss == 0.0
+    assert jitter == 3.71
+
+
+def test_failed_parse_output_on_linux():
+    sample_output = """
+    PING 192.168.1.2 (192.168.1.2) 56(84) bytes of data.
+
+    --- 192.168.1.2 ping statistics ---
+    2 packets transmitted, 0 received, 100% packet loss, time 1044ms
+    """
+
+    avg_rtt, packet_loss, jitter = _parse_ping_output(sample_output, "Linux")
+
+    assert avg_rtt == 0.0
+    assert packet_loss == 100.0
+    assert jitter == 0.0
+
+
+def test_successful_parse_output_on_windows():
+    sample_output = """
+    Pinging 192.168.1.1 with 32 bytes of data:
+    Reply from 192.168.1.1: bytes=32 time=6ms TTL=64
+    Reply from 192.168.1.1: bytes=32 time=2ms TTL=64
+
+    Ping statistics for 192.168.1.1:
+        Packets: Sent = 2, Received = 2, Lost = 0 (0% loss),
+    Approximate round trip times in milli-seconds:
+        Minimum = 2ms, Maximum = 6ms, Average = 4ms
+    """
+
+    avg_rtt, packet_loss, jitter = _parse_ping_output(sample_output, "Windows")
+
+    assert avg_rtt == 4.0
+    assert packet_loss == 0.0
+    assert jitter == 4.0
+
+
+def test_failed_parse_output_on_windows():
+    sample_output = """
+    Pinging 192.168.1.2 with 32 bytes of data:
+    Request timed out.
+    Request timed out.
+
+    Ping statistics for 192.168.1.2:
+    Packets: Sent = 2, Received = 0, Lost = 2 (100% loss),
+    """
+
+    avg_rtt, packet_loss, jitter = _parse_ping_output(sample_output, "Windows")
+
+    assert avg_rtt == 0.0
+    assert packet_loss == 100.0
+    assert jitter == 0.0

{woninet-2.0.2 → woninet-2.1.0}/woninet/__init__.py

@@ -1,2 +1,2 @@
 # woninet/core/__init__.py
-__version__ = "2.0.2"
+__version__ = "2.1.0"

{woninet-2.0.2 → woninet-2.1.0}/woninet/core/alerts.py

@@ -85,24 +85,34 @@ class AlertEngine:
         """
         for metric in metrics_list:
             if metric is not None:
-                if metric.metric == "latency":
-                    self._evaluate_latency(
-                        ip=ip,
-                        metric="latency",
-                        value=metric.value,
-                        default_consecutive_checks=default_consecutive_checks[
-                            "latency"
-                        ],
-                    )
-                elif metric.metric == "packet_loss":
-                    self._evaluate_packet_loss(
-                        ip=ip,
-                        metric="packet_loss",
-                        value=metric.value,
-                        default_consecutive_checks=default_consecutive_checks[
-                            "packet_loss"
-                        ],
-                    )
+                if metric.value is not None:
+                    if metric.metric == "latency":
+                        self._evaluate_latency(
+                            ip=ip,
+                            metric="latency",
+                            value=metric.value,
+                            default_consecutive_checks=default_consecutive_checks[
+                                "latency"
+                            ],
+                        )
+                    elif metric.metric == "packet_loss":
+                        self._evaluate_packet_loss(
+                            ip=ip,
+                            metric="packet_loss",
+                            value=metric.value,
+                            default_consecutive_checks=default_consecutive_checks[
+                                "packet_loss"
+                            ],
+                        )
+                    elif metric.metric == "jitter":
+                        self._evaluate_jitter(
+                            ip=ip,
+                            metric="jitter",
+                            value=metric.value,
+                            default_consecutive_checks=default_consecutive_checks[
+                                "jitter"
+                            ],
+                        )
 
     def _evaluate_latency(
         self, ip: str, metric: str, value: float, default_consecutive_checks: int
@@ -249,3 +259,78 @@ class AlertEngine:
                 # Reset consecutive checks to its default value
                 state.consecutive_checks = default_consecutive_checks
                 self.storage.update_alert_state(state)
+
+    def _evaluate_jitter(
+        self, ip: str, metric: str, value: float, default_consecutive_checks: int
+    ):
+        """
+        Evaluate a jitter metric against the related alert rule.
+
+        If the metric crosses its threshold for a consecutive number of checks,
+        trigger or resolve an alert accordingly. Persists state transitions
+        and logs any alert changes.
+
+        Args:
+            ip (str): IP address to evaluate.
+            metric (str): Metric name (e.g. `jitter`).
+            value (float): Value of the current metric.
+            default_consecutive_checks (int): Number of consecutive evaluations
+                required to confirm a state transition.
+
+        Side Effects:
+            - Persists alert state in the database via `StorageEngine`.
+            - Emits log events.
+            - Creates `AlertEventTable` records on trigger and recover.
+        """
+        state = self.storage.get_or_create_alert_state(
+            ip=ip, metric=metric, consecutive_checks=default_consecutive_checks
+        )
+        violated = self.is_metric_violated(metric=metric, value=value)
+        if violated:
+            if state.state == "ok":
+                # Confirm remaining consecutive checks before a state transition
+                if state.consecutive_checks > 0:
+                    state.consecutive_checks = state.consecutive_checks - 1
+                    self.storage.update_alert_state(state)
+                    return
+                # Update "ok" to "warning"
+                state.state = "warning"
+                state.triggered_at = datetime.now()
+                state.consecutive_checks = default_consecutive_checks
+                self.storage.update_alert_state(state)
+
+                event = AlertEventTable(
+                    device_ip=ip, metric=metric, value=value, event_type="trigger"
+                )
+                self.storage.store_alert_event(event=event)
+                core_logger.warning(
+                    f"ALERT TRIGGERED | {ip}, metric={metric}, value={value} ms"
+                )
+            else:
+                # Reset consecutive checks to its default value
+                state.consecutive_checks = default_consecutive_checks
+                self.storage.update_alert_state(state)
+        else:
+            if state.state == "warning":
+                # Confirm remaining consecutive checks before a state transition
+                if state.consecutive_checks > 0:
+                    state.consecutive_checks = state.consecutive_checks - 1
+                    self.storage.update_alert_state(state)
+                    return
+                # Update "warning" to "ok"
+                state.state = "ok"
+                state.triggered_at = datetime.now()
+                state.consecutive_checks = default_consecutive_checks
+                self.storage.update_alert_state(state)
+
+                event = AlertEventTable(
+                    device_ip=ip, metric=metric, value=value, event_type="recover"
+                )
+                self.storage.store_alert_event(event=event)
+                core_logger.warning(
+                    f"ALERT RECOVERED | {ip}, metric={metric}, value={value} ms"
+                )
+            else:
+                # Reset consecutive checks to its default value
+                state.consecutive_checks = default_consecutive_checks
+                self.storage.update_alert_state(state)