Add a class for curl-like probing of user apps and associated tests.

Author: alfredeen

README.md

@@ -67,7 +67,7 @@ python3 -m serve_event_listener.main --namespace <some-namespace> --label-select
 ### Running the unit tests
 
 ```bash
-python -m unittest discover -s tests
+python -m unittest discover -s tests/unit/
 ```
 
 ### Running the integration tests

serve_event_listener/http_client/client.py

@@ -25,6 +25,7 @@ def _request(
     token_fetcher: Optional[Callable[[], str]] = None,  # optional
     auth_scheme: str = "Token",  # can easily change to Bearer in the future
     sleep_fn: Callable[[float], None] = time.sleep,  # overridable in tests
+    **request_kwargs,  # pass-through for requests.Session.request
 ) -> Optional[requests.Response]:
     merged_headers = {**(session.headers or {}), **(headers or {})}
 
@@ -49,6 +50,7 @@ def _request(
                 headers=merged_headers or None,
                 verify=verify,
                 timeout=timeout,
+                **request_kwargs,   # can forward extras (allow_redirects, stream, etc.)
             )
             code = resp.status_code
             last = resp

serve_event_listener/probing.py

@@ -0,0 +1,84 @@
+"""Curl-like availability checks of user apps."""
+
+import logging
+import socket
+from dataclasses import dataclass
+from typing import Optional
+from urllib.parse import urlparse
+
+import requests
+
+from serve_event_listener.http_client import get as http_get
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ProbeResult:
+    """Outcome of an availability probe."""
+    status: str                    # "Running" | "Unknown" | "NotFound"
+    port80_status: Optional[int] = None
+    note: str = ""                 # short diagnostic
+
+
+class AppAvailabilityProbe:
+    """
+    Curl-like availability check using only a port-80 URL.
+
+    Classification:
+      - NotFound: DNS cannot resolve the host
+      - Running:  HTTP status 2xx or 3xx
+      - Unknown:  DNS resolves, but no 2xx/3xx (e.g., connection refused, timeout, 4xx/5xx)
+                  (treating 4xx/5xx as 'Unknown' surfaces misconfig/errors; adjust if desired)
+    """
+
+    def __init__(
+        self,
+        session: requests.Session,
+        *,
+        verify_tls: bool = True,
+        timeout: tuple[float, float] = (1.5, 3.0),
+        backoff_seconds: tuple[float, ...] = (0.5, 1.0),
+    ) -> None:
+        self.session = session
+        self.verify_tls = verify_tls
+        self.timeout = timeout
+        self.backoff_seconds = backoff_seconds
+
+    def _dns_resolves(self, url: str) -> bool:
+        host = urlparse(url).hostname
+        if not host:
+            return False
+        try:
+            socket.getaddrinfo(host, None)
+            return True
+        except socket.gaierror:
+            return False
+
+    def probe_url(self, port80_url: str) -> ProbeResult:
+        """Probe a single HTTP URL and classify availability."""
+        # (c) NotFound — DNS cannot resolve
+        if not self._dns_resolves(port80_url):
+            return ProbeResult(status="NotFound", note="DNS resolution failed")
+
+        # Try GET; http_get returns None on network errors/timeouts
+        resp = http_get(
+            self.session,
+            port80_url,
+            verify=self.verify_tls,
+            timeout=self.timeout,
+            backoff_seconds=self.backoff_seconds,
+            allow_redirects=True,
+        )
+        code = resp.status_code if resp is not None else None
+
+        # (a) Running — server responds OK/redirect
+        if code is not None and 200 <= code < 400:
+            return ProbeResult(status="Running", port80_status=code, note="HTTP 2xx/3xx")
+
+        # (b) Unknown — DNS ok but no success (refused/timeout/4xx/5xx)
+        return ProbeResult(
+            status="Unknown",
+            port80_status=code,
+            note="DNS ok; no 2xx/3xx (refused/timeout/4xx/5xx)",
+        )

tests/integration/test_probing_integration.py

@@ -0,0 +1,49 @@
+"""Integration tests for AppAvailabilityProbe (real DNS + HTTP)."""
+
+import os
+import unittest
+
+from serve_event_listener.http_client import make_session
+from serve_event_listener.probing import AppAvailabilityProbe
+from tests.integration.base import IntegrationTestCase
+
+
+class TestAppAvailabilityProbeIntegration(IntegrationTestCase):
+    """Probe real endpoints to classify Running / Unknown / NotFound."""
+
+    def setUp(self):
+        """Build a real Session and a probe with short timeouts."""
+        self.session = make_session(total_retries=2)
+        self.probe = AppAvailabilityProbe(
+            self.session,
+            verify_tls=True,
+            timeout=(0.5, 1.0),
+            backoff_seconds=(0.2, 0.4),
+        )
+
+    def test_running_on_live_endpoint(self):
+        """Returns Running on a healthy live endpoint (base or PROBE_URL)."""
+        url = (
+            os.getenv("PROBE_URL")
+            or os.getenv("BASE_URL")
+        )
+        if not url:
+            raise unittest.SkipTest("Set PROBE_URL or BASE_URL")
+        if not url.endswith("api/are-you-there/"):
+            # Hit the /api/are-you-there/ endpoint
+            url = f'{url.rstrip("/")}/api/are-you-there/'
+        res = self.probe.probe_url(url)
+        # Most healthy bases should be 2xx/3xx → Running. If your base needs auth and
+        # returns 401, adjust this assertion or provide PROBE_URL that is public.
+        self.assertEqual(res.status, "Running", f"Unexpected result for {url}: {res}")
+
+    def test_notfound_on_nonexistent_host(self):
+        """Returns NotFound on a guaranteed-nonexistent domain."""
+        res = self.probe.probe_url("http://no-such-host.invalid/")
+        self.assertEqual(res.status, "NotFound")
+
+    def test_unknown_on_local_refused(self):
+        """Returns Unknown when host resolves but connection is refused."""
+        # Port 9 is typically closed; adjust if your CI environment differs.
+        res = self.probe.probe_url("http://127.0.0.1:9/")
+        self.assertEqual(res.status, "Unknown")

