Merge branch 'fsm_as_eventhandler'

Fix a Sphinx warning message

.drone.yml

@@ -10,4 +10,4 @@ pipeline:
       - docker push eu.gcr.io/avatao-challengestore/tutorial-framework:${DRONE_TAG}
     when:
       event: 'tag'
-      branch: refs/tags/egyptianmau-20*
+      branch: refs/tags/mainecoon-20*

.pylintrc

@@ -1,5 +1,5 @@
 [TYPECHECK]
 
 ignored-modules = zmq
-max-line-length = 150
+max-line-length = 120
-disable = missing-docstring, too-few-public-methods
+disable = missing-docstring, too-few-public-methods, invalid-name

Dockerfile

@@ -11,7 +11,8 @@ RUN curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
         libzmq5                                \
         nginx                                  \
         gettext-base                                                                                   &&\
-    rm -rf /var/lib/apt/lists/*
+    rm -rf /var/lib/apt/lists/*                                                                        &&\
+    ln -sf /bin/bash /bin/sh
 
 COPY requirements.txt /tmp
 RUN pip3 install -r /tmp/requirements.txt
@@ -26,7 +27,7 @@ ENV TFW_PUBLIC_PORT=8888          \
 
 EXPOSE ${TFW_PUBLIC_PORT}
 
-ENV PYTHONPATH="/usr/local/lib/"                                           \
+ENV PYTHONPATH="/usr/local/lib"                                            \
     TFW_SUPERVISOR_HTTP_URI="http://localhost:${TFW_SUPERVISOR_HTTP_PORT}" \
     TFW_SUPERVISORD_CONF="/etc/supervisor/supervisord.conf"                \
     TFW_SUPERVISORD_COMPONENTS="/etc/supervisor/conf"                      \
@@ -36,20 +37,23 @@ ENV PYTHONPATH="/usr/local/lib/"                                           \
     TFW_LIB_DIR="/usr/local/lib/"                                          \
     TFW_TERMINADO_DIR="/tmp/terminado_server"                              \
     TFW_FRONTEND_DIR="/srv/frontend"                                       \
+    TFW_SERVER_DIR="/srv/.tfw"                                             \
     TFW_HISTFILE="/home/${AVATAO_USER}/.bash_history"                      \
     PROMPT_COMMAND="history -a"
 
 COPY bashrc /tmp
-RUN echo "export HISTFILE=${TFW_HISTFILE}\n" >> /tmp/bashrc &&\
+RUN echo "export HISTFILE=${TFW_HISTFILE}" >> /tmp/bashrc &&\
     cat /tmp/bashrc >> /home/${AVATAO_USER}/.bashrc
 
 COPY supervisor/supervisord.conf ${TFW_SUPERVISORD_CONF}
+COPY supervisor/components/ ${TFW_SUPERVISORD_COMPONENTS}
 COPY nginx/nginx.conf ${TFW_NGINX_CONF}
 COPY nginx/default.conf ${TFW_NGINX_DEFAULT}
 COPY nginx/components/ ${TFW_NGINX_COMPONENTS}
 COPY lib LICENSE ${TFW_LIB_DIR}
+COPY supervisor/tfw_server.py ${TFW_SERVER_DIR}/
 
-RUN for dir in "${TFW_LIB_DIR}" "/etc/nginx" "/etc/supervisor"; do \
+RUN for dir in "${TFW_LIB_DIR}"/{tfw,tao,envvars} "/etc/nginx" "/etc/supervisor"; do \
         chown -R root:root "$dir" && chmod -R 700 "$dir";                            \
     done
 

README.md

@@ -3,11 +3,11 @@
 This is the beating heart of TFW – the Docker baseimage containing the internals of the framework.
 
 Every tutorial-framework based challenge has a `solvable` Docker image based on this one: their `Dockerfile`s begin with `FROM eu.gcr.io/avatao-challengestore/tutorial-framework`.
-Note that TFW is not avaliable on Docker Hub due to legal reasons and is only accessible through local builds (dont't worry, we've got you covered with build scripts in the `test-tutorial-framework` repo).
+Note that TFW is not avaliable on Docker Hub due to legal reasons and is only accessible through local builds (don't worry, we've got you covered with build scripts in the [test-tutorial-framework](https://github.com/avatao-content/test-tutorial-framework) repo).
 
 This document explains the general concepts of TFW and should be the first thing you read before getting started with development.
 
-For more on building and running you should consult the `test-tutorial-framework` repo.
+For more on building and running you should check the [test-tutorial-framework](https://github.com/avatao-content/test-tutorial-framework) repo.
 
 ## The framework
 
@@ -20,11 +20,25 @@ Frontend components use websockets to connect to the TFW server, to which you ca
 
 ![TFW architecture](docs/tfw_architecture.png)
 
+### Networking details
+
+Event handlers connect to the TFW server using ZMQ.
+They receive messages on their `SUB`(scribe) sockets, which are connected to the `PUB`(lish) socket of the server.
+Event handlers reply on their `PUSH` socket, then their messages are received on the `PULL` socket of the server.
+
+The TFW server is basically just a fancy proxy.
+It's behaviour is quite simple: it proxies every message received from the fontend to the event handlers and vice versa.
+
+The server is also capable of "mirroring" messages back to their source.
+This is useful for communication between event handlers or frontend components (event handler to event handler or frontend component to frontend component communication).
+
+Components can also broadcast messages (broadcasted messages are received both by event handlers and the frontend as well).
+
 ### Event handlers
 
-Imagine event handlers as callbacks that are invoked when TFW receives a specific type of message. For instance you could send a message to the framework when the user does something of note.
+Imagine event handlers as callbacks that are invoked when TFW receives a specific type of message. For instance, you could send a message to the framework when the user does something of note.
 
-This allows you to define actions triggered on the backend when the user presses a button on the frontend, moves the cursor to a specific area or anything like that.
+Event handler allow you to define actions triggered on the backend when the user presses a button on the frontend or moves the cursor to a specific area, etc.
 
 Event handlers use ZeroMQ to connect to the framework. Due to this they are as loosely-coupled as possible: usually they are running in separate processes and only communicate with TFW through ZMQ.
 
@@ -38,9 +52,9 @@ Inside Avatao this means that any of the content teams can use the framework wit
 Another unique feature of the framework is the FSM – finite state machine – representing the state of your challenge.
 This allows you to track users progressing with the tasks you've defined for them to complete.
 
-For instance you could represent whether the user managed to create a malicious user with a state called `user_registered` and subscribe callbacks to events regarding that state (like entering or leaving).
+For instance, you could represent whether the user managed to create a malicious user with a state called `user_registered` and subscribe callbacks to events regarding that state (like entering or leaving).
 
-You could create challenges that can be completed in several different ways: imagine a state called `challenge_complete`, which represents when the challenge is completed. Several series of actions (triggers) could lead to this state.
+You could create challenges that can be completed in several different ways: imagine a state called `challenge_complete`, which indicates if the challenge is completed. Several series of actions (triggers) could lead to this state.
 
 This enables you to guide your users through the experience you've envisioned with your tutorial.
 We can provide a whole new level of interactivity in our challenges because we know what the user is doing.
@@ -48,17 +62,17 @@ This includes context-dependent hints and the automatic typing of commands to a
 
 ### Frontend
 
-Note that our frontend implementation is written in Angular. It is maintained and documented in the `frontend-tutorial-framework` repository.
+Note that our frontend implementation is written in Angular. It is maintained and documented in the [frontend-tutorial-framework](https://github.com/avatao-content/frontend-tutorial-framework) repository.
 
 ### Messaging format
 
 The framework uses JSON messages internally and in exposed APIs as well.
-These messages must comply some rules.
+These messages must comply with some rules.
 Don't worry, we are not too fond of rules around these parts.
 
 The TFW message format:
 
-```json
+```text
 {
     "key: "some identifier used for addressing",
     "data":
@@ -75,9 +89,180 @@ The TFW message format:
 - The `data` object can contain anything you might want to send
 - The `trigger` key is an optional field that triggers an FSM action with that name from the current state (whatever that might be)
 
+To mirror messages back to their sources you can use a special messaging format, in which the message to be mirrored is enveloped inside the `data` field of the outer message:
+
+```text
+    "key": "mirror",
+    "data":
+    {
+        ...
+        The message you want to mirror (with it's own "key" and "data" fields)
+        ...
+    }
+```
+
+Broadcasting messages is possible in a similar manner by using `"key": "broadcast"` in the outer message.
 
 ## Where to go next
 
 Most of the components you need have docstrings included (hang on tight, this is work in progress) – refer to them for usage info.
 
-To get started you should take a look at the `test-tutorial-framework` repository, which serves as an example project as well.
+In the `docs` folder you can find our Sphinx-based documentation, which you can build using the `hack/tfw.sh` script in the [test-tutorial-framework](https://github.com/avatao-content/test-tutorial-framework) repository.
+
+To get started you should take a look at [test-tutorial-framework](https://github.com/avatao-content/test-tutorial-framework), which serves as an example project as well.
+
+## API
+
+APIs exposed by our pre-witten event handlers are documented here.
+
+### IdeEventHandler
+
+You can read the content of the currently selected file like so:
+```
+{ 
+    "key": "ide",
+    "data":
+    {
+        "command": "read"
+    }
+}
+```
+
+Use the following message to overwrite the content of the currently selected file:
+```
+{ 
+    "key": "ide",
+    "data":
+    {
+        "command": "write",
+        "content": ...string...
+    }
+}
+```
+
+To select a file use the following message:
+```
+{ 
+    "key": "ide",
+    "data":
+    {
+        "command": "select",
+        "filename": ...string...
+    }
+}
+```
+
+You can switch to a new working directory using this message (note that the directory must be in `allowed_directories`):
+```
+{ 
+    "key": "ide",
+    "data":
+    {
+        "command": "selectdir",
+        "directory": ...string...
+    }
+}
+```
+
+Overwriting the current list of excluded file patterns is possible with this message:
+```
+{ 
+    "key": "ide",
+    "data":
+    {
+        "command": "exclude",
+        "exclude": ...array of strings...
+    }
+}
+```
+
+### TerminalEventHandler
+
+Writing to the terminal:
+```
+{ 
+    "key": "shell",
+    "data":
+    {
+        "command": "write",
+        "value": ...string...
+    }
+}
+```
+
+You can read terminal command history like so:
+```
+{ 
+    "key": "shell",
+    "data":
+    {
+        "command": "read",
+        "count": ...number...
+    }
+}
+```
+
+### ProcessManagingEventHandler
+
+Starting, stopping and restarting supervisor processes can be done using similar messages (where `command` is `start`, `stop` or `restart`):
+```
+{ 
+    "key": "processmanager",
+    "data":
+    {
+        "command": ...string...,
+        "process_name": ...string...
+    }
+}
+```
+
+### LogMonitoringEventHandler
+
+To change which supervisor process is monitored use this message:
+```
+{ 
+    "key": "logmonitor",
+    "data" :
+    {
+        "command": "process_name",
+        "value": ...string...
+    }
+}
+```
+
+To set the tail length of logs (the monitor will send back the last `value` characters of the log):
+```
+{ 
+    "key": "logmonitor",
+    "data" :
+    {
+        "command": "log_tail",
+        "value": ...number...
+    }
+}
+```
+
+### FSMManagingEventHandler
+
+To attempt executing a trigger on the FSM use:
+```
+{
+    "key": "fsm",
+    "data" :
+    {
+        "command": "trigger",
+        "value": ...string...
+    }
+}
+```
+
+To force the broadcasting of an FSM update you can use this message:
+```
+{
+    "key": "fsm",
+    "data" :
+    {
+        "command": "update"
+    }
+}
+```

VERSION

@@ -1 +1 @@
-egyptianmau
+mainecoon

bashrc

@@ -9,7 +9,7 @@ _precmd()
 {
     [ -z "$AT_PROMPT" ] && return
     unset AT_PROMPT
-    history -a
+    [ -z "$TFW_DELAY_HISTAPPEND" ] && history -a
 }
 trap _precmd DEBUG
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = baseimage-tutorial-framework
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+set SPHINXPROJ=baseimage-tutorial-framework
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/source/components/components.rst

@@ -0,0 +1,25 @@
+Components
+----------
+
+.. automodule:: tfw.components
+
+.. autoclass:: IdeEventHandler
+    :members:
+
+.. autoclass:: TerminalEventHandler
+    :members:
+
+.. autoclass:: ProcessManagingEventHandler
+    :members:
+
+.. autoclass:: LogMonitoringEventHandler
+    :members:
+
+.. autoclass:: TerminalCommands
+    :members:
+
+.. autoclass:: HistoryMonitor
+    :members:
+
+.. autoclass:: BashMonitor
+    :members:

docs/source/conf.py

@@ -0,0 +1,166 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../lib'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'baseimage-tutorial-framework'
+copyright = '2018, Avatao Innovative Learning Kft'
+author = 'Kristóf Tóth'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = 'mainecoon'
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'baseimage-tutorial-frameworkdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'baseimage-tutorial-framework.tex', 'baseimage-tutorial-framework Documentation',
+     'Kristóf Tóth', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'baseimage-tutorial-framework', 'baseimage-tutorial-framework Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'baseimage-tutorial-framework', 'baseimage-tutorial-framework Documentation',
+     author, 'baseimage-tutorial-framework', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Extension configuration -------------------------------------------------
+def skip(app, what, name, obj, skip, options):
+    if name == "__init__":
+        return False
+    return skip
+
+def setup(app):
+    app.connect("autodoc-skip-member", skip)

docs/source/foundations/eventhandlers.rst

@@ -0,0 +1,12 @@
+Event handler base classes
+--------------------------
+
+Subclass these to create your cusom event handlers.
+
+.. automodule:: tfw
+
+.. autoclass:: EventHandlerBase
+    :members:
+
+.. autoclass:: TriggeredEventHandler
+    :members:

docs/source/foundations/fsms.rst

@@ -0,0 +1,12 @@
+FSM base classes
+----------------
+
+Subclass these to create an FSM that fits your tutorial/challenge.
+
+.. automodule:: tfw
+
+.. autoclass:: FSMBase
+    :members:
+
+.. autoclass:: LinearFSM
+    :members:

docs/source/foundations/tfwserver.rst

@@ -0,0 +1,7 @@
+TFWServer
+---------
+
+.. automodule:: tfw.networking
+
+.. autoclass:: TFWServer
+    :members:

docs/source/index.rst

@@ -0,0 +1,45 @@
+.. baseimage-tutorial-framework documentation master file, created by
+   sphinx-quickstart on Fri Jun  1 14:29:07 2018.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to baseimage-tutorial-framework's documentation!
+========================================================
+
+Foundations
+-----------
+
+This part covers the soil which the framework is based on and stuff you will need to develop your own challenges.
+
+.. toctree::
+    :glob:
+
+    foundations/*
+
+Networking
+----------
+
+You can use these to send messages to the frontend or the event handlers through TFWServer.
+
+.. toctree::
+    :glob:
+
+    networking/*
+
+Components
+----------
+
+These are pre-written components for you to use, such as our IDE, terminal or console.
+
+.. toctree::
+    :glob:
+
+    components/*
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/networking/networking.rst

@@ -0,0 +1,17 @@
+Networking
+----------
+
+.. automodule:: tfw.networking
+
+.. autoclass:: TFWServerConnector
+    :members:
+
+.. automodule:: tfw.networking.event_handlers
+
+.. autoclass:: ServerUplinkConnector
+    :members:
+
+.. automodule:: tfw.networking
+
+.. autoclass:: MessageSender
+    :members:

lib/envvars.py

@@ -1,12 +0,0 @@
-# Copyright (C) 2018 Avatao.com Innovative Learning Kft.
-# All Rights Reserved. See LICENSE file for details.
-
-from collections import namedtuple
-from os import environ
-
-
-def prefixed_envvars_to_namedtuple(prefix: str, tuple_name: str):
-    envvars = {envvar.replace(prefix, '', 1): environ.get(envvar)
-               for envvar in environ.keys()
-               if envvar.startswith(prefix)}
-    return namedtuple(tuple_name, envvars)(**envvars)

lib/envvars/__init__.py

@@ -0,0 +1,25 @@
+# Copyright (C) 2018 Avatao.com Innovative Learning Kft.
+# All Rights Reserved. See LICENSE file for details.
+
+from collections import namedtuple
+from os import environ
+
+from tfw.decorators import lazy_property
+
+
+class LazyEnvironment:
+    def __init__(self, prefix, tuple_name):
+        self._prefix = prefix
+        self._tuple_name = tuple_name
+
+    @lazy_property
+    def environment(self):
+        return self.prefixed_envvars_to_namedtuple()
+
+    def prefixed_envvars_to_namedtuple(self):
+        envvars = {
+            envvar.replace(self._prefix, '', 1): environ.get(envvar)
+            for envvar in environ.keys()
+            if envvar.startswith(self._prefix)
+        }
+        return namedtuple(self._tuple_name, envvars)(**envvars)

lib/tao/config/envvars.py

@@ -1,6 +1,6 @@
 # Copyright (C) 2018 Avatao.com Innovative Learning Kft.
 # All Rights Reserved. See LICENSE file for details.
 
-from envvars import prefixed_envvars_to_namedtuple
+from envvars import LazyEnvironment
 
-TAOENV = prefixed_envvars_to_namedtuple('AVATAO_', 'taoenvtuple')
+TAOENV = LazyEnvironment('AVATAO_', 'taoenvtuple').environment

lib/tfw/__init__.py

@@ -1,6 +1,7 @@
 # Copyright (C) 2018 Avatao.com Innovative Learning Kft.
 # All Rights Reserved. See LICENSE file for details.
 
-from .event_handler_base import EventHandlerBase, TriggeredEventHandler
+from .event_handler_base import EventHandlerBase, TriggeredEventHandler, BroadcastingEventHandler
 from .fsm_base import FSMBase
 from .linear_fsm import LinearFSM
+from .yaml_fsm import YamlFSM

lib/tfw/components/__init__.py

@@ -3,7 +3,9 @@
 
 from .directory_monitoring_event_handler import DirectoryMonitoringEventHandler
 from .process_managing_event_handler import ProcessManagingEventHandler
-from .terminado_event_handler import TerminadoEventHandler
+from .terminal_event_handler import TerminalEventHandler
-from .webide_event_handler import WebideEventHandler
+from .ide_event_handler import IdeEventHandler
 from .history_monitor import HistoryMonitor, BashMonitor, GDBMonitor
 from .terminal_commands import TerminalCommands
+from .log_monitoring_event_handler import LogMonitoringEventHandler
+from .fsm_managing_event_handler import FSMManagingEventHandler

lib/tfw/components/directory_monitor.py

@@ -15,10 +15,11 @@ LOG = logging.getLogger(__name__)
 
 
 class DirectoryMonitor(ObserverMixin):
-    def __init__(self, directory):
+    def __init__(self, ide_key, directories):
-        ObserverMixin.__init__(self)
+        self.eventhandler = IdeReloadWatchdogEventHandler(ide_key)
-        self.eventhandler = WebideReloadWatchdogEventHandler()
+        for directory in directories:
             self.observer.schedule(self.eventhandler, directory, recursive=True)
+
         self.pause, self.resume = self.eventhandler.pause, self.eventhandler.resume
 
     @property
@@ -42,9 +43,10 @@ class DirectoryMonitor(ObserverMixin):
             self.directorymonitor.resume()
 
 
-class WebideReloadWatchdogEventHandler(FileSystemWatchdogEventHandler):
+class IdeReloadWatchdogEventHandler(FileSystemWatchdogEventHandler):
-    def __init__(self):
+    def __init__(self, ide_key):
         super().__init__()
+        self.ide_key = ide_key
         self.uplink = ServerUplinkConnector()
         self._paused = False
         self.ignore = 0
@@ -63,8 +65,10 @@ class WebideReloadWatchdogEventHandler(FileSystemWatchdogEventHandler):
             self.ignore = self.ignore - 1
             return
         LOG.debug(event)
-        self.uplink.send({'key': 'webide',
+        self.uplink.send({
-                          'data': {'command': 'reload'}})
+            'key': self.ide_key,
+            'data': {'command': 'reload'}
+        })
 
 
 def with_monitor_paused(fun):

lib/tfw/components/directory_monitoring_event_handler.py

@@ -15,12 +15,19 @@ class DirectoryMonitoringEventHandler(EventHandlerBase, MonitorManagerMixin):
     def __init__(self, key, directory):
         super().__init__(key)
         self._directory = directory
-        MonitorManagerMixin.__init__(self, DirectoryMonitor, self._directory)
+        MonitorManagerMixin.__init__(
+            self,
+            DirectoryMonitor,
+            key,
+            self._directory
+        )
 
-        self.commands = {'pause':     self.pause,
+        self.commands = {
+            'pause':     self.pause,
             'resume':    self.resume,
             'ignore':    self.ignore,
-                         'selectdir': self.selectdir}
+            'selectdir': self.selectdir
+        }
 
     @property
     def directory(self):

lib/tfw/components/fsm_managing_event_handler.py

@@ -0,0 +1,56 @@
+# Copyright (C) 2018 Avatao.com Innovative Learning Kft.
+# All Rights Reserved. See LICENSE file for details.
+
+from tfw import BroadcastingEventHandler
+from tfw.config.logs import logging
+
+LOG = logging.getLogger(__name__)
+
+
+class FSMManagingEventHandler(BroadcastingEventHandler):
+    def __init__(self, key, fsm_type):
+        super().__init__(key)
+        self.fsm = fsm_type()
+        self._fsm_updater = FSMUpdater(self.fsm)
+
+        self.command_handlers = {
+            'trigger': self.handle_trigger,
+            'update':  self.handle_update
+        }
+
+    def handle_event(self, message):
+        try:
+            data = message['data']
+            message['data'] = self.command_handlers[data['command']](data)
+            return message
+        except KeyError:
+            LOG.error('IGNORING MESSAGE: Invalid message received: %s', message)
+
+    def handle_trigger(self, data):
+        self.fsm.step(data['value'])
+        return self.with_fsm_update(data)
+
+    def with_fsm_update(self, data):
+        return {
+            **data,
+            **self._fsm_updater.get_fsm_state_and_transitions()
+        }
+
+    def handle_update(self, data):
+        return self.with_fsm_update(data)
+
+
+class FSMUpdater:
+    def __init__(self, fsm):
+        self.fsm = fsm
+
+    def get_fsm_state_and_transitions(self):
+        state = self.fsm.state
+        valid_transitions = [
+            {'trigger': trigger}
+            for trigger in self.fsm.get_triggers(self.fsm.state)
+        ]
+        return {
+            'current_state': state,
+            'valid_transitions': valid_transitions
+        }

lib/tfw/components/history_monitor.py

@@ -36,15 +36,17 @@ class HistoryMonitor(CallbackMixin, ObserverMixin, ABC):
     See examples below.
     """
     def __init__(self, histfile):
-        CallbackMixin.__init__(self)
-        ObserverMixin.__init__(self)
         self.histfile = histfile
         self._history = []
         self._last_length = len(self._history)
-        self.observer.schedule(CallbackEventHandler([self.histfile],
+        self.observer.schedule(
+            CallbackEventHandler(
+                [self.histfile],
                 self._fetch_history,
-                                                    self._invoke_callbacks),
+                self._invoke_callbacks
-                               dirname(self.histfile))
+            ),
+            dirname(self.histfile)
+        )
 
     @property
     def history(self):
@@ -55,7 +57,10 @@ class HistoryMonitor(CallbackMixin, ObserverMixin, ABC):
         with open(self.histfile, 'r') as ifile:
             pattern = compileregex(self.command_pattern)
             data = ifile.read()
-            self._history = [self.sanitize_command(command) for command in findall(pattern, data)]
+            self._history = [
+                self.sanitize_command(command)
+                for command in findall(pattern, data)
+            ]
 
     @property
     @abstractmethod

lib/tfw/components/ide_event_handler.py

@@ -40,9 +40,9 @@ class FileManager:  # pylint: disable=too-many-instance-attributes
     @workdir.setter
     def workdir(self, directory):
         if not exists(directory) or not isdir(directory):
-            raise EnvironmentError('"{}" is not a directory!'.format(directory))
+            raise EnvironmentError(f'"{directory}" is not a directory!')
-        if not self._is_in_whitelisted_dir(directory):
+        if not self._is_in_allowed_dir(directory):
-            raise EnvironmentError('Directory "{}" is not in whitelist!'.format(directory))
+            raise EnvironmentError(f'Directory "{directory}" is not allowed!')
         self._workdir = directory
 
     @property
@@ -65,8 +65,13 @@ class FileManager:  # pylint: disable=too-many-instance-attributes
 
     @property
     def files(self):
-        return [self._relpath(file) for file in glob(join(self._workdir, '**/*'), recursive=True)
+        return [
-                if isfile(file) and self._is_in_whitelisted_dir(file) and not self._is_blacklisted(file)]
+            self._relpath(file)
+            for file in glob(join(self._workdir, '**/*'), recursive=True)
+            if isfile(file)
+            and self._is_in_allowed_dir(file)
+            and not self._is_blacklisted(file)
+        ]
 
     @property
     def file_contents(self):
