httpd::url(n) 1.2 "Tcl Web Server"

NAME

httpd::url - Url dispatching

SYNOPSIS

package require httpd::url ?1.2?

Url_Dispatch sock
Url_DeferredDispatch prefix suffix sock varname errmsg
Url_PostHook sock length
Url_PrefixInstall prefix command (option value)...
Url_PrefixRemove prefix
Url_AccessInstall proc
Url_AccessInstallPrepend proc
Url_AccessUnInstall proc
Url_PrefixMatch url prefixVar suffixVar
Url_PrefixExists prefix
Url_Handle cmd sock
Url_UnCache sock ?force?
Url_Unwind sock ei ec
Url_PathCheck urlsuffix
Url_DecodeQuery query (option value)...
Url_DecodeQueryOnly query (option value)...
Url_DecodeQuery_multipart/form-data query qualifiers
Url_DecodeQuery_application/x-www-urlencoded query qualifiers
Url_DecodeQuery_application/x-www-form-urlencoded query qualifiers
Url_QuerySetup sock
Url_ReadPost sock varname
Url_DecodeMIMEField type
Url_Decode data
Url_Encode string
Url_IsLinkToSelf url

DESCRIPTION

The package httpd::url is a companion package to package httpd and required by it. It provides the database mapping from urls in http requests to the tcl commands implementing them, and the commands to manipulate said database.

The main concept of this package is the domain. A domain is described by an url prefix and handled by single tcl command, the domain handler. In other words, a domain is an url tree, i.e. an url directory and all urls inside of that directory [*]. These urls are handled by the associated tcl command.

[*] There is one exception to this definition. It is possible, actually allowed, to define a domain whose url prefix is inside of another domain. All the urls in this sub-domain do not belong to the enclosing domain anymore.

Interface to protocol engines

The commands in this section are called by the package httpd as part of the url dispatching process. They are public for use in implementations of the HTTP protocol different from httpd.

Url_Dispatch sock
Dispatches the request currently waiting on the connection sock to the associated domain handler. The http protocol engine has already read the HTTP headers and placed into the connection status array. It may have read all posted data before invoking the domain handler. This is done if and only if requested by the domain.

Before the domain handler is invoked all registered access control callbacks are run. If any of them denies the request an http error reply is sent back and the domain handler is not invoked.

Url_DeferredDispatch prefix suffix sock varname errmsg
Bare bones invocation of the domain handler for the url (prefix and suffix) in the current request waiting on the connection sock. Executed after all posted data was read by this package. If the error message in errmssg is not empty the request will be aborted, using this message in the generated http error reply, and the domain handler is not invoked.

This command does not perform access control. It assumes that this has already been done before.

Url_PostHook sock length
Backdoor hack for Url_DecodeQuery compatibility. Remembers the current connection sock and length of pending data so that Url_DecodeQuery can read the post data if it has not already been read by the time it is called. Setting a length of 0 deactivates the remembered information.

Database manipulation

The commands in this section are for use by domain implementations, to manage their presence in the dispatcher database.

Url_PrefixInstall prefix command (option value)...
Adds a domain described by the url prefix to the database. After the call any access to an url in the domain will cause this package to call the associated domain handler, the command prefix command.

The domain handler is called with one additional argument, the channel handle sock of the connection which made the request for an url in the domain. The state data of this connection is available through

 
	upvar #0 Httpd$sock

as described in httpd. The allowed options and their meanings are:

readpost
takes a boolean value. If set to true (the default), then this package will retrieve post data before calling the domain handler. Else the domain handler is responsible for reading any post data the browser might have sent.

callback
takes a command prefix. It is invokes whenever a request in the domain was completed, with or without error. This allows the domain handler to cleanup any resources it might have allocated for the request at that time, like aborting a long running server operation.

The callback will be invoked with two additional arguments, sock and a string, in this order. The string can be empty. If the string is not empty it will contain an error message.

thread
takes a boolean value. If set to true the domain handler will run in its own thread. The default is false. In a server which is not thread-enabled this option will be ignored and the value always forced to false.
Url_PrefixRemove prefix
Remove the domain described by the url prefix from the database. After the call all urls in the domain may fall into a different domain and will be handled by that domain handler. If they don't fall into a different domain they will cause the generation of http error replies when accessed from a browser.

Url_AccessInstall proc
Adds the command with name proc at the end of the list of access control callback managed by the package. After the call the command will be invoked for all incoming requests. It can grant access, deny it, or announce that it doesn't care. When calling the command multiple times for the same proc only the first call will update the package. All others will be ignored.

