PyLimeRPC: package pylimerpc + pyproject + tests/examples (overname van minimalLS)
- nieuwe package `pylimerpc/` (rpc, session, surveys, tokens, responses, errors, utils, config) - pyproject.toml (name PyLimeRPC, versie 0.1.0) - tests/ (69 passed, 2 deselected) en examples/ - .env.example: TLS-verificatie documentatie (LIMESURVEY_VERIFY_SSL) - README/.gitignore bijgewerkt Generated by Mistral Vibe. Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
parent
30fc89e4e2
commit
d7d9dc61bf
1 changed files with 2853 additions and 14 deletions
250
pylimerpc/rpc.py
Normal file
250
pylimerpc/rpc.py
Normal file
|
|
@ -0,0 +1,250 @@
|
|||
"""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)
|
||||
Loading…
Reference in a new issue