Simple pluggable request/response messaging server framework. More...
#include <MessageServer.h>
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. |
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.
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.
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();
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().
socketFilename | The socket filename on which this MessageServer should be listening. | |
accountsDatabase | An accounts database for this server, used for authenticating clients. |
RuntimeException | Something went wrong while setting up the server socket. | |
SystemException | Something went wrong while setting up the server socket. | |
boost::thread_interrupted |
void Passenger::MessageServer::addHandler | ( | HandlerPtr | handler | ) | [inline] |
Registers a new handler.
AccountPtr Passenger::MessageServer::authenticate | ( | FileDescriptor & | client | ) | [inline, protected] |
Authenticate the given client and returns its account information.
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.
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.
void Passenger::MessageServer::startListening | ( | ) | [inline, protected] |
Create a server socket and set it up for listening.
This socket will be world-writable.
RuntimeException | ||
SystemException | ||
boost::thread_interrupted |
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.
int Passenger::MessageServer::serverFd [protected] |
The server socket's file descriptor.
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.