- Introduction
- The Apache Request Object
- The HTTP Request Message
- The Client Request
- Accessing Client Request Headers
- Accessing HTML Form Fields
- Reading POSTed Data Manually
- Manipulating Cookies
- Handling File Uploads
- Setting Server Response Headers
- Controlling Caching Behavior
- Sending Server Response Headers
- Setting the Response Status
- Setting Error Headers
- Manipulating Headers with Multiple Like Fields
- Using Subrequests
- Setting Headers for Subrequests
- Short-Circuiting Subrequests
- Getting or Setting the Request Method
- Accessing the Request Object from XS
This chapter is from the book
This chapter is from the book
This chapter is from the book
The HTTP Request Message
You want to see the entire request.
Technique
Use the $r->as_string() method to view the message, including the client request and server response headers.
sub handler {
my $r = shift;
print STDERR $r->as_string;
return OK;
}
Comments
If you print out the results of $r->as_string() after Apache has finished sending the response (such as from a PerlCleanupHandler), you should see something similar to
GET /index.html HTTP/1.0 Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png, */* Accept-Charset: iso-8859-1,*,utf-8 Accept-Encoding: gzip Accept-Language: en Connection: Keep-Alive Host: http://www.example.com Pragma: no-cache User-Agent: Mozilla/4.73 (Windows NT 5.0; U) HTTP/1.0 200 OK Content-Location: index.html.en Vary: negotiate TCN: choice Last-Modified: Fri, 19 Jan 2001 19:39:47 GMT ETag: "4d52-51e-3a689803;3aedadb0" Accept-Ranges: bytes Content-Length: 1310 Keep-Alive: timeout=15, max=100 Connection: Keep-Alive Content-Type: text/html Content-Language: en Content-Location: index.html.en
This represents both the HTTP Request message and the HTTP Response message (without the message bodies) as defined by the HTTP protocol. You can find the entire protocol at http://www.w3.org/Protocols/rfc2616/rfc2616.html, but it doesn't exactly make for interesting bedtime reading. From a mod_perl programmer's point of view, the important things to understand (and understand well) about the protocol are the concepts of the HTTP message and client-request/server-response cycle.
The mechanism that drives the Web we interact with every day is incredibly different from the typical client-server environment that may be familiar programming territory. If you are already doing CGI programming, then much of this is not terribly new, but it is worth taking the time to understand the mechanics of it.
The HTTP request cycle consists of transmitting a series of HTTP messages back and forth between the user agent and server. All HTTP messages consist of an initial identifying line, followed by message headers, and ending with the message contents. The important concept to grasp is that a request cycle consists of a single iteration of each of these parts—the HTTP protocol is itself "stateless," and does nothing but describe the mechanism for the retrieval of a single resource.
Table 3.1 illustrates the methods used to access each of the parts of the HTTP message from the Apache request object.
Table 3.1 Accessing the HTTP Message
|
Method Name |
Description |
|
the_request() |
Provides access to the Request-Line of the client request. For example, GET /index.html HTTP/1.0 in the preceding output. |
|
headers_in() |
Provides access to the incoming headers from the client request. |
|
content() |
Returns the message body of the client request, such as POSTed HTML form data. |
|
status_line() |
Provides access to the Status-Line of the client request. For example, HTTP/1.0 200 OK in the preceding output. |
|
headers_out() |
Provides access to the server response headers. |
|
print() |
Generates the message body of the server response. |
Although all Web programmers are interested in delivering content, mod_perl programmers usually take a special interest in the request headers, which describe aspects of how the content is delivered and received. Headers are used to communicate things such as whether the user agent can interpret compressed content, what language preference the end user has, and even whether content is considered stale and should be updated. The HTTP/1.1 protocol defines four types of headers:
Request Headers. Describe aspects of the incoming client request
Response Headers. Describe aspects of the server response
Entity Headers. Describe the contents of the transferred entity (usually the server resource)
General Headers. Multipurpose headers that can appear in either a request or response
Each of these headers has its own section in RFC 2616, with the exception of headers related to cookies, which you can find in RFC 2109 (http://www.w3.org/Protocols/rfc2109/rfc2109.txt). The recipes contained within the remainder of this book will often make reference to specific headers and use them to control how content is generated, so being familiar with them (or at least knowing where to look) is good.
Other than as an introduction to the basics of the HTTP protocol, and perhaps as a debugging tool, the as_string() method is not terribly useful in and of itself. The other methods described in this recipe that allow you to interact with the various parts of the HTTP message directly are much more interesting, and are discussed in more detail in the following recipes.