You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by bu...@apache.org on 2012/05/06 16:18:10 UTC
svn commit: r816029 [16/23] - in /websites/staging/httpd/trunk/content: ./
apreq/ apreq/docs/ apreq/docs/libapreq2/ contributors/ css/ dev/
dev/images/ dev/whiteboard/ docs-project/ docs/ images/ info/
info/css-security/ library/ mod_fcgid/ mod_ftp/ mo...
Added: websites/staging/httpd/trunk/content/dev/API.html
==============================================================================
--- websites/staging/httpd/trunk/content/dev/API.html (added)
+++ websites/staging/httpd/trunk/content/dev/API.html Sun May 6 14:18:02 2012
@@ -0,0 +1,806 @@
+<HTML>
+<HEAD>
+<TITLE>Shambhala API notes</TITLE>
+</HEAD>
+<BODY>
+<H1>Shambhala API notes</H1>
+
+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.<P>
+
+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.<P>
+
+Finally, here's an outline, to give you some bare idea of what's
+coming up, and in what order:
+
+<UL>
+ <LI> <A HREF="#basics">Basic concepts.</A>
+ <UL>
+ <LI> <A HREF="#HMR">Handlers, Modules, and Requests</A>
+ <LI> <A HREF="#moduletour">A brief tour of a module</A>
+ </UL>
+ <LI> <A HREF="#handlers">How handlers work</A>
+ <UL>
+ <LI> <A HREF="#req_tour">A brief tour of the <CODE>request_rec</CODE></A>
+ <LI> <A HREF="#req_orig">Where request_rec structures come from</A>
+ <LI> <A HREF="#req_return">Handling requests, declining, and returning error codes</A>
+ <LI> <A HREF="#resp_handlers">Special considerations for response handlers</A>
+ <LI> <A HREF="#auth_handlers">Special considerations for authentication handlers</A>
+ <LI> <A HREF="#log_handlers">Special considerations for logging handlers</A>
+ </UL>
+ <LI> <A HREF="#pools">Resource allocation and resource pools</A>
+ <LI> <A HREF="#config">Configuration, commands and the like</A>
+ <UL>
+ <LI> <A HREF="#per-dir">Per-directory configuration structures</A>
+ <LI> <A HREF="#commands">Command handling</A>
+ <LI> <A HREF="#servconf">Side notes --- per-server configuration, virtual servers, etc.</A>
+ </UL>
+</UL>
+
+<H2><A NAME="basics">Basic concepts.</A></H2>
+
+We begin with an overview of the basic concepts behind the Shambhala
+API, and how they are manifested in the code.
+
+<H3><A NAME="HMR">Handlers, Modules, and Requests</A></H3>
+
+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:
+
+<UL>
+ <LI> URI -> Filename translation
+ <LI> Auth ID checking [is the user who they say they are?]
+ <LI> Auth access checking [is the user authorized <EM>here</EM>?]
+ <LI> Access checking other than auth
+ <LI> Determining MIME type of the object requested
+ <LI> "Fixups" --- there aren't any of these yet, but the phase is
+ intended as a hook for possible extensions like
+ <CODE>SetEnv</CODE>, which don't really fit well elsewhere.
+ <LI> Actually sending a response back to the client.
+ <LI> Logging the request
+</UL>
+
+These phases are handled by looking at each of a succession of
+<EM>modules</EM>, 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:
+
+<UL>
+ <LI> <EM>Handle</EM> the request, and indicate that it has done so
+ by returning the magic constant <CODE>OK</CODE>.
+ <LI> <EM>Decline</EM> to handle the request, by returning the magic
+ integer constant <CODE>DECLINED</CODE>. In this case, the
+ server behaves in all respects as if the handler simply hadn't
+ been there.
+ <LI> 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.
+</UL>
+
+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
+<EM>any</EM> request, by giving it the key <CODE>*/*</CODE> (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).<P>
+
+The handlers themselves are functions of one argument (a
+<CODE>request_rec</CODE> structure. vide infra), which returns an
+integer, as above.<P>
+
+<H3><A NAME="moduletour">A brief tour of a module</A></H3>
+
+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 <CODE>ScriptAlias</CODE> 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.<P>
+
+Let's begin with handlers. In order to handle the CGI scripts, the
+module declares a response handler for them. Because of
+<CODE>ScriptAlias</CODE>, it also has handlers for the name
+translation phase (to recognise <CODE>ScriptAlias</CODE>ed URI's), the
+type-checking phase (any <CODE>ScriptAlias</CODE>ed request is typed
+as a CGI script).<P>
+
+The module needs to maintain some per (virtual)
+server information, namely, the <CODE>ScriptAlias</CODE>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
+<CODE>ScriptAlias</CODE>es declared).<P>
+
+Finally, this module contains code to handle the
+<CODE>ScriptAlias</CODE> command itself. This particular module only
+declares one command, but there could be more, so modules have
+<EM>command tables</EM> which declare their commands, and describe
+where they are permitted, and how they are to be invoked. <P>
+
+A final note on the declared types of the arguments of some of these
+commands: a <CODE>pool</CODE> is a pointer to a <EM>resource pool</EM>
+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
+<CODE>cmd_parms</CODE> 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 <CODE>ScriptAlias</CODE>).
+
+With no further ado, the module itself:
+
+<PRE>
+/* 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 */
+};
+</PRE>
+
+<H2><A NAME="handlers">How handlers work</A></H2>
+
+The sole argument to handlers is a <CODE>request_rec</CODE> 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 <CODE>request_rec</CODE> structure.<P>
+
+<H3><A NAME="req_tour">A brief tour of the <CODE>request_rec</CODE></A></H3>
+
+The <CODE>request_rec</CODE> 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.<P>
+
+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 which handle the
+request, respectively). <P>
+
+Other commonly used data items are tables giving the MIME headers on
+the client's original request, MIME headers to be sent back with the
+ppppresponse (which modules can add to at will), and environment variables
+for any subprocesses which are spawned off in the course of servicing
+the request. These tables are manipulated using the
+<CODE>table_get</CODE> and <CODE>table_set</CODE> routines. <P>
+
+Finally, there are pointers to two data structures which, in turn,
+point to per-module configuration structures. Specifically, these
+hold pointers to the data structures which the module has built to
+describe the way it has been configured to operate in a given
+directory (via <CODE>.htaccess</CODE> files or
+<CODE><Directory></CODE> sections), for private data it has
+built in the course of servicing the request (so modules' handlers for
+one phase can pass "notes" to their handlers for other phases). There
+is another such configuration vector in the <CODE>server_rec</CODE>
+data structure pointed to by the <CODE>request_rec</CODE>, which
+contains per (virtual) server configuration data.<P>
+
+Here is an abridged declaration, giving the fields most commonly used:<P>
+
+<PRE>
+struct request_rec {
+
+ pool *pool;
+ conn_rec *connection;
+ server_rec *server;
+
+ /* What object is being requested */
+
+ char *uri;
+ char *filename;
+ char *path_info;
+ char *args; /* QUERY_ARGS, if any */
+ struct stat finfo; /* Set by server core;
+ * st_mode set to zero if no such file */
+
+ char *content_type;
+ char *content_encoding;
+
+ /* MIME header environments, in and out. Also, an array containing
+ * environment variables to be passed to subprocesses, so people can
+ * write modules to add to that environment.
+ *
+ * The difference between headers_out and err_headers_out is that the
+ * latter are printed even on error, and persist across internal redirects
+ * (so the headers printed for ErrorDocument handlers will have them).
+ */
+
+ table *headers_in;
+ table *headers_out;
+ table *err_headers_out;
+ table *subprocess_env;
+
+ /* Info about the request itself... */
+
+ int header_only; /* HEAD request, as opposed to GET */
+ char *protocol; /* Protocol, as given to us, or HTTP/0.9 */
+ char *method; /* GET, HEAD, POST, etc. */
+ int method_number; /* M_GET, M_POST, etc. */
+
+ /* Info for logging */
+
+ char *the_request;
+ int bytes_sent;
+
+ /* A flag which modules can set, to indicate that the data being
+ * returned is volatile, and clients should be told not to cache it.
+ */
+
+ int no_cache;
+
+ /* Various other config info which may change with .htaccess files
+ * These are config vectors, with one void* pointer for each module
+ * (the thing pointed to being the module's business).
+ */
+
+ void *per_dir_config; /* Options set in config files, etc. */
+ void *request_config; /* Notes on *this* request */
+
+};
+
+</PRE>
+
+<H3><A NAME="req_orig">Where request_rec structures come from</A></H3>
+
+Most <CODE>request_rec</CODE> structures are built by reading an HTTP
+request from a client, and filling in the fields. However, there are
+a few exceptions:
+
+<UL>
+ <LI> If the request is to an imagemap, a type map (i.e., a
+ <CODE>*.var</CODE> file), or a CGI script which returned a
+ local "Location:", then the resource which the user requested
+ is going to be ultimately located by some URI other than what
+ the client originally supplied. In this case, the server does
+ an <EM>internal redirect</EM>, constructing a new
+ <CODE>request_rec</CODE> for the new URI, and processing it
+ almost exactly as if the client had requested the new URI
+ directly. <P>
+
+ <LI> If some handler signaled an error, and an
+ <CODE>ErrorDocument</CODE> is in scope, the same internal
+ redirect machinery comes into play.<P>
+
+ <LI> Finally, a handler occasionally needs to investigate "what
+ would happen if" some other request were run. For instance,
+ the directory indexing module needs to know what MIME type
+ would be assigned to a request for each directory entry, in
+ order to figure out what icon to use.<P>
+
+ Such handlers can construct a <EM>sub-request</EM>, using the
+ functions <CODE>sub_req_lookup_file</CODE> and
+ <CODE>sub_req_lookup_uri</CODE>; this constructs a new
+ <CODE>request_rec</CODE> structure and processes it as you
+ would expect, up to but not including the point of actually
+ sending a response. (These functions skip over the access
+ checks if the sub-request is for a file in the same directory
+ as the original request).<P>
+
+ (Server-side includes work by building sub-requests and then
+ actually invoking the response handler for them, via the
+ function <CODE>run_sub_request</CODE>).
+</UL>
+
+<H3><A NAME="req_return">Handling requests, declining, and returning error codes</A></H3>
+
+As discussed above, each handler, when invoked to handle a particular
+<CODE>request_rec</CODE>, has to return an <CODE>int</CODE> to
+indicate what happened. That can either be
+
+<UL>
+ <LI> OK --- the request was handled successfully. This may or may
+ not terminate the phase.
+ <LI> DECLINED --- no erroneous condition exists, but the module
+ declines to handle the phase; the server tries to find another.
+ <LI> an HTTP error code, which aborts handling of the request.
+</UL>
+
+Note that if the error code returned is <CODE>REDIRECT</CODE>, then
+the module should put a <CODE>Location</CODE> in the request's
+<CODE>headers_out</CODE>, to indicate where the client should be
+redirected <EM>to</EM>. <P>
+
+<H3><A NAME="resp_handlers">Special considerations for response handlers</A></H3>
+
+Handlers for most phases do their work by simply setting a few fields
+in the <CODE>request_rec</CODE> structure (or, in the case of access
+checkers, simply by returning the correct error code). However,
+response handlers have to actually send a request back to the client. <P>
+
+They should begin by sending an HTTP response header, using the
+function <CODE>send_http_header</CODE>. (You don't have to do
+anything special to skip sending the header for HTTP/0.9 requests; the
+function figures out on its own that it shouldn't do anything). If
+the request is marked <CODE>header_only</CODE>, that's all they should
+do; they should return after that, without attempting any further
+output. <P>
+
+Otherwise, they should produce a request body which responds to the
+client as appropriate. The primitives for this are <CODE>rputc</CODE>
+and <CODE>rprintf</CODE>, for internally generated output, and
+<CODE>send_fd</CODE>, to copy the contents of some <CODE>FILE *</CODE>
+straight to the client. <P>
+
+One final consideration: when doing I/O to the client, there is the
+possibility of indefinite delays. It is therefore important to arm a
+timeout before initiating I/O to the client.<P>
+
+At this point, you should more or less understand the following piece
+of code, which is the handler which handles <CODE>GET</CODE> requests
+which have no more specific handler; it also shows how conditional
+<CODE>GET</CODE>s can be handled, if it's desirable to do so in a
+particular response handler. (The functions <CODE>pfopen</CODE> and
+<CODE>pfclose</CODE> tie the <CODE>FILE *</CODE> returned into the
+resource pool machinery, so it will be closed even if the request is
+aborted).<P>
+
+<PRE>
+int default_handler (request_rec *r)
+{
+ int errstatus;
+ FILE *f;
+
+ if (r->method_number != M_GET) return DECLINED;
+ if (r->finfo.st_mode == 0) return NOT_FOUND;
+
+ if ((errstatus = set_content_length (r, r->finfo.st_size))
+ || (errstatus = set_last_modified (r, r->finfo.st_mtime)))
+ return errstatus;
+
+ f = pfopen (r->pool, r->filename, "r");
+
+ if (f == NULL) {
+ log_reason("file permissions deny server access", r->filename, r);
+ return FORBIDDEN;
+ }
+
+ register_timeout ("send", r);
+ send_http_header (r);
+
+ if (!r->header_only) {
+ send_fd (f, r);
+ }
+
+ kill_timeout(r);
+ pfclose (r->pool, f);
+ return OK;
+}
+</PRE>
+
+Finally, if all of this is too much of a challenge, there are a few
+ways out of it. First off, as shown above, a response handler which
+has not yet produced any output can simply return an error code, in
+which case the server will automatically produce an error response.
+Secondly, it can punt to some other handler by invoking
+<CODE>internal_redirect</CODE>, which is how the internal redirection
+machinery discussed above is invoked. A response handler which has
+internally redirected should always return <CODE>OK</CODE>. <P>
+
+(Invoking <CODE>internal_redirect</CODE> from handlers which are
+<EM>not</EM> response handlers will lead to serious confusion).
+
+<H3><A NAME="auth_handlers">Special considerations for authentication handlers</A></H3>
+
+Stuff that should be discussed here in detail:
+
+<UL>
+ <LI> Authentication-phase handlers not invoked unless auth is
+ configured for the directory.
+ <LI> Common auth configuration stored in the core per-dir
+ configuration; it has accessors <CODE>auth_type</CODE>,
+ <CODE>auth_name</CODE>, and <CODE>requires</CODE>.
+ <LI> Common routines, to handle the protocol end of things, at least
+ for HTTP basic authentication (<CODE>get_basic_auth_pw</CODE>,
+ which sets the <CODE>connection->user</CODE> structure field
+ automatically, and <CODE>note_basic_auth_failure</CODE>, which
+ arranges for the proper <CODE>WWW-Authenticate:</CODE> header
+ to be sent back).
+</UL>
+
+<H3><A NAME="log_handlers">Special considerations for logging handlers</A></H3>
+
+When a request has internally redirected, there is the question of
+what to log. Shambhala handles this by bundling the entire chain of
+redirects into a list of <CODE>request_rec</CODE> structures which are
+threaded through the <CODE>r->prev</CODE> and <CODE>r->next</CODE>
+pointers. The <CODE>request_rec</CODE> which is passed to the logging
+handlers in such cases is the one which was originally built for the
+intial request from the client; note that the bytes_sent field will
+only be correct in the last request in the chain (the one for which a
+response was actually sent).
+
+<H2><A NAME="pools">Resource allocation and resource pools</A></H2>
+
+One of the problems of writing and designing a server-pool server is
+that of preventing leakage, that is, allocating resources (memory,
+open files, etc.), without subsequently releasing them. The resource
+pool machinery is designed to prevent this. Stuff that should be
+discussed here in detail:
+
+<UL>
+ <LI> Allocating memory --- <CODE>palloc</CODE> and friends
+ <LI> The array and table stuff
+ <LI> Files and file descriptors
+ <LI> sub-pools and <CODE>destroy_sub_request</CODE>
+</UL>
+
+<H2><A NAME="config">Configuration, commands and the like</A></H2>
+
+One of the design goals for this server was to maintain external
+compatibility with the NCSA 1.3 server --- that is, to read the same
+configuration files, to process all the directives therein correctly,
+and in general to be a drop-in replacement for NCSA. On the other
+hand, another design goal was to move as much of the server's
+functionality into modules which have as little as possible to do with
+the monolithic server core. The only way to reconcile these goals is
+to move the handling of most commands from the central server into the
+modules. <P>
+
+However, just giving the modules command tables is not enough to
+divorce them completely from the server core. The server has to
+remember the commands in order to act on them later. That involves
+maintaining data which is private to the modules, and which can be
+either per-server, or per-directory. Most things are per-directory,
+including in particular access control and authorization information,
+but also information on how to determine file types from suffixes,
+which can be modified by <CODE>AddType</CODE> and
+<CODE>DefaultType</CODE> directives, and so forth. In general, the
+governing philosophy is that anything which <EM>can</EM> be made
+configurable by directory should be; per-server information is
+generally used in the standard set of modules for information like
+<CODE>Alias</CODE>es and <CODE>Redirect</CODE>s which come into play
+before the request is tied to a particular place in the underlying
+file system. <P>
+
+Another requirement for emulating the NCSA server is being able to
+handle the per-directory configuration files, generally called
+<CODE>.htaccess</CODE> files, though even in the NCSA server they can
+contain directives which have nothing at all to do with access
+control. Accordingly, after URI -> filename translation, but before
+performing any other phase, the server walks down the directory
+hierarchy of the underlying filesystem, following the translated
+pathname, to read any <CODE>.htaccess</CODE> files which might be
+present. The information which is read in then has to be
+<EM>merged</EM> with the applicable information from the server's own
+config files (either from the <CODE><Directory></CODE> sections
+in <CODE>access.conf</CODE>, or from defaults in
+<CODE>srm.conf</CODE>, which actually behaves for most purposes almost
+exactly like <CODE><Directory /></CODE>).<P>
+
+Finally, after having served a request which involved reading
+<CODE>.htaccess</CODE> files, we need to discard the storage allocated
+for handling them. That is solved the same way it is solved wherever
+else similar problems come up, by tying those structures to the
+per-transaction resource pool. <P>
+
+<H3><A NAME="per-dir">Per-directory configuration structures</A></H3>
+
+Let's look out how all of this plays out in <CODE>mod_mime.c</CODE>,
+which defines the file typing handler which emulates the NCSA server's
+behavior of determining file types from suffixes. What we'll be
+looking at, here, is the code which implements the
+<CODE>AddType</CODE> and <CODE>AddEncoding</CODE> commands. These
+commands can appear in <CODE>.htaccess</CODE> files, so they must be
+handled in the module's private per-directory data, which in fact,
+consists of two separate <CODE>table</CODE>s for MIME types and
+encoding information, and is declared as follows:
+
+<PRE>
+typedef struct {
+ table *forced_types; /* Additional AddTyped stuff */
+ table *encoding_types; /* Added with AddEncoding... */
+} mime_dir_config;
+</PRE>
+
+When the server is reading a configuration file, or
+<CODE><Directory></CODE> section, which includes one of the MIME
+module's commands, it needs to create a <CODE>mime_dir_config</CODE>
+structure, so those commands have something to act on. It does this
+by invoking the function it finds in the module's "create per-dir
+config slot", with two arguments: the name of the directory to which
+this configuration information applies (or <CODE>NULL</CODE> for
+<CODE>srm.conf</CODE>), and a pointer to a resource pool in which the
+allocation should happen. <P>
+
+(If we are reading a <CODE>.htaccess</CODE> file, that resource pool
+is the per-request resource pool for the request; otherwise it is a
+resource pool which is used for configuration data, and cleared on
+restarts. Either way, it is important for the structure being created
+to vanish when the pool is cleared, by registering a cleanup on the
+pool if necessary). <P>
+
+For the MIME module, the per-dir config creation function just
+<CODE>palloc</CODE>s the structure above, and a creates a couple of
+<CODE>table</CODE>s to fill it. That looks like this:
+
+<PRE>
+void *create_mime_dir_config (pool *p, char *dummy)
+{
+ mime_dir_config *new =
+ (mime_dir_config *) palloc (p, sizeof(mime_dir_config));
+
+ new->forced_types = make_table (p, 4);
+ new->encoding_types = make_table (p, 4);
+
+ return new;
+}
+</PRE>
+
+Now, suppose we've just read in a <CODE>.htaccess</CODE> file. We
+already have the per-directory configuration structure for the next
+directory up in the hierarchy. If the <CODE>.htaccess</CODE> file we
+just read in didn't have any <CODE>AddType</CODE> or
+<CODE>AddEncoding</CODE> commands, its per-directory config structure
+for the MIME module is still valid, and we can just use it.
+Otherwise, we need to merge the two structures somehow. <P>
+
+To do that, the server invokes the module's per-directory config merge
+function, if one is present. That function takes three arguments:
+the two structures being merged, and a resource pool in which to
+allocate the result. For the MIME module, all that needs to be done
+is overlay the tables from the new per-directory config structure with
+those from the parent:
+
+<PRE>
+void *merge_mime_dir_configs (pool *p, void *parent_dirv, void *subdirv)
+{
+ mime_dir_config *parent_dir = (mime_dir_config *)parent_dirv;
+ mime_dir_config *subdir = (mime_dir_config *)subdirv;
+ mime_dir_config *new =
+ (mime_dir_config *)palloc (p, sizeof(mime_dir_config));
+
+ new->forced_types = overlay_tables (p, subdir->forced_types,
+ parent_dir->forced_types);
+ new->encoding_types = overlay_tables (p, subdir->encoding_types,
+ parent_dir->encoding_types);
+
+ return new;
+}
+</PRE>
+
+As a note --- if there is no per-directory merge function present, the
+server will just use the subdirectory's configuration info, and ignore
+the parent's. For some modules, that works just fine (e.g., for the
+includes module, whose per-directory configuration information
+consists solely of the state of the <CODE>XBITHACK</CODE>), and for
+those modules, you can just not declare one, and leave the
+corresponding structure slot in the module itself <CODE>NULL</CODE>.<P>
+
+<H3><A NAME="commands">Command handling</A></H3>
+
+Now that we have these structures, we need to be able to figure out
+how to fill them. That involves processing the actual
+<CODE>AddType</CODE> and <CODE>AddEncoding</CODE> commands. To find
+commands, the server looks in the module's <CODE>command table</CODE>.
+That table contains information on how many arguments the commands
+take, and in what formats, where it is permitted, and so forth. That
+information is sufficient to allow the server to invoke most
+command-handling functions with preparsed arguments. Without further
+ado, let's look at the <CODE>AddType</CODE> command handler, which
+looks like this (the <CODE>AddEncoding</CODE> command looks basically
+the same, and won't be shown here):
+
+<PRE>
+char *add_type(cmd_parms *cmd, mime_dir_config *m, char *ct, char *ext)
+{
+ if (*ext == '.') ++ext;
+ table_set (m->forced_types, ext, ct);
+ return NULL;
+}
+</PRE>
+
+This command handler is unusually simple. As you can see, it takes
+four arguments, two of which are preparsed arguments, the third being
+the per-directory configuration structure for the module in question,
+and the fourth being a pointer to a <CODE>cmd_parms</CODE> structure.
+That structure contains a bunch of arguments which are frequently of
+use to some, but not all, commands, including a resource pool (from
+which memory can be allocated, and to which cleanups should be tied),
+and the (virtual) server being configured, from which the module's
+per-server configuration data can be obtained if required.<P>
+
+Another way in which this particular command handler is unusually
+simple is that there are no error conditions which it can encounter.
+If there were, it could return an error message instead of
+<CODE>NULL</CODE>; this causes an error to be printed out on the
+server's <CODE>stderr</CODE>, followed by a quick exit, if it is in
+the main config files; for a <CODE>.htaccess</CODE> file, the syntax
+error is logged in the server error log (along with an indication of
+where it came from), and the request is bounced with a server error
+response (HTTP error status, code 500). <P>
+
+The MIME module's command table has entries for these commands, which
+look like this:
+
+<PRE>
+command_rec mime_cmds[] = {
+{ "AddType", add_type, NULL, OR_FILEINFO, TAKE2,
+ "a mime type followed by a file extension" },
+{ "AddEncoding", add_encoding, NULL, OR_FILEINFO, TAKE2,
+ "an encoding (e.g., gzip), followed by a file extension" },
+{ NULL }
+};
+</PRE>
+
+The entries in these tables are:
+
+<UL>
+ <LI> The name of the command
+ <LI> The function which handles it
+ <LI> a <CODE>(void *)</CODE> pointer, which is passed in the
+ <CODE>cmd_parms</CODE> structure to the command handler ---
+ this is useful in case many similar commands are handled by the
+ same function.
+ <LI> A bit mask indicating where the command may appear. There are
+ mask bits corresponding to each <CODE>AllowOverride</CODE>
+ option, and an additional mask bit, <CODE>RSRC_CONF</CODE>,
+ indicating that the command may appear in the server's own
+ config files, but <EM>not</EM> in any <CODE>.htaccess</CODE>
+ file.
+ <LI> A flag indicating how many arguments the command handler wants
+ preparsed, and how they should be passed in.
+ <CODE>TAKE2</CODE> indicates two preparsed arguments. Other
+ options are <CODE>TAKE1</CODE>, which indicates one preparsed
+ argument, <CODE>FLAG</CODE>, which indicates that the argument
+ should be <CODE>On</CODE> or <CODE>Off</CODE>, and is passed in
+ as a boolean flag, <CODE>RAW_ARGS</CODE>, which causes the
+ server to give the command the raw, unparsed arguments
+ (everything but the command name itself). There is also
+ <CODE>ITERATE</CODE>, which means that the handler looks the
+ same as <CODE>TAKE1</CODE>, but that if multiple arguments are
+ present, it should be called multiple times, and finally
+ <CODE>ITERATE2</CODE>, which indicates that the command handler
+ looks like a <CODE>TAKE2</CODE>, but if more arguments are
+ present, then it should be called multiple times, holding the
+ first argument constant.
+ <LI> Finally, we have a string which describes the arguments that
+ should be present. If the arguments in the actual config file
+ are not as required, this string will be used to help give a
+ more specific error message. (You can safely leave this
+ <CODE>NULL</CODE>).
+</UL>
+
+Finally, having set this all up, we have to use it. This is
+ultimately done in the module's handlers, specifically for its
+file-typing handler, which looks more or less like this; note that the
+per-directory configuration structure is extracted from the
+<CODE>request_rec</CODE>'s per-directory configuration vector by using
+the <CODE>get_module_config</CODE> function.
+
+<PRE>
+int find_ct(request_rec *r)
+{
+ int i;
+ char *fn = pstrdup (r->pool, r->filename);
+ mime_dir_config *conf =
+ (mime_dir_config *)get_module_config(r->per_dir_config, &mime_module);
+ char *type;
+
+ if (S_ISDIR(r->finfo.st_mode)) {
+ r->content_type = DIR_MAGIC_TYPE;
+ return OK;
+ }
+
+ if((i=rind(fn,'.')) < 0) return DECLINED;
+ ++i;
+
+ if ((type = table_get (conf->encoding_types, &fn[i])))
+ {
+ r->content_encoding = type;
+
+ /* go back to previous extension to try to use it as a type */
+
+ fn[i-1] = '\0';
+ if((i=rind(fn,'.')) < 0) return OK;
+ ++i;
+ }
+
+ if ((type = table_get (conf->forced_types, &fn[i])))
+ {
+ r->content_type = type;
+ }
+
+ return OK;
+}
+
+</PRE>
+
+<H3><A NAME="servconf">Side notes --- per-server configuration, virtual servers, etc.</A></H3>
+
+The basic ideas behind per-server module configuration are basically
+the same as those for per-directory configuration; there is a creation
+function and a merge function, the latter being invoked where a
+virtual server has partially overriden the base server configuration,
+and a combined structure must be computed. (As with per-directory
+configuration, the default if no merge function is specified, and a
+module is configured in some virtual server, is that the base
+configuration is simply ignored). <P>
+
+The only substantial difference is that when a command needs to
+configure the per-server private module data, it needs to go to the
+<CODE>cmd_parms</CODE> data to get at it. Here's an example, from the
+alias module, which also indicates how a syntax error can be returned
+(note that the per-directory configuration argument to the command
+handler is declared as a dummy, since the module doesn't actually have
+per-directory config data):
+
+<PRE>
+char *add_redirect(cmd_parms *cmd, void *dummy, char *f, char *url)
+{
+ server_rec *s = cmd->server;
+ alias_server_conf *conf =
+ (alias_server_conf *)get_module_config(s->module_config,&alias_module);
+ alias_entry *new = push_array (conf->redirects);
+
+ if (!is_url (url)) return "Redirect to non-URL";
+
+ new->fake = f; new->real = url;
+ return NULL;
+}
+</PRE>
+</BODY>
+</HTML>
Added: websites/staging/httpd/trunk/content/dev/debugging.xml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/httpd/trunk/content/dev/debugging.xml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: websites/staging/httpd/trunk/content/dev/devnotes.xml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/httpd/trunk/content/dev/devnotes.xml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: websites/staging/httpd/trunk/content/dev/fetch-from-cvs.txt
==============================================================================
--- websites/staging/httpd/trunk/content/dev/fetch-from-cvs.txt (added)
+++ websites/staging/httpd/trunk/content/dev/fetch-from-cvs.txt Sun May 6 14:18:02 2012
@@ -0,0 +1,42 @@
+#!/usr/bin/perl -w
+#
+# Simple script to fetch the latest tarball in from-cvs/ and unpack it
+# in $dir.
+#
+# Script by Doug MacEachern <do...@telebusiness.co.nz>
+# minor fix by Magnus Bodin <ma...@bodin.org>
+
+use strict;
+use URI::URL ();
+use HTML::LinkExtor ();
+use LWP::Simple;
+use File::Path;
+
+my $ver = '1.3';
+my $dir = shift || "/tmp/apache_$ver-dev";
+my $cvs = "http://cvs.apache.org/snapshots/apache-$ver/";
+my $filptn = "apache-$ver\_";
+
+rmtree $dir;
+mkpath $dir, 0755;
+
+chdir $dir;
+
+my $p = HTML::LinkExtor->new(\&cb, $cvs);
+my $cnt;
+
+sub cb {
+ my($tag, %links) = @_;
+ return unless exists $links{href} and $links{href} =~ /$fileptn/;
+ return unless ++$cnt == 4;
+
+ my $file = URI::URL->new($links{href})->rel($cvs);
+ warn "mirror $links{href} => $file\n";
+
+ mirror $links{href} => $file;
+ system "gunzip < $file | tar -xvf -";
+ unlink $file;
+}
+
+$p->parse(get $cvs);
+
Added: websites/staging/httpd/trunk/content/dev/footer.html
==============================================================================
--- websites/staging/httpd/trunk/content/dev/footer.html (added)
+++ websites/staging/httpd/trunk/content/dev/footer.html Sun May 6 14:18:02 2012
@@ -0,0 +1 @@
+ <HR>
Added: websites/staging/httpd/trunk/content/dev/guidelines.xml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/httpd/trunk/content/dev/guidelines.xml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: websites/staging/httpd/trunk/content/dev/header.html
==============================================================================
--- websites/staging/httpd/trunk/content/dev/header.html (added)
+++ websites/staging/httpd/trunk/content/dev/header.html Sun May 6 14:18:02 2012
@@ -0,0 +1,3 @@
+<DIV ALIGN="CENTER">
+ <IMG SRC="images/apache_logo.gif" ALT="[APACHE]">
+</DIV>
Added: websites/staging/httpd/trunk/content/dev/how-to-release.xml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/httpd/trunk/content/dev/how-to-release.xml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: websites/staging/httpd/trunk/content/dev/images/apache_feather_bullet.gif
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/httpd/trunk/content/dev/images/apache_feather_bullet.gif
------------------------------------------------------------------------------
svn:mime-type = image/gif
Added: websites/staging/httpd/trunk/content/dev/images/apache_logo.gif
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/httpd/trunk/content/dev/images/apache_logo.gif
------------------------------------------------------------------------------
svn:mime-type = image/gif
Added: websites/staging/httpd/trunk/content/dev/index.xml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/httpd/trunk/content/dev/index.xml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: websites/staging/httpd/trunk/content/dev/patches.xml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/httpd/trunk/content/dev/patches.xml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: websites/staging/httpd/trunk/content/dev/platforms.html
==============================================================================
--- websites/staging/httpd/trunk/content/dev/platforms.html (added)
+++ websites/staging/httpd/trunk/content/dev/platforms.html Sun May 6 14:18:02 2012
@@ -0,0 +1,81 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+<TITLE>Apache Debugging Guide</TITLE>
+</HEAD>
+<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+<BODY
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#000080"
+ALINK="#FF0000"
+>
+
+<H1>Apache Platform List</H1>
+
+<P>Apache runs on a variety of (UNIX) platforms. In general, an officially supported platform is one where the developers have direct access. Over time, this access has come and gone, but these platforms are still included as "official" Apache ports.
+<P>The following is a list of those platforms Apache runs on "out of the box" that have developers who claim "responsibility" for maintaining that port. If you have access to any of those platforms lacking developers, please contact us at <a href="mailto:apache@apache.org">apache@apache.org</a>.
+<P>
+<hr>
+<dl>
+ <dt><b>A/UX 3.1.1</b>:</dt>
+ <dd>Jim Jagielski <a href="mailto:jim@jaguNET.com">(jim@jaguNET.com</a>)</dd>
+ <dd> </dd>
+ <dt><b>AIX</b>:</dt>
+ <dd>Ralf Engelschall (<a href="mailto:rse@engelschall.com">rse@engelschall.com</a>)</dd>
+ <dt> </dt>
+ <dt><b>BeOS</b>:</dt>
+ <dd>David Reid (<a href="mailto:dreid@jetnet.co.uk">dreid@jetnet.co.uk</a>)</dd>
+ <dt> </dt>
+ <dt><b>BSDI</b>:</dt>
+ <dd>David Reid (<a href="mailto:dreid@jetnet.co.uk">dreid@jetnet.co.uk</a>)</dd>
+ <dt> </dt>
+ <dt><b>Cygwin 1.x</b>:</dt>
+ <dd>Stipe Tolj (<a href="mailto:tolj@wapme-systems.de">tolj@wapme-systems.de</a>)</dd>
+ <dt> </dt>
+ <dt><b>DG/UX 5.4</b>:</dt>
+ <dd>Sameer Parekh (<a href="mailto:sameer@c2.net">sameer@c2.net</a>)</dd>
+ <dt> </dt>
+ <dt><b>FreeBSD 2.2.x</b>:</dt>
+ <dd>Jim Jagielski (<a href="mailto:jim@jaguNET.com">jim@jaguNET.com</a>)</dd>
+ <dt> </dt>
+ <dt><b>FreeBSD 3.x</b>:</dt>
+ <dd>Ralf Engelschall (<a href="mailto:rse@engelschall.com">rse@engelschall.com</a>)</dd>
+ <dt> </dt>
+ <dt><b>HP-UX</b>:</dt>
+ <dd>Rob Hartill (<a href="mailto:robh@imdb.com">robh@imdb.com</a>)</dd>
+ <dt> </dt>
+ <dt><b>IRIX</b>:</dt>
+ <dd>Ralf Engelschall (<a href="mailto:rse@engelschall.com">rse@engelschall.com</a>)</dd>
+ <dt> </dt>
+ <dt><b>Linux</b>:</dt>
+ <dd>Dean Gaudet (<a href="mailto:dean@apache.org">dean@apache.org</a>)</dd>
+ <dt> </dt>
+ <dt><b>Mac OS</b>:</dt>
+ <dd>Wilfredo Sánchez (<a href="mailto:wsanchez@apple.com">wsanchez@apache.org</a>)</dd>
+ <dt> </dt>
+ <dt></dt>
+ <dt><b>NeXT</b>:</dt>
+ <dd>Rob Hartill (<a href="mailto:robh@imdb.com">robh@imdb.com</a>)</dd>
+ <dt> </dt>
+ <dt><b>OSF1</b>:</dt>
+ <dd>Lars Eilebrecht (<a href="mailto:lars@apache.org">lars@apache.org</a>)</dd>
+ <dt> </dt>
+ <dt><b>ReliantUNIX/SINIX</b>:</dt>
+ <dd>Martin Kraemer (<a href="mailto:martin.kraemer%40fujitsu-siemens.com">martin.kraemer@fujitsu-siemens.com</a>)</dd>
+ <dt> </dt>
+ <dt><b>SCO</b>:</dt>
+ <dd>Ben Laurie (<a href="mailto:ben@algroup.co.uk">ben@algroup.co.uk</a>)</dd>
+ <dt> </dt>
+ <dt><b>Solaris</b>:</dt>
+ <dd>Lars Eilebrecht (<a href="mailto:lars@apache.org">lars@apache.org</a>)</dd>
+ <dt> </dt>
+</dl>
+<HR>
+
+<P>Got more platforms? Send 'em to
+<A HREF="mailto:apache@apache.org">apache@apache.org</A>. Thanks!
+
+</BODY>
+</HTML>
Added: websites/staging/httpd/trunk/content/dev/ports.html
==============================================================================
--- websites/staging/httpd/trunk/content/dev/ports.html (added)
+++ websites/staging/httpd/trunk/content/dev/ports.html Sun May 6 14:18:02 2012
@@ -0,0 +1,87 @@
+<HTML><HEAD>
+<TITLE>Version testing of Apache 1.1</TITLE>
+</HEAD><BODY>
+
+<H1>Version testing of Apache 1.1</H1>
+
+This page is to keep track of which platforms 1.1 has been explicitly compiled on.
+We have no testing formalism yet, this is just so we know that all platforms we
+claim to support are actually supported.
+
+<P>
+
+<BLOCKQUOTE><STRONG>mod_auth_msql can be excluded from the "all distribution modules
+compile" list since most people do not have MSQL on their systems.
+Likewise, mod_dld is also excluded from this list. Perhaps the
+"Configuration" file should mention which platforms DLD support exists
+on.</STRONG></BLOCKQUOTE>
+
+<P>
+
+
+<TABLE border=1>
+<TR><TH>Platform <TH>Core modules compile <TH>All distribution modules compile <TH>Compiled by <TH>Notes/Warnings</TR>
+<TR><TD>AIX <TD> <TD> <TD> <TD> </TR>
+<TR><TD>Apollo Domain/OS <TD> <TD> <TD> <TD> </TR>
+<TR><TD>A/UX <TD> <TD> <TD> <TD> </TR>
+<TR><TD>BSDI 1.1 <TD> <TD> <TD> <TD> </TR>
+<TR><TD>BSDI 2.x <TD>Yes <TD>Yes <TD>Brian B. <TD>mod_proxy warning (no error) </TR>
+<TR><TD>DEC OSF/1 <TD> <TD> <TD> <TD> </TR>
+<TR><TD>DG/UX 5.x <TD> <TD> <TD> <TD> </TR>
+<TR><TD>FreeBSD <TD>Yes <TD>Yes <TD>Chuck Murcko <TD>mod_proxy warning (no error) </TR>
+<TR><TD>HPUX 9.x <TD>Yes <TD>Yes (except msql, dld, db) <TD>Alexei <TD>Warnings:<BR>mod_proxy.c:2694: warning: passing arg 2 of `select' from incompatible pointer type
+ </TR>
+<TR><TD>HPUX 10.x <TD> <TD> <TD> <TD> </TR>
+<TR><TD>Irix 5.x, gcc <TD>Yes <TD>Yes <TD>Chuck Murcko <TD>http_main.c: In function `sig_term':
+http_main.c:904: warning: implicit declaration of function `killpg'<BR>
+http_main.c: In function `standalone_main':
+http_main.c:1404: warning: implicit declaration of function `bzero'<BR>
+mod_auth.c: In function `authenticate_basic_user':
+mod_auth.c:180: warning: implicit declaration of function `crypt'<BR>
+mod_proxy.c: In function `connect_handler':
+mod_proxy.c:2687: warning: implicit declaration of function `bzero'<BR>
+no mod_auth_db
+</TR>
+<TR><TD>Irix 5.x, SGI cc <TD>Yes <TD>Yes <TD>Mark Cox <TD>Warnings: http_bprintf.c, line 86: Long double not supported; double assumed. </TR>
+<TR><TD>Irix 6.x, gcc <TD> <TD> <TD> <TD> </TR>
+<TR><TD>Irix 6.x, SGI cc <TD>Yes <TD>Yes <TD>Brian Behlendorf <TD>Same as 5.x, SGI cc, though: "ld: WARNING 84: /usr/lib/libsun.a is not used for resolving any symbol" </TR>
+<TR><TD>Linux 1.x <TD> <TD> <TD> <TD> </TR>
+<TR><TD>LynxOS <TD> <TD> <TD> <TD> </TR>
+<TR><TD>NetBSD <TD> <TD> <TD> <TD> </TR>
+<TR><TD>NeXT 3.x <TD> <TD> <TD> <TD> </TR>
+<TR><TD>NeXT 4.x <TD> <TD> <TD> <TD> </TR>
+<TR><TD>OS/2 <TD> <TD> <TD> <TD> </TR>
+<TR><TD>QNX <TD> <TD> <TD> <TD> </TR>
+<TR><TD>SCO ODT 3 <TD> <TD> <TD> <TD> </TR>
+<TR><TD>SCO 5 <TD> <TD> <TD> <TD> </TR>
+<TR><TD>Sequent <TD> <TD> <TD> <TD> </TR>
+<TR><TD>Solaris 2.4, gcc <TD>Yes <TD>Yes <TD>Chuck Murcko <TD>util.c: In function `get_local_host':
+util.c:1090: warning: implicit declaration of function `gethostname'<BR>
+mod_auth.c: In function `authenticate_basic_user':
+mod_auth.c:180: warning: implicit declaration of function `crypt'<BR>
+mod_auth_dbm.c: In function `dbm_authenticate_basic_user':
+mod_auth_dbm.c:170: warning: implicit declaration of function `crypt'<BR>
+mod_cookies.c: In function `make_cookie':
+mod_cookies.c:133: warning: implicit declaration of function `gettimeofday'<BR>
+mod_proxy.c: In function `cache_check':
+mod_proxy.c:1663: warning: empty body in an else-statement
+<BR>no mod_auth_db </TR>
+<TR><TD>Solaris 2.4, Sun cc <TD>Yes <TD>Yes <TD>Chuck Murcko <TD>"http_main.c", line 1565: warning: Function has no return statement : main<BR>
+"util.c", line 1090: warning: implicitly declaring function to return int: gethostname()<BR>
+"mod_auth.c", line 180: warning: implicitly declaring function to return int: crypt()<BR>
+"mod_auth_dbm.c", line 170: warning: implicitly declaring function to return int: crypt()<BR>
+"mod_cookies.c", line 133: warning: implicitly declaring function to return int:gettimeofday()<BR>
+"mod_proxy.c", line 756: warning: semantics of "<" change in ANSI C; use explicit cast<BR>
+"mod_proxy.c", line 1649: warning: semantics of "<" change in ANSI C; use explicit cast<BR>
+"mod_proxy.c", line 2658: warning: statement not reached
+<BR>no mod_auth_db </TR>
+<TR><TD>Solaris 2.5, gcc <TD> <TD> <TD> <TD> </TR>
+<TR><TD>Solaris 2.5, Sun cc <TD>Yes <TD>Yes (except msql, dld, db) <TD>Alexei <TD>Warnings: http_main, util, mod_auth, mod_auth_dbm, mod_cookies, mod_proxy
+ </TR>
+<TR><TD>Sunos 4.1.x <TD> <TD> <TD> <TD> </TR>
+<TR><TD>Ultrix <TD> <TD> <TD> <TD> </TR>
+<TR><TD>UnixWare 2.x, cc <TD> <TD> <TD> <TD> </TR>
+
+</TABLE>
+</BODY>
+</HTML>
Added: websites/staging/httpd/trunk/content/dev/project-plan.html
==============================================================================
--- websites/staging/httpd/trunk/content/dev/project-plan.html (added)
+++ websites/staging/httpd/trunk/content/dev/project-plan.html Sun May 6 14:18:02 2012
@@ -0,0 +1,94 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+<HEAD>
+<TITLE>Apache Server Project Plan</TITLE>
+</HEAD>
+<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+<BODY
+BGCOLOR="#FFFFFF"
+TEXT="#000000"
+LINK="#0000FF"
+VLINK="#000080"
+ALINK="#FF0000"
+>
+
+<H1>Apache Server Project Plan</H1>
+<hr>
+<p><strong>THIS DOCUMENT IS CURRENTLY BEING UPDATED. PLANS POST 2.0 ARE STILL FUZZY! </strong>
+<p><hr>
+
+<p>
+
+This document aims to encapsulate our plans for world domination, uh,
+I mean, further work on the Apache web server. This is simply a
+statement of goals, is always subject to change, and should not be
+relied upon for business or mission-critical purposes. Nothing is
+guaranteed.
+
+<P>
+
+Last modified: <!--#echo var="LAST_MODIFIED" -->
+
+<H2>2.0</H2>
+
+<UL>
+ <LI>Multithreaded/Multiprocess hybrid
+ <LI>An Apache runtime library
+ <LI>Shared memory pools
+ <LI>Absolute Enforcement of an "Apache Style" for code.
+ <LI>Updated Configure/build/make process (autoconf?)
+ <LI>Configuration API, so that different configuration loaders can be written (Perl, Java, etc.)
+ <LI>More API hooks:
+ <UL>
+ <LI>Post config-read; so we can check consistency between
+ directives and abort the startup
+
+ <LI>Per child init
+
+ <LI>Per child die
+
+ <LI>Pre-handler; which asks round what could *potentially* be served on a URI;
+ gets back a list of possible internal redirects with the mime-type/lang/charset
+ and quality values.
+
+ <LI>Up to 4 placeholders for future use ?
+ </UL>
+ <LI>Logging enhancements
+ <UL>
+ <LI>Separate logs for stderr and server error messages
+ <LI>Enable all virtual hosts to error-log to the same log, in ways
+ which distinguish entries.
+ <LI>Syslog, with different debugging levels, a la named or sendmail
+ </UL>
+ <LI>Fully 1.1 compliant proxy module.
+ <LI>Protocol abstraction layer, so that different protocol implementations can be distributed as a module.
+</UL>
+
+<H2>2.1</H2>
+<UL>
+<LI>Check returns from all system calls: read, write, etc.
+<LI>Nicer Access Control (allow "OneOf","AND","OR" ala NCSA)
+<LI>Named Access Methods
+<LI>Implementation of the "LINK" Method
+<LI>Authentication API, to make authentication type and database
+type orthogonal
+<LI>Next-generation content negotiation support
+<LI>Data store abstraction API? So we're not always presuming we sit on top of a filesystem.
+<LI>Enable logging of all "POST"ed data - for commercial-database-like
+backups and replay ability.
+<LI>Support for CERN-style imagemaps? http://www.w3.org/pub/WWW/Daemon/User/CGI/HTImageDoc.html#config.
+<LI>give an "Option", like "IncludesNoExec", except allow for CGI includes,
+not CMD includes.
+<LI>Serious dynamic loading support, so that binary distributions can have all
+ modules compiled and can be used even by folks without compilers of their own.
+<LI>Standardized PUT support, at least a perl script included with the distribution.
+</UL>
+
+<H2>3.0</H2>
+<UL>
+ <LI>HTTP-NG
+</UL>
+
+<HR>
+
+Last Modified <!--#echo var="LAST_MODIFIED" -->
Added: websites/staging/httpd/trunk/content/dev/release.xml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/httpd/trunk/content/dev/release.xml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: websites/staging/httpd/trunk/content/dev/robots.txt
==============================================================================
(empty)
Added: websites/staging/httpd/trunk/content/dev/styleguide.xml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/httpd/trunk/content/dev/styleguide.xml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: websites/staging/httpd/trunk/content/dev/todo.html
==============================================================================
--- websites/staging/httpd/trunk/content/dev/todo.html (added)
+++ websites/staging/httpd/trunk/content/dev/todo.html Sun May 6 14:18:02 2012
@@ -0,0 +1,99 @@
+<HTML><HEAD>
+<TITLE>Apache Bugs List / To Do List / Wish List</TITLE>
+</HEAD><BODY>
+
+<H2>Apache Bugs List / To Do List / Wish List</H2>
+
+<hr>
+<p><strong>THIS LIST IS COMPLETELY AND UTTERLY OUT OF DATE. But nobody
+ever gets around to cleaning it up... because we've got an entirely
+different method of tracking these things. The real todo lists are
+in STATUS messages regularly posted to the new-httpd mailing list,
+and available in the STATUS file in the root of each development
+tree (1.2, 1.3, and 2.0). The todo also includes various bugs in
+the <a href="http://bugs.apache.org/">bug database</a>.</strong>
+<p><hr>
+
+<strong>You've been warned!</strong><p>
+
+<STRONG>BUGS</STRONG>
+
+<UL>
+
+<LI>Fix -f command lines to take paths correctly. I know this is a
+bugwards compatibility with NCSA, but I don't like it and think we
+should change it. - beb
+
+<LI>AddDescription, and other mod_dir cleanups - beb
+
+</UL>
+
+<STRONG>To Do List</STRONG>
+
+<UL>
+
+<LI>Protocol Abstraction - so that SSL, SHTTP, and PCT can be plugged
+in as modules, and distributed separately without needing to patch
+core Apache code. Also hopefully HTTP-NG. - beb
+
+<LI>authentication API, to make authentication type and database type orthogonal - beb
+
+<LI>More tolerant config-file parsing - beb
+
+<LI>Formalized internal error-logging system, like sendmail/syslogd
+interaction - beb
+
+</UL>
+
+<STRONG>Wish List</STRONG>
+
+<UL>
+
+<LI>Scripted installation process, i.e. one that asks questions about
+the site and generates the conf files appropriately - beb
+
+<LI>Enable logging of all "POST"ed data - for commercial-database-like
+backups and replay ability. - beb
+
+<LI>Configurable Error Reporting
+ <UL>
+ <LI>Separate logs for stderr and server error messages
+ </UL>
+
+<LI>Dynamic Package builder - so that people can download binaries
+with exactly the options and packages they want. - beb
+
+<LI>Implementation of the "LINK" Method - beb
+
+<LI>Data store abstraction API? So we're not always presuming we sit on top of a filesystem. - beb
+
+<LI>Port to BeBox - beb
+
+<LI>give an "Option", like "IncludesNoExec", except allow for CGI includes,
+not CMD includes. -beb, and others
+
+</UL>
+
+<H2>Documentation needed on:</H2>
+
+<UL>
+<LI>Standards for Modules - beb
+<LI>CGI Extensions - beb
+<LI>Setting up logging and logfile analysis system - beb
+<LI>DBM documentation: explain about having username/group in same file - mjc
+<LI>MSQL documentation -dv
+<LI>Policy - what it takes for a module to move from contrib to the regular distribution. - aw
+</UL>
+
+<HR>
+
+Last Modified <!--#echo var="LAST_MODIFIED" -->
+<UL>
+<LI>beb - Brian Behlendorf, brian@organic.com
+<LI>ak - Alexei Kosut, akosut@nueva.pvt.k12.ca.us
+<LI>mjc - Mark J Cox, mark@awe.com
+<LI>aw - Andrew Wilson, andrew@tees.elsevier.co.uk
+<LI>cm - Chuck Murcko, chuck@telebase.com
+<LI>dv - Dirk.vanGulik, Dirk.vanGulik@jrc.it
+<LI>pcs - Paul Sutton, paul@awe.com
+</UL>
Added: websites/staging/httpd/trunk/content/dev/verification.xml
==============================================================================
Binary file - no diff available.
Propchange: websites/staging/httpd/trunk/content/dev/verification.xml
------------------------------------------------------------------------------
svn:mime-type = application/xml
Added: websites/staging/httpd/trunk/content/dev/voting.html
==============================================================================
--- websites/staging/httpd/trunk/content/dev/voting.html (added)
+++ websites/staging/httpd/trunk/content/dev/voting.html Sun May 6 14:18:02 2012
@@ -0,0 +1,400 @@
+<HTML>
+<HEAD>
+<TITLE>Apache voting rules and guidelines</TITLE>
+</HEAD>
+<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+ <BODY
+ BGCOLOR="#FFFFFF"
+ TEXT="#000000"
+ LINK="#0000FF"
+ VLINK="#000080"
+ ALINK="#FF0000"
+ >
+
+<H1>This document is now obsolete. Please refer to <A
+HREF="guidelines.html">the Apache Project guidelines</A> for
+up-to-date info.</H1>
+
+
+<H1 ALIGN=CENTER>
+ <IMG SRC="images/apache_logo.gif" ALT=""><BR>
+ Apache voting rules and guidelines
+</H1>
+
+<P>
+This document defines the rules and guidelines for Apache Group members
+to follow when voting on patches, documentation, or other action items
+to be applied to the Apache HTTP Server.
+</P>
+
+<P>
+The objective here is to avoid unnecessary conflict over changes and
+continue to produce a quality system in a timely manner. Not all conflict
+can be avoided, but at least we can agree on the procedures for conflict
+to be resolved.
+</P>
+
+<P>
+Some abbreviations used below...
+</P>
+<DL>
+ <DT><STRONG>mailing list</STRONG></DT>
+ <DD>The Apache developers' mailing list.
+ Subscription to the list is by invitation only, and only subscribers
+ can post directly to the list.</DD>
+ <DT><STRONG>CURRENT</STRONG></DT>
+ <DD>The most recent version of the source. Used as
+ the base code into which new patches are to be merged.</DD>
+
+ <DT><STRONG>C_VERSION</STRONG></DT>
+ <DD>The version number of <STRONG>CURRENT</STRONG>.</DD>
+
+ <DT><STRONG>NEXT</STRONG></DT>
+ <DD>The next version of the source. The product of
+ applying approved patches to <STRONG>CURRENT</STRONG></DD>
+
+</DL>
+
+<HR SIZE=6>
+<H2><IMG SRC="images/apache_feather_bullet.gif" ALT="o ">
+Issues and Action Items</H2>
+
+Many issues will be encountered by the project, each resulting in zero
+or more proposed action items. All action items may be voted on, but not all
+of them will require a formal vote. Issues should be raised on the
+mailing list as soon as they are identified. Action items
+<STRONG>must</STRONG> be raised on the mailing list.
+
+
+<H3>Types of Action Items</H3>
+
+<DL>
+ <DT><STRONG>Code Changes</STRONG></DT>
+ <DD>Code changes require peer review and testing over a wide range
+ of server platforms. Therefore, all code changes must pass through
+ a formal "patch vote", as described <A HREF="#patchvote">below</A>.
+ All those participating in a patch vote must be willing and able
+ to test the patched system.</DD>
+
+ <DT><STRONG>Documentation Changes</STRONG></DT>
+ <DD>Documentation changes are only voted on after (or during) the change.
+ The author of the changes must notify the mailing list, preferably
+ in advance of the work to avoid duplicate efforts, of where the
+ changes are being made. If the changes are to existing documents,
+ the existing documents should not be replaced until at least
+ 24 hours after notifying the list. Any group member may veto a
+ change, but must then provide real assistance to the author
+ in correcting the problem if it can be corrected, and must rescind
+ the veto once the problem has been corrected (this may be assumed
+ in good faith).</DD>
+
+ <DT><STRONG>Long Term Plans</STRONG></DT>
+ <DD>Long term plans are simply announcements that group members
+ are working on particular issues related to the Apache software.
+ These are not voted on,
+ but group members who do not agree with a particular plan,
+ or think an alternate plan would be better, are obligated to
+ inform the group of their feelings. In general, it is always
+ better to hear about alternate plans <STRONG>prior</STRONG> to
+ spending time on less adequate solutions.
+</DL>
+
+<H2><IMG SRC="images/apache_feather_bullet.gif" ALT="o ">
+Casting Votes</H2>
+<P>
+Anyone on the mailing list may vote on any issue. However, the act
+of voting carries certain obligations -- voting members are not only
+stating their opinion, they are agreeing to help do the work of the
+Apache Project.</P>
+
+<P>Each vote can be made in one of three flavors:
+
+<DL COMPACT>
+ <DT><STRONG>+1</STRONG></DT>
+ <DD> Yes, agree, or the action should be performed. On some issues, this
+ vote must only be given after the voter has tested the action on
+ their own system(s).
+ </DD><P>
+ <DT><STRONG>±0</STRONG></DT>
+ <DD> Abstain, no opinion, or I am happy to let the other group members
+ decide this issue. An abstention may have detrimental affects if
+ too many people abstain.
+ </DD><P>
+ <DT><STRONG>-1</STRONG></DT>
+ <DD> No, I <STRONG>veto</STRONG> this action. All vetos must include
+ an explanation of why the veto is appropriate. A veto with
+ no explanation is void.
+ </DD>
+</DL>
+
+<P>All votes must be sent to the mailing list.
+
+
+<H2><IMG SRC="images/apache_feather_bullet.gif" ALT="o ">
+<A NAME="patchvote">Formal Patch Votes</A></H2>
+<P>
+As mentioned above, changes to the source code require peer review
+and adequate testing across many platforms. The formal patch vote
+rules are intended to ensure that this happens even when we are all in a
+hurry to see things fixed. However, also see the section on
+<A
+ HREF="#lazy-voting"
+>lazy voting</A>
+mode.
+</P>
+<P>There are four distinct roles in the patch vote process, each of which
+may be shared by multiple group members: patch provider, vote coordinator,
+voter, and version builder.
+
+<P>Patch providers include anyone that has an action item to propose.
+Unless it is infeasible to do so, source code changes must be proposed in
+the form of input to the patch command. Feasibility is defined by each
+voter and the version builder(s), who may veto an action item if the
+action requires effort beyond what they are expected to perform.
+
+<H3>Uploading an Action Item</H3>
+
+<P>Action items (usually patches) are uploaded to hyperreal (apache.org)
+via FTP, either directly into the directory for patches to <STRONG>CURRENT</STRONG>
+(/httpd/patches/for_Apache_<STRONG>C_VERSION</STRONG>/), or into an incoming
+FTP directory for later transfer into the patch directory.<P>
+
+<P>Each filename should at least hint at the action objective and
+include reference to:
+ <OL>
+ <LI>(C_VERSION) the version number of <STRONG>CURRENT</STRONG></LI>
+ <LI>(ID) the unique action item numeric ID</LI>
+ <LI>(p) the patch letter, if an alternate patchfile is proposed</LI>
+ </OL>
+
+<P>The syntax for filenames not containing patches is:
+<PRE> ID.description</PRE>
+e.g.,<BR>
+<PRE> 01.Modula3_rewrite</PRE>
+if the action item is not (yet) in the form of a patch.
+
+<P>The syntax for filenames containing patches is:
+<PRE> IDp.description.<STRONG>C_VERSION</STRONG>.patch</PRE>
+e.g., <BR>
+<PRE> 01.ScriptAliasKaboom.0.8.11.patch
+ 01a.ScriptAliasKaboom.0.8.11.patch
+ 01b.ScriptAliasKaboom.0.8.11.patch</PRE>
+
+<P>The ID number should start at 01, and be incremented for each new
+action item uploaded.</P>
+
+<H3>Action Item Format</H3>
+
+<P>An action item should contain a list of header information
+(formatted like e-mail or HTTP headers):
+
+ <DL>
+ <DT><STRONG>From:</STRONG></DT>
+ <DD>A list of patch authors and/or people who identified the problem.
+ <DT><STRONG>Subject:</STRONG></DT>
+ <DD>A description of the problem being addressed.
+ <DT><STRONG>Requires:</STRONG></DT>
+ <DD>A list of other patches that must be applied before this one.
+ <DT><STRONG>Affects:</STRONG></DT>
+ <DD>A list of source file names that this patch affects
+ <DT><STRONG>Changelog:</STRONG></DT>
+ <DD>A couple of lines for use in a future changelog, so that the
+ patch (if accepted) can be recorded.
+ <DT><STRONG>Comments:</STRONG></DT>
+ <DD>Any additional comments about the problem.
+ </DL>
+
+followed by an empty line and then the patch (if any).
+
+<H3>Patch Format</H3>
+
+<P>The patch should be created by using <CODE>diff -u</CODE> on the
+<STRONG>CURRENT</STRONG> source and the modified source. E.g.,</P>
+
+<PRE> diff -u http_main.c.orig http_main.c</PRE>
+
+<P>All patches necessary to address an action item must be concatenated
+within a single patchfile. The source files affected by the patchfile
+should be listed in an Affects header.</P>
+
+<P>The completed patchfile should produce no errors or prompts when the
+command,</P>
+<PRE> patch -s < patchfile</PRE>
+is issued.
+
+<P>If the patch produces errors or prompts, then it may be rejected by
+others. Problems with patches should be reported to the mailing list
+as soon as they are noticed. Dependencies between patches must be
+noted with a Requires line in the patchfile headers.</P>
+
+<H3>Alternate Patches</H3>
+
+<P>Once uploaded, changes to the contents of a patchfile are limited
+to the header information (i.e., everything other than the patch itself).
+For example, the Changelog entry can be changed, but not the output
+of the <CODE>diff</CODE> command(s).
+
+<P>Should the patch itself need changing, a new patchfile should be created
+with a new patchletter after the ID. Anyone can upload a patch to address
+a single problem, so alternative patches can be offered for the same problem.
+The author of the patch is the only person allowed to (or give permission to)
+have an existing patch removed. Removal of a patch means removal of the
+patchfile.</P>
+
+<P>Each patchfile is voted on independently. New alternate patches must
+garner their own votes -- they do not automatically inherit the votes
+for patches they replace.</P>
+
+<P>Patches for <STRONG>CURRENT</STRONG> can be uploaded at any time before or
+during a voting session.</P>
+
+<H3>The Voting Session</H3>
+
+<P>A voting session can be initiated by anyone so long as a volunteer
+or volunteers can be found to:
+ <UL>
+ <LI>be the vote coordinator: collect the votes cast by group members</LI>
+ <LI>be the version builder: apply approved patches to create the
+ <STRONG>NEXT</STRONG> version of the system.</LI>
+ </UL>
+
+<P>The person or persons volunteering to perform these tasks agree
+on a timetable and announce it on the mailing list. The important
+part of the timetable is the vote deadline, which specifies when
+the votes will be tallied and the new version can be built.
+Unless it is an <A HREF="#emergency">emergency</A>, the initial
+deadline should be at least three days after the announcement.</P>
+
+<P>The vote deadline can be moved if, using the same voting rules
+as for patches, there are enough votes and no vetos. The current deadline
+cannot be voted on.</P>
+
+<P>Group members can vote and comment on the patches under consideration
+as often as they want. The final vote (if votes are changed) of a person
+is assumed to invalidate previous votes.</P>
+
+<P>Votes are cast as follows;
+
+ <DL COMPACT>
+ <DT><STRONG>+1</STRONG></DT>
+ <DD> can be given to a patch if the person has,
+ <OL>
+ <LI>read the patch header to see what problem it addresses</LI>
+ <LI>successfully patched it into <STRONG>CURRENT</STRONG></LI>
+ <LI>observed no bad side-effects resulting from the patch.</LI>
+ </OL>
+ </DD><P>
+ <DT><STRONG>-1</STRONG></DT>
+ <DD> is a veto on the patch. All vetos must come
+ with an explanation of why the veto is appropriate. A veto with
+ no explanation is void.
+ </DD>
+ </DL>
+
+<P>No veto can be overruled. If you disagree with the veto, you
+should lobby the person who cast the veto. Voters intending to veto
+a patch should make their opinions known to the group immediately,
+so that the problem can be remedied prior to the vote deadline, if
+possible.</P>
+
+<H3>Vote Collection</H3>
+
+<P>Votes are tallied by the vote coordinator as soon as the final
+vote deadline has passed. The results of the vote are then posted
+to the mailing list.</P>
+
+<P><STRONG>In order to be approved, an action item file must receive
+at least 3 positive votes and NO vetos.</STRONG></P>
+
+<P>Late <STRONG>+1</STRONG> votes can be ignored or accepted by the vote coordinator
+at his/her discretion. A late veto has no value: It can only be used
+to try to convince positive voters to rethink. If a positive voter changes
+to a veto, that veto is valid even though it is late.</P>
+
+<H3>Release Build and Announcement</H3>
+
+<P>After the vote coordinator gives the version builder the results,
+<STRONG>NEXT</STRONG> is created by applying the approved patches
+to <STRONG>CURRENT</STRONG>, making the changes called for by other approved
+(non-patch) action items, adding the approved action item descriptions
+to the changelog, and incrementing the version number.</P>
+
+<P><STRONG>NEXT</STRONG> is then uploaded by the version builder to hyperreal
+and placed in the pre-release directory (/httpd/dist) in compressed
+and gzip'd tar files that name the new version number. The availability
+of the new version is then announced on the private mailing list.</P>
+
+<P>After the version announcement, accidental mistakes made by the builder
+can be rectified without a vote, but must be announced to the group.</P>
+
+<P>Unless stated otherwise at the start of the vote session, <STRONG>NEXT</STRONG>
+is assumed to be intended for public release. If an objection to the
+public release is put forward, a majority decision vote will determine
+whether or not the release is made public. Unlike the other votes,
+a minority opinion cannot stop a public release.</P>
+
+<P>If <STRONG>NEXT</STRONG> is to be released publically, everyone on the mailing
+list should make the effort to download it and try it out. <STRONG>NEXT</STRONG>
+should not be publically released until 24 hours after it has been created
+and announced to the group.</P>
+
+<P>If one of the patches used to create <STRONG>NEXT</STRONG> is subsequently
+found to cause a more serious problem than those it fixed, this problem
+should be reported to the group and any public release postponed until
+a majority decision on how to rectify the problem is obtained.</P>
+
+<H3><A NAME="emergency">Emergency Patch Votes</A></H3>
+
+<P>In the event of an emergency patch/vote session to fix a security
+problem, the group may need to bypass the normal operating procedures
+described above in order to get a fix in place prior to any public
+announcement of the problem. Any group member may announce an emergency
+on the mailing list and is encouraged to do so immediately if notified
+about a severe problem. Any group member may veto an emergency in order
+to force it through the normal procedures.</P>
+
+<P>Patches created to solve an emergency problem may be linked directly
+from the Apache home page as soon as the patch has been created and
+tested by its author. However, this link must be removed or changed
+if the original patch is vetoed.</P>
+
+<P>The availability of an emergency patch may be announced to the public
+after 24hours or three +1 votes are given for the patch, whichever comes
+first.</P>
+
+<H2>
+ <A NAME="lazy-voting">
+ Lazy-Voting Mode
+ </A>
+</H2>
+<P>
+At some times, such as early in the devlopment cycle, it may be
+desirable to operate in what has been called "lazy" voting
+mode. This is essentially identical to the
+<A
+ HREF="#patchvote"
+>formal voting process</A>,
+except that "silence gives assent" -- if 48 hours pass without
+a veto, a quorum of "aye" votes is assumed even not officially
+collected.
+</P>
+<P>
+Formal and lazy voting environments may co-exist; some topics may
+require formal votes whilst others may not. Common sense should be
+exercised, and potentially highly-controversial patches shouldn't
+be submitted under the lazy rules.
+</P>
+<P>
+When a patch submitter expects to take advantage of lazy voting mode, it
+<EM>must</EM> be explicitly stated in the patch submission.
+</P>
+<HR SIZE=6>
+<ADDRESS>
+Rob Hartill and Roy Fielding<BR>
+3 September 1995
+</ADDRESS>
+<ADDRESS>
+ Modified 26 August 1997 by Ken Coar
+</ADDRESS>
+</BODY>
+</HTML>
Added: websites/staging/httpd/trunk/content/dev/whiteboard/README
==============================================================================
--- websites/staging/httpd/trunk/content/dev/whiteboard/README (added)
+++ websites/staging/httpd/trunk/content/dev/whiteboard/README Sun May 6 14:18:02 2012
@@ -0,0 +1,6 @@
+This is a collection of ideas proposed by various contributors to
+Apache on future directions the core HTTP server might want to take.
+These don't represent a "roadmap" or anything like that, but they're
+intended to provoke debate and hopefully inspire some coding.
+
+
Added: websites/staging/httpd/trunk/content/dev/whiteboard/api-middle.txt
==============================================================================
--- websites/staging/httpd/trunk/content/dev/whiteboard/api-middle.txt (added)
+++ websites/staging/httpd/trunk/content/dev/whiteboard/api-middle.txt Sun May 6 14:18:02 2012
@@ -0,0 +1,104 @@
+Subject: 2.0: Thoughts on the Module API/Middle End
+Date: Tue, 04 Aug 1998 00:00:41 -0400
+From: Simon Spero <se...@tipper.oit.unc.edu>
+Reply-To: new-httpd@apache.org
+To: new-httpd@hyperreal.org
+
+I've been meaning to post some thoughts about the design of the module API ,
+but I've been sick and busy, so I thought I'd just throws some ideas up for
+people to rip to shreds.Sorry if a lot of this is incoherent. I'd like to
+blame it all on voice recognition, but it's really my fault
+
+First of all, some stuff that should be non-controversial.
+
+1. The current API is too HTTP specific, and too procedural in nature. It
+is ill-defined, and inflexible when it comes to adding extra functions. It
+is very hard to predict how modules from different developers will interact
+with each other, or two used to modules providing the same type of service
+at the same time (for example, using two different authentication modules to
+get user information from two different places).
+
+2.
+
+Back-end vs. middle-end, objects vs. names.
+
+ this may be controversial, I like to think of the things that are managed
+by the back end of the server as being objects; these objects may have
+state, provided by a filesystem or a database, and can be accessed by
+invoking many different methods. The implementation of these methods could
+potentially come from code provided by many different modules; it is the job
+of the middle end to work out which methods go with which object. Methods
+can be grouped together to form interfaces (like in Java or CORBA).
+
+Use different types of Interfaces.
+
+Each type of activity should be defined by a different interface; it should
+be possible to implement several different interfaces in the same module; it
+should also be possible to only implement part of an interface, with the
+remaining implementations coming from different sources.
+
+Use Late binding.
+
+Interfaces should be flexible and late bound; module should only provide a
+single symbol, which would be a standard function identifying the methods
+and interfaces provided by this module. This identification the should be
+done using strings instead of locations within structs to avoid problems
+caused by adding methods to an interface.
+
+Provide fast method invocation
+
+Method indications should be fast; on the order of a jump to a function
+pointer, instead of a linear search. It should be possible to use this
+invocation method to provide basic services to other modules (for example,
+then might be a database interface). It should be possible to take modules
+which use a carefully limited set of system services, and automatically load
+them into the kernel, or access them from a kernel module.
+
+Object VTABLES can be pieced together at run time.
+
+The process of constructing an object might start with name resolution;
+For example, a database based implementation of a meta- information
+interface might be bound to /. A filesystem based implementation of the
+name resolution interface could then be bound to /files. Control of the
+name resolution processing would then be passed in to that implementation of
+the name resolution interface, which would do further construction of the
+object, including handling tasks like content-negotiation. This can be
+combined with other mechanisms for locating appropriate implementations to
+use with this object.
+
+VTABLES should be mostly pre-computed.
+
+ the important thing is that it should be possible to statically evaluate as
+much of the resolution process as possible to build cached vtables for the
+common-path. This could be done through a method in the name resolution
+interface which would return a list of tuples of name prefixes and
+vtables. It should be possible to quickly combine vtables for cases where
+dynamic processing is necessary. This might involve links rather than
+copying.
+
+Method Combination Should Be Predicatable And Controllable.
+
+It should be possible to control how methods are combined. This might
+involve e.g. making a pointer to the next function to call available to the
+invokes method, in the style of LISP or Dylan; or trying all methods until
+one succeeds, all succeed, etc. . The main constraint is that it should be
+easy to see what sort of method combination is being used without having to
+read every single piece of code involved.
+
+Object/VTABLE Construction Should Be Customisable
+
+The process of name resolution and method combination must be customizable
+as an interface; this allows for other types of object, in particular front
+end protocol stacks, to be implemented using the same mechanisms.
+
+-------
+Misc.
+
+All access to objects should be mediated by a cache (the core of the
+middle-end).
+
+There should be certain types of stereotyped interfaces e.g. for objects
+that behave like files. This allows caches to be smarter.
+
+Once in object has been resolved, it should have an object ID which can be
+used in internal caching.
Added: websites/staging/httpd/trunk/content/dev/whiteboard/overview_aek
==============================================================================
--- websites/staging/httpd/trunk/content/dev/whiteboard/overview_aek (added)
+++ websites/staging/httpd/trunk/content/dev/whiteboard/overview_aek Sun May 6 14:18:02 2012
@@ -0,0 +1,172 @@
+
+From akosut@leland.Stanford.EDU Thu Jul 23 09:38:40 1998
+Date: Sun, 19 Jul 1998 00:12:37 -0700 (PDT)
+From: Alexei Kosut <ak...@leland.Stanford.EDU>
+To: new-httpd@apache.org
+Subject: Apache 2.0 - an overview
+
+For those not at the Apache meeting in SF, and even for those who were,
+here's a quick overview of (my understanding of) the Apache 2.0
+architecture that we came up with. I present this to make sure that I have
+it right, and to get opinions from the rest of the group. Enjoy.
+
+
+1. "Well, if we haven't released 2.0 by Christmas of 1999, it won't
+ matter anyway."
+
+A couple of notes about this plan: I'm looking at this right now from a
+design standpoint, not an implementation one. If the plan herein were
+actually coded as-is, you'd get a very inefficient web server. But as
+Donald Knuth (Professor emeritus at Stanford, btw... :) points out,
+"premature optimization is the root of all evil." Rest assured there are
+plenty of ways to make sure Apache 2.0 is much faster than Apache 1.3.
+Taking out all the "slowness" code, for example... :)
+
+Also, the main ideas in this document mainly come from Dean Gaudet, Simon
+Spero, Cliff Skolnick and a bunch of other people, from the Apache Group's
+meeting in San Francisco, July 2 and 3, 1998. The other ideas come from
+other people. I'm being vague because I can't quite remember. We should
+have videotaped it. I've titled the sections of this document with quotes
+from our meeting, but they are paraphrased from memory, so don't take them
+too seriously.
+
+2. "But Simon, how can you have a *middle* end?"
+
+One of the main goals of Apache 2.0 is protocol independence (i.e.,
+serving HTTP/1.1, HTTP-NG, and maybe FTP or gopher or something). Another
+is to rid the server of the belief that everything is a file. Towards this
+end, we divide the server up into three parts, the front end, the middle
+end, and the back end.
+
+The front end is essentially a combination of http_main and http_protocol
+today. It takes care of all network and protocol matters, interpreting the
+request, putting it into a protocol-neutral form, and (possibly) passing
+it off to the rest of the server. This is approximately equivalent to the
+part of Apache contained in Dean's flow stuff, and it also works very well
+in certain non-Unix-like architectures such as clustered mainframes. In
+addition, part of this front-end might be optionally run in kernel space,
+giving a very fast server indeed...
+
+The back end is what generates the content. At the back of the back end we
+have backing stores (Cliff's term), which contain actual data. These might
+represent files on a disk, entries in a database, CGI scripts, etc... The
+back end also consists of other modules, which can alter the request in
+various fashions. The objects the server acts on can be thought of (Cliff
+again) as a filehandle and a set of key/value pairs (metainformation).
+The modules are set up as filters that can alter either one of those,
+stacking I/O routines onto the stream of data, or altering the
+metainformation.
+
+The middle end is what comes between the front and back ends. Think of
+http_request. This section takes care of arranging the modules, backing
+stores, etc... into a manner so that the path of the request will result
+in the correct entity being delivered to the front end and sent to the
+client.
+
+3. "I won't embarrass you guys with the numbers for how well Apache
+ performs compared to IIS." (on NT)
+
+For a server that was designed to handle flat files, Apache does it
+surprisingly poorly, compared with other servers that have been optimized
+for it. And the performance for non-static files is, of course, worse.
+While Apache is still more than fast enough for 95% of Web servers, we'd
+be remiss to dismiss those other 5% (they're the fun ones anyway). Another
+problem Apache has is its lack of a good, caching, proxy module.
+
+Put these together, along with the work Dean has done with the flow and
+mod_mmap_static stuff, and we realize the most important part of Apache
+2.0: a built-in, all-pervasive, cache. Every part of the request process
+will involve caching. In the path outlined above, between each layer of
+the request, between each module, sits the cache, which can (when it is
+useful), cache the response and its metainformation - including its
+variance, so it knows when it is safe to give out the cached copy. This
+gives every opportunity to increase the speed of the server by making sure
+it never has to dynamically create content more than it needs to, and
+renders accelerators such as Squid unnecessary.
+
+This also allows what I alluded to earlier: a kernel (or near-to-kernel)
+based web server component, which could read the request, consult the
+cache to find the requested object, and spit it back out, without so much
+as an interrupt in the way. Of course, the rest of Apache (with all its
+modules - it's generally a bad idea to let unknown, untrusted code, insert
+itself into the kernel) sits up in user-space, ready to handle any request
+the micro-Apache can't.
+
+A built-in cache also makes a real working HTTP/1.1 proxy server trivially
+easy to write.
+
+4. "Stop asking about backwards compatibility with the API. We'll write a
+ compatibility module... later."
+
+If modules are as described above, then obviously they are very much
+distinct from how Apache's current modules function. The only module
+function that is similar to the current model is the handler, or backing
+store, that actually provides the basic stream of data that the server
+alters to product a response entity.
+
+The basic module's approach to its job is to stack a filter onto the
+output. But it's better to think of the modules not as a stack that the
+request flows through (a layer cake with cache icing between the layers),
+but more of a mosaic (pretend I didn't use that word. I wrote collage. You
+can't prove anything), with modules stuck onto various sides of the
+request at different points, altering the request/response.
+
+Today's Apache modules take an all-or-nothing approach to request
+handlers. They tell Apache what they can do, overestimating, and then are
+supposed to DECLINE if they don't pass a number of checks they are
+supposed to make. Most modules don't do this correctly. The better
+approach is to allow the modules to inform Apache exactly of what they can
+do, and have Apache (the middle-end) take care of invoking them when
+appropriate.
+
+The final goal of all of this, of course, is simply to allow CGI output to
+be parsed for server-side includes. But don't tell Dean that.
+
+5. "Will Apache run without any of the normal Unix binaries installed,
+ only the BSD/POSIX libraries?"
+
+Another major issue is, of course, configuration of the server. There are
+a number of distinct opinions on this, both as to what should be
+configured and how it should be done. We talked mainly about the latter,
+but the did touch on the former. Obviously, with a radically distinct
+module API, the configuration is radically different. We need a good way
+to specify how the modules are supposed to interact, and of controlling
+what they can do, when and how, balancing what the user asks the server to
+do, and what the module (author) wants the server to do. We didn't really
+come up with a good answer to this.
+
+However, we did make some progress on the other side of the issue: We
+agreed that the current configuration system is definitely taking the
+right approach. Having a well-defined repository of the configuration
+scheme, containing the possible directives, when they are applicable, what
+their parameters are, etc... is the right way to go. We agreed that more
+information and stronger-typing (no RAW_ARGS!) would be good, and may
+enable on-the-fly generated configuration managers.
+
+We agreed that such a program, probably external to Apache, would generate
+a configuration and pass it to Apache, either via a standard config file,
+or by calling Apache API functions. It is desirable to be able to go the
+other way, pulling current configuration from Apache to look at, and
+perhaps change it on the fly, but unfortunately is unlikely this
+information would always be available; modules may perform optimizations
+on their configuration that makes the original configuration unavailable.
+
+For the language and specification of the configuration, we thought
+perhaps XML might be a good approach, and agreed it should be looked
+into. Other issues, such as SNMP, were brought up and laughed at.
+
+6. "So you're saying that the OS that controls half the banks, and 90% of
+ the airlines, doesn't even have memory protection for seperate
+ processes?"
+
+Obviously, there are a lot more items that have to be part of Apache 2.0,
+and we talked about a number of them. However, the four points above, I
+think, represent the core of the architecture we agreed on as a starting
+point.
+
+-- Alexei Kosut <ak...@stanford.edu> <http://www.stanford.edu/~akosut/>
+ Stanford University, Class of 2001 * Apache <http://www.apache.org> *
+
+
+
+