Generic HTTP-Enabled Application Responder (GHEAR)

Table of Contents

1. Background
2. Goals
3. How It Works
   1. GHEAR Framework
   2. Automagically included Functionality
   3. Incorporating an Application into the Framework
   4. Requesting Information
   5. Config File
4. Requirements
5. Known Bugs & Missing Features
6. Planned Future Enhancements
7. Security Considerations
8. References
9. Version History
10. Download
11. JavaDoc
12. Misc
13. Credits
14. License

Background

Often one will want to get some kind of information or status from compute-intensive or long-running processes. Sometimes, it would be useful to get this kind of information even when not at the console.

The GHEAR framework was created to solve this problem. It's a relatively simple set of Java classes that can be used to provide an HTTP-compatible information-reporting mechanism to any such process. In other words, you can get information from the process with any web browser.

Goals

• Create an Open Source framework to simply add HTTP capability to processes.
• Keep the framework small and flexible.
• Provide some additional helpful functionality (like serving up "readme" type documents).

How it Works

GHEAR Framework

The GHEAR framework comprises a multithreaded server class, and some abstract classes that are subclassed to build an HTTP-enabled application. The server class knows how to respond to HTTP requests, and wraps up responses nicely.

The classes that make up GHEAR are as follows:

• Server (Server.java) - This contains the "Main" function. It reads the Server properties file, initializes the ServiceDispatcher, sets up runtime metrics, and starts the listener socket.
• HTTPService (Server.java) - This is the handler that deals with each individual incoming HTTP request.
• ServiceDispatcher (ServiceDispatcher.java) - this is an abstract class for dispatching individual Services. Subclasses of this are responsible for reporting on all of the Services that they deploy.
• Service (Service.java) - this is an abstract class. Subclasses of this are what do the actual work. The abstract class exists to define several reporting methods that need to be implemented.
• Response (Response.java) - this is a simplistic class for containing HTTP responses.

• SampleService (SampleService.java) - a simple example of a Service.
• SampleServiceDispatcher (SampleServiceDispatcher.java) - a simple example of a ServiceDispatcher.

• ghear.conf - the configuration file. See below for settings.
• readme.html - a standard readme file.
• stdheader.html - an HTML template to pre-fix all output.
• stdfooter.html - an HTML template to post-fix all output.

Automagically included functionality

Functionality includes the ability to respond to HTTP requests on a specified port, prepend and append pre-set HTML files to all output, and

Any system built using the GHEAR framework will respond to three commands, regardless of what's implemented in the ServiceDispatcher. Specifically, these commands are:

• /readme - this will display any file in the application's directory that has the name "readme.html". If this file doesn't exist, GHEAR will return a somewhat ugly "File error" message.
• /license - this will redirect the browser to the GNU Public License page at gnu.org.
• /stats - this will show low-level system statistics, such as memory usage, time spent in initializing, etc. You can add statistics to this page using the Metrics object.

Incorporating an Application into the Framework

1. First, you need to identify the pieces. You will need one or more processes (specifically Java classes) that do some kind of work. For each of these processes, you should identify what kinds of information they will want to report.
2. Modify these classes to extend com.andthehorseyourodinon.ghear.Service.
3. Implement the methods for these classes:
   • run - this will be where most of the original code from your class gets moved.
   • getServiceName - this should return the Service's name
   • getServiceStatus - this should return a String describing the Service's status
   • getServiceReport - this should return a String based upon what report request is passed to it.
4. Now that your processes have become Services, you need to create a Service Dispatcher for them.
5. Subclass com.andthehorseyourodinon.ghear.ServiceDispatcher
6. Implement the methods for these classes:
   • initDispatcher - any initialization you need for the Dispatcher.
   • initServices - any global initialization for the Services themselves (read in a Properties file? Other config work?).
   • getName - returns the name of the ServiceDispatcher
   • getDispatchReport - this should return a String based upon what report request is passed to it. See SampleServiceDispatcher.java for more information.
7. Add any metrics information to your Services or ServiceDispatcher.
8. Update the ghear.conf file to point at your ServiceDispatcher See below for settings.
9. That's it!

 java com.andthehorseyourodeinon.ghear.Server
 

The GHEAR server will start, read its configuration file, and launch your ServiceDispatcher

Requesting information

Config File Options

The config file should be fairly self-explanatory. A sample is included below.

#
# ghear.conf
#
# The Generic HTTP-Enabled Application Responder (it's not pronounced "Fear" for nothing!)
#
# This file is for configuration of the Responder. Other config files may exist for
# specific services that are launched by the Responder.
#
#
#
# Most important configuration: the ServiceDispatch class
# This identifies the Java class of the ServiceDispatcher. Since the ServiceDispatcher
# is responsible for spawning off the appropriate Services, this is how you can
# customize the system to work for your own Services. You simply subclass ServiceDispatcher
# and have it use the services that you create (and preferably subclass from Service).
#

dispatch-service = com.andthehorseyourodeinon.ghear.SampleServiceDispatcher

#
# Port for the Responder thread to listen at.
#

port=16068

#
# Use the files "stdheader.html" and "stdfooter.html" to wrap all output?
# This allows you to create an easy, consistent look-n-feel to the server
# responses.

usestdheader = true
usestdfooter = true

#
# Create a log file for each run? If this doesn't equal "false," it'll
# write a log file.
#
write-log = false

#
# Verbosity? Do you want a chatty server, or a silent server?
#
# Set at:
# 0 for silent operation
# 1 for fatal error reporting
# 2 for all error reporting
# 3 for warnings
# 4 for informational messages
# 5 for all possible internal messages, to a boring degree.
#
verbose=5

Requirements

Known Bugs & Missing features

• Doesn't support full HTTP feature set.
• HTTP isn't standards-compliant. It claims to speak whatever version of HTTP the client speaks.

Planned Future Enhancements

• Support for wider suite of HTTP commands. Currently, the system only has a mechanism for HTTP GETs. Certainly, support for POST would be useful for getting information into running processes.
• Support for Basic Authentication. Sometimes you'll want to password protect the process information.

Security Considerations

As far as I know, there aren't any major buffer overrun-type problems with Java's I/O libraries, but if there are, this code could be at risk. A compromised Virtual Machine could be used to cause a lot of problems, so it seems prudent to run GHEAR application under accounts that have limited permissions. Don't run 'em as root!

Obviously, GHEAR yields some information about one or more running processes. If this information is sensitive, don't use GHEAR for those processes!

GHEAR's listener thread is itself vulnerable to certain denial of service attacks, and could be used to induce others (like overloading the CPU by overwhelming the VM with requests).

References

Version History

Initial release.

Download

You can grab a tarball.

You can access the current CVS tree using:

setenv CVSROOT :pserver:anonymous@www.andthehorseyourodeinon.com:/home/cvsroot

Password for anonymous access to the CVS repository is "anonymous".

JavaDoc

Right this way...

The whole bundle (including utilities, and so on) lives at http://www.andthehorseyourodeinon.com/tech/javadoc/packages.html

Misc

Q: What's with the "Fear" bit?
A: Well, in words like "enough" or "tough" the "gh" is pronounced similarly to the usual pronunciation of the letter "f." So, GHEAR should properly by pronounced "fear." Check out the source. It'll all make sense...

Credits

Initial version by Samuel Goldstein (samuelg@andthehorseyourodeinon.com)
Contributors: Karl Zilles
Latest Web Page Update: 21 May 2000

License

Join the Blue Ribbon Online Free Speech Campaign!