tuber 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28e2397d8368c54a6711fa1db82b5c54ea649a4113e4da808b9dbc6db9cec1cb
-  data.tar.gz: dee769c5e37ff64726e1563150af3a25e2dc3f65405844f58b76bafbf4f7148f
+  metadata.gz: 3dad07a18da118a0c3f50cdb00de169fbc73c4691e7484c422d98bccd12b750e
+  data.tar.gz: eeb2247e67cf72d407c578f9a0e2e61820ebc3b3594ce6da39f90eb312ef23d4
 SHA512:
-  metadata.gz: 48a99c28b12b3f83cd1f24f743fabda6f06a97802c3e2633bb805f7309a3574508d45b3ba7c2ce1cfd7842b1f92159115e19f7331362c79d662c687f0b60af75
-  data.tar.gz: 60fa0ea0b9d9440ba798bf953f640f9a6c654bf3988bdca58bc51e037bfa347fefc606964c81a236335467cd5441ce4344ef9382a725e2920d69d8a871ba996f
+  metadata.gz: 476561b12a94b1017ec600d249236ad1296a3760c19c8fae126bace4ae26de1b9d448c54b74413dbf7805eb3ed91d8bf4ee53c17a148fe194705c43783e44e71
+  data.tar.gz: d3e34a35f30ee2ae578bdfb1f88c243585a2bbfcb9de4e0d76241d1839e35cb51715fcd5a9921ff5e002557c1d2f53f66aad1daea18c6114ae62687d43b74e58

data/CHANGELOG.md

@@ -4,6 +4,21 @@ 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

data/README.md

@@ -371,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
@@ -413,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/connection.rb

@@ -200,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
@@ -393,6 +468,17 @@ class Tuber
       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
     #
     # @param [Proc] block The command to execute.

data/lib/tuber/errors.rb

@@ -11,7 +11,7 @@ class Tuber
   # Abstract class for errors that occur when a command does not complete successfully.
   class UnexpectedResponse < RuntimeError
     # Set of status states that are considered errors
