doc/protocol.txt

   1 = Beanstalk Protocol =
   2
   3 Protocol
   4 --------
   5
   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.
  12
  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.
  18
  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.
  25
  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.
  31
  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:
  35
  36  - "OUT_OF_MEMORY\r\n" The server cannot allocate enough memory for the job.
  37    The client should try again later.
  38
  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.
  42
  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.
  46
  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.
  52
  53  - "UNKNOWN_COMMAND\r\n" The client sent a command that the server does not
  54    know.
  55
  56  - "EXPECTED_CRLF\r\n" The job body must be followed by a CR-LF pair, that is,
  57    "\r\n". These two bytes are not counted in the job size given by the client
  58    in the put command line.
  59
  60  - "JOB_TOO_BIG\r\n" The client has requested to put a job with a body larger
  61    than 2**16 bytes.
  62
  63 These error responses will not be listed in this document for individual
  64 commands in the following sections, but they are implicitly included in the
  65 description of all commands. Clients should be prepared to receive an error
  66 response after any command.
  67
  68 As a last resort, if the server has a serious error that prevents it from
  69 continuing service to the current client, the server will close the
  70 connection.
  71
  72 Job Lifecycle
  73 -------------
  74
  75 A job in beanstalk gets created by a client with the "put" command. During its
  76 life it can be in one of four states: "ready", "reserved", "delayed", or
  77 "buried". After the put command, a job typically starts out ready. It waits in
  78 the ready queue until a worker comes along and runs the "reserve" command. If
  79 this job is next in the queue, it will be reserved for the worker. The worker
  80 will execute the job; when it is finished the worker will send a "delete"
  81 command to delete the job.
  82
  83 Here is a picture of the typical job lifecycle:
  84
  85
  86    put            reserve               delete
  87   -----> [READY] ---------> [RESERVED] --------> *poof*
  88
  89
  90
  91 Here is a picture with more possibilities:
  92
  93
  94
  95    put with delay               release with delay
  96   ----------------> [DELAYED] <------------.
  97                         |                   |
  98                         | (time passes)     |
  99                         |                   |
 100    put                  v     reserve       |       delete
 101   -----------------> [READY] ---------> [RESERVED] --------> *poof*
 102                        ^  ^                |  |
 103                        |   \  release      |  |
 104                        |    `-------------'   |
 105                        |                      |
 106                        | kick                 |
 107                        |                      |
 108                        |       bury           |
 109                     [BURIED] <---------------'
 110                        |
 111                        |  delete
 112                         `--------> *poof*
 113
 114
 115 The system has one or more tubes. Each tube consists of a ready queue and a
 116 delay queue. Each job spends its entire life in one tube. Consumers can show
 117 interest in tubes by sending the "watch" command; they can show disinterest by
 118 sending the "ignore" command. This set of interesting tubes is said to be a
 119 consumer's "watch list". When a client reserves a job, it may come from any of
 120 the tubes in its watch list.
 121
 122 When a client connects, its watch list is initially just the tube named
 123 "default". If it submits jobs without having sent a "use" command, they will
 124 live in the tube named "default".
 125
 126 Tubes are created on demand whenever they are referenced. If a tube is empty
 127 (that is, it contains no ready, delayed, or buried jobs) and no client refers
 128 to it, it will be deleted.
 129
 130 Producer Commands
 131 -----------------
 132
 133 The "put" command is for any process that wants to insert a job into the queue.
 134 It comprises a command line followed by the job body:
 135
 136 put <pri> <delay> <ttr> <bytes>\r\n
 137 <data>\r\n
 138
 139 It inserts a job into the client's currently used tube (see the "use" command
 140 below).
 141
 142  - <pri> is an integer < 2**32. Jobs with smaller priority values will be
 143    scheduled before jobs with larger priorities. The most urgent priority is 0;
 144    the least urgent priority is 4294967295.
 145
 146  - <delay> is an integer number of seconds to wait before putting the job in
 147    the ready queue. The job will be in the "delayed" state during this time.
 148
 149  - <ttr> -- time to run -- is an integer number of seconds to allow a worker
 150    to run this job. This time is counted from the moment a worker reserves
 151    this job. If the worker does not delete, release, or bury the job within
 152    <ttr> seconds, the job will time out and the server will release the job.
 153    The minimum ttr is 1. If the client sends 0, the server will silently
 154    increase the ttr to 1.
 155
 156  - <bytes> is an integer (currently must be < 2**16) indicating the size of
 157    the job body, not including the trailing "\r\n".
 158
 159  - <data> is the job body -- a sequence of bytes of length <bytes> from the
 160    previous line.
 161
 162 After sending the command line and body, the client waits for a reply, which
 163 may be:
 164
 165  - "INSERTED <id>\r\n" to indicate success.
 166
 167    - <id> is the integer id of the new job
 168
 169  - "BURIED <id>\r\n" if the server ran out of memory trying to grow the
 170    priority queue data structure.
 171
 172    - <id> is the integer id of the new job
 173
 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".
 177
 178 use <tube>\r\n
 179
 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.
 182
 183 The only reply is:
 184
 185 USING\r\n
 186
 187 Worker Commands
 188 ---------------
 189
 190 A process that wants to consume jobs from the queue uses "reserve", "delete",
 191 "release", and "bury". The first worker command, "reserve", looks like this:
 192
 193 reserve\r\n
 194
 195 This will return a newly-reserved job. If no job is available to be reserved,
 196 beanstalkd will wait to send a response until one becomes available. Once a job
 197 is reserved for the client, the client has limited time to run the job before
 198 the job times out, when the server will put the job back into the ready queue.
 199 The time available can be found by asking the server for the job's stats.
 200
 201 There is only one possible response in the form of a text line followed by the
 202 job body:
 203
 204 RESERVED <id> <bytes>\r\n
 205 <data>\r\n
 206
 207  - <id> is the job id -- an integer unique to this job in this instance of
 208    beanstalkd.
 209
 210  - <bytes> is an integer indicating the size of the job body, not including
 211    the trailing "\r\n".
 212
 213  - <data> is the job body -- a sequence of bytes of length <bytes> from the
 214    previous line. This is a verbatim copy of the bytes that were originally
 215    sent to the server in the put command for this job.
 216
 217 The delete command removes a job from the server entirely. It is normally used
 218 by the client when the job has successfully run to completion. A client can
 219 only delete jobs that it has reserved or jobs that are buried. The delete
 220 command looks like this:
 221
 222 delete <id>\r\n
 223
 224  - <id> is the job id to delete.
 225
 226 The client then waits for one line of response, which may be:
 227
 228  - "DELETED\r\n" to indicate success.
 229
 230  - "NOT_FOUND\r\n" if the job does not exist or is not either reserved by the
 231    client or buried. This could happen if the job timed out before the client
 232    sent the delete command.
 233
 234 The release command puts a reserved job back into the ready queue (and marks
 235 its state as "ready") to be run by any client. It is normally used when the job
 236 fails because of a transitory error. It looks like this:
 237
 238 release <id> <pri> <delay>\r\n
 239
 240  - <id> is the job id to release.
 241
 242  - <pri> is a new priority to assign to the job.
 243
 244  - <delay> is an integer number of seconds to wait before putting the job in
 245    the ready queue. The job will be in the "delayed" state during this time.
 246
 247 The client expects one line of response, which may be:
 248
 249  - "RELEASED\r\n" to indicate success.
 250
 251  - "BURIED\r\n" if the server ran out of memory trying to grow the priority
 252    queue data structure.
 253
 254  - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
 255
 256 The bury command puts a job into the "buried" state. Buried jobs are put into a
 257 FIFO linked list and will not be touched by the server again until a client
 258 kicks them with the "kick" command.
 259
 260 The bury command looks like this:
 261
 262 bury <id> <pri>\r\n
 263
 264  - <id> is the job id to release.
 265
 266  - <pri> is a new priority to assign to the job.
 267
 268 There are two possible responses:
 269
 270  - "BURIED\r\n" to indicate success.
 271
 272  - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
 273
 274 The "watch" command adds the named tube to the watch list for the current
 275 connection. A reserve command will take a job from any of the tubes in the
 276 watch list. For each new connection, the watch list initially consists of one
 277 tube, named "default".
 278
 279 watch <tube>\r\n
 280
 281  - <tube> is a name at most 200 bytes. It specifies a tube to add to the watch
 282    list.
 283
 284 The reply is:
 285
 286 WATCHING <count>\r\n
 287
 288  - <count> is the integer number of tubes currently in the watch list.
 289
 290 The "ignore" command is for consumers. It removes the named tube from the
 291 watch list for the current connection.
 292
 293 ignore <tube>\r\n
 294
 295 The reply is one of:
 296
 297  - "WATCHING <count>\r\n" to indicate success.
 298
 299    - <count> is the integer number of tubes currently in the watch list.
 300
 301  - "NOT_IGNORED\r\n" if the client attempts to ignore the only tube in its
 302    watch list.
 303
 304 Other Commands
 305 --------------
 306
 307 The peek command lets the client inspect a job in the system. Its format:
 308
 309 peek[ <id>]\r\n
 310
 311 If <id> is not given, peek will show the next job in the list of buried jobs,
 312 if any.
 313
 314  - <id> is the job id to show, if given.
 315
 316 There are two possible responses, either a single line:
 317
 318  - "NOT_FOUND\r\n" if the requested job doesn't exist or there are no buried
 319    jobs.
 320
 321 Or a line followed by a chunk of data, if the command was successful:
 322
 323 FOUND <id> <bytes>\r\n
 324 <data>\r\n
 325
 326  - <id> is the job id.
 327
 328  - <bytes> is an integer indicating the size of the job body, not including
 329    the trailing "\r\n".
 330
 331  - <data> is the job body -- a sequence of bytes of length <bytes> from the
 332    previous line.
 333
 334 The kick command moves jobs into the ready queue. If there are any buried jobs,
 335 it will only kick buried jobs. Otherwise it will kick delayed jobs. It looks
 336 like:
 337
 338 kick <bound>\r\n
 339
 340  - <bound> is an integer upper bound on the number of jobs to kick. The server
 341    will kick no more than <bound> jobs.
 342
 343 The response is of the form
 344
 345 KICKED <count>\r\n
 346
 347  - <count> is an integer indicating the number of jobs actually kicked.
 348
 349 The stats-job command gives statistical information about the specified job if
 350 it exists. Its form is:
 351
 352 stats-job <id>\r\n
 353
 354  - <id> is a job id.
 355
 356 The response is one of:
 357
 358  - "NOT_FOUND\r\n" if the job does not exist.
 359
 360  - "OK <bytes>\r\n<data>\r\n"
 361
 362    - <bytes> is the size of the following data section in bytes.
 363
 364    - <data> is a sequence of bytes of length <bytes> from the previous line. It
 365      is a YAML file with statistical information represented a dictionary.
 366
 367 The stats-job data is a YAML file representing a single dictionary of strings
 368 to scalars. It contains these keys:
 369
 370  - "id" is the job id
 371
 372  - "tube" is the name of the tube that contains this job
 373
 374  - "state" is "ready" or "delayed" or "reserved" or "buried"
 375
 376  - "pri" is the priority value set by the put, release, or bury commands.
 377
 378  - "age" is the time in seconds since the put command that created this job.
 379
 380  - "time-left" is the number of seconds left until the server puts this job
 381    into the ready queue. This number is only meaningful if the job is
 382    reserved or delayed. If the job is reserved and this amount of time
 383    elapses before its state changes, it is considered to have timed out.
 384
 385  - "timeouts" is the number of times this job has timed out during a
 386    reservation.
 387
 388  - "releases" is the number of times a client has released this job from a
 389    reservation.
 390
 391  - "buries" is the number of times this job has been buried.
 392
 393  - "kicks" is the number of times this job has been kicked.
 394
 395 The stats-tube command gives statistical information about the specified tube
 396 if it exists. Its form is:
 397
 398 stats-tube <tube>\r\n
 399
 400  - <tube> is a name at most 200 bytes. Stats will be returned for this tube.
 401
 402 The response is one of:
 403
 404  - "NOT_FOUND\r\n" if the tube does not exist.
 405
 406  - "OK <bytes>\r\n<data>\r\n"
 407
 408    - <bytes> is the size of the following data section in bytes.
 409
 410    - <data> is a sequence of bytes of length <bytes> from the previous line. It
 411      is a YAML file with statistical information represented a dictionary.
 412
 413 The stats-tube data is a YAML file representing a single dictionary of strings
 414 to scalars. It contains these keys:
 415
 416  - "name" is the tube's name.
 417
 418  - "current-jobs-urgent" is the number of ready jobs with priority < 1024 in
 419    this tube.
 420
 421  - "current-jobs-ready" is the number of jobs in the ready queue in this tube.
 422
 423  - "current-jobs-reserved" is the number of jobs reserved by all clients in
 424    this tube.
 425
 426  - "current-jobs-delayed" is the number of delayed jobs in this tube.
 427
 428  - "current-jobs-buried" is the number of buried jobs in this tube.
 429
 430  - "total-jobs" is the cumulative count of jobs created in this tube.
 431
 432  - "current-waiting" is the number of open connections that have issued a
 433    reserve command while watching this tube but not yet received a response.
 434
 435 The stats command gives statistical information about the system as a whole.
 436 Its form is:
 437
 438 stats\r\n
 439
 440 The server will respond:
 441
 442 OK <bytes>\r\n
 443 <data>\r\n
 444
 445  - <bytes> is the size of the following data section in bytes.
 446
 447  - <data> is a sequence of bytes of length <bytes> from the previous line. It
 448    is a YAML file with statistical information represented a dictionary.
 449
 450 The stats data for the system is a YAML file representing a single dictionary
 451 of strings to scalars. It contains these keys:
 452
 453  - "current-jobs-urgent" is the number of ready jobs with priority < 1024.
 454
 455  - "current-jobs-ready" is the number of jobs in the ready queue.
 456
 457  - "current-jobs-reserved" is the number of jobs reserved by all clients.
 458
 459  - "current-jobs-delayed" is the number of delayed jobs.
 460
 461  - "current-jobs-buried" is the number of buried jobs.
 462
 463  - "cmd-put" is the cumulative number of put commands.
 464
 465  - "cmd-peek" is the cumulative number of peek commands.
 466
 467  - "cmd-reserve" is the cumulative number of reserve commands.
 468
 469  - "cmd-delete" is the cumulative number of delete commands.
 470
 471  - "cmd-release" is the cumulative number of release commands.
 472
 473  - "cmd-bury" is the cumulative number of bury commands.
 474
 475  - "cmd-kick" is the cumulative number of kick commands.
 476
 477  - "cmd-stats" is the cumulative number of stats commands.
 478
 479  - "cmd-stats-job" is the cumulative number of stats-job commands.
 480
 481  - "cmd-stats-tube" is the cumulative number of stats-tube commands.
 482
 483  - "cmd-list-tubes" is the cumulative number of list-tubes commands.
 484
 485  - "cmd-list-watched-tubes" is the cumulative number of list-watched-tubes
 486    commands.
 487
 488  - "job-timeouts" is the cumulative count of times a job has timed out.
 489
 490  - "total-jobs" is the cumulative count of jobs created.
 491
 492  - "current-tubes" is the number of currently-existing tubes.
 493
 494  - "current-connections" is the number of currently open connections.
 495
 496  - "current-producers" is the number of open connections that have each
 497    issued at least one put command.
 498
 499  - "current-workers" is the number of open connections that have each issued
 500    at least one reserve command.
 501
 502  - "current-waiting" is the number of open connections that have issued a
 503    reserve command but not yet received a response.
 504
 505  - "total-connections" is the cumulative count of connections.
 506
 507  - "pid" is the process id of the server.
 508
 509  - "version" is the version string of the server.
 510
 511  - "rusage-utime" is the accumulated user CPU time of this process in seconds
 512    and microseconds.
 513
 514  - "rusage-stime" is the accumulated system CPU time of this process in
 515    seconds and microseconds.
 516
 517  - "uptime" is the number of seconds since this server started running.
 518
 519 The list-tubes command returns a list of all existing tubes. Its form is:
 520
 521 list-tubes\r\n
 522
 523 The response is:
 524
 525 OK <bytes>\r\n
 526 <data>\r\n
 527
 528  - <bytes> is the size of the following data section in bytes.
 529
 530  - <data> is a sequence of bytes of length <bytes> from the previous line. It
 531    is a YAML file containing all tube names as a list of strings.
 532
 533 The list-watched-tubes command returns a list tubes currently being watched by
 534 the client. Its form is:
 535
 536 list-watched-tubes\r\n
 537
 538 The response is:
 539
 540 OK <bytes>\r\n
 541 <data>\r\n
 542
 543  - <bytes> is the size of the following data section in bytes.
 544
 545  - <data> is a sequence of bytes of length <bytes> from the previous line. It
 546    is a YAML file containing watched tube names as a list of strings.
 547