tuber 0.0.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56b8831d5bdb6338f58cee603b906c4d41a4c36a0a4ac497ab3761838e8e5ffa
-  data.tar.gz: 361c630c0d818b347dc033ba14c6679a60ea1d35e8bfb22feae2f86ac9ca151b
+  metadata.gz: 5bf9725eaee223b9a587d41a70472161997c0792a7e3ad7917488e8e5dbacb62
+  data.tar.gz: 4759d84c9fae6eda87ed77f26817b6eae8d88fb2d80addf98723530c99551f7b
 SHA512:
-  metadata.gz: 39705970d8f4128a944dbb48741cebfaf34071eba99a50c5ee308c4b5f5d416d9c6ae2b054ea792701aea751da3fc26fc683d1bad074c38642d9911dd03c2d0e
-  data.tar.gz: 1e3e6de54b17990613c44b81d4318cfc5b6dcef81f94bef600614ca93cccf29503c3ab63dbc34decc44a8e2a63def7a6008a029039bd0a87f84dcb14a37e92e0
+  metadata.gz: 712f68857c4fcbedeaee298e94499abc9134337b1cd30de8f32c6a77fc8e640062bd6b1f0ba45122031d79a3c85cba7622c228f2d4447427e0d90c95668c6c47
+  data.tar.gz: 6bc153d12ffc33d3dcdd772ea31e8b2675a672779ace7812748bbd00c64346382bfea7c7d843ed0a24e610117f638f81445e0696dcfffa11633d93cc275cccd4

data/.github/workflows/ruby.yml

