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


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
\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
\centering\begin{tabular}{\vert l\vert c\vert p{8cm}\vert}
...y issues via an
interactive telnet session.\\

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

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:

  1. 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).
  2. 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.
  3. Comment - An entry describing what the object is.
  4. 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.

next up previous contents
Next: 4. Command Protocol Up: Status Server Detailed Design Previous: 2. Development and Execution   Contents
Tom Vermeulen