falqon 0.0.1 → 1.0.0

data/lib/falqon/cli/list.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Falqon
+  class CLI
+    # Display all active (registered) queues
+    #
+    # Usage:
+    #  falqon list
+    #
+    # @example
+    #   $ falqon list
+    #   jobs
+    #   emails
+    class List < Base
+      # @!visibility private
+      def validate; end
+
+      # @!visibility private
+      def execute
+        Falqon::Queue.all.each do |queue|
+          puts queue.name
+        end
+      end
+    end
+  end
+end

data/lib/falqon/cli/refill.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Falqon
+  class CLI
+    # Refill queue (move processing messages to pending)
+    #
+    # This command moves all messages from the processing queue back to the pending queue (in order).
+    # It is useful when a worker crashes or is stopped, and messages are left in the processing queue.
+    #
+    # Usage:
+    #   falqon refill -q, --queue=QUEUE
+    #
+    # Options:
+    #   -q, --queue=QUEUE  # Queue name
+    #
+    # @example Refill the queue
+    #   $ falqon refill --queue jobs
+    #   Refilled 3 messages in queue jobs
+    #
+    class Refill < Base
+      # @!visibility private
+      def validate
+        raise "No queue registered with this name: #{options[:queue]}" if options[:queue] && !Falqon::Queue.all.map(&:name).include?(options[:queue])
+      end
+
+      # @!visibility private
+      def execute
+        queue = Falqon::Queue.new(options[:queue])
+
+        ids = queue.refill
+
+        puts "Refilled #{pluralize(ids.count, 'message', 'messages')} in queue #{queue.name}"
+      end
+    end
+  end
+end

data/lib/falqon/cli/revive.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Falqon
+  class CLI
+    # Revive queue (move dead messages to pending)
+    #
+    # This command moves all messages from the dead queue back to the pending queue (in order).
+    # It is useful when messages are moved to the dead queue due to repeated failures, and need to be retried.
+    #
+    # Usage:
+    #   falqon revive -q, --queue=QUEUE
+    #
+    # Options:
+    #   -q, --queue=QUEUE  # Queue name
+    #
+    # @example Revive the queue
+    #   $ falqon revive --queue jobs
+    #   Revived 3 messages in queue jobs
+    #
+    class Revive < Base
+      # @!visibility private
+      def validate
+        raise "No queue registered with this name: #{options[:queue]}" if options[:queue] && !Falqon::Queue.all.map(&:name).include?(options[:queue])
+      end
+
+      # @!visibility private
+      def execute
+        queue = Falqon::Queue.new(options[:queue])
+
+        ids = queue.revive
+
+        puts "Revived #{pluralize(ids.count, 'message', 'messages')} in queue #{queue.name}"
+      end
+    end
+  end
+end

data/lib/falqon/cli/schedule.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Falqon
+  class CLI
+    # Schedule failed messages for a retry
+    #
+    # This command moves all eligible messages from the scheduled queue back to the head of the pending queue (in order).
+    # Messages are eligible for a retry according to the configured retry strategy.
+    #
+    # Usage:
+    #   falqon schedule -q, --queue=QUEUE
+    #
+    # Options:
+    #   -q, --queue=QUEUE  # Queue name
+    #
+    # @example Schedule eligible failed messages for retry
+    #   $ falqon schedule --queue jobs
+    #   Scheduled 3 messages for a retry in queue jobs
+    class Schedule < Falqon::CLI::Base
+      # @!visibility private
+      def validate
+        raise "No queue registered with this name: #{options[:queue]}" if options[:queue] && !Falqon::Queue.all.map(&:name).include?(options[:queue])
+      end
+
+      # @!visibility private
+      def execute
+        # Schedule failed messages
+        message_ids = queue.schedule
+
+        puts "Scheduled #{pluralize(message_ids.count, 'failed message', 'failed messages')} for a retry in queue #{queue.name}"
+      end
+
+      private
+
+      def queue
+        @queue ||= Falqon::Queue.new(options[:queue])
+      end
+    end
+  end
+end

data/lib/falqon/cli/show.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Falqon
+  class CLI
+    # Display messages in a queue
+    #
+    # Usage:
+    #   falqon show -q, --queue=QUEUE
+    #
+    # Options:
+    #   -q, --queue=QUEUE                                           # Queue name
+    #       [--pending], [--no-pending], [--skip-pending]           # Display pending messages (default)
+    #       [--processing], [--no-processing], [--skip-processing]  # Display processing messages
+    #       [--dead], [--no-dead], [--skip-dead]                    # Display dead messages
+    #   -d, [--data], [--no-data], [--skip-data]                    # Display raw data
+    #   -m, [--meta], [--no-meta], [--skip-meta]                    # Display additional metadata
+    #       [--head=N]                                              # Display N messages from head of queue
+    #       [--tail=N]                                              # Display N messages from tail of queue
+    #       [--index=N]                                             # Display message at index N
+    #       [--range=N M]                                           # Display messages at index N to M
+    #       [--id=N]                                                # Display message with ID N
+    #
+    # @example Print all messages in the queue (by default only pending messages are displayed)
+    #   $ falqon show --queue jobs
+    #   id = 1 data = 8742 bytes
+    #
+    # @example Display only pending messages
+    #   $ falqon show --queue jobs --pending
+    #   ...
+    #
+    # @example Display only processing messages
+    #   $ falqon show --queue jobs --processing
+    #   ...
+    #
+    # @example Display only scheduled messages
+    #   $ falqon show --queue jobs --scheduled
+    #   ...
+    #
+    # @example Display only dead messages
+    #   $ falqon show --queue jobs --dead
+    #   ...
+    #
+    # @example Display raw data
+    #   $ falqon show --queue jobs --data
+    #   {"id":1,"message":"Hello, world!"}
+    #
+    # @example Display additional metadata
+    #   $ falqon show --queue jobs --meta
+    #   id = 1 retries = 0 created_at = 1970-01-01 00:00:00 +0000 updated_at = 1970-01-01 00:00:00 +0000 data = 8742 bytes
+    #
+    # @example Display first 5 messages
+    #   $ falqon show --queue jobs --head 5
+    #   id = 1 data = 8742 bytes
+    #   id = 2 data = 8742 bytes
+    #   id = 3 data = 8742 bytes
+    #   id = 4 data = 8742 bytes
+    #   id = 5 data = 8742 bytes
+    #
+    # @example Display last 5 messages
+    #   $ falqon show --queue jobs --tail 5
+    #   ...
+    #
+    # @example Display message at index 5
+    #   $ falqon show --queue jobs --index 3 --index 5
+    #   id = 3 data = 8742 bytes
+    #   id = 5 data = 8742 bytes
+    #
+    # @example Display messages from index 5 to 10
+    #   $ falqon show --queue jobs --range 5 10
+    #   ...
+    #
+    # @example Display message with ID 5
+    #   $ falqon show --queue jobs --id 5 --id 1
+    #   id = 5 data = 8742 bytes
+    #   id = 1 data = 8742 bytes
+    #
+    class Show < Base
+      # @!visibility private
+      def validate
+        raise "No queue registered with this name: #{options[:queue]}" if options[:queue] && !Falqon::Queue.all.map(&:name).include?(options[:queue])
+
+        raise "--pending, --processing, --scheduled, and --dead are mutually exclusive" if [options[:pending], options[:processing], options[:scheduled], options[:dead]].count(true) > 1
+        raise "--meta and --data are mutually exclusive" if [options[:meta], options[:data]].count(true) > 1
+
+        raise "--head, --tail, --index, and --range are mutually exclusive" if [options[:head], options[:tail], options[:index], options[:range]].count { |o| o } > 1
+        raise "--range must be specified as two integers" if options[:range] && options[:range].count != 2
+
+        raise "--id is mutually exclusive with --head, --tail, --index, and --range" if options[:id] && [options[:head], options[:tail], options[:index], options[:range]].count { |o| o }.positive?
+      end
+
+      # @!visibility private
+      def execute
+        # Collect identifiers
+        ids = if options[:id]
+                Array(options[:id])
+              else
+                queue.redis.with do |r|
+                  if options[:index]
+                    Array(options[:index]).map do |i|
+                      r.lindex(subqueue.id, i) || raise("No message at index #{i}")
+                    end
+                  else
+                    r.lrange(subqueue.id, *range_options)
+                  end
+                end
+              end
+
+        # Transform identifiers to messages
+        messages = ids.map do |id|
+          message = Falqon::Message.new(queue, id: id.to_i)
+
+          raise "No message with ID #{id}" unless message.exists?
+
+          message
+        end
+
+        # Serialize messages
+        messages.each do |message|
+          puts Serializer
+            .new(message, meta: options[:meta], data: options[:data])
+        end
+      end
+
+      private
+
+      def queue
+        @queue ||= Falqon::Queue.new(options[:queue])
+      end
+
+      def subqueue
+        @subqueue ||= if options[:processing]
+                        queue.processing
+                      elsif options[:scheduled]
+                        queue.scheduled
+                      elsif options[:dead]
+                        queue.dead
+                      else
+                        queue.pending
+                      end
+      end
+
+      def range_options
+        if options[:tail]
+          [
+            -options[:tail],
+            -1,
+          ]
+        elsif options[:range]
+          [
+            options[:range].first,
+            options[:range].last,
+          ]
+        else # options[:head]
+          [
+            0,
+            options.fetch(:head, 0) - 1,
+          ]
+        end
+      end
+
+      # @!visibility private
+      class Serializer
+        attr_reader :message, :meta, :data
+
+        def initialize(message, meta: false, data: false)
+          @message = message
+          @meta = meta
+          @data = data
+        end
+
+        def to_s
+          return message.data if data
+
+          if meta
+            "id = #{message.id} " \
+              "retries = #{message.metadata.retries} " \
+              "retried_at = #{message.metadata.retried_at ? Time.at(message.metadata.retried_at) : 'N/A'} " \
+              "retry_error = #{message.metadata.retry_error || 'N/A'} " \
+              "created_at = #{Time.at(message.metadata.created_at)} " \
+              "updated_at = #{Time.at(message.metadata.updated_at)} " \
+              "data = #{message.data.length} bytes"
+          else
+            "id = #{message.id} data = #{message.data.length} bytes"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/falqon/cli/stats.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Falqon
+  class CLI
+    # Display queue statistics
+    #
+    # Usage:
+    #   falqon stats
+    #
+    # Options:
+    #   -q, [--queue=QUEUE]  # Queue name
+    #
+    # @example Print statistics of all queues
+    #   $ falqon stats
+    #   jobs: 492 processed, 43 failed, 15 retried (created: 1970-01-01 00:00:00 +0000, updated: 1970-01-01 00:00:00 +0000)
+    #
+    # @example Print statistics of a specific queue
+    #   $ falqon status --queue jobs
+    #   jobs: 492 processed, 43 failed, 15 retried (created: 1970-01-01 00:00:00 +0000, updated: 1970-01-01 00:00:00 +0000)
+    #
+    class Stats < Base
+      # @!visibility private
+      def validate
+        raise "No queue registered with this name: #{options[:queue]}" if options[:queue] && !Falqon::Queue.all.map(&:name).include?(options[:queue])
+
+        raise "No queues registered" if Falqon::Queue.all.empty?
+      end
+
+      # @!visibility private
+      def execute
+        queues = options[:queue] ? [Falqon::Queue.new(options[:queue])] : Falqon::Queue.all
+
+        # Left pad queue names to the same length
+        length = queues.map { |q| q.name.length }.max
+
+        queues.each do |queue|
+          puts "#{queue.name.ljust length}: #{queue.metadata.processed} processed, #{queue.metadata.failed} failed, #{queue.metadata.retried} retried (created: #{Time.at(queue.metadata.created_at).to_datetime.iso8601}, updated: #{Time.at(queue.metadata.updated_at).to_datetime.iso8601})"
+        end
+      end
+    end
+  end
+end

