Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix: CLI claims the server is not running when it is running but unhealthy PIN-015

Luigi Agosti046dff0d15aa
diff --git a/cmd/pinchtab/cmd_mcp_test.go b/cmd/pinchtab/cmd_mcp_test.go
index 2efc0405..277bc192 100644
--- a/cmd/pinchtab/cmd_mcp_test.go
+++ b/cmd/pinchtab/cmd_mcp_test.go
@@ -7,6 +7,8 @@ import (
"strings"
"testing"
"time"
+
+ "github.com/pinchtab/pinchtab/internal/server"
)
func TestIsServerHealthy_ReturnsTrue(t *testing.T) {
@@ -94,8 +96,8 @@ func TestEnsureServerNoopWhenHealthy(t *testing.T) {
started = true
return nil
},
- func(baseURL, token string) bool {
- return true
+ func(baseURL, token string) server.HealthProbe {
+ return server.HealthProbe{Reachable: true, StatusCode: http.StatusOK}
},
time.Second,
)
@@ -120,9 +122,12 @@ func TestEnsureServerStartsAndWaits(t *testing.T) {
started = true
return nil
},
- func(baseURL, token string) bool {
+ func(baseURL, token string) server.HealthProbe {
healthChecks++
- return started && healthChecks >= 2
+ if started && healthChecks >= 2 {
+ return server.HealthProbe{Reachable: true, StatusCode: http.StatusOK}
+ }
+ return server.HealthProbe{}
},
time.Second,
)
@@ -150,8 +155,8 @@ func TestEnsureServerDoesNotStartWhenAutoStartDisabled(t *testing.T) {
started = true
return nil
},
- func(baseURL, token string) bool {
- return false
+ func(baseURL, token string) server.HealthProbe {
+ return server.HealthProbe{}
},
time.Second,
)
@@ -185,8 +190,8 @@ func TestEnsureServerReturnsStartError(t *testing.T) {
func() error {
return wantErr
},
- func(baseURL, token string) bool {
- return false
+ func(baseURL, token string) server.HealthProbe {
+ return server.HealthProbe{}
},
time.Second,
)
diff --git a/cmd/pinchtab/cmd_server_ensure.go b/cmd/pinchtab/cmd_server_ensure.go
index 3fc38676..4a88aba2 100644
--- a/cmd/pinchtab/cmd_server_ensure.go
+++ b/cmd/pinchtab/cmd_server_ensure.go
@@ -16,20 +16,29 @@ const ensureServerTimeout = 30 * time.Second
type serverStartFunc func() error
type serverHealthFunc func(baseURL, token string) bool
+type serverProbeFunc func(baseURL, token string) server.HealthProbe
func ensureServerForCLI(cfg *config.RuntimeConfig, baseURL, token, command string) error {
- return ensureServerWithAutoStart(baseURL, token, command, canAutoStartServerForCLI(cfg, baseURL), autoStartServer, isServerHealthy, ensureServerTimeout)
+ return ensureServerWithAutoStart(baseURL, token, command, canAutoStartServerForCLI(cfg, baseURL), autoStartServer, probeServerHealth, ensureServerTimeout)
}
-func ensureServerWith(baseURL, token, command string, start serverStartFunc, healthy serverHealthFunc, timeout time.Duration) error {
- return ensureServerWithAutoStart(baseURL, token, command, true, start, healthy, timeout)
+func ensureServerWith(baseURL, token, command string, start serverStartFunc, probe serverProbeFunc, timeout time.Duration) error {
+ return ensureServerWithAutoStart(baseURL, token, command, true, start, probe, timeout)
}
-func ensureServerWithAutoStart(baseURL, token, command string, allowAutoStart bool, start serverStartFunc, healthy serverHealthFunc, timeout time.Duration) error {
- if healthy(baseURL, token) {
+func ensureServerWithAutoStart(baseURL, token, command string, allowAutoStart bool, start serverStartFunc, probe serverProbeFunc, timeout time.Duration) error {
+ initial := probe(baseURL, token)
+ if serverProbeHealthy(initial) {
return nil
}
+ // Reachable but unhealthy: the server is up and answered this very probe, so
+ // starting a second one cannot fix whatever it reported. Quote its reason
+ // instead of waiting out the readiness timeout.
+ if initial.Reachable {
+ return fmt.Errorf("server at %s is running but unhealthy: %s", baseURL, unhealthyServerDetail(initial))
+ }
+
if !allowAutoStart {
return fmt.Errorf("server at %s is not running; auto-start is only supported for the default local server", baseURL)
}
@@ -40,7 +49,11 @@ func ensureServerWithAutoStart(baseURL, token, command string, allowAutoStart bo
return fmt.Errorf("server at %s is not running and auto-start failed: %w", baseURL, err)
}
- if !waitForServerWith(baseURL, token, timeout, healthy) {
+ // The readiness wait keeps the bool semantics: a freshly spawned server
+ // answers 503 while its browser comes up, which is not-ready-yet, not a
+ // reason to abort.
+ ready := func(url, tok string) bool { return serverProbeHealthy(probe(url, tok)) }
+ if !waitForServerWith(baseURL, token, timeout, ready) {
return fmt.Errorf("server did not become healthy at %s within %s", baseURL, timeout)
}
@@ -48,13 +61,25 @@ func ensureServerWithAutoStart(baseURL, token, command string, allowAutoStart bo
return nil
}
-func isServerHealthy(baseURL, token string) bool {
- headers := map[string]string{}
- if auth := server.AuthorizationHeaderValue(token); auth != "" {
- headers["Authorization"] = auth
+func unhealthyServerDetail(probe server.HealthProbe) string {
+ if reason := probe.Reason(); reason != "" {
+ return reason
}
- status, _, reachable := server.ProbeHealth(baseURL+"/health", 3*time.Second, headers)
- return reachable && status < 500
+ return fmt.Sprintf("HTTP %d", probe.StatusCode)
+}
+
+func probeServerHealth(baseURL, token string) server.HealthProbe {
+ return server.ProbeHealthWithToken(baseURL+"/health", 3*time.Second, token)
+}
+
+// serverProbeHealthy is the CLI ensure path's own readiness rule: anything the
+// server answers below 500 means it is up enough to take the command.
+func serverProbeHealthy(probe server.HealthProbe) bool {
+ return probe.Reachable && probe.StatusCode < 500
+}
+
+func isServerHealthy(baseURL, token string) bool {
+ return serverProbeHealthy(probeServerHealth(baseURL, token))
}
func autoStartServer() error {
diff --git a/cmd/pinchtab/cmd_server_ensure_test.go b/cmd/pinchtab/cmd_server_ensure_test.go
new file mode 100644
index 00000000..19ce21f5
--- /dev/null
+++ b/cmd/pinchtab/cmd_server_ensure_test.go
@@ -0,0 +1,172 @@
+package main
+
+import (
+ "net/http"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/pinchtab/pinchtab/internal/server"
+)
+
+const unhealthyReason = "browser initialization failed: cloakbrowser binary not found: set browser.binary to the CloakBrowser binary path"
+
+func unhealthyProbe(body string) server.HealthProbe {
+ return server.HealthProbe{Reachable: true, StatusCode: http.StatusServiceUnavailable, Body: []byte(body)}
+}
+
+func TestEnsureServer_ReachableButUnhealthyReportsReasonAndSkipsAutoStart(t *testing.T) {
+ started := false
+ probes := 0
+
+ err := ensureServerWith(
+ "http://127.0.0.1:9877",
+ "",
+ "nav",
+ func() error {
+ started = true
+ return nil
+ },
+ func(baseURL, token string) server.HealthProbe {
+ probes++
+ return unhealthyProbe(`{"reason":"` + unhealthyReason + `","status":"error"}`)
+ },
+ time.Second,
+ )
+
+ if err == nil {
+ t.Fatal("expected an error for a reachable but unhealthy server")
+ }
+ if !strings.Contains(err.Error(), "is running but unhealthy") {
+ t.Errorf("error = %q, want it to say the server is running but unhealthy", err)
+ }
+ if !strings.Contains(err.Error(), unhealthyReason) {
+ t.Errorf("error = %q, want the server's own reason verbatim", err)
+ }
+ if strings.Contains(err.Error(), "is not running") {
+ t.Errorf("error = %q, must not claim the server is not running", err)
+ }
+ if started {
+ t.Error("auto-start ran against a server that is already up and answering")
+ }
+ if probes != 1 {
+ t.Errorf("health probes = %d, want 1 — an unhealthy server must not be polled to the timeout", probes)
+ }
+}
+
+func TestEnsureServer_UnhealthyWithUnparseableBodyReportsStatusOnly(t *testing.T) {
+ for _, body := range []string{"", "not json at all", `{"status":"error"}`} {
+ t.Run(body, func(t *testing.T) {
+ started := false
+ err := ensureServerWith(
+ "http://127.0.0.1:9877",
+ "",
+ "nav",
+ func() error {
+ started = true
+ return nil
+ },
+ func(baseURL, token string) server.HealthProbe { return unhealthyProbe(body) },
+ time.Second,
+ )
+
+ if err == nil {
+ t.Fatal("expected an error for a reachable but unhealthy server")
+ }
+ if !strings.Contains(err.Error(), "is running but unhealthy") {
+ t.Errorf("error = %q, want the unhealthy message", err)
+ }
+ if !strings.Contains(err.Error(), "HTTP 503") {
+ t.Errorf("error = %q, want the status code when no reason can be parsed", err)
+ }
+ if started {
+ t.Error("auto-start ran against a reachable server")
+ }
+ })
+ }
+}
+
+func TestEnsureServer_UnreachableStillAutoStarts(t *testing.T) {
+ started := false
+ probes := 0
+
+ err := ensureServerWith(
+ "http://127.0.0.1:9867",
+ "",
+ "nav",
+ func() error {
+ started = true
+ return nil
+ },
+ func(baseURL, token string) server.HealthProbe {
+ probes++
+ if started {
+ return server.HealthProbe{Reachable: true, StatusCode: http.StatusOK}
+ }
+ return server.HealthProbe{}
+ },
+ time.Second,
+ )
+
+ if err != nil {
+ t.Fatalf("ensureServerWith() error = %v", err)
+ }
+ if !started {
+ t.Fatal("expected an unreachable server to be auto-started")
+ }
+ if probes < 2 {
+ t.Errorf("health probes = %d, want the post-start readiness poll too", probes)
+ }
+}
+
+func TestEnsureServer_ReadinessWaitTreatsUnhealthyAsNotReadyYet(t *testing.T) {
+ started := false
+ probes := 0
+
+ err := ensureServerWith(
+ "http://127.0.0.1:9867",
+ "",
+ "nav",
+ func() error {
+ started = true
+ return nil
+ },
+ func(baseURL, token string) server.HealthProbe {
+ probes++
+ switch {
+ case !started:
+ return server.HealthProbe{}
+ case probes < 4:
+ return unhealthyProbe(`{"reason":"browser starting","status":"error"}`)
+ default:
+ return server.HealthProbe{Reachable: true, StatusCode: http.StatusOK}
+ }
+ },
+ 5*time.Second,
+ )
+
+ if err != nil {
+ t.Fatalf("ensureServerWith() error = %v — a server answering 503 while it boots must be waited out", err)
+ }
+ if probes < 4 {
+ t.Errorf("health probes = %d, want the wait to keep polling past the 503s", probes)
+ }
+}
+
+func TestServerProbeHealthy_KeepsTheEnsurePathThreshold(t *testing.T) {
+ cases := []struct {
+ probe server.HealthProbe
+ want bool
+ }{
+ {server.HealthProbe{Reachable: true, StatusCode: http.StatusOK}, true},
+ {server.HealthProbe{Reachable: true, StatusCode: http.StatusUnauthorized}, true},
+ {server.HealthProbe{Reachable: true, StatusCode: http.StatusServiceUnavailable}, false},
+ {server.HealthProbe{Reachable: true, StatusCode: http.StatusInternalServerError}, false},
+ {server.HealthProbe{}, false},
+ }
+ for _, tc := range cases {
+ if got := serverProbeHealthy(tc.probe); got != tc.want {
+ t.Errorf("serverProbeHealthy(%+v) = %v, want %v", tc.probe, got, tc.want)
+ }
+ }
+}
diff --git a/internal/server/helpers.go b/internal/server/helpers.go
index f5e5a05f..e621bdc5 100644
--- a/internal/server/helpers.go
+++ b/internal/server/helpers.go
@@ -1,6 +1,7 @@
package server
import (
+ "encoding/json"
"fmt"
"io"
"net/http"
@@ -36,6 +37,39 @@ func ProbeHealth(url string, timeout time.Duration, headers map[string]string) (
return resp.StatusCode, b, true
}
+// HealthProbe is one /health probe outcome with the three states kept apart —
+// unreachable, reachable but unhealthy, and healthy — plus the body, so a caller
+// can quote the reason the server gave instead of guessing at it. Which status
+// codes count as healthy is the caller's rule, not this type's.
+type HealthProbe struct {
+ Reachable bool
+ StatusCode int
+ Body []byte
+}
+
+// Reason returns the server-supplied reason from a health body, or "" when the
+// body is absent or is not the expected JSON shape (a non-PinchTab listener).
+func (p HealthProbe) Reason() string {
+ var payload struct {
+ Reason string `json:"reason"`
+ }
+ if err := json.Unmarshal(p.Body, &payload); err != nil {
+ return ""
+ }
+ return strings.TrimSpace(payload.Reason)
+}
+
+// ProbeHealthWithToken is ProbeHealth with the token turned into an
+// Authorization header and the three states kept in one value.
+func ProbeHealthWithToken(url string, timeout time.Duration, token string) HealthProbe {
+ headers := map[string]string{}
+ if auth := AuthorizationHeaderValue(token); auth != "" {
+ headers["Authorization"] = auth
+ }
+ status, body, reachable := ProbeHealth(url, timeout, headers)
+ return HealthProbe{Reachable: reachable, StatusCode: status, Body: body}
+}
+
func AuthorizationHeaderValue(token string) string {
token = strings.TrimSpace(token)
if token == "" {
@@ -48,12 +82,8 @@ func AuthorizationHeaderValue(token string) string {
}
func CheckPinchTabRunning(port, token string) bool {
- headers := map[string]string{}
- if auth := AuthorizationHeaderValue(token); auth != "" {
- headers["Authorization"] = auth
- }
- status, _, reachable := ProbeHealth(fmt.Sprintf("http://localhost:%s/health", port), 500*time.Millisecond, headers)
- return reachable && status == 200
+ probe := ProbeHealthWithToken(fmt.Sprintf("http://localhost:%s/health", port), 500*time.Millisecond, token)
+ return probe.Reachable && probe.StatusCode == 200
}
// DefaultProxyShorthands is the curated subset of bridge shorthand routes the
diff --git a/internal/server/helpers_test.go b/internal/server/helpers_test.go
index de6d30cf..d3ca5521 100644
--- a/internal/server/helpers_test.go
+++ b/internal/server/helpers_test.go
@@ -1,7 +1,11 @@
package server
import (
+ "net/http"
+ "net/http/httptest"
+ "strings"
"testing"
+ "time"
"github.com/pinchtab/pinchtab/internal/routes"
)
@@ -51,3 +55,77 @@ func TestDefaultProxyShorthandsAreCatalogRoutes(t *testing.T) {
t.Error("GET /tabs is now a catalog route; drop it from managementAllow")
}
}
+
+func TestHealthProbeReason(t *testing.T) {
+ tests := []struct {
+ name string
+ body string
+ want string
+ }{
+ {name: "health reason", body: `{"reason":"browser initialization failed","status":"error"}`, want: "browser initialization failed"},
+ {name: "trimmed", body: `{"reason":" spaced out "}`, want: "spaced out"},
+ {name: "no reason field", body: `{"status":"error"}`, want: ""},
+ {name: "not json", body: `<html>nginx</html>`, want: ""},
+ {name: "empty body", body: "", want: ""},
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ probe := HealthProbe{Reachable: true, StatusCode: 503, Body: []byte(tt.body)}
+ if got := probe.Reason(); got != tt.want {
+ t.Fatalf("Reason() = %q, want %q", got, tt.want)
+ }
+ })
+ }
+}
+
+// CheckPinchTabRunning answers a narrower question than the CLI ensure path:
+// only a 200 counts, so a listener answering anything else is not "running".
+func TestCheckPinchTabRunningRequiresExactly200(t *testing.T) {
+ tests := []struct {
+ status int
+ want bool
+ }{
+ {status: http.StatusOK, want: true},
+ {status: http.StatusNoContent, want: false},
+ {status: http.StatusUnauthorized, want: false},
+ {status: http.StatusServiceUnavailable, want: false},
+ }
+ for _, tt := range tests {
+ t.Run(http.StatusText(tt.status), func(t *testing.T) {
+ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.WriteHeader(tt.status)
+ }))
+ defer ts.Close()
+
+ port := ts.URL[strings.LastIndex(ts.URL, ":")+1:]
+ if got := CheckPinchTabRunning(port, ""); got != tt.want {
+ t.Fatalf("CheckPinchTabRunning(status %d) = %v, want %v", tt.status, got, tt.want)
+ }
+ })
+ }
+}
+
+func TestProbeHealthWithTokenCarriesAuthorizationAndBody(t *testing.T) {
+ ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Header.Get("Authorization") != "Bearer tok" {
+ w.WriteHeader(http.StatusUnauthorized)
+ return
+ }
+ w.WriteHeader(http.StatusServiceUnavailable)
+ _, _ = w.Write([]byte(`{"reason":"no browser","status":"error"}`))
+ }))
+ defer ts.Close()
+
+ probe := ProbeHealthWithToken(ts.URL+"/health", time.Second, "tok")
+ if !probe.Reachable || probe.StatusCode != http.StatusServiceUnavailable {
+ t.Fatalf("probe = %+v, want a reachable 503", probe)
+ }
+ if probe.Reason() != "no browser" {
+ t.Fatalf("Reason() = %q, want the server's reason", probe.Reason())
+ }
+
+ unreachable := ProbeHealthWithToken("http://127.0.0.1:1/health", time.Second, "tok")
+ if unreachable.Reachable {
+ t.Fatalf("probe = %+v, want unreachable", unreachable)
+ }
+}