fix(sat): improve Docker error reporting, socket fallback, and payload field name

- Show actual DockerError messages in CLI instead of generic "Docker
  Desktop is required" message, so users can see the real failure cause
- Add fallback to known Docker Desktop socket paths on macOS when
  docker.from_env() fails
- Fix payload field name from "payload" to "payload_b64" to match
  sdr-docker API response format

Author: buckleypaul

src/hubblenetwork/cli.py

@@ -2860,8 +2860,8 @@ def sat_scan(
     # Fail fast: verify Docker is available before printing anything.
     try:
         sat_mod.ensure_docker_available()
-    except sat_mod.DockerError:
-        msg = _docker_err_msg()
+    except sat_mod.DockerError as exc:
+        msg = str(exc) or _docker_err_msg()
         if printer.suppress_info_messages:
             click.echo(json.dumps({"error": msg}))
         else:
@@ -2892,9 +2892,9 @@ def _on_interrupt(sig, frame):
             printer.print_row(pkt)
             if count is not None and printer.packet_count >= count:
                 break
-    except sat_mod.DockerError:
+    except sat_mod.DockerError as exc:
         error_occurred = True
-        msg = _docker_err_msg()
+        msg = str(exc) or _docker_err_msg()
         if printer.suppress_info_messages:
             click.echo(json.dumps({"error": msg}))
         else:

src/hubblenetwork/sat.py

@@ -13,6 +13,7 @@
 import json
 import logging
 import time
+from pathlib import Path
 from typing import Generator, List, Optional, Set, Tuple
 
 import httpx
@@ -37,10 +38,21 @@ def _packets_url(port: int = API_PORT) -> str:
 # ---------------------------------------------------------------------------
 
 
+_DOCKER_DESKTOP_SOCKETS = [
+    Path.home() / ".docker/run/docker.sock",
+    Path.home() / "Library/Containers/com.docker.docker/Data/docker-cli.sock",
+]
+
+
 def _get_client():
     """Return a Docker client from the environment.
 
-    Raises ``DockerError`` if the Docker SDK is not installed.
+    Tries ``docker.from_env()`` first (which honours ``DOCKER_HOST`` and the
+    default ``/var/run/docker.sock``).  If that fails, probes well-known
+    Docker Desktop socket paths on macOS before giving up.
+
+    Raises ``DockerError`` if the Docker SDK is not installed or no
+    reachable daemon is found.
     """
     try:
         import docker
@@ -52,7 +64,24 @@ def _get_client():
     try:
         return docker.from_env()
     except docker.errors.DockerException:
-        raise DockerError("Docker is not available")
+        pass
+
+    # Fallback: try known Docker Desktop socket paths.
+    for sock in _DOCKER_DESKTOP_SOCKETS:
+        if sock.exists():
+            try:
+                client = docker.DockerClient(base_url=f"unix://{sock}")
+                client.ping()
+                return client
+            except Exception:
+                continue
+
+    raise DockerError(
+        "Docker is not available. If Docker Desktop is running, enable "
+        "'Allow the default Docker socket to be used' in Docker Desktop "
+        "settings, or set the DOCKER_HOST environment variable "
+        "(e.g. export DOCKER_HOST=unix://$HOME/.docker/run/docker.sock)."
+    )
 
 
 def ensure_docker_available() -> None:
@@ -140,7 +169,7 @@ def _parse_jsonl(text: str) -> List[SatellitePacket]:
             continue
         try:
             obj = json.loads(line)
-            payload_b64 = obj.get("payload", "")
+            payload_b64 = obj.get("payload_b64", "")
             payload = base64.b64decode(payload_b64) if payload_b64 else b""
             packets.append(
                 SatellitePacket(

tests/test_sat.py

@@ -4,6 +4,7 @@
 
 import base64
 import json
+from pathlib import Path
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -65,10 +66,10 @@ def test_frozen(self):
 SAMPLE_JSONL = (
     '{"device_id": "0xBB2973BD", "seq_num": 153, "device_type": "silabs", '
     '"timestamp": 1774289859.339, "rssi_dB": -42.3, "channel_num": 2, '
-    f'"freq_offset_hz": 21654.5, "payload": "{_PAYLOAD_B64}"}}\n'
+    f'"freq_offset_hz": 21654.5, "payload_b64": "{_PAYLOAD_B64}"}}\n'
     '{"device_id": "0xBB2973BD", "seq_num": 154, "device_type": "silabs", '
     '"timestamp": 1774289863.860, "rssi_dB": -42.9, "channel_num": 15, '
-    f'"freq_offset_hz": 21588.0, "payload": "{_PAYLOAD_B64}"}}\n'
+    f'"freq_offset_hz": 21588.0, "payload_b64": "{_PAYLOAD_B64}"}}\n'
 )
 
 
@@ -136,6 +137,96 @@ def test_key_tuple(self):
 # ---------------------------------------------------------------------------
 
 
+class TestGetClient:
+    @patch("docker.from_env")
+    def test_from_env_succeeds(self, mock_from_env):
+        mock_client = MagicMock()
+        mock_from_env.return_value = mock_client
+        assert sat._get_client() is mock_client
+
+    @patch("hubblenetwork.sat._DOCKER_DESKTOP_SOCKETS", [])
+    @patch("docker.from_env")
+    def test_from_env_fails_no_fallbacks(self, mock_from_env):
+        import docker
+
+        mock_from_env.side_effect = docker.errors.DockerException("no sock")
+        with pytest.raises(DockerError, match="Docker is not available"):
+            sat._get_client()
+
+    @patch("docker.DockerClient")
+    @patch("docker.from_env")
+    def test_fallback_to_desktop_socket(self, mock_from_env, mock_client_cls, tmp_path):
+        import docker
+
+        mock_from_env.side_effect = docker.errors.DockerException("no sock")
+
+        # Create a fake socket file so the path.exists() check passes.
+        fake_sock = tmp_path / "docker.sock"
+        fake_sock.touch()
+
+        mock_client = MagicMock()
+        mock_client_cls.return_value = mock_client
+
+        with patch("hubblenetwork.sat._DOCKER_DESKTOP_SOCKETS", [fake_sock]):
+            result = sat._get_client()
+
+        mock_client_cls.assert_called_once_with(base_url=f"unix://{fake_sock}")
+        mock_client.ping.assert_called_once()
+        assert result is mock_client
+
+    @patch("docker.DockerClient")
+    @patch("docker.from_env")
+    def test_fallback_skips_nonexistent_sockets(
+        self, mock_from_env, mock_client_cls, tmp_path
+    ):
+        import docker
+
+        mock_from_env.side_effect = docker.errors.DockerException("no sock")
+
+        missing = tmp_path / "missing.sock"
+        existing = tmp_path / "docker.sock"
+        existing.touch()
+
+        mock_client = MagicMock()
+        mock_client_cls.return_value = mock_client
+
+        with patch(
+            "hubblenetwork.sat._DOCKER_DESKTOP_SOCKETS", [missing, existing]
+        ):
+            result = sat._get_client()
+
+        # Only the existing socket should be tried.
+        mock_client_cls.assert_called_once_with(base_url=f"unix://{existing}")
+        assert result is mock_client
+
+    @patch("docker.DockerClient")
+    @patch("docker.from_env")
+    def test_fallback_skips_socket_that_fails_ping(
+        self, mock_from_env, mock_client_cls, tmp_path
+    ):
+        import docker
+
+        mock_from_env.side_effect = docker.errors.DockerException("no sock")
+
+        bad_sock = tmp_path / "bad.sock"
+        bad_sock.touch()
+        good_sock = tmp_path / "good.sock"
+        good_sock.touch()
+
+        bad_client = MagicMock()
+        bad_client.ping.side_effect = Exception("connection refused")
+        good_client = MagicMock()
+
+        mock_client_cls.side_effect = [bad_client, good_client]
+
+        with patch(
+            "hubblenetwork.sat._DOCKER_DESKTOP_SOCKETS", [bad_sock, good_sock]
+        ):
+            result = sat._get_client()
+
+        assert result is good_client
+
+
 class TestDockerHelpers:
     @patch("hubblenetwork.sat._get_client")
     def test_ensure_docker_available_success(self, mock_get_client):
@@ -254,4 +345,4 @@ def test_docker_not_available(self, mock_sat, runner):
 
         result = runner.invoke(cli, ["sat", "scan", "--timeout", "1"])
         assert result.exit_code != 0
-        assert "Docker" in result.output
+        assert "Docker is not installed" in result.output