Username Password
Bookmark and Share

WebGUI Request Cycle


The WebGUI request cycle is the path that a user request from the browser takes through WebGUI's internals. In general, the path goes from the browser to mod_proxy, to mod_perl, to a URL handler, then a content handler, then an asset, and back to mod_perl, mod_proxy, and is displayed in the user's browser.



The standard way of running WebGUI is behind a reverse proxy. Because of the large amount of code used by WebGUI, the mod_perl server takes up a significant amount of memory. Using a smaller process to handle the simpler request, such as file access, allows the system to run much faster. This isn't a required part of WebGUI, however, and can be configured by the individual system administrator.



From the reverse proxy, the requests for dynamic content (the most important part of WebGUI) are forwarded to a server using mod_perl. mod_perl is the Perl interface to Apache©, and allows complete control over how Apache handles these requests. This is where all of WebGUI's code lives and is the essential part of the system. Based on the Apache configuration directives (usually virtual host sections), a WebGUI base directory and configuration file is chosen for the request. WebGUI is registered as an Init handler, where it will set itself as a handler for other phases of Apache's request processing.


SetHandler perl-script # Tell Apache we are using perl

PerlInitHandler WebGUI # Register WebGUI for Init

PerlSetVar WebguiRoot /data/WebGUI # List the location of the WebGUI code and config

PerlSetVar WebguiConfig # List the configuration file to use



The configuration file listed is the first main area used to control WebGUI. It contains essential information such as the database to connect to, the macros to use, and the assets to make available. When developing add-ons for WebGUI, adding it to the configuration file is usually one of the steps. The WebGUI configuration file is also where you'll find the list of URL handlers to be called.


URL Handlers

URL handlers allow you to plug functionality into WebGUI that will handle all functions on a given URL or group of URL's. See the URL Handlers chapter for additional details.



The first URL handler is the PassThru handler which deals with the /extras folder, where WebGUI stores sharable static content like images and javascript files that are used throughout the system. Three other pieces of information included in the configuration file are the extras, passthrough, and uploads locations. Extras include the major javascript libraries used by WebGUI, such as YUI© and TinyMCE©. These are just static files on the filesystem, so WebGUI directs Apache© to serve them as such. Passthrough URL's are handled the same way, but don't have any particular meaning to WebGUI. These could be other areas with static files, or any other type of handler configured in Apache©. When a proxy server is in use, it would usually be configured to handle these locations to decrease the load on the server.



Uploads are another area with static files, but are managed by WebGUI. Often they are set up to be served by the proxy server; however, this places limits on them. WebGUI attaches security information to uploads, but if the handling of these files is short circuited by the proxy server anyone would be able to access them. Uploads are stored in randomly generated path names which provides some obscurity, but for truly sensitive data real permissions handling is needed. Of course, this extra handling isn't without a price. The extra handling to enforce the permissions imposes significant slowdowns.

To handle security on uploads, the ID of the group with access to the file is stored in a file named .wgaccess, which is stored in the same location as the file. Upon retrieving the group ID, WebGUI first checks if it is the Everyone group. If so, it instructs Apache to serve these files. For any other group, though, it has to find the group membership information, which means creating a WebGUI session to read the information out of the database. The session will also determine the currently logged in user, which is then compared to the group listed in the access file. From here, either the file or a forbidden error is returned to the user.



The Content URL handler is another plug-in to the URL handlers system. Content handlers are easier to write, and instead of working from specific URL's, they can come into play by cookies, URL's, form parameters, or any number of other things. The next section in this chapter talks more about the content handlers that come with WebGUI, and you can learn more about them in the Content Handlers chapter.


Content Handlers

After handling as many cases of static files as possible, a database connection is needed for any further processing, and this is where content handlers come in. The next step is to initialize a WebGUI session. Creating the session uses the database information from the configuration file and the Apache request object. From this it determines if the user has an active browser session and retrieves WebGUI's general settings.



As part of WebGUI's upgrade process, it saves a setting in the database marking the site as under maintenance. If this has been set, it will stop processing and display a maintenance screen to users. This is to prevent the code from operating on a different database structure than it was designed for, resulting in possible errors or even data corruption.



Operations are the first section where major work is done. These are used for anything in WebGUI that doesn't pertain to an Asset. They are called by the client by including op=<operation name> in the query string. The majority of operations are administrative functions, such as the User and Group management systems. The workflow and scheduler system works through operations as well, sending and receiving information from Spectre. Authentication and user profile editing is also done through operations. Operations work through a fixed list defined in the WebGUI::Operation module. This list links each operation name with the perl module that has the code for it. For example, the line:


'editGroup' => 'WebGUI::Operation::Group',


This line defines that a URL request ending with ?op=editGroup will be handled by the WebGUI::Operation::Group module. It will call the sub www_editGroup, giving the session object as the first parameter. If needed, the module will automatically be loaded. After doing whatever processing is needed, the operation can return output to the client. Alternately, it can return nothing and WebGUI will continue processing the request as if there had not been an operation.



Setup mode is another special state in which WebGUI can be. This is set when initially creating a WebGUI site. When in setup mode, the client is shown a screen allowing them to set the website's name and define the administrator account. It also includes the Site Starter, where a simple custom theme can be defined. Setup mode will automatically be turned off when this is complete.



Next is the most important processing area in WebGUI: Assets. Each asset on the site is addressed by a unique URL. WebGUI will use this URL to find and instantiate the asset. If the URL doesn't match any of the assets in the database, WebGUI will do one of two things. If the user is currently in admin mode, s/he will be prompted to create a new asset if desired. Otherwise, WebGUI continues processing, but uses the asset listed in the Admin Settings screen as the “Not Found” page.

Once it has determined that the asset exists, it checks the HTTP cache headers. These headers include the last date and time the client checked for content at a given URL. If the most recent revision of the asset is older than the date sent by the client, there is no need to re-send the same content to the client, so WebGUI returns an HTTP 304 Content Not Modified message.

At this stage, the asset has been determined and it is known that the client needs to be sent the content. WebGUI will check if an alternate entry point has been specified using the func query parameter. If a function has been specified, the www_func method will be called to generate the output. If not, or if the function is otherwise invalid, www_view will be used. This method is responsible for generating the output for the asset. If a function was specified, but didn't output anything when called, it will again fall back on the www_view method.



The asset or operation has several options for handling its output. The most common method is to use the session's output object. With this, the asset outputs content directly to the client, and then needs to return the magic value “chunked”, indicating that the output has been delivered. This allows the asset to output larger amounts of data without loading it all into memory at once. The output object will also process macros. Although specific assets use the macro API to process them earlier, macros are generally processed immediately before delivering the content to the client. If WebGUI finds the value “chunked,” it stops processing the request, as there is no more work to be done.

The next option the asset has for output is to point to a static file on the filesystem. In this case, it tells the session what file it wants to output. If WebGUI is configured to enable streaming these files, it will tell Apache the location of the file and instruct it to serve it.

The last option available for output is a redirect. Similar to a file, the asset needs to tell the WebGUI session it wants to perform a redirect. When getting to this stage, it will output the HTTP header needed to direct the client to the new URL.

If the asset hasn't specified any of these special cases, it is expected to return the full data to send to the client. That data is then sent to the client, which is the last stage of the request cycle.

Keywords: assets content handler operations setup upgrade

Search | Most Popular | Recent Changes | Wiki Home
© 2018 Plain Black Corporation | All Rights Reserved