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:

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

The server socket's file descriptor.

Invariant:
serverFd >= 0

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:

Generated by  doxygen 1.6.2