- Publicity: Public Only All
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.153.2.66 2024/08/28 06:32:37 gustafn Exp $
Procedures in this file
- acs::root_of_host (public)
- acs::root_of_host_noncached (private)
- ad_acs_kernel_id (public)
- ad_acs_kernel_id_not_cached (private)
- ad_conn (public)
- ad_host (public)
- ad_http_cache_control (private)
- ad_port (private)
- ad_register_filter (public)
- ad_register_proc (public)
- ad_script_abort (public)
- root_of_host (public, deprecated)
- rp_concrete_file (private)
- rp_file_can_be_public_p (private)
- rp_filter (private)
- rp_finish_serving_page (private)
- rp_form_put (public, deprecated)
- rp_form_update (public, deprecated)
- rp_getform (public, deprecated)
- rp_handle_request (private)
- rp_handle_tcl_request (public)
- rp_handler (private)
- rp_html_directory_listing (private)
- rp_internal_redirect (public)
- rp_invoke_filter (private)
- rp_invoke_proc (private)
- rp_lookup_node_from_host (private)
- rp_path_prefixes (private)
- rp_register_extension_handler (private)
- rp_registered_proc_info_compare (private)
- rp_report_error (private)
- rp_request_denied_filter (private)
- rp_resources_filter (private)
- rp_serve_abstract_file (private)
- rp_serve_concrete_file (public)
- rp_serve_resource_file (private)
Detailed information
acs::root_of_host (public)
acs::root_of_host host
Maps a hostname to the corresponding subdirectory.
- Parameters:
- host
- Partial Call Graph (max 5 caller/called nodes):
- 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
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
ad_acs_kernel_id (public)
ad_acs_kernel_id
Returns the package_id of the kernel.
- Partial Call Graph (max 5 caller/called nodes):
- 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)
- Partial Call Graph (max 5 caller/called nodes):
- 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 forns_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:
- Partial Call Graph (max 5 caller/called nodes):
- 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.
- Partial Call Graph (max 5 caller/called nodes):
- 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>
- Partial Call Graph (max 5 caller/called nodes):
- 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.
- Partial Call Graph (max 5 caller/called nodes):
- 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
(defaults to"f"
) (optional)- If debug is set to "t", all invocations of the filter will be ns_logged.
- -priority
(defaults to"10000"
) (optional)- Priority is an integer; lower numbers indicate higher priority.
- -critical
(defaults to"f"
) (optional)- If a filter is critical, page viewing will abort if a filter fails.
- -description
(optional)- Parameters:
- kind - Specify preauth, postauth or trace.
method - Use a method of "*" to register GET, POST, and HEAD filters.
path
proc
arg (optional)
- Partial Call Graph (max 5 caller/called nodes):
- 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
(boolean) (optional)- specifies that the filter should be applied on a sitewide (not subsite-by-subsite basis).
- -debug
(defaults to"f"
) (optional)- -noinherit
(defaults to"f"
) (optional)- -description
(optional)- Parameters:
- method
path
proc
arg (optional)
- Partial Call Graph (max 5 caller/called nodes):
- 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.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- ad_return_exception_template, create_folder_with_page, create_workflow_with_instance, xowiki_test_cases, create_form_with_form_instance
root_of_host (public, deprecated)
root_of_host host
Deprecated. Invoking this procedure generates a warning.
Maps a hostname to the corresponding subdirectory. DEPRECATED: this proc does not comply with OpenACS naming convention.
- Parameters:
- host
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
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
(defaults to".*"
) (optional)- Parameters:
- path
- Partial Call Graph (max 5 caller/called nodes):
- 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 - 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.
- Partial Call Graph (max 5 caller/called nodes):
- 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
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
rp_finish_serving_page (private)
rp_finish_serving_page
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
rp_form_put (public, deprecated)
rp_form_put name value
Deprecated. Invoking this procedure generates a warning.
This proc adds a query variable to AOLserver's internal ns_getform form, so that it'll be picked up by ad_page_contract and other procs that look at the query variables or form supplied. This is useful when you do an rp_internal_redirect to a new page, and you want to feed that page with certain query variables. Note that the variable will just be appended to the form ns_set which may not be what you want, if it exists already you will now have two entries in the ns_set which may cause ad_page_contract to break. Also, only simple variables may be added, not arrays. DEPRECATED: this proc is a trivial wrapper over NaviServer functionalities. One should use the native api directly.
- Parameters:
- name
value
- Returns:
- the form ns_set, in case you're interested. Mostly you will want to discard the result.
- Author:
- Lars Pind <lars@pinds.com>
- Created:
- August 20, 2002
- See Also:
- ns_getform
- ns_set
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
rp_form_update (public, deprecated)
rp_form_update name value
Deprecated. Invoking this procedure generates a warning.
Identical to rp_form_put, but uses ns_set update instead. DEPRECATED: this proc is a trivial wrapper over NaviServer functionalities. One should use the native api directly.
- Parameters:
- name
value
- Returns:
- the form ns_set, in case you're interested. Mostly you will want to discard the result.
- See Also:
- ns_getform
- ns_set
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
rp_getform (public, deprecated)
rp_getform
Deprecated. Invoking this procedure generates a warning.
This proc is a simple wrapper around AOLserver's standard ns_getform proc, that will create the form if it doesn't exist, so that you can then add values to that form. This is useful in conjunction with rp_internal_redirect to redirect to a different page with certain query variables set. DEPRECATED: modern ns_getform from NaviServer will never return the empty string, assuming that we are in a connection. When we are not in a connection, it makes little sense that we set request variables.
- Returns:
- the form ns_set, just like ns_getform, except it will always be nonempty.
- Author:
- Lars Pind <lars@pinds.com>
- Created:
- August 20, 2002
- See Also:
- ns_getform
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
rp_handle_request (private)
rp_handle_request
- Partial Call Graph (max 5 caller/called nodes):
- 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.
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
rp_handler (private)
rp_handler
The request handler, which responds to absolutely every HTTP request made to the server.
- Partial Call Graph (max 5 caller/called nodes):
- 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
- Partial Call Graph (max 5 caller/called nodes):
- 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
(boolean) (optional)- If set the path is an absolute path within the host filesystem
- Parameters:
- path - path to the file to serve
- See Also:
- ns_getform
- ns_set
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- create_workflow_with_instance
rp_invoke_filter (private)
rp_invoke_filter conn filter_info why
Invokes the filter described in $argv, writing an error message to the browser if it fails (unless kind is
trace
).
- Parameters:
- conn
filter_info
why
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
rp_invoke_proc (private)
rp_invoke_proc conn argv
Invokes a registered procedure.
- Parameters:
- conn
argv
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
rp_lookup_node_from_host (private)
rp_lookup_node_from_host host
Lookup host from host_node_map.
- Parameters:
- host
- Returns:
- node_id on success or empty string
- Partial Call Graph (max 5 caller/called nodes):
- 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
- Partial Call Graph (max 5 caller/called nodes):
- 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
- Partial Call Graph (max 5 caller/called nodes):
- 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
info2
- Partial Call Graph (max 5 caller/called nodes):
- 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).- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
rp_request_denied_filter (private)
rp_request_denied_filter why
Deny serving the request
- Parameters:
- why
- Partial Call Graph (max 5 caller/called nodes):
- 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
- Author:
- Don Baccus <dhogaza@pacifier.com>
- Partial Call Graph (max 5 caller/called nodes):
- 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:
Should not be used in .vuh files or elsewhere, instead use the public function rp_internal_redirect.
- 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)
- Switches:
- -noredirect
(boolean) (optional)- -nodirectory
(boolean) (optional)- -extension_pattern
(defaults to".*"
) (optional)- Parameters:
- path
- See Also:
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.
rp_serve_concrete_file (public)
rp_serve_concrete_file file
Serves a file.
- Parameters:
- file
- Partial Call Graph (max 5 caller/called nodes):
- 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
- Partial Call Graph (max 5 caller/called nodes):
- Testcases:
- No testcase defined.