README and TODO

1 files changed, 77 insertions, 7 deletions

diff --git a/README b/README
index 979d838..0db2272 100644
--- a/README
+++ b/README
@@ -5,7 +5,7 @@ SYNOPSIS
 DESCRIPTION
     presque is a message queue system based on Tatsumaki and Redis.
 
-    It's functionality are inspired by RestMQ
+    The functionalities are inspired by RestMQ
     <http://github.com/gleicon/restmq> and the name by resque
     <http://github.com/defunkt/resque>.
 
@@ -17,12 +17,15 @@ DESCRIPTION
     POST /q/queuename
         insert an object in the queue
 
+    PUT /q/queuename
+        re-insert a job after a worker failed to process the job
+
     DELETE /q/queuename
         purge and delete the queue
 
-    GET /stats/[queuename]
-        return some statues about the queue. If no queue is given, return
-        basic statues about all the queues.
+    GET /status/(queuename)
+        If no queuename is given, return a list of queues. If queuename is
+        given, return the size of the queue and the current policy.
 
     GET /j/queuename
         return some basic information about a queue.
@@ -35,7 +38,53 @@ DESCRIPTION
     POST /control/queuename
         change the status of the queue.
 
-  INSERT A JOB
+    GET /w/(?[worker_id|queue_name])
+        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.
+
+    POST /w/queue_name?worker_id
+        register a worker on a queue.
+
+    DELETE /w/queue_name?worker_id
+        unregister a worker on a queue.
+
+USAGE
+  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, ...
+
+   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 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.
+
+   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"
+        }
+
+   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.
+
+  JOB INTERFACE
+   INSERT A JOB
     The Content-Type of the request must be set to application/json. The
     body of the request must be a valid JSON object.
 
@@ -48,14 +97,35 @@ DESCRIPTION
 
     the delayed value should be a date in epoch
 
-  FETCH A JOB
+   FETCH A JOB
     Return a JSON object
 
        curl http://localhost:5002/q/foo
 
-  PURGE AND DELETE A QUEUE
+   PURGE AND DELETE A QUEUE
        curl -X DELETE http://localhost:5002/q/foo
 
+  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"}
+
+  GET SOME STATUS ABOUT A QUEUE
 AUTHOR
     franck cuny <franck@lumberjaph.net>