rp-design.adp
Delivered as text/html
Related Files
[ hide source ] | [ make this the default ]
File Contents
<property name="context">{/doc/acs-core-docs/ {ACS Core Documentation}} {Request Processor Design}</property> <property name="doc(title)">Request Processor Design</property> <master> <include src="/packages/acs-core-docs/lib/navheader" leftLink="rp-requirements" leftLabel="Prev" title=" Chapter 15. Kernel Documentation" rightLink="tcl-doc" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="rp-design" id="rp-design"></a>Request Processor Design</h2></div></div></div><div class="authorblurb"> <p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> </p> OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.</div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="rp-design-essentials" id="rp-design-essentials"></a>Essentials</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p><a class="xref" href="rp-requirements" title="Request Processor Requirements">OpenACS 4 Request Processor Requirements</a></p></li><li class="listitem"><p><a class="ulink" href="request-processor" target="_top">Request Processor Stages and API</a></p></li><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages/acs-tcl/tcl/request-processor-procs.tcl" target="_top">/packages/acs-tcl/tcl/request-processor-procs.tcl</a></p></li><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages/acs-tcl/tcl/request-processor-init.tcl" target="_top">/packages/acs-tcl/tcl/request-processor-init.tcl</a></p></li><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages/acs-tcl/tcl/site-nodes-procs.tcl" target="_top">/packages/acs-tcl/tcl/site-nodes-procs.tcl</a></p></li><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages/acs-tcl/tcl/site-nodes-init.tcl" target="_top">/packages/acs-tcl/tcl/site-nodes-init.tcl</a></p></li><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?package_key=acs-kernel&url=site-nodes-create.sql" target="_top">/packages/acs-kernel/sql/site-nodes-create.sql</a></p></li> </ul></div> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="rp-design-intro" id="rp-design-intro"></a>Introduction</h3></div></div></div><p>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.</p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="rp-design-related-systems" id="rp-design-related-systems"></a>Related Systems</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"><li class="listitem"><p><a class="xref" href="apm-design" title="Package Manager Design">Package Manager Design</a></p></li></ul></div> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="rp-design-terminology" id="rp-design-terminology"></a>Terminology</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p> <span class="strong"><strong>pageroot</strong></span> -- 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.</p></li><li class="listitem"><p> <span class="strong"><strong>global pageroot</strong></span> (<span class="strong"><strong>/var/lib/aolserver/<span class="emphasis"><em>servicename</em></span>/www</strong></span>) -- Files appearing under this pageroot will be served directly off the base url http://www.<span class="emphasis"><em>servicename</em></span>.com/</p></li><li class="listitem"><p> <span class="strong"><strong>package root</strong></span> (<span class="strong"><strong>/var/lib/aolserver/<span class="emphasis"><em>servicename</em></span>/packages</strong></span>) -- Each subdirectory of the package root is a package. A typical OpenACS installation will have several packages.</p></li><li class="listitem"><p> <span class="strong"><strong>package pageroot</strong></span> (<span class="strong"><strong>/var/lib/aolserver/<span class="emphasis"><em>servicename</em></span>/packages/<span class="emphasis"><em>package_key</em></span>/www</strong></span>) -- This is the pageroot for the <span class="emphasis"><em>package_key</em></span> package.</p></li><li class="listitem"><p> <span class="strong"><strong>request environment</strong></span> (<span class="strong"><strong>ad_conn</strong></span>) -- This is a global namespace containing variables associated with the current request.</p></li><li class="listitem"><p> <span class="strong"><strong>abstract URL</strong></span> -- A URL with no extension that doesn't directly correspond to a file in the filesystem.</p></li><li class="listitem"><p> <span class="strong"><strong>abstract file</strong></span> or <span class="strong"><strong>abstract path</strong></span> -- 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.</p></li><li class="listitem"><p> <span class="strong"><strong>concrete file</strong></span> or <span class="strong"><strong>concrete path</strong></span> -- A file or path that actually references something in the filesystem.</p></li> </ul></div> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="rp-design-system-overview" id="rp-design-system-overview"></a>System Overview</h3></div></div></div><p><span class="strong"><strong>Package Lookup</strong></span></p><p>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 <span class="strong"><strong>package_url</strong></span> (/offices/boston/announcements/), and the abstract (no extension info) file path (index). The request processor must be able to figure out which <span class="strong"><strong>package_id</strong></span> 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.</p><p><span class="strong"><strong>Authentication and Authorization</strong></span></p><p>Once the request processor has located both the package_id and concrete file associated with the request, authentication is performed by the <a class="ulink" href="security-design" target="_top">session</a> security system. After authentication has been performed the user is authorized to have read access for the given package by the <a class="xref" href="permissions-design" title="Permissions Design">OpenACS 4 Permissions Design</a>. If authorization succeeds then the request is served, otherwise it is aborted.</p><p><span class="strong"><strong>Concrete File Search</strong></span></p><p>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.</p><p><span class="strong"><strong>Virtual URL Handlers</strong></span></p><p>If no file is found during the concrete file search, then the request processor searches the filesystem for a <span class="strong"><strong>virtual url handler</strong></span> (<span class="strong"><strong>.vuh</strong></span>) 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 <span class="strong"><strong>path_info</strong></span> is set to the portion of the url <span class="emphasis"><em>not</em></span> 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.</p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="rp-design-site-nodes" id="rp-design-site-nodes"></a>Site Nodes</h3></div></div></div><p>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.</p><p>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.</p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="rp-design-req-env" id="rp-design-req-env"></a>Request Environment</h3></div></div></div><p>The request environment is managed by the procedure <span class="strong"><strong>ad_conn</strong></span>. 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.</p><div class="informaltable"><table class="informaltable" cellspacing="0" border="0"> <colgroup> <col class="c1"><col class="c2"> </colgroup><tbody> <tr><td colspan="2"><span class="strong"><strong>Request processor</strong></span></td></tr><tr> <td valign="top"><code class="computeroutput">[ad_conn urlv]</code></td><td valign="top">A list containing each element of the URL</td> </tr><tr> <td valign="top"><code class="computeroutput">[ad_conn url]</code></td><td valign="top">The URL associated with the request.</td> </tr><tr> <td valign="top"><code class="computeroutput">[ad_conn query]</code></td><td valign="top">The portion of the URL from the ? on (i.e. GET variables) associated with the request.</td> </tr><tr> <td valign="top"><code class="computeroutput">[ad_conn file]</code></td><td valign="top">The filepath including filename of the file being served</td> </tr><tr> <td valign="top"><code class="computeroutput">[ad_conn request]</code></td><td valign="top">The number of requests since the server was last started</td> </tr><tr> <td valign="top"><code class="computeroutput">[ad_conn start_clicks]</code></td><td valign="top">The system time when the RP starts handling the request</td> </tr><tr><td colspan="2"></td></tr><tr><td colspan="2"> <span class="strong"><strong>Session System Variables</strong></span>: set in sec_handler, check security with ad_validate_security_info</td></tr><tr> <td valign="top"><code class="computeroutput">[ad_conn session_id]</code></td><td valign="top">The unique session_id coming from the sequence <code class="computeroutput">sec_id_seq</code> </td> </tr><tr> <td valign="top"><code class="computeroutput">[ad_conn user_id]</code></td><td valign="top">User_id of a person if the person is logged in. Otherwise, it is blank</td> </tr><tr> <td valign="top"><code class="computeroutput">[ad_conn sec_validated]</code></td><td valign="top">This becomes "secure" when the connection uses SSL</td> </tr><tr><td colspan="2"></td></tr><tr><td colspan="2"><span class="strong"><strong>Database API</strong></span></td></tr><tr> <td valign="top"><code class="computeroutput">[ad_conn db,handles]</code></td><td valign="top">What are the list of handles available to AOL?</td> </tr><tr> <td valign="top"><code class="computeroutput">[ad_conn db,n_handles_used]</code></td><td valign="top">How many database handles are currently used?</td> </tr><tr> <td valign="top"><code class="computeroutput">[ad_conn db,last_used]</code></td><td valign="top">Which database handle did we use last?</td> </tr><tr> <td valign="top"><code class="computeroutput">[ad_conn db,transaction_level,$db]</code></td><td valign="top">Specifies what transaction level we are in</td> </tr><tr> <td valign="top"><code class="computeroutput">[ad_conn db,db_abort_p,$dbh]</code></td><td valign="top">Whether the transaction is aborted</td> </tr><tr><td colspan="2"></td></tr><tr><td colspan="2"><span class="strong"><strong>APM</strong></span></td></tr><tr> <td valign="top"><code class="computeroutput">[ad_conn xml_loaded_p]</code></td><td valign="top">Checks whether the XML parser is loaded so that it only gets loaded once. Set in apm_load_xml_packages</td> </tr><tr><td colspan="2"></td></tr><tr><td colspan="2"><span class="strong"><strong>Packages</strong></span></td></tr><tr> <td valign="top"><code class="computeroutput">[ad_conn package_id]</code></td><td valign="top">The package_id of the package associated with the URL.</td> </tr><tr> <td valign="top"><code class="computeroutput">[ad_conn package_url]</code></td><td valign="top">The URL on which the package is mounted.</td> </tr><tr><td colspan="2"></td></tr><tr><td colspan="2"><span class="strong"><strong>Miscellaneous</strong></span></td></tr><tr> <td valign="top"><code class="computeroutput">[ad_conn system_p]</code></td><td valign="top">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.</td> </tr><tr><td colspan="2"></td></tr><tr><td colspan="2"><span class="strong"><strong>Documentation</strong></span></td></tr><tr> <td valign="top"><code class="computeroutput">[ad_conn api_page_documentation_mode_p]</code></td><td valign="top"> </td> </tr> </tbody> </table></div> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="rp-requirements" leftLabel="Prev" leftTitle="Request Processor Requirements" rightLink="tcl-doc" rightLabel="Next" rightTitle="Documenting Tcl Files: Page Contracts and Libraries" homeLink="index" homeLabel="Home" upLink="kernel-doc" upLabel="Up">