The register callback is invoked with two additional arguments, the channel handle of the connection, and the url which is accessed. It has to return one of

ok
Access is granted.

denied
Access is denied. It is recommended that the callback generates the appropriate http error reply. However the system will work even if it does not, by generating its own reply when it finds that the callback did not.

return
See denied.

skip
The callback does not care about this url.


The package invokes the callbacks from first registered to last and will not stop as long as the callbacks return skip. Any tcl error thrown by a callback wil cause url processing to abort.

Url_AccessInstallPrepend proc
See Url_AccessInstall, except that the command prefix is added at the front of the list, causing it to be called before anything else registered before.

Url_AccessUnInstall proc
Removes the command prefix proc from the list of access control callbacks managed y the package. If the command prefix could not be found this command will do nothing.

Url_PrefixMatch url prefixVar suffixVar
Finds the best-matching domain for the url and stores the url prefix of the domain into the variable prefixVar, and the remainder of the url (i.e. everything after the prefix) into the variable suffixVar.

The best-matching domain is the domain with the longest prefix which still matches the specified url, path-component wise. In other words, the prefix /tcl will not match the url /tclhttpd/foo.

Url_PrefixExists prefix
Checks if a domain was registerd for prefix. The result is a boolean value where true signals that a domain was registered indeed.

Url_Handle cmd sock
This used to cache the domain handler command cmd for the url on the connection sock before invoking it. Nowadays it only invokes the command.

Url_UnCache sock ?force?
Removes the domain handler command for the url on the connection sock from the domain handler cache. If the argument force is present and set then there will be no special case for the internal redirect hack.

Support for domain handlers

The commands of this section are for use by domain implementations, to aid the tasks of url and request processing.

Url_Unwind sock ei ec
Performs common error handling after the current request on the connection sock was aborted with a tcl error. The two arguments ei and ec contain the errorInfo and errorCode information from the interpreter.

Url_PathCheck urlsuffix
Validates the pathname urlsuffix and makes sure that it doesn't sneak out of its domain via ..-trickery. Either raises an error, or returns a list of components in the pathname.

Url_DecodeQuery query (option value)...
A small wrapper around Url_DecodeQueryOnly. Ensures that the POST data on the connection set via Url_PostHook is read before handing over to the decoder. query is the name of the internal variable the data is stored into. The options coming after this information are simply handed over to the actual decoder, i.e. Url_DecodeQueryOnly. Accepted options:

type
Forces a specific type for the query data. Defaults to application/x-www-urlencoded. If no decoder for that type is present the system is forced back to the default.

qualifiers
Empty by default. Transformed into the second argument of the type specific decoders, see below.
Url_DecodeQueryOnly query (option value)...
Decodes the POST data stored in the variable query. It does this by dispatching to the appropriate type-specific decoder command (see below). See Url_DecodeQuery for the accepted options.

Url_DecodeQuery_multipart/form-data query qualifiers
Decoder for query data of type multipart/form-data. Essentially has to parse the MIME document in query, with guidance by the dictionary qualifiers. Used keys are

boundary
The boundary line used to separate the MIME parts. Required.
Returns a dictionary mapping from the names of the uploaded files to their contents.

Url_DecodeQuery_application/x-www-urlencoded query qualifiers
Decoder for application/x-www-urlencoded query data. The argument qualifiers is not used. Returns a dictionary mapping from the query keys to the query values.

Url_DecodeQuery_application/x-www-form-urlencoded query qualifiers
Decoder for application/x-www-form-urlencoded query data. An alias of Url_DecodeQuery_application/x-www-urlencoded.

Url_QuerySetup sock
Reads the POST data on the connection sock and initializes the ncgi package with it, for convenient access by URL implementations later on.

Url_ReadPost sock varname
Synchronously reads the POST data on the connection sock and stores it into the variable varname.

Url_DecodeMIMEField type
Decodes a mime type. Returns a list containing 3 elements, the major and minor type, and its qualifiers, a dictionary, in this order.

Url_Decode data
Decodes a single string in x-www-urlencoded form. The decoded string is returned as the result of the command.

Url_Encode string
Encodes a string for use in x-www-urlencoded query data. The encoded string is returned as the result of the command.

Url_IsLinkToSelf url
Compares the url to the url of the current page. The result of the comparison is a boolean flag. If they seem to be the same true will be returned, else false.

SEE ALSO

httpd, httpd::counter, httpd::doc_error, httpd::threadmgr, httpd::utils

KEYWORDS

domain, url, url dispatch, web server

COPYRIGHT

Copyright © 2003 Andreas Kupries <andreas_kupries@users.sourceforge.net>