486N/ALast modified at [$Date: 2002/10/18 01:08:38 $]
486N/AThe Apache HTTP Server project must balance two competing and disjoint
486N/Aobjectives: maintain stable code for third party authors, distributors and
486N/Amost importantly users so that bug and security fixes can be quickly adopted
486N/Awithout significant hardship due to API changes; and continue the development
486N/Aprocess that requires ongoing redesign to work around earlier oversights in
486N/Athe implementation of a fluid and flexible API.
486N/AThe Apache HTTP Server versions, through 2.0, used the Module Magic Number
486N/Ato reflect the relatively frequent API changes. This had the shortcoming
486N/Aof often leaving binary download users hunting to replace their loaded third
486N/Aparty modules. This left the third party module authors searching through
486N/Athe API change histories to determine the new declarations, APIs and side
486N/Aeffects of making the necessary code changes.
486N/AWith the simultaneous release of Apache 2.2-stable and Apache 2.3-development,
486N/Athe Apache HTTP Server project is moving to a more predictable stable code
486N/Abranch, while opening the development to forward progress without concern
486N/Afor breaking the stable branch. This document explains the rationale between
486N/Athe two versions and their behavior, going forward.
486N/ASTABLE RELEASES, 2.{even}.{revision}
486N/A------------------------------------
486N/AAll even numbered releases will be considered stable revisions.
486N/AStable revisions will retain forward compatiblity to the maximum
486N/Apossible extent. Features may be added during minor revisions, and
486N/Afeatures may be deprecated by making appropriate notations in the
486N/Adocumentation, but no features may be removed.
486N/AIn essence, that implies that you can upgrade from one minor revision
486N/Ato the next with a minimum of trouble. In particular, this means:
486N/A * The Module API will retain forward compatibility.
486N/A It will not be necessary to update modules to work with new
486N/A revisions of the stable tree.
486N/A * The run-time configuration will be forward compatible.
486N/A No configuration changes will be necessary to work with new
486N/A revisions of the stable tree.
486N/A * Compile-time configuration will be forward compatible.
486N/A The configure command line options that work in one release
486N/A of the stable tree will also work in the next release.
486N/AAs always, it will be necessary to test any new release to assure
486N/Athat it works correctly with a particular configuration and a
486N/Aparticular set of modules, but every effort will be made to assure
486N/Athat upgrades are as smooth as possible.
486N/AIn addition, the following development restrictions will aid in
486N/Akeeping the stable tree as safe as possible:
486N/A * No 'Experimental' modules; while it may be possible (based on API changes
486N/A required to support a given module) to load a 2.3-development module into
486N/A a 2.2-stable build of Apache, there are no guarantees. Experimental
486N/A modules will be introduced to the 2.3-development versions and either
486N/A added to 2.2-stable once they are proven and compatible, or deferred
486N/A to the 2.4-stable release if they cannot be incorporated in the current
486N/A stable release due to API change requirements.
486N/A * The stable CVS tree should not remain unstable at any time. Atomic commits
486N/A aught be used to introduce code from the development version to the stable
486N/A tree. At any given time a security release may be in preparation,
486N/A unbeknownst to other contributors. At any given time, testers may be
486N/A checking out CVS head to confirm that a bug has been corrected. And as
486N/A all code was well-tested in development prior to committing to the stable
486N/A tree, there is really no reason for this tree to be broken for more than
486N/A a few minutes during a lengthy commit.
486N/ADEVELOPMENT RELEASES, 2.{odd}.{revision}
486N/A-----------------------------------------
486N/AAll odd numbered releases designate the 'next' possible stable release,
486N/Atherefore the current development version will always be one greater than
486N/Athe stable release. Work proceeds on development releases, permitting
486N/Athe modification of the MMN at any time in order to correct deficiencies
486N/Aor shortcomings in the API. This means that third party modules from one
486N/Arevision to another may not be binary compatible, and may not successfully
486N/Acompile without modification to accomodate the API changes.
486N/AThe only 'supported' development release at any time will be the most
486N/Arecently released version. Developers will not be answering bug reports
486N/Aof older development releases once a new release is available, it becomes
486N/Athe resposibility of the reporter to use the latest development version
486N/Ato confirm that the bug still exists.
486N/AAny new code, new API features or new ('experimental') modules may be
486N/Apromoted at any time to the next stable release, by a vote of the project
486N/Acontributors. This vote is based on the technical stability of the new
486N/Acode and the stability of the interface. Once moved to stable, that feature
486N/Acannot change for the remainder of that lifetime of that stable verions,
486N/Aso the vote must reflect that the final decisions on the behavior and naming
486N/Aof that new feature were reached. Vetos continue to apply to this choice
486N/Aof introducing the new work to the stable version.
486N/AAt any given time, when the quality of changes to the development branch
486N/Ais considered release quality, that version may become a candidate for the
486N/Anext stable release. This includes some or all of the API changes, promoting
486N/Aexperimental modules to stable or deprecating and eliminating older modules
486N/Afrom the last stable release. All of these choices are considered by the
486N/Aproject as a group in the interests of promoting the stable release, so that
486N/Aany given change may be 'deferred' for a future release by the group, rather
486N/Athan introduce unacceptable risks to adopting the next stable release.
486N/AThird party module authors are strongly encouraged to test with the latest
486N/Adevelopment version. This assures that the module will be ready for the next
486N/Astable release, but more importantly, the author can react to shortcomings
486N/Ain the API early enough to warn the dev@httpd.apache.org community of the
shortcomings so that they can be addressed before the stable release. The
entire onus is on the third party module author to anticipate the needs of
their module before the stable release is created, once it has been released
they will be stuck with that API for the lifetime of that stable release.
In order to avoid 'skipped' release numbers, the Release Manager will generally
roll a release candidate (APACHE_#_#_#_RC#) tag. This is true of both the
stable as well as the development tree. Release Candidate tarballs will be
announced to the stable-testers@httpd.apache.org for the stable tree, or to
the current-testers@httpd.apache.org list for the development tree.
The final APACHE_#_#_# tag will not exist until the APACHE_#_#_#_RC# candidate
has passed the usual votes to release that version. Only then is the final
tarball packaged, removing all -rc# designations from the version number, and
tagging the tree with the release number.
* Source code should follow style guidelines.
OK, we all agree pretty code is good. Probably best to clean this
up by hand immediately upon branching a 2.1 tree.
Status: Justin volunteers to hand-edit the entire source tree ;)
Recall when the release plan for 2.0 was written:
Absolute Enforcement of an "Apache Style" for code.
Watch this slip into 3.0.
The style guide needs to be reviewed before this can be done.
The current file is dated April 20th 1998!
It's survived since '98 because it's welldone :-) Suggest we
branch the next tree. Really sort of straightforward, if you
dislike a bit within that doc, bring it up on the dev@httpd
list prior to the next branch.
So Bill sums up ... let's get the code cleaned up in CVS head.
Remember, it just takes cvs diff -b (that is, --ignore-space-change)
to see the code changes and ignore that cruft. Get editing Justin :)
* revamp the input filter syntax to provide for ordering of
filters created with the Set{Input|Output}Filter and the
Add{Input|Output}Filter directives. A 'relative to filterx'
syntax is definately preferable.
* Platforms that do not support fork (primarily Win32 and AS/400)
Architect start-up code that avoids initializing all the modules
in the parent process on platforms that do not support fork.
. Better yet - not only inform the startup of which phase it's in,
but allow the parent 'process' to initialize shared memory, etc,
and create a module-by-module stream to pass to the child, so the
parent can actually arbitrate the important stuff.
* Replace stat [deferred open] with
open/fstat in directory_walk.
Justin, Ian, OtherBill all interested in this. Implies setting up
the apr_file_t member in request_rec, and having all modules use
that file, and allow the cleanup to close it [if it isn't a shared,
* The Async Apache Server implemented in terms of APR.
[Bill Stoddard's pet project.]
Message-ID: <008301c17d42$9b446970$01000100@sashimi> (dev@apr)
OtherBill notes that this can proceed in two parts...
Async accept, setup, and tear-down of the request
e.g. dealing with the incoming request headers, prior to
dispatching the request to a thread for processing.
This doesn't need to wait for a
2.x/3.0 bump.
Async delegation of the entire request processing chain
Too many handlers use stack storage and presume it is
available for the life of the request, so a complete
async implementation would need to happen 3.0 release.
* Add a string "class" that combines a char* with a length
and a reference count. This will help reduce the number
of strlen and strdup operations during request processing.
Including both the length and allocation will save us a ton
of reallocation we do today, in terms of string manipulation.
OtherBill asks if this is really an APR issue, not an HTTPD issue?
MAKING APACHE REPOSITORY-AGNOSTIC
(or: remove knowledge of the filesystem)
[ 2002/10/01: discussion in progress on items below; this isn't
* dav_resource concept for an HTTP resource ("ap_resource")
* r->filename, r->canonical_filename, r->finfo need to
disappear. All users need to use new APIs on the ap_resource
(backwards compat: today, when this occurs with mod_dav and a
custom backend, the above items refer to the topmost directory
mapped by a location;
e.g. docroot)
Need to preserve a 'filename'-like string for mime-by-name
sorts of operations. But this only needs to be the name itself
Justin: Can we leverage the path info, or do we not trust the
gstein: well, it isn't the "path info", but the actual URI of
the resource. And of course we trust the user... that is
the resource they requested.
dav_resource->uri is the field you want. path_info might
still exist, but that portion might be related to the
CGI concept of "path translated" or some other further
To continue, I would suggest that "path translated" and
having *any* path info is Badness. It means that you did
not fully resolve a resource for the given URI. The
"abs_path" in a URI identifies a resource, and that
should get fully resolved. None of this "resolve to
<here> and then we have a magical second resolution
(inside the CGI script)" or somesuch.
Justin: Well, let's consider mod_mbox for a second. It is sort of
a virtual filesystem in its own right - as it introduces
it's own notion of a URI space, but it is intrinsically
tied to the filesystem to do the lookups. But, for the
portion that isn't resolved on the file system, it has
its own addressing scheme. Do we need the ability to
* The translate_name hook goes away
Wrowe altogether disagrees. translate_name today even operates
on URIs ... this mechansim needs to be preserved.
* The doc for map_to_storage is totally opaque to me. It has
something to do with filesystems, but it also talks about
security and per_dir_config and other stuff. I presume something
needs to happen there -- at least better doc.
Wrowe agrees and will write it up.
* The directory_walk concept disappears. All configuration is
tagged to Locations. The "mod_filesystem" module might have some
internal concept of the same config appearing in multiple
places, but that is handled internally rather than by Apache
Wrowe suggests this is wrong, instead it's private to filesystem
requests, and is already invoked from map_to_storage, not the core
handler. <Directory > and <Files > blocks are preserved as-is,
but <Directory > sections become specific to the filesystem handler
alone. Because alternate filesystem schemes could be loaded, this
should be exposed, from the core, for other file-based stores to
share. Consider an archive store where the layers become
<Directory path> -> <Archive store> -> <File name>
Justin: How do we map Directory entries to Locations?
* The "Location tree" is an in-memory representation of the URL
namespace. Nodes of the tree have configuration specific to that
location in the namespace.
const char *name; /* name of this node relative to parent */
struct ap_conf_vector_t *locn_config;
apr_hash_t *children; /* NULL if no child configs */
<Location /server-status>
Creates a node with name=="server_status", and the node is a
child of the "/" node. (hmm. node->name is redundant with the
hash key; maybe drop node->name)
In the config vector, mod_access has stored its Order, Deny, and
Allow configs. mod_core has stored the SetHandler.
During the Location walk, we merge the config vectors normally.
Note that an Alias simply associates a filesystem path (in
mod_filesystem) with that Location in the tree. Merging
continues with child locations, but a merge is never done
through filesystem locations. Config on a specific subdir needs
to be mapped back into the corresponding point in the Location
* Config is parsed into a tree, as we did for the 2.0 timeframe,
but that tree is just a representation of the config (for
multiple runs and for in-memory manipulation and usage). It is
unrelated to the "Location tree".
* Calls to apr_file_io functions generally need to be replaced
with operations against the ap_resource. For example, rather
resource->repos->get_children() or somesuch.
Note that things like mod_dir, mod_autoindex, and mod_negotation
need to be converted to use these mechanisms so that their
functions will work on logical repositories rather than just
* How do we handle CGI scripts? Especially when the resource may
not be backed by a file? Ideally, we should be able to come up
with some mechanism to allow CGIs to work in a
repository-independent manner.
- Writing the virtual data as a file and then executing it?
- Can a shell be executed in a streamy manner? (Portably?)
- Have an 'execute_resource'
hook/func that allows the
repository to choose its manner - be it exec() or whatever.
- Won't this approach lead to duplication of code? Helper fns?
gstein: PHP, Perl, and Python scripts are nominally executed by
But to ask further: what if it is an executable
*program* rather than just a script? Do we yank that out
of the repository, drop it onto the filesystem, and run
I'll vote -0.9 for CGIs as a filter. Keep 'em handlers.
Justin: So, do we give up executing CGIs from virtual repositories?
That seems like a sad tradeoff to make. I'd like to have
my CGI scripts under DAV (SVN) control.
* How do we handle overlaying of Location and Directory entries?
Right now, we have a problem when /cgi-bin/ is ScriptAlias'd and
mod_dav has control over /. Some people believe that /cgi-bin/
shouldn't be under DAV control, while others do believe it
should be. What's the right strategy?