tests/unit/test_probing.py

@@ -0,0 +1,103 @@
+"""Unit tests for AppAvailabilityProbe (DNS + HTTP classification)."""
+
+import socket
+import unittest
+from unittest.mock import MagicMock, patch
+
+import requests
+
+from serve_event_listener.probing import AppAvailabilityProbe, ProbeResult
+
+
+class TestAppAvailabilityProbe(unittest.TestCase):
+    """Classify results based on mocked DNS and HTTP outcomes."""
+
+    def setUp(self):
+        """Create a probe with a fake Session and short timeouts."""
+        self.session = MagicMock(spec=requests.Session)
+        self.probe = AppAvailabilityProbe(
+            self.session,
+            verify_tls=True,
+            timeout=(0.2, 0.5),
+            backoff_seconds=(0.05, 0.1),
+        )
+
+    @patch("serve_event_listener.probing.http_get")
+    @patch("serve_event_listener.probing.socket.getaddrinfo")
+    def test_notfound_when_dns_fails(self, mock_dns, mock_http_get):
+        """Returns NotFound when DNS cannot resolve the host."""
+        mock_dns.side_effect = socket.gaierror()
+        res = self.probe.probe_url("http://no-such-host.invalid/")
+        self.assertIsInstance(res, ProbeResult)
+        self.assertEqual(res.status, "NotFound")
+        mock_http_get.assert_not_called()
+
+    @patch("serve_event_listener.probing.http_get")
+    @patch("serve_event_listener.probing.socket.getaddrinfo")
+    def test_running_on_200(self, mock_dns, mock_http_get):
+        """Returns Running on HTTP 200."""
+        mock_dns.return_value = [(None,)]
+        mock_http_get.return_value = MagicMock(status_code=200)
+
+        res = self.probe.probe_url("http://example.com/")
+        self.assertEqual(res.status, "Running")
+        self.assertEqual(res.port80_status, 200)
+
+        # Arguments are forwarded correctly
+        _, kwargs = mock_http_get.call_args
+        self.assertTrue(kwargs.get("allow_redirects"))
+        self.assertEqual(kwargs.get("timeout"), (0.2, 0.5))
+
+    @patch("serve_event_listener.probing.http_get")
+    @patch("serve_event_listener.probing.socket.getaddrinfo")
+    def test_running_on_3xx(self, mock_dns, mock_http_get):
+        """Returns Running on HTTP 302 redirect."""
+        mock_dns.return_value = [(None,)]
+        mock_http_get.return_value = MagicMock(status_code=302)
+        res = self.probe.probe_url("http://example.com/")
+        self.assertEqual(res.status, "Running")
+        self.assertEqual(res.port80_status, 302)
+
+    @patch("serve_event_listener.probing.http_get")
+    @patch("serve_event_listener.probing.socket.getaddrinfo")
+    def test_unknown_on_network_error(self, mock_dns, mock_http_get):
+        """Returns Unknown when HTTP wrapper returns None (timeout/refused)."""
+        mock_dns.return_value = [(None,)]
+        mock_http_get.return_value = None
+        res = self.probe.probe_url("http://example.com/")
+        self.assertEqual(res.status, "Unknown")
+        self.assertIsNone(res.port80_status)
+
+    @patch("serve_event_listener.probing.http_get")
+    @patch("serve_event_listener.probing.socket.getaddrinfo")
+    def test_unknown_on_5xx(self, mock_dns, mock_http_get):
+        """Returns Unknown on server 5xx."""
+        mock_dns.return_value = [(None,)]
+        mock_http_get.return_value = MagicMock(status_code=503)
+        res = self.probe.probe_url("http://example.com/")
+        self.assertEqual(res.status, "Unknown")
+        self.assertEqual(res.port80_status, 503)
+
+    @patch("serve_event_listener.probing.http_get")
+    @patch("serve_event_listener.probing.socket.getaddrinfo")
+    def test_unknown_on_4xx(self, mock_dns, mock_http_get):
+        """Returns Unknown on client 4xx."""
+        mock_dns.return_value = [(None,)]
+        mock_http_get.return_value = MagicMock(status_code=404)
+        res = self.probe.probe_url("http://example.com/")
+        self.assertEqual(res.status, "Unknown")
+        self.assertEqual(res.port80_status, 404)
+
+    @patch("serve_event_listener.probing.http_get")
+    @patch("serve_event_listener.probing.socket.getaddrinfo")
+    def test_notfound_when_url_has_no_host(self, mock_dns, mock_http_get):
+        """Returns NotFound when URL has no hostname."""
+        # urlparse(host) -> None triggers NotFound before DNS call
+        res = self.probe.probe_url("http:///nohost")
+        self.assertEqual(res.status, "NotFound")
+        mock_dns.assert_not_called()
+        mock_http_get.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()