Next: 4. Command Protocol Up: Status Server Detailed Design Previous: 2. Development and Execution Contents

Subsections

3.1 Client $\Leftrightarrow$ Server Communication

3. Status Server System Overview

A visual representation of the high-level components involved in the Status Server System can be found in figure 2. This document focuses on the Status Server and Client C API components and the message protocol used between client and server. It is possible for users to connect to the Status Server via a telnet session, using the same message protocol used by the client C API.

**Figure 1:** Status Server High-Level System Diagram
$\begin{figure} \center \epsfig {file=ss_system.eps}\end{figure}$

3.1 Client $\Leftrightarrow$ Server Communication

3.1.1 Overview

The Status Server will listen over a socket interface to client requests. The server will service each request and send back an associated response. With the exception of a disconnect request, each client request will receive a response from the Status Server. In most cases, the client will receive a single line response to a request. The exception to the single response model is the case where a client has requested monitoring updates or the client has requested the contents of a directory. Multiple line response messages will always be terminated with an end-of-transaction (EOT) return message. The client must not send any new commands until it has fully processed the current command. If, for some reason, the server receives a new command request from a client before it has sent the client the last response, it may inform the client that a protocol error has occurred. At this point, the Status Server will expect the client to close the connection. If, however, the client sends another command, the Status Server will close the client connection.

In the case of monitored objects, it is possible for a client to receive an unsolicited message across the interface. This message is triggered the first time a client-monitored object is updated beyond the ``deadband'' restriction and the client has not already been informed of a monitor update. Once a client is informed that it has monitored information to retrieve, it must initiate a ``poll'' request to retrieve the information. This is an event-driven model which triggers the client to always initiate a retrieval of monitor information. This document does not address the handshaking implementation concerning how a client using the Client API will be notified that monitors are available and the triggering mechanism to retrieve them. This will be defined in the detailed design of the Client API.

The Status Server will utilize the sockio library to handle the low-level socket details. The sockio library uses a single-threaded non-blocking approach to handling client connections. The interaction between the sockio library functions and the Status Server will be discussed in more detail in the software design section of this document. In addition, you can review the the CFHT Socket I/O Library document for more information regarding the design of this library.

Both the Status Server and sockio library are designed in such a way that any data sent across the socket can be gracefully handled. This includes receiving binary data or unusually long messages which may or may not be properly terminated with a newline character. If a client attempts to connect from outside the CFHT network, or a client violates the established message protocol, whenever possible its connection will be terminated.

Each request received by the Status Server will be checked to make sure it is both a valid command and does not contain any invalid characters. The Status Server will only process requests which contain URL encoded 7 bit ASCII printable characters terminated with a newline (CR/LF or LF). If a non-conforming request is received, it will be rejected with a ``syntax error'' response. In the Status Server encoding scheme, only printable characters with the exception of some special characters can be sent unencoded. Figure 2 shows the characters which must be explicitly encoded prior to being received by the Status Server.

**Figure 2:** Characters Which must be URL Encoded
$\begin{figure} \centering\begin{tabular}{\vert l\vert c\vert p{8cm}\vert} \hline... ...y issues via an interactive telnet session.\\ \hline \end{tabular}\end{figure}$

URL encoding of a character consists of a ``%'' symbol, followed by the two-digit hexadecimal representation (case-insensitive) of the character value. For example, a tab character would be encoded as ``%09''.

Since the Status Server does not perform any encoding or decoding functionality, functions will be available in the Client API to perform encoding and decoding of Strings from an 8 bit character format to URL encoded format. Clients which decide to access the Status Server via a telnet session or custom socket implementation, must be aware of the URL encoding requirements of the Status Server and perform the necessary encoding.

It is important to note that any encoding schemes used to encapsulate data are completely hidden from clients using the Client API. A client using the Client API does not need to call any encoding or decoding functions.

All string data stored and manipulated within the Status Server is 7 bit only.

3.1.2 Directory Structure

Objects within the Status Server are grouped together in a tree-like fashion patterned after the UNIX file system. As a result, it will be possible for a client to traverse and manipulate objects within the Status Server much like traversing a directory tree and manipulating files in a file system. Objects within the Status Server can be referenced either via a fully qualified directory path/object name combination, or a relative path-name combination. In order to manage relative path references, a current path will be maintained for each client connection. Rules to determine whether a path-name combination is expressed as an absolute path or relative path will be applied the same way they are in a UNIX file system. A visual example of the type of structure used to hold Status Server information is shown in figure 3.