-    ERROR_STATES = %w(OUT_OF_MEMORY INTERNAL_ERROR
+    ERROR_STATES = %w(OUT_OF_MEMORY OUT_OF_STORAGE INTERNAL_ERROR
       BAD_FORMAT UNKNOWN_COMMAND JOB_TOO_BIG DRAINING
       TIMED_OUT DEADLINE_SOON NOT_FOUND NOT_IGNORED EXPECTED_CRLF)
 
@@ -27,13 +27,14 @@ class Tuber
     #
     # @param [Tuber::UnexpectedResponse] status Unexpected response object
     # @param [String] cmd Beanstalkd request command
+    # @param [String, nil] message Overrides the default "Response failed with: <status>"
     #
     # @example
     #   Tuber::UnexpectedResponse.new(NotFoundError, 'bury 123')
     #
-    def initialize(status, cmd)
+    def initialize(status, cmd, message = nil)
       @status, @cmd = status, cmd
-      super("Response failed with: #{status}")
+      super(message || "Response failed with: #{status}")
     end
 
     # Translate beanstalkd error status to ruby Exeception
@@ -55,6 +56,8 @@ class Tuber
 
   # Raises when the beanstalkd instance runs out of memory
   class OutOfMemoryError < UnexpectedResponse; end
+  # Raises when a persistent Tuber server's disk budget (--max-storage-bytes) is spent
+  class OutOfStorageError < UnexpectedResponse; end
   # Raises when the beanstalkd instance is draining and new jobs cannot be inserted
   class DrainingError < UnexpectedResponse; end
   # Raises when the job or tube cannot be found
@@ -75,4 +78,55 @@ class Tuber
   class TimedOutError < UnexpectedResponse; end
   # Raises when a tube could not be ignored because it is the last watched tube.
   class NotIgnoredError < UnexpectedResponse; end
+
+  # Raises when a Tuber server refuses a schedule sync (see Tuber::Schedules#sync).
+  #
+  # Unless #applied? is true, nothing changed: the owner's previous schedule
+  # is still the one in effect.
+  class ScheduleSyncError < UnexpectedResponse
+    # @!attribute owner
+    #   @return [String] the owner whose sync was refused
+    # @!attribute entry
+    #   @return [String, nil] the entry tuber refused, nil when it refused the
+    #     sync as a whole (on begin or commit)
+    attr_reader :owner, :entry
+
+    # @param [String] status The server's reply, e.g. "BAD_SCHEDULE"
+    # @param [String] cmd The command it refused
+    # @param [String] owner The owner being synced
+    # @param [String, nil] entry The refused entry's name
+    def initialize(status, cmd, owner:, entry: nil)
+      @owner, @entry = owner, entry
+      super(status, cmd, describe(status, cmd, owner, entry))
+    end
+
+    # True when the new set is live despite the error: the commit took effect
+    # in memory but tuber couldn't write it to disk (INTERNAL_ERROR). A tuber
+    # restart before the next successful sync brings back the previous set.
+    #
+    # @return [Boolean]
+    def applied?
+      cmd == 'schedule-commit' && status == 'INTERNAL_ERROR'
+    end
+
+    private
+
+    def describe(status, cmd, owner, entry)
+      if entry
+        "tuber refused schedule #{entry.inspect} (#{status}): #{cmd}. " \
+          "Nothing changed: #{owner.inspect}'s previous schedule is still in effect."
+      elsif cmd == 'schedule-commit' && status == 'INTERNAL_ERROR'
+        "#{owner.inspect}'s new schedule is live, but tuber couldn't write it to disk " \
+          "(INTERNAL_ERROR). A tuber restart before the next successful sync brings back the previous one."
+      elsif cmd == 'schedule-commit'
+        "tuber refused #{owner.inspect}'s schedule on commit (#{status}). " \
+          "Nothing changed: the previous schedule is still in effect."
+      elsif status == 'UNKNOWN_COMMAND'
+        "this server has no recurring schedules (UNKNOWN_COMMAND to #{cmd.inspect}): " \
+          "it is beanstalkd, or a tuber older than the scheduler."
+      else
+        "tuber refused to begin a schedule sync for #{owner.inspect} (#{status})."
+      end
+    end
+  end
 end

data/lib/tuber/schedules.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+require 'time'
+
+class Tuber
+  # Recurring schedules held by a Tuber server (beanstalkd has none): entries
+  # the server puts into a tube at the times a spec names, so an app needs no
+  # scheduler process of its own. A fire is an ordinary put — workers reserve
+  # the job as they would any other.
+  #
+  # An app owns its entries under a name of its choosing, the *owner*, and
+  # replaces the whole set with one #sync: entries it no longer sends are
+  # removed, an edited one is updated in place, and an unchanged one keeps its
+  # next fire. Every replica may sync; an identical set changes nothing.
+  #
+  # @example
+  #   tuber.schedules.sync("splat") do |s|
+  #     s.add "data_retention", tube: "splat.maintenance",
+  #           cron: "0 2 * * *", zone: "Australia/Melbourne",
+  #           body: { class: "DataRetentionJob", args: [] }.to_json, con: "maintenance"
+  #     s.add "monitor_evaluation", tube: "splat.checkins", every: 60,
+  #           idp: "monitor_evaluation", body: { class: "MonitorEvaluationJob", args: [] }.to_json
+  #   end
+  #   # => #<struct Tuber::Schedules::SyncResult added=2, changed=0, removed=0, unchanged=0>
+  #
+  class Schedules
+    # What a committed sync did to the owner's entries.
+    #
+    # If the connection dropped and the sync was re-run, the counts describe
+    # the last attempt only: a drop after the first attempt's commit landed
+    # makes the re-run report every entry as unchanged.
+    SyncResult = Struct.new(:added, :changed, :removed, :unchanged)
+
+    # One staged entry: its name, the `schedule-put` arguments, and the
+    # serialized body.
+    Entry = Struct.new(:name, :line, :body)
+
+    # Owners, entry names and tubes follow the server's tube-name rules.
+    NAME = %r{\A[A-Za-z0-9+/;.$_()][A-Za-z0-9\-+/;.$_()]*\z}
+
+    # @!attribute client
+    #   @return [Tuber] returns the client instance
+    attr_reader :client
+
+    # @param [Tuber] client The tuber client instance.
+    def initialize(client)
+      @client = client
+    end
+
+    # Replaces +owner+'s entries with the ones the block adds, in one step.
+    #
+    # Send the complete schedule every time: an entry left out is deleted.
+    #
+    # Sync when a new release starts — a release step, or once at process
+    # boot — not on reconnect. Tuber keeps schedules across its own restarts
+    # (with -b), and during a rolling deploy an old process re-syncing would
+    # put back what the new release removed.
+    #
+    # @param [String] owner The app's name for its set of entries
+    # @param [Boolean] allow_empty A sync with no entries removes all of the
+    #   owner's entries. Refused unless this is true, since an app that loaded
+    #   an empty config by mistake would otherwise wipe its schedule.
+    # @yieldparam [Tuber::Schedules::Builder] s Call +s.add+ once per entry
+    # @return [Tuber::Schedules::SyncResult]
+    # @raise [Tuber::ScheduleSyncError] The server refused an entry or the
+    #   sync. Nothing changed unless the error's #applied? says otherwise.
+    # @raise [ArgumentError] An entry is malformed, or the set is empty
+    #   without +allow_empty+. Nothing is sent.
+    # @raise [Tuber::NotConnected] The sync's own connection couldn't be
+    #   made (see Tuber::Configuration#connect_retries)
+    # @api public
+    def sync(owner, allow_empty: false)
+      owner = Schedules.name!("owner", owner)
+      builder = Builder.new
+      yield builder if block_given?
+      if builder.entries.empty? && !allow_empty
+        raise ArgumentError, "refusing to sync no entries for #{owner.inspect}: that removes " \
+                             "all of its schedules. Pass allow_empty: true if that's meant."
+      end
+
+      # A connection of its own: a blocking reserve on the client's connection
+      # can't hold the sync up, and an error partway, which can leave the
+      # server mid-sync with a reply unread, is cleaned up by closing it.
+      connection = Connection.new(client.connection.address)
+      begin
+        connection.schedule_sync(owner, builder.entries)
+      ensure
+        connection.close
+      end
+    end
+
+    # The entries the server holds, as [owner, name] pairs.
+    #
+    # @param [String, nil] owner Only this owner's entries
+    # @return [Array<Array(String, String)>]
+    # @example
+    #   tuber.schedules.list("splat") # => [["splat", "data_retention"], ["splat", "monitor_evaluation"]]
+    # @api public
+    def list(owner = nil)
+      owner = Schedules.name!("owner", owner) if owner
+      yaml = client.connection.transmit_raw(owner ? "list-schedules #{owner}" : "list-schedules")
+      yaml.each_line.grep(/\A- /).map { |line| line.chomp[2..-1].split(' ', 2) }
+    end
+
+    # One entry's definition, next three fires, last fire and counters.
+    #
+    # Times are Time objects at the entry's own zone offset, nil when there is
+    # none yet; counters are Integers. +buried_streak+ above 0 means fires are
+    # deduplicating against a buried job (through +idp:+) and queueing nothing.
+    #
+    # @param [String] owner The entry's owner
+    # @param [String] name The entry's name
+    # @return [Tuber::StatStruct, nil] nil if there is no such entry
+    # @example
+    #   stats = tuber.schedules.stats("splat", "data_retention")
+    #   stats.next_fire       # => 2026-10-12 02:00:00 +1100
+    #   stats["next-fire-2"]  # => 2026-10-13 02:00:00 +1100
+    #   stats.buried_streak   # => 0
+    # @api public
+    def stats(owner, name)
+      owner = Schedules.name!("owner", owner)
+      name = Schedules.name!("name", name)
+      yaml = client.connection.transmit_raw("stats-schedule #{owner} #{name}")
+      stats = yaml.each_line.with_object({}) do |line, hash|
+        key, value = line.chomp.split(': ', 2)
+        hash[key] = Schedules.stat_value(value) if value
+      end
+      StatStruct.from_hash(stats)
+    rescue Tuber::NotFoundError
+      nil
+    end
+
+    # String representation of the schedules collection.
+    def to_s
+      "#<Tuber::Schedules>"
+    end
+    alias :inspect :to_s
+
+    # Checks an owner, entry name or tube against tube-name rules.
+    #
+    # @return [String] The name, a Symbol converted
+    # @raise [ArgumentError] It breaks them
+    # @api private
+    def self.name!(what, value)
+      value = value.to_s if value.is_a?(Symbol)
+      return value if value.is_a?(String) && value.bytesize <= 200 && value.match?(NAME)
+      raise ArgumentError, "invalid schedule #{what} #{value.inspect}: up to 200 bytes of letters, " \
+                           "digits and - + / ; . $ _ ( ), not starting with -"
+    end
+
+    # Converts one stats-schedule value by how tuber writes it: a quoted value
+    # is a String, `""` meaning none (nil); bare digits are a counter; any
+    # other bare value is a time.
+    #
+    # @api private
+    def self.stat_value(value)
+      if value.start_with?('"')
+        string = value.delete_prefix('"').delete_suffix('"')
+        string.empty? ? nil : string
+      elsif value.match?(/\A\d+\z/)
+        value.to_i
+      else
+        begin
+          Time.iso8601(value)
+        rescue ArgumentError
+          value # a field newer than this gem; better raw than an error
+        end
+      end
+    end
+
+    # Collects the entries of one sync. Nothing is sent until the block ends,
+    # and nothing at all if an #add raises.
+    class Builder
+      # @!attribute entries
+      #   @return [Array<Tuber::Schedules::Entry>] the entries added so far
+      attr_reader :entries
+
+      def initialize
+        @entries = []
+      end
+
+      # Adds one entry. Give exactly one of +cron:+, +every:+ or +spec:+.
+      #
+      # @param [String] name The entry's name, unique within the owner. Keep
+      #   it stable: a renamed entry is a removal plus an addition.
+      # @param [String] tube The tube each fire puts into
+      # @param [String] body The job body each fire puts, passed through
+      #   Tuber.configuration.job_serializer as for Tube#put
+      # @param [String] cron 5-field cron (`"0 2 * * *"`) or a macro
+      #   (`"@daily"`), optionally followed by an IANA zone
+      # @param [String] zone IANA zone for +cron+ (default UTC)
+      # @param [Integer, String] every Interval, aligned to the Unix epoch:
+      #   seconds, or `"10m"`, `"1h"`, `"1d"`
+      # @param [Integer, String] offset Shift for +every+, e.g. `"5m"`
+      # @param [String] spec The spec as tuber reads it, instead of the above
+      # @param [Integer] pri Priority; defaults as for a put
+      # @param [Integer] delay Delay of each fire's job; defaults as for a put
+      # @param [Integer] ttr TTR of each fire's job; defaults as for a put
+      # @param [String, Array] idp Idempotency key, or [key, ttl], as for a
+      #   put. A fire is skipped while the previous fire's job is still in
+      #   the tube — buried included, so a buried job stops the entry until
+      #   it is kicked or deleted.
+      # @param [String, Array] con Concurrency key, or [key, limit], as for a put
+      # @param [String] grp Group key, as for a put
+      # @param [String] aft After-group key, as for a put
+      # @param [Symbol, Integer, false] catchup What a tick missed while
+      #   tuber was down does: `:once` (the default) fires once for the gap;
+      #   an Integer fires that once only if it is at most that many seconds
+      #   stale; `:never`, `false` or 0 never fires it.
+      # @return [self]
+      # @raise [ArgumentError] Something tuber would refuse, or that would
+      #   break the line
+      def add(name, tube:, body:, cron: nil, zone: nil, every: nil, offset: nil, spec: nil,
+              pri: nil, delay: nil, ttr: nil, idp: nil, con: nil, grp: nil, aft: nil, catchup: :once)
+        name = Schedules.name!("name", name)
+        tube = Schedules.name!("tube", tube)
+        raise ArgumentError, "schedule #{name.inspect} added twice" if @entries.any? { |e| e.name == name }
+
+        config = Tuber.configuration
+        serialized = config.job_serializer.call(body)
+        unless serialized.is_a?(String)
+          raise ArgumentError, "the body of schedule #{name.inspect} is a #{serialized.class}, not a String: " \
+                               "serialize it, or set Tuber.configuration.job_serializer"
+        end
+        serialized = serialized.b
+
+        words = [name, tube,
+                 Integer(pri || config.default_put_pri),
+                 Integer(delay || config.default_put_delay),
+                 Integer(ttr || config.default_put_ttr),
+                 serialized.bytesize]
+        words.concat(tags(name, idp: idp, con: con, grp: grp, aft: aft, catchup: catchup))
+        words << spec_text(name, cron: cron, zone: zone, every: every, offset: offset, spec: spec)
+        @entries << Entry.new(name, words.join(' '), serialized)
+        self
+      end
+
+      private
+
+      def spec_text(name, cron:, zone:, every:, offset:, spec:)
+        given = { spec: spec, cron: cron, every: every }.compact
+        unless given.size == 1
+          raise ArgumentError, "schedule #{name.inspect} needs exactly one of cron:, every: or spec: " \
+                               "(got #{given.empty? ? 'none' : given.keys.join(', ')})"
+        end
+        raise ArgumentError, "schedule #{name.inspect}: zone: goes with cron:" if zone && !cron
+        raise ArgumentError, "schedule #{name.inspect}: offset: goes with every:" if offset && !every
+
+        text = if every
+          ["every #{duration(every)}", (offset && "offset #{duration(offset)}")].compact.join(' ')
+        elsif cron
+          [cron, zone].compact.join(' ')
+        else
+          spec
+        end
+        # Tags end at the first word without a colon, so a spec can't have one.
+        if !text.is_a?(String) || text.strip.empty? || text.match?(/[\r\n:]/)
+          raise ArgumentError, "invalid spec #{text.inspect} for schedule #{name.inspect}"
+        end
+        text.strip
+      end
+
+      def duration(value)
+        value.is_a?(Integer) ? "#{value.to_i}s" : value.to_s
+      end
+
+      def tags(name, catchup:, **options)
+        tags = Tube.tags(options)
+        case catchup
+        when :once, nil then nil
+        when :never, false then tags << "catchup:0"
+        when Integer
+          raise ArgumentError, "catchup: can't be negative (schedule #{name.inspect})" if catchup.negative?
+          tags << "catchup:#{catchup.to_i}"
+        else
+          raise ArgumentError, "invalid catchup: #{catchup.inspect} for schedule #{name.inspect} " \
+                               "(:once, :never, or a number of seconds)"
+        end
+        tags.each do |tag|
+          next if tag.match?(/\A[a-z]+:\S+\z/)
+          raise ArgumentError, "invalid tag #{tag.inspect} for schedule #{name.inspect}: " \
+                               "keys can't be empty or contain whitespace"
+        end
+        tags
+      end
+    end
+  end # Schedules
+end # Tuber

data/lib/tuber/tube/record.rb

@@ -62,21 +62,32 @@ class Tuber
 
         cmd_options = "#{options[:pri]} #{options[:delay]} #{options[:ttr]} #{serialized_body.bytesize}"
 
-        tags = []
-        if options[:idp]
-          tags << (options[:idp].is_a?(Array) ? "idp:#{options[:idp].join(':')}" : "idp:#{options[:idp]}")
-        end
-        if options[:con]
-          tags << (options[:con].is_a?(Array) ? "con:#{options[:con].join(':')}" : "con:#{options[:con]}")
-        end
-        tags << "grp:#{options[:grp]}" if options[:grp]
-        tags << "aft:#{options[:aft]}" if options[:aft]
-
+        tags = Tube.tags(options)
         cmd_options = "#{cmd_options} #{tags.join(' ')}" if tags.any?
         transmit("put #{cmd_options}\r\n#{serialized_body}")
       end
     end
 
+    # The tags a put carries for its :idp, :con, :grp and :aft options.
+    # Tuber::Schedules builds its entries' tags here too: every fire is a put
+    # carrying them.
+    #
+    # @param [Hash] options Put options, as for #put
+    # @return [Array<String>] e.g. ["idp:report:300", "con:api"]
+    # @api private
+    def self.tags(options)
+      tags = []
+      if options[:idp]
+        tags << (options[:idp].is_a?(Array) ? "idp:#{options[:idp].join(':')}" : "idp:#{options[:idp]}")
+      end
+      if options[:con]
+        tags << (options[:con].is_a?(Array) ? "con:#{options[:con].join(':')}" : "con:#{options[:con]}")
+      end
+      tags << "grp:#{options[:grp]}" if options[:grp]
+      tags << "aft:#{options[:aft]}" if options[:aft]
+      tags
+    end
+
     # Peek at next job within this tube in given `state`.
     #
     # @param [String] state The job state to peek at (`ready`, `buried`, `delayed`)

data/lib/tuber/version.rb

@@ -2,5 +2,5 @@
 
 class Tuber
   # Current version of gem.
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/tuber.rb

@@ -2,7 +2,7 @@
 
 require 'thread' unless defined?(Mutex)
 
-%w(version configuration errors connection tube job stats).each do |f|
+%w(version configuration errors connection tube job stats schedules).each do |f|
   require "tuber/#{f}"
 end
 
@@ -51,6 +51,15 @@ class Tuber
     @stats ||= Stats.new(self)
   end
 
+  # Returns Tuber::Schedules object for the server's recurring schedules
+  # (Tuber only).
+  #
+  # @return [Tuber::Schedules] schedules object
+  # @api public
+  def schedules
+    @schedules ||= Schedules.new(self)
+  end
+
   # Puts the server into drain mode, rejecting new puts.
   #
   # @return [Hash] Response from beanstalkd

data/test/connection_test.rb

@@ -624,4 +624,24 @@ describe Tuber::Connection do
       assert_raises(Tuber::DrainingError) { @bc.transmit("put 0 0 100 4\r\ntest") }
     end
   end # drain and undrain
+
+  describe 'for a put refused with OUT_OF_STORAGE' do
+    # Tuber answers OUT_OF_STORAGE once a persistent server's disk budget
+    # (--max-storage-bytes) is spent. It must raise like OUT_OF_MEMORY does,
+    # not come back as a hash a caller would read as a successful put.
+    it "should raise" do
+      @bc = Tuber::Connection.new('localhost')
+      TCPSocket.any_instance.stubs(:write)
+      TCPSocket.any_instance.expects(:readline).returns("OUT_OF_STORAGE\r\n")
+      err = begin
+        @bc.transmit("put 0 0 100 4\r\ntest")
+        nil
+      rescue Tuber::UnexpectedResponse => e
+        e
+      end
+      refute_nil err, "OUT_OF_STORAGE came back as a result instead of raising"
+      assert_equal 'OUT_OF_STORAGE', err.status
+      assert_equal 'OutOfStorageError', err.class.name.split('::').last
+    end
+  end # OUT_OF_STORAGE
 end # Tuber::Connection

data/test/errors_test.rb

@@ -32,4 +32,11 @@ describe "Tuber::Errors" do
     assert_equal 'reserve 0', @klazz.cmd
     assert_equal 'EXPECTED_CRLF', @klazz.status
   end
+
+  it 'should raise proper exception for invalid status OUT_OF_STORAGE' do
+    @klazz = Tuber::UnexpectedResponse.from_status("OUT_OF_STORAGE", "put 0 0 120 4")
+    assert_kind_of(Tuber::UnexpectedResponse, @klazz)
+    assert_equal 'OutOfStorageError', @klazz.class.name.split('::').last
+    assert_equal 'OUT_OF_STORAGE', @klazz.status
+  end
 end

data/test/schedules_test.rb

@@ -0,0 +1,382 @@
+# frozen_string_literal: true
+
+# test/schedules_test.rb
+
+require File.expand_path('../test_helper', __FILE__)
+
+describe Tuber::Schedules do
+  before do
+    @beanstalk = Tuber.new(tuber_address)
+    @schedules = @beanstalk.schedules
+    # Owners are namespaces, so a unique one keeps tests apart.
+    @owner = "gemtest.#{Process.pid}.#{rand(1 << 30)}"
+  end
+
+  after do
+    begin
+      @schedules.sync(@owner, allow_empty: true) if $tuber_schedules
+    rescue Tuber::UnexpectedResponse, Tuber::NotConnected
+      # the test already failed; don't bury its error under this one
+    end
+  end
+
+  def add_two(sync)
+    sync.add "rollup", tube: "gemtest.sched", cron: "5 * * * *", body: "rollup"
+    sync.add "checkin", tube: "gemtest.sched", every: 60, body: "checkin"
+  end
+
+  describe "for #sync" do
+    before { require_schedules! }
+
+    it "adds, keeps, changes and removes entries" do
+      assert_equal [2, 0, 0, 0], @schedules.sync(@owner) { |s| add_two(s) }.to_a
+      assert_equal [0, 0, 0, 2], @schedules.sync(@owner) { |s| add_two(s) }.to_a
+      assert_equal [[@owner, "checkin"], [@owner, "rollup"]], @schedules.list(@owner).sort
+      assert_includes @schedules.list, [@owner, "rollup"]
+
+      result = @schedules.sync(@owner) do |s|
+        s.add "rollup", tube: "gemtest.sched", cron: "15 * * * *", body: "rollup"
+      end
+      assert_equal [0, 1, 1, 0], result.to_a
+      assert_equal [[@owner, "rollup"]], @schedules.list(@owner)
+    end
+
+    it "lands each option in the entry tuber stores" do
+      @schedules.sync(@owner) do |s|
+        s.add "nightly", tube: "gemtest.sched", cron: "0 2 * * *", zone: "Australia/Melbourne",
+              body: "nightly", idp: ["nightly", 300], con: ["maintenance", 2], catchup: 300,
+              pri: 1024, delay: 5, ttr: 60
+        s.add "hourly", tube: "gemtest.sched", every: "1h", offset: "5m", body: "hourly", catchup: false
+        s.add "daily", tube: "gemtest.sched", spec: "@daily", body: "daily"
+      end
+
+      nightly = @schedules.stats(@owner, "nightly")
+      assert_equal "0 2 * * * Australia/Melbourne", nightly.spec
+      assert_equal "gemtest.sched", nightly.tube
+      assert_equal [1024, 5, 60], [nightly.pri, nightly.delay, nightly.ttr]
+      assert_equal "idp:nightly:300 con:maintenance:2", nightly.tags
+      assert_equal "once within 300s", nightly.catchup
+
+      hourly = @schedules.stats(@owner, "hourly")
+      assert_equal "every 1h offset 5m", hourly.spec
+      assert_equal "never", hourly.catchup
+      assert_nil hourly.tags
+
+      daily = @schedules.stats(@owner, "daily")
+      assert_equal "once", daily.catchup
+      config = Tuber.configuration
+      assert_equal [config.default_put_pri, config.default_put_delay, config.default_put_ttr],
+                   [daily.pri, daily.delay, daily.ttr]
+    end
+
+    it "raises naming the refused entry, and leaves the previous set in place" do
+      nightly = lambda do |s|
+        s.add "nightly", tube: "gemtest.sched", cron: "0 2 * * *", zone: "Australia/Melbourne", body: "n"
+      end
+      @schedules.sync(@owner, &nightly)
+
+      err = assert_raises(Tuber::ScheduleSyncError) do
+        @schedules.sync(@owner) do |s|
+          s.add "nightly", tube: "gemtest.sched", cron: "0 3 * * *", zone: "Australia/Melbourne", body: "n"
+          s.add "typo", tube: "gemtest.sched", cron: "0 2 * * *", zone: "Australia/Melborne", body: "t"
+        end
+      end
+      assert_equal "BAD_SCHEDULE", err.status
+      assert_equal "typo", err.entry
+      assert_equal @owner, err.owner
+      refute err.applied?
+      assert_match %r{Australia/Melborne}, err.message
+
+      assert_equal [[@owner, "nightly"]], @schedules.list(@owner)
+      assert_equal "0 2 * * * Australia/Melbourne", @schedules.stats(@owner, "nightly").spec
+      # The connection left sync mode: the next sync goes through.
+      assert_equal [0, 0, 0, 1], @schedules.sync(@owner, &nightly).to_a
+    end
+
+    it "refuses an empty set unless allow_empty" do
+      @schedules.sync(@owner) { |s| add_two(s) }
+
+      assert_raises(ArgumentError) { @schedules.sync(@owner) { |_s| } }
+      assert_raises(ArgumentError) { @schedules.sync(@owner) }
+      assert_equal 2, @schedules.list(@owner).size
+
+      assert_equal [0, 0, 2, 0], @schedules.sync(@owner, allow_empty: true).to_a
+      assert_equal [], @schedules.list(@owner)
+    end
+
+    it "sends nothing when an entry is invalid" do
+      @schedules.sync(@owner) { |s| add_two(s) }
+
+      assert_raises(ArgumentError) do
+        @schedules.sync(@owner) do |s|
+          s.add "rollup", tube: "gemtest.sched", cron: "5 * * * *", body: "rollup"
+          s.add "broken", tube: "gemtest.sched", cron: "5 * * * *", every: 60, body: "broken"
+        end
+      end
+      assert_equal 2, @schedules.list(@owner).size
+    end
+
+    it "puts the body into the tube when an entry fires" do
+      serializer, parser = Tuber.configuration.job_serializer, Tuber.configuration.job_parser
+      Tuber.configure do |config|
+        config.job_serializer = lambda { |body| JSON.dump(body) }
+        config.job_parser = lambda { |body| JSON.parse(body) }
+      end
+      tube = "gemtest.fire.#{rand(1 << 30)}"
+      @schedules.sync(@owner) do |s|
+        s.add "tick", tube: tube, every: 1, body: { "class" => "TickJob", "args" => [1] }
+      end
+
+      job = @beanstalk.tubes.find(tube).reserve(3)
+      assert_equal({ "class" => "TickJob", "args" => [1] }, job.body)
+      job.delete
+    ensure
+      Tuber.configure do |config|
+        config.job_serializer = serializer
+        config.job_parser = parser
+      end
+    end
+
+    it "re-runs the whole sync when the connection drops partway" do
+      $sync_writes = []
+      $drop_mid_sync = true
+      TCPSocket.prepend Module.new {
+        def write(data)
+          $sync_writes << data.to_s if $sync_writes
+          super
+        end
+
+        def readline
+          if $drop_mid_sync && $sync_writes.last.to_s.start_with?("schedule-put")
+            $drop_mid_sync = false
+            close # the server sees the connection go and discards what was staged
+            raise EOFError
+          end
+          super
+        end
+      }
+
+      result = @schedules.sync(@owner) { |s| add_two(s) }
+
+      assert_equal 2, $sync_writes.count { |w| w.start_with?("schedule-begin") }
+      assert_equal [2, 0, 0, 0], result.to_a
+      assert_equal [[@owner, "checkin"], [@owner, "rollup"]], @schedules.list(@owner).sort
+    ensure
+      # Leave the prepended module inert for the rest of the suite.
+      $drop_mid_sync = false
+      $sync_writes = nil
+    end
+
+    it "isn't held up by a blocking reserve on the client's connection" do
+      tube = "gemtest.empty.#{rand(1 << 30)}"
+      reserver = Thread.new do
+        @beanstalk.tubes.find(tube).reserve(3)
+      rescue Tuber::TimedOutError
+        nil
+      end
+      sleep 0.3 # let the reserve take the connection
+
+      started = Time.now
+      @schedules.sync(@owner) { |s| add_two(s) }
+      assert_operator Time.now - started, :<, 1.5, "the sync waited for the reserve to time out"
+    ensure
+      reserver.join if reserver
+    end
+
+    it "closes the connection it syncs on, refused or not" do
+      # A leaked socket closes only when it is garbage collected, which would
+      # hide the leak; and earlier tests' unclosed clients must go first.
+      GC.start
+      GC.disable
+      sleep 0.2 # let the server notice anything just closed
+      before = @beanstalk.stats["current-connections"]
+
+      @schedules.sync(@owner) { |s| add_two(s) }
+      assert_raises(Tuber::ScheduleSyncError) do
+        @schedules.sync(@owner) do |s|
+          s.add "typo", tube: "gemtest.sched", cron: "0 2 * * *", zone: "Australia/Melborne", body: "t"
+        end
+      end
+
+      after = nil
+      10.times do # the server notices a close a moment later
+        after = @beanstalk.stats["current-connections"]
+        break if after <= before
+        sleep 0.1
+      end
+      assert_operator after, :<=, before
+    ensure
+      GC.enable
+    end
+
+    it "leaves nothing behind when an unexpected error interrupts it" do
+      $fail_mid_sync = true
+      $sync_last_write = nil
+      TCPSocket.prepend Module.new {
+        def write(data)
+          $sync_last_write = data.to_s if $fail_mid_sync
+          super
+        end
+
+        def readline
+          if $fail_mid_sync && $sync_last_write.to_s.start_with?("schedule-put")
+            $fail_mid_sync = false
+            raise IOError, "simulated read failure" # e.g. a read timeout: not a dropped socket
+          end
+          super
+        end
+      }
+
+      assert_raises(IOError) { @schedules.sync(@owner) { |s| add_two(s) } }
+
+      # The client's connection still answers its own commands in step...
+      assert_equal "default", @beanstalk.connection.transmit("list-tube-used")[:id]
+      # ...nothing of the interrupted sync was committed, and the next sync starts clean.
+      assert_equal [], @schedules.list(@owner)
+      assert_equal [2, 0, 0, 0], @schedules.sync(@owner) { |s| add_two(s) }.to_a
+    ensure
+      $fail_mid_sync = false
+    end
+  end # sync
+
+  describe "for #stats" do
+    before { require_schedules! }
+
+    it "returns times as Time in the entry's zone, and counters as Integers" do
+      @schedules.sync(@owner) do |s|
+        s.add "nightly", tube: "gemtest.sched", cron: "0 2 * * *", zone: "Australia/Melbourne", body: "n"
+      end
+
+      stats = @schedules.stats(@owner, "nightly")
+      assert_equal @owner, stats.owner
+      assert_kind_of Time, stats.synced_at
+      assert_kind_of Time, stats.next_fire
+      assert_includes [10 * 3600, 11 * 3600], stats.next_fire.utc_offset
+      assert_includes [2, 3], stats.next_fire.hour # 3 on a spring-forward day
+      assert stats.next_fire < stats.next_fire_2
+      assert stats.next_fire_2 < stats.next_fire_3
+      assert_equal stats.next_fire_2, stats["next-fire-2"]
+      assert_nil stats.last_fire
+      assert_nil stats.last_result
+      assert_equal 0, stats.total_fires
+      assert_equal 0, stats.total_deduped_buried
+      assert_equal 0, stats.buried_streak
+    end
+
+    it "returns nil for an entry it doesn't hold" do
+      assert_nil @schedules.stats(@owner, "nope")
+    end
+
+    it "keeps a name and tube made of digits as Strings" do
+      @schedules.sync(@owner) { |s| s.add "2026", tube: "123", every: 60, body: "b" }
+      stats = @schedules.stats(@owner, "2026")
+      assert_equal "2026", stats.name
+      assert_equal "123", stats.tube
+    end
+  end # stats
+end # Tuber::Schedules
+
+# Replies a healthy server won't produce on demand. No @beanstalk here, so the
+# suite's teardown doesn't talk through the stubbed socket.
+describe "Tuber::Schedules sync refusals" do
+  before do
+    @client = Tuber.new(tuber_address)
+    @owner = "gemtest.stubbed"
+    TCPSocket.any_instance.stubs(:write)
+  end
+
+  after do
+    @client.close
+  end
+
+  def sync_one
+    @client.schedules.sync(@owner) { |s| s.add "a", tube: "gemtest.sched", every: 60, body: "a" }
+  end
+
+  it "says the set is live when the commit couldn't be written" do
+    TCPSocket.any_instance.stubs(:readline).returns("SYNCING #{@owner}\r\n", "STAGED\r\n", "INTERNAL_ERROR\r\n")
+    err = assert_raises(Tuber::ScheduleSyncError) { sync_one }
+    assert_equal "INTERNAL_ERROR", err.status
+    assert_nil err.entry
+    assert err.applied?
+    assert_match(/is live/, err.message)
+  end
+
+  it "says nothing changed when the commit is refused" do
+    TCPSocket.any_instance.stubs(:readline).returns("SYNCING #{@owner}\r\n", "STAGED\r\n", "OUT_OF_STORAGE\r\n")
+    err = assert_raises(Tuber::ScheduleSyncError) { sync_one }
+    assert_equal "OUT_OF_STORAGE", err.status
+    refute err.applied?
+    assert_match(/Nothing changed/, err.message)
+  end
+
+  it "aborts the sync before raising for a refused entry" do
+    TCPSocket.any_instance.expects(:write).with("schedule-abort\r\n")
+    TCPSocket.any_instance.stubs(:readline).returns("SYNCING #{@owner}\r\n", "JOB_TOO_BIG\r\n", "ABORTED\r\n")
+    err = assert_raises(Tuber::ScheduleSyncError) { sync_one }
+    assert_equal "JOB_TOO_BIG", err.status
+    assert_equal "a", err.entry
+  end
+
+  it "explains a server without schedules" do
+    TCPSocket.any_instance.stubs(:readline).returns("UNKNOWN_COMMAND\r\n")
+    err = assert_raises(Tuber::ScheduleSyncError) { sync_one }
+    assert_equal "UNKNOWN_COMMAND", err.status
+    assert_match(/no recurring schedules/, err.message)
+  end
+end
+
+describe Tuber::Schedules::Builder do
+  before do
+    @builder = Tuber::Schedules::Builder.new
+  end
+
+  it "writes the schedule-put arguments: tags before the spec" do
+    @builder.add "nightly", tube: "splat.maintenance", cron: "0 2 * * *", zone: "Australia/Melbourne",
+                 body: "{}", idp: ["nightly", 300], con: "maintenance", catchup: 300, pri: 1024
+    entry = @builder.entries.first
+    assert_equal "nightly", entry.name
+    assert_equal "nightly splat.maintenance 1024 0 120 2 idp:nightly:300 con:maintenance catchup:300 " \
+                 "0 2 * * * Australia/Melbourne", entry.line
+    assert_equal Encoding::BINARY, entry.body.encoding
+  end
+
+  it "counts the body in bytes" do
+    @builder.add "utf8", tube: "t", every: 60, body: "café"
+    assert_equal "utf8 t 65536 0 120 5 every 60s", @builder.entries.first.line
+  end
+
+  it "writes every: and offset:, and catchup: :never" do
+    @builder.add :hourly, tube: "t", every: 3600, offset: 300, body: "b", catchup: :never
+    assert_equal "hourly t 65536 0 120 1 catchup:0 every 3600s offset 300s", @builder.entries.first.line
+  end
+
+  it "refuses an entry tuber would refuse, or that would break the line" do
+    bad = [
+      { tube: "t", body: "b" },                                     # no spec
+      { tube: "t", body: "b", cron: "5 * * * *", every: 60 },       # two specs
+      { tube: "t", body: "b", every: 60, zone: "UTC" },             # zone without cron
+      { tube: "t", body: "b", cron: "5 * * * *", offset: "5m" },    # offset without every
+      { tube: "t", body: "b", spec: "5 * * * * UTC+10:00" },        # a colon reads as a tag
+      { tube: "t", body: "b", spec: "5 * * * *\r\nflush-tube t" },  # a second command
+      { tube: "-t", body: "b", every: 60 },                         # bad tube name
+      { tube: "t", body: { "a" => 1 }, every: 60 },                 # body isn't a String
+      { tube: "t", body: "b", every: 60, idp: "two words" },        # tag with a space
+      { tube: "t", body: "b", every: 60, con: "" },                 # empty tag key
+      { tube: "t", body: "b", every: 60, catchup: -1 },
+      { tube: "t", body: "b", every: 60, catchup: "soon" },
+    ]
+    bad.each do |options|
+      assert_raises(ArgumentError, options.inspect) { Tuber::Schedules::Builder.new.add("name", **options) }
+    end
+
+    ["", "-name", "has space", "x" * 201, nil].each do |name|
+      assert_raises(ArgumentError, name.inspect) { @builder.add(name, tube: "t", every: 60, body: "b") }
+    end
+  end
+
+  it "refuses a name added twice" do
+    @builder.add "once", tube: "t", every: 60, body: "b"
+    assert_raises(ArgumentError) { @builder.add "once", tube: "t", every: 120, body: "b" }
+  end
+end

data/test/test_helper.rb

@@ -43,6 +43,24 @@ class MiniTest::Unit::TestCase
     skip "requires a Tuber server, not stock beanstalkd" unless tuber_server?
   end
 
+  # Skips the current test unless the server runs recurring schedules. A
+  # Tuber older than the scheduler answers UNKNOWN_COMMAND to list-schedules.
+  def require_schedules!
+    require_tuber!
+    if $tuber_schedules.nil?
+      client = Tuber.new(tuber_address)
+      begin
+        client.connection.transmit_raw('list-schedules')
+        $tuber_schedules = true
+      rescue Tuber::UnknownCommandError
+        $tuber_schedules = false
+      ensure
+        client.close
+      end
+    end
+    skip "requires a Tuber server with recurring schedules" unless $tuber_schedules
+  end
+
   # Cleans up all jobs from specific tubes
   #
   # @example

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tuber
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Dan Milne
@@ -105,6 +105,7 @@ files:
 - lib/tuber/job.rb
 - lib/tuber/job/collection.rb
 - lib/tuber/job/record.rb
+- lib/tuber/schedules.rb
 - lib/tuber/stats.rb
 - lib/tuber/stats/fast_struct.rb
 - lib/tuber/stats/stat_struct.rb
@@ -117,6 +118,7 @@ files:
 - test/job_test.rb
 - test/jobs_test.rb
 - test/prompt_regexp_test.rb
+- test/schedules_test.rb
 - test/stat_struct_test.rb
 - test/stats_test.rb
 - test/test_helper.rb
@@ -145,7 +147,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Ruby client for the Tuber job queue server.
 test_files: []