@@ -78,11 +83,17 @@ class FileManager:  # pylint: disable=too-many-instance-attributes
         with open(self._filepath(self.filename), 'w', errors='surrogateescape') as ofile:
             ofile.write(value)
 
-    def _is_in_whitelisted_dir(self, path):
+    def _is_in_allowed_dir(self, path):
-        return any(realpath(path).startswith(allowed_dir) for allowed_dir in self.allowed_directories)
+        return any(
+            realpath(path).startswith(allowed_dir)
+            for allowed_dir in self.allowed_directories
+        )
 
     def _is_blacklisted(self, file):
-        return any(fnmatchcase(file, blacklisted) for blacklisted in self.exclude)
+        return any(
+            fnmatchcase(file, blacklisted)
+            for blacklisted in self.exclude
+        )
 
     def _filepath(self, filename):
         return join(self._workdir, filename)
@@ -91,41 +102,62 @@ class FileManager:  # pylint: disable=too-many-instance-attributes
         return relpath(self._filepath(filename), start=self._workdir)
 
 
-class WebideEventHandler(EventHandlerBase, MonitorManagerMixin):
+class IdeEventHandler(EventHandlerBase, MonitorManagerMixin):
     # pylint: disable=too-many-arguments
     """
     Event handler implementing the backend of our browser based IDE.
     By default all files in the directory specified in __init__ are displayed
     on the fontend. Note that this is a stateful component.
 
-    This EventHandler accepts messages that have a data["command"] key specifying
+    When any file in the selected directory changes they are automatically refreshed
+    on the frontend (this is done by listening to inotify events).
+
+    This EventHandler accepts messages that have a data['command'] key specifying
     a command to be executed.
-    The API of each command is documented in their respective handlers.
+
+    The API of each command is documented in their respective handler.
     """
     def __init__(self, key, directory, allowed_directories, selected_file=None, exclude=None):
         """
         :param key: the key this instance should listen to
         :param directory: working directory which the EventHandler should serve files from
-        :param allowed_directories: list of directories that can be switched to using the selectdir command
+        :param allowed_directories: list of directories that can be switched to using selectdir
         :param selected_file: file that is selected by default
-        :param exclude: list of filenames that should not appear between files (for *.o, *.pyc, etc.)
+        :param exclude: list of filenames that should not appear between files (for .o, .pyc, etc.)
         """
         super().__init__(key)
