request-processor-procs.tcl

The ACS Request Processor: the set of routines called upon every single HTTP request to an ACS server.

Location:
packages/acs-tcl/tcl/request-processor-procs.tcl
Created:
15 May 2000
Author:
Jon Salz <jsalz@arsdigita.com>
CVS Identification:
$Id: request-processor-procs.tcl,v 1.157 2024/10/28 16:04:31 gustafn Exp $

Procedures in this file

Detailed information

acs::root_of_host (public)

 acs::root_of_host host

Maps a hostname to the corresponding subdirectory.

Parameters:
host (required)

Testcases:
package_normalize_path, xowiki_test_cases, link_tests, slot_interactions, path_resolve

acs::root_of_host_noncached (private)

 acs::root_of_host_noncached host

Helper function for acs::root_of_host, which performs the actual work.

Parameters:
host (required)

Testcases:
No testcase defined.

ad_acs_kernel_id (public)

 ad_acs_kernel_id

Returns the package_id of the kernel.

Testcases:
auth_password_change, auth_use_email_for_login_p, auth_email_on_password_change, password_recovery_page, acs_system_information_api, link_tests

ad_acs_kernel_id_not_cached (private)

 ad_acs_kernel_id_not_cached

Returns the package_id of the kernel. (not cached)

Testcases:
No testcase defined.

ad_conn (public)

 ad_conn [ args... ]

Returns a property about the connection. See the request processor documentation for an (incomplete) list of allowable values. If option "-set" is passed as first argument, then ad_conn sets the specified property, otherwise it returns its value. If the property has not been set directly by OpenACS it will be passed on to AOLserver's/NaviServer's ns_conn If the property is not a valid option for ns_conn either then it will throw an error.

Valid options for ad_conn are: ajax_p, behind_proxy_p, behind_secure_proxy_p, bot_p, browser_id, deferred_dml, extra_url, instance_name, last_issue, mobile_p, node_id, object_id, object_type, object_url, package_id, package_key, package_url, path_info, peeraddr, recursion_count, request, sec_validated, session_id, start_clicks, subsite_id, subsite_node_id, subsite_url, system_p, token, untrusted_user_id, user_id, vhost_package_url, vhost_subsite_url, vhost_url.

See Also:

Testcases:
cookie_consent__setup

ad_host (public)

 ad_host

Returns the hostname as it was typed in the browser, provided forcehostp is set to 0.

Testcases:
package_normalize_path, xowiki_test_cases, link_tests, slot_interactions, path_resolve

ad_http_cache_control (private)

 ad_http_cache_control

This adds specific headers to the http output headers for the current request in order to prevent user agents and proxies from caching the page.

It should be called only when the method to return the data to the client is going to be ns_return. In other cases, e.g. ns_returnfile, one can assume that the returned content is not dynamic and can in fact be cached. Besides that, AOLserver implements its own handling of Last-Modified headers with ns_returnfile. Also it should be called as late as possible - shortly before ns_return, so that other code has the chance to set no_cache_control_p to 1 before it runs.

This proc can be disabled per request by calling "ad_conn -set no_http_cache_control_p 1" before this proc is reached. It will not modify any headers if this variable is set to 1.

If the acs-kernel parameter CacheControlP is set to 0 then it's fully disabled.

Author:
Tilmann Singer <tils-oacs@tils.net>

Testcases:
No testcase defined.

ad_port (private)

 ad_port

Returns the port as it was typed in the browser, provided forcehostp is set to 0.

Testcases:
No testcase defined.

ad_register_filter (public)

 ad_register_filter [ -debug debug ] [ -priority priority ] \
    [ -critical critical ] [ -description description ] kind method \
    path proc [ arg ]

Registers a filter that gets called during page serving. The filter should return one of

  • filter_ok, meaning the page serving will continue;
  • filter_break meaning the rest of the filters of this type will not be called;
  • filter_return meaning the server will close the connection and end the request processing.

