Skip to content

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

fix: a stale-ref click that submits a form places the order and then answers 'ref not found and recovery failed', so the natural retry double-submits (PIN-234)

Luigi Agostie0750c8131c4
diff --git a/internal/handlers/action_execution.go b/internal/handlers/action_execution.go
index 8d6a050f..df7dc61a 100644
--- a/internal/handlers/action_execution.go
+++ b/internal/handlers/action_execution.go
@@ -149,6 +149,48 @@ func (h *Handlers) cacheActionIntent(tabID string, req bridge.ActionRequest) {
})
}
+// ErrStaleSubmitTarget refuses a click whose ref is stale and whose target submits a
+// form. The exactly-once rule the submit path already states cannot be honoured by an
+// automatic retry, and the DOM — not the request — decides whether a click submits: an
+// agent working from a snapshot row `e2:button "Place order"` has no way to declare it.
+//
+// Submit-detection is a PROXY for non-idempotency, not a solution to it. A delete link is
+// as dangerous and the DOM cannot say so; a policy for non-idempotent clicks at large is a
+// separate decision and this refusal does not claim to cover the class.
+var ErrStaleSubmitTarget = errors.New("ref is stale and its target submits a form; take a /snapshot first and click the fresh ref")
+
+// submitControlJS reports whether the node is the control that submits a form. A var so a
+// test can stub it: the guard's own effect is only visible against a real page, and the
+// stub is how the pre-fix dispatch is reproduced. A <button>
+// inside a form submits by DEFAULT — an absent type attribute means submit — which is the
+// case an agent is least likely to have declared. The closest ancestor is consulted so a
+// click landing on a <span> inside the button answers for the button.
+var submitControlJS = `function() {
+ var el = this.closest ? this.closest('button, input') : null;
+ if (!el || !el.form) return false;
+ var type = (el.getAttribute('type') || '').toLowerCase();
+ if (el.tagName.toLowerCase() === 'input') return type === 'submit' || type === 'image';
+ return type === '' || type === 'submit';
+}`
+
+// recoveredNodeSubmits answers whether a click about to be dispatched at a recovered node
+// would submit a form. Only clicks are asked: no other action kind dispatches a submit,
+// and a read of the DOM per recovery attempt is not free.
+//
+// A failed read answers false. The alternative — refusing when the page cannot be read —
+// would turn every transport hiccup into a refusal on the ordinary stale-link path, which
+// is the far more common one.
+func (h *Handlers) recoveredNodeSubmits(ctx context.Context, req bridge.ActionRequest, nodeID int64) bool {
+ if bridge.CanonicalActionKind(req.Kind) != bridge.ActionClick || nodeID <= 0 {
+ return false
+ }
+ var submits bool
+ if err := h.Bridge.CallFunctionOnNode(ctx, nodeID, submitControlJS, nil, &submits); err != nil {
+ return false
+ }
+ return submits
+}
+
func (h *Handlers) executeAction(ctx context.Context, req bridge.ActionRequest, cfg *config.RuntimeConfig) (map[string]any, string, error) {
req.Kind = bridge.CanonicalActionKind(req.Kind)
@@ -169,12 +211,20 @@ func (h *Handlers) executeActionResilient(ctx context.Context, req *bridge.Actio
submitClick := bridge.IsSubmitClick(req.Kind, *req)
if refMissing {
if submitClick {
- return nil, "", nil, fmt.Errorf("click submit target is unresolved; automatic recovery is disabled")
+ return nil, "", nil, ErrStaleSubmitTarget
}
rr, recRes, recErr := h.Recovery.Attempt(
ctx, resolvedTabID, req.Ref, req.Kind,
func(c context.Context, _ string, nodeID int64) (map[string]any, error) {
req.NodeID = nodeID
+ // The caller did not declare a submit, but whether a click submits a form
+ // is a property of the page. Recovery is about to dispatch at a node it
+ // MATCHED rather than resolved, and a submit dispatched at a guessed
+ // target cannot be taken back — so this refuses before the click rather
+ // than reporting afterwards.
+ if h.recoveredNodeSubmits(c, *req, nodeID) {
+ return nil, ErrStaleSubmitTarget
+ }
if secErr := h.refreshActionSecondaryTargets(c, resolvedTabID, req); secErr != nil {
return nil, secErr
}
@@ -183,6 +233,17 @@ func (h *Handlers) executeActionResilient(ctx context.Context, req *bridge.Actio
},
)
if recErr != nil {
+ // The action RAN: the click landed and moved the page, and the guard reports
+ // that navigation from inside the callback. Wrapping it as "ref not found and
+ // recovery failed" asserted two false things about a dispatch that happened,
+ // and the natural retry then repeats it. The navigation is passed through
+ // unwrapped so this answers what the same click answers with a fresh ref.
+ if errors.Is(recErr, bridge.ErrUnexpectedNavigation) || errors.Is(recErr, ErrStaleSubmitTarget) {
+ // No recovery block either: nothing was re-resolved. A block reading
+ // recovered:true with a low-confidence score is a record of a match made
+ // against the page the click already navigated to.
+ return nil, "", nil, recErr
+ }
return nil, "", &rr, fmt.Errorf("ref %s not found and recovery failed: %w", req.Ref, recErr)
}
return recRes, "", &rr, nil
diff --git a/internal/handlers/action_stale_submit_test.go b/internal/handlers/action_stale_submit_test.go
new file mode 100644
index 00000000..1240dd37
--- /dev/null
+++ b/internal/handlers/action_stale_submit_test.go
@@ -0,0 +1,176 @@
+package handlers
+
+import (
+ "context"
+ "errors"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "sync/atomic"
+ "testing"
+ "time"
+
+ "github.com/chromedp/chromedp"
+ "github.com/pinchtab/pinchtab/internal/bridge"
+ "github.com/pinchtab/pinchtab/internal/config"
+ "github.com/pinchtab/pinchtab/internal/testbrowser"
+ "github.com/pinchtab/semantic"
+ "github.com/pinchtab/semantic/recovery"
+)
+
+// orderFixture serves a form whose button posts an order, and counts the posts. The counter
+// is the instrument this card turns on: a response saying the ref was not found is only
+// wrong if an order was placed anyway, and no assertion on the response text can show that.
+type orderFixture struct {
+ server *httptest.Server
+ orders *int64
+}
+
+func newOrderFixture(t *testing.T) orderFixture {
+ t.Helper()
+ var orders int64
+ mux := http.NewServeMux()
+ mux.HandleFunc("/order", func(w http.ResponseWriter, r *http.Request) {
+ if r.Method == http.MethodPost {
+ atomic.AddInt64(&orders, 1)
+ }
+ w.Header().Set("Content-Type", "text/html")
+ _, _ = w.Write([]byte(`<h1>Order placed</h1>`))
+ })
+ mux.HandleFunc("/", func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Content-Type", "text/html")
+ _, _ = w.Write([]byte(`<h1>Checkout</h1>
+ <form action="/order" method="post"><button id="b">Place order</button></form>`))
+ })
+ srv := httptest.NewServer(mux)
+ t.Cleanup(srv.Close)
+ return orderFixture{server: srv, orders: &orders}
+}
+
+func (f orderFixture) placed() int64 { return atomic.LoadInt64(f.orders) }
+
+// settleForOrder waits for a post that may still be in flight. A form submission is
+// dispatched by the browser and arrives at the server after the call returns, so reading
+// the counter immediately would let a placed order pass as none — the exact failure this
+// fixture exists to detect.
+func (f orderFixture) settleForOrder() int64 {
+ for i := 0; i < 40 && f.placed() == 0; i++ {
+ time.Sleep(50 * time.Millisecond)
+ }
+ return f.placed()
+}
+
+// staleSubmitHandlers stands up a real browser on the checkout page with handlers whose
+// recovery engine is the production one, and records the intent a snapshot would have
+// cached for the button's ref. That intent is what recovery matches on, so this reproduces
+// the state the card describes: a ref the cache no longer resolves, whose remembered
+// descriptor still names the submit button.
+func staleSubmitHandlers(t *testing.T, f orderFixture) (*Handlers, context.Context, string) {
+ t.Helper()
+ chromePath := testbrowser.Path(t)
+ profile := testbrowser.ProfileDir(t)
+ alloc, cancelAlloc := chromedp.NewExecAllocator(context.Background(), append(
+ chromedp.DefaultExecAllocatorOptions[:],
+ chromedp.ExecPath(chromePath),
+ chromedp.UserDataDir(profile),
+ chromedp.Flag("headless", true),
+ chromedp.Flag("no-sandbox", true),
+ )...)
+ ctx, cancelBrowser := chromedp.NewContext(alloc)
+ ctx, cancelTimeout := context.WithTimeout(ctx, 30*time.Second)
+ t.Cleanup(func() {
+ cancelTimeout()
+ cancelBrowser()
+ cancelAlloc()
+ })
+
+ if err := chromedp.Run(ctx,
+ chromedp.Navigate(f.server.URL+"/"),
+ chromedp.WaitVisible("#b", chromedp.ByID),
+ ); err != nil {
+ t.Fatal(err)
+ }
+
+ cfg := &config.RuntimeConfig{ActionTimeout: 10 * time.Second, DefaultBrowser: config.BrowserChrome, StateDir: t.TempDir()}
+ b := bridge.New(context.Background(), ctx, cfg)
+ const tabID = "tab-stale-submit"
+ b.RegisterTab(tabID, ctx)
+ h := New(b, cfg, nil, nil, nil)
+
+ h.Recovery.RecordIntent(tabID, "e2", recovery.IntentEntry{
+ Descriptor: semantic.ElementDescriptor{Ref: "e2", Role: "button", Name: "Place order"},
+ CachedAt: time.Now(),
+ })
+ return h, ctx, tabID
+}
+
+func staleClick() *bridge.ActionRequest {
+ return &bridge.ActionRequest{Kind: bridge.ActionClick, Ref: "e2"}
+}
+
+// The defect: the click was DISPATCHED at a node recovery matched, the form posted, and the
+// caller was told the ref could not be found — so the only sane reaction, retry after a
+// re-snapshot, places a second order. The refusal has to come before the dispatch, which is
+// why the counter rather than the message is the assertion.
+func TestAStaleRefOnASubmitControlIsRefusedBeforeAnyOrderIsPlaced(t *testing.T) {
+ f := newOrderFixture(t)
+ h, ctx, tabID := staleSubmitHandlers(t, f)
+
+ _, _, rr, err := h.executeActionResilient(ctx, staleClick(), h.Config, tabID, true)
+
+ if !errors.Is(err, ErrStaleSubmitTarget) {
+ t.Fatalf("error = %v, want the stale-submit refusal", err)
+ }
+ if placed := f.settleForOrder(); placed != 0 {
+ t.Errorf("%d order(s) placed by a call that refused; the refusal must precede the dispatch", placed)
+ }
+ if rr != nil {
+ t.Errorf("a recovery block was published for a call that never re-resolved anything: %+v", rr)
+ }
+ if got := err.Error(); !strings.Contains(got, "/snapshot") {
+ t.Errorf("refusal %q does not tell the caller to re-snapshot", got)
+ }
+}
+
+// A ref that is stale on a page with nothing to submit keeps the ordinary recovery path:
+// this refusal is scoped to submit controls, not to stale refs at large.
+func TestAStaleRefWithNoSubmitControlIsNotRefusedByTheSubmitGuard(t *testing.T) {
+ f := newOrderFixture(t)
+ h, ctx, tabID := staleSubmitHandlers(t, f)
+
+ if err := chromedp.Run(ctx, chromedp.Navigate(f.server.URL+"/order")); err != nil {
+ t.Fatal(err)
+ }
+
+ _, _, _, err := h.executeActionResilient(ctx, staleClick(), h.Config, tabID, true)
+
+ if errors.Is(err, ErrStaleSubmitTarget) {
+ t.Errorf("a page with no form answered the submit refusal: %v", err)
+ }
+ if placed := f.settleForOrder(); placed != 0 {
+ t.Errorf("%d order(s) placed on a page with no form", placed)
+ }
+}
+
+// The guard is what stops the order, not the wording of the refusal: with the DOM check
+// stubbed to the answer it gave before this card — no, this is not a submit — the identical
+// call dispatches at the node recovery MATCHED and the form posts. That is the reported
+// defect reproduced in the suite, so the refusal above cannot be weakened without this
+// turning red.
+func TestTheSubmitCheckIsWhatStopsTheOrder(t *testing.T) {
+ f := newOrderFixture(t)
+ h, ctx, tabID := staleSubmitHandlers(t, f)
+
+ original := submitControlJS
+ t.Cleanup(func() { submitControlJS = original })
+ submitControlJS = `function() { return false; }`
+
+ _, _, _, err := h.executeActionResilient(ctx, staleClick(), h.Config, tabID, true)
+
+ if errors.Is(err, ErrStaleSubmitTarget) {
+ t.Fatalf("the stubbed check still refused, so the refusal is not coming from the DOM check: %v", err)
+ }
+ if placed := f.settleForOrder(); placed != 1 {
+ t.Fatalf("orders placed without the check = %d, want 1: recovery no longer reaches the button, so this fixture has stopped reproducing the defect the guard prevents", placed)
+ }
+}
diff --git a/internal/handlers/actions.go b/internal/handlers/actions.go
index 009588f8..71528c3a 100644
--- a/internal/handlers/actions.go
+++ b/internal/handlers/actions.go
@@ -86,6 +86,21 @@ func rejectMultiStepSubmitClicks(w http.ResponseWriter, actions []bridge.ActionR
return true
}
+// A stale ref whose target submits a form is refused, and the only correct next move is to
+// re-read the page and click the ref that is actually there. `--submit` is the wrong advice
+// from this state — it answers 404 from the same staleness — so the remedy is the snapshot.
+const staleSubmitTargetHint = "The ref came from an older snapshot and now resolves to a control that submits a form. Nothing was dispatched. Take a fresh snapshot and click the ref it reports; do not retry this ref, and do not add --submit, which cannot resolve a stale ref either."
+
+var reSnapshot = remedy.Declare("pinchtab snap")
+
+func staleSubmitTargetDetails() map[string]any {
+ details := remedy.Details(staleSubmitTargetHint, reSnapshot.Remedy())
+ // The submit family reports dispatch state on every refusal, and this one is the
+ // reason the card exists: nothing was clicked.
+ details["dispatched"] = false
+ return details
+}
+
const navigationChangedHint = "The action navigated the page, which the guard reports unless the request declares it: set waitNav true to wait for the navigation, or submit true when the click submits a form. From the CLI those are --wait-nav and --submit."
// The ref stays a placeholder: this guard reports on an action it did not receive the ref
@@ -437,9 +452,7 @@ func (h *Handlers) HandleAction(w http.ResponseWriter, r *http.Request) {
refMissing := selectorResolution.refMissing
submitClick := bridge.IsSubmitClick(req.Kind, req)
if submitClick && refMissing {
- httpx.ErrorCode(w, http.StatusNotFound, "submit_target_not_found", fmt.Sprintf("ref %s not found - take a /snapshot first", req.Ref), false, map[string]any{
- "dispatched": false,
- })
+ httpx.ErrorCode(w, http.StatusNotFound, "submit_target_not_found", fmt.Sprintf("ref %s not found - take a /snapshot first", req.Ref), false, staleSubmitTargetDetails())
return
}
if submitClick && req.NodeID <= 0 {
@@ -510,6 +523,11 @@ func (h *Handlers) HandleAction(w http.ResponseWriter, r *http.Request) {
httpx.ErrorCode(w, http.StatusBadRequest, "invalid_action_request", fmt.Sprintf("action %s: %v", req.Kind, actionErr), false, nil)
return
}
+ if errors.Is(actionErr, ErrStaleSubmitTarget) {
+ httpx.ErrorCode(w, http.StatusNotFound, "submit_target_not_found",
+ fmt.Sprintf("ref %s not found - take a /snapshot first", req.Ref), false, staleSubmitTargetDetails())
+ return
+ }
if errors.Is(actionErr, bridge.ErrUnexpectedNavigation) {
httpx.ErrorCode(w, 409, "navigation_changed", actionErr.Error(), false, navigationChangedDetails(actionErr))
return