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 ("$"), underscore ("_"), and parentheses ("(" and ")"),
  16 but they may not begin with a hyphen. They are terminated by white space
  17 (either a space char or end of line). Each name must be at least one character
  18 long.
  19
  20 The protocol contains two kinds of data: text lines and unstructured chunks of
  21 data. Text lines are used for client commands and server responses. Chunks are
  22 used to transfer job bodies and stats information. Each job body is an opaque
  23 sequence of bytes. The server never inspects or modifies a job body and always
  24 sends it back in its original form. It is up to the clients to agree on a
  25 meaningful interpretation of job bodies.
  26
  27 The client may issue the "quit" command, or simply close the TCP connection
  28 when it no longer has use for the server. However, beanstalkd performs very
  29 well with a large number of open connections, so it is usually better for the
  30 client to keep its connection open and reuse it as much as possible. This also
  31 avoids the overhead of establishing new TCP connections.
  32
  33 If a client violates the protocol (such as by sending a request that is not
  34 well-formed or a command that does not exist) or if the server has an error,
  35 the server will reply with one of the following error messages:
  36
  37  - "OUT_OF_MEMORY\r\n" The server cannot allocate enough memory for the job.
  38    The client should try again later.
  39
  40  - "INTERNAL_ERROR\r\n" This indicates a bug in the server. It should never
  41    happen. If it does happen, please report it at
  42    http://groups.google.com/group/beanstalk-talk.
  43
  44  - "BAD_FORMAT\r\n" The client sent a command line that was not well-formed.
  45    This can happen if the line does not end with \r\n, if non-numeric
  46    characters occur where an integer is expected, if the wrong number of
  47    arguments are present, or if the command line is mal-formed in any other
  48    way.
  49
  50  - "UNKNOWN_COMMAND\r\n" The client sent a command that the server does not
  51    know.
  52
  53 These error responses will not be listed in this document for individual
  54 commands in the following sections, but they are implicitly included in the
  55 description of all commands. Clients should be prepared to receive an error
  56 response after any command.
  57
  58 As a last resort, if the server has a serious error that prevents it from
  59 continuing service to the current client, the server will close the
  60 connection.
  61
  62 Job Lifecycle
  63 -------------
  64
  65 A job in beanstalk gets created by a client with the "put" command. During its
  66 life it can be in one of four states: "ready", "reserved", "delayed", or
  67 "buried". After the put command, a job typically starts out ready. It waits in
  68 the ready queue until a worker comes along and runs the "reserve" command. If
  69 this job is next in the queue, it will be reserved for the worker. The worker
  70 will execute the job; when it is finished the worker will send a "delete"
  71 command to delete the job.
  72
  73 Here is a picture of the typical job lifecycle:
  74
  75
  76    put            reserve               delete
  77   -----> [READY] ---------> [RESERVED] --------> *poof*
  78
  79
  80
  81 Here is a picture with more possibilities:
  82
  83
  84
  85    put with delay               release with delay
  86   ----------------> [DELAYED] <------------.
  87                         |                   |
  88                         | (time passes)     |
  89                         |                   |
  90    put                  v     reserve       |       delete
  91   -----------------> [READY] ---------> [RESERVED] --------> *poof*
  92                        ^  ^                |  |
  93                        |   \  release      |  |
  94                        |    `-------------'   |
  95                        |                      |
  96                        | kick                 |
  97                        |                      |
  98                        |       bury           |
  99                     [BURIED] <---------------'
 100                        |
 101                        |  delete
 102                         `--------> *poof*
 103
 104
 105 The system has one or more tubes. Each tube consists of a ready queue and a
 106 delay queue. Each job spends its entire life in one tube. Consumers can show
 107 interest in tubes by sending the "watch" command; they can show disinterest by
 108 sending the "ignore" command. This set of interesting tubes is said to be a
 109 consumer's "watch list". When a client reserves a job, it may come from any of
 110 the tubes in its watch list.
 111
 112 When a client connects, its watch list is initially just the tube named
 113 "default". If it submits jobs without having sent a "use" command, they will
 114 live in the tube named "default".
 115
 116 Tubes are created on demand whenever they are referenced. If a tube is empty
 117 (that is, it contains no ready, delayed, or buried jobs) and no client refers
 118 to it, it will be deleted.
 119
 120 Producer Commands
 121 -----------------
 122
 123 The "put" command is for any process that wants to insert a job into the queue.
 124 It comprises a command line followed by the job body:
 125
 126 put <pri> <delay> <ttr> <bytes>\r\n
 127 <data>\r\n
 128
 129 It inserts a job into the client's currently used tube (see the "use" command
 130 below).
 131
 132  - <pri> is an integer < 2**32. Jobs with smaller priority values will be
 133    scheduled before jobs with larger priorities. The most urgent priority is 0;
 134    the least urgent priority is 4,294,967,295.
 135
 136  - <delay> is an integer number of seconds to wait before putting the job in
 137    the ready queue. The job will be in the "delayed" state during this time.
 138
 139  - <ttr> -- time to run -- is an integer number of seconds to allow a worker
 140    to run this job. This time is counted from the moment a worker reserves
 141    this job. If the worker does not delete, release, or bury the job within
 142    <ttr> seconds, the job will time out and the server will release the job.
 143    The minimum ttr is 1. If the client sends 0, the server will silently
 144    increase the ttr to 1.
 145
 146  - <bytes> is an integer indicating the size of the job body, not including the
 147    trailing "\r\n". This value must be less than max-job-size (default: 2**16).
 148
 149  - <data> is the job body -- a sequence of bytes of length <bytes> from the
 150    previous line.
 151
 152 After sending the command line and body, the client waits for a reply, which
 153 may be:
 154
 155  - "INSERTED <id>\r\n" to indicate success.
 156
 157    - <id> is the integer id of the new job
 158
 159  - "BURIED <id>\r\n" if the server ran out of memory trying to grow the
 160    priority queue data structure.
 161
 162    - <id> is the integer id of the new job
 163
 164  - "EXPECTED_CRLF\r\n" The job body must be followed by a CR-LF pair, that is,
 165    "\r\n". These two bytes are not counted in the job size given by the client
 166    in the put command line.
 167
 168  - "JOB_TOO_BIG\r\n" The client has requested to put a job with a body larger
 169    than max-job-size bytes.
 170
 171  - "DRAINING\r\n" This means that the server has been put into "drain mode"
 172    and is no longer accepting new jobs. The client should try another server
 173    or disconnect and try again later.
 174
 175 The "use" command is for producers. Subsequent put commands will put jobs into
 176 the tube specified by this command. If no use command has been issued, jobs
 177 will be put into the tube named "default".
 178
 179 use <tube>\r\n
 180
 181  - <tube> is a name at most 200 bytes. It specifies the tube to use. If the
 182    tube does not exist, it will be created.
 183
 184 The only reply is:
 185
 186 USING <tube>\r\n
 187
 188  - <tube> is the name of the tube now being used.
 189
 190 Worker Commands
 191 ---------------
 192
 193 A process that wants to consume jobs from the queue uses "reserve", "delete",
 194 "release", and "bury". The first worker command, "reserve", looks like this:
 195
 196 reserve\r\n
 197
 198 Alternatively, you can specify a timeout as follows:
 199
 200 reserve-with-timeout <seconds>\r\n
 201
 202 This will return a newly-reserved job. If no job is available to be reserved,
 203 beanstalkd will wait to send a response until one becomes available. Once a
 204 job is reserved for the client, the client has limited time to run (TTR) the
 205 job before the job times out. When the job times out, the server will put the
 206 job back into the ready queue. Both the TTR and the actual time left can be
 207 found in response to the stats-job command.
 208
 209 If more than one job is ready, beanstalkd will choose the one with the
 210 smallest priority value. Within each priority, it will choose the one that
 211 was received first.
 212
 213 A timeout value of 0 will cause the server to immediately return either a
 214 response or TIMED_OUT.  A positive value of timeout will limit the amount of
 215 time the client will block on the reserve request until a job becomes
 216 available.
 217
 218 During the TTR of a reserved job, the last second is kept by the server as a
 219 safety margin, during which the client will not be made to wait for another
 220 job. If the client issues a reserve command during the safety margin, or if
 221 the safety margin arrives while the client is waiting on a reserve command,
 222 the server will respond with:
 223
 224 DEADLINE_SOON\r\n
 225
 226 This gives the client a chance to delete or release its reserved job before
 227 the server automatically releases it.
 228
 229 TIMED_OUT\r\n
 230
 231 If a non-negative timeout was specified and the timeout exceeded before a job
 232 became available, or if the client's connection is half-closed, the server
 233 will respond with TIMED_OUT.
 234
 235 Otherwise, the only other response to this command is a successful reservation
 236 in the form of a text line followed by the job body:
 237
 238 RESERVED <id> <bytes>\r\n
 239 <data>\r\n
 240
 241  - <id> is the job id -- an integer unique to this job in this instance of
 242    beanstalkd.
 243
 244  - <bytes> is an integer indicating the size of the job body, not including
 245    the trailing "\r\n".
 246
 247  - <data> is the job body -- a sequence of bytes of length <bytes> from the
 248    previous line. This is a verbatim copy of the bytes that were originally
 249    sent to the server in the put command for this job.
 250
 251 The delete command removes a job from the server entirely. It is normally used
 252 by the client when the job has successfully run to completion. A client can
 253 delete jobs that it has reserved, ready jobs, delayed jobs, and jobs that are
 254 buried. The delete command looks like this:
 255
 256 delete <id>\r\n
 257
 258  - <id> is the job id to delete.
 259
 260 The client then waits for one line of response, which may be:
 261
 262  - "DELETED\r\n" to indicate success.
 263
 264  - "NOT_FOUND\r\n" if the job does not exist or is not either reserved by the
 265    client, ready, or buried. This could happen if the job timed out before the
 266    client sent the delete command.
 267
 268 The release command puts a reserved job back into the ready queue (and marks
 269 its state as "ready") to be run by any client. It is normally used when the job
 270 fails because of a transitory error. It looks like this:
 271
 272 release <id> <pri> <delay>\r\n
 273
 274  - <id> is the job id to release.
 275
 276  - <pri> is a new priority to assign to the job.
 277
 278  - <delay> is an integer number of seconds to wait before putting the job in
 279    the ready queue. The job will be in the "delayed" state during this time.
 280
 281 The client expects one line of response, which may be:
 282
 283  - "RELEASED\r\n" to indicate success.
 284
 285  - "BURIED\r\n" if the server ran out of memory trying to grow the priority
 286    queue data structure.
 287
 288  - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
 289
 290 The bury command puts a job into the "buried" state. Buried jobs are put into a
 291 FIFO linked list and will not be touched by the server again until a client
 292 kicks them with the "kick" command.
 293
 294 The bury command looks like this:
 295
 296 bury <id> <pri>\r\n
 297
 298  - <id> is the job id to release.
 299
 300  - <pri> is a new priority to assign to the job.
 301
 302 There are two possible responses:
 303
 304  - "BURIED\r\n" to indicate success.
 305
 306  - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
 307
 308 The "touch" command allows a worker to request more time to work on a job.
 309 This is useful for jobs that potentially take a long time, but you still want
 310 the benefits of a TTR pulling a job away from an unresponsive worker.  A worker
 311 may periodically tell the server that it's still alive and processing a job
 312 (e.g. it may do this on DEADLINE_SOON).
 313
 314 The touch command looks like this:
 315
 316 touch <id>\r\n
 317
 318  - <id> is the ID of a job reserved by the current connection.
 319
 320 There are two possible responses:
 321
 322  - "TOUCHED\r\n" to indicate success.
 323
 324  - "NOT_FOUND\r\n" if the job does not exist or is not reserved by the client.
 325
 326 The "watch" command adds the named tube to the watch list for the current
 327 connection. A reserve command will take a job from any of the tubes in the
 328 watch list. For each new connection, the watch list initially consists of one
 329 tube, named "default".
 330
 331 watch <tube>\r\n
 332
 333  - <tube> is a name at most 200 bytes. It specifies a tube to add to the watch
 334    list. If the tube doesn't exist, it will be created.
 335
 336 The reply is:
 337
 338 WATCHING <count>\r\n
 339
 340  - <count> is the integer number of tubes currently in the watch list.
 341
 342 The "ignore" command is for consumers. It removes the named tube from the
 343 watch list for the current connection.
 344
 345 ignore <tube>\r\n
 346
 347 The reply is one of:
 348
 349  - "WATCHING <count>\r\n" to indicate success.
 350
 351    - <count> is the integer number of tubes currently in the watch list.
 352
 353  - "NOT_IGNORED\r\n" if the client attempts to ignore the only tube in its
 354    watch list.
 355
 356 Other Commands
 357 --------------
 358
 359 The peek commands let the client inspect a job in the system. There are four
 360 variations. All but the first operate only on the currently used tube.
 361
 362  - "peek <id>\r\n" - return job <id>.
 363
 364  - "peek-ready\r\n" - return the next ready job.
 365
 366  - "peek-delayed\r\n" - return the delayed job with the shortest delay left.
 367
 368  - "peek-buried\r\n" - return the next job in the list of buried jobs.
 369
 370 There are two possible responses, either a single line:
 371
 372  - "NOT_FOUND\r\n" if the requested job doesn't exist or there are no jobs in
 373    the requested state.
 374
 375 Or a line followed by a chunk of data, if the command was successful:
 376
 377 FOUND <id> <bytes>\r\n
 378 <data>\r\n
 379
 380  - <id> is the job id.
 381
 382  - <bytes> is an integer indicating the size of the job body, not including
 383    the trailing "\r\n".
 384
 385  - <data> is the job body -- a sequence of bytes of length <bytes> from the
 386    previous line.
 387
 388 The kick command applies only to the currently used tube. It moves jobs into
 389 the ready queue. If there are any buried jobs, it will only kick buried jobs.
 390 Otherwise it will kick delayed jobs. It looks like:
 391
 392 kick <bound>\r\n
 393
 394  - <bound> is an integer upper bound on the number of jobs to kick. The server
 395    will kick no more than <bound> jobs.
 396
 397 The response is of the form:
 398
 399 KICKED <count>\r\n
 400
 401  - <count> is an integer indicating the number of jobs actually kicked.
 402
 403 The kick-job command is a variant of kick that operates with a single job
 404 identified by its job id. If the given job id exists and is in a buried or
 405 delayed state, it will be moved to the ready queue of the the same tube where it
 406 currently belongs. The syntax is:
 407
 408 kick-job <id>\r\n
 409
 410  - <id> is the job id to kick.
 411
 412 The response is one of:
 413
 414  - "NOT_FOUND\r\n" if the job does not exist or is not in a kickable state. This
 415    can also happen upon internal errors.
 416
 417  - "KICKED\r\n" when the operation succeeded.
 418
 419 The stats-job command gives statistical information about the specified job if
 420 it exists. Its form is:
 421
 422 stats-job <id>\r\n
 423
 424  - <id> is a job id.
 425
 426 The response is one of:
 427
 428  - "NOT_FOUND\r\n" if the job does not exist.
 429
 430  - "OK <bytes>\r\n<data>\r\n"
 431
 432    - <bytes> is the size of the following data section in bytes.
 433
 434    - <data> is a sequence of bytes of length <bytes> from the previous line. It
 435      is a YAML file with statistical information represented a dictionary.
 436
 437 The stats-job data is a YAML file representing a single dictionary of strings
 438 to scalars. It contains these keys:
 439
 440  - "id" is the job id
 441
 442  - "tube" is the name of the tube that contains this job
 443
 444  - "state" is "ready" or "delayed" or "reserved" or "buried"
 445
 446  - "pri" is the priority value set by the put, release, or bury commands.
 447
 448  - "age" is the time in seconds since the put command that created this job.
 449
 450  - "time-left" is the number of seconds left until the server puts this job
 451    into the ready queue. This number is only meaningful if the job is
 452    reserved or delayed. If the job is reserved and this amount of time
 453    elapses before its state changes, it is considered to have timed out.
 454
 455  - "file" is the number of the earliest binlog file containing this job.
 456    If -b wasn't used, this will be 0.
 457
 458  - "reserves" is the number of times this job has been reserved.
 459
 460  - "timeouts" is the number of times this job has timed out during a
 461    reservation.
 462
 463  - "releases" is the number of times a client has released this job from a
 464    reservation.
 465
 466  - "buries" is the number of times this job has been buried.
 467
 468  - "kicks" is the number of times this job has been kicked.
 469
 470 The stats-tube command gives statistical information about the specified tube
 471 if it exists. Its form is:
 472
 473 stats-tube <tube>\r\n
 474
 475  - <tube> is a name at most 200 bytes. Stats will be returned for this tube.
 476
 477 The response is one of:
 478
 479  - "NOT_FOUND\r\n" if the tube does not exist.
 480
 481  - "OK <bytes>\r\n<data>\r\n"
 482
 483    - <bytes> is the size of the following data section in bytes.
 484
 485    - <data> is a sequence of bytes of length <bytes> from the previous line. It
 486      is a YAML file with statistical information represented a dictionary.
 487
 488 The stats-tube data is a YAML file representing a single dictionary of strings
 489 to scalars. It contains these keys:
 490
 491  - "name" is the tube's name.
 492
 493  - "current-jobs-urgent" is the number of ready jobs with priority < 1024 in
 494    this tube.
 495
 496  - "current-jobs-ready" is the number of jobs in the ready queue in this tube.
 497
 498  - "current-jobs-reserved" is the number of jobs reserved by all clients in
 499    this tube.
 500
 501  - "current-jobs-delayed" is the number of delayed jobs in this tube.
 502
 503  - "current-jobs-buried" is the number of buried jobs in this tube.
 504
 505  - "total-jobs" is the cumulative count of jobs created in this tube in
 506    the current beanstalkd process.
 507
 508  - "current-using" is the number of open connections that are currently
 509    using this tube.
 510
 511  - "current-waiting" is the number of open connections that have issued a
 512    reserve command while watching this tube but not yet received a response.
 513
 514  - "current-watching" is the number of open connections that are currently
 515    watching this tube.
 516
 517  - "pause" is the number of seconds the tube has been paused for.
 518
 519  - "cmd-delete" is the cumulative number of delete commands for this tube
 520
 521  - "cmd-pause-tube" is the cumulative number of pause-tube commands for this
 522    tube.
 523
 524  - "pause-time-left" is the number of seconds until the tube is un-paused.
 525
 526 The stats command gives statistical information about the system as a whole.
 527 Its form is:
 528
 529 stats\r\n
 530
 531 The server will respond:
 532
 533 OK <bytes>\r\n
 534 <data>\r\n
 535
 536  - <bytes> is the size of the following data section in bytes.
 537
 538  - <data> is a sequence of bytes of length <bytes> from the previous line. It
 539    is a YAML file with statistical information represented a dictionary.
 540
 541 The stats data for the system is a YAML file representing a single dictionary
 542 of strings to scalars. Entries described as "cumulative" are reset when the
 543 beanstalkd process starts; they are not stored on disk with the -b flag.
 544
 545  - "current-jobs-urgent" is the number of ready jobs with priority < 1024.
 546
 547  - "current-jobs-ready" is the number of jobs in the ready queue.
 548
 549  - "current-jobs-reserved" is the number of jobs reserved by all clients.
 550
 551  - "current-jobs-delayed" is the number of delayed jobs.
 552
 553  - "current-jobs-buried" is the number of buried jobs.
 554
 555  - "cmd-put" is the cumulative number of put commands.
 556
 557  - "cmd-peek" is the cumulative number of peek commands.
 558
 559  - "cmd-peek-ready" is the cumulative number of peek-ready commands.
 560
 561  - "cmd-peek-delayed" is the cumulative number of peek-delayed commands.
 562
 563  - "cmd-peek-buried" is the cumulative number of peek-buried commands.
 564
 565  - "cmd-reserve" is the cumulative number of reserve commands.
 566
 567  - "cmd-use" is the cumulative number of use commands.
 568
 569  - "cmd-watch" is the cumulative number of watch commands.
 570
 571  - "cmd-ignore" is the cumulative number of ignore commands.
 572
 573  - "cmd-delete" is the cumulative number of delete commands.
 574
 575  - "cmd-release" is the cumulative number of release commands.
 576
 577  - "cmd-bury" is the cumulative number of bury commands.
 578
 579  - "cmd-kick" is the cumulative number of kick commands.
 580
 581  - "cmd-stats" is the cumulative number of stats commands.
 582
 583  - "cmd-stats-job" is the cumulative number of stats-job commands.
 584
 585  - "cmd-stats-tube" is the cumulative number of stats-tube commands.
 586
 587  - "cmd-list-tubes" is the cumulative number of list-tubes commands.
 588
 589  - "cmd-list-tube-used" is the cumulative number of list-tube-used commands.
 590
 591  - "cmd-list-tubes-watched" is the cumulative number of list-tubes-watched
 592    commands.
 593
 594  - "cmd-pause-tube" is the cumulative number of pause-tube commands.
 595
 596  - "job-timeouts" is the cumulative count of times a job has timed out.
 597
 598  - "total-jobs" is the cumulative count of jobs created.
 599
 600  - "max-job-size" is the maximum number of bytes in a job.
 601
 602  - "current-tubes" is the number of currently-existing tubes.
 603
 604  - "current-connections" is the number of currently open connections.
 605
 606  - "current-producers" is the number of open connections that have each
 607    issued at least one put command.
 608
 609  - "current-workers" is the number of open connections that have each issued
 610    at least one reserve command.
 611
 612  - "current-waiting" is the number of open connections that have issued a
 613    reserve command but not yet received a response.
 614
 615  - "total-connections" is the cumulative count of connections.
 616
 617  - "pid" is the process id of the server.
 618
 619  - "version" is the version string of the server.
 620
 621  - "rusage-utime" is the cumulative user CPU time of this process in seconds
 622    and microseconds.
 623
 624  - "rusage-stime" is the cumulative system CPU time of this process in
 625    seconds and microseconds.
 626
 627  - "uptime" is the number of seconds since this server process started running.
 628
 629  - "binlog-oldest-index" is the index of the oldest binlog file needed to
 630    store the current jobs.
 631
 632  - "binlog-current-index" is the index of the current binlog file being
 633    written to. If binlog is not active this value will be 0.
 634
 635  - "binlog-max-size" is the maximum size in bytes a binlog file is allowed
 636    to get before a new binlog file is opened.
 637
 638  - "binlog-records-written" is the cumulative number of records written
 639    to the binlog.
 640
 641  - "binlog-records-migrated" is the cumulative number of records written
 642    as part of compaction.
 643
 644  - "id" is a random id string for this server process, generated when each
 645    beanstalkd process starts.
 646
 647  - "hostname" the hostname of the machine as determined by uname.
 648
 649 The list-tubes command returns a list of all existing tubes. Its form is:
 650
 651 list-tubes\r\n
 652
 653 The response is:
 654
 655 OK <bytes>\r\n
 656 <data>\r\n
 657
 658  - <bytes> is the size of the following data section in bytes.
 659
 660  - <data> is a sequence of bytes of length <bytes> from the previous line. It
 661    is a YAML file containing all tube names as a list of strings.
 662
 663 The list-tube-used command returns the tube currently being used by the
 664 client. Its form is:
 665
 666 list-tube-used\r\n
 667
 668 The response is:
 669
 670 USING <tube>\r\n
 671
 672  - <tube> is the name of the tube being used.
 673
 674 The list-tubes-watched command returns a list tubes currently being watched by
 675 the client. Its form is:
 676
 677 list-tubes-watched\r\n
 678
 679 The response is:
 680
 681 OK <bytes>\r\n
 682 <data>\r\n
 683
 684  - <bytes> is the size of the following data section in bytes.
 685
 686  - <data> is a sequence of bytes of length <bytes> from the previous line. It
 687    is a YAML file containing watched tube names as a list of strings.
 688
 689 The quit command simply closes the connection. Its form is:
 690
 691 quit\r\n
 692
 693 The pause-tube command can delay any new job being reserved for a given time. Its form is:
 694
 695 pause-tube <tube-name> <delay>\r\n
 696
 697  - <tube> is the tube to pause
 698
 699  - <delay> is an integer number of seconds to wait before reserving any more
 700    jobs from the queue
 701
 702 There are two possible responses:
 703
 704  - "PAUSED\r\n" to indicate success.
 705
 706  - "NOT_FOUND\r\n" if the tube does not exist.
 707