Skip to content

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

8.2 KB
Raw Blame
package handlers

import (
	"context"
	"fmt"
	"net/http"
	"time"

	"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/httpx"
)

// HandleSolve attempts to solve a browser challenge on the current page.
//
// When "solver" is omitted from the request body, all registered solvers are
// tried in order via auto-detection.  When "solver" is set (e.g. "cloudflare"),
// only that solver is invoked.
//
// @Endpoint POST /solve
// @Description Auto-detect and solve browser challenges (Cloudflare, etc.)
//
// @Param tabId       string  body  Tab ID (optional — uses default tab)
// @Param solver      string  body  Solver name (optional — auto-detect)
// @Param maxAttempts int     body  Max solve attempts (optional, default: 3)
// @Param timeout     float64 body  Timeout in ms (optional, default: 30000)
//
// @Response 200 application/json Returns {tabId, solver, solved, challengeType, attempts, title}
// @Response 400 application/json Invalid request body or unknown solver
// @Response 423 application/json Tab is locked by another owner
// @Response 500 application/json Chrome/CDP error
//
// @Example curl:
//
//	curl -X POST http://localhost:9867/solve \
//	  -H "Content-Type: application/json" \
//	  -d '{"maxAttempts": 3, "timeout": 30000}'
//
// @Example curl (specific solver):
//
//	curl -X POST http://localhost:9867/solve \
//	  -H "Content-Type: application/json" \
//	  -d '{"solver": "cloudflare", "maxAttempts": 3}'
func (h *Handlers) HandleSolve(w http.ResponseWriter, r *http.Request) {
	var req struct {
		TabID       string  `json:"tabId"`
		Solver      string  `json:"solver"`
		MaxAttempts int     `json:"maxAttempts"`
		Timeout     float64 `json:"timeout"`
	}

	if !decodeOptionalJSON(w, r, &req) {
		return
	}

	if name := r.PathValue("name"); name != "" {
		req.Solver = name
	}

	if req.Solver != "" && !h.isAvailableAutoSolver(req.Solver) {
		h.rejectUnavailableSolver(w, req.Solver)
		return
	}

	ctx, resolvedTabID, err := h.tabContext(r, req.TabID)
	if err != nil {
		WriteTabContextError(w, err, 404)
		return
	}

	owner := resolveOwner(r, "")
	if err := h.enforceTabLease(resolvedTabID, owner); err != nil {
		httpx.ErrorCode(w, 423, "tab_locked", err.Error(), false, nil)
		return
	}

	if _, ok := h.applyTabGuards(w, r, ctx, resolvedTabID, guardDialogBlocked|guardDomainPolicy|guardHandoffPause); !ok {
		return
	}

	action := "solve"
	if req.Solver != "" {
		action = "solve:" + req.Solver
	}
	h.recordActivity(r, activity.Update{Action: action, TabID: resolvedTabID})

	page, executor, err := adapters.NewFromBridge(h.Bridge, resolvedTabID)
	if err != nil {
		httpx.Error(w, 500, fmt.Errorf("resolve solve tab: %w", err))
		return
	}

	cfg := h.normalizedAutoSolverConfig()
	cfg.Enabled = true
	if req.MaxAttempts > 0 {
		cfg.MaxAttempts = req.MaxAttempts
	}
	if req.Solver != "" {
		cfg.Solvers = []string{req.Solver}
	}

	includeSemantic := req.Solver == "" || req.Solver == coreautosolver.SemanticSolverName
	as := h.buildAutoSolver(cfg, includeSemantic)

	timeout := 30 * time.Second
	if req.Timeout > 0 {
		timeout = time.Duration(req.Timeout) * time.Millisecond
	} else {
		estimated := estimateAutoSolverRunTimeout(cfg)
		if estimated > timeout {
			timeout = estimated
		}
	}

	tCtx, tCancel := context.WithTimeout(ctx, timeout)
	defer tCancel()
	go httpx.CancelOnClientDone(r.Context(), tCancel)

	result, err := as.Solve(tCtx, page, executor)
	if err != nil {
		httpx.Error(w, 500, fmt.Errorf("solve: %w", err))
		return
	}
	if result == nil {
		httpx.Error(w, 500, fmt.Errorf("solve: empty result"))
		return
	}

	if _, ok := h.applyTabGuards(w, r, ctx, resolvedTabID, guardDomainPolicy); !ok {
		return
	}

	solverName := result.SolverUsed
	if solverName == "" && req.Solver != "" {
		solverName = req.Solver
	}

	title := result.FinalTitle
	if title == "" {
		title = page.Title()
	}

	challengeType := deriveChallengeType(result, page)
	resp := map[string]any{
		"tabId":         resolvedTabID,
		"solver":        solverName,
		"solved":        result.Solved,
		"challengeType": challengeType,
		"attempts":      result.Attempts,
		"title":         title,
	}

	// If a challenge was detected but the solver couldn't resolve it, flip the
	// tab into paused_handoff so subsequent actions block and the caller can
	// escalate to a human.
	if !result.Solved && result.Attempts > 0 && challengeType != "" {
		h.autoHandoffAfterFailure(resolvedTabID, challengeType)
		resp["handoff"] = "paused_handoff"
		resp["hint"] = handoffHintMessage
	}

	httpx.JSON(w, 200, resp)
}

