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 <tube>\r\n
 186
 187  - <tube> is the name of the tube now being used.
 188
 189 Worker Commands
 190 ---------------
 191
 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:
 194
 195 reserve\r\n
 196
 197 This will return a newly-reserved job. If no job is available to be reserved,
 198 beanstalkd will wait to send a response until one becomes available. Once a job
 199 is reserved for the client, the client has limited time to run the job before
 200 the job times out, when the server will put the job back into the ready queue.
 201 The time available can be found by asking the server for the job's stats.
 202
 203 If the client has previously reserved job J and issues a reserve command when
 204 J has less than one second left in its ttr interval, the server will respond
 205 with:
 206
 207 TIMEOUT\r\n
 208
 209 This gives the client a chance to delete or release job J before the server
 210 automatically releases it. Otherwise, the only response is in the form of a
 211 text line followed by the job body:
 212
 213 RESERVED <id> <bytes>\r\n
 214 <data>\r\n
 215
 216  - <id> is the job id -- an integer unique to this job in this instance of
 217    beanstalkd.
 218
 219  - <bytes> is an integer indicating the size of the job body, not including
 220    the trailing "\r\n".
 221
 222  - <data> is the job body -- a sequence of bytes of length <bytes> from the
 223    previous line. This is a verbatim copy of the bytes that were originally
 224    sent to the server in the put command for this job.
 225
 226 The delete command removes a job from the server entirely. It is normally used
 227 by the client when the job has successfully run to completion. A client can
 228 only delete jobs that it has reserved or jobs that are buried. The delete
 229 command looks like this:
 230
 231 delete <id>\r\n
 232
 233  - <id> is the job id to delete.
 234
 235 The client then waits for one line of response, which may be:
 236
 237  - "DELETED\r\n" to indicate success.
 238
 239  - "NOT_FOUND\r\n" if the job does not exist or is not either reserved by the
 240    client or buried. This could happen if the job timed out before the client
 241    sent the delete command.
 242
 243 The release command puts a reserved job back into the ready queue (and marks
 244 its state as "ready") to be run by any client. It is normally used when the job
 245 fails because of a transitory error. It looks like this:
 246
 247 release <id> <pri> <delay>\r\n
 248
 249  - <id> is the job id to release.
 250
 251  - <pri> is a new priority to assign to the job.
 252
 253  - <delay> is an integer number of seconds to wait before putting the job in
 254    the ready queue. The job will be in the "delayed" state during this time.
 255
 256 The client expects one line of response, which may be:
 257
 258  - "RELEASED\r\n" to indicate success.
 259
 260  - "BURIED\r\n" if the server ran out of memory trying to grow the priority
 261    queue data structure.
 262
 263  - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
 264
 265 The bury command puts a job into the "buried" state. Buried jobs are put into a
 266 FIFO linked list and will not be touched by the server again until a client
 267 kicks them with the "kick" command.
 268
 269 The bury command looks like this:
 270
 271 bury <id> <pri>\r\n
 272
 273  - <id> is the job id to release.
 274
 275  - <pri> is a new priority to assign to the job.
 276
 277 There are two possible responses:
 278
 279  - "BURIED\r\n" to indicate success.
 280
 281  - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
 282
 283 The "watch" command adds the named tube to the watch list for the current
 284 connection. A reserve command will take a job from any of the tubes in the
 285 watch list. For each new connection, the watch list initially consists of one
 286 tube, named "default".
 287
 288 watch <tube>\r\n
 289
 290  - <tube> is a name at most 200 bytes. It specifies a tube to add to the watch
 291    list. If the tube doesn't exist, it will be created.
 292
 293 The reply is:
 294
 295 WATCHING <count>\r\n
 296
 297  - <count> is the integer number of tubes currently in the watch list.
 298
 299 The "ignore" command is for consumers. It removes the named tube from the
 300 watch list for the current connection.
 301
 302 ignore <tube>\r\n
 303
 304 The reply is one of:
 305
 306  - "WATCHING <count>\r\n" to indicate success.
 307
 308    - <count> is the integer number of tubes currently in the watch list.
 309
 310  - "NOT_IGNORED\r\n" if the client attempts to ignore the only tube in its
 311    watch list.
 312
 313 Other Commands
 314 --------------
 315
 316 The peek command lets the client inspect a job in the system. Its format:
 317
 318 peek[ <id>]\r\n
 319
 320 If <id> is not given, peek will show the next job in the list of buried jobs,
 321 if any.
 322
 323  - <id> is the job id to show, if given.
 324
 325 There are two possible responses, either a single line:
 326
 327  - "NOT_FOUND\r\n" if the requested job doesn't exist or there are no buried
 328    jobs.
 329
 330 Or a line followed by a chunk of data, if the command was successful:
 331
 332 FOUND <id> <bytes>\r\n
 333 <data>\r\n
 334
 335  - <id> is the job id.
 336
 337  - <bytes> is an integer indicating the size of the job body, not including
 338    the trailing "\r\n".
 339
 340  - <data> is the job body -- a sequence of bytes of length <bytes> from the
 341    previous line.
 342
 343 The kick command moves jobs into the ready queue. If there are any buried jobs
 344 in the currently used tube, it will only kick buried jobs. Otherwise it will
 345 kick delayed jobs. It looks like:
 346
 347 kick <bound>\r\n
 348
 349  - <bound> is an integer upper bound on the number of jobs to kick. The server
 350    will kick no more than <bound> jobs.
 351
 352 When the server kicks buried jobs, they are taken from the buried list in only
 353 the currently used tube. However, when the server kicks delayed jobs, they are
 354 taken from the global delay queue; thus jobs in any tube may be kicked.
 355
 356 The response is of the form:
 357
 358 KICKED <count>\r\n
 359
 360  - <count> is an integer indicating the number of jobs actually kicked.
 361
 362 The stats-job command gives statistical information about the specified job if
 363 it exists. Its form is:
 364
 365 stats-job <id>\r\n
 366
 367  - <id> is a job id.
 368
 369 The response is one of:
 370
 371  - "NOT_FOUND\r\n" if the job does not exist.
 372
 373  - "OK <bytes>\r\n<data>\r\n"
 374
 375    - <bytes> is the size of the following data section in bytes.
 376
 377    - <data> is a sequence of bytes of length <bytes> from the previous line. It
 378      is a YAML file with statistical information represented a dictionary.
 379
 380 The stats-job data is a YAML file representing a single dictionary of strings
 381 to scalars. It contains these keys:
 382
 383  - "id" is the job id
 384
 385  - "tube" is the name of the tube that contains this job
 386
 387  - "state" is "ready" or "delayed" or "reserved" or "buried"
 388
 389  - "pri" is the priority value set by the put, release, or bury commands.
 390
 391  - "age" is the time in seconds since the put command that created this job.
 392
 393  - "time-left" is the number of seconds left until the server puts this job
 394    into the ready queue. This number is only meaningful if the job is
 395    reserved or delayed. If the job is reserved and this amount of time
 396    elapses before its state changes, it is considered to have timed out.
 397
 398  - "timeouts" is the number of times this job has timed out during a
 399    reservation.
 400
 401  - "releases" is the number of times a client has released this job from a
 402    reservation.
 403
 404  - "buries" is the number of times this job has been buried.
 405
 406  - "kicks" is the number of times this job has been kicked.
 407
 408 The stats-tube command gives statistical information about the specified tube
 409 if it exists. Its form is:
 410
 411 stats-tube <tube>\r\n
 412
 413  - <tube> is a name at most 200 bytes. Stats will be returned for this tube.
 414
 415 The response is one of:
 416
 417  - "NOT_FOUND\r\n" if the tube does not exist.
 418
 419  - "OK <bytes>\r\n<data>\r\n"
 420
 421    - <bytes> is the size of the following data section in bytes.
 422
 423    - <data> is a sequence of bytes of length <bytes> from the previous line. It
 424      is a YAML file with statistical information represented a dictionary.
 425
 426 The stats-tube data is a YAML file representing a single dictionary of strings
 427 to scalars. It contains these keys:
 428
 429  - "name" is the tube's name.
 430
 431  - "current-jobs-urgent" is the number of ready jobs with priority < 1024 in
 432    this tube.
 433
 434  - "current-jobs-ready" is the number of jobs in the ready queue in this tube.
 435
 436  - "current-jobs-reserved" is the number of jobs reserved by all clients in
 437    this tube.
 438
 439  - "current-jobs-buried" is the number of buried jobs in this tube.
 440
 441  - "total-jobs" is the cumulative count of jobs created in this tube.
 442
 443  - "current-waiting" is the number of open connections that have issued a
 444    reserve command while watching this tube but not yet received a response.
 445
 446 The stats command gives statistical information about the system as a whole.
 447 Its form is:
 448
 449 stats\r\n
 450
 451 The server will respond:
 452
 453 OK <bytes>\r\n
 454 <data>\r\n
 455
 456  - <bytes> is the size of the following data section in bytes.
 457
 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.
 460
 461 The stats data for the system is a YAML file representing a single dictionary
 462 of strings to scalars. It contains these keys:
 463
 464  - "current-jobs-urgent" is the number of ready jobs with priority < 1024.
 465
 466  - "current-jobs-ready" is the number of jobs in the ready queue.
 467
 468  - "current-jobs-reserved" is the number of jobs reserved by all clients.
 469
 470  - "current-jobs-delayed" is the number of delayed jobs.
 471
 472  - "current-jobs-buried" is the number of buried jobs.
 473
 474  - "cmd-put" is the cumulative number of put commands.
 475
 476  - "cmd-peek" is the cumulative number of peek commands.
 477
 478  - "cmd-reserve" is the cumulative number of reserve commands.
 479
 480  - "cmd-use" is the cumulative number of use commands.
 481
 482  - "cmd-watch" is the cumulative number of watch commands.
 483
 484  - "cmd-ignore" is the cumulative number of ignore commands.
 485
 486  - "cmd-delete" is the cumulative number of delete commands.
 487
 488  - "cmd-release" is the cumulative number of release commands.
 489
 490  - "cmd-bury" is the cumulative number of bury commands.
 491
 492  - "cmd-kick" is the cumulative number of kick commands.
 493
 494  - "cmd-stats" is the cumulative number of stats commands.
 495
 496  - "cmd-stats-job" is the cumulative number of stats-job commands.
 497
 498  - "cmd-stats-tube" is the cumulative number of stats-tube commands.
 499
 500  - "cmd-list-tubes" is the cumulative number of list-tubes commands.
 501
 502  - "cmd-list-tube-used" is the cumulative number of list-tube-used commands.
 503
 504  - "cmd-list-tubes-watched" is the cumulative number of list-tubes-watched
 505    commands.
 506
 507  - "job-timeouts" is the cumulative count of times a job has timed out.
 508
 509  - "total-jobs" is the cumulative count of jobs created.
 510
 511  - "current-tubes" is the number of currently-existing tubes.
 512
 513  - "current-connections" is the number of currently open connections.
 514
 515  - "current-producers" is the number of open connections that have each
 516    issued at least one put command.
 517
 518  - "current-workers" is the number of open connections that have each issued
 519    at least one reserve command.
 520
 521  - "current-waiting" is the number of open connections that have issued a
 522    reserve command but not yet received a response.
 523
 524  - "total-connections" is the cumulative count of connections.
 525
 526  - "pid" is the process id of the server.
 527
 528  - "version" is the version string of the server.
 529
 530  - "rusage-utime" is the accumulated user CPU time of this process in seconds
 531    and microseconds.
 532
 533  - "rusage-stime" is the accumulated system CPU time of this process in
 534    seconds and microseconds.
 535
 536  - "uptime" is the number of seconds since this server started running.
 537
 538 The list-tubes command returns a list of all existing tubes. Its form is:
 539
 540 list-tubes\r\n
 541
 542 The response is:
 543
 544 OK <bytes>\r\n
 545 <data>\r\n
 546
 547  - <bytes> is the size of the following data section in bytes.
 548
 549  - <data> is a sequence of bytes of length <bytes> from the previous line. It
 550    is a YAML file containing all tube names as a list of strings.
 551
 552 The list-tube-used command returns the tube currently being used by the
 553 client. Its form is:
 554
 555 list-tube-used\r\n
 556
 557 The response is:
 558
 559 USING <tube>\r\n
 560
 561  - <tube> is the name of the tube being used.
 562
 563 The list-tubes-watched command returns a list tubes currently being watched by
 564 the client. Its form is:
 565
 566 list-tubes-watched\r\n
 567
 568 The response is:
 569
 570 OK <bytes>\r\n
 571 <data>\r\n
 572
 573  - <bytes> is the size of the following data section in bytes.
 574
 575  - <data> is a sequence of bytes of length <bytes> from the previous line. It
 576    is a YAML file containing watched tube names as a list of strings.
 577