Bind the Cloud Run port before app import via gunicorn

Cloud Run's startup probe hard-caps total probe time at 240s, and the
app import (~232s, dominated by country package construction) races it
on every instance start, failing roughly half of first-attempt deploys.
gunicorn's master binds the listen socket before forking workers, and
without --preload the import happens in the worker post-fork, so the
probe passes in milliseconds and readiness is governed by the
pipeline's health_check.sh /readiness-check poll (900s budget) instead
of the platform cap. --timeout 0 disables the worker heartbeat watchdog
that would otherwise kill the worker mid-import; --keep-alive 5 and
--forwarded-allow-ips preserve today's uvicorn keep-alive and proxy
header behavior (UvicornWorker leaves proxy_headers at uvicorn's
default of enabled).

health_check.sh curls now carry --max-time (default 10s, overridable
via HEALTH_CHECK_CURL_MAX_TIME_SECONDS): with the port open before the
app can answer, an unanswered poll would otherwise block until Cloud
Run's 300s request timeout.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: anth-volk

.github/scripts/health_check.sh

@@ -5,10 +5,13 @@ set -euo pipefail
 health_url="${1:?health check URL is required}"
 timeout_seconds="${HEALTH_CHECK_TIMEOUT_SECONDS:-900}"
 interval_seconds="${HEALTH_CHECK_INTERVAL_SECONDS:-10}"
+curl_max_time_seconds="${HEALTH_CHECK_CURL_MAX_TIME_SECONDS:-10}"
 deadline=$((SECONDS + timeout_seconds))
 
 while (( SECONDS < deadline )); do
-  if curl --silent --show-error --fail "${health_url}" >/dev/null; then
+  if curl --silent --show-error --fail \
+      --max-time "${curl_max_time_seconds}" \
+      "${health_url}" >/dev/null; then
     exit 0
   fi
   sleep "${interval_seconds}"

gcp/cloud_run/start.sh

@@ -10,21 +10,21 @@ REDIS_READY_MAX_ATTEMPTS="${REDIS_READY_MAX_ATTEMPTS:-30}"
 export CACHE_REDIS_HOST CACHE_REDIS_PORT CACHE_REDIS_DB
 
 redis_pid=""
-uvicorn_pid=""
+server_pid=""
 
 shutdown() {
   trap - INT TERM
 
-  if [ -n "$uvicorn_pid" ] && kill -0 "$uvicorn_pid" 2>/dev/null; then
-    kill "$uvicorn_pid" 2>/dev/null || true
+  if [ -n "$server_pid" ] && kill -0 "$server_pid" 2>/dev/null; then
+    kill "$server_pid" 2>/dev/null || true
   fi
 
   if [ -n "$redis_pid" ] && kill -0 "$redis_pid" 2>/dev/null; then
     kill "$redis_pid" 2>/dev/null || true
   fi
 
-  if [ -n "$uvicorn_pid" ]; then
-    wait "$uvicorn_pid" 2>/dev/null || true
+  if [ -n "$server_pid" ]; then
+    wait "$server_pid" 2>/dev/null || true
   fi
 
   if [ -n "$redis_pid" ]; then
@@ -58,23 +58,29 @@ until redis-cli -h "$CACHE_REDIS_HOST" -p "$CACHE_REDIS_PORT" ping >/dev/null 2>
   sleep 1
 done
 
-uvicorn policyengine_api.asgi:app \
-  --host 0.0.0.0 \
-  --port "$PORT" \
+# gunicorn's master binds the listen socket before forking workers, so the
+# Cloud Run TCP startup probe passes immediately instead of racing the
+# multi-minute app import (which happens in the worker, post-fork, because
+# --preload is NOT set). --timeout 0 is required: a worker mid-import does
+# not heartbeat, and the default 30s watchdog would kill it before boot.
+gunicorn policyengine_api.asgi:app \
+  --worker-class uvicorn.workers.UvicornWorker \
   --workers "$WEB_CONCURRENCY" \
-  --proxy-headers \
+  --bind "0.0.0.0:${PORT}" \
+  --timeout 0 \
+  --keep-alive 5 \
   --forwarded-allow-ips '*' &
-uvicorn_pid="$!"
+server_pid="$!"
 
 set +e
-wait -n "$redis_pid" "$uvicorn_pid"
+wait -n "$redis_pid" "$server_pid"
 status="$?"
 set -e
 
 if ! kill -0 "$redis_pid" 2>/dev/null; then
   echo "Redis exited; stopping Cloud Run container" >&2
-elif ! kill -0 "$uvicorn_pid" 2>/dev/null; then
-  echo "Uvicorn exited; stopping Cloud Run container" >&2
+elif ! kill -0 "$server_pid" 2>/dev/null; then
+  echo "API server exited; stopping Cloud Run container" >&2
 else
   echo "A supervised Cloud Run process exited; stopping container" >&2
 fi

tests/unit/test_cloud_run_deploy_scripts.py

@@ -270,20 +270,20 @@ def test_cloud_run_dockerfile_runs_startup_with_bash():
     assert 'CMD ["/bin/sh", "/app/start.sh"]' not in dockerfile
 
 
-def test_cloud_run_startup_supervises_redis_and_uvicorn_children():
+def test_cloud_run_startup_supervises_redis_and_server_children():
     start_script = (REPO / "gcp/cloud_run/start.sh").read_text(encoding="utf-8")
 
     assert "#!/usr/bin/env bash" in start_script
     assert 'redis_pid="$!"' in start_script
-    assert 'uvicorn_pid="$!"' in start_script
+    assert 'server_pid="$!"' in start_script
     assert "REDIS_READY_MAX_ATTEMPTS" in start_script
     assert "Redis exited before becoming ready" in start_script
     assert "Redis did not become ready" in start_script
     assert "Redis exited; stopping Cloud Run container" in start_script
-    assert "Uvicorn exited; stopping Cloud Run container" in start_script
-    assert 'wait -n "$redis_pid" "$uvicorn_pid"' in start_script
+    assert "API server exited; stopping Cloud Run container" in start_script
+    assert 'wait -n "$redis_pid" "$server_pid"' in start_script
     assert 'kill -0 "$redis_pid"' in start_script
-    assert 'kill -0 "$uvicorn_pid"' in start_script
+    assert 'kill -0 "$server_pid"' in start_script
     assert "trap 'shutdown; exit 143' INT TERM" in start_script
     assert "pkill" not in start_script
     assert re.search(r"(?m)^ *wait 2>/dev/null", start_script) is None