// HandleTabSolve handles POST /tabs/{id}/solve and /tabs/{id}/solve/{name}.
//
// @Endpoint POST /tabs/{id}/solve
// @Description Solve a browser challenge on a specific tab
func (h *Handlers) HandleTabSolve(w http.ResponseWriter, r *http.Request) {
	// Reject (not silently overwrite) a body tabId that disagrees with the
	// path id; the path id is canonical and forwarded to HandleSolve.
	h.withPathTabIDBody(w, r, h.HandleSolve)
}

// HandleListSolvers returns the list of registered solver names.
//
// @Endpoint GET /solvers
// @Description List available challenge solvers
// @Response 200 application/json Returns {solvers: ["cloudflare", ...]}
func (h *Handlers) HandleListSolvers(w http.ResponseWriter, r *http.Request) {
	httpx.JSON(w, 200, map[string]any{
		"solvers": h.availableAutoSolverNames(),
	})
}

// HandleAutoSolverConfig returns effective autosolver runtime settings.
//
// @Endpoint GET /config/autosolver
// @Description Return effective autosolver configuration and available solver names
// @Response 200 application/json Returns autosolver runtime config
func (h *Handlers) HandleAutoSolverConfig(w http.ResponseWriter, r *http.Request) {
	cfg := h.normalizedAutoSolverConfig()

	autoTrigger := true
	triggerOnNavigate := true
	triggerOnAction := true
	llmProvider := ""

	if h != nil && h.Config != nil {
		autoTrigger = h.Config.AutoSolver.AutoTrigger
		triggerOnNavigate = h.Config.AutoSolver.TriggerOnNavigate
		triggerOnAction = h.Config.AutoSolver.TriggerOnAction
		llmProvider = h.Config.AutoSolver.LLMProvider
	}

	httpx.JSON(w, 200, map[string]any{
		"enabled":           cfg.Enabled,
		"autoTrigger":       autoTrigger,
		"triggerOnNavigate": triggerOnNavigate,
		"triggerOnAction":   triggerOnAction,
		"maxAttempts":       cfg.MaxAttempts,
		"solverTimeoutSec":  int(cfg.SolverTimeout / time.Second),
		"retryBaseDelayMs":  int(cfg.RetryBaseDelay / time.Millisecond),
		"retryMaxDelayMs":   int(cfg.RetryMaxDelay / time.Millisecond),
		"solvers":           h.availableAutoSolverNames(),
		"llmProvider":       llmProvider,
		"llmFallback":       cfg.LLMFallback,
	})
}

// 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 := coreautosolver.KeyGatedSolverNamed(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 ""
	}

	finalTitle := result.FinalTitle
	if finalTitle == "" {
		finalTitle = page.Title()
	}
	finalURL := result.FinalURL
	if finalURL == "" {
		finalURL = page.URL()
	}

	html, err := page.HTML()
	if err == nil {
		if detected := coreautosolver.DetectChallengeIntent(finalTitle, finalURL, html); detected != nil {
			if detected.ChallengeType != "" {
				return detected.ChallengeType
			}
			if detected.Type != "" && detected.Type != coreautosolver.IntentNormal {
				return string(detected.Type)
			}
		}
	}

	if result.Intent != "" && result.Intent != coreautosolver.IntentNormal {
		return string(result.Intent)
	}

	return ""
}