-        self.filemanager = FileManager(allowed_directories=allowed_directories, working_directory=directory,
+        try:
-                                       selected_file=selected_file, exclude=exclude)
+            self.filemanager = FileManager(
-        MonitorManagerMixin.__init__(self, DirectoryMonitor, self.filemanager.workdir)
+                allowed_directories=allowed_directories,
+                working_directory=directory,
+                selected_file=selected_file,
+                exclude=exclude
+            )
+        except IndexError:
+            raise EnvironmentError(
+                f'No file(s) in IdeEventHandler working_directory "{directory}"!'
+            )
 
-        self.commands = {'read':      self.read,
+        MonitorManagerMixin.__init__(
+            self,
+            DirectoryMonitor,
+            self.key,
+            self.filemanager.allowed_directories
+        )
+
+        self.commands = {
+            'read':      self.read,
             'write':     self.write,
             'select':    self.select,
             'selectdir': self.select_dir,
-                         'exclude':   self.exclude}
+            'exclude':   self.exclude
+        }
 
     def read(self, data):
         """
         Read the currently selected file.
 
-        :return: message with the contents of the file in data['content']
+        :return dict: message with the contents of the file in data['content']
         """
         try:
             data['content'] = self.filemanager.file_contents
@@ -141,7 +173,9 @@ class WebideEventHandler(EventHandlerBase, MonitorManagerMixin):
         """
         Overwrites a file with the desired string.
 
-        :param data['content']: string containing the desired file contents
+        :param data: TFW message data containing key 'content'
+                     (new file content)
+
         """
         self.monitor.ignore = self.monitor.ignore + 1
         try:
@@ -155,7 +189,8 @@ class WebideEventHandler(EventHandlerBase, MonitorManagerMixin):
         """
         Selects a file from the current directory.
 
-        :param data['filename']: name of file to select relative to the current directory
+        :param data: TFW message data containing 'filename'
+                     (name of file to select relative to the current directory)
         """
         try:
             self.filemanager.filename = data['filename']
@@ -167,9 +202,10 @@ class WebideEventHandler(EventHandlerBase, MonitorManagerMixin):
         """
         Select a new working directory to display files from.
 
-        :param data['directory']: absolute path of diretory to select.
+        :param data: TFW message data containing 'directory'
+                     (absolute path of diretory to select.
                      must be a path whitelisted in
-                                  self.allowed_directories
+                     self.allowed_directories)
         """
         try:
             self.filemanager.workdir = data['directory']
@@ -187,7 +223,9 @@ class WebideEventHandler(EventHandlerBase, MonitorManagerMixin):
         """
         Overwrite list of excluded files
 
-        :param data['exclude']: list of filename patterns to be excluded, e.g.: ["*.pyc", "*.o"]
+        :param data: TFW message data containing 'exclude'
+                     (list of unix-style filename patterns to be excluded,
+                     e.g.: ["\*.pyc", "\*.o")
         """
         try:
             self.filemanager.exclude = list(data['exclude'])

lib/tfw/components/log_monitor.py

