Writing Apache Modules with Perl & C - Softcover

Stein, Lincoln

Softcover

ISBN 10: 156592567X ISBN 13: 9781565925670

Publisher: O′Reilly, 1999

Synopsis

Apache is the most popular web server on the Internet because it is free, reliable, and extensible. The availability of the source code and the modular design of Apache makes it possible to extend web server functionality through the Apache API.For the most part, however, the Apache API has only been available to C programmers, and requires rebuilding the Apache server from source. mod_perl, the popular Apache module used primarily for enhanced CGI performance, changed all that by making the Apache API available to Perl programmers. With mod_perl, it becomes simple to develop Apache modules with Perl and install them without having to rebuild the web server.Writing Apache Modules with Perl and C shows how to extend web server capabilities regardless of whether the programming language is Perl or C. The book explains the design of Apache, mod_perl, and the Apache API. It then demonstrates how to use them to perform for tasks like the following:

• Rewriting CGI scripts as Apache modules to vastly improve performance
• Server-side filtering of HTML documents, to embed special markup or code (much like SSI)
• Enhancing server log functionality
• Converting file formats on the fly
• Implementing dynamic navigation bars
• Incorporating database access into CGI scripts
• Customizing access control and authorization to block robots or to use an external database for passwords

The authors are Lincoln Stein and Doug MacEachern. Lincoln is the successful author of How to Set Up and Maintain a World Wide web Site and the developer of the widely used Perl CGI.pm module. Doug is a consultant and the creator of the innovative mod_perl Apache module.

About this title

About the Author

Doug MacEachern has been addicted to Perl and web servers since early 1994 when he was introduced to Plexus as a student employee at the University of Arizona. Soon after returning to his home town of Boston, Massachusetts, and entering the "real world," he discovered the Apache web server, and since early 1996, he has been gluing Perl into all its nooks and crannies. His day job has consisted of integrating various other technologies with the Web, including DCE, Kerberos, and GSSAPI, but Perl has been the only one he cannot let go of. Doug has continued as a developer disguised as a consultant since the start of 1998, spending most of his time between Auckland, New Zealand, and San Francisco, California, with time at home in Boston during the warmer months. Doug likes to spend his time away from software--far, far away, sailing on the ocean, diving below it, or simply looking at it from a warm, sandy beach where technology doesn't go much beyond thatched huts and blenders.

Lincoln Stein is an assistant investigator at Cold Spring Harbor Laboratory, where he develops databases and user interfaces for the Human Genome Project using the Apache server and its module API. He is the author of several books about programming for the Web, including The Official Guide to CGI.pm, How to Set Up and Maintain a Web Site, and Web Security: A Step-by-Step Reference Guide.

Excerpt. © Reprinted by permission. All rights reserved.

Chapter 4 - Content Handlers

In this chapter:
Content Handlers as File Processors
Virtual Documents
Redirection
Processing Input
Apache::Registry
Handling Errors
Chaining Content Handlers
Method Handlers

This chapter is about writing content handlers for the Apache response phase, when the contents of the page are actually produced. In this chapter you'll learn how to produce dynamic pages from thin air, how to modify real documents on the fly to produce effects like server-side includes, and how Apache interacts with the MIME-typing system to select which handler to invoke.

Starting with this chapter we shift to using the Apache Perl API exclusively for code examples and function prototypes. The Perl API covers the majority of what C programmers need to use the C-language API. What's missing are various memory management functions that are essential to C programmers but irrelevant in Perl. If you are a C programmer, just have patience and the missing pieces will be filled in eventually. In the meantime, follow along with the Perl examples and enjoy yourself. Maybe you'll even become a convert.

Content Handlers as File Processors
Early web servers were designed as engines for transmitting physical files from the host machine to the browser. Even though Apache does much more, the file-oriented legacy still remains. Files can be sent to the browser unmodified or passed through content handlers to transform them in various ways before sending them on to the browser. Even though many of the documents that you produce with modules have no corresponding physical files, some parts of Apache still behave as if they did.

When Apache receives a request, the URI is passed through any URI translation handlers that may be installed (see Chapter 7, Other Request Phases, for information on how to roll your own), transforming it into a file path. The mod_alias translation handler (compiled in by default) will first process any Alias, ScriptAlias, Redirect, or other mod_alias directives. If none applies, the http_core default translator will simply prepend the DocumentRoot directory to the beginning of the URI.

Next, Apache attempts to divide the file path into two parts: a "filename" part which usually (but not always) corresponds to a physical file on the host's filesystem, and an "additional path information" part corresponding to additional stuff that follows the filename. Apache divides the path using a very simple-minded algorithm. It steps through the path components from left to right until it finds something that doesn't correspond to a directory on the host machine. The part of the path up to and including this component becomes the filename, and everything that's left over becomes the additional path information.

Consider a site with a document root of /home/www that has just received a request for URI /abc/def/ghi. The way Apache splits the file path into filename and path information parts depends on what directories it finds in the document root:

Note that the presence of any actual files in the path is irrelevant to this process. The division between the filename and the path information depends only on what directories are present.

Once Apache has decided where the file is in the path, it determines what MIME type it might be. This is again one of the places where you can intervene to alter the process with a custom type handler. The default type handler (mod_mime) just compares the filename's extension to a table of MIME types. If there's a match, this becomes the MIME type. If no match is found, then the MIME type is undefined. Again, note that this mapping from filename to MIME type occurs even when there's no actual file there.

There are two special cases. If the last component of the filename happens to be a physical directory, then Apache internally assigns it a "magic" MIME type, defined by the DIR_MAGIC_TYPE constant as httpd/unix-directory. This is used by the directory module to generate automatic directory listings. The second special case occurs when you have the optional mod_mime_magic module installed and the file actually exists. In this case Apache will peek at the first few bytes of the file's contents to determine what type of file it might be. Chapter 7 shows you how to write your own MIME type checker handlers to implement more sophisticated MIME type determination schemes.

After Apache has determined the name and type of the file referenced by the URI, it decides what to do about it. One way is to use information hard-wired into the module's static data structures. The module's handler_rec table, which we describe in detail in Chapter 10, C API Reference Guide, Part I, declares the module's willingness to handle one or more magic MIME types and associates a content handler with each one. For example, the mod_cgi module associates MIME type application/x-httpd-cgi with its cgi_handler( ) handler subroutine. When Apache detects that a filename is of type application/x-httpd-cgi it invokes cgi_handler( ) and passes it information about the file. A module can also declare its desire to handle an ordinary MIME type, such as video/quicktime, or even a wildcard type, such as video/*. In this case, all requests for URIs with matching MIME types will be passed through the module's content handler unless some other module registers a more specific type.

Edition details

• Publisher: O′Reilly
• Publication date: 1999
• ISBN 10: 156592567X
• ISBN 13: 9781565925670
• Binding: Paperback
• Language: English
• Number of pages: 750