postburner 1.0.0.pre.5 → 1.0.0.pre.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38e2982c4478f99aa0d19c58ac7455cdf82ff1c3707a154d1dbd0c3a1546ceb8
-  data.tar.gz: 0d17bb9da882d8e1cf2cce7c1cddd508ddbc7531c037dd56b7e0c6d34bd40f5b
+  metadata.gz: a480ddab26850f1ecacc0f3c1ec75de82d8ac1f0acd2b4b7f0997dc5b3cc044c
+  data.tar.gz: 6d7ed3b8dd92df4d1064750c7eead44b8fa8d3c60887cb5c98771844a14f014d
 SHA512:
-  metadata.gz: 28421eb19f5e288e43e9d455364906dabe0ee3ab024a230efb9aca19842ac3677c4b602788d8f0f7c67253f64e1b382d12a4f23756ff01ef2e43a5b51d478d55
-  data.tar.gz: f13d5452e5394c3e6d8b9468d8863344f35049972fbe5eac6c20cbede12ddc7e9eb2a17538bccb626a7a00a744c567d33e59558f5e7309ab3ecf775bea3db5b9
+  metadata.gz: 92f61d683537fa34a3aec8c7a052eb2313476fa2b647760d909022b28d0171db89b90c572b73af7eef6438bb1fc462f457d4b44bad1d249064993f68269de7e1
+  data.tar.gz: 495c9b4fba775507dd54666ab964bfa4d41fcc6608c3499ab5f4cc24b4f0af9a2cb4265b18331b566d61fce1318b1b1bc6a7ed9bc05d73619c5d5dd5dbc1711b

data/README.md

@@ -1352,6 +1352,91 @@ end
 ```
 
 
+### Tube Statistics and Management
+
+Postburner provides methods to inspect and manage Beanstalkd tubes:
+
+**View tube statistics:**
+
+```ruby
+# View all tubes on the Beanstalkd server
+stats = Postburner.stats
+# => {
+#   tubes: [
+#     { name: "postburner.production.default", ready: 10, delayed: 5, buried: 0, reserved: 2, total: 17 },
+#     { name: "postburner.production.critical", ready: 0, delayed: 0, buried: 0, reserved: 1, total: 1 }
+#   ],
+#   totals: { ready: 10, delayed: 5, buried: 0, reserved: 3, total: 18 }
+# }
+
+# View specific tubes only
+stats = Postburner.stats(['postburner.production.critical'])
+# => { tubes: [...], totals: {...} }
+```
+
+**Clear jobs from tubes:**
+
+For safety, `clear_jobs!` requires you to explicitly specify which tubes to clear. This prevents accidentally clearing tubes from other applications sharing the same Beanstalkd server.
+
+```ruby
+# Collect stats only (no clearing)
+result = Postburner.clear_jobs!
+# => { tubes: [...], totals: {...}, cleared: false }
+
+# Clear specific tubes (must be in config/postburner.yml)
+result = Postburner.clear_jobs!(['postburner.production.default'])
+# => { tubes: [...], totals: {...}, cleared: true }
+
+# Pretty-print JSON output
+Postburner.clear_jobs!(['postburner.production.default'], silent: false)
+# Outputs formatted JSON to stdout
+
+# Silent mode (no output, just return data)
+result = Postburner.clear_jobs!(['postburner.production.default'], silent: true)
+```
+
+**Safety validation:**
+
+Only tubes defined in your loaded configuration can be cleared. This prevents mistakes in multi-tenant Beanstalkd environments:
+
+```ruby
+# Error: trying to clear tube not in config
+Postburner.clear_jobs!(['postburner.production.other-app'])
+# => ArgumentError: Cannot clear tubes not in configuration.
+#    Invalid tubes: postburner.production.other-app
+#    Configured tubes: postburner.production.default, postburner.production.critical
+```
+
+**Shortcut using watched_tube_names:**
+
+Clear all configured tubes at once:
+
+```ruby
+# Get all tubes from current configuration
+watched_tubes = Postburner.watched_tube_names
+# => ["postburner.production.default", "postburner.production.critical", "postburner.production.mailers"]
+
+# Clear all configured tubes
+Postburner.clear_jobs!(watched_tubes, silent: true)
+# or
+Postburner.clear_jobs!(Postburner.watched_tube_names, silent: true)
+```
+
+**Low-level Connection API:**
+
+For programmatic use without output formatting, use `Connection#clear_tubes!`:
+
+```ruby
+Postburner.connected do |conn|
+  # Returns data only (no puts)
+  result = conn.clear_tubes!(Postburner.watched_tube_names)
+  # => { tubes: [...], totals: {...}, cleared: true }
+
+  # Same validation - must be in configuration
+  result = conn.clear_tubes!(['postburner.production.default'])
+end
+```
+
 ## Web UI
 
 Mount the inspection interface:

