# Passenger::MessageServer Class Reference
[Apache-independent support classes and function]

Simple pluggable request/response messaging server framework. More...

`#include <MessageServer.h>`

List of all members.

## Classes

class | ClientContext
| Interface for client context objects. More...
class | CommonClientContext
| A common client context, containing client-specific information used by MessageServer itself. More...
struct | DisconnectEventBroadcastGuard
| Calls clientDisconnected() on all handlers when destroyed. More...
class | Handler
| An abstract message handler class. More...

## Public Member Functions

| MessageServer (const string &socketFilename, AccountsDatabasePtr accountsDatabase)
| Creates a new MessageServer object.
void | mainLoop ()
| Starts the server main loop.
void | addHandler (HandlerPtr handler)
| Registers a new handler.
void | setLoginTimeout (unsigned long long timeout)
| Sets the maximum number of milliseconds that clients may spend on logging in.

## Protected Member Functions

void | startListening ()
| Create a server socket and set it up for listening.
AccountPtr | authenticate (FileDescriptor &client)
| Authenticate the given client and returns its account information.
void | clientHandlingMainLoop (FileDescriptor &client)
| The main function for a thread which handles a client.

## Protected Attributes

string | socketFilename
| The filename of the server socket on which this MessageServer is listening.
AccountsDatabasePtr | accountsDatabase
| An accounts database, used for authenticating clients.
vector< HandlerPtr > | handlers
| The registered message handlers.
unsigned long long | loginTimeout
| The maximum number of milliseconds that client may spend on logging in.
dynamic_thread_group | threadGroup
| The client threads.
int | serverFd
| The server socket's file descriptor.

## Detailed Description

Simple pluggable request/response messaging server framework.

MessageServer implements a server with the following properties:

- It listens on a Unix socket. Socket creation and destruction is automatically handled. The socket is world-writable because a username/password authentication scheme is used to enforce security.
- Multithreaded: 1 thread per client.
- Designed for simple request/response cycles. That is, a client sends a request, and the server may respond with arbitrary data. The server does not respond sporadically, i.e. it only responds after a request.
- Requests are discrete MessageChannel array messages, not byte streams.
- Connections are authenticated. Connecting clients must send a username and password, which are then checked against an accounts database. The associated account is known throughout the entire connection life time so that it's possible to implement authorization features.

MessageServer does not process messages by itself. Instead, one registers handlers which handle message processing. This framework allows one to seperate message handling code by function, while allowing everything to listen on the same socket and to use a common request parsing and dispatching codebase.

A username/password authentication scheme was chosen over a file permission scheme because experience has shown that the latter is inadequate. For example, the web server may consist of multiple worker processes, each running as a different user. Although ACLs can solve this problem as well, not every platform supports ACLs by default.

## Writing handlers

Handlers must inherit from MessageServer::Handler. They may implement newClient() and must implement processMessage().

When a new client is accepted, MessageServer will call newClient() on all handlers. This method accepts one argument: a common client context object. This context object contains client-specific information, such as its file descriptor. It cannot be extended to store more information, but it is passed to every handler anyway, hence the word "common" in its name. newClient() is supposed to return a handler-specific client context object for storing its own information, or a null pointer if it doesn't need to store anything.

When a client sends a request, MessageServer iterates through all handlers and calls processMessage() on each one, passing it the common client context and the handler-specific client context. processMessage() may return either true or false; true indicates that the handler processed the message, false indicates that it did not. Iteration stops at the first handler that returns true. If all handlers return false, i.e. the client sent a message that no handler recognizes, then MessageServer will close the connection with the client.

Handlers do not need to be thread-safe as long as they only operate on data in the context objects. MessageServer ensures that context objects are not shared with other threads.

## Usage example

This implements a simple ping server. Every time a "ping" request is sent, the server responds with "pong" along with the number of times it had already sent pong to the same client in the past.

       class PingHandler: public MessageServer::Handler {
       public:
           struct MyContext: public MessageServer::ClientContext {
               int count;

               MyContext() {
                   count = 0;
               }
           };

           MessageServer::ClientContextPtr newClient(MessageServer::CommonClientContext &commonContext) {
               return MessageServer::ClientContextPtr(new MyContext());
           }

           bool processMessage(MessageServer::CommonClientContext &commonContext,
                               MessageServer::ClientContextPtr &specificContext,
                               const vector<string> &args)
           {
               if (args[0] == "ping") {
                   MyContext *myContext = (MyContext *) specificContext.get();
                   commonContext.channel.write("pong", toString(specificContext->count).c_str(), NULL);
                   specificContext->count++;
                   return true;
               } else {
                   return false;
               }
           }
       };

       ...

       MessageServer server("server.sock");
       server.addHandler(MessageServer::HandlerPtr(new PingHandler()));
       server.addHandler(MessageServer::HandlerPtr(new PingHandler()));
       server.mainLoop();

## Constructor & Destructor Documentation

Passenger::MessageServer::MessageServer | ( | const string & | socketFilename,
|  | AccountsDatabasePtr | accountsDatabase |
| ) |  |  | `[inline]`

Creates a new MessageServer object.

The actual server main loop is not started until you call mainLoop().

Parameters:

  | socketFilename | The socket filename on which this MessageServer should be listening.
  | accountsDatabase | An accounts database for this server, used for authenticating clients.

Exceptions:

  | RuntimeException | Something went wrong while setting up the server socket.
  | SystemException | Something went wrong while setting up the server socket.
  | boost::thread_interrupted |

## Member Function Documentation

void Passenger::MessageServer::addHandler | ( | HandlerPtr | handler | ) | `[inline]`

Registers a new handler.

Precondition:
  The main loop isn't running.

AccountPtr Passenger::MessageServer::authenticate | ( | FileDescriptor & | client | ) | `[inline, protected]`

Authenticate the given client and returns its account information.

Returns:
  A smart pointer to an Account object, or NULL if authentication failed.

void Passenger::MessageServer::mainLoop | ( |  | ) | `[inline]`

Starts the server main loop.

This method will loop forever until some other thread interrupts the calling thread, or until an exception is raised.

Exceptions:

  | SystemException | Unable to accept a new connection. If this is a non-fatal error then you may call mainLoop() again to restart the server main loop.
  | boost::thread_interrupted | The calling thread has been interrupted.

void Passenger::MessageServer::setLoginTimeout | ( | unsigned long long | timeout | ) | `[inline]`

Sets the maximum number of milliseconds that clients may spend on logging in.

Clients that take longer are disconnected.

Precondition:
  timeout != 0
  The main loop isn't running.

void Passenger::MessageServer::startListening | ( |  | ) | `[inline, protected]`

Create a server socket and set it up for listening.

This socket will be world-writable.

Exceptions:

  | RuntimeException |
  | SystemException |
  | boost::thread_interrupted |

## Member Data Documentation

AccountsDatabasePtr Passenger::MessageServer::accountsDatabase `[protected]`

An accounts database, used for authenticating clients.

vector<HandlerPtr> Passenger::MessageServer::handlers `[protected]`

The registered message handlers.

unsigned long long Passenger::MessageServer::loginTimeout `[protected]`

The maximum number of milliseconds that client may spend on logging in.

Clients that take longer are disconnected.

Invariant:
  loginTimeout != 0

int Passenger::MessageServer::serverFd `[protected]`

The server socket's file descriptor.

Invariant:
  serverFd >= 0

string Passenger::MessageServer::socketFilename `[protected]`

The filename of the server socket on which this MessageServer is listening.

dynamic_thread_group Passenger::MessageServer::threadGroup `[protected]`

The client threads.

The documentation for this class was generated from the following file:

- MessageServer.h