Access key module

[Grzegorz Nosek]

On Mon, Dec 31, 2007 at 12:55:23PM +0100, Manlio Perillo wrote:
> I think that each external module should be kept separate from nginx "core".
> 
> An example is my mod_wsgi module, where I provide support for several 
> nginx version using patches.

I think that it might be useful to keep an official contrib module list.
If nothing else, it should increase confidence in these modules.

The directory layout could look e.g. like:
src/ (nginx source)
contrib/
 mod_wsgi-0.5/
 mod_wsgi-0.6/
 upstream_fair/
 whatever/

We could/should also keep some metadata about the modules (required
nginx version, required extra libraries, etc.) in an easily parsable
format for some future tool to include them in the build process (maybe
patch-o-matic style but simpler).

I'm not going to fight about putting them in a single tree (though I'd
like it), but I think they should all be accessible from a single place
with a unified interface. IMO this makes them look more polished than a
bunch of links (an svn here, a tarball there etc.). However, this would
require a certain amount of coordination between module authors.

> >I think that an official repository (with vanilla and all the contrib
> >modules in one tree), with some nice bug tracker (trac indeed would be
> >fine) would help. This could also become a place for collecting
> >development documentation (i.e. internal APIs, ways to do things
> >nginx-style, common coding pitfalls, FAQs etc.) which is too technical
> >to put it on the main wiki.
> 
> This would be a great thing, but we need the collaboration of Igor, 
> otherwise I would consider it just a fork of nginx.

Yes, Igor's blessing would be neccessary for the project to be deemed
official. However, if we aggregated some third-party modules and
provided a common interface to them, I'd be reluctant to call it a fork.
A frontend or "community edition" maybe. Realistically, we cannot expect
Igor to maintain the external modules, so the level of support we'd
*need* would be "lack of open hostility" ;) and accepting bug reports
from the tracker. Of course, his input into the documentation would be
invaluable.

> >The "Guide to Nginx Module Development" is a great document but I
> >think that the community could extend it even further, e.g. I'm
> >currently up to date with nginx's shared memory support (which needs
> >getting used to) and load balancer interface, Manlio with his mod_wsgi
> >could probably write a lot of interesting stuff etc.

> Yes, with mod_wsgi I have learned a lot of nginx internals ;-).

I bet :) upstream_fair is a pretty small module but I had to dig through
almost all the nginx code to get it up to shape.

> Unfortunately I'm not very good at writing documentation.

 - Hi, I'm Greg, and I'm a bad writer too.
 - (all together) Hi, Greg!

> However I can start to write single documentation pages for each of the 
> nginx "public" headers, and some documentation page for nginx 
> "astractions" and main concepts (events, process channels, buffer 
> chains, modules and configuration).

I think that documenting headers is less useful than the bigger picture.
This is IMHO a major deficiency in many OSS projects, which document
every class/function via doxygen and call it a day. E.g. to use shared
memory in nginx, you need not only to allocate a segment and use it, but
also wire it up in such a way that subsequent reloads don't trash it
or cause leaks etc. Even the best documentation for a single function
won't cut it (again, IMHO). I'd like the documentation to be
task-oriented, i.e. "How do I write a handler?", "When and how should I
use rbtrees?", etc. It could then serve as a sequel to the Guide.

Best regards,
 Grzegorz Nosek