# Overview

This package provides a means for listening in one an HTTP connection and recieving commands after being authenticated. The primary use case is communication between Javascript running in a browser from the Lime Wire Store web site and the Lime Wire Client. In order to do this the core component, called the {@link Dispatcher}.will first authenticate who ever is talking on this connection, and then pass along the remaining commands. To create a {@link Dispatcher} one would call the following method:

> {@link LWSDispatcherFactory.createInstance(SenderOfMessagesToServer, ReceivesCommandsFromDispatcher)}

In this instance, the {@link SenderOfMessagesToServer} would have to be able to encode a url and send it to a remote server; the {@link ReceivesCommandsFromDispatcher} would do some action when a command was receives on the HTTP connection.

{@link Dispatcher} is an instance of {@link org.limewire.http.AsyncHttpRequestHandler} so can listen on the local HTTP acceptor. So a typical use of this package would be the following

>     SenderOfMessagesToServer s = new SenderOfMessagesToServer() {
>     	public String sendMessageToServer(String msg, Map args) throws IOException {
>     		// send the message, msg, and arguments args to a remote server
>     		// ...
>     		// return the result
>     	}
>     	ReceivesCommandsFromDispatcher r = new ReceivesCommandsFromDispatcher() {

>     	  private final List connectionListeners = new ArrayList();
>         private boolean isConnected;

>      			public String receiveCommand(String cmd, Map args) {
>      				// take some action
>      			}

>         public final void setConnected(boolean isConnected) {
>             this.isConnected = isConnected;
>             connectionChanged(this.isConnected);
>             if (!connectionListeners.isEmpty()) {
>                 for (ConnectionListener lis : connectionListeners) {
>                     lis.connectionChanged(isConnected);
>                 }
>             }
>         }

>         public final boolean addConnectionListener(ConnectionListener lis) {
>             return connectionListeners.contains(lis) ? false : connectionListeners.add(lis);
>         }

>         public final boolean removeConnectionListener(ConnectionListener lis) {
>             return !connectionListeners.contains(lis) ? false : connectionListeners.remove(lis);
>         }
>     };
>     Dispatcher d = LWSDispatcherFactory.createInstance(s,r);

>     // now attach d to the local HTTP connection using the 'registerHandler' command

The class {@link AbstractReceivesCommandsFromDispatcher} abstracts away the management of the {@link ConnectionListener}s. Next is the authentication scheme used in this package.

## Authentication

In order to do this securely (i.e. make sure the javascript sending messages is actually from `limewire.com` and not the ever-evil `pelzer.com`), we need a scheme to authenticate the the javascript, and in English it is:

- the javascript initiates a session with the local server
- the local server generates a private- and public-key and sends these plus its IP address to the remote server and the public key to the javascript
- the javascript send its IP address and this public key to the remote server, and they match those sent from the local server, the remote server sends back the private key
- this private key is then used to authenticate the javascript with the local server

More formally (but just barely) this scheme consists of the following participants:

- C: the javascript code
- L: the local running server running on `localhost`
- R: the remote server running on `limewire.com`

and there are three pieces of data:

- p: public key
- r: private key
- i: IP address

and the scheme is:

- C sends a start request to L
- L generates p and r and sends ( p, r, iL ) to R and sends p to C
- C sends ( p', iC ) to R and if p' = p and iC = iL then R sends r to C
- C sends r to L for authentication and then begins communication

## Lifecycle of the local server

The life cycle of the local server can be represented using an FSA such as the following: