PyLimeRPC/pylimerpc/rpc.py

250 lines
8.6 KiB
Python
Raw Normal View History

"""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)