data/lib/falqon/cli/status.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Falqon
+  class CLI
+    # Display queue status
+    #
+    # Usage:
+    #   falqon status
+    #
+    # Options:
+    #   -q, [--queue=QUEUE]  # Queue name
+    #
+    # @example Print status of all queues
+    #   $ falqon status
+    #   jobs: 41 messages (34 pending, 2 processing, 0 scheduled, 5 dead)
+    # emails: empty
+    #
+    # @example Print status of a specific queue
+    #   $ falqon status --queue jobs
+    #   jobs: 41 messages (34 pending, 2 processing, 0 scheduled, 5 dead)
+    #
+    class Status < Base
+      # @!visibility private
+      def validate
+        raise "No queue registered with this name: #{options[:queue]}" if options[:queue] && !Falqon::Queue.all.map(&:name).include?(options[:queue])
+
+        raise "No queues registered" if Falqon::Queue.all.empty?
+      end
+
+      # @!visibility private
+      def execute
+        queues = options[:queue] ? [Falqon::Queue.new(options[:queue])] : Falqon::Queue.all
+
+        # Left pad queue names to the same length
+        length = queues.map { |q| q.name.length }.max
+
+        queues.each do |queue|
+          if queue.pending.empty? && queue.processing.empty? && queue.dead.empty?
+            puts "#{queue.name.ljust length}: empty"
+          else
+            puts "#{queue.name.ljust length}: #{queue.pending.size} pending, #{queue.processing.size} processing, #{queue.scheduled.size} scheduled, #{queue.dead.size} dead"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/falqon/cli/version.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Falqon
+  class CLI
+    # @!visibility private
+    class Version < Base
+      def validate; end
+
+      def execute
+        puts "Falqon #{Falqon::VERSION}"
+      end
+    end
+  end
+end

