250 lines
8.6 KiB
Python
250 lines
8.6 KiB
Python
|
|
"""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)
|