modelverse/techreport/general/network_communication.tex

\chapter{Network communication}
%Apart from the logical interface that is exposed, the physical interface should also be specified.
%This interface determines how the provided services can be invoked, possibly over the network.
%Since the Modelverse components are defined as seperate modules, with a standardized API, multiple back-ends can be created to couple them.
%Depending on the used back-end, the physical interface will differ.
%We will implement a simple back-end that makes the Modelverse state run as a service, exposed to the network.
%This is done with the XML/HTTP back-end, described below.
%
%While XML/HTTP is not the most efficient protocol for this data exchange, it has the most wide portability and is not blocked by most firewalls.
%It also shows that our approach works with even a minimal communication protocol.
%In the future, it is possible to define new back-ends, which possibly uses low-latency and low-overhead communication protocols.
%Using XML/HTTP can still be used as a fallback method if other protocols are not supported.

\section{Motivation}

\section{Modelverse State}

\subsection{Interface}
The XML/HTTPRequest back-end of the MvS will simply host an HTTP server, which responds to POST requests.
The reply of the server is again encoded in the same format as the POST request.

All requests should be send via POST, and contain the following two parameters:
\begin{itemize}
\item \textbf{op}: this indicates which operation to execute on the MvS.
\item \textbf{params}: contains the parameters for the function, encoded in JSON format.
    While we require JSON encoding, the data can never be complex due to the simple signature of the supported operations.
    This parameter should always be a list of the parameters to pass.
    If there is only a single parameter, a list with a single element is still required.
\end{itemize}

The operations all use coding, to reduce the amount of data that needs to be transfered.
Table~\ref{table:decoding} shows the mapping between the operation and the formalized function name.

\begin{table}
\center
\begin{tabular}{l l}
    \textbf{Operation} & \textbf{Formal function} \\
    \hline
    \hline
    CN & create\_node \\
    CE & create\_edge \\
    CNV & create\_nodevalue \\
    CD & create\_dict \\
    \hline
    RV & read\_value \\
    RO & read\_outgoing \\
    RI & read\_incoming \\
    RE & read\_edge \\
    RD & read\_dict \\
    RDN & read\_dict\_node \\
    RDE & read\_dict\_edge \\
    RRD & read\_reverse\_dict \\
    RR & read\_root \\
    RDK & read\_dict\_keys \\
    \hline
    DE & delete\_edge \\
    DN &  delete\_node \\
\end{tabular}
\caption{Mapping between operations and formalized function name}
\label{table:decoding}
\end{table}

\begin{lstlisting}[label=listing:request_reply,caption=Example request and reply,frame=single]
Request: op=RE&params=[1]
Reply:   data=[[2, 3], 100]
\end{lstlisting}

An example request, and corresponding reply, is shown in Listing~\ref{listing:request_reply}, where an edge with identifier 1 is read.
The reply indicates that the request was succesful (statuscode 100), and the returnvalue indicates that edge 1 goes from element 2 to element 3.

Note that the $\mathcal{G}$ parts of the request and reply, as were formalized previously, are not included.
This is because the MvS itself is the instance of $\mathcal{G}$ being modified.

Sockets are kept open until explicitly closed, so it is possible to reuse a single socket for every request.
It is also possible to send a request before the previous request is handled of.
In that case, the order of the replies will be the same as of the requests.

\subsection{Statechart}

\begin{figure}
    \center
    \includegraphics[width=0.7\textwidth]{images/mvs_server.pdf}
    \caption{Modelverse State server statechart}
    \label{fig:mvs_server_statechart}
\end{figure}

\section{Modelverse Kernel}

\subsection{Interface}
Communication with the Modelverse Kernel is very similar to the communication with the Modelverse State.
The Modelverse accepts two different operations: \texttt{set\_input} and \texttt{get\_output}.
Data is to be send as a POST request, and has to consist of the following fields:
\begin{enumerate}
\item \textbf{op}: the operation to perform. It can be either "set\_input" or "get\_output".
    Depending on the value of this entry, some additional elements need to be present in the request.
\item \textbf{username}: the name of the user whose input or output queue is modified.
    Always present for both operations.
\item \textbf{element\_type}: how to interpret the value parameter.
    It is either "R", to indicate that the value parameter is a reference, and therefore an element identifier.
    The other option is "V", to indicate that the value parameter is a JSON encoded value.
    Only present if the operation is set\_input.
\item \textbf{value}: the actual parameter to the operation.
    Its interpretation is given by the element\_type operation.
    If it has to be interpreted as a value, it needs to be an instance of a primitive for the MvS.
    Only present if the operation is set\_input.
\end{enumerate}

For both requests, a reply will be returned containing an \textit{id} and \textit{value} entry.

For the \texttt{set\_input}, the \textit{id} and \textit{value} are a status code and human-readable description.
Generally, giving input should always succeed, resulting in \textit{id} 100 and \textit{value} \texttt{success}.

For the \texttt{get\_output}, the \textit{id} will be the identifier of the node that is to be output.
The \textit{value} is the value of the node with the provided identifier.
Getting output is a blocking call, so the request will stay open until input is actually generated.
As soon as the output is generated, it will be sent out.

An example request and reply is shown in Listing~\ref{listing:reqrep_new_user} and~\ref{listing:reqrep_setR}, for set\_input, and Listing~\ref{listing:reqrep_output} and~\ref{listing:reqrep_output_fail}, for get\_output.

\begin{lstlisting}[frame=single,caption=Example: create new user,label=listing:reqrep_new_user]
Request: op=set_input&username=user_manager&element_type=V&value="user_1"
Reply:   id=100&value="success"
\end{lstlisting}

\begin{lstlisting}[frame=single,caption=Example: input element ID 15 for user,label=listing:reqrep_setR]
Request: op=set_input&username=user_1&element_type=R&value=15
Reply:   id=100&value="success"
\end{lstlisting}

\begin{lstlisting}[frame=single,caption=Example: read output valuelabel=listing:reqrep_output]
Request: op=get_output&username=user_1
Reply:   id=123&value="node_value"
\end{lstlisting}

\subsection{Statechart}

\begin{figure}
    \center
    \includegraphics[width=1.3\textwidth,angle=90]{images/mvk_server.pdf}
    \caption{Modelverse Kernel server statechart}
    \label{fig:mvk_server_statechart}
\end{figure}

\section{Modelverse Interface}