plugin XEP-0050: use Enums and add type hints:

- Replaces namedtuple with enums which are more appropriate here.
- Add docstrings and type hints to `AdHocCommand`

rel 465
This commit is contained in:
Goffi 2025-10-01 17:57:47 +02:00
commit a32b8bf9e8

View file

@ -17,24 +17,25 @@
# along with this program. If not, see <http://www.gnu.org/licenses/>.
from collections import namedtuple
from uuid import uuid4
from enum import Enum, StrEnum, auto
from typing import Callable
from uuid import uuid4
from zope.interface import implementer
from twisted.internet import defer
from twisted.words.protocols.jabber import jid
from twisted.words.protocols.jabber.error import StanzaError
from twisted.words.protocols.jabber.xmlstream import XMPPHandler
from twisted.words.xish import domish
from twisted.internet import defer
from wokkel import disco, iwokkel, data_form
from libervia.backend.core.i18n import _, D_
from libervia.backend.core.constants import Const as C
from libervia.backend.core.log import getLogger
from libervia.backend.core.core_types import SatXMPPEntity
from wokkel import data_form, disco, iwokkel
from zope.interface import implementer
from libervia.backend.core import exceptions
from libervia.backend.core.constants import Const as C
from libervia.backend.core.core_types import SatXMPPEntity
from libervia.backend.core.i18n import D_, _
from libervia.backend.core.log import getLogger
from libervia.backend.memory.memory import Sessions
from libervia.backend.tools import xml_tools, utils
from libervia.backend.tools import utils, xml_tools
from libervia.backend.tools.common import data_format
@ -68,50 +69,83 @@ PLUGIN_INFO = {
}
Status = namedtuple("Status", ("EXECUTING", "COMPLETED", "CANCELED"))
Action = namedtuple("Action", ("EXECUTE", "CANCEL", "NEXT", "PREV"))
Note = namedtuple("Note", ("INFO", "WARN", "ERROR"))
Error = namedtuple(
"Error",
(
"MALFORMED_ACTION",
"BAD_ACTION",
"BAD_LOCALE",
"BAD_PAYLOAD",
"BAD_SESSIONID",
"SESSION_EXPIRED",
"FORBIDDEN",
"ITEM_NOT_FOUND",
"FEATURE_NOT_IMPLEMENTED",
"INTERNAL",
),
)
class Status(StrEnum):
EXECUTING = auto()
COMPLETED = auto()
CANCELED = auto()
class Action(StrEnum):
EXECUTE = auto()
CANCEL = auto()
NEXT = auto()
PREV = auto()
class Note(StrEnum):
INFO = auto()
WARN = auto()
ERROR = auto()
class Error(tuple[str, str | None], Enum):
"""Errors from XEP-0050 §4.4 Table 5"""
MALFORMED_ACTION = ("bad-request", "malformed-action")
BAD_ACTION = ("bad-request", "bad-action")
BAD_LOCALE = ("bad-request", "bad-locale")
BAD_PAYLOAD = ("bad-request", "bad-payload")
BAD_SESSIONID = ("bad-request", "bad-sessionid")
SESSION_EXPIRED = ("not-allowed", "session-expired")
FORBIDDEN = ("forbidden", None)
ITEM_NOT_FOUND = ("item-not-found", None)
FEATURE_NOT_IMPLEMENTED = ("feature-not-implemented", None)
INTERNAL = ("internal-server-error", None)
class AdHocError(Exception):
def __init__(self, error_const):
"""Error to be used from callback
@param error_const: one of XEP_0050.ERROR
@param error_const: one of Error
"""
assert error_const in XEP_0050.ERROR
assert error_const in Error
self.callback_error = error_const
@implementer(iwokkel.IDisco)
class AdHocCommand(XMPPHandler):
"""Implementation of an Ad-Hoc Command handler for XMPP.
This class handles the execution of ad-hoc commands as defined in XEP-0050.
It manages command sessions, authorization checks, and communication with clients.
"""
def __init__(
self,
callback,
label,
node,
features,
timeout,
allowed_jids,
allowed_groups,
allowed_magics,
forbidden_jids,
forbidden_groups,
):
callback: Callable,
label: str,
node: str,
features: list[str],
timeout: int,
allowed_jids: list[jid.JID],
allowed_groups: list[str],
allowed_magics: list[str],
forbidden_jids: list[jid.JID],
forbidden_groups: list[str],
) -> None:
"""Initialize the AdHocCommand handler.
@param callback: The callback function to execute when command is invoked
@param label: Label for the command displayed in UI
@param node: Unique identifier for this command
@param features: List of features supported by this command
@param timeout: Session timeout in seconds
@param allowed_jids: List of JIDs that are allowed to use this command
@param allowed_groups: List of roster groups that are allowed to use this command
@param allowed_magics: List of magic identifiers for special access rules
@param forbidden_jids: List of JIDs that are forbidden from using this command
@param forbidden_groups: List of roster groups that are forbidden from using this
command
"""
XMPPHandler.__init__(self)
self.callback = callback
self.label = label
@ -125,13 +159,28 @@ class AdHocCommand(XMPPHandler):
self.sessions = Sessions(timeout=timeout)
@property
def client(self):
def client(self) -> SatXMPPEntity:
"""Get the client associated with this command handler.
@return: The XMPP client instance
"""
assert self.parent is not None
return self.parent
def getName(self, xml_lang=None):
def getName(self, xml_lang: str | None = None) -> str:
"""Get the name of this command for display purposes.
@param xml_lang: Language code for localization (unused)
@return: The label of this command
"""
return self.label
def is_authorised(self, requestor):
def is_authorised(self, requestor: jid.JID) -> bool:
"""Check if a requestor is authorized to use this command.
@param requestor: JID of the entity requesting access
@return: True if authorized, False otherwise
"""
if C.ENTITY_ALL in self.allowed_magics:
return True
forbidden = set(self.forbidden_jids)
@ -153,7 +202,16 @@ class AdHocCommand(XMPPHandler):
return True
return False
def getDiscoInfo(self, requestor, target, nodeIdentifier=""):
def getDiscoInfo(
self, requestor: jid.JID, target: jid.JID, nodeIdentifier: str = ""
) -> list[disco.DiscoFeature]:
"""Get disco info for this command.
@param requestor: JID of the entity requesting information
@param target: Target JID
@param nodeIdentifier: Node identifier (unused)
@return: List of disco features supported by this command
"""
if (
nodeIdentifier != NS_COMMANDS
): # FIXME: we should manage other disco nodes here
@ -161,38 +219,46 @@ class AdHocCommand(XMPPHandler):
# identities = [ID_CMD_LIST if self.node == NS_COMMANDS else ID_CMD_NODE] # FIXME
return [disco.DiscoFeature(NS_COMMANDS)] + self.features
def getDiscoItems(self, requestor, target, nodeIdentifier=""):
def getDiscoItems(
self, requestor: jid.JID, target: jid.JID, nodeIdentifier: str = ""
) -> list[disco.DiscoItem]:
"""Get disco items for this command.
@param requestor: JID of the entity requesting information
@param target: Target JID
@param nodeIdentifier: Node identifier (unused)
@return: Empty list as no items are supported
"""
return []
def _sendAnswer(
self,
callback_data: tuple[
tuple[domish.Element, None],
domish.Element | None,
Status,
list[str] | None,
tuple[Note, str] | None,
],
session_id,
request,
session_id: str,
request: domish.Element,
) -> None:
"""Send result of the command
"""Send result of the command.
@param callback_data: tuple (payload, status, actions, note) with:
- payload: usualy containing data form
- payload: usually containing data form
- status: current status
- actions: list of allowed actions (see XEP_0050.ACTION).
- actions: list of allowed actions (see Action).
First action is the default one. Default to EXECUTE
- note: optional additional note: either None or a tuple with (note type,
human readable string)
@param session_id: current session id
@param request: original request (domish.Element)
@return: deferred
"""
payload, status, actions, note = callback_data
assert isinstance(payload, domish.Element) or payload is None
assert status in XEP_0050.STATUS
assert status in Status
if not actions:
actions = [XEP_0050.ACTION.EXECUTE]
actions = [Action.EXECUTE]
result = domish.Element((None, "iq"))
result["type"] = "result"
result["id"] = request["id"]
@ -202,8 +268,8 @@ class AdHocCommand(XMPPHandler):
command_elt["node"] = self.node
command_elt["status"] = status
if status != XEP_0050.STATUS.CANCELED:
if status != XEP_0050.STATUS.COMPLETED:
if status != Status.CANCELED:
if status != Status.COMPLETED:
actions_elt = command_elt.addElement("actions")
actions_elt["execute"] = actions[0]
for action in actions:
@ -218,13 +284,19 @@ class AdHocCommand(XMPPHandler):
command_elt.addChild(payload)
self.client.send(result)
if status in (XEP_0050.STATUS.COMPLETED, XEP_0050.STATUS.CANCELED):
if status in (Status.COMPLETED, Status.CANCELED):
del self.sessions[session_id]
def _sendError(self, error_constant, session_id, request):
"""Send error stanza
def _sendError(
self,
error_constant: tuple[str, str | None],
session_id: str,
request: domish.Element,
) -> None:
"""Send error stanza.
@param error_constant: one of XEP_OO50.ERROR
@param error_constant: one of Error
@param session_id: Session ID
@param request: original request (domish.Element)
"""
xmpp_condition, cmd_condition = error_constant
@ -235,36 +307,54 @@ class AdHocCommand(XMPPHandler):
self.client.send(iq_elt)
del self.sessions[session_id]
def _request_eb(self, failure_, request, session_id):
def _request_eb(
self, failure_: defer.Failure, request: domish.Element, session_id: str
) -> None:
"""Error handler for command requests.
@param failure_: The error that occurred
@param request: Original request (domish.Element)
@param session_id: Session ID
"""
if failure_.check(AdHocError):
error_constant = failure_.value.callback_error
else:
log.error(f"unexpected error while handling request: {failure_}")
error_constant = XEP_0050.ERROR.INTERNAL
error_constant = Error.INTERNAL
self._sendError(error_constant, session_id, request)
def on_request(self, command_elt, requestor, action, session_id):
def on_request(
self,
command_elt: domish.Element,
requestor: jid.JID,
action: str,
session_id: str | None,
) -> None:
"""Handle an incoming command request.
@param command_elt: The command element from the request
@param requestor: JID of the entity making the request
@param action: The action to perform (execute, cancel, etc.)
@param session_id: Session ID if continuing an existing session
@return: Deferred for handling the response
"""
if not self.is_authorised(requestor):
return self._sendError(
XEP_0050.ERROR.FORBIDDEN, session_id, command_elt.parent
)
return self._sendError(Error.FORBIDDEN, session_id, command_elt.parent)
if session_id:
try:
session_data = self.sessions[session_id]
except KeyError:
return self._sendError(
XEP_0050.ERROR.SESSION_EXPIRED, session_id, command_elt.parent
Error.SESSION_EXPIRED, session_id, command_elt.parent
)
if session_data["requestor"] != requestor:
return self._sendError(
XEP_0050.ERROR.FORBIDDEN, session_id, command_elt.parent
)
return self._sendError(Error.FORBIDDEN, session_id, command_elt.parent)
else:
session_id, session_data = self.sessions.new_session()
session_data["requestor"] = requestor
if action == XEP_0050.ACTION.CANCEL:
d = defer.succeed((None, XEP_0050.STATUS.CANCELED, None, None))
if action == Action.CANCEL:
d = defer.succeed((None, Status.CANCELED, None, None))
else:
d = utils.as_deferred(
self.callback,
@ -279,21 +369,6 @@ class AdHocCommand(XMPPHandler):
class XEP_0050:
STATUS = Status("executing", "completed", "canceled")
ACTION = Action("execute", "cancel", "next", "prev")
NOTE = Note("info", "warn", "error")
ERROR = Error(
("bad-request", "malformed-action"),
("bad-request", "bad-action"),
("bad-request", "bad-locale"),
("bad-request", "bad-payload"),
("bad-request", "bad-sessionid"),
("not-allowed", "session-expired"),
("forbidden", None),
("item-not-found", None),
("feature-not-implemented", None),
("internal-server-error", None),
) # XEP-0050 §4.4 Table 5
def __init__(self, host):
log.info(_("plugin XEP-0050 initialization"))
@ -357,7 +432,7 @@ class XEP_0050:
@param entity(jid.JID): entity which will execture the command
@param node(unicode): node of the command
@param action(unicode): one of XEP_0050.ACTION
@param action(unicode): one of Action
@param session_id(unicode, None): id of the ad-hoc session
None if no session is involved
@param form_values(dict, None): values to use to create command form
@ -386,10 +461,10 @@ class XEP_0050:
except StopIteration:
raise exceptions.NotFound(_("Missing command element"))
def ad_hoc_error(self, error_type):
def ad_hoc_error(self, error_type: Error):
"""Shortcut to raise an AdHocError
@param error_type(unicode): one of XEP_0050.ERROR
@param error_type(unicode): one of Error
"""
raise AdHocError(error_type)
@ -436,7 +511,7 @@ class XEP_0050:
def parse_command_answer(self, iq_elt):
command_elt = self.get_command_elt(iq_elt)
data = {}
data["status"] = command_elt.getAttribute("status", XEP_0050.STATUS.EXECUTING)
data["status"] = command_elt.getAttribute("status", Status.EXECUTING)
data["session_id"] = command_elt.getAttribute("sessionid")
data["notes"] = notes = []
for note_elt in command_elt.elements(NS_COMMANDS, "note"):
@ -458,10 +533,10 @@ class XEP_0050:
"""
command_elt, answer_data = self.parse_command_answer(iq_elt)
status = answer_data["status"]
if status in [XEP_0050.STATUS.COMPLETED, XEP_0050.STATUS.CANCELED]:
if status in [Status.COMPLETED, Status.CANCELED]:
# the command session is finished, we purge our session
del self.requesting[session_id]
if status == XEP_0050.STATUS.COMPLETED:
if status == Status.COMPLETED:
session_id = None
else:
return None
@ -474,7 +549,7 @@ class XEP_0050:
break
else:
# no matching data element found
if status != XEP_0050.STATUS.COMPLETED:
if status != Status.COMPLETED:
log.warning(
_("No known payload found in ad-hoc command result, aborting")
)
@ -586,7 +661,7 @@ class XEP_0050:
client,
entity,
session_data["node"],
action=XEP_0050.ACTION.EXECUTE,
action=Action.EXECUTE,
session_id=remote_id,
form_values=data_form_values,
)
@ -614,7 +689,7 @@ class XEP_0050:
if len(actions) == 1:
# it's our first request, we ask the desired new status
status = XEP_0050.STATUS.EXECUTING
status = Status.EXECUTING
form = data_form.Form("form", title=_("status selection"))
show_options = [
data_form.Option(name, label) for name, label in list(SHOWS.items())
@ -634,20 +709,20 @@ class XEP_0050:
answer_form = data_form.Form.fromElement(x_elt)
show = answer_form["show"]
except (KeyError, StopIteration):
self.ad_hoc_error(XEP_0050.ERROR.BAD_PAYLOAD)
self.ad_hoc_error(Error.BAD_PAYLOAD)
if show not in SHOWS:
self.ad_hoc_error(XEP_0050.ERROR.BAD_PAYLOAD)
self.ad_hoc_error(Error.BAD_PAYLOAD)
if show == "disconnect":
self.host.disconnect(client.profile)
else:
self.host.presence_set(show=show, profile_key=client.profile)
# job done, we can end the session
status = XEP_0050.STATUS.COMPLETED
status = Status.COMPLETED
payload = None
note = (self.NOTE.INFO, _("Status updated"))
note = (Note.INFO, _("Status updated"))
else:
self.ad_hoc_error(XEP_0050.ERROR.INTERNAL)
self.ad_hoc_error(Error.INTERNAL)
return (payload, status, None, note)