data/lib/falqon/cli.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Falqon
+  # Falqon includes a command-line interface (CLI) to manage queues and messages
+  #
+  # After installing Falqon, run +falqon+ to see the available commands.
+  #
+  #   $ falqon
+  #   Commands:
+  #     falqon help [COMMAND]  # Describe available commands or one specific command
+  #     falqon status          # Print queue status
+  #     falqon version         # Print version
+  #
+  # To see the available options for a command, run +falqon help COMMAND+.
+  # The command-line interface assumes the default Falqon configuration.
+  # To use a custom configuration, set the corresponding environment variables:
+  #
+  #   # Configure global queue name prefix
+  #   FALQON_PREFIX=falqon
+  #
+  #   # Configure Redis connection pool
+  #   REDIS_URL=redis://localhost:6379/0
+  #
+  class CLI < Thor
+    # @!visibility private
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "version", "Display version"
+    # @!visibility private
+    def version
+      Version
+        .new(options)
+        .call
+    end
+
+    desc "list", "Display all active (registered) queues"
+    # @!visibility private
+    def list
+      List
+        .new(options)
+        .call
+    end
+
+    desc "status", "Display queue status"
+    option :queue, aliases: "-q", type: :string, desc: "Queue name"
+    # @!visibility private
+    def status
+      Status
+        .new(options)
+        .call
+    end
+
+    desc "stats", "Display queue statistics"
+    option :queue, aliases: "-q", type: :string, desc: "Queue name"
+    # @!visibility private
+    def stats
+      Stats
+        .new(options)
+        .call
+    end
+
+    desc "show", "Display messages in a queue"
+    option :queue, aliases: "-q", type: :string, desc: "Queue name", required: true
+
+    option :pending, type: :boolean, desc: "Display pending messages (default)"
+    option :processing, type: :boolean, desc: "Display processing messages"
+    option :dead, type: :boolean, desc: "Display dead messages"
+
+    option :data, aliases: "-d", type: :boolean, desc: "Display raw data"
+    option :meta, aliases: "-m", type: :boolean, desc: "Display additional metadata"
+
+    option :head, type: :numeric, desc: "Display N messages from head of queue"
+    option :tail, type: :numeric, desc: "Display N messages from tail of queue"
+    option :index, type: :numeric, desc: "Display message at index N", repeatable: true
+    option :range, type: :array, desc: "Display messages at index N to M", banner: "N M"
+
+    option :id, type: :numeric, desc: "Display message with ID N", repeatable: true
+    # @!visibility private
+    def show
+      Show
+        .new(options)
+        .call
+    end
+
+    desc "delete", "Delete messages from a queue"
+    option :queue, aliases: "-q", type: :string, desc: "Queue name", required: true
+
+    option :pending, type: :boolean, desc: "Delete only pending messages (default)"
+    option :processing, type: :boolean, desc: "Delete only processing messages"
+    option :dead, type: :boolean, desc: "Delete only dead messages"
+
+    option :head, type: :numeric, desc: "Delete N messages from head of queue"
+    option :tail, type: :numeric, desc: "Delete N messages from tail of queue"
+    option :index, type: :numeric, desc: "Delete message at index N", repeatable: true
+    option :range, type: :array, desc: "Delete messages at index N to M", banner: "N M"
+
+    option :id, type: :numeric, desc: "Delete message with ID N", repeatable: true
+    # @!visibility private
+    def delete
+      Delete
+        .new(options)
+        .call
+    end
+
+    desc "kill", "Kill messages in a queue"
+    option :queue, aliases: "-q", type: :string, desc: "Queue name", required: true
+
+    option :pending, type: :boolean, desc: "Kill only pending messages (default)"
+    option :processing, type: :boolean, desc: "Kill only processing messages"
+
+    option :head, type: :numeric, desc: "Kill N messages from head of queue"
+    option :tail, type: :numeric, desc: "Kill N messages from tail of queue"
+    option :index, type: :numeric, desc: "Kill message at index N", repeatable: true
+    option :range, type: :array, desc: "Kill messages at index N to M", banner: "N M"
+
+    option :id, type: :numeric, desc: "Kill message with ID N", repeatable: true
+    # @!visibility private
+    def kill
+      Kill
+        .new(options)
+        .call
+    end
+
+    desc "clear", "Clear messages from a queue"
+    option :queue, aliases: "-q", type: :string, desc: "Queue name", required: true
+
+    option :pending, type: :boolean, desc: "Clear only pending messages"
+    option :processing, type: :boolean, desc: "Clear only processing messages"
+    option :dead, type: :boolean, desc: "Clear only dead messages"
+    # @!visibility private
+    def clear
+      Clear
+        .new(options)
+        .call
+    end
+
+    desc "refill", "Refill queue (move processing messages to pending)"
+    option :queue, aliases: "-q", type: :string, desc: "Queue name", required: true
+    # @!visibility private
+    def refill
+      Refill
+        .new(options)
+        .call
+    end
+
+    desc "revive", "Revive queue (move dead messages to pending)"
+    option :queue, aliases: "-q", type: :string, desc: "Queue name", required: true
+    # @!visibility private
+    def revive
+      Revive
+        .new(options)
+        .call
+    end
+
+    desc "schedule", "Schedule failed messages for a retry"
+    option :queue, aliases: "-q", type: :string, desc: "Queue name", required: true
+    # @!visibility private
+    def schedule
+      Schedule
+        .new(options)
+        .call
+    end
+  end
+end