[cgiapp] What to do about a documentation mismatch

[Nicholas Bamber]

I am still working my way through all the code in 
CGI::Application::Plugin::Authentication. I'm mainly concentrating on 
getting the test coverage up at the moment. In that I have found what I 
believe is a mismatch between the documentation and the code. The issue 
is with custom filters and arguably there are two bugs.

1.) Standard filters can take "parameters" and the documentation does 
not explain that parameters are not supported for custom filters.
2.) The example custom filter takes only one argument which is taken to 
be a credential (a password in fact). According to the code it should 
take the first argument to be a "parameter".

Now if I make the code fit the documentation I have to risk breaking 
some code and also make it clear that custom filters do not take 
parameters. If change the documentation then I should also add support 
for parameters. However I am not clear that parameters in general do 
much. As I understand it is only really used for "crypt" functionality.

I should really own up and say I have some philosophical issues with 
this filter stuff. It's mostly designed to work with the DBI driver but 
I do not agree with the DBI driver's approach. I think an authentication 
driver should be a robust implementation of a specific trusted 
authentication algorithm. The DBI driver instead tries to be a lego set 
of authentication bricks. I think this approach is doomed because not 
only does the implentation have to be good, but the specific 
configuration must be as well.

So my long term plan is:
1.) Do the best that can be done with the DBI driver.
2.) Provide a robust driver as soon as I am confident I can produce one. 
It stills needs to be flexible but probably not as flexible as the DBI 
driver. I would like to copy the algorithm from ESAPI but they have not 
finalized their guidelines.
3.) Deprecate the DBI driver.

In the meantime I am taking the code as I find it.