sursolver 0.1.0__py3-none-any.whl

sursolver/_core.py

@@ -0,0 +1,362 @@
+"""Validation, request building and response classification shared by both clients."""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._errors import (
+    ApiError,
+    ConfigurationError,
+    Operation,
+    ProtocolError,
+    SurSolverError,
+    TransportError,
+    api_error_for,
+)
+from ._types import (
+    HttpRequest,
+    HttpResponse,
+    ServiceInfo,
+    TaskResult,
+    TaskTypeCatalog,
+    TaskTypeInfo,
+)
+from ._version import VERSION
+
+DEFAULT_BASE_URL = "https://api.sursolver.com"
+DEFAULT_REQUEST_TIMEOUT = 30.0
+DEFAULT_POLL_INTERVAL = 3.0
+DEFAULT_SOLVE_TIMEOUT = 210.0
+DEFAULT_MAX_SUBMIT_RETRIES = 1
+SUBMIT_RETRY_JITTER_MS = 1000
+"""Upper bound of the random delay added to a submit retry, so parallel callers spread out."""
+
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    api_key: str
+    base_url: str
+    request_timeout: float
+    poll_interval: float
+    solve_timeout: float
+    max_submit_retries: int
+    app_id: str | None
+    user_agent: str
+
+
+def positive_seconds(name: str, value: float | None, fallback: float) -> float:
+    if value is None:
+        return fallback
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(value)
+        or value <= 0
+    ):
+        raise ConfigurationError(f"{name} must be a positive number of seconds")
+    return float(value)
+
+
+def _normalize_base_url(raw: str) -> str:
+    parts = urlsplit(raw)
+    loopback_http = parts.scheme == "http" and parts.hostname in _LOOPBACK_HOSTS
+    if parts.scheme != "https" and not loopback_http:
+        raise ConfigurationError("base_url must use https:// (plain http:// only for localhost)")
+    if not parts.netloc:
+        raise ConfigurationError("base_url has no host")
+    if parts.username is not None or parts.password is not None or parts.query or parts.fragment:
+        raise ConfigurationError("base_url must not carry credentials, a query or a fragment")
+    return f"{parts.scheme}://{parts.netloc}{parts.path.rstrip('/')}"
+
+
+def build_settings(
+    api_key: str,
+    *,
+    base_url: str,
+    request_timeout: float | None,
+    poll_interval: float | None,
+    solve_timeout: float | None,
+    max_submit_retries: int | None,
+    app_id: str | None,
+    user_agent_suffix: str | None,
+) -> Settings:
+    if not isinstance(api_key, str) or api_key.strip() == "":
+        raise ConfigurationError("api_key must be a non-empty string")
+    if api_key.strip() != api_key:
+        raise ConfigurationError("api_key has leading or trailing whitespace")
+    retries = DEFAULT_MAX_SUBMIT_RETRIES if max_submit_retries is None else max_submit_retries
+    if isinstance(retries, bool) or not isinstance(retries, int) or retries < 0:
+        raise ConfigurationError("max_submit_retries must be a non-negative integer")
+    if user_agent_suffix is not None and not (
+        user_agent_suffix and all(" " <= char <= "~" for char in user_agent_suffix)
+    ):
+        raise ConfigurationError("user_agent_suffix must be printable ASCII")
+    user_agent = f"sursolver-python/{VERSION}"
+    if user_agent_suffix is not None:
+        user_agent = f"{user_agent} {user_agent_suffix}"
+    trimmed_app_id = app_id.strip() if app_id is not None else ""
+    return Settings(
+        api_key=api_key,
+        base_url=_normalize_base_url(base_url),
+        request_timeout=positive_seconds("request_timeout", request_timeout, DEFAULT_REQUEST_TIMEOUT),
+        poll_interval=positive_seconds("poll_interval", poll_interval, DEFAULT_POLL_INTERVAL),
+        solve_timeout=positive_seconds("solve_timeout", solve_timeout, DEFAULT_SOLVE_TIMEOUT),
+        max_submit_retries=retries,
+        app_id=trimmed_app_id or None,
+        user_agent=user_agent,
+    )
+
+
+def solver_request(settings: Settings, path: str, payload: dict[str, Any]) -> HttpRequest:
+    return HttpRequest(
+        method="POST",
+        url=f"{settings.base_url}{path}",
+        headers={
+            "accept": "application/json",
+            "content-type": "application/json",
+            "user-agent": settings.user_agent,
+        },
+        body=json.dumps(payload).encode("utf-8"),
+        timeout=settings.request_timeout,
+    )
+
+
+def catalog_request(settings: Settings, path: str) -> HttpRequest:
+    return HttpRequest(
+        method="GET",
+        url=f"{settings.base_url}{path}",
+        headers={"accept": "application/json", "user-agent": settings.user_agent},
+        body=None,
+        timeout=settings.request_timeout,
+    )
+
+
+def create_task_payload(settings: Settings, task: Any) -> dict[str, Any]:
+    payload: dict[str, Any] = {"clientKey": settings.api_key, "task": task}
+    if settings.app_id is not None:
+        payload["appId"] = settings.app_id
+    return payload
+
+
+def transport_failure(operation: Operation, error: Exception, timeout: float) -> TransportError:
+    """A transport that raised: no response arrived."""
+    if isinstance(error, (httpx.TimeoutException, TimeoutError)):
+        return TransportError(operation, f"request timed out after {timeout:g} s")
+    return TransportError(operation, "connection failed")
+
+
+def _load_json(body: bytes) -> Any:
+    if not body:
+        return None
+    try:
+        return json.loads(body)
+    except ValueError:
+        return None
+
+
+def _is_integral(value: Any) -> bool:
+    if isinstance(value, bool):
+        return False
+    return isinstance(value, int) or (isinstance(value, float) and value.is_integer())
+
+
+def _checked(operation: Operation, response: HttpResponse) -> Any:
+    """Reject non-200 statuses; return the parsed JSON body (None when not JSON)."""
+    parsed = _load_json(response.body)
+    if response.status != 200:
+        envelope = parsed.get("error") if isinstance(parsed, dict) else None
+        envelope = envelope if isinstance(envelope, dict) else {}
+        code = envelope.get("code")
+        server_code = code if isinstance(code, str) else None
+        retry_after = envelope.get("retry_after_seconds")
+        reason = f"HTTP {response.status}" + ("" if server_code is None else f" ({server_code})")
+        raise TransportError(
+            operation,
+            reason,
+            status=response.status,
+            server_code=server_code,
+            retry_after_seconds=retry_after
+            if isinstance(retry_after, (int, float)) and not isinstance(retry_after, bool)
+            else None,
+        )
+    return parsed
+
+
+def parse_solver(operation: Operation, response: HttpResponse, task_id: str | None = None) -> dict[str, Any]:
+    """Return the ``errorId: 0`` body of a solver call or raise the classified error."""
+    body = _checked(operation, response)
+    if not isinstance(body, dict) or not _is_integral(body.get("errorId")):
+        what = "not JSON" if body is None else "not the solver envelope"
+        raise TransportError(operation, f"HTTP 200 body is {what}", status=200)
+    error_id = body["errorId"]
+    if error_id == 0:
+        return body
+    if error_id != 1:
+        raise ProtocolError(operation, f"errorId {error_id}")
+    code = body.get("errorCode")
+    if not isinstance(code, str):
+        raise ProtocolError(operation, "errorId 1 without a string errorCode")
+    description = body.get("errorDescription")
+    supported = body.get("supportedUserAgents")
+    raise api_error_for(
+        operation,
+        code,
+        description if isinstance(description, str) else "",
+        task_id=task_id,
+        supported_user_agents=[ua for ua in supported if isinstance(ua, str)]
+        if isinstance(supported, list)
+        else (),
+    )
+
+
+def parse_catalog(operation: Operation, response: HttpResponse) -> dict[str, Any]:
+    """Return ``data`` of a ``{"success": true, "data": {...}}`` envelope."""
+    body = _checked(operation, response)
+    if (
+        not isinstance(body, dict)
+        or body.get("success") is not True
+        or not isinstance(body.get("data"), dict)
+    ):
+        raise TransportError(operation, "HTTP 200 body is not the API envelope", status=200)
+    data: dict[str, Any] = body["data"]
+    return data
+
+
+def task_id_from(body: dict[str, Any]) -> str:
+    task_id = body.get("taskId")
+    if not isinstance(task_id, str) or task_id == "":
+        raise ProtocolError("createTask", "errorId 0 without a taskId")
+    return task_id
+
+
+def task_result_from(body: dict[str, Any]) -> TaskResult:
+    status = body.get("status")
+    if status == "processing":
+        return TaskResult(status="processing")
+    if status == "ready":
+        solution = body.get("solution")
+        if not isinstance(solution, dict):
+            raise ProtocolError("getTaskResult", "status ready without a solution object")
+        return TaskResult(status="ready", solution=solution)
+    raise ProtocolError("getTaskResult", f"unknown status {json.dumps(status)}")
+
+
+def balance_from(body: dict[str, Any]) -> float:
+    balance = body.get("balance")
+    if isinstance(balance, bool) or not isinstance(balance, (int, float)) or not math.isfinite(balance):
+        raise ProtocolError("getBalance", "errorId 0 without a numeric balance")
+    return balance
+
+
+class _Entry:
+    """Typed reads of one catalog entry; a missing or mistyped field is a ProtocolError."""
+
+    def __init__(self, operation: Operation, value: Any) -> None:
+        if not isinstance(value, dict):
+            raise ProtocolError(operation, "a catalog entry is not an object")
+        self._operation = operation
+        self._value: dict[str, Any] = value
+
+    def _fail(self, key: str, expected: str) -> ProtocolError:
+        return ProtocolError(self._operation, f"catalog field {key} is not {expected}")
+
+    def text(self, key: str) -> str:
+        value = self._value.get(key)
+        if not isinstance(value, str):
+            raise self._fail(key, "a string")
+        return value
+
+    def optional_text(self, key: str) -> str | None:
+        value = self._value.get(key)
+        if value is not None and not isinstance(value, str):
+            raise self._fail(key, "a string or null")
+        return value
+
+    def integer(self, key: str) -> int:
+        value = self._value.get(key)
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise self._fail(key, "an integer")
+        return value
+
+    def optional_integer(self, key: str) -> int | None:
+        return None if self._value.get(key) is None else self.integer(key)
+
+    def texts(self, key: str) -> tuple[str, ...]:
+        value = self._value.get(key)
+        if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+            raise self._fail(key, "a list of strings")
+        return tuple(value)
+
+    def groups(self, key: str) -> tuple[tuple[str, ...], ...]:
+        value = self._value.get(key)
+        if not isinstance(value, list) or not all(
+            isinstance(group, list) and all(isinstance(item, str) for item in group) for group in value
+        ):
+            raise self._fail(key, "a list of string lists")
+        return tuple(tuple(group) for group in value)
+
+
+def task_types_from(data: dict[str, Any]) -> TaskTypeCatalog:
+    entries, codes = data.get("task_types"), data.get("error_codes")
+    if not isinstance(entries, list) or not isinstance(codes, list):
+        raise ProtocolError("listTaskTypes", "data without task_types and error_codes arrays")
+    task_types = []
+    for raw in entries:
+        entry = _Entry("listTaskTypes", raw)
+        task_types.append(
+            TaskTypeInfo(
+                page_slug=entry.optional_text("page_slug"),
+                display_name=entry.text("display_name"),
+                task_type=entry.text("task_type"),
+                task_type_proxyless=entry.optional_text("task_type_proxyless"),
+                aliases=entry.texts("aliases"),
+                proxy=entry.text("proxy"),
+                required=entry.groups("required"),
+                any_of=entry.groups("any_of"),
+                optional=entry.texts("optional"),
+                solution_keys=entry.texts("solution_keys"),
+            )
+        )
+    if not all(isinstance(code, str) for code in codes):
+        raise ProtocolError("listTaskTypes", "error_codes is not a list of strings")
+    return TaskTypeCatalog(task_types=tuple(task_types), error_codes=tuple(codes))
+
+
+def services_from(data: dict[str, Any]) -> list[ServiceInfo]:
+    services = data.get("services")
+    if not isinstance(services, list):
+        raise ProtocolError("listServices", "data without a services array")
+    result = []
+    for raw in services:
+        entry = _Entry("listServices", raw)
+        result.append(
+            ServiceInfo(
+                id=entry.integer("id"),
+                slug=entry.text("slug"),
+                display_name=entry.text("display_name"),
+                price_per_request=entry.text("price_per_request"),
+                status=entry.text("status"),
+                avg_latency_ms=entry.optional_integer("avg_latency_ms"),
+            )
+        )
+    return result
+
+
+def submit_retry_delay(poll_interval: float, random_value: float) -> float:
+    """Wait before resubmitting after ERROR_NO_SLOT_AVAILABLE: one poll interval plus jitter."""
+    return poll_interval + math.floor(random_value * SUBMIT_RETRY_JITTER_MS) / 1000
+
+
+def is_transient_poll_error(error: SurSolverError) -> bool:
+    """Poll failures that say nothing about the task and may be retried inside the deadline."""
+    return isinstance(error, TransportError) or (
+        isinstance(error, ApiError) and error.code == "ERROR_INTERNAL_ERROR"
+    )