data/app/concerns/postburner/insertion.rb

@@ -159,9 +159,8 @@ module Postburner
       #debugger
 
       # Response must be a hash with an :id key (value can be nil)
-      # Backburner returns symbol keys
       unless response.is_a?(Hash) && response.key?(:id)
-        raise MalformedResponse, "Missing :id key in response: #{response.inspect}"
+        raise Postburner::Job::MalformedResponse, "Missing :id key in response: #{response.inspect}"
       end
 
       persist_metadata!(bkid: response[:id])

data/lib/postburner/configuration.rb

@@ -99,11 +99,18 @@ module Postburner
         if workers.size == 1
           worker_name = workers.keys.first
         else
-          raise ArgumentError, "Configuration has multiple workers, but --worker not specified\nAvailable workers: #{workers.keys.join(', ')}\nUsage: bin/postburner --worker <name>"
+          raise ArgumentError, <<~ERROR
+            Configuration has multiple workers, but --worker not specified
+            Available workers: #{workers.keys.join(', ')}
+            Usage: bin/postburner --worker <name>
+          ERROR
         end
       else
         unless workers.key?(worker_name)
-          raise ArgumentError, "Worker '#{worker_name}' not found in #{path}\nAvailable workers: #{workers.keys.join(', ')}"
+          raise ArgumentError, <<~ERROR
+            Worker '#{worker_name}' not found in #{path}
+            Available workers: #{workers.keys.join(', ')}
+          ERROR
         end
       end
 

data/lib/postburner/connection.rb

@@ -88,6 +88,68 @@ module Postburner
       @pool = nil
     end
 
+    # Clears jobs from specified tubes or collects stats for all tubes.
+    #
+    # Low-level method that returns data only (no output to stdout).
+    # Delegates to Postburner.stats for collecting statistics.
+    # For user-facing output, use Postburner.clear_jobs! instead.
+    #
+    # SAFETY: Only allows clearing tubes that are defined in the loaded
+    # configuration (watched_tube_names). This prevents accidentally clearing
+    # tubes from other applications or environments.
+    #
+    # @param tube_names [Array<String>, nil] Array of tube names to clear, or nil to only collect stats
+    #
+    # @return [Hash] Statistics and results with keys:
+    #   - tubes: Array of hashes with per-tube stats
+    #   - totals: Hash with aggregated counts across all tubes
+    #   - cleared: Boolean indicating if tubes were actually cleared
+    #
+    # @raise [ArgumentError] if tube_names contains tubes not in watched_tube_names
+    #
+    # @example Collect stats only (no clearing)
+    #   result = conn.clear_tubes!
+    #   result[:totals][:total]  # => 42
+    #
+    # @example Clear configured tubes only
+    #   result = conn.clear_tubes!(Postburner.watched_tube_names)
+    #   result[:cleared]  # => true
+    #
+    # @example Invalid tube raises error
+    #   conn.clear_tubes!(['random-tube'])
+    #   # => ArgumentError: Cannot clear tubes not in configuration
+    #
+    def clear_tubes!(tube_names = nil)
+      ensure_connected!
+
+      # Validate that tubes to clear are in the loaded configuration
+      if tube_names&.any?
+        watched = Postburner.watched_tube_names
+        invalid_tubes = tube_names - watched
+
+        if invalid_tubes.any?
+          raise ArgumentError, <<~ERROR
+            Cannot clear tubes not in configuration.
+            Invalid tubes: #{invalid_tubes.join(', ')}
+            Configured tubes: #{watched.join(', ')}
+          ERROR
+        end
+      end
+
+      # Get stats using Postburner.stats
+      result = Postburner.stats(tube_names)
+      result[:cleared] = tube_names&.any? ? true : false
+
+      # Actually clear if tube names were provided and validated
+      if tube_names&.any?
+        tube_names.each do |tube_name|
+          tubes[tube_name].clear
+        end
+      end
+
+      result
+    end
+
     private
 
     # Establishes connection to Beanstalkd.

