Request Processor Design

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Essentials

Introduction

The request processor is the set of procs that responds to every HTTP request made to the OpenACS. The request processor must authenticate the connecting user, and make sure that he is authorized to perform the given request. If these steps succeed, then the request processor must locate the file that is associated with the specified URL, and serve the content it provides to the browser.

Related Systems

Package Manager Design

Terminology

pageroot -- Any directory that contains scripts and/or static files intended to be served in response to HTTP requests. A typical OpenACS installation is required to serve files from multiple pageroots.
global pageroot (/var/lib/aolserver/servicename/www) -- Files appearing under this pageroot will be served directly off the base url http://www.servicename.com/
package root (/var/lib/aolserver/servicename/packages) -- Each subdirectory of the package root is a package. A typical OpenACS installation will have several packages.
package pageroot (/var/lib/aolserver/servicename/packages/package_key/www) -- This is the pageroot for the package_key package.
request environment (ad_conn) -- This is a global namespace containing variables associated with the current request.
abstract URL -- A URL with no extension that doesn't directly correspond to a file in the filesystem.
abstract file or abstract path -- A URL that has been translated into a filesystem path (probably by prepending the appropriate pageroot), but still doesn't have any extension and so does not directly correspond to a file in the filesystem.
concrete file or concrete path -- A file or path that actually references something in the filesystem.

System Overview

Package Lookup

One of the first things the request processor must do is to determine which package instance a given request references, and based on this information, which pageroot to use when searching for a file to serve. During this process the request processor divides the URL into two pieces. The first portion identifies the package instance. The rest identifies the path into the package pageroot. For example if the news package is mounted on /offices/boston/announcements/, then a request for /offices/boston/announcements/index would be split into the package_url (/offices/boston/announcements/), and the abstract (no extension info) file path (index). The request processor must be able to figure out which package_id is associated with a given package_url, and package mountings must be persistent across server restarts and users must be able to manipulate the mountings on a live site, therefore, this mapping is stored in the database.

Authentication and Authorization

Once the request processor has located both the package_id and concrete file associated with the request, authentication is performed by the session security system. After authentication has been performed the user is authorized to have read access for the given package by the OpenACS 4 Permissions Design. If authorization succeeds then the request is served, otherwise it is aborted.

Concrete File Search

To actually serve a file, the request processor generates an ordered list of abstract paths and searches each path for a concrete file. The first path searched is composed of the package pageroot with the extra portion of the URL appended. The second abstract path consists of the global pageroot with the full URL appended. This means that if an instance of the news package is mounted on /offices/boston/announcements/, then any requests that are not matched by something in the news package pageroot could be matched by something under the global pageroot in the /offices/boston/announcements/ directory. Files take precedence over directory listings, so an index file in the global pageroot will be served instead of a directory listing in the package pageroot, even though the global pageroot is searched later. If a file is found at any of the searched locations then it is served.

Virtual URL Handlers

If no file is found during the concrete file search, then the request processor searches the filesystem for a virtual url handler (.vuh) file. This file contains normal Tcl code, and is in fact handled by the same extension handling procedure that handles .tcl files. The only way this file is treated differently is in how the request processor searches for it. When a lookup fails, the request processor generates each valid prefix of all the abstract paths considered in the concrete file search, and searches these prefixes in order from most specific to least specific for a matching .vuh file. If a file is found then the ad_conn variable path_info is set to the portion of the url not matched by the .vuh script, and the script is sourced. This facility is intended to replace the concept of registered procs, since no special distinction is required between sitewide procs and package specific procs when using this facility. It is also much less prone to overlap and confusion than the use of registered procs, especially in an environment with many packages installed.

Site Nodes

The request processor manages the mappings from URL patterns to package instances with the site_nodes data model. Every row in the site_nodes table represents a fully qualified URL. A package can be mounted on any node in this data model. When the request processor performs a URL lookup, it determines which node matches the longest possible prefix of the request URI. In order to make this lookup operation as fast as possible, the rows in the site_nodes table are pulled out of the database at server startup, and stored in memory.

The memory structure used to store the site_nodes mapping is a hash table that maps from the fully qualified URL of the node, to the package_id and package_key of the package instance mounted on the node. A lookup is performed by starting with the full request URI and successively stripping off the rightmost path components until a match is reached. This way the time required to lookup a URL is proportional to the length of the URL, not to the number of entries in the mapping.

Request Environment

The request environment is managed by the procedure ad_conn. Variables can be set and retrieved through use of the ad_conn procedure. The following variables are available for public use. If the ad_conn procedure doesn't recognize a variable being passed to it for a lookup, it tries to get a value using ns_conn. This guarantees that ad_conn subsumes the functionality of ns_conn.

Request processor
`[ad_conn urlv]`	A list containing each element of the URL
`[ad_conn url]`	The URL associated with the request.
`[ad_conn query]`	The portion of the URL from the ? on (i.e. GET variables) associated with the request.
`[ad_conn file]`	The filepath including filename of the file being served
`[ad_conn request]`	The number of requests since the server was last started
`[ad_conn start_clicks]`	The system time when the RP starts handling the request

Session System Variables: set in sec_handler, check security with ad_validate_security_info
`[ad_conn session_id]`	The unique session_id coming from the sequence `sec_id_seq`
`[ad_conn user_id]`	User_id of a person if the person is logged in. Otherwise, it is blank
`[ad_conn sec_validated]`	This becomes "secure" when the connection uses SSL

Database API
`[ad_conn db,handles]`	What are the list of handles available to AOL?
`[ad_conn db,n_handles_used]`	How many database handles are currently used?
`[ad_conn db,last_used]`	Which database handle did we use last?
`[ad_conn db,transaction_level,$db]`	Specifies what transaction level we are in
`[ad_conn db,db_abort_p,$dbh]`	Whether the transaction is aborted

APM
`[ad_conn xml_loaded_p]`	Checks whether the XML parser is loaded so that it only gets loaded once. Set in apm_load_xml_packages

Packages
`[ad_conn package_id]`	The package_id of the package associated with the URL.
`[ad_conn package_url]`	The URL on which the package is mounted.

Miscellaneous
`[ad_conn system_p]`	If true then the request has been made to one of the special directories specified in the config file (somewhere), and no authentication or authorization has been performed.

Documentation
`[ad_conn api_page_documentation_mode_p]`