Switches:
-debug (optional, defaults to "f")
If debug is set to "t", all invocations of the filter will be ns_logged.
-priority (optional, defaults to "10000")
Priority is an integer; lower numbers indicate higher priority.
-critical (optional, defaults to "f")
If a filter is critical, page viewing will abort if a filter fails.
-description (optional)
Parameters:
kind (required)
Specify preauth, postauth or trace.
method (required)
Use a method of "*" to register GET, POST, and HEAD filters.
path (required)
proc (required)
arg (optional)

Testcases:
No testcase defined.

ad_register_proc (public)

 ad_register_proc [ -sitewide ] [ -debug debug ] \
    [ -noinherit noinherit ] [ -description description ] method path \
    proc [ arg ]

Registers a procedure (see ns_register_proc for syntax). Use a method of "*" to register GET, POST, and HEAD filters. If debug is set to "t", all invocations of the procedure will be logged in the server log.

Switches:
-sitewide (optional, boolean)
specifies that the filter should be applied on a sitewide (not subsite-by-subsite basis).
-debug (optional, defaults to "f")
-noinherit (optional, defaults to "f")
-description (optional)
Parameters:
method (required)
path (required)
proc (required)
arg (optional)

Testcases:
test_ad_register_proc

ad_script_abort (public)

 ad_script_abort

Aborts the current running Tcl script, returning to the request processor. Used to stop processing after doing ad_returnredirect or other commands which have already returned output to the client. After such operations, the connection for this request is closed and no more replies can be sent to the client.

Testcases:
ad_return_exception_template, create_folder_with_page, create_workflow_with_instance, xowiki_test_cases, create_form_with_form_instance

rp_concrete_file (private)

 rp_concrete_file [ -extension_pattern extension_pattern ] path

Given a path in the filesystem, returns the file that would be served, trying all possible extensions. Returns an empty string if there's no file "$path.*" in the filesystem (even if the file $path itself does exist).

Switches:
-extension_pattern (optional, defaults to ".*")
Parameters:
path (required)

Testcases:
No testcase defined.

rp_file_can_be_public_p (private)

 rp_file_can_be_public_p path

Determines if -- absent application restrictions -- a file can be served to a client without violating simple security checks. The checks and response do not require the initialization of ad_conn or expensive permission:: calls. The proc will return page-not-found messages to the client in the case where the file must not be served, log a warning, and close the connection to the client.

Parameters:
path (required)
The file to perform the simple security checks on.
Returns:
0 (and close the connection!) if the file must not be served. 1 if the application should perform its own checks, if any.

Testcases:
No testcase defined.

rp_filter (private)

 rp_filter why

This is the first filter that runs for non-resource URLs. It sets up ad_conn and handles session security.

Parameters:
why (required)

Testcases:
No testcase defined.

rp_finish_serving_page (private)

 rp_finish_serving_page

Testcases:
No testcase defined.

rp_handle_request (private)

 rp_handle_request

Testcases:
No testcase defined.

rp_handle_tcl_request (public)

 rp_handle_tcl_request

Handles a request for a .tcl file. Sets up the stack of datasource frames, in case the page is templated.

Testcases:
No testcase defined.

rp_handler (private)

 rp_handler

The request handler, which responds to absolutely every HTTP request made to the server.

Testcases:
No testcase defined.

rp_html_directory_listing (private)

 rp_html_directory_listing dir

Generates an HTML-formatted listing of a directory. This is mostly stolen from _ns_dirlist in an AOLserver module (fastpath.tcl).

Parameters:
dir (required)

Testcases:
No testcase defined.

rp_internal_redirect (public)

 rp_internal_redirect [ -absolute_path ] path

Tell the request processor to return some other page. The path can either be relative to the current directory (e.g. "some-template") relative to the server root (e.g. "/packages/my-package/www/some-template"), or an absolute path (e.g. "/home/donb/openacs-4/templates/some-cms-template"). When there is no extension then the request processor will choose the matching file according to the extension preferences. Parameters will stay the same as in the initial request. Keep in mind that if you do an internal redirect to something other than the current directory, relative links returned to the clients browser may be broken (since the client will have the original URL). Update the ns_set obtained via ns_getform if you want to feed query variables to the redirected page.

