tuber 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bf9725eaee223b9a587d41a70472161997c0792a7e3ad7917488e8e5dbacb62
-  data.tar.gz: 4759d84c9fae6eda87ed77f26817b6eae8d88fb2d80addf98723530c99551f7b
+  metadata.gz: 3dad07a18da118a0c3f50cdb00de169fbc73c4691e7484c422d98bccd12b750e
+  data.tar.gz: eeb2247e67cf72d407c578f9a0e2e61820ebc3b3594ce6da39f90eb312ef23d4
 SHA512:
-  metadata.gz: 712f68857c4fcbedeaee298e94499abc9134337b1cd30de8f32c6a77fc8e640062bd6b1f0ba45122031d79a3c85cba7622c228f2d4447427e0d90c95668c6c47
-  data.tar.gz: 6bc153d12ffc33d3dcdd772ea31e8b2675a672779ace7812748bbd00c64346382bfea7c7d843ed0a24e610117f638f81445e0696dcfffa11633d93cc275cccd4
+  metadata.gz: 476561b12a94b1017ec600d249236ad1296a3760c19c8fae126bace4ae26de1b9d448c54b74413dbf7805eb3ed91d8bf4ee53c17a148fe194705c43783e44e71
+  data.tar.gz: d3e34a35f30ee2ae578bdfb1f88c243585a2bbfcb9de4e0d76241d1839e35cb51715fcd5a9921ff5e002557c1d2f53f66aad1daea18c6114ae62687d43b74e58

data/CHANGELOG.md