@@ -0,0 +1,56 @@
+# Copyright (C) 2018 Avatao.com Innovative Learning Kft.
+# All Rights Reserved. See LICENSE file for details.
+
+import logging
+from os.path import dirname
+
+from watchdog.events import PatternMatchingEventHandler as PatternMatchingWatchdogEventHandler
+
+from tfw.networking.event_handlers import ServerUplinkConnector
+from tfw.decorators import RateLimiter
+from tfw.mixins import ObserverMixin, SupervisorLogMixin
+
+
+class LogMonitor(ObserverMixin):
+    def __init__(self, process_name, log_tail=0):
+        self.prevent_log_recursion()
+        event_handler = SendLogWatchdogEventHandler(
+            process_name,
+            log_tail=log_tail
+        )
+        self.observer.schedule(
+            event_handler,
+            event_handler.path
+        )
+
+    @staticmethod
+    def prevent_log_recursion():
+        # This is done to prevent inotify event logs triggering themselves (infinite log recursion)
+        logging.getLogger('watchdog.observers.inotify_buffer').propagate = False
+
+
+class SendLogWatchdogEventHandler(PatternMatchingWatchdogEventHandler, SupervisorLogMixin):
+    def __init__(self, process_name, log_tail=0):
+        self.process_name = process_name
+        self.procinfo = self.supervisor.getProcessInfo(self.process_name)
+        super().__init__([
+            self.procinfo['stdout_logfile'],
+            self.procinfo['stderr_logfile']
+        ])
+        self.uplink = ServerUplinkConnector()
+        self.log_tail = log_tail
+
+    @property
+    def path(self):
+        return dirname(self.procinfo['stdout_logfile'])
+
+    @RateLimiter(rate_per_second=5)
+    def on_modified(self, event):
+        self.uplink.send({
+            'key': 'processlog',
+            'data': {
+                'command': 'new_log',
+                'stdout': self.read_stdout(self.process_name, tail=self.log_tail),
+                'stderr': self.read_stderr(self.process_name, tail=self.log_tail)
+            }
+        })

lib/tfw/components/log_monitoring_event_handler.py

@@ -0,0 +1,67 @@
+# Copyright (C) 2018 Avatao.com Innovative Learning Kft.
+# All Rights Reserved. See LICENSE file for details.
+
+from tfw import EventHandlerBase
+from tfw.mixins import MonitorManagerMixin
+from tfw.config.logs import logging
+from .log_monitor import LogMonitor
+
+LOG = logging.getLogger(__name__)
+
+
+class LogMonitoringEventHandler(EventHandlerBase, MonitorManagerMixin):
+    """
+    Monitors the output of a supervisor process (stdout, stderr) and
+    sends the results to the frontend.
+
+    Accepts messages that have a data['command'] key specifying
+    a command to be executed.
+
+    The API of each command is documented in their respective handler.
+    """
+    def __init__(self, key, process_name, log_tail=0):
+        super().__init__(key)
+        self.process_name = process_name
+        self.log_tail = log_tail
+        MonitorManagerMixin.__init__(
+            self,
+            LogMonitor,
+            self.process_name,
+            self.log_tail
+        )
+
+        self.command_handlers = {
+            'process_name': self.handle_process_name,
+            'log_tail':     self.handle_log_tail
+        }
+
+    def handle_event(self, message):
+        try:
+            data = message['data']
+            self.command_handlers[data['command']](data)
+            self.reload_monitor()
+        except KeyError:
+            LOG.error('IGNORING MESSAGE: Invalid message received: %s', message)
+
+    def handle_process_name(self, data):
+        """
+        Changes the monitored process.
+
+        :param data: TFW message data containing 'value'
+                     (name of the process to monitor)
+        """
+        self.set_monitor_args(data['value'], self.log_tail)
+
+    def handle_log_tail(self, data):
+        """
+        Sets tail length of the log the monitor will send
+        to the frontend (the monitor will send back the last
+        'value' characters of the log).
+
+        :param data: TFW message data containing 'value'
+                     (new tail length)
+        """
+        self.set_monitor_args(self.process_name, data['value'])
+
+    def cleanup(self):
+        self.monitor.stop()

lib/tfw/components/process_managing_event_handler.py

@@ -4,19 +4,20 @@
 from xmlrpc.client import Fault as SupervisorFault
 
 from tfw import EventHandlerBase
-from tfw.mixins import SupervisorMixin
+from tfw.mixins import SupervisorMixin, SupervisorLogMixin
 from tfw.config.logs import logging
 from .directory_monitor import with_monitor_paused
 
 LOG = logging.getLogger(__name__)
 
 
-class ProcessManager(SupervisorMixin):
+class ProcessManager(SupervisorMixin, SupervisorLogMixin):
     def __init__(self):
-        self.commands = {'start': self.start_process,
+        self.commands = {
+            'start':   self.start_process,
             'stop':    self.stop_process,
-                         'restart': self.restart_process,
+            'restart': self.restart_process
-                         'readlog': self.read_log}
+        }
 
     def __call__(self, command, process_name):
         return self.commands[command](process_name)
@@ -26,30 +27,39 @@ class ProcessManagingEventHandler(EventHandlerBase):
     """
     Event handler that can manage processes managed by supervisor.
 
-    This EventHandler accepts messages that have a data["command"] key specifying
+    This EventHandler accepts messages that have a data['command'] key specifying
     a command to be executed.
-    Every message must contain a data["process_name"] field with the name of the
+    Every message must contain a data['process_name'] field with the name of the
     process to manage. This is the name specified in supervisor config files like so:
     [program:someprogram]
 
     Commands available: start, stop, restart, readlog
     (the names are as self-documenting as it gets)
     """
-    def __init__(self, key, dirmonitor=None):
+    def __init__(self, key, dirmonitor=None, log_tail=0):
         super().__init__(key)
         self.key = key
         self.monitor = dirmonitor
         self.processmanager = ProcessManager()
+        self.log_tail = log_tail
 
     @with_monitor_paused
     def handle_event(self, message):
         try:
             data = message['data']
+            try:
                 self.processmanager(data['command'], data['process_name'])
+            except SupervisorFault as fault:
+                message['data']['error'] = fault.faultString
+            finally:
+                message['data']['stdout'] = self.processmanager.read_stdout(
+                    data['process_name'],
+                    self.log_tail
+                )
+                message['data']['stderr'] = self.processmanager.read_stderr(
+                    data['process_name'],
+                    self.log_tail
+                )
             return message
         except KeyError:
             LOG.error('IGNORING MESSAGE: Invalid message received: %s', message)
-        except SupervisorFault as fault:
-            message['data']['error'] = fault.faultString
-            message['data']['log'] = self.processmanager.read_log(message['data']['process_name'])
-            return message

lib/tfw/components/terminado_mini_server.py

@@ -14,15 +14,15 @@ LOG = logging.getLogger(__name__)
 class TerminadoMiniServer:
     def __init__(self, url, port, workdir, shellcmd):
         self.port = port
-        self._term_manager = SingleTermManager(shell_command=shellcmd,
+        self._term_manager = SingleTermManager(
-                                               term_settings={'cwd': workdir})
+            shell_command=shellcmd,
-        self.application = Application(
+            term_settings={'cwd': workdir}
-            [(
+        )
+        self.application = Application([(
             url,
             TerminadoMiniServer.ResetterTermSocket,
             {'term_manager': self._term_manager}
-            )]
+        )])
-        )
 
     @property
     def term_manager(self):
@@ -46,5 +46,10 @@ class TerminadoMiniServer:
 
 if __name__ == '__main__':
     LOG.info('Terminado Mini Server listening on %s', TFWENV.TERMINADO_PORT)
-    TerminadoMiniServer('/terminal', TFWENV.TERMINADO_PORT, TFWENV.TERMINADO_WD, ['bash']).listen()
+    TerminadoMiniServer(
+        '/terminal',
+        TFWENV.TERMINADO_PORT,
+        TFWENV.TERMINADO_WD,
+        ['bash']
+    ).listen()
     IOLoop.instance().start()

lib/tfw/components/terminal_commands.py

@@ -3,6 +3,7 @@
 
 from abc import ABC
 from re import match
+from shlex import split
 
 from tfw.config.logs import logging
 
@@ -18,13 +19,13 @@ class TerminalCommands(ABC):
     To receive events you need to subscribe TerminalCommand.callback to a HistoryMonitor
     instance.
 
-    Inherit from this class and define methods which start with "command_". When the user
+    Inherit from this class and define methods which start with "command\_". When the user
     executes the command specified after the underscore, your method will be invoked. All
-    such commands must expect the parameter *args which will contain the arguments of the
+    such commands must expect the parameter \*args which will contain the arguments of the
     command.
 
     For example to define a method that runs when someone starts vim in the terminal
-    you have to define a method like: "def command_vim(self, *args)"
+    you have to define a method like: "def command_vim(self, \*args)"
 
     You can also use this class to create new commands similarly.
     """
@@ -35,8 +36,12 @@ class TerminalCommands(ABC):
             self._setup_bashrc_aliases(bashrc)
 
     def _build_command_to_implementation_dict(self):
-        return {self._parse_command_name(fun): getattr(self, fun) for fun in dir(self)
+        return {
-                if callable(getattr(self, fun)) and self._is_command_implementation(fun)}
+            self._parse_command_name(fun): getattr(self, fun)
+            for fun in dir(self)
+            if callable(getattr(self, fun))
+            and self._is_command_implementation(fun)
+        }
 
     def _setup_bashrc_aliases(self, bashrc):
         with open(bashrc, 'a') as ofile:
@@ -57,10 +62,10 @@ class TerminalCommands(ABC):
         return match(self._command_method_regex, string)
 
     def callback(self, history):
-        parts = history[-1].split()
+        parts = split(history[-1])
         command = parts[0]
         if command in self.command_implemetations.keys():
             try:
                 self.command_implemetations[command](*parts[1:])
-            except IndexError:
+            except Exception: # pylint: disable=broad-except
-                LOG.debug('Command "%s" failed!', command)
+                LOG.exception('Command "%s" failed:', command)

lib/tfw/components/terminal_event_handler.py

@@ -10,15 +10,15 @@ from .terminado_mini_server import TerminadoMiniServer
 LOG = logging.getLogger(__name__)
 
 
-class TerminadoEventHandler(EventHandlerBase):
+class TerminalEventHandler(EventHandlerBase):
     """
     Event handler responsible for managing terminal sessions for frontend xterm
     sessions to connect to. You need to instanciate this in order for frontend
     terminals to work.
 
-    This EventHandler accepts messages that have a data["command"] key specifying
+    This EventHandler accepts messages that have a data['command'] key specifying
     a command to be executed.
