Wait for analysis readiness before starting API

README.md

@@ -50,7 +50,7 @@ The worker accepts one analysis at a time. The backend stages inputs and receive
 
 For a local Docker check, build with `docker build -t sporalize-backend .`, then run `docker run --rm --env-file .env -e PORT=7860 -p 7860:7860 sporalize-backend`. The `.env` NODE_ENV setting controls whether production HTTPS checks apply.
 
-Node health: `GET /health`. AI health is internal at `http://127.0.0.1:8000/healthz` and becomes available after model initialization. Node health alone does not indicate model readiness. Video uploads go through Node directly to Python without Vercel. Validate hosting timeouts and representative large uploads before release.
+Node health: `GET /health`. At startup, `start.py` waits for the internal AI health endpoint at `http://127.0.0.1:8000/healthz` before starting Node, so the public API opens only after model initialization. This readiness check runs once at startup and adds no latency to normal requests. If AI startup fails or takes longer than 25 minutes, the service exits with a clear error; Hugging Face's default Space startup timeout is 30 minutes. Video uploads go through Node directly to Python without Vercel. Validate hosting timeouts and representative large uploads before release.
 
 Run one container with one Python worker: analysis jobs and retry payloads are in memory and are lost on restart. Temporary local files are ephemeral. Completed videos and `results.json` are stored in the private HF dataset; Node stores session metadata and frame indices in Supabase. Model constants are in `app.py`.
 

start.py

@@ -1,14 +1,37 @@
 """Run the public Node API and private Python worker as one service."""
+import json
 import os
 from pathlib import Path
 import signal
 import subprocess
 import sys
 import time
+from urllib.request import urlopen
 
 from dotenv import load_dotenv
 
 
+def wait_for_analysis(process, should_stop, timeout_seconds=25 * 60):
+    deadline = time.monotonic() + timeout_seconds
+    while not should_stop():
+        exit_code = process.poll()
+        if exit_code is not None:
+            print(f"Analysis process exited before it was ready ({exit_code})", flush=True)
+            return False
+        try:
+            with urlopen("http://127.0.0.1:8000/healthz", timeout=1) as response:
+                payload = json.load(response) if response.status == 200 else None
+                if isinstance(payload, dict) and payload.get("ok") is True:
+                    return process.poll() is None
+        except (OSError, ValueError):
+            pass
+        if time.monotonic() >= deadline:
+            print(f"Analysis process did not become ready within {timeout_seconds} seconds", flush=True)
+            return False
+        time.sleep(0.5)
+    return False
+
+
 def main():
     root = Path(__file__).resolve().parent
     load_dotenv(root / ".env")
@@ -28,8 +51,11 @@ def main():
     for sig in (signal.SIGINT, signal.SIGTERM):
         signal.signal(sig, stop)
     try:
-        children.append(subprocess.Popen([sys.executable, "-m", "uvicorn", "app:app",
-            "--host", "127.0.0.1", "--port", "8000", "--workers", "1"], cwd=root, env=env))
+        analysis = subprocess.Popen([sys.executable, "-m", "uvicorn", "app:app",
+            "--host", "127.0.0.1", "--port", "8000", "--workers", "1"], cwd=root, env=env)
+        children.append(analysis)
+        if not wait_for_analysis(analysis, lambda: stopping):
+            return 0 if stopping else 1
         children.append(subprocess.Popen(["node", "dist/server.js"], cwd=root, env=env))
         while not stopping:
             for child in children:

tests/test_start.py

@@ -0,0 +1,54 @@
+import unittest
+from unittest.mock import MagicMock, Mock, patch
+
+import start
+
+
+class StartupTest(unittest.TestCase):
+    def test_waits_for_analysis_health_before_accepting_requests(self):
+        process = Mock()
+        process.poll.return_value = None
+        response = MagicMock()
+        response.__enter__.return_value.status = 200
+        response.__enter__.return_value.read.return_value = b'{"ok": true}'
+        with patch.object(start, "urlopen", side_effect=[OSError("not listening"), response]) as probe, \
+                patch.object(start.time, "sleep") as sleep:
+            self.assertTrue(start.wait_for_analysis(process, lambda: False))
+        self.assertEqual(probe.call_count, 2)
+        sleep.assert_called_once_with(0.5)
+
+    def test_exits_without_starting_node_if_analysis_fails(self):
+        analysis = Mock()
+        analysis.poll.return_value = 3
+        analysis.returncode = 3
+        with patch.object(start.subprocess, "Popen", return_value=analysis) as spawn, \
+                patch.object(start, "load_dotenv"), patch.object(start.signal, "signal"):
+            self.assertEqual(start.main(), 1)
+        spawn.assert_called_once()
+
+    def test_times_out_if_analysis_never_becomes_ready(self):
+        analysis = Mock()
+        analysis.poll.return_value = None
+        with patch.object(start, "urlopen", side_effect=OSError("not listening")), \
+                patch.object(start.time, "monotonic", side_effect=[0, 2]), \
+                patch.object(start.time, "sleep") as sleep:
+            self.assertFalse(start.wait_for_analysis(analysis, lambda: False, timeout_seconds=1))
+        sleep.assert_not_called()
+
+    def test_starts_node_after_analysis_is_ready(self):
+        analysis = Mock()
+        analysis.poll.return_value = None
+        node = Mock()
+        node.poll.return_value = 2
+        node.returncode = 2
+        with patch.object(start.subprocess, "Popen", side_effect=[analysis, node]) as spawn, \
+                patch.object(start, "load_dotenv"), patch.object(start.signal, "signal"), \
+                patch.object(start, "wait_for_analysis", side_effect=lambda *_: spawn.call_count == 1) as readiness:
+            self.assertEqual(start.main(), 2)
+        self.assertEqual(spawn.call_count, 2)
+        self.assertEqual(spawn.call_args_list[1].args[0], ["node", "dist/server.js"])
+        readiness.assert_called_once()
+
+
+if __name__ == "__main__":
+    unittest.main()