sursolver/_errors.py

@@ -0,0 +1,163 @@
+"""Error types. Cancellation is never wrapped: it stays ``asyncio.CancelledError``."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Literal
+
+Operation = Literal["createTask", "getTaskResult", "getBalance", "listTaskTypes", "listServices"]
+
+
+class SurSolverError(Exception):
+    """Base class of every error this package raises."""
+
+    operation: Operation | None
+
+    def __init__(self, message: str, operation: Operation | None = None) -> None:
+        super().__init__(message)
+        self.operation = operation
+
+
+class ConfigurationError(SurSolverError, ValueError):
+    """The client was built with an unusable option. Nothing was sent."""
+
+
+class TransportError(SurSolverError):
+    """No usable answer: connection failure, timeout, a non-200 status, or a body that is not
+    the API's envelope. It says nothing about the task.
+
+    ``may_have_created_task`` is true for ``create_task``: the request may have been accepted
+    and charged before the answer was lost. Check ``get_balance()`` before submitting again;
+    the API has no idempotency.
+    """
+
+    def __init__(
+        self,
+        operation: Operation,
+        reason: str,
+        *,
+        status: int | None = None,
+        server_code: str | None = None,
+        retry_after_seconds: int | float | None = None,
+    ) -> None:
+        self.may_have_created_task = operation == "createTask"
+        note = (
+            " The task may have been created and charged; check get_balance() before submitting again."
+            if self.may_have_created_task
+            else ""
+        )
+        super().__init__(f"{operation} failed: {reason}.{note}", operation)
+        self.status = status
+        self.server_code = server_code
+        self.retry_after_seconds = retry_after_seconds
+
+
+class ProtocolError(SurSolverError):
+    """HTTP 200 JSON whose shape the API contract does not allow."""
+
+    def __init__(self, operation: Operation, detail: str) -> None:
+        super().__init__(f"{operation} returned an unexpected response: {detail}", operation)
+
+
+class ApiError(SurSolverError):
+    """The API answered ``errorId: 1``. Subclasses group the codes callers act on.
+
+    ``code`` is the ``errorCode`` exactly as sent (including codes newer than this package);
+    ``retryable`` is true only for ``ERROR_NO_SLOT_AVAILABLE``; ``supported_user_agents`` is
+    the list sent with ``ERROR_WRONG_USERAGENT`` and empty otherwise.
+    """
+
+    def __init__(
+        self,
+        operation: Operation,
+        code: str,
+        description: str,
+        *,
+        task_id: str | None = None,
+        supported_user_agents: Iterable[str] = (),
+    ) -> None:
+        task = "" if task_id is None else f" (task {task_id})"
+        super().__init__(f"{code}: {description}{task}", operation)
+        self.code = code
+        self.description = description
+        self.retryable = code == "ERROR_NO_SLOT_AVAILABLE"
+        self.task_id = task_id
+        self.supported_user_agents: tuple[str, ...] = tuple(supported_user_agents)
+
+
+class AuthenticationError(ApiError):
+    """``ERROR_WRONG_CLIENT_KEY`` or ``ERROR_KEY_DOES_NOT_EXIST``: fix the API key."""
+
+
+class InvalidTaskError(ApiError):
+    """``create_task`` refused the task itself: ``ERROR_INVALID_REQUEST``,
+    ``ERROR_TYPE_NOT_SUPPORTED`` or ``ERROR_WRONG_USERAGENT`` (see ``supported_user_agents``).
+    Nothing was created or charged."""
+
+
+class InsufficientBalanceError(ApiError):
+    """``ERROR_ZERO_BALANCE``: the balance or plan cannot cover the task. Nothing was charged."""
+
+
+class NoSlotAvailableError(ApiError):
+    """``ERROR_NO_SLOT_AVAILABLE``: the account's open tasks fill its thread limit, or the
+    service is briefly not admitting work. Nothing was created; submitting later is safe."""
+
+
+class TaskNotFoundError(ApiError):
+    """``ERROR_TASK_NOT_FOUND``: unknown task id, or one owned by another account."""
+
+
+class TaskFailedError(ApiError):
+    """The task ended without a result: ``ERROR_FAILED``, ``ERROR_TASK_TIMEOUT``,
+    ``ERROR_TASK_EXPIRED``, or ``ERROR_WRONG_USERAGENT`` after acceptance. Final for this
+    task; the API returns a failed task's charge once."""
+
+
+class SolveTimeoutError(SurSolverError):
+    """``solve()`` reached its deadline. The task may still finish and stays charged: poll it
+    with ``get_task_result(error.task_id)`` if you still need the result. ``last_error`` is the
+    final poll's transient failure, when there was one."""
+
+    def __init__(self, task_id: str, timeout: float, last_error: SurSolverError | None = None) -> None:
+        super().__init__(
+            f"task {task_id} was not ready within {timeout:g} s; it may still finish and stays charged",
+            "getTaskResult",
+        )
+        self.task_id = task_id
+        self.last_error = last_error
+        self.__cause__ = last_error
+
+
+_TASK_FAILURE_CODES = frozenset(
+    {"ERROR_FAILED", "ERROR_TASK_TIMEOUT", "ERROR_TASK_EXPIRED", "ERROR_WRONG_USERAGENT"}
+)
+
+_CLASS_BY_CODE: dict[str, type[ApiError]] = {
+    "ERROR_WRONG_CLIENT_KEY": AuthenticationError,
+    "ERROR_KEY_DOES_NOT_EXIST": AuthenticationError,
+    "ERROR_INVALID_REQUEST": InvalidTaskError,
+    "ERROR_TYPE_NOT_SUPPORTED": InvalidTaskError,
+    "ERROR_WRONG_USERAGENT": InvalidTaskError,
+    "ERROR_ZERO_BALANCE": InsufficientBalanceError,
+    "ERROR_NO_SLOT_AVAILABLE": NoSlotAvailableError,
+    "ERROR_TASK_NOT_FOUND": TaskNotFoundError,
+}
+
+
+def api_error_for(
+    operation: Operation,
+    code: str,
+    description: str,
+    *,
+    task_id: str | None = None,
+    supported_user_agents: Iterable[str] = (),
+) -> ApiError:
+    """The error class for an ``errorId: 1`` answer: it depends on the operation and the code."""
+    if operation == "getTaskResult" and code in _TASK_FAILURE_CODES:
+        error_class: type[ApiError] = TaskFailedError
+    else:
+        error_class = _CLASS_BY_CODE.get(code, ApiError)
+    return error_class(
+        operation, code, description, task_id=task_id, supported_user_agents=supported_user_agents
+    )

