From 34611f252fdc66c1a4d6ac259a89e06119981ba1 Mon Sep 17 00:00:00 2001
From: franck cuny <franck@lumberjaph.net>
Date: Sat, 15 May 2010 17:40:46 +0200
Subject: clean POD, move spec to appropriate class

---
 lib/presque.pm | 109 ++++++++++-----------------------------------------------
 1 file changed, 19 insertions(+), 90 deletions(-)

(limited to 'lib/presque.pm')

diff --git a/lib/presque.pm b/lib/presque.pm
index 0940810..309898f 100644
--- a/lib/presque.pm
+++ b/lib/presque.pm
@@ -48,15 +48,21 @@ __END__
 
 =head1 NAME
 
-presque - a redis based message queue
+presque - a redis/tatsumaki based message queue
 
 =head1 SYNOPSIS
 
 =head1 DESCRIPTION
 
-presque is a message queue system based on Tatsumaki and Redis.
+presque is a persistent job queue that uses Redis for storage and Tatsumaki for the interface between workers and Redis.
 
-The functionalities are inspired by L<RestMQ|http://github.com/gleicon/restmq> and the name by L<resque|http://github.com/defunkt/resque>.
+presque implement a REST interface for communications, and jobs are JSON data structure.
+
+Workers can be written in any language as long as they implement the REST interface. A complete worker exists for Perl L<presque::worker>. Some examples in other languages can be found in the B<eg> directory.
+
+The functionalities are inspired by L<RestMQ|http://github.com/gleicon/restmq> and L<resque|http://github.com/defunkt/resque>.
+
+=head2 HTTP ROUTES
 
 The following HTTP routes are available:
 
@@ -78,9 +84,9 @@ re-insert a job after a worker failed to process the job
 
 purge and delete the queue
 
-=item B<GET /status/(queuename)>
+=item B<GET /status/>
 
-If no queuename is given, return a list of queues. If queuename is given, return the size of the queue and the current policy.
+informations about a queue.
 
 =item B<GET /j/queuename>
 
@@ -94,107 +100,30 @@ return the status of the queue. A queue have two statues: open or closed. When a
 
 change the status of the queue.
 
-=item B<GET /w/(?[worker_id|queue_name])>
+=item B<GET /w/>
 
-If no argument is given, return some stats about workers. If a worker_id is given, return stats about the specific worker. If a queue name is given return stats about the workers on this queue.
+some statisctics about a worker
 
-=item B<POST /w/queue_name?worker_id>
+=item B<POST /w/queuename>
 
 register a worker on a queue.
 
-=item B<DELETE /w/queue_name?worker_id>
+=item B<DELETE /w/queue_name>
 
 unregister a worker on a queue.
 
 =back
 
-=head1 USAGE
-
-=head2 WORKERS INTERFACE
-
-It's possible for a worker to register itself against presque. This is not required. The main purpose of registering workers is to collect informations about your workers : what are they doing right now, how many jobs have they failed, how many jobs have they processed, ...
-
-=head3 REGISTER A WORKER
-
-To register a worker, a POST request must be made. The content of the POST must be a JSON structure that contains the key B<worker_id>.
-
-    curl -H 'Content-Type: appplication/json' http://localhost:5000/w/foo -d '{"worker_id":"myworker_1"}
-
-The HTTP response is 201, and no content is returned.
-
-=head3 STATISTICS
-
-When a worker is registered, statistics about this worker are collected.
-
-    curl "http://localhost:5000/w/?worker_id=myworker_1" | json_xs -f json -t json-pretty
-
-    {
-        "worker_id" : "myworker_1",
-        "started_at" : 1273923534,
-        "processed" : "0",
-        "failed" : "0"
-    }
-
-=head3 UNREGISTER A WORKER
-
-When a worker has finished to work, it should unregister itself:
-
-    curl -X DELETE "http://localhost:5000/w/foo?worker_id=myworker_1"
-
-The response HTTP code is 204, and no content is returned.
-
-=head2 JOB INTERFACE
-
-=head3 INSERT A JOB
-
-The B<Content-Type> of the request must be set to B<application/json>. The body of the request must be a valid JSON object.
-
-    curl -H 'Content-Type: application/json' -X POST "http://localhost:5002/q/foo" -d '{"key":"value"}'
-
-It's possible to create delayed jobs (eg: job that will not be run before a defined time in the futur).
-
-    curl -H 'Content-Type: application/json' -X POST "http://localhost:5002/q/foo?delayed="$(expr `date +%s` + 500) -d '{"key":"value"}'
-
-the B<delayed> value should be a date in epoch
-
-=head3 FETCH A JOB
-
-Return a JSON object
-
-   curl http://localhost:5002/q/foo
-
-=head3 PURGE AND DELETE A QUEUE
-
-   curl -X DELETE http://localhost:5002/q/foo
-
-=head2 CHANGE THE POLICY OF A QUEUE
-
-By default, when a queue is created, the status is set to 'open'. When a queue is set to 'stop', no job will be fetched from the queue.
-
-To stop a queue:
-
-    curl -X POST -H 'Content-Type: application/json' -d '{"status":"stop"}' http://localhost:5000/control/foo
-
-    {"response":"updated","queue":"foo"}
-
-To re-open a queue:
-
-    curl -X POST -H 'Content-Type: application/json' -d '{"status":"start"}' http://localhost:5000/control/foo
-
-To fetch the status of a queue:
-
-    curl http://localhost:5000/control/foo
-
-    {"status":"0","queue":"foo"}
-
-=head2 GET SOME STATUS ABOUT A QUEUE
-
 =head1 AUTHOR
 
 franck cuny E<lt>franck@lumberjaph.netE<gt>
 
 =head1 SEE ALSO
 
+For a complete description of each routes, refer to L<presque::WorkerHandler>, L<presque::RestQueueHandler>, L<presque::ControlHandler>, L<JobQueueHandler>, L<presque::StatusHandler>.
+
+For a complete worker see L<presque::worker>.
+
 =head1 LICENSE
 
 Copyright 2010 by Linkfluence
-- 
cgit 1.4.1