data/lib/postburner/time_helpers.rb

@@ -64,8 +64,10 @@ module Postburner
     #
     def travel_to(time, &block)
       unless defined?(ActiveSupport::Testing::TimeHelpers)
-        raise "ActiveSupport::Testing::TimeHelpers not available. " \
-              "Postburner::TimeHelpers requires Rails testing helpers for time travel."
+        raise <<~ERROR
+          ActiveSupport::Testing::TimeHelpers not available.
+          Postburner::TimeHelpers requires Rails testing helpers for time travel.
+        ERROR
       end
 
       helper = Object.new.extend(ActiveSupport::Testing::TimeHelpers)

data/lib/postburner/version.rb

@@ -1,3 +1,3 @@
 module Postburner
-  VERSION = '1.0.0.pre.5'
+  VERSION = '1.0.0.pre.6'
 end

data/lib/postburner.rb

@@ -375,25 +375,50 @@ module Postburner
     end
   end
 
-  # Removes all jobs from all tubes (not yet implemented).
+  # Clears jobs from specified tubes or shows stats for all tubes.
   #
-  # This is a destructive operation intended for development/testing cleanup.
-  # Requires confirmation string "CONFIRM" to prevent accidental execution.
+  # High-level method with formatted output. Delegates to Connection#clear_tubes!
+  # for the actual work, then pretty-prints the results.
   #
-  # @param confirm [String] Must be exactly "CONFIRM" to execute
+  # SAFETY: Only allows clearing tubes that are defined in the loaded
+  # configuration. This prevents accidentally clearing tubes from other
+  # applications or environments sharing the same Beanstalkd server.
   #
-  # @return [void]
+  # @param tube_names [Array<String>, nil] Array of tube names to clear, or nil to only show stats
+  # @param silent [Boolean] If true, suppress output to stdout (default: false)
   #
-  # @example
-  #   Postburner.remove_all!("CONFIRM")
+  # @return [Hash] Statistics and results (see Connection#clear_tubes!)
+  #
+  # @raise [ArgumentError] if tube_names contains tubes not in watched_tube_names
+  #
+  # @example Show stats only (no clearing) - SAFE
+  #   Postburner.clear_jobs!
+  #   # Shows stats for ALL tubes on Beanstalkd, but doesn't clear anything
+  #
+  # @example Clear watched tubes only - SAFE
+  #   Postburner.clear_jobs!(Postburner.watched_tube_names)
+  #   # Only clears tubes defined in your config
   #
-  # @note Currently a no-op - implementation pending
-  # @todo Implement job removal from all tubes
+  # @example Trying to clear unconfigured tube - RAISES ERROR
+  #   Postburner.clear_jobs!(['some-other-app-tube'])
+  #   # => ArgumentError: Cannot clear tubes not in configuration
   #
-  def self.remove_all!(confirm)
-    return unless confirm == "CONFIRM"
+  # @example Silent mode (programmatic use)
+  #   result = Postburner.clear_jobs!(Postburner.watched_tube_names, silent: true)
+  #   result[:totals][:total]  # => 42
+  #
+  # @see Connection#clear_tubes!
+  #
+  def self.clear_jobs!(tube_names = nil, silent: false)
+    require 'json'
+
+    result = connection.clear_tubes!(tube_names)
+
+    unless silent
+      puts JSON.pretty_generate(result)
+    end
 
-    # TODO
+    result
   end
 
   # Returns array of watched tube names with environment prefix.
@@ -423,38 +448,82 @@ module Postburner
     @__watched_tubes ||= watched_tube_names.map { |tube_name| connection.tubes[tube_name] }
   end
 
-  # Returns statistics and introspection data about Beanstalkd and configured queues.
+  # Returns detailed statistics about Beanstalkd tubes.
   #