@@ -0,0 +1,68 @@
+# CI runs the full suite against Tuber (the primary target) and the portable
+# subset against stock beanstalkd (Tuber-only tests skip via require_tuber!).
+
+name: Build Status
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: tuber (ruby ${{ matrix.ruby-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["2.7", "3.0", "3.1", "3.2", "3.3", "3.4", "4.0"]
+
+    steps:
+    - uses: actions/checkout@v4
+    # Not a service container: the image's entrypoint needs the `server`
+    # subcommand, and services can't pass a command.
+    - name: Start tuber
+      run: |
+        docker run -d --name tuber -p 11300:11300 ghcr.io/tuberq/tuber:latest server
+        for i in $(seq 1 30); do (echo > /dev/tcp/127.0.0.1/11300) 2>/dev/null && exit 0; sleep 1; done
+        docker logs tuber; exit 1
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - name: Run tests
+      run: bundle exec rake test:full
+      env:
+        TUBER_TEST_ADDRESS: 127.0.0.1
+
+  beanstalkd-compat:
+    name: beanstalkd compat (ruby ${{ matrix.ruby-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["2.7", "4.0"]
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Download & Extract beanstalkd
+      run: curl -L https://github.com/beanstalkd/beanstalkd/archive/refs/tags/v1.13.tar.gz | tar xz
+    - name: Make beanstalkd
+      run: make
+      working-directory: beanstalkd-1.13
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+    - name: Daemonize beanstalkd
+      run: ./beanstalkd-1.13/beanstalkd -l 127.0.0.1 &
+    - name: Run tests
+      run: bundle exec rake test:full
+      env:
+        TUBER_TEST_ADDRESS: 127.0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+_yardoc
+.bundle
+.config
+.yardoc
+*.gem
+*.rbc
+coverage
+doc/
+Gemfile.lock
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.yardopts

@@ -0,0 +1,8 @@
+--output-dir doc/
+--readme README.md
+--title Tuber
+--markup-provider=redcarpet
+--markup=markdown
+--protected
+--no-private
+lib/tuber/**/*.rb

data/CHANGELOG.md

@@ -0,0 +1,112 @@
+# CHANGELOG for the tuber gem
+
+The tuber gem is a fork of [beaneater](https://github.com/beanstalkd/beaneater), taken at
+beaneater 1.1.4. Entries from 1.1.4 down are beaneater's history, kept for reference.
+(0.0.1 was an empty placeholder published to claim the gem name.)
+
+## 0.5.1 (August 13 2026)
+
+* Fix empty keyword arguments forwarded through `Tube#transmit`, `Tubes#transmit` and `Jobs#transmit` arriving as an extra positional `{}` on Ruby 2.7
+* CI: start the Tuber container with an explicit `server` subcommand, add Ruby 4.0 to the test matrix
+
+## 0.5.0 (August 13 2026)
+
+First functional release under the `tuber` name. Versioning restarts below 1.0
+while the Tuber-first API settles; 1.0.0 will follow once it has. Entries below
+1.1.4 with earlier version numbers are beaneater history.
+
+* **Renamed from `beaneater` to `tuber`** (briefly `russet` while the gem name was being freed up, though never published under that name). The `Beaneater` class is now `Tuber`, and `require 'beaneater'` becomes `require 'tuber'`. Nothing else changed in the rename — see "Migrating from beaneater" in the README.
+* Fix `_with_retry` retransmitting non-idempotent commands (`put`/`delete`/`release`/`bury`/`touch`/`kick` and batch variants) after a reconnect: the first send's fate is unknown, so a re-sent `put` could duplicate a job and a re-sent `delete` could raise `NOT_FOUND` for work that succeeded. These verbs now reconnect (and re-watch tubes) but re-raise the original connection error so the caller decides; idempotent commands keep the transparent retry.
+* Add `Jobs#touch_all` (Tuber 0.12.0+): one-command heartbeat for every job the connection holds, returning how many were still held
+* Add `Tube#flush_buried` (Tuber only): atomically deletes only the buried jobs in a tube, returning the count
+* Add optional long-poll `timeout` to `reserve_batch` (Tuber only): `tubes.reserve_batch(count, timeout)` blocks up to `timeout` seconds for the first job, then drains what's ready
+* Add `connect_timeout` (Ruby 3+), `resolv_timeout` (Ruby 3+), `read_timeout`, and `write_timeout` configuration options (@rveznaver)
+* Fix fractional timeout handling for `read_timeout` and `write_timeout` socket options
+* Add `TUBER_URL` environment variable and `config.tuber_url` as the primary way to point at a server; `BEANSTALKD_URL` and `config.beanstalkd_url` remain as compatible fallbacks/aliases
+* Tests can target a specific server via `TUBER_TEST_ADDRESS`, and Tuber-only tests skip automatically against stock beanstalkd; CI runs the full suite against Tuber and the portable subset against beanstalkd
+* Fix `StatStruct#[]` raising a `SyntaxError` when looking up hyphenated beanstalkd keys (e.g. `stats['current-jobs-ready']`); keys are now underscored before lookup to match how they are stored
+
+## 1.1.4 (March 6 2026)
+
+* Add frozen string literal comments for Ruby 3.4 compatibility (@nearapogee)
+* Update tests for Ruby 3.4.x (@nearapogee)
+* Add GitHub Actions CI workflow (@Ifiht)
+* Update README.md (@Ifiht)
+
+## 1.1.3 (Oct 14 2022)
+
+* Fixes issue introduced in 1.1.2 re YML parsing (@pond)
+* Fix job lookup test so it passes again
+
+## 1.1.2 (Oct 10 2022)
+
+* Fixes beaneater when used with Ruby 3.1 and YAML 4 (@pond)
+
+## 1.1.1 (April 27th 2021)
+
+* Support Ruby 3 keyword arguments (@yahonda)
+* Add CI for Ruby 3 (@yahonda)
+
+## 1.1.0 (April 25th 2021)
+
+* 'clear' behavior was failing unexpectedly, swallow issues during delete as well (@bfolkens)
+* Fix assigned but unused variables (@utilum)
+* Fix last_used tube not stored (@albb0920)
+* Fix deprecation warning in ruby 2.7 (@albb0920)
+* Fix watched tubes not restored after reconnect (@albb0920)
+* Fix keyword arguemnt warning (@albb0920)
+
+## 1.0.0 (April 26th 2015)
+
+* Beginning from version 1.0.0 the support for `Beaneater::Pool` has been dropped (@alup)
+* `Jobs#find_all` method has been removed, since it is no longer necessary after removing pool (@alup)
+* `Tubes` is now an enumerable allowing `tubes` to be handled as a collection (@Aethelflaed)
+
+## 0.3.3 (August 16th 2014)
+
+* Fix failure when job is not defined and fix exception handling for jobs (@nicholasorenrawlings)
+* Add reserve_timeout option to job processing (@nicholasorenrawlings)
+* Add travis-ci badge (@tdg5)
+* Fix tests to run more reliably (@tdg5)
+
+## 0.3.2 (Sept 15 2013)
+
+* Fix #29 ExpectedCrlfError name and invocation (@tdg5)
+
+## 0.3.1 (Jun 28 2013)
+
+* Fixes issue with "chomp" nil exception when losing connection (Thanks @simao)
+* Better handling of unknown or invalid commands during transmit
+* Raise proper CRLF exception (Thanks @carlosmoutinho)
+
+## 0.3.0 (Jan 23 2013)
+
+* Replace Telnet with tcpsocket thanks @vidarh
+
+## 0.2.2 (Dec 2 2012)
+
+* Fixes status and ID parsing in a response (Thanks @justincase)
+
+## 0.2.1 (Dec 1 2012)
+
+* Convert command to ASCII_8Bit to avoid gsub issues
+
+## 0.2.0 (Nov 12 2012)
+* Fix 1.8.7 compatibility issues
+* Add configuration block to beaneater and better job parsing
+* BREAKING: json jobs now return as string by default not hashes
+
+## 0.1.2 (Nov 7 2012)
+
+* Add timeout: false to transmit to allow longer reserve
+
+## 0.1.1 (Nov 4 2012)
+
+* Add `Jobs#find_all` to fix #10
+* Fixed issue with `tubes-list` by merging results
+* Add `Job#ttr`, `Job#pri`, `Job#delay`
+* Improved yardocs coverage and accuracy
+
+## 0.1.0 (Nov 1 2012)
+
+* Initial release!

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in tuber.gemspec
+gemspec
+
+group :development do
+  gem 'redcarpet', '~> 1'
+  gem 'github-markup'
+  gem 'yard'
+end
+
+group :development, :test do
+  gem 'coveralls', :require => false
+end

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2012 Nico Taing
+Copyright (c) 2026 Dan Milne
+
+Tuber is a fork of beaneater (https://github.com/beanstalkd/beaneater),
+originally written by Nico Taing and contributors, and is distributed under
+the same MIT License.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,14 +1,385 @@
-# tuber
+# Tuber
 
-Ruby client for [Tuber](https://github.com/tuberq/tuber), a fast job queue server written in Rust. Tuber is wire-compatible with [beanstalkd](https://github.com/beanstalkd/beanstalkd) and extends it with unique jobs, concurrency control, job group pipelines, batch operations, weighted queues, and offloaded job bodies.
+The Ruby client for [Tuber](https://github.com/tuberq/tuber), the simple, fast job queue server. One binary, zero dependencies — with unique/idempotent jobs, concurrency keys, job group pipelines, weighted tubes and batch operations built in.
 
-**This gem currently reserves the name while the client is finalized.** In the meantime, use [russet](https://github.com/dkam/russet) — a beaneater fork with full support for Tuber's protocol extensions — to talk to Tuber or beanstalkd from Ruby.
+Tuber (the server and this gem) is wire-compatible with [beanstalkd](https://github.com/beanstalkd/beanstalkd): point this client at a stock beanstalkd and everything except the Tuber-only extensions works unchanged. The gem is a fork of [beaneater](https://github.com/beanstalkd/beaneater), so it is also a drop-in beaneater replacement — see [Migrating from beaneater](#migrating-from-beaneater).
 
-## Links
+## Quick Start
 
-- Tuber server: https://github.com/tuberq/tuber
-- Ruby client (current): https://github.com/dkam/russet
+```ruby
+@tuber = Tuber.new('localhost:11300')
 
-## License
+@tube = @tuber.tubes["my-tube"]
+@tube.put '{"key": "foo"}', pri: 5
+@tube.put '{"key": "bar"}', delay: 3
 
-MIT
+while @tube.peek(:ready)
+  job = @tube.reserve
+  puts job.body
+  job.delete
+end
+
+@tuber.close
+```
+
+## Installation
+
+Install the [tuber server](https://github.com/tuberq/tuber) (a single binary; `brew install tuberq/tuber/tuber`, Docker image `ghcr.io/tuberq/tuber`, or a [release binary](https://github.com/tuberq/tuber/releases)) — or use an existing beanstalkd — then add the gem:
+
+```ruby
+# Gemfile
+gem 'tuber'
+```
+
+## Migrating from beaneater
+
+Tuber forked from beaneater 1.1.4. The rename is the only breaking change — every
+method, option and return value is unchanged. Two things to update:
+
+```ruby
+require 'beaneater'                        # before
+require 'tuber'                           # after
+
+@beanstalk = Beaneater.new('localhost:11300')  # before
+@beanstalk = Tuber.new('localhost:11300')      # after
+```
+
+That includes the nested constants (`Beaneater::Job` → `Tuber::Job`), the error
+classes (`Beaneater::NotConnected` → `Tuber::NotConnected`) and the configuration
+block (`Beaneater.configure` → `Tuber.configure`). In most codebases a
+case-sensitive `Beaneater` → `Tuber` and `beaneater` → `tuber` replacement is the
+whole migration.
+
+The `BEANSTALKD_URL` environment variable is still honoured (it's a beanstalkd
+convention, not a beaneater one), though `TUBER_URL` now takes precedence.
+Likewise `config.beanstalkd_url` remains as an alias for `config.tuber_url`.
+
+## Usage
+
+### Configuration
+
+To setup advanced options for tuber, you can pass configuration options using:
+
+```ruby
+Tuber.configure do |config|
+  # config.default_put_delay   = 0
+  # config.default_put_pri     = 65536
+  # config.default_put_ttr     = 120
+  # config.job_parser          = lambda { |body| body }
+  # config.job_serializer      = lambda { |body| body }
+  # config.tuber_url           = 'localhost:11300'
+  # config.connect_timeout     = nil
+  # config.resolv_timeout      = nil
+  # config.read_timeout        = nil
+  # config.write_timeout       = nil
+end
+```
+
+The above options are all defaults, so only include a configuration block if you need to make changes.
+
+`connect_timeout` and `resolv_timeout` are passed through to `TCPSocket.new` on Ruby 3.0 and newer (ignored on Ruby < 3.0 for compatibility). `read_timeout` and `write_timeout` apply socket read and write timeouts via `setsockopt`.
+
+### Connection
+
+```ruby
+@tuber = Tuber.new('10.0.1.5:11300')
+
+# Or use ENV['TUBER_URL'] (or ENV['BEANSTALKD_URL'])
+@tuber = Tuber.new
+
+@tuber.close
+```
+
+### Tubes
+
+Tubes are named work queues. Jobs are `put` into the used tube and `reserve`d from watched tubes. Each tube has a _ready_, _delayed_, and _buried_ queue.
+
+```ruby
+@tube = @tuber.tubes.find("some-tube")
+
+# Watch tubes for reserving jobs
+@tuber.tubes.watch!('some-tube')        # watch only these tubes
+@tuber.tubes.watch('another-tube')       # append to watch list
+@tuber.tubes.ignore('some-tube')         # stop watching
+
+# List tubes
+@tuber.tubes.all       # => [<Tube name='foo'>, <Tube name='bar'>]
+@tuber.tubes.used      # => <Tube name='bar'>
+@tuber.tubes.watched   # => [<Tube name='foo'>]
+
+# Manage tubes
+@tube.pause(3)        # pause for 3 seconds
+@tube.clear           # delete all jobs
+@tube.flush           # delete all jobs, returns count
+@tube.flush_buried    # delete only buried jobs (Tuber only), returns count
+```
+
+Each client manages two separate concerns: **use**/**using** controls where `put` places jobs, and **watch**/**watching** controls where `reserve` takes jobs from. These are fully orthogonal.
+
+### Jobs
+
+A job has a body (string) and metadata. The typical lifecycle:
+
+```
+   put            reserve               delete
+  -----> [READY] ---------> [RESERVED] --------> *poof*
+```
+
+Jobs are in one of three states:
+
+| State   | Description |
+| ------- | ----------- |
+| ready   | Waiting to be reserved and processed. |
+| delayed | Waiting to become ready after a delay. |
+| buried  | Held aside after failure, waiting to be kicked. |
+
+#### Inserting jobs
+
+```ruby
+@tube.put "job-data-here"
+@tube.put({foo: 'bar'}.to_json)
+@tube.put "job-data-here", pri: 1000, delay: 50, ttr: 200
+```
+
+- **pri** — integer < 2^32, lower values run first (default: 65536)
+- **delay** — seconds to wait before the job becomes ready (default: 0)
+- **ttr** — time to run, seconds a worker has to finish the job (default: 120)
+
+#### Reserving and processing jobs
+
+```ruby
+job = @tuber.tubes.reserve      # blocks until a job is available
+job = @tuber.tubes.reserve(5)   # wait up to 5 seconds
+
+puts job.body
+puts job.tube
+puts job.stats.state  # => 'reserved'
+
+job.touch    # extend ttr
+job.delete   # success
+job.release delay: 5  # retry later
+job.bury     # set aside for inspection
+```
+
+#### Peeking and kicking
+
+```ruby
+@tuber.jobs.find(123)       # peek at a specific job
+@tube.peek(:ready)              # peek at next ready job
+@tube.peek(:buried)
+@tube.peek(:delayed)
+
+@tuber.tubes['some-tube'].kick(3)  # kick 3 buried jobs back to ready
+```
+
+#### Automatic processing
+
+Register handlers for tubes and let `process!` loop over incoming jobs:
+
+```ruby
+@tuber.jobs.register('some-tube', retry_on: [SomeError]) do |job|
+  do_something(job)
+end
+
+@tuber.jobs.register('other-tube') do |job|
+  do_something_else(job)
+end
+
+@tuber.jobs.process!
+```
+
+The loop reserves a job, calls the matching handler, then: deletes on success, releases on `retry_on` errors, and buries on other exceptions. Raise `AbortProcessingError` to stop the loop.
+
+### Job Dependencies (Tuber only)
+
+When using [Tuber](https://github.com/tuberq/tuber), you can group related jobs and chain dependent work using `group:` and `after:` options on `put`. After-jobs are held until every job in the group they depend on has been deleted:
+
+```ruby
+# Fan-out: enqueue grouped work
+@tube.put "import-row-1", group: "import"
+@tube.put "import-row-2", group: "import"
+
+# Fan-in: this job waits until all "import" jobs are deleted
+@tube.put "send-summary", after: "import"
+```
+
+Chain stages together by combining `after:` and `group:` on the same job to build a simple DAG pipeline:
+
+```ruby
+@tube.put "row-1", group: "extract"
+@tube.put "row-2", group: "extract"
+@tube.put "transform", after: "extract", group: "transform"
+@tube.put "load",      after: "transform"
+```
+
+Here `transform` waits for the extract group to finish, then becomes part of the `transform` group. `load` waits for `transform` to complete.
+
+Buried jobs block group completion — kick them to let the group finish. Group names are global and can span multiple tubes.
+
+### Unique Jobs / Idempotency (Tuber only)
+
+Prevent duplicate jobs with the `idempotency:` option. If a job with the same key already exists in the tube, the original job is returned instead of creating a duplicate:
+
+```ruby
+@tube.put "send-report", idempotency: "daily-report"
+# => <Tuber::Job id=1 body="send-report">
+
+@tube.put "send-report", idempotency: "daily-report"
+# => <Tuber::Job id=1 body="send-report">  (same job, no duplicate created)
+```
+
+The key is scoped to the tube and cleared when the job is deleted, so the same key can be reused afterwards.
+
+Add a cooldown TTL to keep deduplicating for N seconds after deletion — useful for preventing rapid resubmission:
+
+```ruby
+@tube.put "send-report", idempotency: "daily-report", idempotency_ttl: 300
+```
+
+### Concurrency Keys (Tuber only)
+
+Limit parallel processing of related jobs. When a job with a concurrency key is reserved, other ready jobs sharing the same key are hidden from `reserve` until the reservation ends:
+
+```ruby
+# Only one job per user can be processed at a time
+@tube.put "process-user-42", concurrency: "user-42"
+@tube.put "process-user-42-again", concurrency: "user-42"
+```
+
+The second job won't be reserved until the first is deleted, released, or buried. Set a higher limit to allow N concurrent reservations:
+
+```ruby
+# Allow up to 3 concurrent API jobs
+@tube.put "api-call-1", concurrency: "api", concurrency_limit: 3
+@tube.put "api-call-2", concurrency: "api", concurrency_limit: 3
+```
+
+### Weighted Tubes (Tuber only)
+
+By default, `reserve` picks the highest-priority job across all watched tubes. Switch to weighted mode to select tubes randomly in proportion to their weight:
+
+```ruby
+@tuber.tubes.watch('email')
+@tuber.tubes.watch('notifications', weight: 2)
+@tuber.tubes.watch('batch-jobs', weight: 6)
+
+@tuber.tubes.reserve_mode(:weighted)
+
+job = @tuber.tubes.reserve  # batch-jobs selected 6x as often as email
+```
+
+Tubes default to weight 1. Switch back with `reserve_mode(:fifo)`.
+
+### Batch Reserve (Tuber only)
+
+Reserve multiple jobs atomically in a single call:
+
+```ruby
+jobs = @tuber.tubes.reserve_batch(10)  # up to 10 jobs
+
+jobs.each do |job|
+  process(job)
+  job.delete
+end
+```
+
+By default `reserve_batch` is non-blocking — it returns whatever is ready
+immediately, possibly an empty array. Pass a timeout (in seconds) to long-poll
+instead: the call blocks until the first job arrives, then drains everything
+ready up to `count`, or returns an empty array when the timeout elapses. This
+avoids hot-looping a worker on empty polls.
+
+```ruby
+jobs = @tuber.tubes.reserve_batch(10, 30)  # block up to 30s for the first job
+```
+
+While blocked, a positive-timeout batch reserve may raise
+`Tuber::DeadlineSoonError` if one of the connection's already-reserved jobs
+is about to hit its TTR — service that job, then reserve again.
+
+### Batch Touch (Tuber 0.12.0+)
+
+A batch reserve starts the TTR clock on every job at the same instant, but a
+worker processes them serially — so the tail of a large batch can expire and
+return to the queue while the worker is still busy. `touch_all` extends the TTR
+of every job the connection currently holds in a single command:
+
+```ruby
+jobs = @tuber.tubes.reserve_batch(10)
+
+jobs.each do |job|
+  process(job)
+  job.delete
+  @tuber.jobs.touch_all   # heartbeat whatever is still held
+end
+```
+
+No ids are sent: the server tracks the reserved set per connection, so jobs
+already deleted, released, buried or lost to a TTR timeout are simply absent.
+Each job keeps its own TTR — deadlines are extended individually, not levelled
+onto a common value.
+
+The return value is how many jobs the connection *actually* still holds. A count
+lower than expected means jobs hit their TTR and went back to the queue while the
+worker was busy — otherwise invisible, since nothing notifies a worker that it
+lost a job.
+
+### Stats
+
+```ruby
+@tuber.stats                            # server-wide stats
+@tuber.tubes['some-tube'].stats         # tube stats
+@tuber.jobs[some_job_id].stats          # job stats
+```
+
+## Configuration
+
+```ruby
+Tuber.configure do |config|
+  config.default_put_delay   = 0
+  config.default_put_pri     = 65536
+  config.default_put_ttr     = 120
+  config.job_parser          = lambda { |body| body }
+  config.job_serializer      = lambda { |body| body }
+  config.tuber_url           = 'localhost:11300'
+end
+```
+
+The `job_serializer` is applied to every `put` body — useful for automatic JSON encoding:
+
+```ruby
+Tuber.configure do |config|
+  config.job_serializer = lambda { |body| JSON.dump(body) }
+end
+```
+
+## Error Handling
+
+| Error                         | Description |
+| ----------------------------- | ----------- |
+| Tuber::NotConnected       | Cannot connect to the server. |
+| Tuber::InvalidTubeName    | Tube name is not valid. |
+| Tuber::NotFoundError      | Job or tube not found. |
+| Tuber::TimedOutError      | Reserve timed out. |
+| Tuber::JobNotReserved     | Action requires a reserved job. |
+
+See the [Tuber protocol](https://github.com/tuberq/tuber/blob/main/docs/protocol.md) (a superset of the [beanstalk protocol](https://github.com/beanstalkd/beanstalkd/blob/master/doc/protocol.txt)) for additional error types.
+
+## Resources
+
+ * [Tuber](https://github.com/tuberq/tuber)
+ * [Tuber protocol](https://github.com/tuberq/tuber/blob/main/docs/protocol.md)
+ * [Tuber on RubyGems](https://rubygems.org/gems/tuber)
+ * [Beanstalkd](https://github.com/beanstalkd/beanstalkd) and the [beanstalk protocol](https://github.com/beanstalkd/beanstalkd/blob/master/doc/protocol.txt)
+ * [Backburner](https://github.com/nesquena/backburner) — Ruby job queue for Rails/Sinatra
+
+## Contributors
+
+Tuber is maintained by [Dan Milne](https://github.com/dkam), and builds on the work of
+everyone who wrote beaneater, from which it is forked:
+
+ - [Nico Taing](https://github.com/Nico-Taing) - Creator and co-maintainer of beaneater
+ - [Nathan Esquenazi](https://github.com/nesquena) - Contributor and co-maintainer
+ - [Keith Rarick](https://github.com/kr) - Much code inspired and adapted from beanstalk-client
+ - [Vidar Hokstad](https://github.com/vidarh) - Replaced telnet with correct TCP socket handling
+ - [Andreas Loupasakis](https://github.com/alup) - Improve test coverage, improve job configuration