209 lines
6.1 KiB
Python
209 lines
6.1 KiB
Python
########################################################################
|
|
# File name: service.py
|
|
# This file is part of: aioxmpp
|
|
#
|
|
# LICENSE
|
|
#
|
|
# This program is free software: you can redistribute it and/or modify
|
|
# it under the terms of the GNU Lesser General Public License as
|
|
# published by the Free Software Foundation, either version 3 of the
|
|
# License, or (at your option) any later version.
|
|
#
|
|
# This program is distributed in the hope that it will be useful, but
|
|
# WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
# Lesser General Public License for more details.
|
|
#
|
|
# You should have received a copy of the GNU Lesser General Public
|
|
# License along with this program. If not, see
|
|
# <http://www.gnu.org/licenses/>.
|
|
#
|
|
########################################################################
|
|
import asyncio
|
|
import typing
|
|
|
|
import aioxmpp
|
|
import aioxmpp.disco
|
|
import aioxmpp.errors
|
|
import aioxmpp.service
|
|
|
|
from . import xso as version_xso
|
|
|
|
|
|
class VersionServer(aioxmpp.service.Service):
|
|
"""
|
|
:class:`~aioxmpp.service.Service` which handles inbound :xep:`92` Software
|
|
Version requests.
|
|
|
|
.. warning::
|
|
|
|
Do **not** depend on this service in another service. This service
|
|
exposes possibly private or sensitive information over the XMPP
|
|
network without any filtering. Implicitly summoning this service via
|
|
a dependency is thus discouraged.
|
|
|
|
*If* you absolutely need to do this for the implementation of another
|
|
published XEP, please file an issue against :mod:`aioxmpp` so that we
|
|
can work out a good solution.
|
|
|
|
.. warning::
|
|
|
|
This service does answer version queries, no matter who asks. This may
|
|
not be desirable, in which case this service is not for you.
|
|
|
|
.. seealso::
|
|
|
|
:func:`~.version.query_version`
|
|
for a function to obtain another entities software version.
|
|
|
|
.. note::
|
|
|
|
By default, this service does not reply to version queries. The
|
|
:attr:`name` attribute needs to be set first.
|
|
|
|
The response can be configured with the following attributes:
|
|
|
|
.. autoattribute:: name
|
|
:annotation: = None
|
|
|
|
.. autoattribute:: version
|
|
:annotation: = None
|
|
|
|
.. autoattribute:: os
|
|
:annotation: = distro.name() or platform.system()
|
|
"""
|
|
|
|
ORDER_AFTER = [
|
|
aioxmpp.disco.DiscoServer,
|
|
]
|
|
|
|
disco_feature = aioxmpp.disco.register_feature(
|
|
"jabber:iq:version",
|
|
)
|
|
|
|
def __init__(self, client, **kwargs):
|
|
super().__init__(client, **kwargs)
|
|
try:
|
|
import distro
|
|
except ImportError:
|
|
import platform
|
|
self._os = platform.system()
|
|
else:
|
|
self._os = distro.name()
|
|
|
|
self._name = None
|
|
self._version = None
|
|
|
|
@property
|
|
def os(self) -> typing.Optional[str]:
|
|
"""
|
|
The operating system of this entity.
|
|
|
|
Defaults to :func:`distro.name` or :func:`platform.system` (if
|
|
:mod:`distro` is not available).
|
|
|
|
This attribute can be set to :data:`None` or deleted to prevent
|
|
inclusion of the OS element in the reply.
|
|
"""
|
|
return self._os
|
|
|
|
@os.setter
|
|
def os(self, value: typing.Optional[str]):
|
|
if value is None:
|
|
self._os = None
|
|
else:
|
|
self._os = str(value)
|
|
|
|
@os.deleter
|
|
def os(self):
|
|
self._os = None
|
|
|
|
@property
|
|
def name(self) -> typing.Optional[str]:
|
|
"""
|
|
The software name of this entity.
|
|
|
|
Defaults to :data:`None`.
|
|
|
|
If this attribute is :data:`None`, version requests are not answered
|
|
but fail with a ``service-unavailable`` error.
|
|
"""
|
|
return self._name
|
|
|
|
@name.setter
|
|
def name(self, value: typing.Optional[str]):
|
|
if value is None:
|
|
self._name = None
|
|
else:
|
|
self._name = str(value)
|
|
|
|
@name.deleter
|
|
def name(self):
|
|
self._name = None
|
|
|
|
@property
|
|
def version(self) -> typing.Optional[str]:
|
|
"""
|
|
The software version of this entity.
|
|
|
|
Defaults to :data:`None`.
|
|
|
|
If this attribute is :data:`None` or the empty string, the version will
|
|
be shown as ``"unspecified"`` to other entities. This can be used to
|
|
avoid disclosing the specific version of the software.
|
|
"""
|
|
return self._version
|
|
|
|
@version.setter
|
|
def version(self, value: typing.Optional[str]):
|
|
if value is None:
|
|
self._version = None
|
|
else:
|
|
self._version = str(value)
|
|
|
|
@version.deleter
|
|
def version(self):
|
|
self._version = None
|
|
|
|
@aioxmpp.service.iq_handler(aioxmpp.IQType.GET,
|
|
version_xso.Query)
|
|
async def handle_query(self, iq: aioxmpp.IQ) -> version_xso.Query:
|
|
if self._name is None:
|
|
raise aioxmpp.errors.XMPPCancelError(
|
|
aioxmpp.errors.ErrorCondition.SERVICE_UNAVAILABLE,
|
|
)
|
|
|
|
result = version_xso.Query()
|
|
result.name = self._name
|
|
result.os = self._os
|
|
result.version = self._version or "unspecified"
|
|
return result
|
|
|
|
|
|
async def query_version(stream: aioxmpp.stream.StanzaStream,
|
|
target: aioxmpp.JID) -> version_xso.Query:
|
|
"""
|
|
Query the software version of an entity.
|
|
|
|
:param stream: A stanza stream to send the query on.
|
|
:type stream: :class:`aioxmpp.stream.StanzaStream`
|
|
:param target: The address of the entity to query.
|
|
:type target: :class:`aioxmpp.JID`
|
|
:raises OSError: if a connection issue occurred before a reply was received
|
|
:raises aioxmpp.errors.XMPPError: if an XMPP error was returned instead
|
|
of a reply.
|
|
:rtype: :class:`aioxmpp.version.xso.Query`
|
|
:return: The response from the peer.
|
|
|
|
The response is returned as :class:`~aioxmpp.version.xso.Query` object. The
|
|
attributes hold the data returned by the peer. Each attribute may be
|
|
:data:`None` if the peer chose to omit that information. In an extreme
|
|
case, all attributes are :data:`None`.
|
|
"""
|
|
|
|
return await stream.send(aioxmpp.IQ(
|
|
type_=aioxmpp.IQType.GET,
|
|
to=target,
|
|
payload=version_xso.Query(),
|
|
))
|