NAME

  qdb-cgi - service http qdb requests

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 ;

DESCRIPTION

Program qdb-cgi is a cgi script that handles qdb requests.

The following is the help-message of the script.

Intro

This service provides access to CPAN's update history.

CPAN's update history is a list of events.
An event is a tuple : [ id, type, path ] ; where
- id is some meaningless, (auto-increment) unique number,
- type is either new or delete,
- path is a filesystem path in CPAN.
The history is updated by adding events.
In the history, $path is unique ; there can only be one event per $path.

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

Usage

To use the service, you must issue a 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 $err is defined, then

$res is not defined, and
the http status code is 400 Bad Request.

Requests

database queries

count

The result is the number of events in the history.

Example : http://server/cgi-bin/qdb/count

first_id

The result is the id of the first event.

Example : http://server/cgi-bin/qdb/first_id

last_id

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

Example : http://server/cgi-bin/qdb/last_id

from/$n

The result is an id-ordered list of the oldest events with id ≥ $n ;

at most 1000 events are returned.

Example : http://server/cgi-bin/qdb/from/7000

from/$n/limit/$x

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

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

last/$x

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

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

path/$path

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

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

filesystem queries

stat/$path

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

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

lstat/$path

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

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

readlink/$path

The result is readlink "/path/to/cpan/$path"

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

type/$path

The result is file, link, dir, other or undef.

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

Notes

Updates of the RECENT files are not represented in the event-stream. Updates of the RECENT files must be reflected in the the qdb-database, so qdb-based rrr-clients know when to re-sync them.
a downstream server is always a sleeping beauty, although she normally only sleeps for a few minutes. Does a downstream server has to keep its own history? Or can queries be truthfully answered, given some valid local last_id?

FILES

  /etc/qdb/conf : qdb-configuration

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.