=pod

=head1 NAME

  qdb-cgi - service http qdb requests

=head1 SYNOPSIS

  Usage: qdb.cgi [-v] [-q] [-d] [-h] [-t [arg] ]
  option v : be verbose
  option q : be quiet
  option d : show debug info
  option h : show help
  option t : test ; set $ENV{PATH_INFO} = $arg ;

=head1 DESCRIPTION

Program B<qdb-cgi> is a cgi script that handles L<qdb|http://archive.science.uu.nl/pub/PERL/qdb-dev/qdb.html> requests.

The following is the help-message of the script.


=head2 Intro

This service provides access to CPAN's update history.

=over 4

=item *

CPAN's update history is a list of I<events>.

=item *

An I<event> is a tuple :
C<[> I<id>, I<type>, I<path> C<]> ;
where

=over 4

=item *

I<id> is some meaningless, (auto-increment) unique number,

=item *

I<type> is either C<new> or C<delete>,

=item *

I<path> is a filesystem path in CPAN.

=back


=item *

The history is updated by adding events.

=item *

In the history, I<$path> is I<unique> ;
there can only be one event per I<$path>.

When a I<$path>-event is added,
it replaces a previous I<$path>-event.


=back


=head2 Usage

To use the service, you must issue a I<web-request> ;
see the next section for an overview.

Each request returns a json-text :


  { "cmd" : ...  # the request
  , "err" : ...  # any errors found
  , "res" : ...  # the result
  }


If I<$err> is defined, then

=over 4

=item *

I<$res> is not defined, and

=item *

the I<http status code> is I<400 Bad Request>.

=back


=head2 Requests


=head3 database queries


=over 4

=item C<count>

The result is the number of events in the history.

Example : C<http://server/cgi-bin/qdb/C<count>>



=item C<first_id>

The result is the I<id> of the first event.

Example : C<http://server/cgi-bin/qdb/C<first_id>>



=item C<last_id>

The result is the I<id> of the last (most recent) event.

Example : C<http://server/cgi-bin/qdb/C<last_id>>



=item C<from/>I<$n>

The result is an I<id>-ordered list of the oldest events
with I<id &ge; $n> ;

at most 1000 events are returned.

Example :
C<http://server/cgi-bin/qdb/C<from/7000>>



=item C<from/>I<$n>C</limit/>I<$x>

same as C<from/> but at most I<min($x,1000)>
events are returned.

Example :
C<http://server/cgi-bin/qdb/C<from/7000/limit/8>>


=item C<last/>I<$x>

The result is an I<id>-ordered list
of the last I<min($x,1000)> events.

Examples :
C<http://server/cgi-bin/qdb/C<last/8>> ;
C<http://server/cgi-bin/qdb/C<last/32>>


=item C<path/>I<$path>

The result is a list of (0 or 1) events pertaining to $path.

Example :
C<http://server/cgi-bin/qdb/C<path/src/stable.tar.bz2>>


=back


=head3 filesystem queries


=over 4

=item C<stat/>I<$path>

The result is C<[stat "/path/to/cpan/$path"]>

Example :
C<http://server/cgi-bin/qdb/C<stat/src/stable.tar.bz2>>


=item C<lstat/>I<$path>

The result is C<[lstat "/path/to/cpan/$path"]>

Example :
C<http://server/cgi-bin/qdb/C<lstat/src/stable.tar.bz2>>


=item C<readlink/>I<$path>

The result is C<readlink "/path/to/cpan/$path">

Example :
C<http://server/cgi-bin/qdb/C<readlink/src/stable.tar.bz2>>


=item C<type/>I<$path>

The result is
C<file>,
C<link>,
C<dir>,
C<other> or
C<undef>.

Example :
C<http://server/cgi-bin/qdb/C<type/src/stable.tar.bz2>>


=back


=head2 Notes


=over 4

=item *

Updates of the I<RECENT> files are not represented in
the event-stream.
Updates of the I<RECENT> files must be reflected in the
the qdb-database, so qdb-based I<rrr>-clients know when
to re-sync them.


=item *

a I<downstream> server is always a I<sleeping beauty>,
although she normally only sleeps for a few minutes.
Does a I<downstream> server has to keep its own history?
Or can queries be truthfully answered,
given some valid local C<I<last_id>>?


=back


=head1 FILES

  /etc/qdb/conf : qdb-configuration

=head1 SEE ALSO

L<qdb|http://archive.science.uu.nl/pub/PERL/qdb-dev/qdb.html>, L<qdb-fsck|http://archive.science.uu.nl/pub/PERL/qdb-dev/qdb-fsck.html>, L<qdb-send|http://archive.science.uu.nl/pub/PERL/qdb-dev/qdb-send.html>


=head1 LICENSE

You may distribute under the terms of either the GNU General Public
License or the Artistic License, as specified in the Perl 5.10.0 README
file.

=head1 AUTHOR

=for html qdb-cgi &copy; 2015-2017
<a href="http://www.staff.science.uu.nl/~penni101">Henk P. Penning</a>
- All rights reserved
; qdb-0.04-p12 - Sat Jan 21 11:22:02 2017

=for man Henk P. Penning, <http://www.staff.science.uu.nl/~penni101> ;
qdb-0.04-p12 - Sat Jan 21 11:22:02 2017


=cut