-  # Provides Beaneater tube instances for configured tubes and all tubes that exist
-  # on the Beanstalkd server. Tube instances support introspection methods:
+  # Collects job counts (ready, delayed, buried, reserved) for each tube
+  # and provides aggregate totals across all tubes.
   #
-  # - tube.name - Tube name
-  # - tube.stats - Tube statistics hash (current-jobs-ready, current-jobs-buried, etc.)
-  # - tube.peek_ready - Next ready job
-  # - tube.peek_delayed - Next delayed job
-  # - tube.peek_buried - Next buried job
-  # - tube.kick(n) - Kick n buried jobs back to ready
-  # - tube.pause(delay) - Pause tube for delay seconds
-  # - tube.clear - Delete all jobs in tube
+  # @param tube_names [Array<String>, nil] Specific tube names to inspect, or nil for all tubes
   #
-  # @return [Hash] Statistics hash with the following keys:
-  #   - watched_tubes: Array of configured/watched Beaneater::Tube instances
-  #   - tubes: Array of all Beaneater::Tube instances on the server
+  # @return [Hash] Statistics hash with keys:
+  #   - tubes: Array of hashes with per-tube stats (name, ready, delayed, buried, reserved, total)
+  #   - totals: Hash with aggregated counts across all tubes
   #
   # @raise [Beaneater::NotConnected] if connection to Beanstalkd fails
   #
-  # @example
+  # @example Get stats for all tubes
   #   stats = Postburner.stats
-  #   stats[:watched_tubes].each { |tube| puts "#{tube.name}: #{tube.stats}" }
-  #   stats[:tubes].first.peek_ready
+  #   stats[:totals][:total]  # => 42
+  #   stats[:tubes].first[:name]  # => "default"
+  #
+  # @example Get stats for specific tubes
+  #   stats = Postburner.stats(Postburner.watched_tube_names)
+  #   stats[:tubes].size  # => 3
   #
-  def self.stats
+  def self.stats(tube_names = nil)
     connected do |conn|
-      {
-        watched_tubes: self.watched_tubes,
-        # Get all tube instances that exist on Beanstalkd
-        tubes: conn.beanstalk.tubes.all
+      # Get tubes to inspect
+      tubes_to_inspect = if tube_names&.any?
+        tube_names.map { |name| conn.tubes[name] }
+      else
+        conn.beanstalk.tubes.all
+      end
+
+      result = {
+        tubes: [],
+        totals: {
+          ready: 0,
+          delayed: 0,
+          buried: 0,
+          reserved: 0,
+          total: 0
+        }
       }
+
+      # Collect stats from each tube
+      tubes_to_inspect.each do |tube|
+        begin
+          stats = tube.stats
+          # Beaneater returns a StatStruct; access the underlying hash
+          stats_hash = stats.instance_variable_get(:@hash) || {}
+
+          tube_data = {
+            name: tube.name,
+            ready: stats_hash['current-jobs-ready'] || 0,
+            delayed: stats_hash['current-jobs-delayed'] || 0,
+            buried: stats_hash['current-jobs-buried'] || 0,
+            reserved: stats_hash['current-jobs-reserved'] || 0,
+            total: (stats_hash['current-jobs-ready'] || 0) +
+                   (stats_hash['current-jobs-delayed'] || 0) +
+                   (stats_hash['current-jobs-buried'] || 0) +
+                   (stats_hash['current-jobs-reserved'] || 0)
+          }
+        rescue Beaneater::NotFoundError
+          # Tube doesn't exist yet, skip it
+          next
+        end
+
+        result[:tubes] << tube_data
+
+        # Aggregate totals
+        result[:totals][:ready] += tube_data[:ready]
+        result[:totals][:delayed] += tube_data[:delayed]
+        result[:totals][:buried] += tube_data[:buried]
+        result[:totals][:reserved] += tube_data[:reserved]
+        result[:totals][:total] += tube_data[:total]
+      end
+
+      result
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: postburner
 version: !ruby/object:Gem::Version
-  version: 1.0.0.pre.5
+  version: 1.0.0.pre.6
 platform: ruby
 authors:
 - Matt Smith