2023-05-13 12:35:20 +02:00
|
|
|
import asyncio
|
2018-01-29 13:47:21 +01:00
|
|
|
import os
|
2023-05-06 22:04:48 +02:00
|
|
|
import pathlib
|
|
|
|
import secrets
|
2019-02-07 14:26:10 +01:00
|
|
|
import threading
|
2018-01-04 02:45:23 +01:00
|
|
|
|
2023-05-07 19:38:40 +02:00
|
|
|
from multiprocessing import Process
|
2023-05-13 12:35:20 +02:00
|
|
|
from time import time
|
|
|
|
from typing import List, Mapping, Optional
|
|
|
|
from tornado.httpserver import HTTPServer
|
2021-09-16 17:53:40 +02:00
|
|
|
|
2023-05-13 12:35:20 +02:00
|
|
|
from tornado.netutil import bind_sockets
|
|
|
|
from tornado.process import cpu_count, fork_processes
|
2023-05-07 19:38:40 +02:00
|
|
|
from tornado.wsgi import WSGIContainer
|
|
|
|
from tornado.web import Application, FallbackHandler
|
|
|
|
|
2019-02-23 21:19:00 +01:00
|
|
|
from platypush.backend import Backend
|
2019-02-24 00:11:35 +01:00
|
|
|
from platypush.backend.http.app import application
|
2023-05-09 00:03:11 +02:00
|
|
|
from platypush.backend.http.app.utils import get_ws_routes
|
|
|
|
from platypush.backend.http.app.ws.events import events_redis_topic
|
2023-05-07 19:38:40 +02:00
|
|
|
|
2023-05-02 21:24:50 +02:00
|
|
|
from platypush.bus.redis import RedisBus
|
2023-05-06 22:04:48 +02:00
|
|
|
from platypush.config import Config
|
2023-05-07 12:08:28 +02:00
|
|
|
from platypush.utils import get_redis
|
2018-01-04 02:45:23 +01:00
|
|
|
|
|
|
|
|
|
|
|
class HttpBackend(Backend):
|
2018-06-26 00:16:39 +02:00
|
|
|
"""
|
2021-02-22 01:20:01 +01:00
|
|
|
The HTTP backend is a general-purpose web server.
|
2018-06-26 00:16:39 +02:00
|
|
|
|
2021-02-22 01:20:01 +01:00
|
|
|
Example configuration:
|
2018-06-26 00:16:39 +02:00
|
|
|
|
2021-02-22 01:20:01 +01:00
|
|
|
.. code-block:: yaml
|
|
|
|
|
|
|
|
backend.http:
|
|
|
|
# Default HTTP listen port
|
|
|
|
port: 8008
|
|
|
|
# External folders that will be exposed over `/resources/<name>`
|
|
|
|
resource_dirs:
|
|
|
|
photos: /mnt/hd/photos
|
|
|
|
videos: /mnt/hd/videos
|
|
|
|
music: /mnt/hd/music
|
|
|
|
|
|
|
|
You can leverage this backend:
|
|
|
|
|
|
|
|
* To execute Platypush commands via HTTP calls. In order to do so:
|
|
|
|
|
2023-05-09 02:40:32 +02:00
|
|
|
* Register a user to Platypush through the web panel (usually
|
|
|
|
served on ``http://host:8008/``).
|
2021-02-22 01:20:01 +01:00
|
|
|
|
2023-05-09 02:40:32 +02:00
|
|
|
* Generate a token for your user, either through the web panel
|
|
|
|
(Settings -> Generate Token) or via API:
|
2021-02-22 01:20:01 +01:00
|
|
|
|
|
|
|
.. code-block:: shell
|
|
|
|
|
|
|
|
curl -XPOST -H 'Content-Type: application/json' -d '
|
|
|
|
{
|
|
|
|
"username": "$YOUR_USER",
|
|
|
|
"password": "$YOUR_PASSWORD"
|
|
|
|
}' http://host:8008/auth
|
|
|
|
|
2021-02-22 01:35:42 +01:00
|
|
|
* Execute actions through the ``/execute`` endpoint:
|
2021-02-22 01:20:01 +01:00
|
|
|
|
|
|
|
.. code-block:: shell
|
|
|
|
|
|
|
|
curl -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" -d '
|
|
|
|
{
|
|
|
|
"type": "request",
|
|
|
|
"action": "tts.say",
|
|
|
|
"args": {
|
|
|
|
"text": "This is a test"
|
|
|
|
}
|
2021-02-22 02:53:20 +01:00
|
|
|
}' http://host:8008/execute
|
2018-06-26 00:16:39 +02:00
|
|
|
|
2023-05-09 02:40:32 +02:00
|
|
|
* To interact with your system (and control plugins and backends)
|
|
|
|
through the Platypush web panel, by default available on
|
|
|
|
``http://host:8008/``. Any configured plugin that has an available
|
|
|
|
panel plugin will be automatically added to the web panel.
|
|
|
|
|
|
|
|
* To create asynchronous integrations with Platypush over websockets.
|
|
|
|
Two routes are available:
|
|
|
|
|
|
|
|
* ``/ws/events`` - Subscribe to this websocket to receive the
|
|
|
|
events generated by the application.
|
|
|
|
* ``/ws/requests`` - Subscribe to this websocket to send commands
|
|
|
|
to Platypush and receive the response asynchronously.
|
|
|
|
|
|
|
|
You will have to authenticate your connection to these websockets,
|
|
|
|
just like the ``/execute`` endpoint. In both cases, you can pass the
|
|
|
|
token either via ``Authorization: Bearer``, via the ``token`` query
|
|
|
|
string or body parameter, or leverage ``Authorization: Basic`` with
|
|
|
|
username and password (not advised), or use a valid ``session_token``
|
|
|
|
cookie from an authenticated web panel session.
|
2021-02-22 01:20:01 +01:00
|
|
|
|
|
|
|
* To display a fullscreen dashboard with custom widgets.
|
|
|
|
|
2023-05-09 02:40:32 +02:00
|
|
|
* Widgets are available as Vue.js components under
|
|
|
|
``platypush/backend/http/webapp/src/components/widgets``.
|
2021-02-22 01:20:01 +01:00
|
|
|
|
2023-05-09 02:40:32 +02:00
|
|
|
* Explore their options (some may require some plugins or backends
|
|
|
|
to be configured in order to work) and create a new dashboard
|
|
|
|
template under ``~/.config/platypush/dashboards``- e.g.
|
|
|
|
``main.xml``:
|
2018-06-26 00:16:39 +02:00
|
|
|
|
2021-02-22 01:20:01 +01:00
|
|
|
.. code-block:: xml
|
2018-06-26 00:16:39 +02:00
|
|
|
|
2021-02-22 01:20:01 +01:00
|
|
|
<Dashboard>
|
|
|
|
<!-- Display the following widgets on the same row. Each row consists of 12 columns.
|
|
|
|
You can specify the width of each widget either through class name (e.g. col-6 means
|
|
|
|
6 columns out of 12, e.g. half the size of the row) or inline style
|
|
|
|
(e.g. `style="width: 50%"`). -->
|
|
|
|
<Row>
|
|
|
|
<!-- Show a calendar widget with the upcoming events. It requires the `calendar` plugin to
|
|
|
|
be enabled and configured. -->
|
|
|
|
<Calendar class="col-6" />
|
|
|
|
|
|
|
|
<!-- Show the current track and other playback info. It requires `music.mpd` plugin or any
|
|
|
|
other music plugin enabled. -->
|
|
|
|
<Music class="col-3" />
|
|
|
|
|
2022-04-27 14:52:41 +02:00
|
|
|
<!-- Show current date, time and weather.
|
|
|
|
It requires a `weather` plugin or backend enabled -->
|
2021-02-22 01:20:01 +01:00
|
|
|
<DateTimeWeather class="col-3" />
|
|
|
|
</Row>
|
|
|
|
|
|
|
|
<!-- Display the following widgets on a second row -->
|
|
|
|
<Row>
|
|
|
|
<!-- Show a carousel of images from a local folder. For security reasons, the folder must be
|
2022-04-27 14:52:41 +02:00
|
|
|
explicitly exposed as an HTTP resource through the backend
|
|
|
|
`resource_dirs` attribute. -->
|
2021-02-22 01:20:01 +01:00
|
|
|
<ImageCarousel class="col-6" img-dir="/mnt/hd/photos/carousel" />
|
|
|
|
|
|
|
|
<!-- Show the news headlines parsed from a list of RSS feed and stored locally through the
|
|
|
|
`http.poll` backend -->
|
|
|
|
<RssNews class="col-6" db="sqlite:////path/to/your/rss.db" />
|
|
|
|
</Row>
|
|
|
|
</Dashboard>
|
|
|
|
|
2023-05-09 02:40:32 +02:00
|
|
|
* The dashboard will be accessible under
|
|
|
|
``http://host:8008/dashboard/<name>``, where ``name=main`` if for
|
|
|
|
example you stored your template under
|
|
|
|
``~/.config/platypush/dashboards/main.xml``.
|
2021-02-22 01:20:01 +01:00
|
|
|
|
2023-05-09 02:40:32 +02:00
|
|
|
* To expose custom endpoints that can be called as web hooks by other
|
|
|
|
applications and run some custom logic. All you have to do in this case
|
|
|
|
is to create a hook on a
|
|
|
|
:class:`platypush.message.event.http.hook.WebhookEvent` with the
|
|
|
|
endpoint that you want to expose and store it under e.g.
|
|
|
|
``~/.config/platypush/scripts/hooks.py``:
|
2021-02-22 01:20:01 +01:00
|
|
|
|
|
|
|
.. code-block:: python
|
|
|
|
|
|
|
|
from platypush.context import get_plugin
|
|
|
|
from platypush.event.hook import hook
|
|
|
|
from platypush.message.event.http.hook import WebhookEvent
|
|
|
|
|
|
|
|
hook_token = 'abcdefabcdef'
|
|
|
|
|
|
|
|
# Expose the hook under the /hook/lights_toggle endpoint
|
|
|
|
@hook(WebhookEvent, hook='lights_toggle')
|
|
|
|
def lights_toggle(event, **context):
|
|
|
|
# Do any checks on the request
|
|
|
|
assert event.headers.get('X-Token') == hook_token, 'Unauthorized'
|
|
|
|
|
|
|
|
# Run some actions
|
|
|
|
lights = get_plugin('light.hue')
|
|
|
|
lights.toggle()
|
2019-02-23 21:19:00 +01:00
|
|
|
|
|
|
|
Any plugin can register custom routes under ``platypush/backend/http/app/routes/plugins``.
|
|
|
|
Any additional route is managed as a Flask blueprint template and the `.py`
|
|
|
|
module can expose lists of routes to the main webapp through the
|
|
|
|
``__routes__`` object (a list of Flask blueprints).
|
|
|
|
|
2023-05-09 02:40:32 +02:00
|
|
|
Security: Access to the endpoints requires at least one user to be
|
|
|
|
registered. Access to the endpoints is regulated in the following ways
|
|
|
|
(with the exception of event hooks, whose logic is up to the user):
|
2021-02-22 01:20:01 +01:00
|
|
|
|
|
|
|
* **Simple authentication** - i.e. registered username and password.
|
2023-05-09 02:40:32 +02:00
|
|
|
* **JWT token** provided either over as ``Authorization: Bearer``
|
|
|
|
header or ``GET`` ``?token=<TOKEN>`` parameter. A JWT token can be
|
|
|
|
generated either through the web panel or over the ``/auth``
|
|
|
|
endpoint.
|
|
|
|
* **Global platform token**, usually configured on the root of the
|
|
|
|
``config.yaml`` as ``token: <VALUE>``. It can provided either over on
|
|
|
|
the ``X-Token`` header or as a ``GET`` ``?token=<TOKEN>`` parameter.
|
|
|
|
* **Session token**, generated upon login, it can be used to
|
|
|
|
authenticate requests through the ``Cookie`` header (cookie name:
|
|
|
|
``session_token``).
|
2018-07-08 21:36:58 +02:00
|
|
|
|
2018-06-26 00:16:39 +02:00
|
|
|
"""
|
2018-01-04 02:45:23 +01:00
|
|
|
|
2019-02-23 21:19:00 +01:00
|
|
|
_DEFAULT_HTTP_PORT = 8008
|
2023-05-13 12:35:20 +02:00
|
|
|
"""The default listen port for the webserver."""
|
2019-02-07 14:26:10 +01:00
|
|
|
|
2022-04-27 14:52:41 +02:00
|
|
|
def __init__(
|
|
|
|
self,
|
2023-05-07 12:08:28 +02:00
|
|
|
port: int = _DEFAULT_HTTP_PORT,
|
|
|
|
bind_address: str = '0.0.0.0',
|
|
|
|
resource_dirs: Optional[Mapping[str, str]] = None,
|
|
|
|
secret_key_file: Optional[str] = None,
|
2023-05-13 12:35:20 +02:00
|
|
|
num_workers: Optional[int] = None,
|
2023-02-08 00:46:50 +01:00
|
|
|
**kwargs,
|
2022-04-27 14:52:41 +02:00
|
|
|
):
|
2018-06-26 00:16:39 +02:00
|
|
|
"""
|
|
|
|
:param port: Listen port for the web server (default: 8008)
|
2021-02-23 23:07:35 +01:00
|
|
|
:param bind_address: Address/interface to bind to (default: 0.0.0.0, accept connection from any IP)
|
2018-12-30 18:40:03 +01:00
|
|
|
:param resource_dirs: Static resources directories that will be
|
|
|
|
accessible through ``/resources/<path>``. It is expressed as a map
|
|
|
|
where the key is the relative path under ``/resources`` to expose and
|
|
|
|
the value is the absolute path to expose.
|
2023-05-06 22:04:48 +02:00
|
|
|
:param secret_key_file: Path to the file containing the secret key that will be used by Flask
|
|
|
|
(default: ``~/.local/share/platypush/flask.secret.key``).
|
2023-05-13 12:35:20 +02:00
|
|
|
:param num_workers: Number of worker processes to use (default: ``(cpu_count * 2) + 1``).
|
2018-06-26 00:16:39 +02:00
|
|
|
"""
|
|
|
|
|
2018-01-04 02:45:23 +01:00
|
|
|
super().__init__(**kwargs)
|
2018-05-04 03:24:35 +02:00
|
|
|
|
2018-01-04 02:45:23 +01:00
|
|
|
self.port = port
|
2023-05-13 12:35:20 +02:00
|
|
|
self._server_proc: Optional[Process] = None
|
|
|
|
self._workers: List[Process] = []
|
2023-01-01 13:16:46 +01:00
|
|
|
self._service_registry_thread = None
|
2021-02-23 23:07:35 +01:00
|
|
|
self.bind_address = bind_address
|
2019-05-15 09:31:04 +02:00
|
|
|
|
|
|
|
if resource_dirs:
|
2022-04-27 14:52:41 +02:00
|
|
|
self.resource_dirs = {
|
|
|
|
name: os.path.abspath(os.path.expanduser(d))
|
|
|
|
for name, d in resource_dirs.items()
|
|
|
|
}
|
2019-05-15 09:31:04 +02:00
|
|
|
else:
|
|
|
|
self.resource_dirs = {}
|
|
|
|
|
2023-05-06 22:04:48 +02:00
|
|
|
self.secret_key_file = os.path.expanduser(
|
|
|
|
secret_key_file
|
2023-05-07 12:08:28 +02:00
|
|
|
or os.path.join(Config.get('workdir'), 'flask.secret.key') # type: ignore
|
2023-05-06 22:04:48 +02:00
|
|
|
)
|
2023-05-07 12:08:28 +02:00
|
|
|
self.local_base_url = f'http://localhost:{self.port}'
|
2023-05-13 12:35:20 +02:00
|
|
|
self.num_workers = num_workers or (cpu_count() * 2) + 1
|
2020-02-06 01:04:36 +01:00
|
|
|
|
2023-05-02 21:24:50 +02:00
|
|
|
def send_message(self, *_, **__):
|
2018-06-06 20:09:18 +02:00
|
|
|
self.logger.warning('Use cURL or any HTTP client to query the HTTP backend')
|
2018-01-04 02:45:23 +01:00
|
|
|
|
2019-02-23 21:19:00 +01:00
|
|
|
def on_stop(self):
|
2022-04-27 14:52:41 +02:00
|
|
|
"""On backend stop"""
|
2020-08-14 00:34:13 +02:00
|
|
|
super().on_stop()
|
2018-06-06 20:09:18 +02:00
|
|
|
self.logger.info('Received STOP event on HttpBackend')
|
2018-01-29 13:47:21 +01:00
|
|
|
|
2023-05-13 12:35:20 +02:00
|
|
|
start_time = time()
|
|
|
|
timeout = 5
|
|
|
|
workers = self._workers.copy()
|
|
|
|
|
|
|
|
for i, worker in enumerate(workers[::-1]):
|
|
|
|
if worker and worker.is_alive():
|
|
|
|
worker.terminate()
|
|
|
|
worker.join(timeout=max(0, start_time + timeout - time()))
|
|
|
|
|
|
|
|
if worker and worker.is_alive():
|
|
|
|
worker.kill()
|
|
|
|
self._workers.pop(i)
|
|
|
|
|
|
|
|
if self._server_proc:
|
|
|
|
self._server_proc.terminate()
|
|
|
|
self._server_proc.join(timeout=5)
|
|
|
|
self._server_proc = None
|
|
|
|
|
|
|
|
if self._server_proc and self._server_proc.is_alive():
|
|
|
|
self._server_proc.kill()
|
|
|
|
|
|
|
|
self._server_proc = None
|
|
|
|
self.logger.info('HTTP server terminated')
|
2021-02-23 23:07:35 +01:00
|
|
|
|
2023-01-01 13:16:46 +01:00
|
|
|
if self._service_registry_thread and self._service_registry_thread.is_alive():
|
|
|
|
self._service_registry_thread.join(timeout=5)
|
|
|
|
self._service_registry_thread = None
|
|
|
|
|
2018-01-29 13:47:21 +01:00
|
|
|
def notify_web_clients(self, event):
|
2022-04-27 14:52:41 +02:00
|
|
|
"""Notify all the connected web clients (over websocket) of a new event"""
|
2023-05-07 12:08:28 +02:00
|
|
|
get_redis().publish(events_redis_topic, str(event))
|
2018-01-29 13:47:21 +01:00
|
|
|
|
2023-05-06 22:04:48 +02:00
|
|
|
def _get_secret_key(self, _create=False):
|
|
|
|
if _create:
|
|
|
|
self.logger.info('Creating web server secret key')
|
|
|
|
pathlib.Path(self.secret_key_file).parent.mkdir(parents=True, exist_ok=True)
|
|
|
|
with open(self.secret_key_file, 'w') as f:
|
|
|
|
f.write(secrets.token_urlsafe(32))
|
|
|
|
|
|
|
|
os.chmod(self.secret_key_file, 0o600)
|
|
|
|
return secrets.token_urlsafe(32)
|
|
|
|
|
|
|
|
try:
|
|
|
|
with open(self.secret_key_file, 'r') as f:
|
|
|
|
return f.read()
|
|
|
|
except IOError as e:
|
|
|
|
if not _create:
|
|
|
|
return self._get_secret_key(_create=True)
|
|
|
|
|
|
|
|
raise e
|
|
|
|
|
2023-01-01 13:16:46 +01:00
|
|
|
def _register_service(self):
|
2021-10-24 02:51:05 +02:00
|
|
|
try:
|
|
|
|
self.register_service(port=self.port)
|
|
|
|
except Exception as e:
|
|
|
|
self.logger.warning('Could not register the Zeroconf service')
|
|
|
|
self.logger.exception(e)
|
2018-01-29 16:34:00 +01:00
|
|
|
|
2023-05-02 21:24:50 +02:00
|
|
|
def _start_zeroconf_service(self):
|
|
|
|
self._service_registry_thread = threading.Thread(
|
|
|
|
target=self._register_service,
|
|
|
|
name='ZeroconfService',
|
|
|
|
)
|
|
|
|
self._service_registry_thread.start()
|
|
|
|
|
2023-05-13 12:35:20 +02:00
|
|
|
async def _post_fork_main(self, sockets):
|
|
|
|
assert isinstance(
|
|
|
|
self.bus, RedisBus
|
|
|
|
), 'The HTTP backend only works if backed by a Redis bus'
|
|
|
|
|
|
|
|
application.config['redis_queue'] = self.bus.redis_queue
|
|
|
|
application.secret_key = self._get_secret_key()
|
|
|
|
container = WSGIContainer(application)
|
|
|
|
tornado_app = Application(
|
|
|
|
[
|
|
|
|
*[(route.path(), route) for route in get_ws_routes()],
|
|
|
|
(r'.*', FallbackHandler, {'fallback': container}),
|
|
|
|
]
|
|
|
|
)
|
|
|
|
|
|
|
|
server = HTTPServer(tornado_app)
|
|
|
|
server.add_sockets(sockets)
|
|
|
|
|
|
|
|
try:
|
|
|
|
await asyncio.Event().wait()
|
|
|
|
except (asyncio.CancelledError, KeyboardInterrupt):
|
|
|
|
return
|
|
|
|
|
|
|
|
def _web_server_proc(self):
|
|
|
|
self.logger.info(
|
|
|
|
'Starting local web server on port %s with %d service workers',
|
|
|
|
self.port,
|
|
|
|
self.num_workers,
|
|
|
|
)
|
|
|
|
|
|
|
|
sockets = bind_sockets(self.port, address=self.bind_address, reuse_port=True)
|
|
|
|
|
|
|
|
try:
|
|
|
|
fork_processes(self.num_workers)
|
|
|
|
future = self._post_fork_main(sockets)
|
|
|
|
asyncio.run(future)
|
|
|
|
except (asyncio.CancelledError, KeyboardInterrupt):
|
|
|
|
return
|
|
|
|
|
|
|
|
def _start_web_server(self):
|
|
|
|
self._server_proc = Process(target=self._web_server_proc)
|
|
|
|
self._server_proc.start()
|
|
|
|
self._server_proc.join()
|
2018-01-04 02:45:23 +01:00
|
|
|
|
2023-05-02 21:24:50 +02:00
|
|
|
def run(self):
|
|
|
|
super().run()
|
|
|
|
|
|
|
|
self._start_zeroconf_service()
|
2023-05-13 12:35:20 +02:00
|
|
|
self._start_web_server()
|
2023-01-01 13:16:46 +01:00
|
|
|
|
2018-01-04 02:45:23 +01:00
|
|
|
|
2019-01-07 15:34:31 +01:00
|
|
|
# vim:sw=4:ts=4:et:
|