This document is just a quick, high level overview of the design, classes, and code for PokerFace. If you are looking for specifics of a paticular class or method, please consult it's Javadoc.

PokerFace only deals with http/https protocols, and handles everything asynchrounously. Because of that this document will drop the HttpAsync prefixes and suffixes commonly used in org.apache.http.*.

With all the request / response / consumer / producer combinations, it is important to keep these specific meanings straight in your head:

Request-Consumer: Consumes an HttpRequest from a client / browser.

Request-Producer: Issues an HttpRequest to a remote system.

Response-Consumer: Reads the response back from a remote system.

Response-Producer: Sends an HttpResponse back to a client / browser.

TargetDescriptor (aka Target)

A TargetDescriptor is basically an org.apache.http.HttpHost descrbing a remote system which PokerFace proxys to, and which keeps track of some meta-info that allows us to optionally transform the request url from the client into a suitable request to the remote Target.

RequestHandler

The RequestHandler is a singleton dispatcher that analyzes all new request from the browser (which may not yet be fully received yet). Because this object is the brains behind PokerFace, we will discuss it in more detail:

The RequestHandler.processRequest method is called by the framework, and always returns a subclass instance of AbsClientRequestConsumer (see below).

The flow of the processRequest method is as follows:

  1. Checks to see if there is a static file matching the request uri.
  2. If there is a matching static file, a RequestForFileConsumer is returned.
  3. Checks to see if any script endpoint matches the browser request.
    • Please see the ‘inspectRequest()’ method in the EndpointTemplate.js file for further documentation.
  4. If the script wished to handle the request, a RequestForScriptConsumer is returned.
  5. The request (possibly modified by the script) is matched against configured proxy TargetDescriptors
    • If a configured TargetDescriptor is not found and the redirect request came from the script endpoint, then IF the dynamicHostMap option is set to true, a proxy TargetDescriptor will be created on the fly.
  6. The processRequest method then returns a RequestForTargetConsumer to consume the request.
    • NOTE: The Target itself may be null at this point, and if so the RequestForTargetConsumer.getResult method will return a ResponseProducer instance that will send a 404 response back to the client.

NOTE: All Request-Consumer's have a getResult method that returns a ResponseProducer instance which will in turn produces the response back to the client. The framework will pass this ResponseProducer to the RequestHandler.handle method.

Building

On a Mac:

export JAVA_HOME="`/usr/libexec/java_home -v '1.8*'`"
mvn clean package site