@@ -4,6 +4,43 @@ The tuber gem is a fork of [beaneater](https://github.com/beanstalkd/beaneater),
 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.7.0 (October 11 2026)
+
+Recurring schedules. A Tuber with the scheduler runs an app's recurring jobs
+itself, so the app can drop its scheduler process. This release adds the client
+side. Nothing changes for code that doesn't call it.
+
+* Add `Tuber#schedules`: `sync(owner) { |s| s.add ... }` replaces an owner's whole set of entries in one step, and `list` and `stats` show what the server holds. `s.add` takes `cron:` (with `zone:`), `every:` (with `offset:`) or a raw `spec:`, the put options with their usual defaults and value shapes, and `catchup:`. See "Recurring Schedules" in the README.
+* `sync` refuses an empty set unless given `allow_empty: true`. An empty sync removes every entry the owner has, and an app that loaded an empty config by mistake shouldn't wipe its schedule.
+* `sync` runs on a short-lived connection of its own, closed afterwards. A worker blocked in `reserve` on the client's connection can't hold it up, and an error partway can't leave that connection mid-sync. If the socket drops, the whole sync is re-run from the start, never resumed partway.
+* Add `Tuber::ScheduleSyncError` for a sync tuber refuses. It names the owner, the refused entry (`#entry`) and tuber's reply (`#status`). The gem aborts the sync before raising, so the previous schedule keeps running. `#applied?` is true for the one exception: a commit that took effect but couldn't be written to disk.
+* `schedules.stats` returns a `StatStruct`, like tube and job stats: `stats.next_fire` or `stats["next-fire"]`. Times come back as `Time` in the entry's own zone, counters as Integers, and empty fields as nil.
+* Add `Connection#transmit_raw`, which returns an `OK <bytes>` body unparsed. `transmit`'s YAML handling rewrites `:`, `-` and `~` inside values, and schedule stats are full of them.
+* Fix a put refused with `OUT_OF_STORAGE` coming back as a result hash, as though it had succeeded. Tuber sends that reply once a persistent server's `--max-storage-bytes` budget is spent. It now raises the new `Tuber::OutOfStorageError`, as `OUT_OF_MEMORY` raises `OutOfMemoryError`.
+* `Tuber::UnexpectedResponse.new` takes an optional message as a third argument.
+
+## 0.6.0 (September 16 2026)
+
+Reconnection release. The gem retried reconnects but not connects, so a
+consumer that caught `Tuber::NotConnected` and built a new client — the obvious
+thing to write — never reached the retrying path, and a server restart of a few
+seconds was enough to kill it. `reconnect!` makes the existing healing
+reachable, and `connect_retries` gives a cold start a window wider than the
+outage. Existing behaviour is unchanged until `connect_retries` is raised, with
+two exceptions noted below: `NotConnected` messages gained a suffix (the
+historical text remains a strict prefix), and a connect error other than
+`ECONNREFUSED` is now retried and surfaced as `NotConnected` rather than
+escaping as a raw `Errno`.
+
+* Add `Tuber#reconnect!` / `Connection#reconnect!`: re-establishes the connection and replays its tube state (watched tubes with their weights, the used tube, the reserve mode). This healing only ever ran when the connection itself noticed a dropped socket, so a consumer that caught `Tuber::NotConnected` had no way to reach it and had to build a new client — which starts with no tube state and has to re-watch and re-weight every tube by hand.
+* Add `connect_retries` and `connect_retry_interval` configuration. The initial connect took exactly one attempt with no retry, so a cold start during a server restart — a web boot, a fresh `Tuber.new`, a daemon rebuilding its client after an error — failed where an established connection would have healed. Defaults to the historical single attempt; raising it also lifts the reconnect budget of connections already established, so one knob covers both.
+* Retry a connect that fails for any reason the server might be unreachable (`ETIMEDOUT`, `EHOSTUNREACH`, `ENETUNREACH`, DNS failure, connect timeout), not only `ECONNREFUSED`. Those previously escaped as a raw `Errno` from the middle of a reconnect, a class no consumer thinks to rescue.
+* `Tuber::NotConnected` now names the underlying error in its message and keeps it as the exception's `cause`. A bare `rescue` collapsed every connect failure into "Connection to beanstalk '...' is closed!", hiding whether the server refused, timed out, or was never resolved — exactly what you need during an outage.
+* `Connection#close` no longer raises if the socket cannot be closed cleanly; the connection is gone either way and `reconnect!` must not fail on the way to replacing it.
+* Fix a reconnect silently dropping per-tube weights and the connection's reserve mode ([#1](https://github.com/tuberq/tuber-gem/issues/1)). Both are per-connection server state that a fresh socket resets, so a consumer that healed across a brief server restart kept working but quietly fell back to FIFO. `Connection` now remembers the weight each tube was watched with and the mode set by `Tubes#reserve_mode`, and replays them (watch, then `ignore default`, then `reserve-mode`) when re-initialising tubes.
+* Fix `_initialize_tubes` sending `ignore default` after a reconnect even when `default` was one of the watched tubes, which dropped it from the watch list.
+* `Connection#add_to_watched` now takes an optional weight as a second argument, and `Connection#tube_weights` / `Connection#reserve_mode` expose the replayed state.
+
 ## 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

data/Gemfile

@@ -6,7 +6,9 @@ source 'https://rubygems.org'
 gemspec
 
 group :development do
-  gem 'redcarpet', '~> 1'
+  # 3.5.1 fixes CVE-2020-26298 (XSS when processing quotes). The old '~> 1'
+  # pin was inherited from beaneater and capped us below the fix.
+  gem 'redcarpet', '~> 3.6', '>= 3.5.1'
   gem 'github-markup'
   gem 'yard'
 end

data/README.md

@@ -72,6 +72,8 @@ Tuber.configure do |config|
   # config.resolv_timeout      = nil
   # config.read_timeout        = nil
   # config.write_timeout       = nil
+  # config.connect_retries        = 0
+  # config.connect_retry_interval = 1
 end
 ```
 
@@ -90,6 +92,47 @@ The above options are all defaults, so only include a configuration block if you
 @tuber.close
 ```
 
+#### Surviving a server restart
+
+An established connection heals itself: when a command notices the socket has
+died, the connection reconnects, replays its tube state, and re-sends the
+command (except for the non-idempotent verbs — `put`, `delete`, `release`,
+`bury`, `touch`, `kick` — where a blind re-send could duplicate a job or act on
+a reservation that died with the old socket, so the original error is raised
+for the caller to decide).
+
+That healing gets three connect attempts a second apart. A server restart
+typically takes longer, so give the client a budget that outlasts it:
+
+```ruby
+Tuber.configure do |config|
+  config.connect_retries        = 15   # extra attempts, 0 = a single attempt
+  config.connect_retry_interval = 1    # seconds between them
+end
+```
+
+`connect_retries` covers both a cold start (`Tuber.new` while the server is
+down) and reconnects on a client you already hold. It defaults to `0` — a
+single attempt — which is the historical behaviour.
+
+When a command does surface `Tuber::NotConnected`, heal the client you have
+rather than building a new one:
+
+```ruby
+begin
+  job = @tuber.tubes.reserve
+rescue Tuber::NotConnected
+  @tuber.reconnect!   # watched tubes, their weights, the used tube and the
+  retry               # reserve mode all come back with it
+end
+```
+
+A fresh `Tuber.new` starts with no tube state, so a worker that reconnects that
+way has to re-watch and re-weight every tube by hand — and will silently fall
+back to FIFO if it forgets the reserve mode. `reconnect!` replays all of it.
+It takes the same budget as the config, overridable per call:
+`@tuber.reconnect!(tries: 30, retry_interval: 2)`.
+
 ### 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.
@@ -270,6 +313,10 @@ job = @tuber.tubes.reserve  # batch-jobs selected 6x as often as email
 
 Tubes default to weight 1. Switch back with `reserve_mode(:fifo)`.
 
+Weights and reserve mode are per-connection server state. The client remembers
+both and replays them if the connection has to be re-established, so a worker
+that heals across a server blip keeps reserving by weight.
+
 ### Batch Reserve (Tuber only)
 
 Reserve multiple jobs atomically in a single call:
@@ -324,6 +371,98 @@ lower than expected means jobs hit their TTR and went back to the queue while th
 worker was busy — otherwise invisible, since nothing notifies a worker that it
 lost a job.
 
+### Recurring Schedules (Tuber only)
+
+Tuber can run an app's recurring jobs itself, so the app needs no scheduler
+process (whenever, rufus-scheduler, sidekiq-cron, a `bin/scheduler` container).
+The app sends its complete schedule under a name of its choosing, the *owner*,
+and tuber puts each entry's body into its tube at the times the entry names. A
+fire is an ordinary put: workers reserve, delete and bury it like any other job.
+
+```ruby
+tuber = Tuber.new
+
+result = tuber.schedules.sync("splat") do |s|
+  s.add "monitor_evaluation", tube: "splat.checkins", every: 60,
+        body: { class: "Monitors::EvaluateJob", args: [] }.to_json,
+        idp: "monitor_evaluation", pri: 1024
+  s.add "histogram_rollup", tube: "splat.maintenance", cron: "5 * * * *",
+        body: { class: "Analytics::HistogramRollupJob", args: [] }.to_json,
+        idp: "histogram_rollup", con: "maintenance", pri: 1024
+  s.add "data_retention", tube: "splat.maintenance",
+        cron: "0 2 * * *", zone: "Australia/Melbourne",
+        body: { class: "Maintenance::RetentionJob", args: [] }.to_json,
+        idp: "data_retention", con: "maintenance", pri: 1024
+end
+result.to_h  # => {added: 3, changed: 0, removed: 0, unchanged: 0}
+```
+
+- **Send the complete set every time.** An entry you leave out is removed. An
+  edited entry keeps its name and is updated in place. An identical sync changes
+  nothing, not even when entries next fire, so every replica may run it.
+- **An empty set is refused** with `ArgumentError`, since it would remove every
+  entry the owner has. Pass `allow_empty: true` when that is what you mean.
+- **Sync when a release starts, not on reconnect.** Use a release step (a Kamal
+  `pre-deploy` hook, a Heroku `release` phase) or sync once at process boot.
+  Tuber keeps schedules across its own restarts (with `-b`), and during a
+  rolling deploy an old process re-syncing after a reconnect would put back
+  entries the new release removed. The gem never syncs on its own.
+- A sync uses a short-lived connection of its own, so a worker blocked in
+  `reserve` on the client's connection doesn't hold it up.
+
+`s.add` takes the entry's name and:
+
+| Option | |
+| --- | --- |
+| `tube:`, `body:` | Required. The body goes through `job_serializer`, as for `put` |
+| `cron:` | 5-field cron or a macro (`"@daily"`); `zone:` adds an IANA zone (default UTC) |
+| `every:` | Seconds, or `"10m"`, `"1h"`, `"1d"`, aligned to the Unix epoch; `offset:` shifts it |
+| `spec:` | The spec as tuber reads it, instead of `cron:` or `every:` |
+| `pri:`, `delay:`, `ttr:` | As for `put`, with the same defaults |
+| `idp:`, `con:`, `grp:`, `aft:` | As for `put`: `idp: "key"` or `["key", ttl]`, `con: "key"` or `["key", limit]` |
+| `catchup:` | For ticks missed while tuber was down: `:once` (default) fires once for the gap, an Integer fires it only if at most that many seconds late, `:never` skips it |
+
+A `con:` value is a key, not a number: every job with `con: "maintenance"`
+shares one slot, so entries that share it run one after another.
+
+Anything tuber would refuse that the gem can see — a bad name, two specs, a body
+that isn't a String — raises `ArgumentError` before anything is sent. When tuber
+refuses the sync, it raises `Tuber::ScheduleSyncError`, and nothing changed: the
+previous schedule keeps running. `#entry` names the refused entry (nil when tuber
+refused the sync as a whole) and `#status` gives tuber's reply, such as
+`BAD_SCHEDULE` for a zone typo like `Australia/Melborne`. The one exception is
+`#applied?`: the commit took effect but tuber couldn't write it to disk
+(`INTERNAL_ERROR`). It runs until tuber restarts, so sync again once the disk is
+fixed.
+
+```ruby
+begin
+  tuber.schedules.sync("splat") { |s| ... }
+rescue Tuber::ScheduleSyncError => e
+  Rails.logger.error(e.message)  # names the entry and the reason
+end
+```
+
+To see what tuber holds:
+
+```ruby
+tuber.schedules.list            # => [["splat", "data_retention"], ...] across owners
+tuber.schedules.list("splat")
+stats = tuber.schedules.stats("splat", "data_retention")  # nil if there's no such entry
+stats.next_fire                 # => 2026-10-12 02:00:00 +1100 (next_fire_2, next_fire_3 too)
+stats.last_result               # => "INSERTED 4711"
+stats.buried_streak             # => 0
+```
+
+**`idp:` and buried jobs.** With `idp:`, a fire is skipped while the previous
+fire's job is still in the tube, which is what you want when a run outlasts its
+interval. But a *buried* job keeps its key too, so every later fire dedups
+against it and queues nothing until it is kicked or deleted. `buried_streak`
+counts those fires: alert when it is above 0.
+
+Tuber's [scheduling guide](https://github.com/tuberq/tuber/blob/main/docs/scheduling.md)
+covers spec syntax, daylight saving, catch-up and monitoring.
+
 ### Stats
 
 ```ruby
@@ -342,6 +481,10 @@ Tuber.configure do |config|
   config.job_parser          = lambda { |body| body }
   config.job_serializer      = lambda { |body| body }
   config.tuber_url           = 'localhost:11300'
+
+  # Connect attempts; see "Surviving a server restart" above.
+  config.connect_retries        = 0
+  config.connect_retry_interval = 1
 end
 ```
 
@@ -362,6 +505,8 @@ end
 | Tuber::NotFoundError      | Job or tube not found. |
 | Tuber::TimedOutError      | Reserve timed out. |
 | Tuber::JobNotReserved     | Action requires a reserved job. |
+| Tuber::OutOfStorageError  | A persistent Tuber's disk budget (`--max-storage-bytes`) is spent. |
+| Tuber::ScheduleSyncError  | Tuber refused a schedule sync; see Recurring Schedules. |
 
 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.
 

data/lib/tuber/configuration.rb

@@ -15,6 +15,21 @@ class Tuber
     attr_accessor :read_timeout        # socket read timeout in seconds
     attr_accessor :write_timeout       # socket write timeout in seconds
 
+    # How hard a client tries to connect — "how long should this ride out a
+    # server restart", in one knob.
+    #
+    # An established connection has always retried when it notices a dropped
+    # socket (Tuber::Connection::MAX_RETRIES attempts), but the *initial*
+    # connect got exactly one: a cold start during an outage — a web boot, a
+    # fresh Tuber.new, a daemon rebuilding its client after an error — failed
+    # where a held connection would have healed.
+    #
+    # Defaults to that single attempt, so nothing changes until you raise it.
+    # Raising it covers the initial connect and lifts the reconnect budget of
+    # connections already established along with it.
+    attr_accessor :connect_retries          # extra connect attempts, 0 = one shot
+    attr_accessor :connect_retry_interval   # seconds between connect attempts
+
     def initialize
       @default_put_delay   = 0
       @default_put_pri     = 65536
@@ -26,6 +41,9 @@ class Tuber
       @resolv_timeout      = nil
       @read_timeout        = nil
       @write_timeout       = nil
+      @connect_retries     = 0
+      # Matches Tuber::Connection::DEFAULT_RETRY_INTERVAL, which is not loaded yet.
+      @connect_retry_interval = 1
     end
   end # Configuration
 end # Tuber

data/lib/tuber/connection.rb

@@ -33,7 +33,17 @@ class Tuber
     #   @returns [Array<String>] returns currently watched tube names
     # @!attribute tube_used
     #   @returns [String] returns currently used tube name
-    attr_accessor :tubes_watched, :tube_used
+    # @!attribute reserve_mode
+    #   @returns [String, Symbol, nil] the reserve mode set on this connection,
+    #     nil when it was never set (the server default is fifo)
+    attr_accessor :tube_used, :reserve_mode
+    attr_reader :tubes_watched
+
+    # @!attribute tube_weights
+    #   @returns [Hash{String => Integer}] weight last watched with, per tube.
+    #     Tubes watched without a weight are absent: the server resets a tube's
+    #     weight to 1 on a plain `watch`, so "no weight" is state worth keeping.
+    attr_reader :tube_weights
 
     # Default port value for beanstalk connection
     DEFAULT_PORT = 11300
@@ -49,6 +59,25 @@ class Tuber
     # keeps the transparent retry.
     NON_IDEMPOTENT_COMMANDS = %w[put delete delete-batch release bury touch touch-all kick kick-job].freeze
 
+    # Errno names that mean "the server is not reachable right now" during a
+    # connect attempt. Every one of them is worth another try: a host coming
+    # back from a restart answers EHOSTUNREACH or ETIMEDOUT as readily as
+    # ECONNREFUSED, and a raw Errno escaping the connection is a class no
+    # consumer thinks to rescue.
+    CONNECT_ERROR_NAMES = %w[
+      ECONNREFUSED ECONNRESET ECONNABORTED ETIMEDOUT
+      EHOSTUNREACH EHOSTDOWN ENETUNREACH ENETDOWN EPIPE
+    ].freeze
+
+    # The resolved exception classes, skipping any Errno the platform lacks.
+    # SocketError covers a name that will not resolve (a DNS server restarting
+    # alongside the queue), IO::TimeoutError a connect_timeout on Ruby >= 3.2.
+    CONNECT_ERRORS = (
+      CONNECT_ERROR_NAMES.map { |name| Errno.const_get(name) if Errno.const_defined?(name) }.compact +
+      [SocketError] +
+      (defined?(IO::TimeoutError) ? [IO::TimeoutError] : [])
+    ).freeze
+
     # Initializes new connection.
     #
     # @param [String] address beanstalkd instance address.
@@ -61,15 +90,23 @@ class Tuber
     #   @b.connection.host # => '127.0.0.1'
     #   @b.connection.port # => '11300'
     #
+    # @raise [Tuber::NotConnected] Could not connect. The underlying error is
+    #   named in the message and kept as the exception's +cause+.
+    #
     def initialize(address)
       @address = address || _host_from_env || Tuber.configuration.tuber_url
       @mutex = Mutex.new
       @tube_used = 'default'
       @tubes_watched = ['default']
-
-      establish_connection
-    rescue
-      _raise_not_connected!
+      @tube_weights = {}
+      @reserve_mode = nil
+
+      _connect(tries: config.connect_retries.to_i + 1,
+               retry_interval: config.connect_retry_interval)
+    rescue Tuber::NotConnected
+      raise # already carries its cause; do not wrap it twice
+    rescue => ex
+      _raise_not_connected!(ex)
     end
 
     # Send commands to beanstalkd server via connection.
@@ -163,6 +200,81 @@ class Tuber
       end
     end
 
+    # Sends a command answered with `OK <bytes>` and returns the body
+    # unparsed. For replies whose values #parse_response would mangle:
+    # its Psych workaround rewrites `:`, `-` and `~` inside every value, and
+    # stats-schedule's times, specs and tags are full of them.
+    #
+    # @param [String] command A command whose success reply is `OK <bytes>`
+    # @return [String] The reply body (the YAML document), without its CRLF
+    # @raise [Tuber::UnexpectedResponse] Any other reply, e.g. NotFoundError
+    #
+    def transmit_raw(command)
+      _with_retry do
+        @mutex.synchronize do
+          _raise_not_connected! unless connection
+
+          connection.write(command + "\r\n")
+          status, bytes = connection.readline.chomp.split(/\s/, 2)
+          raise UnexpectedResponse.from_status(status, command) unless status == 'OK'
+
+          body = connection.read(bytes.to_i)
+          crlf = connection.read(2)
+          raise ExpectedCrlfError.new('EXPECTED_CRLF', command) unless crlf == "\r\n"
+          body.force_encoding(Encoding::UTF_8)
+        end
+      end
+    end
+
+    # Replaces +owner+'s recurring schedule with +entries+ in one exchange:
+    # schedule-begin, a schedule-put per entry, schedule-commit. The mutex is
+    # held throughout, so no other command interleaves with it on the socket.
+    #
+    # A dropped socket makes the server discard what was staged, so the whole
+    # exchange is re-run on a fresh connection — never resumed partway. That
+    # is safe because a sync is idempotent; if the drop came after the commit
+    # landed, the re-run reports every entry as unchanged.
+    #
+    # Run it on a connection of its own, and close that afterwards, as
+    # Tuber::Schedules#sync does: any other error partway can leave the server
+    # mid-sync on this socket with a reply unread.
+    #
+    # @param [String] owner The owner whose entries are replaced
+    # @param [Array<Tuber::Schedules::Entry>] entries The complete new set
+    # @return [Tuber::Schedules::SyncResult]
+    # @raise [Tuber::ScheduleSyncError] The server refused the sync
+    # @api private Use Tuber::Schedules#sync, which validates the entries
+    #
+    def schedule_sync(owner, entries)
+      _with_retry do
+        @mutex.synchronize do
+          _raise_not_connected! unless connection
+
+          cmd = "schedule-begin #{owner}"
+          reply = _round_trip(cmd)
+          raise ScheduleSyncError.new(reply[/\A\S*/], cmd, owner: owner) unless reply == "SYNCING #{owner}"
+
+          entries.each do |entry|
+            cmd = "schedule-put #{entry.line}"
+            reply = _round_trip(cmd, entry.body)
+            next if reply == 'STAGED'
+
+            # The refusal has already doomed the sync; the commit would only
+            # say ABORTED. Abort now so the error names the entry, and so the
+            # connection leaves sync mode before the caller sees it.
+            _round_trip('schedule-abort')
+            raise ScheduleSyncError.new(reply, cmd, owner: owner, entry: entry.name)
+          end
+
+          status, *counts = _round_trip('schedule-commit').split(' ')
+          unless status == 'SYNCED' && counts.size == 4
+            raise ScheduleSyncError.new(status.to_s, 'schedule-commit', owner: owner)
+          end
+          Schedules::SyncResult.new(*counts.map(&:to_i))
+        end
+      end
+    end
+
     # Close connection with beanstalkd server.
     #
     # @example
@@ -170,11 +282,50 @@ class Tuber
     #
     def close
       if @connection
-        @connection.close
+        begin
+          @connection.close
+        rescue StandardError
+          # A socket whose peer has already vanished can fail to close
+          # cleanly. It is gone either way, and #reconnect! must not raise
+          # on the way to replacing it.
+        end
         @connection = nil
       end
     end
 
+    # Re-establishes this connection and replays its tube state onto the new
+    # socket: watched tubes with the weights they were watched with, the used
+    # tube, and the reserve mode. Safe to call whether the current socket is
+    # healthy, dropped, or already closed.
+    #
+    # This is the same healing the connection performs internally when a
+    # command notices the socket has died, exposed for consumers that hold a
+    # connection across an outage. Prefer it to building a new Tuber: a fresh
+    # Connection makes a single connect attempt by default (see
+    # Tuber::Configuration#connect_retries) and starts with no tube state, so
+    # the caller has to re-watch and re-weight everything by hand.
+    #
+    # @param [Integer, nil] tries Maximum number of connect attempts, nil for
+    #   the configured default (see Tuber::Configuration#connect_retries)
+    # @param [Numeric, nil] retry_interval Seconds to wait between attempts,
+    #   nil for the configured default
+    # @return [Tuber::Connection] self
+    # @raise [Tuber::NotConnected] Every connect attempt failed
+    # @example
+    #   begin
+    #     job = @conn.transmit("reserve")
+    #   rescue Tuber::NotConnected
+    #     @conn.reconnect!   # watches, weights and reserve mode come back with it
+    #     retry
+    #   end
+    #
+    def reconnect!(tries: nil, retry_interval: nil)
+      _reconnect(tries: tries || _connect_tries,
+                 retry_interval: retry_interval || config.connect_retry_interval)
+      _initialize_tubes
+      self
+    end
+
     # Returns string representation of job.
     #
     # @example
@@ -185,15 +336,34 @@ class Tuber
     end
     alias :inspect :to_s
 
-    def add_to_watched(tube_name)
+    # Records a tube as watched, along with the weight it was watched with.
+    #
+    # @param [String] tube_name Name of the tube now being watched
+    # @param [Integer, nil] weight Weight passed to `watch`, nil for a plain watch
+    def add_to_watched(tube_name, weight = nil)
       @tubes_watched << tube_name
-      @tubes_watched.uniq
+      @tubes_watched.uniq!
+      if weight
+        @tube_weights[tube_name] = weight
+      else
+        @tube_weights.delete(tube_name)
+      end
+      @tubes_watched
     end
 
     def remove_from_watched(tube_name)
+      @tube_weights.delete(tube_name)
       @tubes_watched.delete(tube_name)
     end
 
+    # Replaces the watched tube list, dropping weights for tubes that are no
+    # longer watched.
+    def tubes_watched=(tube_names)
+      @tubes_watched = tube_names
+      @tube_weights.keep_if { |name, _| @tubes_watched.include?(name) }
+      @tubes_watched
+    end
+
     protected
 
     # Establish a connection based on beanstalk address.
@@ -278,16 +448,35 @@ class Tuber
 
     private
 
+    # Replays this connection's tube state onto a freshly established socket.
+    # Weights and reserve mode are per-connection server state that a new socket
+    # resets, so a reconnect that only re-watched the tube names would silently
+    # drop a weighted consumer back to FIFO. Order matters: watch, then drop
+    # default, then set the mode.
     def _initialize_tubes
-      if @tubes_watched != ['default']
+      if @tubes_watched != ['default'] || @tube_weights.any?
         tubes_watched.each do |t|
-          transmit("watch #{t}", init: false)
+          weight = @tube_weights[t]
+          transmit(weight ? "watch #{t} #{weight}" : "watch #{t}", init: false)
         end
 
-        transmit("ignore default", init: false)
+        transmit("ignore default", init: false) unless @tubes_watched.include?('default')
       end
 
       transmit("use #{tube_used}", init: false) if @tube_used != 'default'
+
+      transmit("reserve-mode #{@reserve_mode}", init: false) if @reserve_mode && @reserve_mode.to_s != 'fifo'
+    end
+
+    # Writes one command, and a body framed as for put when given, and reads
+    # the one-line reply. Callers hold the mutex.
+    #
+    # @return [String] The reply line without its CRLF
+    def _round_trip(command, body = nil)
+      frame = "#{command}\r\n".b
+      frame << body.b << "\r\n" if body
+      connection.write(frame)
+      connection.readline.chomp
     end
 
     # Wrapper method for capturing certain failures and retry the payload block
@@ -304,7 +493,7 @@ class Tuber
       yield
     rescue EOFError, Errno::ECONNRESET, Errno::EPIPE,
       Errno::ECONNREFUSED => ex
-      _reconnect(ex, retry_interval)
+      _reconnect(tries: _connect_tries, retry_interval: retry_interval)
       _initialize_tubes if init
       raise ex unless retransmit
       retry
@@ -318,19 +507,37 @@ class Tuber
       retry
     end
 
-    # Tries to re-establish connection to the beanstalkd
+    # Connect attempts to allow when healing a connection that was already
+    # established. Never fewer than MAX_RETRIES, so the transparent retry
+    # behaves exactly as it always has by default; raising connect_retries
+    # lifts this with it, making one knob answer "how long should a client
+    # ride out a server restart" for cold starts and reconnects alike.
+    #
+    # @return [Integer] maximum number of connect attempts
+    def _connect_tries
+      [MAX_RETRIES, config.connect_retries.to_i + 1].max
+    end
+
+    # Drops the current socket and connects again.
     #
-    # @param [Exception] original_exception The exception caused the retry
-    # @param [Integer] retry_interval The time to wait before the next reconnect
     # @param [Integer] tries The maximum number of attempts to reconnect
-    def _reconnect(original_exception, retry_interval, tries=MAX_RETRIES)
+    # @param [Numeric] retry_interval The time to wait before the next attempt
+    # @raise [Tuber::NotConnected] Every attempt failed
+    def _reconnect(tries: MAX_RETRIES, retry_interval: DEFAULT_RETRY_INTERVAL)
       close
+      _connect(tries: tries, retry_interval: retry_interval)
+    end
+
+    # Connects, retrying while the server is refusing or unreachable.
+    #
+    # @param [Integer] tries The maximum number of connect attempts
+    # @param [Numeric] retry_interval The time to wait between attempts
+    # @raise [Tuber::NotConnected] Every attempt failed
+    def _connect(tries: MAX_RETRIES, retry_interval: DEFAULT_RETRY_INTERVAL)
       establish_connection
-    rescue Errno::ECONNREFUSED
+    rescue *CONNECT_ERRORS => ex
       tries -= 1
-      if tries.zero?
-        _raise_not_connected!
-      end
+      _raise_not_connected!(ex) if tries <= 0
       sleep(retry_interval || DEFAULT_RETRY_INTERVAL)
       retry
     end
@@ -356,10 +563,23 @@ class Tuber
       [sec, usec].pack('l_l_')
     end
 
-    # Raises an error to be triggered when the connection has failed
+    # Raises an error to be triggered when the connection has failed.
+    #
+    # The underlying error is named in the message as well as kept as the
+    # exception's +cause+. A log line reading only "Connection to beanstalk
+    # '...' is closed!" hides whether the server refused, timed out, or never
+    # resolved — which is exactly what you want to know during an outage.
+    #
+    # Only the two callers that are genuinely inside a rescue pass a cause.
+    # Defaulting to +$!+ would be wrong: a command issued from inside someone
+    # else's rescue block would name whatever they were handling.
+    #
+    # @param [Exception, nil] cause The error that stopped the connect
     # @raise [Tuber::NotConnected] Beanstalkd is no longer connected
-    def _raise_not_connected!
-      raise Tuber::NotConnected, "Connection to beanstalk '#{@host}:#{@port}' is closed!"
+    def _raise_not_connected!(cause = nil)
+      message = "Connection to beanstalk '#{@host}:#{@port}' is closed!"
+      message += " (#{cause.class}: #{cause.message})" if cause && !cause.is_a?(Tuber::NotConnected)
+      raise Tuber::NotConnected, message
     end
 
   end # Connection