"""JSON-RPC 2.0 transport for the LimeSurvey RemoteControl API. Standard library only (``urllib.request``). - ``endpoint_url(base_url)`` — turns a base URL into the correct endpoint ``{base}index.php?r=admin/remotecontrol``. Note: the alias ``/remotecontrol`` returns HTTP 400 in LimeSurvey — always use the ``index.php?r=...`` form. - ``rpc_call(url, method, params, timeout=30)`` — performs one JSON-RPC 2.0 POST and returns the ``result`` field. - ``RpcClient`` — thin wrapper with a fixed endpoint URL and timeout; used by session/surveys/responses/tokens. Error handling (everything diagnosable: method, params, HTTP status and body are in the exception message and attributes): - network errors (urllib exceptions, timeout, HTTP error status, invalid JSON) → ``LsConnectionError`` - JSON-RPC ``error`` in the response → ``LsApiError`` (``LsAuthError`` for auth errors) Debug logging (``logging.getLogger("pylimerpc.rpc")``) logs the request, the response and the ``statistic`` field when LimeSurvey sends one. TLS: the server certificate is verified by default. With ``make_ssl_context(False)`` / ``LsConfig(verify_ssl=False)`` the check can be disabled for test instances with a wrong certificate (never for production). SSL errors (including certificate mismatch) surface as ``LsConnectionError`` (``cause`` holds the underlying ``ssl.SSLError``). """ from __future__ import annotations import itertools import json import logging import ssl import urllib.error import urllib.request from typing import Any from .config import LsConfig from .errors import LsApiError, LsAuthError, LsConnectionError logger = logging.getLogger(__name__) DEFAULT_TIMEOUT = 30 MAX_SNIPPET = 500 _ids = itertools.count(1) # strings that indicate an auth problem in an RPC error _AUTH_HINTS = ( "session key", "invalid user", "password", "unauthorized", "not authorized", "permission", "login", ) def endpoint_url(base_url: str) -> str: """Turn a base URL into the RemoteControl endpoint. ``https://host/limesurvey`` → ``https://host/limesurvey/index.php?r=admin/remotecontrol``. If the URL already contains ``index.php`` (as in our .env), it is kept as-is. """ base = base_url.strip().rstrip("/") if "index.php" in base: return base return f"{base}/index.php?r=admin/remotecontrol" def make_ssl_context(verify_ssl: bool = True) -> ssl.SSLContext | None: """Create an SSLContext for the HTTPS connection. ``verify_ssl=True`` (default) → ``None`` (urllib then uses its standard, verifying context). ``verify_ssl=False`` → context without hostname and certificate check — ONLY for local test instances with a wrong/self-signed certificate, NEVER for production. """ if verify_ssl: return None ctx = ssl.create_default_context() ctx.check_hostname = False ctx.verify_mode = ssl.CERT_NONE return ctx def _snippet(value: Any, limit: int = MAX_SNIPPET) -> str: """Make a short, log-safe snippet of a value.""" text = value if isinstance(value, str) else repr(value) if len(text) <= limit: return text return text[:limit] + "...(truncated)" def _looks_like_auth_error(method: str, message: str | None) -> bool: if method == "get_session_key": return True msg = (message or "").lower() return any(hint in msg for hint in _AUTH_HINTS) def rpc_call( url: str, method: str, params: list[Any], timeout: int = DEFAULT_TIMEOUT, ssl_context: ssl.SSLContext | None = None, ) -> Any: """Perform one JSON-RPC 2.0 call to ``url`` and return ``result``. Args: url: the full RemoteControl endpoint (see ``endpoint_url``). method: RPC method, e.g. ``"get_session_key"``. params: list of parameters (positional order matters in LimeSurvey). timeout: timeout in seconds for the HTTP call. ssl_context: optional ``ssl.SSLContext`` (see ``make_ssl_context``); ``None`` = standard verifying context. Returns: The ``result`` field of the JSON-RPC response. Raises: LsConnectionError: server unreachable, timeout, SSL error (incl. certificate mismatch), HTTP error status or no valid JSON-RPC response (method/params/HTTP status/body in message and attributes). LsApiError: the response contains a JSON-RPC ``error`` (original ``rpc_code``/``rpc_message`` in the attributes). LsAuthError: subtype of LsApiError for login/session-key problems. """ req_id = next(_ids) payload = {"jsonrpc": "2.0", "method": method, "params": params, "id": req_id} body = json.dumps(payload, ensure_ascii=False).encode("utf-8") request = urllib.request.Request( url, data=body, headers={"Content-Type": "application/json", "Accept": "application/json"}, method="POST", ) logger.debug( "RPC request → POST %s | method=%s params=%s", url, method, _snippet(json.dumps(params, ensure_ascii=False, default=str)), ) http_status: int | None = None raw_body = b"" try: with urllib.request.urlopen(request, timeout=timeout, context=ssl_context) as response: http_status = response.status raw_body = response.read() except urllib.error.HTTPError as exc: # the server did respond, but with an HTTP error status — the body often holds the cause try: raw_body = exc.read() except Exception: raw_body = b"" text = raw_body.decode("utf-8", errors="replace") snippet = _snippet(text) raise LsConnectionError( f"RPC {method!r} (params={_snippet(params)}) to {url} → HTTP {exc.code}, body: {snippet}", url=url, cause=exc, http_status=exc.code, body=snippet, ) from exc except (urllib.error.URLError, TimeoutError, OSError) as exc: raise LsConnectionError( f"RPC {method!r} (params={_snippet(params)}) to {url} failed — server unreachable/timeout: {exc}", url=url, cause=exc, ) from exc text = raw_body.decode("utf-8", errors="replace") logger.debug("RPC response ← method=%s HTTP %s body=%s", method, http_status, _snippet(text)) try: out = json.loads(text) except json.JSONDecodeError as exc: raise LsConnectionError( f"RPC {method!r} (params={_snippet(params)}) to {url} returned no valid JSON (HTTP {http_status}), body: {_snippet(text)}", url=url, cause=exc, http_status=http_status, body=_snippet(text), ) from exc if not isinstance(out, dict): raise LsConnectionError( f"RPC {method!r} to {url} returned no JSON-RPC object (HTTP {http_status}), body: {_snippet(text)}", url=url, http_status=http_status, body=_snippet(text), ) if out.get("statistic") is not None: logger.debug("RPC statistic field for %s: %s", method, out["statistic"]) if out.get("error"): err = out["error"] if isinstance(err, dict): code = err.get("code") message = err.get("message") else: code = None message = str(err) exc_cls = LsAuthError if _looks_like_auth_error(method, message) else LsApiError raise exc_cls( f"RPC {method!r} (params={_snippet(params)}) to {url} → HTTP {http_status}, " f"API error code={code}: {message} | body: {_snippet(text)}", method=method, rpc_code=code, rpc_message=message, raw=err, http_status=http_status, body=_snippet(text), ) return out.get("result") class RpcClient: """Wrapper around ``rpc_call`` with a fixed endpoint URL and timeout.""" def __init__( self, url: str, timeout: int = DEFAULT_TIMEOUT, ssl_context: ssl.SSLContext | None = None, ) -> None: self.url = url self.timeout = timeout self.ssl_context = ssl_context @classmethod def from_config(cls, config: LsConfig) -> RpcClient: """Build a client from an ``LsConfig`` (base_url, timeout, verify_ssl).""" return cls( endpoint_url(config.base_url), timeout=config.timeout, ssl_context=make_ssl_context(config.verify_ssl), ) def call(self, method: str, params: list[Any]) -> Any: """Perform an RPC call on the fixed endpoint URL.""" return rpc_call(self.url, method, params, timeout=self.timeout, ssl_context=self.ssl_context)