Login | Register
My pages Projects Community openCollabNet

noodle
Project home

If you were registered and logged in, you could join this project.

Summary Noodle is a transparent HTTP Proxy
Category libraries
License Apache License
Owner(s) jon

Noodle Documentation

Introduction

Noodle is a set of 100% Pure Java classes for transparently making arbitrary changes to an HTTP request and response. You can use Noodle to create a servlet that, on every HTTP request, runs Java 'filters' that you define on the request, sends the new request off to another web server, and streams the resulting response through another set of filters. The execution path looks something like this:

The above diagram is read left to right and then right to left; it translates as the following:

The HTTP client is, e.g., a web browser. It makes a connection to the Noodle servlet through an HTTP server, just as it would make a connection to any other servlet. Its HTTP request is the client request. When the Noodle servlet is executed, it sets up some internal data and executes predefined proxy request filters. These filters have a chance to modify the HttpServletRequest headers as well as the content of the request (such as the POST data).

Once the proxy request filters have been executed, Noodle makes an HTTP connection to the HTTP server and sends the Proxy request. The HTTP server treats this as it would any other HTTP request, and returns a response (the Proxy response) consisting of a set of HTTP headers and any body data. Noodle reads the data from the proxy response in chunks, and filters it using proxy response filters, which can add to, modify, or remove any of the headers or content sent to the client through the client response.

The beauty of the Noodle system is that it is easy to implement any sort of proxy request and proxy response filters. These filters can do anything you want to munge both the header and body data as it's passed back and forth, such as executing regular expressions on body data using a Java regular expressions package.

Noodle is considered a "transparent" HTTP proxy because neither the HTTP client nor the HTTP server can know about the presence of Noodle. With the creative use of Apache's mod_rewrite it is possible to place Noodle in front of nearly any type of CGI to change the CGI's UI without without modifications to the CGI or any need to re-write links within the CGI. An example of using Noodle in this way would be to add your own look and feel to Bugzilla without needing to modify Bugzilla's source code yourself. Implementing this functionality is left as an exercise to the reader.

Please subscribe to the Noodle mailing list if you have questions or comments.

Licensing Information

Noodle is available under the Tigris.org license, which is similar to the BSD license. You can do pretty much whatever you want with this code, but please make sure to read the conditions stated in the license.

Noodle also contains a bit of utility source code from both the Apache JServ project as well as the Turbine project (it is not necessary to download either of these; the required code comes directly with Noodle). In order to create the internal HTTP connection, Noodle uses the HTTPClient code (included in the /lib directory). This replaces the poorly designed and buggy java.net.URLConnection class. We credit and thank the authors of all of those projects for the use of their source code.

Noodle was originally created by Jon S. Stevens, and suffered a major rewrite at the hands of Leonard Richardson, and again an additional rewrite of some of the functionality by Ed Korthof.

Building

To build Noodle all you need to do is "cd build; build-noodle.{sh,bat} war". That will compile the source code and create a "noodle-war" WAR directory that you can move to your tomcat/webapps/ directory and rename to "noodle".

You should use the .bat extension if you are on Win32 or the .sh extension if you are on Unix. You must have the JAVA_HOME environment variable set appropriately as well as the JSDK (Java Servlet Development Kit) 2.0 and higher in your classpath. All other packages currently required for building Noodle are included with Noodle.

The URL given in the introduction can be used to execute Noodle itself and run the NoodleTest servlet. Please look at the source code and the tech to see what is happening. It is all well documented and easy to read.


To read how to drive Noodle from a servlet, how regular URLs turn into Noodle URLs, and how to write Noodle filters, please see the Noodle Technical Manual.