3 Last modified at [$Date: 2002/10/18 16:58:14 $]
8 The Apache HTTP Server project must balance two competing and disjoint
9 objectives: maintain stable code for third party authors, distributors and
10 most importantly users so that bug and security fixes can be quickly adopted
11 without significant hardship due to user-visible changes; and continue the
12 development process that requires ongoing redesign to correct earlier
13 oversights and to add additional features.
15 The Apache HTTP Server, through version 2.0, used the Module Magic Number (MMN)
16 to reflect API changes. This had the shortcoming of often leaving users
17 hunting to replace binary third party modules that were now incompatible.
18 This also left module authors searching through the API change histories to
19 determine the exact cause for the MMN change and whether their module was
22 With the simultaneous release of Apache 2.2-stable and Apache 2.3-development,
23 the Apache HTTP Server project is moving towards a more predictable stable
24 release cycle, while allowing forward progress to occur without concern
25 for breaking the stable branch. This document explains the rationale between
26 the two versions and their behavior.
29 STABLE RELEASES, 2.{even}.{revision}
30 ------------------------------------
32 All even numbered releases will be considered stable revisions.
34 Stable revisions will retain forward compatiblity to the maximum
35 possible extent. Features may be added during minor revisions, and
36 features may be deprecated by making appropriate notations in the
37 documentation, but no features may be removed.
39 In essence, that implies that you can upgrade from one minor revision
40 to the next with a minimum of trouble. In particular, this means:
42 * The Module API will retain forward compatibility.
43 It will not be necessary to update modules to work with new
44 revisions of the stable tree.
46 * The run-time configuration will be forward compatible.
47 No configuration changes will be necessary to work with new
48 revisions of the stable tree.
50 * Compile-time configuration will be forward compatible.
51 The configure command line options that work in one release
52 of the stable tree will also work in the next release.
54 As always, it will be necessary to test any new release to assure
55 that it works correctly with a particular configuration and a
56 particular set of modules, but every effort will be made to assure
57 that upgrades are as smooth as possible.
59 In addition, the following development restrictions will aid in
60 keeping the stable tree as safe as possible:
62 * No 'Experimental' modules; while it may be possible (based on API changes
63 required to support a given module) to load a 2.3-development module into
64 a 2.2-stable build of Apache, there are no guarantees. Experimental
65 modules will be introduced to the 2.3-development versions and either
66 added to 2.2-stable once they are proven and compatible, or deferred
67 to the 2.4-stable release if they cannot be incorporated in the current
68 stable release due to API change requirements.
70 * The stable CVS tree should not remain unstable at any time. Atomic commits
71 aught be used to introduce code from the development version to the stable
72 tree. At any given time a security release may be in preparation,
73 unbeknownst to other contributors. At any given time, testers may be
74 checking out CVS head to confirm that a bug has been corrected. And as
75 all code was well-tested in development prior to committing to the stable
76 tree, there is really no reason for this tree to be broken for more than
77 a few minutes during a lengthy commit.
80 DEVELOPMENT RELEASES, 2.{odd}.{revision}
81 -----------------------------------------
83 All odd numbered releases designate the 'next' possible stable release,
84 therefore the current development version will always be one greater than
85 the current stable release. Work proceeds on development releases, permitting
86 the modification of the MMN at any time in order to correct deficiencies
87 or shortcomings in the API. This means that modules from one development
88 release to another may not be binary compatible, or may not successfully
89 compile without modification to accomodate the API changes.
91 The only 'supported' development release at any time will be the most
92 recently released version. Developers will not be answering bug reports
93 of older development releases once a new release is available. It becomes
94 the resposibility of the reporter to use the latest development version
95 to confirm that any issue still exists.
97 Any new code, new API features or new ('experimental') modules may be
98 promoted at any time to the next stable release, by a vote of the project
99 contributors. This vote is based on the technical stability of the new
100 code and the stability of the interface. Once moved to stable, that feature
101 cannot change for the remainder of that stable release cycle, so the vote must
102 reflect that the final decisions on the behavior and naming of that new
103 feature were reached. Vetos continue to apply to this choice of introducing
104 the new work to the stable version.
106 At any given time, when the quality of changes to the development branch
107 is considered release quality, that version may become a candidate for the
108 next stable release. This includes some or all of the API changes, promoting
109 experimental modules to stable or deprecating and eliminating older modules
110 from the last stable release. All of these choices are considered by the
111 project as a group in the interests of promoting the stable release, so that
112 any given change may be 'deferred' for a future release by the group, rather
113 than introduce unacceptable risks to adopting the next stable release.
115 Third party module authors are strongly encouraged to test with the latest
116 development version. This assures that the module will be ready for the next
117 stable release, but more importantly, the author can react to shortcomings
118 in the API early enough to warn the dev@httpd.apache.org community of the
119 shortcomings so that they can be addressed before the stable release. The
120 entire burden is on the module author to anticipate the needs of their module
121 before the stable release is created. Once a new stable release cycle has
122 begun, that API will be present for the lifetime of the stable release. Any
123 desired changes in the stable versions must wait for inclusion into the next
129 In order to avoid 'skipped' release numbers, the Release Manager will generally
130 roll a release candidate (APACHE_#_#_#_RC#) tag. This is true of both the
131 stable as well as the development tree. Release Candidate tarballs will be
132 announced to the stable-testers@httpd.apache.org for the stable tree, or to
133 the current-testers@httpd.apache.org list for the development tree.
135 The final APACHE_#_#_# tag will not exist until the APACHE_#_#_#_RC# candidate
136 has passed the usual votes to release that version. Only then is the final
137 tarball packaged, removing all -rc# designations from the version number, and
138 tagging the tree with the release number.
144 * Source code should follow style guidelines.
145 OK, we all agree pretty code is good. Probably best to clean this
146 up by hand immediately upon branching a 2.1 tree.
147 Status: Justin volunteers to hand-edit the entire source tree ;)
150 Recall when the release plan for 2.0 was written:
151 Absolute Enforcement of an "Apache Style" for code.
152 Watch this slip into 3.0.
155 The style guide needs to be reviewed before this can be done.
156 http://httpd.apache.org/dev/styleguide.html
157 The current file is dated April 20th 1998!
160 It's survived since '98 because it's welldone :-) Suggest we
161 simply follow whatever is documented in styleguide.html as we
162 branch the next tree. Really sort of straightforward, if you
163 dislike a bit within that doc, bring it up on the dev@httpd
164 list prior to the next branch.
166 So Bill sums up ... let's get the code cleaned up in CVS head.
167 Remember, it just takes cvs diff -b (that is, --ignore-space-change)
168 to see the code changes and ignore that cruft. Get editing Justin :)
170 * revamp the input filter syntax to provide for ordering of
171 filters created with the Set{Input|Output}Filter and the
172 Add{Input|Output}Filter directives. A 'relative to filterx'
173 syntax is definately preferable.
175 * Platforms that do not support fork (primarily Win32 and AS/400)
176 Architect start-up code that avoids initializing all the modules
177 in the parent process on platforms that do not support fork.
179 . Better yet - not only inform the startup of which phase it's in,
180 but allow the parent 'process' to initialize shared memory, etc,
181 and create a module-by-module stream to pass to the child, so the
182 parent can actually arbitrate the important stuff.
184 * Replace stat [deferred open] with open/fstat in directory_walk.
185 Justin, Ian, OtherBill all interested in this. Implies setting up
186 the apr_file_t member in request_rec, and having all modules use
187 that file, and allow the cleanup to close it [if it isn't a shared,
190 * The Async Apache Server implemented in terms of APR.
191 [Bill Stoddard's pet project.]
192 Message-ID: <008301c17d42$9b446970$01000100@sashimi> (dev@apr)
194 OtherBill notes that this can proceed in two parts...
196 Async accept, setup, and tear-down of the request
197 e.g. dealing with the incoming request headers, prior to
198 dispatching the request to a thread for processing.
199 This doesn't need to wait for a 2.x/3.0 bump.
201 Async delegation of the entire request processing chain
202 Too many handlers use stack storage and presume it is
203 available for the life of the request, so a complete
204 async implementation would need to happen 3.0 release.
206 * Add a string "class" that combines a char* with a length
207 and a reference count. This will help reduce the number
208 of strlen and strdup operations during request processing.
209 Including both the length and allocation will save us a ton
210 of reallocation we do today, in terms of string manipulation.
212 OtherBill asks if this is really an APR issue, not an HTTPD issue?
215 MAKING APACHE REPOSITORY-AGNOSTIC
216 (or: remove knowledge of the filesystem)
218 [ 2002/10/01: discussion in progress on items below; this isn't
221 * dav_resource concept for an HTTP resource ("ap_resource")
223 * r->filename, r->canonical_filename, r->finfo need to
224 disappear. All users need to use new APIs on the ap_resource
227 (backwards compat: today, when this occurs with mod_dav and a
228 custom backend, the above items refer to the topmost directory
229 mapped by a location; e.g. docroot)
231 Need to preserve a 'filename'-like string for mime-by-name
232 sorts of operations. But this only needs to be the name itself
235 Justin: Can we leverage the path info, or do we not trust the
238 gstein: well, it isn't the "path info", but the actual URI of
239 the resource. And of course we trust the user... that is
240 the resource they requested.
242 dav_resource->uri is the field you want. path_info might
243 still exist, but that portion might be related to the
244 CGI concept of "path translated" or some other further
247 To continue, I would suggest that "path translated" and
248 having *any* path info is Badness. It means that you did
249 not fully resolve a resource for the given URI. The
250 "abs_path" in a URI identifies a resource, and that
251 should get fully resolved. None of this "resolve to
252 <here> and then we have a magical second resolution
253 (inside the CGI script)" or somesuch.
255 Justin: Well, let's consider mod_mbox for a second. It is sort of
256 a virtual filesystem in its own right - as it introduces
257 it's own notion of a URI space, but it is intrinsically
258 tied to the filesystem to do the lookups. But, for the
259 portion that isn't resolved on the file system, it has
260 its own addressing scheme. Do we need the ability to
263 * The translate_name hook goes away
265 Wrowe altogether disagrees. translate_name today even operates
266 on URIs ... this mechansim needs to be preserved.
268 * The doc for map_to_storage is totally opaque to me. It has
269 something to do with filesystems, but it also talks about
270 security and per_dir_config and other stuff. I presume something
271 needs to happen there -- at least better doc.
273 Wrowe agrees and will write it up.
275 * The directory_walk concept disappears. All configuration is
276 tagged to Locations. The "mod_filesystem" module might have some
277 internal concept of the same config appearing in multiple
278 places, but that is handled internally rather than by Apache
281 Wrowe suggests this is wrong, instead it's private to filesystem
282 requests, and is already invoked from map_to_storage, not the core
283 handler. <Directory > and <Files > blocks are preserved as-is,
284 but <Directory > sections become specific to the filesystem handler
285 alone. Because alternate filesystem schemes could be loaded, this
286 should be exposed, from the core, for other file-based stores to
287 share. Consider an archive store where the layers become
288 <Directory path> -> <Archive store> -> <File name>
290 Justin: How do we map Directory entries to Locations?
292 * The "Location tree" is an in-memory representation of the URL
293 namespace. Nodes of the tree have configuration specific to that
294 location in the namespace.
299 const char *name; /* name of this node relative to parent */
301 struct ap_conf_vector_t *locn_config;
303 apr_hash_t *children; /* NULL if no child configs */
306 The following config:
308 <Location /server-status>
309 SetHandler server-status
315 Creates a node with name=="server_status", and the node is a
316 child of the "/" node. (hmm. node->name is redundant with the
317 hash key; maybe drop node->name)
319 In the config vector, mod_access has stored its Order, Deny, and
320 Allow configs. mod_core has stored the SetHandler.
322 During the Location walk, we merge the config vectors normally.
324 Note that an Alias simply associates a filesystem path (in
325 mod_filesystem) with that Location in the tree. Merging
326 continues with child locations, but a merge is never done
327 through filesystem locations. Config on a specific subdir needs
328 to be mapped back into the corresponding point in the Location
329 tree for proper merging.
331 * Config is parsed into a tree, as we did for the 2.0 timeframe,
332 but that tree is just a representation of the config (for
333 multiple runs and for in-memory manipulation and usage). It is
334 unrelated to the "Location tree".
336 * Calls to apr_file_io functions generally need to be replaced
337 with operations against the ap_resource. For example, rather
338 than calling apr_dir_open/read/close(), a caller uses
339 resource->repos->get_children() or somesuch.
341 Note that things like mod_dir, mod_autoindex, and mod_negotation
342 need to be converted to use these mechanisms so that their
343 functions will work on logical repositories rather than just
346 * How do we handle CGI scripts? Especially when the resource may
347 not be backed by a file? Ideally, we should be able to come up
348 with some mechanism to allow CGIs to work in a
349 repository-independent manner.
351 - Writing the virtual data as a file and then executing it?
352 - Can a shell be executed in a streamy manner? (Portably?)
353 - Have an 'execute_resource' hook/func that allows the
354 repository to choose its manner - be it exec() or whatever.
355 - Won't this approach lead to duplication of code? Helper fns?
357 gstein: PHP, Perl, and Python scripts are nominally executed by
358 a filter inserted by mod_php/perl/python. I'd suggest
359 that shell/batch scripts are similar.
361 But to ask further: what if it is an executable
362 *program* rather than just a script? Do we yank that out
363 of the repository, drop it onto the filesystem, and run
366 I'll vote -0.9 for CGIs as a filter. Keep 'em handlers.
368 Justin: So, do we give up executing CGIs from virtual repositories?
369 That seems like a sad tradeoff to make. I'd like to have
370 my CGI scripts under DAV (SVN) control.
372 * How do we handle overlaying of Location and Directory entries?
373 Right now, we have a problem when /cgi-bin/ is ScriptAlias'd and
374 mod_dav has control over /. Some people believe that /cgi-bin/
375 shouldn't be under DAV control, while others do believe it
376 should be. What's the right strategy?