Update protocol doc -- can now delete ready jobs.
[beanstalkd.git] / doc / protocol.txt
blobec37d9b036f472787b8c558fb287e9aae490c786
1 = Beanstalk Protocol =
3 Protocol
4 --------
6 The beanstalk protocol runs over TCP using ASCII encoding. Clients connect,
7 send commands and data, wait for responses, and close the connection. For each
8 connection, the server processes commands serially in the order in which they
9 were received and sends responses in the same order. All integers in the
10 protocol are formatted in decimal and (unless otherwise indicated)
11 nonnegative.
13 Names, in this protocol, are ASCII strings. They may contain letters (A-Z and
14 a-z), numerals (0-9), hyphen ("-"), plus ("+"), slash ("/"), semicolon (";"),
15 dot ("."), dollar-sign ("$"), and parentheses ("(" and ")"), but they may not
16 begin with a hyphen. They are terminated by white space (either a space char or
17 end of line). Each name must be at least one character long.
19 The protocol contains two kinds of data: text lines and unstructured chunks of
20 data. Text lines are used for client commands and server responses. Chunks are
21 used to transfer job bodies and stats information. Each job body is an opaque
22 sequence of bytes. The server never inspects or modifies a job body and always
23 sends it back in its original form. It is up to the clients to agree on a
24 meaningful interpretation of job bodies.
26 There is no command to close the connection -- the client may simply close the
27 TCP connection when it no longer has use for the server. However, beanstalkd
28 performs very well with a large number of open connections, so it is usually
29 better for the client to keep its connection open and reuse it as much as
30 possible. This also avoids the overhead of establishing new TCP connections.
32 If a client violates the protocol (such as by sending a request that is not
33 well-formed or a command that does not exist) or if the server has an error,
34 the server will reply with one of the following error messages:
36  - "OUT_OF_MEMORY\r\n" The server cannot allocate enough memory for the job.
37    The client should try again later.
39  - "INTERNAL_ERROR\r\n" This indicates a bug in the server. It should never
40    happen. If it does happen, please report it at
41    http://groups.google.com/group/beanstalk-talk.
43  - "DRAINING\r\n" This means that the server has been put into "drain mode"
44    and is no longer accepting new jobs. The client should try another server
45    or disconnect and try again later.
47  - "BAD_FORMAT\r\n" The client sent a command line that was not well-formed.
48    This can happen if the line does not end with \r\n, if non-numeric
49    characters occur where an integer is expected, if the wrong number of
50    arguments are present, or if the command line is mal-formed in any other
51    way.
53  - "UNKNOWN_COMMAND\r\n" The client sent a command that the server does not
54    know.
56 These error responses will not be listed in this document for individual
57 commands in the following sections, but they are implicitly included in the
58 description of all commands. Clients should be prepared to receive an error
59 response after any command.
61 As a last resort, if the server has a serious error that prevents it from
62 continuing service to the current client, the server will close the
63 connection.
65 Job Lifecycle
66 -------------
68 A job in beanstalk gets created by a client with the "put" command. During its
69 life it can be in one of four states: "ready", "reserved", "delayed", or
70 "buried". After the put command, a job typically starts out ready. It waits in
71 the ready queue until a worker comes along and runs the "reserve" command. If
72 this job is next in the queue, it will be reserved for the worker. The worker
73 will execute the job; when it is finished the worker will send a "delete"
74 command to delete the job.
76 Here is a picture of the typical job lifecycle:
79    put            reserve               delete
80   -----> [READY] ---------> [RESERVED] --------> *poof*
84 Here is a picture with more possibilities:
88    put with delay               release with delay
89   ----------------> [DELAYED] <------------.
90                         |                   |
91                         | (time passes)     |
92                         |                   |
93    put                  v     reserve       |       delete
94   -----------------> [READY] ---------> [RESERVED] --------> *poof*
95                        ^  ^                |  |
96                        |   \  release      |  |
97                        |    `-------------'   |
98                        |                      |
99                        | kick                 |
100                        |                      |
101                        |       bury           |
102                     [BURIED] <---------------'
103                        |
104                        |  delete
105                         `--------> *poof*
108 The system has one or more tubes. Each tube consists of a ready queue and a
109 delay queue. Each job spends its entire life in one tube. Consumers can show
110 interest in tubes by sending the "watch" command; they can show disinterest by
111 sending the "ignore" command. This set of interesting tubes is said to be a
112 consumer's "watch list". When a client reserves a job, it may come from any of
113 the tubes in its watch list.
115 When a client connects, its watch list is initially just the tube named
116 "default". If it submits jobs without having sent a "use" command, they will
117 live in the tube named "default".
119 Tubes are created on demand whenever they are referenced. If a tube is empty
120 (that is, it contains no ready, delayed, or buried jobs) and no client refers
121 to it, it will be deleted.
123 Producer Commands
124 -----------------
126 The "put" command is for any process that wants to insert a job into the queue.
127 It comprises a command line followed by the job body:
129 put <pri> <delay> <ttr> <bytes>\r\n
130 <data>\r\n
132 It inserts a job into the client's currently used tube (see the "use" command
133 below).
135  - <pri> is an integer < 2**32. Jobs with smaller priority values will be
136    scheduled before jobs with larger priorities. The most urgent priority is 0;
137    the least urgent priority is 4294967295.
139  - <delay> is an integer number of seconds to wait before putting the job in
140    the ready queue. The job will be in the "delayed" state during this time.
142  - <ttr> -- time to run -- is an integer number of seconds to allow a worker
143    to run this job. This time is counted from the moment a worker reserves
144    this job. If the worker does not delete, release, or bury the job within
145    <ttr> seconds, the job will time out and the server will release the job.
146    The minimum ttr is 1. If the client sends 0, the server will silently
147    increase the ttr to 1.
149  - <bytes> is an integer indicating the size of the job body, not including the
150    trailing "\r\n". This value must be less than max-job-size (default: 2**16).
152  - <data> is the job body -- a sequence of bytes of length <bytes> from the
153    previous line.
155 After sending the command line and body, the client waits for a reply, which
156 may be:
158  - "INSERTED <id>\r\n" to indicate success.
160    - <id> is the integer id of the new job
162  - "BURIED <id>\r\n" if the server ran out of memory trying to grow the
163    priority queue data structure.
165    - <id> is the integer id of the new job
167  - "EXPECTED_CRLF\r\n" The job body must be followed by a CR-LF pair, that is,
168    "\r\n". These two bytes are not counted in the job size given by the client
169    in the put command line.
171  - "JOB_TOO_BIG\r\n" The client has requested to put a job with a body larger
172    than max-job-size bytes.
174 The "use" command is for producers. Subsequent put commands will put jobs into
175 the tube specified by this command. If no use command has been issued, jobs
176 will be put into the tube named "default".
178 use <tube>\r\n
180  - <tube> is a name at most 200 bytes. It specifies the tube to use. If the
181    tube does not exist, it will be created.
183 The only reply is:
185 USING <tube>\r\n
187  - <tube> is the name of the tube now being used.
189 Worker Commands
190 ---------------
192 A process that wants to consume jobs from the queue uses "reserve", "delete",
193 "release", and "bury". The first worker command, "reserve", looks like this:
195 reserve\r\n
197 Alternatively, you can specify a timeout as follows:
199 reserve-with-timeout <seconds>\r\n
201 This will return a newly-reserved job. If no job is available to be reserved,
202 beanstalkd will wait to send a response until one becomes available. Once a
203 job is reserved for the client, the client has limited time to run (TTR) the
204 job before the job times out. When the job times out, the server will put the
205 job back into the ready queue. Both the TTR and the actual time left can be
206 found in response to the stats-job command.
208 A timeout value of 0 will cause the server to immediately return either a
209 response or TIMED_OUT.  A positive value of timeout will limit the amount of
210 time the client will block on the reserve request until a job becomes
211 available.
213 During the TTR of a reserved job, the last second is kept by the server as a
214 safety margin, during which the client will not be made to wait for another
215 job. If the client issues a reserve command during the safety margin, or if
216 the safety margin arrives while the client is waiting on a reserve command,
217 the server will respond with:
219 DEADLINE_SOON\r\n
221 This gives the client a chance to delete or release its reserved job before
222 the server automatically releases it.
224 TIMED_OUT\r\n
226 If a non-negative timeout was specified and the timeout exceeded before a job
227 became available, the server will respond with TIMED_OUT.
229 Otherwise, the only other response to this command is a successful reservation
230 in the form of a text line followed by the job body:
232 RESERVED <id> <bytes>\r\n
233 <data>\r\n
235  - <id> is the job id -- an integer unique to this job in this instance of
236    beanstalkd.
238  - <bytes> is an integer indicating the size of the job body, not including
239    the trailing "\r\n".
241  - <data> is the job body -- a sequence of bytes of length <bytes> from the
242    previous line. This is a verbatim copy of the bytes that were originally
243    sent to the server in the put command for this job.
245 The delete command removes a job from the server entirely. It is normally used
246 by the client when the job has successfully run to completion. A client can
247 delete jobs that it has reserved, ready jobs, and jobs that are buried. The
248 delete command looks like this:
250 delete <id>\r\n
252  - <id> is the job id to delete.
254 The client then waits for one line of response, which may be:
256  - "DELETED\r\n" to indicate success.
258  - "NOT_FOUND\r\n" if the job does not exist or is not either reserved by the
259    client, ready, or buried. This could happen if the job timed out before the
260    client sent the delete command.
262 The release command puts a reserved job back into the ready queue (and marks
263 its state as "ready") to be run by any client. It is normally used when the job
264 fails because of a transitory error. It looks like this:
266 release <id> <pri> <delay>\r\n
268  - <id> is the job id to release.
270  - <pri> is a new priority to assign to the job.
272  - <delay> is an integer number of seconds to wait before putting the job in
273    the ready queue. The job will be in the "delayed" state during this time.
275 The client expects one line of response, which may be:
277  - "RELEASED\r\n" to indicate success.
279  - "BURIED\r\n" if the server ran out of memory trying to grow the priority
280    queue data structure.
282  - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
284 The bury command puts a job into the "buried" state. Buried jobs are put into a
285 FIFO linked list and will not be touched by the server again until a client
286 kicks them with the "kick" command.
288 The bury command looks like this:
290 bury <id> <pri>\r\n
292  - <id> is the job id to release.
294  - <pri> is a new priority to assign to the job.
296 There are two possible responses:
298  - "BURIED\r\n" to indicate success.
300  - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
302 The "touch" command allows a worker to request more time to work on a job.
303 This is useful for jobs that potentially take a long time, but you still want
304 the benefits of a TTR pulling a job away from an unresponsive worker.  A worker
305 may periodically tell the server that it's still alive and processing a job
306 (e.g. it may do this on DEADLINE_SOON).
308 The touch command looks like this:
310 touch <id>\r\n
312  - <id> is the ID of a job reserved by the current connection.
314 There are two possible responses:
316  - "TOUCHED\r\n" to indicate success.
318  - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
320 The "watch" command adds the named tube to the watch list for the current
321 connection. A reserve command will take a job from any of the tubes in the
322 watch list. For each new connection, the watch list initially consists of one
323 tube, named "default".
325 watch <tube>\r\n
327  - <tube> is a name at most 200 bytes. It specifies a tube to add to the watch
328    list. If the tube doesn't exist, it will be created.
330 The reply is:
332 WATCHING <count>\r\n
334  - <count> is the integer number of tubes currently in the watch list.
336 The "ignore" command is for consumers. It removes the named tube from the
337 watch list for the current connection.
339 ignore <tube>\r\n
341 The reply is one of:
343  - "WATCHING <count>\r\n" to indicate success.
345    - <count> is the integer number of tubes currently in the watch list.
347  - "NOT_IGNORED\r\n" if the client attempts to ignore the only tube in its
348    watch list.
350 Other Commands
351 --------------
353 The peek commands let the client inspect a job in the system. There are four
354 variations. All but the first operate only on the currently used tube.
356  - "peek <id>\r\n" - return job <id>.
358  - "peek-ready\r\n" - return the next ready job.
360  - "peek-delayed\r\n" - return the delayed job with the shortest delay left.
362  - "peek-buried\r\n" - return the next job in the list of buried jobs.
364 There are two possible responses, either a single line:
366  - "NOT_FOUND\r\n" if the requested job doesn't exist or there are no jobs in
367    the requested state.
369 Or a line followed by a chunk of data, if the command was successful:
371 FOUND <id> <bytes>\r\n
372 <data>\r\n
374  - <id> is the job id.
376  - <bytes> is an integer indicating the size of the job body, not including
377    the trailing "\r\n".
379  - <data> is the job body -- a sequence of bytes of length <bytes> from the
380    previous line.
382 The kick command applies only to the currently used tube. It moves jobs into
383 the ready queue. If there are any buried jobs, it will only kick buried jobs.
384 Otherwise it will kick delayed jobs. It looks like:
386 kick <bound>\r\n
388  - <bound> is an integer upper bound on the number of jobs to kick. The server
389    will kick no more than <bound> jobs.
391 The response is of the form:
393 KICKED <count>\r\n
395  - <count> is an integer indicating the number of jobs actually kicked.
397 The stats-job command gives statistical information about the specified job if
398 it exists. Its form is:
400 stats-job <id>\r\n
402  - <id> is a job id.
404 The response is one of:
406  - "NOT_FOUND\r\n" if the job does not exist.
408  - "OK <bytes>\r\n<data>\r\n"
410    - <bytes> is the size of the following data section in bytes.
412    - <data> is a sequence of bytes of length <bytes> from the previous line. It
413      is a YAML file with statistical information represented a dictionary.
415 The stats-job data is a YAML file representing a single dictionary of strings
416 to scalars. It contains these keys:
418  - "id" is the job id
420  - "tube" is the name of the tube that contains this job
422  - "state" is "ready" or "delayed" or "reserved" or "buried"
424  - "pri" is the priority value set by the put, release, or bury commands.
426  - "age" is the time in seconds since the put command that created this job.
428  - "time-left" is the number of seconds left until the server puts this job
429    into the ready queue. This number is only meaningful if the job is
430    reserved or delayed. If the job is reserved and this amount of time
431    elapses before its state changes, it is considered to have timed out.
433  - "timeouts" is the number of times this job has timed out during a
434    reservation.
436  - "releases" is the number of times a client has released this job from a
437    reservation.
439  - "buries" is the number of times this job has been buried.
441  - "kicks" is the number of times this job has been kicked.
443 The stats-tube command gives statistical information about the specified tube
444 if it exists. Its form is:
446 stats-tube <tube>\r\n
448  - <tube> is a name at most 200 bytes. Stats will be returned for this tube.
450 The response is one of:
452  - "NOT_FOUND\r\n" if the tube does not exist.
454  - "OK <bytes>\r\n<data>\r\n"
456    - <bytes> is the size of the following data section in bytes.
458    - <data> is a sequence of bytes of length <bytes> from the previous line. It
459      is a YAML file with statistical information represented a dictionary.
461 The stats-tube data is a YAML file representing a single dictionary of strings
462 to scalars. It contains these keys:
464  - "name" is the tube's name.
466  - "current-jobs-urgent" is the number of ready jobs with priority < 1024 in
467    this tube.
469  - "current-jobs-ready" is the number of jobs in the ready queue in this tube.
471  - "current-jobs-reserved" is the number of jobs reserved by all clients in
472    this tube.
474  - "current-jobs-delayed" is the number of delayed jobs in this tube.
476  - "current-jobs-buried" is the number of buried jobs in this tube.
478  - "total-jobs" is the cumulative count of jobs created in this tube.
480  - "current-waiting" is the number of open connections that have issued a
481    reserve command while watching this tube but not yet received a response.
483 The stats command gives statistical information about the system as a whole.
484 Its form is:
486 stats\r\n
488 The server will respond:
490 OK <bytes>\r\n
491 <data>\r\n
493  - <bytes> is the size of the following data section in bytes.
495  - <data> is a sequence of bytes of length <bytes> from the previous line. It
496    is a YAML file with statistical information represented a dictionary.
498 The stats data for the system is a YAML file representing a single dictionary
499 of strings to scalars. It contains these keys:
501  - "current-jobs-urgent" is the number of ready jobs with priority < 1024.
503  - "current-jobs-ready" is the number of jobs in the ready queue.
505  - "current-jobs-reserved" is the number of jobs reserved by all clients.
507  - "current-jobs-delayed" is the number of delayed jobs.
509  - "current-jobs-buried" is the number of buried jobs.
511  - "cmd-put" is the cumulative number of put commands.
513  - "cmd-peek" is the cumulative number of peek commands.
515  - "cmd-peek-ready" is the cumulative number of peek-ready commands.
517  - "cmd-peek-delayed" is the cumulative number of peek-delayed commands.
519  - "cmd-peek-buried" is the cumulative number of peek-buried commands.
521  - "cmd-reserve" is the cumulative number of reserve commands.
523  - "cmd-use" is the cumulative number of use commands.
525  - "cmd-watch" is the cumulative number of watch commands.
527  - "cmd-ignore" is the cumulative number of ignore commands.
529  - "cmd-delete" is the cumulative number of delete commands.
531  - "cmd-release" is the cumulative number of release commands.
533  - "cmd-bury" is the cumulative number of bury commands.
535  - "cmd-kick" is the cumulative number of kick commands.
537  - "cmd-stats" is the cumulative number of stats commands.
539  - "cmd-stats-job" is the cumulative number of stats-job commands.
541  - "cmd-stats-tube" is the cumulative number of stats-tube commands.
543  - "cmd-list-tubes" is the cumulative number of list-tubes commands.
545  - "cmd-list-tube-used" is the cumulative number of list-tube-used commands.
547  - "cmd-list-tubes-watched" is the cumulative number of list-tubes-watched
548    commands.
550  - "job-timeouts" is the cumulative count of times a job has timed out.
552  - "total-jobs" is the cumulative count of jobs created.
554  - "max-job-size" is the maximum number of bytes in a job.
556  - "current-tubes" is the number of currently-existing tubes.
558  - "current-connections" is the number of currently open connections.
560  - "current-producers" is the number of open connections that have each
561    issued at least one put command.
563  - "current-workers" is the number of open connections that have each issued
564    at least one reserve command.
566  - "current-waiting" is the number of open connections that have issued a
567    reserve command but not yet received a response.
569  - "total-connections" is the cumulative count of connections.
571  - "pid" is the process id of the server.
573  - "version" is the version string of the server.
575  - "rusage-utime" is the accumulated user CPU time of this process in seconds
576    and microseconds.
578  - "rusage-stime" is the accumulated system CPU time of this process in
579    seconds and microseconds.
581  - "uptime" is the number of seconds since this server started running.
583  - "binlog-oldest-index" is the index of the oldest binlog file needed to
584    store the current jobs
586  - "binlog-current-index" is the index of the current binlog file being
587    written to. If binlog is not active this value will be 0
589  - "binlog-max-size" is the maximum size in bytes a binlog file is allowed
590    to get before a new binlog file is opened
592 The list-tubes command returns a list of all existing tubes. Its form is:
594 list-tubes\r\n
596 The response is:
598 OK <bytes>\r\n
599 <data>\r\n
601  - <bytes> is the size of the following data section in bytes.
603  - <data> is a sequence of bytes of length <bytes> from the previous line. It
604    is a YAML file containing all tube names as a list of strings.
606 The list-tube-used command returns the tube currently being used by the
607 client. Its form is:
609 list-tube-used\r\n
611 The response is:
613 USING <tube>\r\n
615  - <tube> is the name of the tube being used.
617 The list-tubes-watched command returns a list tubes currently being watched by
618 the client. Its form is:
620 list-tubes-watched\r\n
622 The response is:
624 OK <bytes>\r\n
625 <data>\r\n
627  - <bytes> is the size of the following data section in bytes.
629  - <data> is a sequence of bytes of length <bytes> from the previous line. It
630    is a YAML file containing watched tube names as a list of strings.