Skip to content

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

fix: a typo in autoSolver.solvers silently changes which solvers run (PIN-068)

Luigi Agostiff22ab98c704
diff --git a/internal/autosolver/autosolver.go b/internal/autosolver/autosolver.go
index cffe1746..b4e846a6 100644
--- a/internal/autosolver/autosolver.go
+++ b/internal/autosolver/autosolver.go
@@ -200,9 +200,14 @@ func (as *AutoSolver) orderSolvers(matching []Solver) []Solver {
available = append(available, name)
}
sort.Strings(available)
- slog.Debug("autosolver: configured solver order not found, using priority order",
+ // Warn, not debug: every configured solver is unavailable, so the run
+ // silently uses solvers the operator never listed. Refusing to solve
+ // would be the worse failure, so the fallback stays — but it stops
+ // being invisible at the default log level.
+ slog.Warn("autosolver: no configured solver is available, falling back to priority order",
"configured", as.config.Solvers,
- "available", available)
+ "unavailable", missing,
+ "running", available)
return matching
}
@@ -272,7 +277,7 @@ func (as *AutoSolver) trySolvers(ctx context.Context, page Page, executor Action
}
func (as *AutoSolver) trySemantic(ctx context.Context, page Page, executor ActionExecutor, intent *Intent) (bool, *AttemptEntry) {
- entry := &AttemptEntry{Solver: "semantic"}
+ entry := &AttemptEntry{Solver: SemanticSolverName}
semanticStart := time.Now()
if as.semantic == nil {
diff --git a/internal/autosolver/autosolver_test.go b/internal/autosolver/autosolver_test.go
index 6d796c40..8ff30932 100644
--- a/internal/autosolver/autosolver_test.go
+++ b/internal/autosolver/autosolver_test.go
@@ -3,6 +3,7 @@ package autosolver
import (
"context"
"fmt"
+ "log/slog"
"reflect"
"strings"
"testing"
@@ -1075,3 +1076,90 @@ func TestOrderSolversDoesNotMutateInput(t *testing.T) {
t.Fatalf("input reordered in place: %v -> %v", before, after)
}
}
+
+type levelRecorder struct {
+ records []slog.Record
+}
+
+func (r *levelRecorder) Enabled(context.Context, slog.Level) bool { return true }
+func (r *levelRecorder) Handle(_ context.Context, rec slog.Record) error {
+ r.records = append(r.records, rec.Clone())
+ return nil
+}
+func (r *levelRecorder) WithAttrs([]slog.Attr) slog.Handler { return r }
+func (r *levelRecorder) WithGroup(string) slog.Handler { return r }
+
+func (r *levelRecorder) find(t *testing.T, minLevel slog.Level, substr string) slog.Record {
+ t.Helper()
+ for _, rec := range r.records {
+ if rec.Level >= minLevel && strings.Contains(rec.Message, substr) {
+ return rec
+ }
+ }
+ for _, rec := range r.records {
+ if strings.Contains(rec.Message, substr) {
+ t.Fatalf("%q was logged at %s, want %s or above — an operator never sees it at the default level",
+ rec.Message, rec.Level, minLevel)
+ }
+ }
+ t.Fatalf("no log line containing %q (%d records)", substr, len(r.records))
+ return slog.Record{}
+}
+
+func recordAttrs(rec slog.Record) string {
+ var sb strings.Builder
+ rec.Attrs(func(a slog.Attr) bool {
+ fmt.Fprintf(&sb, "%s=%v ", a.Key, a.Value)
+ return true
+ })
+ return sb.String()
+}
+
+// After typo rejection, zero-match is still reachable: every configured solver
+// known but unavailable, e.g. capsolver named without its API key. The fallback
+// stays — refusing to solve is the worse failure — but it must be visible.
+func TestOrderSolversWarnsWhenNoConfiguredSolverIsAvailable(t *testing.T) {
+ recorder := &levelRecorder{}
+ previous := slog.Default()
+ slog.SetDefault(slog.New(recorder))
+ t.Cleanup(func() { slog.SetDefault(previous) })
+
+ priorityOrder := []Solver{
+ &mockSolver{name: "cloudflare", priority: 10},
+ &mockSolver{name: "jschallenge", priority: 20},
+ }
+ as := New(Config{Solvers: []string{"capsolver", "twocaptcha"}}, nil, nil)
+
+ got := solverNames(as.orderSolvers(priorityOrder))
+
+ if want := []string{"cloudflare", "jschallenge"}; !reflect.DeepEqual(got, want) {
+ t.Fatalf("fallback returned %v, want the priority order %v", got, want)
+ }
+
+ rec := recorder.find(t, slog.LevelWarn, "falling back to priority order")
+ attrs := recordAttrs(rec)
+ for _, want := range []string{"capsolver", "twocaptcha", "cloudflare", "jschallenge"} {
+ if !strings.Contains(attrs, want) {
+ t.Errorf("warn line does not name %q: %s", want, attrs)
+ }
+ }
+}
+
+// The partial-match case fires on the shipped default (semantic is a stage, not
+// a registry solver, so it never matches), so it stays below warn — promoting it
+// would put a warning in front of every operator on every run.
+func TestOrderSolversDoesNotWarnOnPartialMatch(t *testing.T) {
+ recorder := &levelRecorder{}
+ previous := slog.Default()
+ slog.SetDefault(slog.New(recorder))
+ t.Cleanup(func() { slog.SetDefault(previous) })
+
+ as := New(Config{Solvers: []string{"cloudflare", "capsolver"}}, nil, nil)
+ as.orderSolvers([]Solver{&mockSolver{name: "cloudflare", priority: 10}})
+
+ for _, rec := range recorder.records {
+ if rec.Level >= slog.LevelWarn {
+ t.Errorf("partial match logged at %s: %q — the shipped default hits this path every run", rec.Level, rec.Message)
+ }
+ }
+}
diff --git a/internal/autosolver/catalog/catalog.go b/internal/autosolver/catalog/catalog.go
new file mode 100644
index 00000000..04c3b640
--- /dev/null
+++ b/internal/autosolver/catalog/catalog.go
@@ -0,0 +1,73 @@
+// Package catalog is the single owner of the names autoSolver.solvers accepts.
+// Every name comes from the thing that answers to it — the solver types' own
+// Name() methods, and the built-in stage's exported name — so adding a solver
+// cannot leave config validation stale behind a second hand-written list.
+package catalog
+
+import (
+ "sort"
+
+ "github.com/pinchtab/pinchtab/internal/autosolver"
+ "github.com/pinchtab/pinchtab/internal/autosolver/external"
+ "github.com/pinchtab/pinchtab/internal/autosolver/solvers"
+)
+
+// registrable is one instance of each solver type that can enter the registry,
+// built with zero config because only Name() is read. KeyGated members are here
+// too: their name is always valid, and whether they register is a separate
+// question answered by the API key.
+func registrable() []autosolver.Solver {
+ return []autosolver.Solver{
+ &solvers.Cloudflare{},
+ &solvers.JSChallenge{},
+ external.NewCapsolver(external.CapsolverConfig{}),
+ external.NewTwoCaptcha(external.TwoCaptchaConfig{}),
+ }
+}
+
+// KeyGated reports the solvers that only register when their API key is set.
+// Naming one without its key is a missing-key mistake, not an unknown solver.
+func KeyGated() []string {
+ return []string{
+ external.NewCapsolver(external.CapsolverConfig{}).Name(),
+ external.NewTwoCaptcha(external.TwoCaptchaConfig{}).Name(),
+ }
+}
+
+// AlwaysRegistered reports the solvers that need no configuration to run.
+func AlwaysRegistered() []string {
+ gated := map[string]struct{}{}
+ for _, name := range KeyGated() {
+ gated[name] = struct{}{}
+ }
+ names := []string{autosolver.SemanticSolverName}
+ for _, s := range registrable() {
+ if _, ok := gated[s.Name()]; ok {
+ continue
+ }
+ names = append(names, s.Name())
+ }
+ sort.Strings(names)
+ return names
+}
+
+// Names is every value autoSolver.solvers may contain, sorted so error messages
+// and tests read the same way every run.
+func Names() []string {
+ names := make([]string, 0, len(registrable())+1)
+ for _, s := range registrable() {
+ names = append(names, s.Name())
+ }
+ names = append(names, autosolver.SemanticSolverName)
+ sort.Strings(names)
+ return names
+}
+
+func IsKnown(name string) bool {
+ for _, known := range Names() {
+ if known == name {
+ return true
+ }
+ }
+ return false
+}
diff --git a/internal/autosolver/types.go b/internal/autosolver/types.go
index 65829eb6..21a47b11 100644
--- a/internal/autosolver/types.go
+++ b/internal/autosolver/types.go
@@ -2,6 +2,12 @@ package autosolver
import "time"
+// SemanticSolverName is what the built-in semantic stage answers to. It is a
+// stage rather than a registry solver, so it has no Name() method to own its
+// name — this constant is that owner, for the attempt entries it reports and
+// for the names autoSolver.solvers accepts.
+const SemanticSolverName = "semantic"
+
// IntentType classifies the detected page state.
type IntentType string
@@ -160,7 +166,7 @@ func DefaultConfig() Config {
Enabled: true,
MaxAttempts: 8,
SolverTimeout: 30 * time.Second,
- Solvers: []string{"cloudflare", "semantic"},
+ Solvers: []string{"cloudflare", SemanticSolverName},
LLMFallback: false,
RetryBaseDelay: 500 * time.Millisecond,
RetryMaxDelay: 10 * time.Second,
diff --git a/internal/config/validate.go b/internal/config/validate.go
index d3d9b854..377d3a0a 100644
--- a/internal/config/validate.go
+++ b/internal/config/validate.go
@@ -10,6 +10,7 @@ import (
"strconv"
"strings"
+ "github.com/pinchtab/pinchtab/internal/autosolver/catalog"
"github.com/pinchtab/pinchtab/internal/browsers"
"github.com/pinchtab/pinchtab/internal/config/geo"
)
@@ -280,6 +281,19 @@ func ValidateFileConfig(fc *FileConfig) []error {
break
}
}
+ // An unmatched name does not fail at run time, it changes which solvers run:
+ // one typo alongside good names silently drops that solver, and a list of
+ // only typos silently runs every solver instead.
+ for i, solverName := range fc.AutoSolver.Solvers {
+ name := strings.TrimSpace(solverName)
+ if name == "" || catalog.IsKnown(name) {
+ continue
+ }
+ errs = append(errs, ValidationError{
+ Field: fmt.Sprintf("autoSolver.solvers[%d]", i),
+ Message: fmt.Sprintf("unknown solver %q (known: %v)", name, catalog.Names()),
+ })
+ }
if fc.Observability.Activity.SessionIdleSec != nil && *fc.Observability.Activity.SessionIdleSec < 0 {
errs = append(errs, ValidationError{
diff --git a/internal/config/validate_test.go b/internal/config/validate_test.go
index eabe3877..46f156f3 100644
--- a/internal/config/validate_test.go
+++ b/internal/config/validate_test.go
@@ -6,6 +6,8 @@ import (
"sync"
"testing"
+ "github.com/pinchtab/pinchtab/internal/autosolver"
+ "github.com/pinchtab/pinchtab/internal/autosolver/catalog"
"github.com/pinchtab/pinchtab/internal/browsers"
_ "github.com/pinchtab/pinchtab/internal/browsers/chrome"
_ "github.com/pinchtab/pinchtab/internal/browsers/cloak"
@@ -1111,3 +1113,82 @@ func TestValidationAcceptsRegisteredStubProvider(t *testing.T) {
}
}
}
+
+// A misspelled solver name never failed at run time; it changed which solvers
+// ran, and in opposite directions depending on how many other names matched.
+func TestValidateFileConfig_UnknownSolverName(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ solvers []string
+ bad string
+ }{
+ {
+ name: "one typo beside a good name silently dropped that solver",
+ solvers: []string{"cloudlfare", "semantic"},
+ bad: "cloudlfare",
+ },
+ {
+ name: "every name a typo silently ran the whole registry",
+ solvers: []string{"cloudlfare"},
+ bad: "cloudlfare",
+ },
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ errs := ValidateFileConfig(&FileConfig{
+ AutoSolver: AutoSolverFileConfig{Solvers: tc.solvers},
+ })
+
+ var msg string
+ for _, err := range errs {
+ if strings.Contains(err.Error(), tc.bad) {
+ msg = err.Error()
+ }
+ }
+ if msg == "" {
+ t.Fatalf("solvers %v produced no error naming %q: %v", tc.solvers, tc.bad, errs)
+ }
+ if !strings.Contains(msg, "autoSolver.solvers") {
+ t.Errorf("error does not name the field: %s", msg)
+ }
+ for _, known := range catalog.Names() {
+ if !strings.Contains(msg, known) {
+ t.Errorf("error does not list the valid name %q: %s", known, msg)
+ }
+ }
+ })
+ }
+}
+
+// Key-gated solvers are valid names whether or not their key is set — naming
+// one without its key is a different mistake, not an unknown solver.
+func TestValidateFileConfig_KnownSolverNamesAccepted(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ solvers []string
+ }{
+ {"full set", catalog.Names()},
+ {"subset", []string{"cloudflare", "semantic"}},
+ {"reordering", []string{"semantic", "jschallenge", "cloudflare"}},
+ {"key-gated without any key configured", catalog.KeyGated()},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ errs := ValidateFileConfig(&FileConfig{
+ AutoSolver: AutoSolverFileConfig{Solvers: tc.solvers},
+ })
+ for _, err := range errs {
+ if strings.Contains(err.Error(), "autoSolver.solvers") {
+ t.Errorf("solvers %v rejected: %s", tc.solvers, err)
+ }
+ }
+ })
+ }
+}
+
+// The shipped default must satisfy the validator it now passes through.
+func TestValidateFileConfig_DefaultSolversAreKnown(t *testing.T) {
+ for _, name := range autosolver.DefaultConfig().Solvers {
+ if !catalog.IsKnown(name) {
+ t.Errorf("default config names solver %q, which validation rejects (known: %v)", name, catalog.Names())
+ }
+ }
+}
diff --git a/internal/handlers/autosolver.go b/internal/handlers/autosolver.go
index cf5c744b..8daf82ed 100644
--- a/internal/handlers/autosolver.go
+++ b/internal/handlers/autosolver.go
@@ -9,6 +9,7 @@ import (
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/autosolver/external"
autosolverllm "github.com/pinchtab/pinchtab/internal/autosolver/llm"
autosolversemantic "github.com/pinchtab/pinchtab/internal/autosolver/semantic"
@@ -250,10 +251,9 @@ func (h *Handlers) buildAutoSolver(cfg coreautosolver.Config, includeSemantic bo
func (h *Handlers) availableAutoSolverNames() []string {
cfg := h.normalizedAutoSolverConfig()
- available := map[string]bool{
- "cloudflare": true,
- "semantic": true,
- "jschallenge": true,
+ available := map[string]bool{}
+ for _, name := range catalog.AlwaysRegistered() {
+ available[name] = true
}
if h != nil && h.Config != nil {
if strings.TrimSpace(h.Config.AutoSolver.CapsolverKey) != "" {
@@ -277,7 +277,7 @@ func (h *Handlers) availableAutoSolverNames() []string {
seen[configured] = struct{}{}
}
- for _, fallback := range []string{"cloudflare", "semantic", "jschallenge"} {
+ for _, fallback := range catalog.AlwaysRegistered() {
if !available[fallback] {
continue
}
diff --git a/internal/handlers/autosolver_test.go b/internal/handlers/autosolver_test.go
index 04233b35..a72d3cf7 100644
--- a/internal/handlers/autosolver_test.go
+++ b/internal/handlers/autosolver_test.go
@@ -2,10 +2,13 @@ package handlers
import (
"context"
+ "slices"
"sync/atomic"
"testing"
"time"
+ coreautosolver "github.com/pinchtab/pinchtab/internal/autosolver"
+ "github.com/pinchtab/pinchtab/internal/autosolver/catalog"
"github.com/pinchtab/pinchtab/internal/config"
)
@@ -150,3 +153,34 @@ func TestMaybeAutoSolve_InvokesRunnerWhenEnabled(t *testing.T) {
t.Fatalf("autoSolverRunner calls with navigate trigger disabled = %d, want unchanged", got)
}
}
+
+// The catalog is only a single owner if what actually registers stays inside it.
+// A new solver wired into buildAutoSolver but not added to the catalog would
+// leave config validation rejecting a name the product really accepts, and this
+// is the link that fails when that happens.
+func TestRegisteredSolversAreAllKnownToTheCatalog(t *testing.T) {
+ h := &Handlers{Config: &config.RuntimeConfig{AutoSolver: config.AutoSolverConfig{
+ CapsolverKey: "test-capsolver-key",
+ TwoCaptchaKey: "test-twocaptcha-key",
+ }}}
+
+ as := h.buildAutoSolver(coreautosolver.DefaultConfig(), true)
+ registered := as.Registry().Names()
+ if len(registered) == 0 {
+ t.Fatal("no solvers registered — this guard is checking nothing")
+ }
+
+ for _, name := range registered {
+ if !catalog.IsKnown(name) {
+ t.Errorf("solver %q registers but config validation rejects it (known: %v)", name, catalog.Names())
+ }
+ }
+
+ // Both key-gated solvers registered above, so the catalog's key-gated list is
+ // the real one rather than a guess.
+ for _, gated := range catalog.KeyGated() {
+ if !slices.Contains(registered, gated) {
+ t.Errorf("catalog lists %q as key-gated but it did not register with a key set (registered: %v)", gated, registered)
+ }
+ }
+}