CMLDEV-786 - switch to using link ID as capture key (#188)

* CMLDEV-786 - switch to using link ID as capture key

* Remove the never-released capture key method

Author: virlos

tests/test_pcap.py

@@ -42,12 +42,7 @@ def mock_link():
 
 def test_url_templates_exist():
     """Test that all required URL templates are defined."""
-    required_templates = [
-        "capture_start",
-        "capture_stop",
-        "capture_status",
-        "capture_key",
-    ]
+    required_templates = ["capture_start", "capture_stop", "capture_status"]
 
     for template in required_templates:
         assert template in Link._URL_TEMPLATES
@@ -59,7 +54,7 @@ def test_start_capture_with_params(mock_link):
     """Test start_capture with explicit parameters."""
     expected_response = {
         "config": {
-            "link_capture_key": "test-key-123",
+            "link_capture_key": mock_link.id,
             "maxpackets": 100,
             "encap": "ethernet",
         },
@@ -73,15 +68,15 @@ def test_start_capture_with_params(mock_link):
 
     assert result == expected_response
     assert result["config"]["maxpackets"] == 100
-    assert "link_capture_key" in result["config"]
+    assert result["config"]["link_capture_key"] == mock_link.id
 
 
 @respx.mock
 def test_start_capture_defaults(mock_link):
     """Test start_capture without parameters uses server defaults."""
     expected_response = {
         "config": {
-            "link_capture_key": "default-key-456",
+            "link_capture_key": mock_link.id,
             "maxpackets": 1000000,
             "maxtime": 86400,
             "encap": "ethernet",
@@ -97,14 +92,15 @@ def test_start_capture_defaults(mock_link):
     assert result == expected_response
     assert result["config"]["maxpackets"] == 1000000
     assert result["config"]["maxtime"] == 86400
+    assert result["config"]["link_capture_key"] == mock_link.id
 
 
 @respx.mock
 def test_capture_status(mock_link):
     """Test capture_status with mocked HTTP call."""
     expected_status = {
         "config": {
-            "link_capture_key": "status-key-456",
+            "link_capture_key": mock_link.id,
             "maxpackets": 200,
             "encap": "ethernet",
         },
@@ -118,17 +114,7 @@ def test_capture_status(mock_link):
 
     assert result == expected_status
     assert result["packetscaptured"] == 15
-
-
-@respx.mock
-def test_capture_key(mock_link):
-    """Test capture_key with mocked HTTP call."""
-    expected_key = "capture-key-789"
-    mock_link._session.get.return_value.json.return_value = expected_key
-
-    result = mock_link.capture_key()
-
-    assert result == expected_key
+    assert result["config"]["link_capture_key"] == mock_link.id
 
 
 @respx.mock
@@ -143,23 +129,15 @@ def test_stop_capture(mock_link):
 
 
 @respx.mock
-def test_download_capture_auto_key(mock_link):
-    """Test download_capture with automatic key retrieval."""
-
-    def mock_get_side_effect(url):
-        mock_response = Mock()
-        if "capture/key" in url:
-            mock_response.json.return_value = "auto-retrieved-key"
-        else:
-            mock_response.content = b"PCAP file content"
-        return mock_response
-
-    mock_link._session.get.side_effect = mock_get_side_effect
+def test_download_capture(mock_link):
+    """Test download_capture."""
+    expected_content = b"PCAP file content"
+    mock_link._session.get.return_value.content = expected_content
 
     result = mock_link.download_capture()
 
-    assert result == b"PCAP file content"
-    assert mock_link._session.get.call_count == 2
+    mock_link._session.get.assert_called_once()
+    assert result == expected_content
 
 
 @respx.mock
@@ -169,16 +147,7 @@ def test_get_capture_packets(mock_link):
         {"packet": {"timestamp": "2026-01-12T10:00:01Z", "size": 64}},
         {"packet": {"timestamp": "2026-01-12T10:00:02Z", "size": 128}},
     ]
-
-    def mock_get_side_effect(url):
-        mock_response = Mock()
-        if "capture/key" in url:
-            mock_response.json.return_value = "packet-key-123"
-        else:
-            mock_response.json.return_value = expected_packets
-        return mock_response
-
-    mock_link._session.get.side_effect = mock_get_side_effect
+    mock_link._session.get.return_value.json.return_value = expected_packets
 
     result = mock_link.get_capture_packets()
 
@@ -187,22 +156,12 @@ def mock_get_side_effect(url):
 
 
 @respx.mock
-def test_download_capture_packet(mock_link):
+def test_get_capture_packet(mock_link):
     """Test download_capture_packet with mocked HTTP call."""
-    expected_packet_data = {
-        "packet": {"timestamp": "2026-01-12T10:00:05Z", "size": 256}
-    }
-
-    def mock_get_side_effect(url):
-        mock_response = Mock()
-        if "capture/key" in url:
-            mock_response.json.return_value = "packet-download-key"
-        else:
-            mock_response.json.return_value = expected_packet_data
-        return mock_response
-
-    mock_link._session.get.side_effect = mock_get_side_effect
+    # the actual PDML is rather large
+    expected_packet_data = {"proto": []}
+    mock_link._session.get.return_value.json.return_value = expected_packet_data
 
-    result = mock_link.download_capture_packet(packet_id=5)
+    result = mock_link.get_capture_packet(packet_id=5)
 
     assert result == expected_packet_data

virl2_client/event_handling.py

@@ -313,8 +313,7 @@ def _handle_element_modified(self, event: Event) -> None:
             event.element._update(event.data, push_to_server=False)
 
         elif event.element_type == "link":
-            # only sends link_capture_key which is not used by the client,
-            # so we discard the message
+            # not used by the client so we discard the message
             pass
 
         else:

virl2_client/models/link.py

@@ -22,6 +22,7 @@
 
 import logging
 import time
+import warnings
 from typing import TYPE_CHECKING
 
 from ..utils import UNCHANGED, _Sentinel, check_stale, get_url_from_template, locked
@@ -48,7 +49,9 @@ class Link:
         "capture_start": "{lab}/links/{id}/capture/start",
         "capture_stop": "{lab}/links/{id}/capture/stop",
         "capture_status": "{lab}/links/{id}/capture/status",
-        "capture_key": "{lab}/links/{id}/capture/key",
+        "pcap_file": "{pcap}/{id}",
+        "pcap_packets": "{pcap}/{id}/packets",
+        "pcap_packet": "{pcap}/{id}/packets/{packet_id}",
     }
 
     def __init__(
@@ -113,8 +116,11 @@ def _url_for(self, endpoint: str, **kwargs):
         :param **kwargs: Keyword arguments used to format the URL.
         :returns: The formatted URL.
         """
-        kwargs["lab"] = self._lab._url_for("lab")
-        kwargs["id"] = self.id
+        if endpoint.startswith("pcap"):
+            kwargs["pcap"] = f"{self._session.base_url}/api/v0/pcap"
+        else:
+            kwargs["lab"] = self._lab._url_for("lab")
+        kwargs["id"] = self._id
         return get_url_from_template(endpoint, self._URL_TEMPLATES, kwargs)
 
     @property
@@ -442,7 +448,7 @@ def start_capture(
         if bpfilter is not None:
             data["bpfilter"] = bpfilter
 
-        _LOGGER.info(f"Starting packet capture on link {self.id}")
+        _LOGGER.info(f"Starting packet capture on link {self._id}")
         return self._session.put(url, json=data).json()
 
     @check_stale
@@ -451,7 +457,7 @@ def stop_capture(self) -> None:
         Stop the packet capture on this link.
         """
         url = self._url_for("capture_stop")
-        _LOGGER.info(f"Stopping packet capture on link {self.id}")
+        _LOGGER.info(f"Stopping packet capture on link {self._id}")
         self._session.put(url)
 
     @check_stale
@@ -464,58 +470,33 @@ def capture_status(self) -> dict:
         url = self._url_for("capture_status")
         return self._session.get(url).json()
 
-    @check_stale
-    def capture_key(self) -> str:
-        """
-        Get the capture key (UUID) for the packet capture on this link.
-
-        :returns: The capture key as a string.
-        :raises: HTTP exception if no capture is running on this link.
-        """
-        url = self._url_for("capture_key")
-        return self._session.get(url).json()
-
-    def download_capture(self, capture_key: str | None = None) -> bytes:
+    def download_capture(self) -> bytes:
         """
-        Download the PCAP file for this link's capture.
+        Download the PCAP file for this link's last capture.
 
-        :param capture_key: The capture key. If None, will fetch it automatically.
         :returns: The PCAP file content as bytes.
         """
-        if capture_key is None:
-            capture_key = self.capture_key()
-
-        url = f"{self._lab._session.base_url}/api/v0/pcap/{capture_key}"
-        _LOGGER.info(f"Downloading PCAP for capture key {capture_key}")
+        url = self._url_for("pcap_file")
+        _LOGGER.info(f"Downloading PCAP for link {self._id}")
         return self._session.get(url).content
 
-    def get_capture_packets(self, capture_key: str | None = None) -> list[dict]:
+    def get_capture_packets(self) -> list[dict]:
         """
-        Get a list of all captured packets in decoded format.
+        Get a list of all captured packets in decoded format from last capture.
 
-        :param capture_key: The capture key. If None, will fetch it automatically.
         :returns: List of packet dictionaries with decoded packet information.
         """
-        if capture_key is None:
-            capture_key = self.capture_key()
-
-        url = f"{self._lab._session.base_url}/api/v0/pcap/{capture_key}/packets"
-        _LOGGER.info(f"Getting packet list for capture key {capture_key}")
+        url = self._url_for("pcap_packets")
+        _LOGGER.info(f"Getting packet list for link {self._id}")
         return self._session.get(url).json()
 
-    def download_capture_packet(
-        self, packet_id: int, capture_key: str | None = None
-    ) -> dict:
+    def get_capture_packet(self, packet_id: int) -> dict:
         """
-        Download a specific packet from the capture in decoded format.
+        Get a specific packet from the last capture in decoded format.
 
-        :param packet_id: The ID of the packet to download (1-based).
-        :param capture_key: The capture key. If None, will fetch it automatically.
+        :param packet_id: The ID of the packet (1-based index).
         :returns: Dictionary containing the decoded packet information.
         """
-        if capture_key is None:
-            capture_key = self.capture_key()
-
-        url = f"{self._lab._session.base_url}/api/v0/pcap/{capture_key}/packet/{packet_id}"
-        _LOGGER.info(f"Downloading packet {packet_id} for capture key {capture_key}")
+        url = self._url_for("pcap_packet", packet_id=packet_id)
+        _LOGGER.info(f"Downloading packet {packet_id} for link {self._id}")
         return self._session.get(url).json()