httpd::url - Url dispatching
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.
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.
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.
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.
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.
The commands in this section are for use by domain implementations, to manage their presence in the dispatcher database.
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:
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.
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
Access is granted.
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.
See denied.
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.
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.
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.
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.
Checks if a domain was registerd for prefix. The result is a boolean value where true signals that a domain was registered indeed.
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.
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.
The commands of this section are for use by domain implementations, to aid the tasks of url and request processing.
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.
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.
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:
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.
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
The boundary line used to separate the MIME parts. Required.
Returns a dictionary mapping from the names of the uploaded files to their contents.
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.
Decoder for application/x-www-form-urlencoded query data. An alias of Url_DecodeQuery_application/x-www-urlencoded.
Reads the POST data on the connection sock and initializes the ncgi package with it, for convenient access by URL implementations later on.
Synchronously reads the POST data on the connection sock and stores it into the variable varname.
Decodes a mime type. Returns a list containing 3 elements, the major and minor type, and its qualifiers, a dictionary, in this order.
Decodes a single string in x-www-urlencoded form. The decoded string is returned as the result of the command.
Encodes a string for use in x-www-urlencoded query data. The encoded string is returned as the result of the command.
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.
httpd, httpd::counter, httpd::doc_error, httpd::threadmgr, httpd::utils
domain, url, url dispatch, web server
Copyright © 2003 Andreas Kupries <[email protected]>