-    The API of each command is documented in their respective handlers.
+    The API of each command is documented in their respective handler.
     """
     def __init__(self, key, monitor):
         """
@@ -29,9 +29,19 @@ class TerminadoEventHandler(EventHandlerBase):
         self.working_directory = TFWENV.TERMINADO_DIR
         self._historymonitor = monitor
         bash_as_user_cmd = ['sudo', '-u', TAOENV.USER, 'bash']
-        self.terminado_server = TerminadoMiniServer('/terminal', TFWENV.TERMINADO_PORT, TFWENV.TERMINADO_WD, bash_as_user_cmd)
+
-        self.commands = {'write': self.write,
+        self.terminado_server = TerminadoMiniServer(
-                         'read': self.read}
+            '/terminal',
+            TFWENV.TERMINADO_PORT,
+            TFWENV.TERMINADO_WD,
+            bash_as_user_cmd
+        )
+
+        self.commands = {
+            'write': self.write,
+            'read': self.read
+        }
+
         if self._historymonitor:
             self._historymonitor.watch()
         self.terminado_server.listen()
@@ -54,16 +64,18 @@ class TerminadoEventHandler(EventHandlerBase):
         Writes a string to the terminal session (on the pty level).
         Useful for pre-typing and executing commands for the user.
 
-        :param data['shellcmd']: command to be written to the pty
+        :param data: TFW message data containing 'value'
+                     (command to be written to the pty)
         """
-        self.terminado_server.pty.write(data['shellcmd'])
+        self.terminado_server.pty.write(data['value'])
 
     def read(self, data):
         """
         Reads the history of commands executed.
 
-        :param data['count']: the number of history elements to return
+        :param data: TFW message data containing 'count'
-        :return: message with list of commands in data['history']
+                     (the number of history elements to return)
+        :return dict: message with list of commands in data['history']
         """
         data['count'] = int(data.get('count', 1))
         if self.historymonitor:

lib/tfw/config/envvars.py

@@ -1,6 +1,6 @@
 # Copyright (C) 2018 Avatao.com Innovative Learning Kft.
 # All Rights Reserved. See LICENSE file for details.
 
-from envvars import prefixed_envvars_to_namedtuple
+from envvars import LazyEnvironment
 
-TFWENV = prefixed_envvars_to_namedtuple('TFW_', 'tfwenvtuple')
+TFWENV = LazyEnvironment('TFW_', 'tfwenvtuple').environment

lib/tfw/decorators/__init__.py

@@ -2,3 +2,4 @@
 # All Rights Reserved. See LICENSE file for details.
 
 from .rate_limiter import RateLimiter
+from .lazy_property import lazy_property

lib/tfw/decorators/lazy_property.py

@@ -0,0 +1,21 @@
+# Copyright (C) 2018 Avatao.com Innovative Learning Kft.
+# All Rights Reserved. See LICENSE file for details.
+
+from functools import update_wrapper
+
+
+class lazy_property:
+    """
+    Decorator that replaces a function with the value
+    it calculates on the first call.
+    """
+    def __init__(self, func):
+        self.func = func
+        update_wrapper(self, func)
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self  # avoids potential __new__ TypeError
+        value = self.func(instance)
+        setattr(instance, self.func.__name__, value)
+        return value

lib/tfw/event_handler_base.py

@@ -2,9 +2,13 @@
 # All Rights Reserved. See LICENSE file for details.
 
 from abc import ABC, abstractmethod
+from json import dumps
+from hashlib import md5
 
-from tfw.networking import deserialize_tfw_msg
 from tfw.networking.event_handlers import ServerConnector
+from tfw.config.logs import logging
+
+LOG = logging.getLogger(__name__)
 
 
 class EventHandlerBase(ABC):
@@ -20,22 +24,23 @@ class EventHandlerBase(ABC):
         self.subscribe(self.key, 'reset')
         self.server_connector.register_callback(self.event_handler_callback)
 
-    def event_handler_callback(self, msg_parts):
+    def event_handler_callback(self, message):
         """
         Callback that is invoked when receiving a message.
         Dispatches messages to handler methods and sends
         a response back in case the handler returned something.
         This is subscribed in __init__().
         """
-        message = deserialize_tfw_msg(*msg_parts)
         response = self.dispatch_handling(message)
         if response:
-            response['key'] = message['key']
             self.server_connector.send(response)
 
     def dispatch_handling(self, message):
         """
         Used to dispatch messages to their specific handlers.
+
+        :param message: the message received
+        :returns: the message to send back
         """
         if message['key'] != 'reset':
             return self.handle_event(message)
@@ -47,6 +52,7 @@ class EventHandlerBase(ABC):
         Abstract method that implements the handling of messages.
 
         :param message: the message received
+        :returns: the message to send back
         """
         raise NotImplementedError
 
@@ -56,6 +62,7 @@ class EventHandlerBase(ABC):
         Usually 'reset' events receive some sort of special treatment.
 
         :param message: the message received
+        :returns: the message to send back
         """
         return None
 
@@ -102,3 +109,38 @@ class TriggeredEventHandler(EventHandlerBase, ABC):
         if message.get('trigger') == self.trigger:
             return super().dispatch_handling(message)
         return None
+
+
+class BroadcastingEventHandler(EventHandlerBase, ABC):
+    # pylint: disable=abstract-method
+    """
+    Abstract base class for EventHandlers which broadcast responses
+    and intelligently ignore their own broadcasted messages they receive.
+    """
+    def __init__(self, key):
+        super().__init__(key)
+        self.own_message_hashes = []
+
+    def event_handler_callback(self, message):
+        message_hash = self.hash_message(message)
+
+        if message_hash in self.own_message_hashes:
+            self.own_message_hashes.remove(message_hash)
+            return
+
+        response = self.dispatch_handling(message)
+        if response:
+            self.own_message_hashes.append(self.hash_message(response))
+            self.server_connector.send(self.make_broadcast_message(response))
+
+    @staticmethod
+    def hash_message(message):
+        message_bytes = dumps(message, sort_keys=True).encode()
+        return md5(message_bytes).hexdigest()
+
+    @staticmethod
+    def make_broadcast_message(message):
+        return {
+            'key': 'broadcast',
+            'data': message
+        }

lib/tfw/fsm_base.py

@@ -1,36 +1,65 @@
 # Copyright (C) 2018 Avatao.com Innovative Learning Kft.
 # All Rights Reserved. See LICENSE file for details.
 
-from typing import List
+from collections import defaultdict
 
-from transitions import Machine
+from transitions import Machine, MachineError
 
 from tfw.mixins import CallbackMixin
+from tfw.config.logs import logging
+
+LOG = logging.getLogger(__name__)
 
 
-class FSMBase(CallbackMixin):
+class FSMBase(Machine, CallbackMixin):
     """
     A general FSM base class you can inherit from to track user progress.
     See linear_fsm.py for an example use-case.
-    TFW the transitions library for state machines, please refer to their
+    TFW uses the transitions library for state machines, please refer to their
     documentation for more information on creating your own machines:
     https://github.com/pytransitions/transitions
     """
     states, transitions = [], []
 
-    def __init__(self, initial: str = None, accepted_states: List[str] = None):
+    def __init__(self, initial=None, accepted_states=None):
-        CallbackMixin.__init__(self)
         self.accepted_states = accepted_states or [self.states[-1]]
-        self.machine = Machine(model=self,
+        self.trigger_predicates = defaultdict(list)
+
+        Machine.__init__(
+            self,
             states=self.states,
             transitions=self.transitions,
             initial=initial or self.states[0],
             send_event=True,
             ignore_invalid_triggers=True,
-                               after_state_change='execute_callbacks')
+            after_state_change='execute_callbacks'
+        )
 
     def execute_callbacks(self, event_data):
         self._execute_callbacks(event_data.kwargs)
 
     def is_solved(self):
         return self.state in self.accepted_states  # pylint: disable=no-member
+
+    def subscribe_predicate(self, trigger, *predicates):
+        self.trigger_predicates[trigger].extend(predicates)
+
+    def unsubscribe_predicate(self, trigger, *predicates):
+        self.trigger_predicates[trigger] = [
+            predicate
+            for predicate in self.trigger_predicates[trigger]
+            not in predicates
+        ]
+
+    def step(self, trigger):
+        predicate_results = (
+            predicate()
+            for predicate in self.trigger_predicates[trigger]
+        )
+
+        # TODO: think about what could we do when this prevents triggering
+        if all(predicate_results):
+            try:
+                self.trigger(trigger)
+            except (AttributeError, MachineError):
+                LOG.debug('FSM failed to execute nonexistent trigger: "%s"', trigger)

lib/tfw/linear_fsm.py

@@ -5,14 +5,25 @@ from .fsm_base import FSMBase
 
 
 class LinearFSM(FSMBase):
+    # pylint: disable=anomalous-backslash-in-string
     """
     This is a state machine for challenges with linear progression, consisting of
-    a number of steps specified in the constructor. It automatically sets up a single
+    a number of steps specified in the constructor. It automatically sets up 2
-    action between states as such:
+    actions (triggers) between states as such:
-    0 ==step_1==> 1 ==step_2==> 2 ==step_3==> 3 ... and so on
+    (0) --  step_1  --> (1) --  step_2  --> (2) --  step_3  --> (3) ... and so on
     """
     def __init__(self, number_of_steps):
         self.states = list(map(str, range(number_of_steps)))
-        self.transitions = [{'trigger': 'step_{}'.format(int(index)+1), 'source': index, 'dest': str(int(index)+1)}
+        self.transitions = []
-                            for index in self.states[:-1]]
+        for index in self.states[:-1]:
+            self.transitions.append({
+                'trigger': f'step_{int(index)+1}',
+                'source': index,
+                'dest': str(int(index)+1)
+            })
+            self.transitions.append({
+                'trigger': 'step_next',
+                'source': index,
+                'dest': str(int(index)+1)
+            })
         super(LinearFSM, self).__init__()

lib/tfw/mixins/__init__.py

@@ -1,7 +1,7 @@
 # Copyright (C) 2018 Avatao.com Innovative Learning Kft.
 # All Rights Reserved. See LICENSE file for details.
 
-from .supervisor_mixin import SupervisorMixin
+from .supervisor_mixin import SupervisorMixin, SupervisorLogMixin
 from .callback_mixin import CallbackMixin
 from .observer_mixin import ObserverMixin
 from .monitor_manager_mixin import MonitorManagerMixin

lib/tfw/mixins/callback_mixin.py

@@ -3,21 +3,32 @@
 
 from functools import partial
 
+from tfw.decorators import lazy_property
+
 
 class CallbackMixin:
-    def __init__(self):
+    @lazy_property
-        self._callbacks = []
+    def _callbacks(self):
+        return []
 
     def subscribe_callback(self, callback, *args, **kwargs):
         """
         Subscribe a callable to invoke once an event is triggered.
         :param callback: callable to be executed on events