sursolver/_types.py

@@ -0,0 +1,105 @@
+"""Public data types."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol
+
+Task = Mapping[str, Any]
+"""A task object: ``type`` plus that type's fields, sent verbatim. Browser task types require
+``userAgent`` (the Windows Chrome User-Agent of the client that will use the result)."""
+
+Solution = dict[str, Any]
+"""A task's result. Keys differ per type (``token``, ``gRecaptchaResponse``, ``cf_clearance``,
+``cookies``, ...) and are passed through untouched. Tokens and cookies are single-use."""
+
+
+@dataclass(frozen=True, slots=True)
+class TaskResult:
+    status: Literal["processing", "ready"]
+    solution: Solution | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class SolveResult:
+    task_id: str
+    solution: Solution
+
+
+@dataclass(frozen=True, slots=True)
+class TaskTypeInfo:
+    """One entry of ``GET /v1/task-types``."""
+
+    page_slug: str | None
+    display_name: str
+    task_type: str
+    """Canonical name (the proxy-capable one when a ProxyLess twin exists)."""
+    task_type_proxyless: str | None
+    aliases: tuple[str, ...]
+    proxy: str
+    """``none``, ``optional`` or ``required``."""
+    required: tuple[tuple[str, ...], ...]
+    """Groups of accepted spellings; supply one name per group."""
+    any_of: tuple[tuple[str, ...], ...]
+    """Alternatives; supply every field of at least one."""
+    optional: tuple[str, ...]
+    solution_keys: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class TaskTypeCatalog:
+    task_types: tuple[TaskTypeInfo, ...]
+    error_codes: tuple[str, ...]
+    """The complete ``errorCode`` vocabulary of the solver endpoints."""
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceInfo:
+    """One entry of ``GET /v1/services``."""
+
+    id: int
+    slug: str
+    display_name: str
+    price_per_request: str
+    """USD price per task as a decimal string, e.g. ``"0.0006"``."""
+    status: str
+    avg_latency_ms: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class HttpRequest:
+    method: Literal["GET", "POST"]
+    url: str
+    headers: Mapping[str, str]
+    body: bytes | None
+    timeout: float
+    """Seconds."""
+
+
+@dataclass(frozen=True, slots=True)
+class HttpResponse:
+    status: int
+    body: bytes
+    headers: Mapping[str, str] = field(default_factory=dict)
+
+
+Transport = Callable[[HttpRequest], HttpResponse]
+"""Sends one request. Return any status; raise only when no response arrived. Must not follow
+redirects."""
+
+AsyncTransport = Callable[[HttpRequest], Awaitable[HttpResponse]]
+
+
+class Clock(Protocol):
+    def now(self) -> float:
+        """Seconds; only differences are used."""
+        ...
+
+    def sleep(self, seconds: float) -> None: ...
+
+
+class AsyncClock(Protocol):
+    def now(self) -> float: ...
+
+    async def sleep(self, seconds: float) -> None: ...

sursolver/_version.py

@@ -0,0 +1,2 @@
+VERSION = "0.1.0"
+"""Package version (single source: pyproject reads it); sent in the User-Agent header."""