aykhans/sarin
1
0
Fork 0
mirror of https://github.com/aykhans/sarin.git synced 2026-04-14 20:19:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor: tighten captcha poll loop and document solver funcs

Browse Source
This commit is contained in:
Aykhan Shahsuvarov
2026-04-12 01:10:20 +04:00
parent 006029aad1
commit 1bd58a02b7
2 changed files with 151 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

161
internal/sarin/captcha.go
View File

@@ -4,6 +4,7 @@ import (
"bytes"
"context"
"encoding/json"
"errors"
"net/http"
"strings"
"time"
@@ -12,16 +13,27 @@ import (
)
const (
captchaPollInterval = 5 * time.Second
captchaPollInterval = 1 * time.Second
captchaTimeout = 120 * time.Second
)
var captchaHTTPClient = &http.Client{Timeout: captchaTimeout}
// solveCaptcha creates a task and polls for the result.
// solveCaptcha creates a task on the given captcha service and polls until it is solved,
// returning the extracted token from the solution object.
//
// baseURL is the service API base (e.g. "https://api.2captcha.com").
// taskIDIsString controls whether taskId is sent back as a string or number.
// task is the task payload the service expects (type + service-specific fields).
// solutionKey is the field name in the solution object that holds the token.
// taskIDIsString controls whether taskId is sent back as a string (CapSolver UUIDs)
// or a JSON number (2Captcha, Anti-Captcha).
//
// It can return the following errors:
// - types.ErrCaptchaKeyEmpty
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaTimeoutError
// - types.CaptchaSolutionKeyError
func solveCaptcha(baseURL, apiKey string, task map[string]any, solutionKey string, taskIDIsString bool) (string, error) {
if apiKey == "" {
return "", types.ErrCaptchaKeyEmpty
@@ -34,6 +46,13 @@ func solveCaptcha(baseURL, apiKey string, task map[string]any, solutionKey strin
return captchaPollResult(baseURL, apiKey, taskID, solutionKey, taskIDIsString)
}
// captchaCreateTask submits a task to the captcha service and returns the assigned taskId.
// The taskId is normalized to a string: numeric IDs are preserved via json.RawMessage,
// and quoted string IDs (CapSolver UUIDs) have their surrounding quotes stripped.
//
// It can return the following errors:
// - types.CaptchaRequestError
// - types.CaptchaAPIError
func captchaCreateTask(baseURL, apiKey string, task map[string]any) (string, error) {
body := map[string]any{
"clientKey": apiKey,
@@ -71,9 +90,21 @@ func captchaCreateTask(baseURL, apiKey string, task map[string]any) (string, err
// taskId may be a JSON number (2captcha, anti-captcha) or a quoted string (capsolver UUIDs).
// Strip surrounding quotes if present so we always work with the underlying value.
return strings.Trim(string(result.TaskID), `"`), nil
taskID := strings.Trim(string(result.TaskID), `"`)
if taskID == "" {
return "", types.NewCaptchaAPIError("createTask", "EMPTY_TASK_ID", "service returned a successful response with no taskId")
}
return taskID, nil
}
// captchaPollResult polls the getTaskResult endpoint at captchaPollInterval until the task
// is solved, an error is returned by the service, or the overall captchaTimeout is hit.
//
// It can return the following errors:
// - types.CaptchaTimeoutError
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaSolutionKeyError
func captchaPollResult(baseURL, apiKey, taskID, solutionKey string, taskIDIsString bool) (string, error) {
ctx, cancel := context.WithTimeout(context.Background(), captchaTimeout)
defer cancel()
@@ -86,18 +117,26 @@ func captchaPollResult(baseURL, apiKey, taskID, solutionKey string, taskIDIsStri
case <-ctx.Done():
return "", types.NewCaptchaTimeoutError(taskID)
case <-ticker.C:
token, done, err := captchaGetTaskResult(baseURL, apiKey, taskID, solutionKey, taskIDIsString)
token, err := captchaGetTaskResult(baseURL, apiKey, taskID, solutionKey, taskIDIsString)
if errors.Is(err, types.ErrCaptchaProcessing) {
continue
}
if err != nil {
return "", err
}
if done {
return token, nil
}
}
}
}
func captchaGetTaskResult(baseURL, apiKey, taskID, solutionKey string, taskIDIsString bool) (string, bool, error) {
// captchaGetTaskResult fetches a single task result from the captcha service.
//
// It can return the following errors:
// - types.ErrCaptchaProcessing
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaSolutionKeyError
func captchaGetTaskResult(baseURL, apiKey, taskID, solutionKey string, taskIDIsString bool) (string, error) {
var bodyMap map[string]any
if taskIDIsString {
bodyMap = map[string]any{"clientKey": apiKey, "taskId": taskID}
@@ -107,7 +146,7 @@ func captchaGetTaskResult(baseURL, apiKey, taskID, solutionKey string, taskIDIsS
data, err := json.Marshal(bodyMap)
if err != nil {
return "", false, types.NewCaptchaRequestError("getTaskResult", err)
return "", types.NewCaptchaRequestError("getTaskResult", err)
}
resp, err := captchaHTTPClient.Post(
@@ -116,7 +155,7 @@ func captchaGetTaskResult(baseURL, apiKey, taskID, solutionKey string, taskIDIsS
bytes.NewReader(data),
)
if err != nil {
return "", false, types.NewCaptchaRequestError("getTaskResult", err)
return "", types.NewCaptchaRequestError("getTaskResult", err)
}
defer resp.Body.Close() //nolint:errcheck
@@ -128,33 +167,41 @@ func captchaGetTaskResult(baseURL, apiKey, taskID, solutionKey string, taskIDIsS
Solution map[string]any `json:"solution"`
}
if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
return "", false, types.NewCaptchaRequestError("getTaskResult", err)
return "", types.NewCaptchaRequestError("getTaskResult", err)
}
if result.ErrorID != 0 {
return "", false, types.NewCaptchaAPIError("getTaskResult", result.ErrorCode, result.ErrorDescription)
return "", types.NewCaptchaAPIError("getTaskResult", result.ErrorCode, result.ErrorDescription)
}
if result.Status == "processing" || result.Status == "idle" {
return "", false, nil
return "", types.ErrCaptchaProcessing
}
token, ok := result.Solution[solutionKey]
if !ok {
return "", false, types.NewCaptchaSolutionKeyError(solutionKey)
return "", types.NewCaptchaSolutionKeyError(solutionKey)
}
tokenStr, ok := token.(string)
if !ok {
return "", false, types.NewCaptchaSolutionKeyError(solutionKey)
return "", types.NewCaptchaSolutionKeyError(solutionKey)
}
return tokenStr, true, nil
return tokenStr, nil
}
// ======================================== 2Captcha ========================================
const twoCaptchaBaseURL = "https://api.2captcha.com"
// twoCaptchaSolveRecaptchaV2 solves a Google reCAPTCHA v2 challenge via 2Captcha.
//
// It can return the following errors:
// - types.ErrCaptchaKeyEmpty
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaTimeoutError
// - types.CaptchaSolutionKeyError
func twoCaptchaSolveRecaptchaV2(apiKey, websiteURL, websiteKey string) (string, error) {
return solveCaptcha(twoCaptchaBaseURL, apiKey, map[string]any{
"type": "RecaptchaV2TaskProxyless",
@@ -163,6 +210,15 @@ func twoCaptchaSolveRecaptchaV2(apiKey, websiteURL, websiteKey string) (string,
}, "gRecaptchaResponse", false)
}
// twoCaptchaSolveRecaptchaV3 solves a Google reCAPTCHA v3 challenge via 2Captcha.
// pageAction may be empty.
//
// It can return the following errors:
// - types.ErrCaptchaKeyEmpty
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaTimeoutError
// - types.CaptchaSolutionKeyError
func twoCaptchaSolveRecaptchaV3(apiKey, websiteURL, websiteKey, pageAction string) (string, error) {
task := map[string]any{
"type": "RecaptchaV3TaskProxyless",
@@ -175,6 +231,15 @@ func twoCaptchaSolveRecaptchaV3(apiKey, websiteURL, websiteKey, pageAction strin
return solveCaptcha(twoCaptchaBaseURL, apiKey, task, "gRecaptchaResponse", false)
}
// twoCaptchaSolveTurnstile solves a Cloudflare Turnstile challenge via 2Captcha.
// cData may be empty.
//
// It can return the following errors:
// - types.ErrCaptchaKeyEmpty
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaTimeoutError
// - types.CaptchaSolutionKeyError
func twoCaptchaSolveTurnstile(apiKey, websiteURL, websiteKey, cData string) (string, error) {
task := map[string]any{
"type": "TurnstileTaskProxyless",
@@ -191,6 +256,14 @@ func twoCaptchaSolveTurnstile(apiKey, websiteURL, websiteKey, cData string) (str
const antiCaptchaBaseURL = "https://api.anti-captcha.com"
// antiCaptchaSolveRecaptchaV2 solves a Google reCAPTCHA v2 challenge via Anti-Captcha.
//
// It can return the following errors:
// - types.ErrCaptchaKeyEmpty
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaTimeoutError
// - types.CaptchaSolutionKeyError
func antiCaptchaSolveRecaptchaV2(apiKey, websiteURL, websiteKey string) (string, error) {
return solveCaptcha(antiCaptchaBaseURL, apiKey, map[string]any{
"type": "RecaptchaV2TaskProxyless",
@@ -199,8 +272,17 @@ func antiCaptchaSolveRecaptchaV2(apiKey, websiteURL, websiteKey string) (string,
}, "gRecaptchaResponse", false)
}
// antiCaptchaSolveRecaptchaV3 solves a Google reCAPTCHA v3 challenge via Anti-Captcha.
// pageAction may be empty. minScore is hardcoded to 0.3 (the loosest threshold) because
// Anti-Captcha rejects the request without it.
//
// It can return the following errors:
// - types.ErrCaptchaKeyEmpty
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaTimeoutError
// - types.CaptchaSolutionKeyError
func antiCaptchaSolveRecaptchaV3(apiKey, websiteURL, websiteKey, pageAction string) (string, error) {
// Anti-Captcha requires minScore for reCAPTCHA v3. 0.3 is the loosest threshold.
task := map[string]any{
"type": "RecaptchaV3TaskProxyless",
"websiteURL": websiteURL,
@@ -213,8 +295,16 @@ func antiCaptchaSolveRecaptchaV3(apiKey, websiteURL, websiteKey, pageAction stri
return solveCaptcha(antiCaptchaBaseURL, apiKey, task, "gRecaptchaResponse", false)
}
// antiCaptchaSolveHCaptcha solves an hCaptcha challenge via Anti-Captcha.
// Anti-Captcha returns hCaptcha tokens under "gRecaptchaResponse" (not "token").
//
// It can return the following errors:
// - types.ErrCaptchaKeyEmpty
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaTimeoutError
// - types.CaptchaSolutionKeyError
func antiCaptchaSolveHCaptcha(apiKey, websiteURL, websiteKey string) (string, error) {
// Anti-Captcha returns hCaptcha tokens under "gRecaptchaResponse" (not "token").
return solveCaptcha(antiCaptchaBaseURL, apiKey, map[string]any{
"type": "HCaptchaTaskProxyless",
"websiteURL": websiteURL,
@@ -222,6 +312,15 @@ func antiCaptchaSolveHCaptcha(apiKey, websiteURL, websiteKey string) (string, er
}, "gRecaptchaResponse", false)
}
// antiCaptchaSolveTurnstile solves a Cloudflare Turnstile challenge via Anti-Captcha.
// cData may be empty.
//
// It can return the following errors:
// - types.ErrCaptchaKeyEmpty
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaTimeoutError
// - types.CaptchaSolutionKeyError
func antiCaptchaSolveTurnstile(apiKey, websiteURL, websiteKey, cData string) (string, error) {
task := map[string]any{
"type": "TurnstileTaskProxyless",
@@ -238,6 +337,14 @@ func antiCaptchaSolveTurnstile(apiKey, websiteURL, websiteKey, cData string) (st
const capSolverBaseURL = "https://api.capsolver.com"
// capSolverSolveRecaptchaV2 solves a Google reCAPTCHA v2 challenge via CapSolver.
//
// It can return the following errors:
// - types.ErrCaptchaKeyEmpty
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaTimeoutError
// - types.CaptchaSolutionKeyError
func capSolverSolveRecaptchaV2(apiKey, websiteURL, websiteKey string) (string, error) {
return solveCaptcha(capSolverBaseURL, apiKey, map[string]any{
"type": "ReCaptchaV2TaskProxyLess",
@@ -246,6 +353,15 @@ func capSolverSolveRecaptchaV2(apiKey, websiteURL, websiteKey string) (string, e
}, "gRecaptchaResponse", true)
}
// capSolverSolveRecaptchaV3 solves a Google reCAPTCHA v3 challenge via CapSolver.
// pageAction may be empty.
//
// It can return the following errors:
// - types.ErrCaptchaKeyEmpty
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaTimeoutError
// - types.CaptchaSolutionKeyError
func capSolverSolveRecaptchaV3(apiKey, websiteURL, websiteKey, pageAction string) (string, error) {
task := map[string]any{
"type": "ReCaptchaV3TaskProxyLess",
@@ -258,6 +374,15 @@ func capSolverSolveRecaptchaV3(apiKey, websiteURL, websiteKey, pageAction string
return solveCaptcha(capSolverBaseURL, apiKey, task, "gRecaptchaResponse", true)
}
// capSolverSolveTurnstile solves a Cloudflare Turnstile challenge via CapSolver.
// cData may be empty. CapSolver nests cData under a "metadata" object.
//
// It can return the following errors:
// - types.ErrCaptchaKeyEmpty
// - types.CaptchaRequestError
// - types.CaptchaAPIError
// - types.CaptchaTimeoutError
// - types.CaptchaSolutionKeyError
func capSolverSolveTurnstile(apiKey, websiteURL, websiteKey, cData string) (string, error) {
task := map[string]any{
"type": "AntiTurnstileTaskProxyLess",

8
internal/types/errors.go
View File

@@ -445,7 +445,13 @@ func (e ScriptUnknownEngineError) Error() string {
// ======================================== Captcha ========================================
var ErrCaptchaKeyEmpty = errors.New("captcha API key cannot be empty")
var (
ErrCaptchaKeyEmpty = errors.New("captcha API key cannot be empty")
// ErrCaptchaProcessing is an internal sentinel returned by the captcha solver polling
// code to signal that a task is not yet solved and polling should continue.
// It should never be surfaced to callers outside of the captcha poll loop.
ErrCaptchaProcessing = errors.New("captcha task still processing")
)
type CaptchaAPIError struct {
Endpoint string