**Figure 3:** Status Server Hierarchical Name-Value Pair Representation
$\begin{figure} \begin{center} {\footnotesize\begin{verbatim}...$

3.1.3 Directory and Data Object Information

Each directory and data object in the Status Server consists of a series of attributes. These attributes include:

Name - Within the Status Server the object name, in combination with its associated directory path location, must be unique. The name and directory path must consist of a string of 7 bit ASCII printable characters. In addition, the following series of characters will not be permitted in a directory path or object name (``, ', =, space).
Value - The value stored with the object. The value of an object stored in the Status Server will always be enclosed within double quotes if it is valid. If the value of the object is not valid, it will not be enclosed within double quotes. For example, the following values would be considered valid: ``data'', ``0.0'', or ``sample data''. If a value is not enclosed within double quotes, it must always be one of the following values.
1. NONEXISTENT - If a request is received by the Status Server to initiate a monitor on a data object which does exist, a data object will be created, and its value will be set to NONEXISTENT. For a client perspective, any request made to update or retrieve the value of this object will fail with an indication that the object does not exist, until the object is created with a ``touch'' command request (see section 4.1.3).
2. UNDEFINED - If a client has created an object, but has not assigned a value. This would be the initial value of an object following a ``touch'' command request (see section 4.1.3).
3. EXPIRED - If the object has not been updated within a ``lifetime'' length of time since its last update.
Comment - An entry describing what the object is.
Lifetime - Indicates the maximum amount of time this object can be considered valid. As an example, the current seeing may only be defined to be valid for an hour.

If a data object has a value of NONEXISTENT, it will be completely removed and deallocated whenever its use counts are zero. This means that a data object can not be completely removed if a client has performed a touch, monitor, or directory listing request on the object. This is a requirement to enforce pointer integrity within the Status Server.

More details regarding the attributes associated with a directory or data object can be found in the software design section (see 6.1.2).

3.1.4 Message Flows between Client and Server

In order to understand the communication between client and server, a set of message flows is included to illustrate normal operational flows and error conditions. In each flow, solid lines indicate Client API or Status Server initiated messages while dotted lines indicate low-level socket messages.

Client Connection - Figure 4 illustrates the normal sequence of messages used when a client connects to the server. In the case of a Client API connection, the Process ID (PID) and Program Name will be sent to the Status Server in a message following the initial connection. The Client API should always receive a positive response to this message. If not, this will be considered an internal error and the Client API will log debug information and exit.

Figure 4: Client Connection Message Flow
$\begin{figure} \center \epsfig {file=ss_connect_flow.eps}\end{figure}$
Client Disconnection - Figure 5 illustrates the normal sequence of messages when a telnet client disconnects from the server. It assumes that the client sent a message to disconnect from the server. It is also possible for the client to close its end of the socket connection in order to trigger a disconnect. The Client API will close the socket connection instead of sending a message to the Status Server. It will always be safe to allow a client program using the Client API to exit without explicitly triggering an ssLogoff() function call. Once the program exits, the socket should automatically be closed.

Figure 5: Client Disconnect Message Flow
$\begin{figure} \center \epsfig {file=ss_disconnect_flow.eps}\end{figure}$
Command Request - Figure 6 illustrates the normal message sequence when a client sends a request. This will be the standard request-response flow for almost all the commands with the exception of the ``getdir'', ``poll'', ``logoff'', and ``shutdown'' commands. The response from the Status Server will indicate whether the command was processed successfully and may contain data if the response is valid. If the command failed, the response will indicate the reason for the failure. It is possible for the client to receive a mailbox message indicating that objects monitored by the client have changed prior to receiving the command response. The Client API must handle this situation properly.

Figure 6: Client Command Request Message Flow
$\begin{figure} \center \epsfig {file=ss_command_flow.eps}\end{figure}$
Server Shutdown Request - Figure 7 illustrates the message sequence when a client requests a shutdown of the Status Server. Once the Status Server has saved the directory structure to disk, it will clean up its internal resources and exit. This process will cause each client connected to the Status Server to receive an indication that its socket connection to the Status Server has been closed by the server.

Figure 7: Client Shutdown Request Message Flow
$\begin{figure} \center \epsfig {file=ss_shutdown_flow.eps}\end{figure}$
Client Out-of-Sequence Request - Figure 8 illustrates a sample message sequence if a client initiates an out-of-sequence message. The client must always wait for the response to a previous message before sending a new message. For clients using the Client API, the API will take care of waiting before a new message is sent. If a client violates this protocol, the server will send a message to the client indicating that a protocol violation occurred. The client should then close the socket connection. If the client does not close the socket connection, the Status Server will close the client connection upon receiving another request.

Figure 8: Out-of-Sequence Client Request Message Flow
$\begin{figure} \center \epsfig {file=ss_error_cmd_seq_flow.eps}\end{figure}$
Server Out-of-Sequence Response - Figure 9 illustrates a sample message sequence if a client receives a response from the Status Server which it believes is out-of-sequence. On the client side, this would be considered a protocol violation by the Status Server. If the Client API encounters this situation, it will send a ``protocol error'' message to the Status Server. The Status Server will respond by logging error information to the CFHT log and closing the client connection. The Client API must be able to handle a ``mailbox'' message at almost any time, so this will not be considered a protocol violation. The exception is if the Server sends multiple ``mailbox'' messages before the client sends a ``poll'' request.

Figure 9: Out-of-Sequence Server Response Message Flow
$\begin{figure} \center \epsfig {file=ss_error_rsp_seq_flow.eps}\end{figure}$
Directory Listing Request - Figure 10 illustrates the message sequence when a client sends a valid directory listing request. The server will send the directory header followed by the set of directories and objects. Once all the directory contents have been sent, the Status Server will send an end-of-transaction (EOT) message. If the directory is empty, the directory header will be sent followed by an immediate EOT message. If the client requests a directory which does not exist, or if the command syntax is invalid, the Status Server will send a descriptive error message instead of sending the directory header. The Status Server will not accept any additional requests from the client until after the EOT message has been sent. If this situation occurs, and is detected by the Status Server, it will send a protocol error message to the client.

Figure 10: Directory Listing Request Message Flow
$\begin{figure} \center \epsfig {file=ss_ls_flow.eps}\end{figure}$
Complete Monitoring Flow - Figure 11 illustrates the complete set of messages exchanged in a typical monitoring flow. Once the Status Server receives the monitor retrieval request, it will reset its flag indicating that a mailbox has previously been sent to the client. As a result, subsequent changes to client monitored objects may trigger a new mailbox message to be sent to the client. An example of this situation is illustrated in figure 12. It is possible that the latest monitor update will be sent to the client in the current monitor retrieval already in progress. If so, when the client initiates another monitor retrieval request the Status Server may immediately return an EOT message. The Status Server will not accept any additional requests from the client until after the end-of-transaction message has been sent. If this situation occurs, and is detected by the Status Server, it will send a protocol error message to the client.

Figure 11: Typical Monitoring Message Flow
$\begin{figure} \center \epsfig {file=ss_monitor_flow.eps}\end{figure}$

Figure 12: Monitoring Message Flow with Midstream Update
$\begin{figure} \center \epsfig {file=ss_monitor_flow_update.eps}\end{figure}$

**Figure 4:** Client Connection Message Flow
$\begin{figure} \center \epsfig {file=ss_connect_flow.eps}\end{figure}$

**Figure 5:** Client Disconnect Message Flow
$\begin{figure} \center \epsfig {file=ss_disconnect_flow.eps}\end{figure}$

**Figure 6:** Client Command Request Message Flow
$\begin{figure} \center \epsfig {file=ss_command_flow.eps}\end{figure}$

**Figure 7:** Client Shutdown Request Message Flow
$\begin{figure} \center \epsfig {file=ss_shutdown_flow.eps}\end{figure}$

**Figure 8:** Out-of-Sequence Client Request Message Flow
$\begin{figure} \center \epsfig {file=ss_error_cmd_seq_flow.eps}\end{figure}$

**Figure 9:** Out-of-Sequence Server Response Message Flow
$\begin{figure} \center \epsfig {file=ss_error_rsp_seq_flow.eps}\end{figure}$

**Figure 10:** Directory Listing Request Message Flow
$\begin{figure} \center \epsfig {file=ss_ls_flow.eps}\end{figure}$

**Figure 11:** Typical Monitoring Message Flow
$\begin{figure} \center \epsfig {file=ss_monitor_flow.eps}\end{figure}$

**Figure 12:** Monitoring Message Flow with Midstream Update
$\begin{figure} \center \epsfig {file=ss_monitor_flow_update.eps}\end{figure}$

Next: 4. Command Protocol Up: Status Server Detailed Design Previous: 2. Development and Execution Contents

Tom Vermeulen
2011-01-26