Skip to content

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

fix: a configured-but-keyless solver is rejected as unknown (PIN-082)

Luigi Agosti4fdd60155418
diff --git a/docs/endpoints.md b/docs/endpoints.md
index 997ef127..8fcd43a1 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -621,6 +621,21 @@ Solve body fields:
- `maxAttempts` optional (defaults to `autoSolver.maxAttempts`, default `8`)
- `timeout` optional in ms (auto-estimated when omitted, minimum `30000`)
+A named `solver` that cannot run is rejected with `400` before anything is
+solved, and the two reasons carry different codes:
+
+| Code | Meaning | Example message |
+| --- | --- | --- |
+| `unknown_solver` | No solver answers to that name — normally a misspelling. Lists what is available. | `unknown solver "cloudlfare" (available: [cloudflare semantic jschallenge])` |
+| `solver_key_missing` | A known key-gated solver whose API key is unset. Names the config key to set. | `solver "capsolver" is configured but its API key is not set; set autoSolver.external.capsolverKey to use it` |
+
+The API is deliberately stricter here than config validation, which accepts
+`capsolver` or `twocaptcha` in `autoSolver.solvers` with no key set — configuring
+a paid solver before its key is legitimate ordering, and the run falls back to
+the solvers that can run. A request naming one solver has no such fallback: it
+must not silently run a different solver, so it is rejected and told which key
+would enable it.
+
`GET /config/autosolver` returns effective autosolver runtime settings and the
currently available solver list.
diff --git a/internal/autosolver/autosolver.go b/internal/autosolver/autosolver.go
index 478bbceb..8f408838 100644
--- a/internal/autosolver/autosolver.go
+++ b/internal/autosolver/autosolver.go
@@ -230,7 +230,7 @@ func (as *AutoSolver) reportMissingSolvers(missing []string, running []Solver) {
unactionable := make([]string, 0, len(missing))
for _, name := range missing {
- gated, ok := keyGatedSolverNamed(name)
+ gated, ok := KeyGatedSolverNamed(name)
if !ok || as.isRegistered(name) {
unactionable = append(unactionable, name)
continue
diff --git a/internal/autosolver/autosolver_test.go b/internal/autosolver/autosolver_test.go
index f7ff7e2f..9ed62268 100644
--- a/internal/autosolver/autosolver_test.go
+++ b/internal/autosolver/autosolver_test.go
@@ -1144,7 +1144,7 @@ func TestOrderSolversDoesNotWarnWhenTheMissingSolverIsNotKeyGated(t *testing.T)
as := New(Config{Solvers: []string{"cloudflare", SemanticSolverName}}, nil, nil)
as.orderSolvers([]Solver{&mockSolver{name: "cloudflare", priority: 10}})
- if _, ok := keyGatedSolverNamed(SemanticSolverName); ok {
+ if _, ok := KeyGatedSolverNamed(SemanticSolverName); ok {
t.Fatalf("%s is key-gated, so this test no longer covers the non-gated case", SemanticSolverName)
}
for _, rec := range recorder.records {
diff --git a/internal/autosolver/catalog/catalog.go b/internal/autosolver/catalog/catalog.go
index 13bde980..b12a1413 100644
--- a/internal/autosolver/catalog/catalog.go
+++ b/internal/autosolver/catalog/catalog.go
@@ -76,3 +76,10 @@ func IsKnown(name string) bool {
}
return false
}
+
+// KeyGatedNamed reports the key-gated solver answering to this name together with
+// the config key that enables it. A caller that has already found the name
+// unavailable uses this to tell a missing key from an unknown name.
+func KeyGatedNamed(name string) (autosolver.KeyGatedSolver, bool) {
+ return autosolver.KeyGatedSolverNamed(name)
+}
diff --git a/internal/autosolver/keygated.go b/internal/autosolver/keygated.go
index 38995b8f..c0301bcb 100644
--- a/internal/autosolver/keygated.go
+++ b/internal/autosolver/keygated.go
@@ -22,7 +22,9 @@ func KeyGatedSolvers() []KeyGatedSolver {
}
}
-func keyGatedSolverNamed(name string) (KeyGatedSolver, bool) {
+// KeyGatedSolverNamed reports the key-gated solver answering to this name, so a
+// caller rejecting it can name the key that would enable it.
+func KeyGatedSolverNamed(name string) (KeyGatedSolver, bool) {
for _, gated := range KeyGatedSolvers() {
if gated.Name == name {
return gated, true
diff --git a/internal/handlers/solver.go b/internal/handlers/solver.go
index 410d0eaa..6e858376 100644
--- a/internal/handlers/solver.go
+++ b/internal/handlers/solver.go
@@ -12,6 +12,7 @@ import (
"github.com/pinchtab/pinchtab/internal/activity"
coreautosolver "github.com/pinchtab/pinchtab/internal/autosolver"
"github.com/pinchtab/pinchtab/internal/autosolver/adapters"
+ "github.com/pinchtab/pinchtab/internal/autosolver/catalog"
"github.com/pinchtab/pinchtab/internal/httpx"
)
@@ -62,13 +63,9 @@ func (h *Handlers) HandleSolve(w http.ResponseWriter, r *http.Request) {
req.Solver = name
}
- if req.Solver != "" {
- if !h.isAvailableAutoSolver(req.Solver) {
- httpx.ErrorCode(w, 400, "unknown_solver",
- fmt.Sprintf("unknown solver %q (available: %v)", req.Solver, h.availableAutoSolverNames()),
- false, nil)
- return
- }
+ if req.Solver != "" && !h.isAvailableAutoSolver(req.Solver) {
+ h.rejectUnavailableSolver(w, req.Solver)
+ return
}
ctx, resolvedTabID, err := h.tabContext(r, req.TabID)
@@ -108,9 +105,7 @@ func (h *Handlers) HandleSolve(w http.ResponseWriter, r *http.Request) {
cfg.Solvers = []string{req.Solver}
}
- // Explicit named solvers should run directly without semantic-first flow,
- // except when the caller explicitly requested the semantic solver.
- includeSemantic := req.Solver == "" || req.Solver == "semantic"
+ includeSemantic := req.Solver == "" || req.Solver == coreautosolver.SemanticSolverName
as := h.buildAutoSolver(cfg, includeSemantic)
timeout := 30 * time.Second
@@ -231,6 +226,23 @@ func (h *Handlers) HandleAutoSolverConfig(w http.ResponseWriter, r *http.Request
})
}
+// rejectUnavailableSolver distinguishes the two reasons a named solver cannot
+// run. A key-gated solver reaching here is always a keyless one — with its key
+// set it would be available — so it gets its own code and names the config key,
+// rather than being reported as a typo. Config validation deliberately accepts
+// the same name without its key; see docs/endpoints.md.
+func (h *Handlers) rejectUnavailableSolver(w http.ResponseWriter, name string) {
+ if gated, ok := catalog.KeyGatedNamed(name); ok {
+ httpx.ErrorCode(w, 400, "solver_key_missing",
+ fmt.Sprintf("solver %q is configured but its API key is not set; set %s to use it", gated.Name, gated.ConfigKey),
+ false, nil)
+ return
+ }
+ httpx.ErrorCode(w, 400, "unknown_solver",
+ fmt.Sprintf("unknown solver %q (available: %v)", name, h.availableAutoSolverNames()),
+ false, nil)
+}
+
func deriveChallengeType(result *coreautosolver.Result, page coreautosolver.Page) string {
if result == nil || page == nil {
return ""
diff --git a/internal/handlers/solver_test.go b/internal/handlers/solver_test.go
index 32923edb..6cc49fbc 100644
--- a/internal/handlers/solver_test.go
+++ b/internal/handlers/solver_test.go
@@ -5,6 +5,8 @@ import (
"encoding/json"
"net/http"
"net/http/httptest"
+ "os"
+ "strings"
"testing"
coreautosolver "github.com/pinchtab/pinchtab/internal/autosolver"
@@ -243,3 +245,110 @@ func TestDeriveChallengeType_NilPage(t *testing.T) {
t.Fatalf("deriveChallengeType(nil page) = %q, want empty string", got)
}
}
+
+// autosolver.SemanticSolverName is the single owner of the semantic stage's name.
+// A bare literal here compiles and passes every behavioural test, so the guard is
+// structural: it fails if the literal comes back.
+func TestSolverHandlerSpellsSemanticThroughItsOwner(t *testing.T) {
+ raw, err := os.ReadFile("solver.go")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if len(raw) == 0 {
+ t.Fatal("solver.go read empty — this guard is checking nothing")
+ }
+
+ literal := `"` + coreautosolver.SemanticSolverName + `"`
+ if strings.Contains(string(raw), literal) {
+ t.Errorf("solver.go spells %s as a literal; use coreautosolver.SemanticSolverName", literal)
+ }
+ if !strings.Contains(string(raw), "coreautosolver.SemanticSolverName") {
+ t.Errorf("solver.go no longer references coreautosolver.SemanticSolverName; the guard above would pass vacuously")
+ }
+}
+
+func solveErrorPayload(t *testing.T, w *httptest.ResponseRecorder) (code, message string) {
+ t.Helper()
+ var payload struct {
+ Code string `json:"code"`
+ Error string `json:"error"`
+ }
+ if err := json.Unmarshal(w.Body.Bytes(), &payload); err != nil {
+ t.Fatalf("decode error payload %q: %v", w.Body.String(), err)
+ }
+ return payload.Code, payload.Error
+}
+
+// capsolver with no API key is a known solver whose key is unset, not a typo.
+// Config validation accepts that exact name (TestValidateFileConfig_KnownSolverNamesAccepted,
+// row "key-gated without any key configured"), so the API must not call it unknown.
+func TestHandleSolveKeylessGatedSolverNamesTheMissingKey(t *testing.T) {
+ h := New(&mockBridge{}, &config.RuntimeConfig{}, nil, nil, nil)
+
+ for _, gated := range coreautosolver.KeyGatedSolvers() {
+ t.Run(gated.Name, func(t *testing.T) {
+ req := httptest.NewRequest("POST", "/solve", bytes.NewReader([]byte(`{"solver": "`+gated.Name+`"}`)))
+ w := httptest.NewRecorder()
+ h.HandleSolve(w, req)
+
+ if w.Code != 400 {
+ t.Fatalf("status = %d, want 400: %s", w.Code, w.Body.String())
+ }
+ code, message := solveErrorPayload(t, w)
+ if code != "solver_key_missing" {
+ t.Errorf("code = %q, want solver_key_missing — a keyless known solver is not an unknown name", code)
+ }
+ if !strings.Contains(message, gated.ConfigKey) {
+ t.Errorf("message %q does not name the missing key %q", message, gated.ConfigKey)
+ }
+ })
+ }
+}
+
+// The misspelling must keep the old code and keep listing what is available.
+func TestHandleSolveMisspelledSolverStaysUnknown(t *testing.T) {
+ h := New(&mockBridge{}, &config.RuntimeConfig{}, nil, nil, nil)
+
+ req := httptest.NewRequest("POST", "/solve", bytes.NewReader([]byte(`{"solver": "cloudlfare"}`)))
+ w := httptest.NewRecorder()
+ h.HandleSolve(w, req)
+
+ if w.Code != 400 {
+ t.Fatalf("status = %d, want 400: %s", w.Code, w.Body.String())
+ }
+ code, message := solveErrorPayload(t, w)
+ if code != "unknown_solver" {
+ t.Errorf("code = %q, want unknown_solver", code)
+ }
+ if !strings.Contains(message, "cloudlfare") {
+ t.Errorf("message %q does not name the rejected value", message)
+ }
+ for _, available := range h.availableAutoSolverNames() {
+ if !strings.Contains(message, available) {
+ t.Errorf("message %q omits available solver %q", message, available)
+ }
+ }
+}
+
+// Neither rejection may run a solver. Asserted by ordering rather than status
+// alone: this bridge cannot resolve a tab, so any path that got as far as
+// resolving one — let alone solving — would answer 404 the way
+// TestHandleSolve_TabNotFound does. A 400 proves the reject came first.
+func TestHandleSolveRejectionPrecedesAnySolveWork(t *testing.T) {
+ h := New(&mockBridge{failTab: true}, &config.RuntimeConfig{}, nil, nil, nil)
+
+ for _, name := range []string{coreautosolver.CapsolverSolverName, "cloudlfare"} {
+ t.Run(name, func(t *testing.T) {
+ req := httptest.NewRequest("POST", "/solve", bytes.NewReader([]byte(`{"solver": "`+name+`"}`)))
+ w := httptest.NewRecorder()
+ h.HandleSolve(w, req)
+
+ if w.Code == 404 {
+ t.Fatalf("got 404: the tab was resolved before the solver name was rejected")
+ }
+ if w.Code != 400 {
+ t.Fatalf("status = %d, want 400: %s", w.Code, w.Body.String())
+ }
+ })
+ }
+}