-        :param *args: arguments passed to callable
+        :param args: arguments passed to callable
-        :param **kwargs: kwargs passed to callable
+        :param kwargs: kwargs passed to callable
         """
         fun = partial(callback, *args, **kwargs)
         self._callbacks.append(fun)
 
+    def subscribe_callbacks(self, *callbacks):
+        """
+        Subscribe a list of callbacks to incoke once an event is triggered.
+        :param callbacks: callbacks to be subscribed
+        """
+        for callback in callbacks:
+            self.subscribe_callback(callback)
+
     def unsubscribe_callback(self, callback):
         self._callbacks.remove(callback)
 

lib/tfw/mixins/monitor_manager_mixin.py

@@ -7,21 +7,24 @@ LOG = logging.getLogger(__name__)
 
 
 class MonitorManagerMixin:
-    def __init__(self, monitor_type, directory):
+    def __init__(self, monitor_type, *monitor_args):
         self._monitor_type = monitor_type
         self._monitor = None
-        self._monitored_directory = directory
+        self.monitor_args = monitor_args
         self.reload_monitor()
 
     @property
     def monitor(self):
         return self._monitor
 
+    def set_monitor_args(self, *monitor_args):
+        self.monitor_args = monitor_args
+
     def reload_monitor(self):
         if self._monitor:
             try:
                 self._monitor.stop()
             except KeyError:
                 LOG.debug('Working directory was removed – ignoring...')
-        self._monitor = self._monitor_type(self._monitored_directory)
+        self._monitor = self._monitor_type(*self.monitor_args)
         self._monitor.watch()   # This runs on a separate thread

lib/tfw/mixins/observer_mixin.py

@@ -3,10 +3,13 @@
 
 from watchdog.observers import Observer
 
+from tfw.decorators import lazy_property
+
 
 class ObserverMixin:
-    def __init__(self):
+    @lazy_property
-        self.observer = Observer()
+    def observer(self):
+        return Observer()
 
     def watch(self):
         self.observer.start()

lib/tfw/mixins/supervisor_mixin.py

@@ -6,12 +6,17 @@ from xmlrpc.client import Fault as SupervisorFault
 from contextlib import suppress
 from os import remove
 
+from tfw.decorators import lazy_property
 from tfw.config import TFWENV
 
 
-class SupervisorMixin:
+class SupervisorBaseMixin:
-    supervisor = xmlrpc.client.ServerProxy(TFWENV.SUPERVISOR_HTTP_URI).supervisor
+    @lazy_property
+    def supervisor(self):
+        return xmlrpc.client.ServerProxy(TFWENV.SUPERVISOR_HTTP_URI).supervisor
 
+
+class SupervisorMixin(SupervisorBaseMixin):
     def stop_process(self, process_name):
         with suppress(SupervisorFault):
             self.supervisor.stopProcess(process_name)
@@ -19,12 +24,20 @@ class SupervisorMixin:
     def start_process(self, process_name):
         self.supervisor.startProcess(process_name)
 
-    def read_log(self, process_name):
-        logs = self.supervisor.readProcessStderrLog(process_name, 0, 0)
-        remove(self.supervisor.getProcessInfo(process_name)['stderr_logfile'])
-        self.supervisor.clearProcessLogs(process_name)
-        return logs
-
     def restart_process(self, process_name):
         self.stop_process(process_name)
         self.start_process(process_name)
+
+
+class SupervisorLogMixin(SupervisorBaseMixin):
+    def read_stdout(self, process_name, tail=0):
+        return self.supervisor.readProcessStdoutLog(process_name, -tail, 0)
+
+    def read_stderr(self, process_name, tail=0):
+        return self.supervisor.readProcessStderrLog(process_name, -tail, 0)
+
+    def clear_logs(self, process_name):
+        for logfile in ('stdout_logfile', 'stderr_logfile'):
+            with suppress(FileNotFoundError):
+                remove(self.supervisor.getProcessInfo(process_name)[logfile])
+        self.supervisor.clearProcessLogs(process_name)

lib/tfw/networking/__init__.py

@@ -1,7 +1,7 @@
 # Copyright (C) 2018 Avatao.com Innovative Learning Kft.
 # All Rights Reserved. See LICENSE file for details.
 
-from .serialization import serialize_tfw_msg, deserialize_tfw_msg, validate_message
+from .serialization import serialize_tfw_msg, deserialize_tfw_msg, with_deserialize_tfw_msg
 from .zmq_connector_base import ZMQConnectorBase
 # from .controller_connector import ControllerConnector # TODO: readd once controller stuff is resolved
 from .message_sender import MessageSender

lib/tfw/networking/controller_connector.py

@@ -12,7 +12,7 @@ class ControllerConnector(ZMQConnectorBase):
     def __init__(self, zmq_context=None):
         super(ControllerConnector, self).__init__(zmq_context)
         self._zmq_rep_socket = self._zmq_context.socket(zmq.REP)
-        self._zmq_rep_socket.connect('tcp://localhost:{}'.format(TFWENV.CONTROLLER_PORT))
+        self._zmq_rep_socket.connect(f'tcp://localhost:{TFWENV.CONTROLLER_PORT}')
         self._zmq_rep_stream = ZMQStream(self._zmq_rep_socket)
 
         self.register_callback = self._zmq_rep_stream.on_recv_stream

lib/tfw/networking/event_handlers/server_connector.py

@@ -6,21 +6,27 @@ from functools import partial
 import zmq
 from zmq.eventloop.zmqstream import ZMQStream
 
-from tfw.networking import serialize_tfw_msg
+from tfw.networking import serialize_tfw_msg, with_deserialize_tfw_msg
 from tfw.networking import ZMQConnectorBase
 from tfw.config import TFWENV
+from tfw.config.logs import logging
+
+LOG = logging.getLogger(__name__)
 
 
 class ServerDownlinkConnector(ZMQConnectorBase):
     def __init__(self, zmq_context=None):
         super(ServerDownlinkConnector, self).__init__(zmq_context)
         self._zmq_sub_socket = self._zmq_context.socket(zmq.SUB)
-        self._zmq_sub_socket.connect('tcp://localhost:{}'.format(TFWENV.PUBLISHER_PORT))
+        self._zmq_sub_socket.connect(f'tcp://localhost:{TFWENV.PUBLISHER_PORT}')
         self._zmq_sub_stream = ZMQStream(self._zmq_sub_socket)
 
         self.subscribe = partial(self._zmq_sub_socket.setsockopt_string, zmq.SUBSCRIBE)
         self.unsubscribe = partial(self._zmq_sub_socket.setsockopt_string, zmq.UNSUBSCRIBE)
-        self.register_callback = self._zmq_sub_stream.on_recv
+
+    def register_callback(self, callback):
+        callback = with_deserialize_tfw_msg(callback)
+        self._zmq_sub_stream.on_recv(callback)
 
 
 class ServerUplinkConnector(ZMQConnectorBase):
@@ -30,11 +36,14 @@ class ServerUplinkConnector(ZMQConnectorBase):
     def __init__(self, zmq_context=None):
         super(ServerUplinkConnector, self).__init__(zmq_context)
         self._zmq_push_socket = self._zmq_context.socket(zmq.PUSH)
-        self._zmq_push_socket.connect('tcp://localhost:{}'.format(TFWENV.RECEIVER_PORT))
+        self._zmq_push_socket.connect(f'tcp://localhost:{TFWENV.RECEIVER_PORT}')
 
     def send_to_eventhandler(self, message):
         """
         Send a message to an event handler.
+        This envelopes the desired message in the 'data' field of the message to
+        TFWServer, which will mirror it to event handlers.
+
         :param message: JSON message you want to send
         :param message['key']: key of event handler you want to address
         """
@@ -46,6 +55,7 @@ class ServerUplinkConnector(ZMQConnectorBase):
     def send(self, message):
         """
         Send a message to the TFW server
+
         :param message: JSON message you want to send
         """
         self._zmq_push_socket.send_multipart(serialize_tfw_msg(message))

lib/tfw/networking/message_sender.py

@@ -1,30 +1,46 @@
 # Copyright (C) 2018 Avatao.com Innovative Learning Kft.
 # All Rights Reserved. See LICENSE file for details.
 
-from datetime import datetime
-
 from tfw.networking.event_handlers import ServerUplinkConnector
 
 
 class MessageSender:
     """
-    Provides a mechanism to send messages to our frontend messaging component which
+    Provides mechanisms to send messages to our frontend messaging component.
-    displays messages with the key "message".
     """
-    def __init__(self, custom_key: str = None):
+    def __init__(self):
         self.server_connector = ServerUplinkConnector()
-        self.key = custom_key or 'message'
+        self.key = 'message'
+        self.queue_key = 'queueMessages'
 
     def send(self, originator, message):
         """
-        Sends a message to the key specified in __init__.
+        Sends a message.
         :param originator: name of sender to be displayed on the frontend
         :param message: message to send
         """
         data = {
             'originator': originator,
-            'timestamp': datetime.now().isoformat(),
             'message': message
         }
-        self.server_connector.send({'key': self.key,
+        self.server_connector.send({
-                                    'data': data})
+            'key': self.key,
+            'data': data
+        })
+
+    def queue_messages(self, originator, messages):
+        """
+        Queues a list of messages to be displayed in a chatbot-like manner.
+        :param originator: name of sender to be displayed on the frontend
+        :param messages: list of messages to queue
+        """
+        data = {
+            'messages': [
+                {'message': message, 'originator': originator}
+                for message in messages
+            ]
+        }
+        self.server_connector.send({
+            'key': self.queue_key,
+            'data': data
+        })

lib/tfw/networking/serialization.py

@@ -22,35 +22,60 @@ The purpose of this module is abstracting away this low level behaviour.
 """
 
 import json
