Shambhala API notes
Shambhala API notes These are some notes on the Shambhala API and the data structures you have to deal with, etc. They are not yet nearly complete, but hopefully, they will help you get your bearings. A few notes on general pedagogical style here. In the interest of conciseness, all structure declarations here are incomplete --- the real ones have more slots, that I'm not telling you about. For the most part, these are reserved to one component of the server core or another, and should be altered by modules with caution.
However, in some cases, they really are things I just haven't gotten around to yet. Welcome to the bleeding edge. Finally, here's an outline, to give you some bare idea of what's coming up, and in what order: Basic concepts. Handlers, Modules, and Requests A brief tour of a module How handlers work A brief tour of the request_rec Where request_rec structures come from Handling requests, declining, and returning error codes Special considerations for response handlers Special considerations for authentication handlers Special considerations for logging handlers Resource allocation and resource pools Configuration, commands and the like Per-directory configuration structures Command handling Side notes --- per-server configuration, virtual servers, etc.
Basic concepts. We begin with an overview of the basic concepts behind the Shambhala API, and how they are manifested in the code. Handlers, Modules, and Requests Shambhala breaks down request handling into a series of steps, more or less the same way the Netscape Server API does (although Shambhala has a few more stages than NetSite does, as hooks for stuff I thought might be useful in the future). These are: URI -> Filename translation Auth ID checking [is the user who they say they are?] Auth access checking [is the user authorized here ?] Access checking other than auth Determining MIME type of the object requested "Fixups" --- there aren't any of these yet, but the phase is intended as a hook for possible extensions like SetEnv , which don't really fit well elsewhere.
Actually sending a response back to the client. Logging the request These phases are handled by looking at each of a succession of modules , looking to see if each of them has a handler for the phase, and attempting invoking it if so. The handler can typically do one of three things: Handle the request, and indicate that it has done so by returning the magic constant OK . Decline to handle the request, by returning the magic integer constant DECLINED .
In this case, the server behaves in all respects as if the handler simply hadn't been there. Signal an error, by returning one of the HTTP error codes. This terminates normal handling of the request, although an ErrorDocument may be invoked to try to mop up, and it will be logged in any case. Most phases are terminated by the first module that handles them; however, for logging, "fixups", and non-access authentication checking, all handlers always run (barring an error).
Also, the response phase is unique in that modules may declare multiple handlers for it, via a dispatch table keyed on the MIME type of the requested object. Modules may declare a response-phase handler which can handle any request, by giving it the key */* (i.e., a wildcard MIME type specification). However, wildcard handlers are only invoked if the server has already tried and failed to find a more specific response handler for the MIME type of the requested object (either none existed, or they all declined).
The handlers themselves are functions of one argument (a request_rec structure. vide infra), which returns an integer, as above. A brief tour of a module At this point, we need to explain the structure of a module. Our candidate will be one of the messier ones, the CGI module --- this handles both CGI scripts and the ScriptAlias config file command. It's actually a great deal more complicated than most modules, but if we're going to have only one example, it might as well be the one with its fingers in everyplace.
Let's begin with handlers. In order to handle the CGI scripts, the module declares a response handler for them. Because of ScriptAlias , it also has handlers for the name translation phase (to recognise ScriptAlias ed URI's), the type-checking phase (any ScriptAlias ed request is typed as a CGI script). The module needs to maintain some per (virtual) server information, namely, the ScriptAlias es in effect; the module structure therefore contains pointers to a functions which builds these structures, and to another which combines two of them (in case the main server and a virtual server both have ScriptAlias es declared).
Finally, this module contains code to handle the ScriptAlias command itself. This particular module only declares one command, but there could be more, so modules have command tables which declare their commands, and describe where they are permitted, and how they are to be invoked. A final note on the declared types of the arguments of some of these commands: a pool is a pointer to a resource pool structure; these are used by the server to keep track of the memory which has been allocated, files opened, etc., either to service a particular request, or to handle the process of configuring itself.
That way, when the request is over (or, for the configuration pool, when the server is restarting), the memory can be freed, and the files closed, en masse, without anyone having to write explicit code to track them all down and dispose of them. Also, a cmd_parms structure contains various information about the config file being read, and other status information, which is sometimes of use to the function which processes a config-file command (such as ScriptAlias ).
With no further ado, the module itself: /* Declarations of handlers. */ int translate_scriptalias (request_rec *); int type_scriptalias (request_rec *); int cgi_handler (request_rec *); /* Subsdiary dispatch table for response-phase handlers, by MIME type */ handler_rec cgi_handlers[] = { { "application/x-httpd-cgi", cgi_handler }, { NULL } }; /* Declarations of routines to manipulate the module's configuration * info.
Note that these are returned, and passed in, as void *'s; * the server core keeps track of them, but it doesn't, and can't, * know their internal structure. */ void *make_cgi_server_config (pool *); void *merge_cgi_server_config (pool *, void *, void *); /* Declarations of routines to handle config-file commands */ char *script_alias (cmd_parms *, void *per_dir_config, char *fake, char *real); command_rec cgi_cmds[] = { { "ScriptAlias", script_alias, NULL, RSRC_CONF, TAKE2, "a fakename and a realname"}, { NULL } }; module cgi_module = { STANDARD_MODULE_STUFF, NULL, /* initializer */ NULL, /* dir config creater */ NULL, /* dir merger --- default is to override */ make_cgi_server_config, /* server config */ merge_cgi_server_config, /* merge server config */ cgi_cmds, /* command table */ cgi_handlers, /* handlers */ translate_scriptalias, /* filename translation */ NULL, /* check_user_id */ NULL, /* check auth */ NULL, /* check access */ type_scriptalias, /* type_checker */ NULL, /* fixups */ NULL /* logger */ }; How handlers work The sole argument to handlers is a request_rec structure.
This structure describes a particular request which has been made to the server, on behalf of a client. In most cases, each connection to the client generates only one request_rec structure. A brief tour of the request_rec The request_rec contains pointers to a resource pool which will be cleared when the server is finished handling the request; to structures containing per-server and per-connection information, and most importantly, information on the request itself.
The most important such information is a small set of character strings describing attributes of the object being requested, including its URI, filename, content-type and content-encoding (these being filled in by the translation and type-check handlers
The rest of this page is on the live site.