fix(wait-for-grafana): two-phase polling with smarter timeout handling (#213)

* fix(wait-for-grafana): two-phase polling with smarter timeout handling

Split the polling loop into two phases:

1. TCP-bind phase (new `startupTimeout` input, default 300s): polls every
   5s while curl returns 000 (ECONNREFUSED). Grafana 13 and dev-preview
   images on contested runners can take >60s to bind the port; the old
   single-phase timeout would fail the job before the process was ready.

2. Health phase (existing `timeout` input, default 60s): once the port
   responds with anything other than 000, switches to fast polling
   (existing `interval`, default 0.5s) until the expected status code
   is received.

Additional improvements:
- Fail fast on 4xx responses in the health phase — these indicate a URL
  misconfiguration rather than a timing issue and won't self-resolve.
- Pass --connect-timeout 2 to curl in phase 1 so each attempt doesn't
  hang waiting for a connection that will never come.

Backward compatible: callers that don't pass `startupTimeout` get the
300s default, which is strictly better than the previous 60s limit.

* babysit: address Copilot review feedback

- Default startup_timeout to 300 if 5th arg is absent, preventing
  immediate Phase 1 exit when called with the old 4-arg interface
- Distinguish ECONNREFUSED (curl exit 7) from other 000-producing
  errors (DNS failure = exit 6, TLS errors, etc.); fail fast on
  anything that isn't exit 7, avoiding a 300s stall on misconfigured URLs
- Add --connect-timeout 2 and --max-time 10 to Phase 2 curl calls
  so a stalled connection cannot outlast the health timeout window

* babysit: document startupTimeout input in README

* babysit: remove version-specific language from docs

000 failures confirmed on grafana-enterprise@12.3.6, not just v13 or
dev-preview images -- the issue is pure runner contention, not image
version. Update action.yml description and README to reflect this.

Author: darrenjaneczek

wait-for-grafana/README.md

@@ -20,6 +20,14 @@ The maximum time to wait for the server to respond, in seconds. Default is `60`.
 
 The time to wait between each check, in seconds. Default is `0.5`.
 
+### `startupTimeout` (optional)
+
+The maximum time to wait for the server's TCP port to bind, in seconds. Default is `300`.
+
+This covers the window between the container starting and Grafana's HTTP listener becoming active. During this phase the action polls every 5 seconds. Once the port responds (with any status other than `000`), normal health polling begins using the `timeout` and `interval` values above.
+
+On contested CI runners, Grafana's HTTP listener can take longer to bind than the default health-check window allows, regardless of Grafana version. Increasing this value gives the process more time to start without affecting the health-check phase.
+
 ## How to use?
 
 You can use this action in your workflow to wait for a Grafana server to become available before running tests or other operations. Here's an example of how to use it:

wait-for-grafana/action.yml

@@ -17,13 +17,18 @@ inputs:
     description: "Interval between checks in seconds"
     required: true
     default: "0.5"
+  startupTimeout:
+    description: "Seconds to wait for the TCP port to bind before health polling begins. On contested CI runners, Grafana's HTTP listener can take longer to start than the default health-check window allows."
+    required: true
+    default: "300"
 runs:
   using: "composite"
   steps:
-    - run: ${{ github.action_path }}/wait-for-grafana.sh "${GRAFANA_URL}" "${GRAFANA_RESPONSE_CODE}" "${GRAFANA_TIMEOUT}" "${GRAFANA_INTERVAL}"
+    - run: ${{ github.action_path }}/wait-for-grafana.sh "${GRAFANA_URL}" "${GRAFANA_RESPONSE_CODE}" "${GRAFANA_TIMEOUT}" "${GRAFANA_INTERVAL}" "${GRAFANA_STARTUP_TIMEOUT}"
       shell: bash
       env:
         GRAFANA_URL: ${{ inputs.url }}
         GRAFANA_RESPONSE_CODE: ${{ inputs.responseCode }}
         GRAFANA_TIMEOUT: ${{ inputs.timeout }}
         GRAFANA_INTERVAL: ${{ inputs.interval }}
+        GRAFANA_STARTUP_TIMEOUT: ${{ inputs.startupTimeout }}

wait-for-grafana/wait-for-grafana.sh

@@ -4,25 +4,67 @@ url="$1"
 expected_response_code="$2"
 timeout="$3"
 interval="$4"
+startup_timeout="${5:-300}"
 
 echo "Checking URL: $url"
 echo "Expected response code: $expected_response_code"
-echo "Timeout: $timeout seconds"
+echo "Startup timeout (TCP bind): $startup_timeout seconds"
+echo "Health timeout (after bind): $timeout seconds"
 echo "Interval: $interval seconds"
 
-end_time=$((SECONDS + timeout))
+# Phase 1: wait for TCP port to bind.
+# curl exit code 7 = ECONNREFUSED: the process isn't listening yet, safe to keep waiting.
+# Any other non-zero exit code (e.g. 6 = DNS failure) indicates misconfiguration — fail fast.
+startup_end=$((SECONDS + startup_timeout))
+port_bound=false
 
-while [ $SECONDS -lt $end_time ]; do
-  response=$(curl -s -o /dev/null -w "%{http_code}" "$url")
+while [ $SECONDS -lt $startup_end ]; do
+  response=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 2 "$url")
+  curl_exit=$?
+
+  if [ $curl_exit -ne 0 ] && [ $curl_exit -ne 7 ]; then
+    echo "curl failed with exit code $curl_exit (not a connection-refused error) — failing fast"
+    exit 1
+  fi
+
+  if [ "$response" != "000" ]; then
+    port_bound=true
+    break
+  fi
+
+  echo "Waiting for TCP bind (curl exit: $curl_exit). Current status: $response"
+  sleep 5
+done
+
+if [ "$port_bound" = false ]; then
+  echo "Startup timeout reached. Server TCP port did not bind within $startup_timeout seconds"
+  exit 1
+fi
+
+echo "TCP port bound. Waiting for server to respond with status code $expected_response_code..."
+
+# Phase 2: port is open, wait for a healthy response.
+# --connect-timeout and --max-time bound each curl call so a stalled connection
+# cannot outlast the health window.
+# Fail fast on 4xx — indicates a URL misconfiguration, not a timing issue.
+health_end=$((SECONDS + timeout))
+
+while [ $SECONDS -lt $health_end ]; do
+  response=$(curl -s -o /dev/null -w "%{http_code}" --connect-timeout 2 --max-time 10 "$url")
 
   if [ "$response" -eq "$expected_response_code" ]; then
     echo "Server is up and responding with status code $expected_response_code"
     exit 0
   fi
 
+  if [ "$response" -ge 400 ] && [ "$response" -lt 500 ]; then
+    echo "Server returned $response — likely a URL misconfiguration, failing fast"
+    exit 1
+  fi
+
   echo "Waiting for server to respond with status code $expected_response_code. Current status: $response"
   sleep "$interval"
 done
 
-echo "Timeout reached. Server did not respond with status code $expected_response_code within $timeout seconds"
+echo "Timeout reached. Server did not respond with status code $expected_response_code within $timeout seconds after TCP bind"
 exit 1