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.goindex 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 = truereturn 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 = truereturn 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 = truereturn 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.goindex 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.Secondtype serverStartFunc func() errortype serverHealthFunc func(baseURL, token string) bool+type serverProbeFunc func(baseURL, token string) server.HealthProbefunc 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 boreturn 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 boreturn 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.gonew file mode 100644index 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.goindex f5e5a05f..e621bdc5 100644--- a/internal/server/helpers.go+++ b/internal/server/helpers.go@@ -1,6 +1,7 @@package serverimport (+ "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 thediff --git a/internal/server/helpers_test.go b/internal/server/helpers_test.goindex de6d30cf..d3ca5521 100644--- a/internal/server/helpers_test.go+++ b/internal/server/helpers_test.go@@ -1,7 +1,11 @@package serverimport (+ "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)+ }+}