curl-solve

Challenge-aware HTTP sessions on curl_cffi.

curl-solve wraps curl_cffi with challenge detection, a cookie-aware retry loop, and pluggable solvers.

It is a lightweight middle tier — not a Cloudflare bypass:

fast HTTP (curl_cffi)  →  curl-solve  →  real browser

Comparison

curl-solve sits on curl_cffi: same impersonated TLS, plus classification and a solver retry loop. cloudscraper can still clear old IUAM JS puzzles; it does not impersonate TLS and does not solve modern managed / Turnstile pages. When both return HTTP 200 product HTML, Cloudflare never issued that interstitial — impersonation (or a clean IP) passed, nothing “solved” the widget.

Install

pip install curl-solve

Requires Python 3.11+ and curl_cffi>=0.16.1.

Quick start

from curl_solve import BROWSER_ONLY_KINDS, ChallengeSession

with ChallengeSession(impersonate="chrome") as session:
    resp = session.get("https://example.com")
    print(resp.status_code, resp.challenge.kind)
    if resp.challenge.kind in BROWSER_ONLY_KINDS:
        print("Escalate to a real browser.")

ChallengeSession keeps one impersonated TLS session. After each request it classifies the response. If a registered solver can handle the challenge, cookies are applied and the original request is retried.

ChallengeSession

from curl_solve import ChallengeSession

session = ChallengeSession(
    impersonate="chrome",
    proxy=None,
    timeout=30,
    http2=True,
    http3=False,
    dns_overrides=None,
    solvers=None,
    max_solves=1,
    raise_on_unsolved=False,
    default_headers=True,
    persist_cookies=True,
    # extra kwargs go to curl_cffi.requests.Session
)

Session properties

Lifecycle

Request methods

All of these go through session.request(...), so they share the same detect → solver → retry loop, cookie jar, impersonate fingerprint, and return type (SolvedResponse).

resp = session.get(url)
resp = session.post(url, json={"q": "sku"})
resp = session.put(url, data=b"raw")
resp = session.patch(url, json={"stock": 1})
resp = session.delete(url)
resp = session.head(url)
resp = session.options(url)
resp = session.request("GET", url, solve=False)

Shared request arguments

These work on every method above (get / post / … / request).

Passed through to curl_cffi

Any other keyword is forwarded to curl_cffi.requests.Session.request:

Response: SolvedResponse

Every request method returns a SolvedResponse. It wraps the curl_cffi response and adds challenge metadata.

print(resp.status_code)
print(resp.challenge.kind)
print(resp.text[:200])

Challenge

resp.challenge is a Detection with a single field:

Escalate with resp.challenge.kind in BROWSER_ONLY_KINDS. A plugin may attempt resp.challenge.kind in SOLVABLE_KINDS (currently only cloudflare_iuam).

Body / HTTP fields (delegated)

Unknown attributes are forwarded to resp.raw (the curl_cffi response):

ChallengeKind

Large product pages that only mention a vendor name (for example datadome in a long 200 body) are not treated as challenges.

How to read a result:

Detection without a session

from curl_solve import detect, ChallengeKind, is_js_challenge, is_blocked, is_session_ban

result = detect(status=403, body="<html>just a moment</html>")
assert result.kind is ChallengeKind.CLOUDFLARE_MANAGED

Pluggable solvers

from curl_solve import ChallengeSession, ChallengeSolver, SOLVABLE_KINDS, SolveOutcome


class MySolver(ChallengeSolver):
    name = "my-solver"

    def can_handle(self, response, detection):
        return detection.kind in SOLVABLE_KINDS

    def solve(self, client, response, detection):
        # client.http.get(...) — extra fetches skip the solve loop
        return SolveOutcome.ok(cookies={"cf_clearance": "..."})
        # or: return SolveOutcome.failed("could not parse challenge")


session = ChallengeSession(solvers=[MySolver()])

Unsolved challenges are returned (or raised when raise_on_unsolved=True) so a caller — later, scrapy-stealth driver="auto" — can escalate: turbo → curl-solve → browser.

Exceptions

License

MIT