Module remoteMessaging

source code

A framework for socket-based client/server persistent remote messaging sessions.

Neither the server nor the client are bi-directional.  Each is intended to either receive messages
(the server) or send messages (the client).

The server functions as the receiver; it is multi-threaded and can receive from any number of
clients simultaneously.  The message content is not limited to strings.  It is possible to send
anything that can be serialzed, including traceback objects, classes, class instances, or code
objects.  Child threads of the main thread are created as needed to handle inbound messages, and are
shut down as soon as the message is deemed to have been received in full.  The message length is
sent in the first 4 bytes of the message; in this way, the message is not deemed to be completely
received until the number of bytes received matches the payload size.  This provides robustness on
congested or noisy networks that do not provide reliable transport.

The client functions as the sender.  It is single threaded and can communicate with only 1 server.
The server's INET socket address (ip address & port number) is an argument to the client's constructor
method.

Main concepts:
    
    * The central host in a messaging session communicates with multiple remote hosts.
    * Each remote host in a messaging session communicates with only 1 central host.
    * The central host runs 1 instance of a server.
    * Each remote host runs 1 instance of a client as well as 1 instance of a server.
    * The central host runs a client instance for each remote host.

Port assignment for the server in python versions 2.5 and above is dynamically assigned by the
kernel, and will be different for each instance.  In python versions 2.4 and below, the server port
is randomly assigned a port between 45000 and 60000. It is the responsibility of the developer to
inform the app instantiating the client of the server's host/port socket address.
    
The creation of a persistent messaging session between a local and remote host is a 4-step process:

    1.) create a server on a local host.  The INET socket address (ip & port) of the server is used when
    the clients are started up on remote machines.  This server instance running on the local host
    is the 'central' server and is expected to have sessions with clients on multiple remote hosts.

    2.) create a server on the remote host.
    
    3.) create a client on the remote host, passing the socket address of the 'central' server to
    the constructor. Send a 'hello' message back to the 'central' server informing it of the socket
    address on the server running on the same machine as the client (the "remote" host from the POV
    of the "central server).

    4.) when the 'central' server running on the local host receives the 'hello' message from the
    remote host, it creates a corresponding client for the server running on the remote host, using
    the socket address of the server running on the remote machine.  Since the local host is
    expected to have messaging sessions with multiple remote hosts, the client which is associated
    with the server on the remote host is stored in a dictionary so that it may be easily accessed
    at a later time.

Communication from a remote host back to the central host is accomplished by using the remote client
to send a message back to the central server.

Communcation from the central server to a remote host is accomplished by looking up the client which
corresponds to the remote host and using that client to send messages.

The app which utilizes the server and clients are meant to implement a heartbeat scheme such that the
server periodically sends heartbeats to the clients; if the clients do not receive heartbeats within
some interval past the timeout, they shut themselves down.

The app on the remote machine should also be written so that it inspects each message sent to the
server instance running on that machine, and if it receives a 'shutdown' message, will shutdown the
client and server and exit.