Access key module

[Evan Miller]

Grzegorz Nosek wrote:
> 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 sure we'd need metadata. Modules should be guaranteed to work 
with the Nginx version they ship with, and they can do their own library 
  checking in their config scripts. (E.g. my Circle GIF module checks 
for ImageMagick during ./configure.)

> 
> 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 too would prefer that the modules sit in a single tree. Perhaps a good 
model is the Linux kernel: they have hundreds of modules written and 
maintained by different people, but each one is approved by a number of 
people before shipping. I personally think that most non-Igor modules 
should sit in the main tree (src/http/modules), and the --add-module 
mechanism should be used only for one-off or proprietary modules that 
are privately maintained.

> 
>>> 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.

We should talk to Igor about his attitude toward third-party modules. I 
imagine he just doesn't have time to inspect, test, and integrate them. 
If it makes things easier, I'd be willing to consolidate our modules 
into a "community edition" and work with Igor to get changes accepted 
upstream.

> 
>>> 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.

Yes, it's time we had something more flexible than the Guide. I would 
like both a low-level API reference and a high-level document more like 
the Guide. For the low-level stuff, I think something like javadoc 
parsed from the code would work best. (Another task for the "community 
edition"?) For the high-level stuff, I rather like how the Django book 
does it:

http://www.djangobook.com/en/1.0/

Each chapter has an individual author, but then anyone can leave 
comments in the margins. I'd prefer this model to a wiki because 
high-level guides are difficult to write, and their authors deserve 
credit for their work.

Evan

> 
> Best regards,
>  Grzegorz Nosek
> 
> 
>