-
+from functools import wraps
-
-def validate_message(message):
-    return 'key' in message
 
 
 def serialize_tfw_msg(message):
+    """
+    Create TFW multipart data from message dict
+    """
     return _serialize_all(message['key'], message)
 
 
+def with_deserialize_tfw_msg(fun):
+    @wraps(fun)
+    def wrapper(message_parts):
+        message = deserialize_tfw_msg(*message_parts)
+        return fun(message)
+    return wrapper
+
+
 def deserialize_tfw_msg(*args):
+    """
+    Return message from TFW multipart data
+    """
     return _deserialize_all(*args)[1]
 
 
 def _serialize_all(*args):
-    return tuple(_serialize_single(arg) for arg in args)
+    return tuple(
+        _serialize_single(arg)
+        for arg in args
+    )
 
 
 def _deserialize_all(*args):
-    return tuple(_deserialize_single(arg) for arg in args)
+    return tuple(
+        _deserialize_single(arg)
+        for arg in args
+    )
 
 
 def _serialize_single(data):
+    """
+    Return input as bytes
+    (serialize input if it is JSON)
+    """
     if not isinstance(data, str):
         data = json.dumps(data)
     return _encode_if_needed(data)
 
 
 def _deserialize_single(data):
+    """
+    Try parsing input as JSON, return it as
+    string if parsing fails.
+    """
     try:
         return json.loads(data)
     except ValueError:
@@ -58,12 +83,20 @@ def _deserialize_single(data):
 
 
 def _encode_if_needed(value):
+    """
+    Return input as bytes
+    (encode if input is string)
+    """
     if isinstance(value, str):
         value = value.encode('utf-8')
     return value
 
 
 def _decode_if_needed(value):
+    """
+    Return input as string
+    (decode if input is bytes)
+    """
     if isinstance(value, (bytes, bytearray)):
         value = value.decode('utf-8')
     return value

lib/tfw/networking/server/__init__.py

@@ -3,5 +3,4 @@
 
 from .event_handler_connector import EventHandlerConnector, EventHandlerUplinkConnector, EventHandlerDownlinkConnector
 from .tfw_server import TFWServer
-from .zmq_websocket_handler import ZMQWebSocketProxy
 # from .controller_responder import ControllerResponder  # TODO: readd once controller stuff is resolved

lib/tfw/networking/server/event_handler_connector.py

@@ -4,7 +4,7 @@
 import zmq
 from zmq.eventloop.zmqstream import ZMQStream
 
-from tfw.networking import ZMQConnectorBase, serialize_tfw_msg
+from tfw.networking import ZMQConnectorBase, serialize_tfw_msg, with_deserialize_tfw_msg
 from tfw.config import TFWENV
 from tfw.config.logs import logging
 
@@ -16,7 +16,7 @@ class EventHandlerDownlinkConnector(ZMQConnectorBase):
         super(EventHandlerDownlinkConnector, self).__init__(zmq_context)
         self._zmq_pull_socket = self._zmq_context.socket(zmq.PULL)
         self._zmq_pull_stream = ZMQStream(self._zmq_pull_socket)
-        address = 'tcp://*:{}'.format(TFWENV.RECEIVER_PORT)
+        address = f'tcp://*:{TFWENV.RECEIVER_PORT}'
         self._zmq_pull_socket.bind(address)
         LOG.debug('Pull socket bound to %s', address)
 
@@ -25,13 +25,14 @@ class EventHandlerUplinkConnector(ZMQConnectorBase):
     def __init__(self, zmq_context=None):
         super(EventHandlerUplinkConnector, self).__init__(zmq_context)
         self._zmq_pub_socket = self._zmq_context.socket(zmq.PUB)
-        address = 'tcp://*:{}'.format(TFWENV.PUBLISHER_PORT)
+        address = f'tcp://*:{TFWENV.PUBLISHER_PORT}'
         self._zmq_pub_socket.bind(address)
         LOG.debug('Pub socket bound to %s', address)
 
 
 class EventHandlerConnector(EventHandlerDownlinkConnector, EventHandlerUplinkConnector):
     def register_callback(self, callback):
+        callback = with_deserialize_tfw_msg(callback)
         self._zmq_pull_stream.on_recv(callback)
 
     def send_message(self, message: dict):

lib/tfw/networking/server/tfw_server.py

@@ -1,15 +1,12 @@
 # Copyright (C) 2018 Avatao.com Innovative Learning Kft.
 # All Rights Reserved. See LICENSE file for details.
 
-from collections import defaultdict
-
 from tornado.web import Application
 
-from tfw.networking import MessageSender
 from tfw.networking.event_handlers import ServerUplinkConnector
 from tfw.networking.server import EventHandlerConnector
 from tfw.config.logs import logging
-from .zmq_websocket_handler import ZMQWebSocketProxy
+from .zmq_websocket_proxy import ZMQWebSocketProxy
 
 LOG = logging.getLogger(__name__)
 
@@ -18,103 +15,29 @@ class TFWServer:
     """
     This class handles the proxying of messages between the frontend and event handers.
     It proxies messages from the "/ws" route to all event handlers subscribed to a ZMQ
-    SUB socket. It also manages an FSM you can define as a constructor argument.
+    SUB socket.
     """
-    def __init__(self, fsm_type):
+    def __init__(self):
-        """
-        :param fsm_type: the type of FSM you want TFW to use
-        """
-        self._fsm = fsm_type()
-        self._fsm_updater = FSMUpdater(self._fsm)
-        self._fsm_manager = FSMManager(self._fsm)
-        self._fsm.subscribe_callback(self._fsm_updater.update)
         self._event_handler_connector = EventHandlerConnector()
+        self._uplink_connector = ServerUplinkConnector()
 
