Continue writing thesis

content/a_tour_of_tfw.tex

@@ -1,4 +1,17 @@
-\chapter{A Tour of TFW}
+\chapter{A Tour of TFW}\label{atouroftfw}
+
+The bulk of the functionality provided by the Tutorial Framework
+is implemented in pre-made components that are built upon the architecture
+described in Chapter~\ref{architecture}.
+To create tutorials, developers generally rely on and use TFW provided components to
+implement most of the common functionality and then build more exercise-specific logic
+based on the TFW architecture themselves.
+A \emph{very important} point to keep in mind is that most of this
+exercise-specific logic will be implemented in \textbf{FSM callbacks} and
+custom \textbf{event handlers}.
+The whole framework is built in a way to faciliate this process and developers
+who understand this mindset are almost always guaranteed to create great
+content using TFW.
 
 The purpose of this chapter is to further detail the built-in components
 provided by the framework.
@@ -191,6 +204,28 @@ certain command are executed by the user.
 
 \pic{figures/terminal.png}{The Frontend Terminal of TFW Running top}
 
+The implementation of reading command history is quite an exotic one.
+The framework need to be able to detect if the user has executed any command in the
+container.
+This is not an easy thing to accomplish without relying some sort of heavyweight
+monitoring solution such as Sysdig%
+\footnote{\href{https://sysdig.comq}{https://sysdig.com}}.
+I deemed most simiar systems a huge overkill to implement this functionality, and their
+memory footprints are not something we can really afford here.
+Another way would be to use \texttt{pam_tty_audit.so} in the PAM%
+\footnote{Linux Pluggable Authentication Modules:
+\href{http://man7.org/linux/man-pages/man3/pam.3.html}
+{http://man7.org/linux/man-pages/man3/pam.3.html}}
+configurations responsible for logins, as this allows various TTY auditing, but
+I have found an ever simpler approach to the problem in the end.
+By using the inotify system built into TFW, I can set up the user's environment in
+such a way, that I can enforce or determine the location of the bash \texttt{HISTFILE}%
+\footnote{This environment variable contains the path to the file bash writes command
+history to}
+of the user.
+This way I can monitor changes made to this file and read the commands executed
+by the user from it.
+
 \section{Console Component}
 
 This component is a simple textbox that can be used to display anything to the user,
@@ -253,3 +288,25 @@ in a spectacular fashion until the whole thing managed to crash.
 It was an event of such chaotic beauty, that I often fondly recall it to this day.
 Of course it would take me several hours to identify the exact causes behind this
 fascinating phenomenon, but those were \emph{very} fun hours.
+
+\section{FSM Management}
+
+I have already mentioned the event handler called \texttt{FSMManagingEventHandler},
+which is responsible for managing the framework FSM.
+For completeness I chose to include it on this chapter as well.
+The API it exposes through TFW messages allows client code to attempt stepping the
+state machine.
+As previously explained this is something that is considered to be a \emph{privileged}
+operation in case authentication is enabled, causing the event handler to accept
+digitally signed messages only.
+In the event of a successful FSM step, this component is going to broadcast
+a message showcased as an example in the beginning of Chapter~\ref{atouroftfw}.
+
+\section{Additional Frontend Features}
+
+The frontend of the framework exposes some additional APIs through
+TFW messages.
+These include the changing of layouts, selecting the terminal or console
+component to be displayed, the possibility of dynamically modifying other
+frontend configuration (such as the frequency of autosaving the files in the editor)
+and more.

content/architecture.tex

@@ -1,4 +1,4 @@
-\chapter{Framework Architecture}
+\chapter{Framework Architecture}\label{architecture}
 \section{Core Technology}
 
 It is important to understand that the Tutorial Framework is currently implemented as
@@ -331,6 +331,12 @@ users, which many solutions for distance education lack so often.
 
 Developers can use a YAML file or write Python code to implement finite
 state machines.
+In state machine implementations it is possbile to subscribe callbacks to be
+invoked on certain events regarding the machine, such as before and after
+state transitions, or onentering and exiting a state.
+It is \emph{very} important to be aware of these callbacks, as much of the
+actual tutorial logic is often going to be implemented in these.
+
 Architecturally a built-in event handler called \texttt{FSMManagingEventHandler}
 is capable of managing the FSM defined by clients.
 The responsibilities of said event handler include:

content/using_the_framework.tex

@@ -1,7 +1,7 @@
 \chapter{Using the Framework}
 
 In this section I am going to dive into further detail on how client code is supposed
-to use the framework, some of the design decisions behind this and how all all of this
+to use the framework, some of the design decisions behind this and how everything is
 is integrated into the \texttt{solvable} Docker image.
 
 To use the framework one has to do several things to get started.
@@ -15,14 +15,31 @@ The main poins include:
     \item set up reverse proxying for any user-facing network applications such as webservers,
           SSH and friends
 \end{itemize}
-At first all these tasks are quite overwhelming.
+At first all these tasks can seem quite overwhelming.
 Remember that witchcraft is what we practice here after all.
 To overcome the high initial learning curve of getting familiar with the framework
 I have created a repository called \emph{test-tutorial-framework} with the purpose of
 providing a project template for developers looking to create challenges using the
 framework.
 This repository is a really simple client codebase that is suitable for
-developing TFW itself as well (a good place to tests for the framework).
-Let us take a look at this to acquire a greater understanding of how the framework operates.
+developing TFW itself as well (a good place for the tests of the framework).
+I also provides an ``industry standard'' \texttt{hack} directory
+containing bash scripts that make the development of challenges and TFW itself very convenient.
+These scripts span from bootstrapping a complete development environment in one command,
+to building and running challenges based on the framework. 
+Let us take a quick look at the \emph{test-tutorial-framework} project to acquire a greater
+understanding of how the framework operates.
 
 \section{Project Structure}
+
+\section{Implementing a Finite State Machine}
+
+\section{Defining Processes to Run}
+
+\section{Exposing Front-facing Networking Applications}
+
+\section{How This Works}
+
+\section{Developer Tooling}
+
+\section{Framework Release Management}