High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix: six inspect endpoints return 500 for a semantic selector that simply did not match, so an agent reads a bad selector as a server fault (PIN-175)
Luigi Agosti20043791733c
diff --git a/internal/handlers/action_selector_resolution.go b/internal/handlers/action_selector_resolution.goindex 527eed5e..56e64e10 100644--- a/internal/handlers/action_selector_resolution.go+++ b/internal/handlers/action_selector_resolution.go@@ -90,7 +90,7 @@ func (h *Handlers) resolveActionRequestSelectorInScope(if handled, err := h.applySemanticActionSelectorInScope(ctx, tabID, frameID, modalNodeID, sel, req); handled {if err != nil {- return actionSelectorResolution{status: semanticSelectorHTTPStatus(err)}, err+ return actionSelectorResolution{status: statusForElementErr(err)}, err}return actionSelectorResolution{}, nil}diff --git a/internal/handlers/count.go b/internal/handlers/count.goindex f0472ffa..bd2b8f08 100644--- a/internal/handlers/count.go+++ b/internal/handlers/count.go@@ -125,7 +125,7 @@ func (h *Handlers) countSemantic(ctx context.Context, tabID string, sel selectorreturn 0, fmt.Errorf("selector %q is not a semantic query", sel.String())}if h.Matcher == nil {- return 0, fmt.Errorf("semantic selectors require a matcher (not configured)")+ return 0, ErrSemanticMatcherUnavailable}frameID := h.selectorFrameID(tabID)diff --git a/internal/handlers/element_resolve.go b/internal/handlers/element_resolve.goindex 66b3f553..a62e991d 100644--- a/internal/handlers/element_resolve.go+++ b/internal/handlers/element_resolve.go@@ -4,12 +4,19 @@ import ("context""errors""fmt"+ "net/http""github.com/pinchtab/pinchtab/internal/bridge")var ErrElementNotFound = errors.New("element not found")+// ErrSemanticMatcherUnavailable is the one server fault in the semantic selector path:+// the feature is not configured, which is not the caller's mistake and not a missing+// element. It carries its own sentinel so the mapping below can keep answering 501 for+// it without asking what the message says.+var ErrSemanticMatcherUnavailable = errors.New("semantic selectors require a matcher (not configured)")+func (h *Handlers) resolveElementNodeID(ctx context.Context, tabID, sel string) (int64, error) {nodeID, err := h.resolveSelectorNodeID(ctx, tabID, sel)if err != nil {@@ -27,9 +34,22 @@ func (h *Handlers) resolveElementNodeID(ctx context.Context, tabID, sel string)return nodeID, nil}+// statusForElementErr is the ONE owner of the selector-failure status, for the inspect+// endpoints and the action path alike. It reads SENTINELS, never message text: a status+// keyed on wording changes the moment someone rewrites a sentence, and the semantic+// messages are rewritten often — the out-of-range one was reworded while this mapping+// was being unified.+//+// A selector that matched nothing is the caller's problem (404: re-snapshot and pick+// another). Everything else is the server's (500: retrying may help). Getting that+// backwards on a read endpoint sends retry storms at a page that is fine.func statusForElementErr(err error) int {- if errors.Is(err, ErrElementNotFound) {- return 404+ switch {+ case errors.Is(err, ErrSemanticMatcherUnavailable):+ return http.StatusNotImplemented+ case errors.Is(err, ErrElementNotFound):+ return http.StatusNotFound+ default:+ return http.StatusInternalServerError}- return 500}diff --git a/internal/handlers/semantic_selectors.go b/internal/handlers/semantic_selectors.goindex fa80de6a..65866637 100644--- a/internal/handlers/semantic_selectors.go+++ b/internal/handlers/semantic_selectors.go@@ -3,8 +3,6 @@ package handlersimport ("context""fmt"- "net/http"- "strings""github.com/pinchtab/pinchtab/internal/bridge""github.com/pinchtab/pinchtab/internal/selector"@@ -25,7 +23,7 @@ func (h *Handlers) applySemanticActionSelectorInScope(ctx context.Context, tabIDreturn false, nil}if h.Matcher == nil {- return true, fmt.Errorf("semantic selectors require a matcher (not configured)")+ return true, ErrSemanticMatcherUnavailable}var (@@ -91,7 +89,10 @@ func (h *Handlers) applySemanticActionSelectorInScope(ctx context.Context, tabID}target, ok := cache.Lookup(result.BestRef)if !ok || target.BackendNodeID == 0 {- return true, fmt.Errorf("semantic selector %q matched ref %s but no node is available", query, result.BestRef)+ // The snapshot named a ref the cache no longer holds: from the caller's side+ // that is a stale selector, not a broken server, so it carries the not-found+ // sentinel like the other misses.+ return true, fmt.Errorf("%w: semantic selector %q matched ref %s but no node is available", ErrElementNotFound, query, result.BestRef)}req.Ref = result.BestRefreq.NodeID = target.BackendNodeID@@ -129,26 +130,6 @@ func scopeSemanticNodesByFrame(nodes []bridge.A11yNode, frameID string) []bridgereturn filtered}-func semanticSelectorHTTPStatus(err error) int {- if err == nil {- return http.StatusOK- }- msg := strings.ToLower(err.Error())- switch {- case strings.Contains(msg, "not configured"):- return http.StatusNotImplemented- case strings.Contains(msg, "no matching element found"),- strings.Contains(msg, "is out of range"),- strings.Contains(msg, "no node is available"):- return http.StatusNotFound- case strings.Contains(msg, "no snapshot available"),- strings.Contains(msg, "no elements found"):- return http.StatusInternalServerError- default:- return http.StatusInternalServerError- }-}-// emptySemanticMatchError distinguishes an empty page from an index nobody can satisfy.// A positional nth: wrapper that runs off the end of the match set otherwise reports// "no matching element found" while the elements are plainly there, which reads as a@@ -158,13 +139,13 @@ func semanticSelectorHTTPStatus(err error) int {func (h *Handlers) emptySemanticMatchError(ctx context.Context, sel selector.Selector, query string, descs []semantic.ElementDescriptor) error {index, base, ok := sel.SemanticNthBase()if !ok {- return fmt.Errorf("semantic selector %q: no matching element found", query)+ return fmt.Errorf("%w: semantic selector %q: no matching element found", ErrElementNotFound, query)}matches := h.countSemanticMatches(ctx, base, descs)if matches == 0 {- return fmt.Errorf("semantic selector %q: no matching element found", sel.String())+ return fmt.Errorf("%w: semantic selector %q: no matching element found", ErrElementNotFound, sel.String())}- return fmt.Errorf("semantic selector %q: index %d is out of range, %q matched %d element(s)", sel.String(), index, base, matches)+ return fmt.Errorf("%w: semantic selector %q: index %d is out of range, %q matched %d element(s)", ErrElementNotFound, sel.String(), index, base, matches)}func (h *Handlers) countSemanticMatches(ctx context.Context, base string, descs []semantic.ElementDescriptor) int {diff --git a/internal/handlers/semantic_status_test.go b/internal/handlers/semantic_status_test.gonew file mode 100644index 00000000..7adc3ea9--- /dev/null+++ b/internal/handlers/semantic_status_test.go@@ -0,0 +1,211 @@+package handlers++import (+ "context"+ "errors"+ "fmt"+ "net/http"+ "net/http/httptest"+ "strings"+ "testing"+ "time"++ "github.com/pinchtab/pinchtab/internal/bridge"+ "github.com/pinchtab/pinchtab/internal/config"+ "github.com/pinchtab/pinchtab/internal/srccensus"+)++// semanticInspectHandlers serves three same-named buttons through the accessibility+// snapshot, which is all a semantic selector needs — no browser, so these run in CI.+func semanticInspectHandlers(t *testing.T, withMatcher bool) *Handlers {+ t.Helper()++ cache := &bridge.RefCache{+ Nodes: []bridge.A11yNode{+ {Ref: "e0", Role: "button", Name: "Save"},+ {Ref: "e1", Role: "button", Name: "Save"},+ {Ref: "e2", Role: "button", Name: "Save"},+ },+ Refs: map[string]int64{"e0": 1, "e1": 2, "e2": 3},+ }+ h := New(&findMockBridge{refCache: cache}, &config.RuntimeConfig{ActionTimeout: 10 * time.Second}, nil, nil, nil)+ if !withMatcher {+ // New always installs a matcher, so an unconfigured one has to be arranged+ // deliberately — see TestAnUnconfiguredMatcherIsNotAMissingElement.+ h.Matcher = nil+ }+ return h+}++// inspectEndpoints are the read surfaces that accept a semantic selector. The defect+// this covers is that the status mapping had one caller — the action path — so all six+// of these answered 500 for a selector that simply did not match, telling an agent to+// retry a page that is fine instead of to re-snapshot and pick another selector.+var inspectEndpoints = []struct {+ name string+ path string+ // countsMatches marks the endpoint whose answer to "nothing matched" is a NUMBER+ // rather than a refusal: /count reports zero, which is the correct answer to how+ // many elements match, not an error. Every other endpoint has to return an element.+ countsMatches bool+ serve func(*Handlers, http.ResponseWriter, *http.Request)+}{+ {name: "attr", path: "/attr?name=id&selector=", serve: func(h *Handlers, w http.ResponseWriter, r *http.Request) { h.HandleGetAttr(w, r) }},+ {name: "value", path: "/value?selector=", serve: func(h *Handlers, w http.ResponseWriter, r *http.Request) { h.HandleGetValue(w, r) }},+ {name: "enabled", path: "/enabled?selector=", serve: func(h *Handlers, w http.ResponseWriter, r *http.Request) { h.HandleGetEnabled(w, r) }},+ {name: "visible", path: "/visible?selector=", serve: func(h *Handlers, w http.ResponseWriter, r *http.Request) { h.HandleGetVisible(w, r) }},+ {name: "checked", path: "/checked?selector=", serve: func(h *Handlers, w http.ResponseWriter, r *http.Request) { h.HandleGetChecked(w, r) }},+ {name: "count", path: "/count?selector=", countsMatches: true, serve: func(h *Handlers, w http.ResponseWriter, r *http.Request) { h.HandleCount(w, r) }},+}++func serveInspect(t *testing.T, h *Handlers, index int, selectorValue string) *httptest.ResponseRecorder {+ t.Helper()+ endpoint := inspectEndpoints[index]+ req := httptest.NewRequest("GET", endpoint.path+strings.ReplaceAll(selectorValue, " ", "%20"), nil)+ w := httptest.NewRecorder()+ endpoint.serve(h, w, req)+ return w+}++// A selector that matched nothing is the caller's problem, so it must read as 404 on+// every read surface — asserted through the HANDLER, because the mapper being right is+// what the previous test proved while five callers never reached it.+func TestASemanticSelectorThatMatchesNothingIs404OnEveryInspectEndpoint(t *testing.T) {+ for index, endpoint := range inspectEndpoints {+ t.Run(endpoint.name, func(t *testing.T) {+ w := serveInspect(t, semanticInspectHandlers(t, true), index, "role:slider Volume")++ if endpoint.countsMatches {+ if w.Code != http.StatusOK || !strings.Contains(w.Body.String(), `"count":0`) {+ t.Fatalf("status = %d body %s, want 200 with a count of 0 — zero is the answer to how many matched", w.Code, w.Body.String())+ }+ return+ }+ if w.Code != http.StatusNotFound {+ t.Fatalf("status = %d, want 404; a 5xx tells an agent to retry a page that is fine (body %s)", w.Code, w.Body.String())+ }+ if !strings.Contains(w.Body.String(), "no matching element found") {+ t.Errorf("body %s does not say the selector matched nothing", w.Body.String())+ }+ })+ }+}++// The out-of-range refusal keeps naming the caller's zero-based index and the bare+// selector's match count, at 404, on every read surface.+func TestAnOutOfRangeWrapperIndexIs404OnEveryInspectEndpoint(t *testing.T) {+ for index, endpoint := range inspectEndpoints {+ t.Run(endpoint.name, func(t *testing.T) {+ w := serveInspect(t, semanticInspectHandlers(t, true), index, "nth:7:role:button Save")++ if w.Code != http.StatusNotFound {+ t.Fatalf("status = %d, want 404 (body %s)", w.Code, w.Body.String())+ }+ body := w.Body.String()+ for _, needle := range []string{"index 7", "out of range", "3 element(s)"} {+ if !strings.Contains(body, needle) {+ t.Errorf("body %s does not carry %q", body, needle)+ }+ }+ if strings.Contains(body, "nth:8") {+ t.Errorf("body %s names the translated one-based index instead of what the caller sent", body)+ }+ })+ }+}++// Criterion five: do not blanket-404 the inspect path. An unconfigured matcher is a+// server-side gap, not a bad selector, and it keeps its own code on every surface.+func TestAnUnconfiguredMatcherIsNotAMissingElement(t *testing.T) {+ for index, endpoint := range inspectEndpoints {+ t.Run(endpoint.name, func(t *testing.T) {+ w := serveInspect(t, semanticInspectHandlers(t, false), index, "role:button Save")++ if w.Code != http.StatusNotImplemented {+ t.Fatalf("status = %d, want 501 for an unconfigured matcher (body %s)", w.Code, w.Body.String())+ }+ })+ }+}++// The action path and the inspect path must reach the SAME mapping. A second copy of+// the switch is how they drifted apart, so this asserts agreement per outcome rather+// than trusting that both call the same name today.+func TestBothPathsAgreeOnTheStatusForTheSameFailure(t *testing.T) {+ h := semanticInspectHandlers(t, true)++ for _, tc := range []struct {+ name string+ selector string+ want int+ }{+ {"no match", "role:slider Volume", http.StatusNotFound},+ {"out of range", "nth:7:role:button Save", http.StatusNotFound},+ } {+ t.Run(tc.name, func(t *testing.T) {+ // The in-scope resolver, not resolveActionRequestSelector: the outer one+ // probes the topmost dialog through CDP, which no mock can answer.+ req := bridge.ActionRequest{Selector: tc.selector}+ resolution, err := h.resolveActionRequestSelectorInScope(context.Background(), "tab1", "", 0, false, &req)+ if err == nil {+ t.Fatal("the action path accepted a selector the inspect path refuses")+ }+ if resolution.status != tc.want {+ t.Errorf("action path status = %d, want %d", resolution.status, tc.want)+ }+ if w := serveInspect(t, h, 0, tc.selector); w.Code != resolution.status {+ t.Errorf("inspect /attr answered %d while the action path answered %d for the same failure", w.Code, resolution.status)+ }+ })+ }+}++// The status must come from the sentinel, not from the wording. The out-of-range+// message was being reworded while this mapping was unified, and a status keyed on text+// silently changes with it.+func TestTheStatusSurvivesRewordingTheMessage(t *testing.T) {+ for _, tc := range []struct {+ name string+ err error+ want int+ }{+ {"reworded miss keeps its 404", fmt.Errorf("%w: absolutely nothing like that on the page", ErrElementNotFound), http.StatusNotFound},+ {"reworded unavailable keeps its 501", fmt.Errorf("%w: turn the matcher on", ErrSemanticMatcherUnavailable), http.StatusNotImplemented},+ {"the old wording alone buys nothing", errors.New("no matching element found"), http.StatusInternalServerError},+ {"out-of-range wording alone buys nothing", errors.New(`index 7 is out of range, "role:button Save" matched 3 element(s)`), http.StatusInternalServerError},+ {"not-configured wording alone buys nothing", errors.New("semantic selectors require a matcher (not configured)"), http.StatusInternalServerError},+ } {+ t.Run(tc.name, func(t *testing.T) {+ if got := statusForElementErr(tc.err); got != tc.want {+ t.Errorf("statusForElementErr(%v) = %d, want %d", tc.err, got, tc.want)+ }+ })+ }+}++// Criterion three, structurally: both paths must REACH the one mapper. The inspect path+// and the action path each mapped selector failures themselves, and the two switches+// drifted — semantic misses answered 404 on /action and 500 on all six read endpoints.+//+// This pins the call sites; TestBothPathsAgreeOnTheStatusForTheSameFailure pins the+// outcome. Both are needed: a census cannot see a second mapper under a new name, and an+// agreement test cannot see a caller that stops mapping at all.+func TestOneMapperServesBothTheInspectAndActionPaths(t *testing.T) {+ pkg := srccensus.Load(t, ".", 20)++ callers := map[string]bool{}+ for _, site := range pkg.Calls(t, "statusForElementErr") {+ callers[site.Func] = true+ }+ for _, required := range []string{"inspectElement", "resolveActionRequestSelectorInScope"} {+ if !callers[required] {+ t.Errorf("%s no longer maps its selector failures through statusForElementErr; a second copy of the status switch is how the inspect and action paths drifted apart", required)+ }+ }++ // The string-matching mapper is gone on purpose: a status keyed on message text+ // changes whenever a sentence is reworded, and these messages are reworded often.+ if _, found := pkg.Func("semanticSelectorHTTPStatus"); found {+ t.Error("semanticSelectorHTTPStatus is back; the semantic statuses come from sentinels now, so a message-matching mapper would silently re-key them on wording")+ }+}diff --git a/internal/handlers/semantic_wrapper_index_test.go b/internal/handlers/semantic_wrapper_index_test.goindex 260b4640..fe3aa205 100644--- a/internal/handlers/semantic_wrapper_index_test.go+++ b/internal/handlers/semantic_wrapper_index_test.go@@ -3,6 +3,7 @@ package handlersimport ("context""encoding/base64"+ "errors""fmt""os""strings"@@ -93,8 +94,12 @@ func TestAnOutOfRangeWrapperIndexSaysSoInsteadOfNoMatch(t *testing.T) {if strings.Contains(msg, "nth:8") {t.Errorf("refusal %q names the translated one-based index; it must name what the caller sent", msg)}- if status := semanticSelectorHTTPStatus(err); status != 404 {- t.Errorf("out-of-range refusal maps to HTTP %d, want 404 rather than a 500 that reads as a server fault", status)+ // The status itself is asserted at the HTTP boundary in semantic_status_test.go —+ // a mapper can be correct while nobody calls it, which is exactly what happened+ // here. What this layer owns is that the refusal CARRIES the sentinel every caller+ // maps from.+ if !errors.Is(err, ErrElementNotFound) {+ t.Errorf("out-of-range refusal does not wrap ErrElementNotFound, so every caller has to recognise it by wording")}}