-        self.application = Application(
+        self.application = Application([(
-            [(r'/ws', ZMQWebSocketProxy, {'make_eventhandler_message': self.make_eventhandler_message,
+            r'/ws', ZMQWebSocketProxy,{
-                                          'proxy_filter': self.proxy_filter,
+                'event_handler_connector': self._event_handler_connector,
-                                          'handle_trigger': self.handle_trigger,
+                'message_handlers': [self.handle_trigger]
-                                          'event_handler_connector': self._event_handler_connector})]
+            })]
         )
-        #self.controller_responder = ControllerResponder(self.fsm) TODO: add this once controller stuff is resolved
-
-    @property
-    def fsm(self):
-        return self._fsm
-
-    @property
-    def fsm_manager(self):
-        return self._fsm_manager
-
-    def make_eventhandler_message(self, message):
-        self.trigger_fsm(message)
-        message['FSMUpdate'] = self._fsm_updater.get_fsm_state_and_transitions()
-        return message
 
     def handle_trigger(self, message):
+        if 'trigger' in message:
             LOG.debug('Executing handler for trigger "%s"', message.get('trigger', ''))
-        self.trigger_fsm(message)
+            self._uplink_connector.send_to_eventhandler({
-
+                'key': 'fsm',
-    def trigger_fsm(self, message):
+                'data': {
-        trigger = message.get('trigger', '')
+                    'command': 'trigger',
-        try:
+                    'value': message.get('trigger', '')
-            self._fsm_manager.trigger(trigger, message)
+                }
-        except AttributeError:
+            })
-            LOG.debug('FSM failed to execute nonexistent trigger: "%s"', trigger)
-
-    def proxy_filter(self, message):
-        # pylint: disable=unused-argument,no-self-use
-        return True
 
     def listen(self, port):
         self.application.listen(port)
-
-
-class FSMManager:
-    def __init__(self, fsm):
-        self._fsm = fsm
-        self.trigger_predicates = defaultdict(list)
-        self.messenge_sender = MessageSender()
-
-    @property
-    def fsm(self):
-        return self._fsm
-
-    def trigger(self, trigger, message):
-        predicate_results = []
-        for predicate in self.trigger_predicates[trigger]:
-            success, message = predicate(message)
-            predicate_results.append(success)
-            self.messenge_sender.send('FSM', message)
-
-        if all(predicate_results):
-            try:
-                self.fsm.trigger(trigger, message=message)
-            except AttributeError:
-                LOG.debug('FSM failed to execute nonexistent trigger: "%s"', trigger)
-
-    def subscribe_predicate(self, trigger, *predicates):
-        self.trigger_predicates[trigger].extend(predicates)
-
-    def unsubscribe_predicate(self, trigger, *predicates):
-        self.trigger_predicates[trigger] = [predicate for predicate in self.trigger_predicates[trigger]
-                                            not in predicates]
-
-
-class FSMUpdater:
-    def __init__(self, fsm):
-        self.fsm = fsm
-        self.uplink = ServerUplinkConnector()
-
-    def update(self, kwargs_dict):
-        # pylint: disable=unused-argument
-        self.uplink.send(self.generate_fsm_update())
-
-    def generate_fsm_update(self):
-        return {'key': 'FSMUpdate',
-                'data': self.get_fsm_state_and_transitions()}
-
-    def get_fsm_state_and_transitions(self):
-        state = self.fsm.state
-        valid_transitions = [{'trigger': trigger} for trigger in self.fsm.machine.get_triggers(self.fsm.state)]
-        return {'current_state': state, 'valid_transitions': valid_transitions}

lib/tfw/networking/server/zmq_websocket_handler.py

@@ -1,91 +0,0 @@
-# Copyright (C) 2018 Avatao.com Innovative Learning Kft.
-# All Rights Reserved. See LICENSE file for details.
-
-import json
-from abc import ABC, abstractmethod
-
-from tornado.websocket import WebSocketHandler
-
-from tfw.networking import deserialize_tfw_msg, validate_message
-from tfw.config.logs import logging
-
-LOG = logging.getLogger(__name__)
-
-
-class ZMQWebSocketHandler(WebSocketHandler, ABC):
-    instances = set()
-
-    def initialize(self, **kwargs): # pylint: disable=arguments-differ
-        self._event_handler_connector = kwargs['event_handler_connector']
-
-    def prepare(self):
-        ZMQWebSocketHandler.instances.add(self)
-
-    def on_close(self):
-        ZMQWebSocketHandler.instances.remove(self)
-
-    def open(self, *args, **kwargs):
-        LOG.debug('WebSocket connection initiated')
-        self._event_handler_connector.register_callback(self.zmq_callback)
-
-    def zmq_callback(self, msg_parts):
-        keyhandlers = {'mirror': self.mirror}
-
-        message = deserialize_tfw_msg(*msg_parts)
-        LOG.debug('Received on pull socket: %s', message)
-        if not validate_message(message):
-            return
-
-        self.handle_trigger(message)
-        if message['key'] not in keyhandlers:
-            for instance in ZMQWebSocketHandler.instances:
-                instance.write_message(message)
-        else:
-            try:
-                keyhandlers[message['key']](message)
-            except KeyError:
-                LOG.error('Invalid mirror message format! Ignoring.')
-
-    def mirror(self, message):
-        message = message['data']
-        self._event_handler_connector.send_message(message)
-
-    def on_message(self, message):
-        LOG.debug('Received on WebSocket: %s', message)
-        if validate_message(message):
-            self.send_message(self.make_eventhandler_message(message))
-
-    @abstractmethod
-    def make_eventhandler_message(self, message):
-        raise NotImplementedError
-
-    def send_message(self, message: dict):
-        self._event_handler_connector.send_message(message)
-
-    @abstractmethod
-    def handle_trigger(self, message):
-        raise NotImplementedError
-
-    # much secure, very cors, wow
-    def check_origin(self, origin):
-        return True
-
-
-class ZMQWebSocketProxy(ZMQWebSocketHandler):
-    # pylint: disable=abstract-method
-    def initialize(self, **kwargs): # pylint: disable=arguments-differ
-        super(ZMQWebSocketProxy, self).initialize(**kwargs)
-        self._make_eventhandler_message = kwargs['make_eventhandler_message']
-        self._proxy_filter = kwargs['proxy_filter']
-        self._handle_trigger = kwargs['handle_trigger']
-
-    def on_message(self, message):
-        message = json.loads(message)
-        if self._proxy_filter(message):
-            super().on_message(message)
-
-    def make_eventhandler_message(self, message):
-        return self._make_eventhandler_message(message)
-
-    def handle_trigger(self, message):
-        self._handle_trigger(message)

lib/tfw/networking/server/zmq_websocket_proxy.py

@@ -0,0 +1,121 @@
+# Copyright (C) 2018 Avatao.com Innovative Learning Kft.
+# All Rights Reserved. See LICENSE file for details.
+
+import json
+
+from tornado.websocket import WebSocketHandler
+
+from tfw.mixins import CallbackMixin
+from tfw.config.logs import logging
+
+LOG = logging.getLogger(__name__)
+
+
+class ZMQWebSocketProxy(WebSocketHandler):
+    instances = set()
+
+    def initialize(self, **kwargs): # pylint: disable=arguments-differ
+        self._event_handler_connector = kwargs['event_handler_connector']
+        self._message_handlers = kwargs.get('message_handlers', [])
+        self._proxy_filters = kwargs.get('proxy_filters', [])
+
+        self.proxy_eventhandler_to_websocket = TFWProxy(
+            self.send_eventhandler_message,
+            self.send_websocket_message
+        )
+        self.proxy_websocket_to_eventhandler = TFWProxy(
+            self.send_websocket_message,
+            self.send_eventhandler_message
+        )
+
+        proxies = (self.proxy_eventhandler_to_websocket, self.proxy_websocket_to_eventhandler)
+        for proxy in proxies:
+            proxy.proxy_filters.subscribe_callbacks(*self._proxy_filters)
+            proxy.proxy_callbacks.subscribe_callbacks(*self._message_handlers)
+
+    def prepare(self):
+        ZMQWebSocketProxy.instances.add(self)
+
+    def on_close(self):
+        ZMQWebSocketProxy.instances.remove(self)
+
+    def open(self, *args, **kwargs):
+        LOG.debug('WebSocket connection initiated')
+        self._event_handler_connector.register_callback(self.eventhander_callback)
+
+    def eventhander_callback(self, message):
+        """
+        Invoked on ZMQ messages from event handlers.
+        """
+        LOG.debug('Received on pull socket: %s', message)
+        self.proxy_eventhandler_to_websocket(message)
+
+    def on_message(self, message):
+        """
+        Invoked on WS messages from frontend.
+        """
+        message = json.loads(message)
+        LOG.debug('Received on WebSocket: %s', message)
+        self.proxy_websocket_to_eventhandler(message)
+
+    def send_eventhandler_message(self, message):
+        self._event_handler_connector.send_message(message)
+
+    @staticmethod
+    def send_websocket_message(message):
+        for instance in ZMQWebSocketProxy.instances:
+            instance.write_message(message)
+
+    # much secure, very cors, wow
+    def check_origin(self, origin):
+        return True
+
+
+class TFWProxy:
+    def __init__(self, to_source, to_destination):
+        self.to_source = to_source
+        self.to_destination = to_destination
+
+        self.proxy_filters = CallbackMixin()
+        self.proxy_callbacks = CallbackMixin()
+
+        self.proxy_filters.subscribe_callback(self.validate_message)
+
+        self.keyhandlers = {
+            'mirror':    self.mirror,
+            'broadcast': self.broadcast
+        }
+
+    @staticmethod
+    def validate_message(message):
+        if 'key' not in message:
+            raise ValueError('Invalid TFW message format!')
+
+    def __call__(self, message):
+        try:
+            self.proxy_filters._execute_callbacks(message)
+        except ValueError:
+            LOG.exception('Invalid TFW message received!')
+            return
+
+        self.proxy_callbacks._execute_callbacks(message)
+
+        if message['key'] not in self.keyhandlers:
+            self.to_destination(message)
+        else:
+            handler = self.keyhandlers[message['key']]
+            try:
+                handler(message)
+            except KeyError:
+                LOG.error('Invalid "%s" message format! Ignoring.', handler.__name__)
+
+    def mirror(self, message):
+        message = message['data']
+        LOG.debug('Mirroring message: %s', message)
+        self.to_source(message)
+
+    def broadcast(self, message):
+        message = message['data']
+        LOG.debug('Broadcasting message: %s', message)
+        self.to_source(message)
+        self.to_destination(message)

lib/tfw/yaml_fsm.py

@@ -0,0 +1,64 @@
+from subprocess import Popen, run
+from functools import partial
+from contextlib import suppress
+
+import yaml
+from transitions import State
+
+from tfw import FSMBase
+
+
+class YamlFSM(FSMBase):
+    def __init__(self, config_file):
+        self.config = self.parse_config(config_file)
+        self.setup_states()
+        super().__init__()  # FSMBase.__init__() requires states
+        self.setup_transitions()
+
+    @staticmethod
+    def parse_config(config_file):
+        with open(config_file, 'r') as ifile:
+            return yaml.safe_load(ifile)
+
+    def setup_states(self):
+        self.for_config_states_and_transitions_do(self.wrap_callbacks_with_subprocess_call)
+        self.states = [State(**state) for state in self.config['states']]
+
+    def setup_transitions(self):
+        self.for_config_states_and_transitions_do(self.subscribe_and_remove_predicates)
+        for transition in self.config['transitions']:
+            self.add_transition(**transition)
+
+    def for_config_states_and_transitions_do(self, what):
+        for array in ('states', 'transitions'):
+            for json_obj in self.config[array]:
+                what(json_obj)
+
+    @staticmethod
+    def wrap_callbacks_with_subprocess_call(json_obj):
+        topatch = ('on_enter', 'on_exit', 'prepare', 'before', 'after')
+        for key in json_obj:
+            if key in topatch:
+                json_obj[key] = partial(run_command_async, json_obj[key])
+
+    def subscribe_and_remove_predicates(self, json_obj):
+        if 'predicates' in json_obj:
+            for predicate in json_obj['predicates']:
+                    self.subscribe_predicate(
+                        json_obj['trigger'],
+                        partial(
+                            command_statuscode_is_zero,
+                            predicate
+                        )
+                    )
+                
+        with suppress(KeyError):
+            json_obj.pop('predicates')
+
+
+def run_command_async(command, event):
+    Popen(command, shell=True)
+
+
+def command_statuscode_is_zero(command):
+    return run(command, shell=True).returncode == 0

nginx/default.conf

@@ -4,6 +4,7 @@ server {
     proxy_connect_timeout 7d;
     proxy_send_timeout 7d;
     proxy_read_timeout 7d;
+    absolute_redirect off;
 
     location = /ws {
         proxy_pass http://127.0.0.1:${TFW_WEB_PORT};

requirements.txt

@@ -3,3 +3,4 @@ pyzmq==17.0.0
 transitions==0.6.4
 terminado==0.8.1
 watchdog==0.8.3
+PyYAML==3.12

setup.py

@@ -0,0 +1,29 @@
+from os.path import dirname, realpath, join
+
+from setuptools import setup, find_packages
+
+here = dirname(realpath(__file__))
+
+with open(join(here, 'VERSION'), 'r') as ifile:
+    version = ifile.read().strip('\n')
+with open(join(here, 'requirements.txt'), 'r') as ifile:
+    requirements = ifile.read().splitlines()
+
+setup(
+    name = 'tfw',
+    version = version,
+    description = 'Avatao tutorial-framework',
+    url = 'https://github.com/avatao-content/baseimage-tutorial-framework',
+    author = 'Avatao.com Innovative Learning Kft.',
+    author_email = 'support@avatao.com',
+    license = 'custom',
+    packages = find_packages('lib'),
+    package_dir = {'': 'lib'},
+    install_requires = requirements,
+    extras_require = {
+        'docs': [
+            'sphinx >= 1.7.0',
+        ],
+    },
+    zip_safe = False,
+)

supervisor/components/tfw_server.conf

@@ -0,0 +1,4 @@
+[program:tfwserver]
+user=root
+directory=%(ENV_TFW_SERVER_DIR)s
+command=python3 tfw_server.py

supervisor/supervisord.conf

@@ -1,8 +1,10 @@
 [supervisord]
 user=root
-logfile = /tmp/supervisord.log
+logfile=/dev/null
+logfile_maxbytes=0
 loglevel = debug
 pidfile = /tmp/supervisord.pid
+strip_ansi=true
 
 [inet_http_server]
 port = 127.0.0.1:%(ENV_TFW_SUPERVISOR_HTTP_PORT)s

supervisor/tfw_server.py

@@ -0,0 +1,9 @@
+from tornado.ioloop import IOLoop
+
+from tfw.networking import TFWServer
+from tfw.config import TFWENV
+
+
+if __name__ == '__main__':
+    TFWServer().listen(TFWENV.WEB_PORT)
+    IOLoop.instance().start()