Switches:
-absolute_path (optional, boolean)
If set the path is an absolute path within the host filesystem
Parameters:
path (required)
path to the file to serve
See Also:
  • ns_getform
  • ns_set

Testcases:
create_workflow_with_instance

rp_invoke_filter (private)

 rp_invoke_filter why filter_info

Invokes the filter described in $argv, writing an error message to the browser if it fails (unless kind is trace).

Parameters:
why (required)
filter_info (required)

Testcases:
No testcase defined.

rp_invoke_proc (private)

 rp_invoke_proc argv

Invokes a registered procedure.

Parameters:
argv (required)

Testcases:
No testcase defined.

rp_lookup_node_from_host (private)

 rp_lookup_node_from_host host

Lookup host from host_node_map.

Parameters:
host (required)
Returns:
node_id on success or empty string

Testcases:
No testcase defined.

rp_path_prefixes (private)

 rp_path_prefixes path

Returns all the prefixes of a path ordered from most to least specific.

Parameters:
path (required)

Testcases:
No testcase defined.

rp_register_extension_handler (private)

 rp_register_extension_handler extension [ args... ]

Registers a proc used to handle requests for files with a particular extension.

Parameters:
extension (required)

Testcases:
No testcase defined.

rp_registered_proc_info_compare (private)

 rp_registered_proc_info_compare info1 info2

A comparison predicate for registered procedures, returning -1, 0, or 1 depending the relative sorted order of $info1 and $info2 in the procedure list. Items with longer paths come first.

Parameters:
info1 (required)
info2 (required)

Testcases:
No testcase defined.

rp_report_error (private)

 rp_report_error [ -message message ]

Writes an error to the connection.

Switches:
-message (optional)
The message to write (pulled from $::errorInfo if none is specified).

Testcases:
No testcase defined.

rp_request_denied_filter (private)

 rp_request_denied_filter why

Deny serving the request

Parameters:
why (required)

Testcases:
No testcase defined.

rp_resources_filter (private)

 rp_resources_filter why

This filter runs on all URLs of the form /resources/*. We just ns_returnfile the file, no permissions are checked, the ad_conn structure is not initialized, etc in order to maximize throughput for resource files. There are three mapping possibilities: /resources/package-key/* maps to root/packages/package-key/www/resources/*. If that fails, we map to root/packages/acs-subsite/www/resources/* If that fails, we map to root/www/resources/* If the file doesn't exist we'll log an error and return filter_ok, which will allow packages mounted at "/resources" in a legacy site to work correctly. This is a horrible kludge which may disappear after discussion with the gang.

Parameters:
why (required)
Author:
Don Baccus <dhogaza@pacifier.com>

Testcases:
No testcase defined.

rp_serve_abstract_file (private)

 rp_serve_abstract_file [ -noredirect ] [ -nodirectory ] \
    [ -extension_pattern extension_pattern ] path

Serves up a file given the abstract path. Raises the following exceptions in the obvious cases:

  • notfound (passes back an empty value)
  • redirect (passes back the url to which it wants to redirect)
  • directory (passes back the path of the directory)
Should not be used in .vuh files or elsewhere, instead use the public function rp_internal_redirect.

Switches:
-noredirect (optional, boolean)
-nodirectory (optional, boolean)
-extension_pattern (optional, defaults to ".*")
Parameters:
path (required)
See Also:

Testcases:
No testcase defined.

rp_serve_concrete_file (public)

 rp_serve_concrete_file file

Serves a file.

Parameters:
file (required)

Testcases:
No testcase defined.

rp_serve_resource_file (private)

 rp_serve_resource_file path

Serve the resource file if kernel parameter settings allow this.

Parameters:
path (required)

Testcases:
No testcase defined.
[ show source ]