Assignment #1 - Multi-threaded Web Proxy Server

Due by 11:59pm, Friday, September 25.

Assignment overview:
In this assignment you are asked to build a multi-threaded Web proxy server that is capable of delivering Web content on behalf of a remote Web server. When a user's browser is configured to connect via a proxy server, her browser establishes a connection to the proxy server's machine and forwards its complete request to the proxy server rather than the "real" Web server. The proxy server accepts user's HTTP requests and forwards them to their final destination - essentially it introduces an extra "hop" between the user's browser (or the client) and the Web server. There are several reasons why people want to use a proxy server instead of connecting to the remote Web server directly: 1) users want to anonymize themselves from the Web server; 2) a corporation might want to monitor or restrict employees' Web surfing; 3) a proxy can be used to locally cache data in order to reduce the amount of global traffic.

Multi-threading is not crucial to the functionality of a Web proxy server, but it is important to allow the server to process multiple simultaneous requests in parallel, a must-have feature for a practical server. This is an individual assignment, so each person should turn in his/her own. Most kinds of communication among the students are encouraged except, of course, copying other people's code.

Requirements in detail:
The proxy server acts as an HTTP server to client browsers while it acts as an HTTP client to the "real" Web server. The protocol specification for version 1.0 of HTTP is defined in RFC 1945. This is not a long document among the protocol specifications, but it may well appear so for you. For your relief, you are asked to implement a very small part of the complete protocol, which will be explained below. We do try to be as specific as possible in this assignment description in order to reduce your need to refer to the lengthy protocol specification. But you should be prepared to do so occasionally.

A full HTTP-1.0 compliant Web server supports HEAD, POST, and GET methods. Your proxy server only needs to support GET method. To serve each request, we first need to parse the request line and headers sent by the client. Since we will only support GET method, we only care about Web page name in request line. The request line for the proxy server typically looks like this:

The requested Web page name contains the Web server name www.foo.com and the requested file on that server /mumbo.html. In this case, your proxy server should make a TCP connection to Web server www.foo.com at the default port 80 and ask for file /mumbo.html by send the following request:

After sending a request to the "real" Web server, an HTTP response including the requested file will be received at the proxy server. The proxy server should then forward the content to the client. There are three parts in an HTTP response message: the status line, the response headers, and the entity body. The status line and response headers are terminated by an empty line (or an extra "\r\n"). In short, an HTTP response message may look like the following:

The status line and most of the header fields should be forwarded to the client without modification. Note that the Date and Last Modified fields are not critical and you can choose not to send them back to the client.

The server should be able to handle multiple simultaneous service requests in parallel. This means that the Web proxy server is multi-threaded. In the main thread, the server listens at a fixed port. When it receives a TCP connection request, it sets up a TCP connection socket and services the request in a separate thread. You are asked NOT to set any timeout on each connection socket. This should be the default behavior.

Program skeleton:
Here we provide a hint on what the program skeleton may look like. You are, however, not required to design your program this way.

Testing:
If you develop your program at your home computer, it is imperative to test it in school network before turn-in. Below we provide some information about how to test your program.

For testing, you can configure a Web browser to use your proxy server. Below are instructions for doing so for some old browser versions. Your current browser may require different setup. We trust that you can figure it out. For Internet Explorer 6.0, you can configure it in the following way: 1) Choose "Tools" in the Menu; 2) Click "Internet Options ..."; 3) Choose "Connections" Tab; 4) Click "LAN Settings ..."; 5) Choose "Proxy Server" and fill the server name as well as its port number. For Firefox 2.0.0.5, you can configure it in the following way: 1) Choose "Edit" in the Menu; 2) Click "Preferences"'; 3) Choose "Advanced" Tab; 4) Choose "Network" Sub-Tab; 5) Click "Settings" for Connection; 6) Click "Manual proxy configuration" and fill the server name as well as its port number. Make sure your proxy server is running and now all HTTP requests from your browser are served via the proxy server!

You can also test your server using the TCP client program you developed in assignment #0. For this example, I assume the program, called tcpclient, takes console input and sends to a server at a specific port number. It then receives server responses and prints them on the console. If your proxy server runs at port 8080 of cycle1.csug.rochester.edu, you can do

You can also try this with the Web server directly, then you will need to specify the default port number 80. For instance, you can do

Caching (extra credit work):
Caching is a desirable feature at the proxy server. With caching, the proxy server stores the return data of past requests in local storage. If the new request matches a past one, the proxy server will directly return the cached data (in local storage) without actually contacting the remote Web server. This may save wide-area network bandwidth because the proxy server is usually close to the client machines while the "real" Web servers are often far away.

When you test the caching functionality in the proxy server, keep in mind that your Web browser also has a cache. So if you request the same file twice from the same browser, the browser cache would kick in first and the second request would not even reach the proxy server. A proper way to test the proxy server caching is to have two different browsers (with different browser caches) to access the same Web page.

Turn-in:
You are asked to turn in your source files, a makefile if needed, and a README file. No matter what programming language you choose to use, your program should take a single parameter (its port number) on startup. You should also name your executable to be ProxyServer. If your program is written in Java, you should be able to launch your server using "java ProxyServer <port-number>". If your program is written in C/C++, you should be able to launch your server using "ProxyServer <port-number>".

The README file should be in plain text format. It should contain a description of your design. What is and what is not realized in your implementation. If your program requires any special compilation flag to build, you need to specify the full build command in the README file. You are strongly recommended to provide us a makefile.

We will provide an electronic turn-in facility for this assignment. The turn-in instructions will be posted on the course web site soon.

Grading guideline:

Late turn-in policy:
Late turn-ins will be accepted for up to three days, with 10% penalty for each late day. No turn-ins more than three-day late will be accepted.