harden dashboard API contracts and proxy errors

apps/web/server.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import http.client
+import json
 import os
 from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
 from urllib.parse import urlsplit
@@ -15,20 +16,29 @@ UPSTREAM_PORT = int(os.environ.get("API_UPSTREAM_PORT", "8000"))
 class ProxyStaticHandler(SimpleHTTPRequestHandler):
     proxy_api = True
 
+    def _send_json_error(self, status: int, code: str) -> None:
+        payload = json.dumps({"error": code}, separators=(",", ":")).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Cache-Control", "no-store, private")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
     def _proxy_request(self) -> None:
         parsed = urlsplit(self.path)
         if parsed.path == "/api" or parsed.path.startswith("/api/"):
             target = self.path
         else:
-            self.send_error(404)
+            self._send_json_error(404, "not_found")
             return
         try:
             length = int(self.headers.get("Content-Length", "0"))
         except ValueError:
-            self.send_error(400, "invalid content length")
+            self._send_json_error(400, "invalid_content_length")
             return
         if length > MAX_PROXY_BODY:
-            self.send_error(413, "request body too large")
+            self._send_json_error(413, "request_body_too_large")
             return
         body = self.rfile.read(length) if length else None
         headers = {
@@ -37,13 +47,14 @@ class ProxyStaticHandler(SimpleHTTPRequestHandler):
             if key.lower() in {"accept", "content-type", "cookie", "user-agent", "x-request-id"}
         }
         headers["Host"] = f"{UPSTREAM_HOST}:{UPSTREAM_PORT}"
-        connection = http.client.HTTPConnection(UPSTREAM_HOST, UPSTREAM_PORT, timeout=15)
+        connection = None
         try:
+            connection = http.client.HTTPConnection(UPSTREAM_HOST, UPSTREAM_PORT, timeout=15)
             connection.request(self.command, target, body=body, headers=headers)
             response = connection.getresponse()
             payload = response.read(MAX_PROXY_BODY + 1)
             if len(payload) > MAX_PROXY_BODY:
-                self.send_error(502, "upstream response too large")
+                self._send_json_error(502, "upstream_response_too_large")
                 return
             self.send_response(response.status, response.reason)
             for key, value in response.getheaders():
@@ -52,9 +63,10 @@ class ProxyStaticHandler(SimpleHTTPRequestHandler):
             self.end_headers()
             self.wfile.write(payload)
         except (OSError, http.client.HTTPException) as exc:
-            self.send_error(502, f"api upstream unavailable: {exc}")
+            self._send_json_error(502, "api_upstream_unavailable")
         finally:
-            connection.close()
+            if connection is not None:
+                connection.close()
 
     def do_GET(self):
         if self.path.startswith("/api"):

apps/web/test_server.py

@@ -1,10 +1,14 @@
 import http.client
+import json
 import os
 import threading
 import unittest
 from unittest.mock import patch
 
 from server import ProxyStaticHandler
+from http.server import ThreadingHTTPServer
+
+RealHTTPConnection = http.client.HTTPConnection
 
 
 class FakeUpstream:
@@ -30,6 +34,22 @@ class ProxyServerTests(unittest.TestCase):
         with patch('server.http.client.HTTPConnection', FakeUpstream):
             self.assertTrue(server.proxy_api)
 
+    def test_upstream_failure_is_structured_json(self):
+        httpd = ThreadingHTTPServer(("127.0.0.1", 0), ProxyStaticHandler)
+        thread = threading.Thread(target=httpd.serve_forever, daemon=True)
+        thread.start()
+        try:
+            with patch('server.http.client.HTTPConnection', side_effect=OSError('connection refused')):
+                conn = RealHTTPConnection('127.0.0.1', httpd.server_port, timeout=3)
+                conn.request('GET', '/api/v1/dashboard/summary')
+                response = conn.getresponse()
+                body = response.read()
+            self.assertEqual(response.status, 502)
+            self.assertEqual(response.getheader('Content-Type'), 'application/json; charset=utf-8')
+            self.assertEqual(json.loads(body), {'error': 'api_upstream_unavailable'})
+        finally:
+            httpd.shutdown(); httpd.server_close(); thread.join(timeout=2)
+
 
 if __name__ == '__main__':
     unittest.main()