lepus 0.0.1.beta2 → 0.1.0

data/lib/lepus/cli.rb

@@ -2,26 +2,57 @@ require "thor"
 
 module Lepus
   class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
     method_option :debug, type: :boolean, default: false
     method_option :logfile, type: :string, default: nil
     method_option :pidfile, type: :string, default: nil
     method_option :require_file, type: :string, aliases: "-r", default: nil
 
-    desc "start FirstConsumer,SecondConsumer ... ,NthConsumer", "Run Consumer"
+    desc "start FirstConsumer SecondConsumer ... NthConsumer", "Run Consumer"
     default_command :start
 
-    def start(consumers = "")
+    def start(*consumers)
       opts = (@options || {}).transform_keys(&:to_sym)
-      unless consumers.empty?
-        opts[:consumers] = consumers.split(",").map(&:strip)
+
+      if (list = consumers.flat_map { |c| c.split(",") }.map(&:strip).uniq.sort).any?
+        opts[:consumers] = list
       end
+
       if (logfile = opts.delete(:logfile))
         Lepus.logger = Logger.new(logfile)
       end
       if opts.delete(:debug)
         Lepus.logger.level = Logger::DEBUG
       end
+
       Lepus::Supervisor.start(**opts)
     end
+
+    desc "web", "Run Lepus Web dashboard"
+    method_option :port, type: :numeric, aliases: "-p", default: 9292, desc: "Port to listen on"
+    method_option :host, type: :string, aliases: "-o", default: "0.0.0.0", desc: "Host to bind"
+    def web
+      port = (options[:port] || 9292).to_i
+      host = options[:host] || "0.0.0.0"
+
+      puts "Starting Lepus Web dashboard on http://#{host}:#{port}"
+      puts "Press Ctrl+C to stop"
+
+      if system("which rackup > /dev/null 2>&1")
+
+        exec "rackup -p #{port} -o #{host} #{__dir__}/../../config.ru"
+      else
+        puts <<~MSG
+          Rack is not installed. Please install it using the following command:
+
+              gem install rack
+
+          Then run the web dashboard again.
+        MSG
+      end
+    end
   end
 end

data/lib/lepus/configuration.rb

@@ -40,6 +40,27 @@ module Lepus
     # @return [Integer] the threshold in seconds to consider a process alive. Default is 5 minutes.
     attr_accessor :process_alive_threshold
 
+    # @return [Symbol] the process registry backend to use (:file or :rabbitmq). Default is :file.
+    attr_accessor :process_registry_backend
+
+    # @return [String, nil] the application name shown in the web dashboard.
+    #   Falls back to {#connection_name} when not explicitly set so that hosts
+    #   that only configure `connection_name` still group correctly in the UI.
+    attr_writer :application_name
+
+    def application_name
+      @application_name || connection_name
+    end
+
+    # @return [String, nil] the RabbitMQ Management API URL.
+    attr_accessor :management_api_url
+
+    # @return [Array<Numeric>] histogram buckets (in seconds) used by the
+    #   prometheus_exporter collector for delivery and publish latency.
+    attr_accessor :prometheus_buckets
+
+    DEFAULT_PROMETHEUS_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10].freeze
+
     def initialize
       @connection_name = "Lepus (#{Lepus::VERSION})"
       @rabbitmq_url = ENV.fetch("RABBITMQ_URL", DEFAULT_RABBITMQ_URL) || DEFAULT_RABBITMQ_URL
@@ -49,22 +70,108 @@ module Lepus
       @consumers_directory = DEFAULT_CONSUMERS_DIRECTORY
       @process_heartbeat_interval = 60
       @process_alive_threshold = 5 * 60
+      @process_registry_backend = :file
+      @application_name = nil
+      @management_api_url = nil
+      @prometheus_buckets = DEFAULT_PROMETHEUS_BUCKETS
+    end
+
+    # Builds the process registry backend based on configuration.
+    # @return [Lepus::ProcessRegistry::Backend] the configured backend
+    def build_process_registry_backend
+      case process_registry_backend
+      when :rabbitmq
+        ProcessRegistry::RabbitmqBackend.new
+      else
+        ProcessRegistry::FileBackend.new
+      end
+    end
+
+    # Builds the Management API client based on configuration.
+    # @return [Lepus::Web::ManagementAPI] the management API client
+    def build_management_api
+      Web::ManagementAPI.new(base_url: management_api_url)
     end
 
+    # @param suffix [String] the suffix to add to the connection name
+    # @return [Bunny::Session] the connection to RabbitMQ
     def create_connection(suffix: nil)
       kwargs = connection_config
+
       if suffix && connection_name
         kwargs[:connection_name] = "#{connection_name} #{suffix}"
       end
+
       ::Bunny
         .new(rabbitmq_url, **kwargs)
         .tap { |conn| conn.start }
     end
 
+    # @param value [Pathname] the directory where the consumers are stored.
     def consumers_directory=(value)
       @consumers_directory = value.is_a?(Pathname) ? value : Pathname.new(value)
     end
 
+    # Configure the worker process that will run the consumers.
+    # @param names [Array<Symbol>] the names of the workers to configure
+    # @param options [Hash] the options to assign to the worker configuration
+    def worker(*names, **options)
+      names << Lepus::Consumers::WorkerFactory::DEFAULT_NAME if names.empty?
+
+      names.map(&:to_s).uniq.each do |pid|
+        inst = Lepus::Consumers::WorkerFactory[pid]
+        inst.assign(options) if options.any?
+        yield(inst) if block_given?
+      end
+    end
+
+    # Configure the producer related settings.
+    # @param options [Hash] the options to assign to the producer configuration
+    def producer(**options)
+      producer_config.assign(options) if options.any?
+      yield(producer_config) if block_given?
+      producer_config
+    end
+
+    # @return [Lepus::Producers::Config] the producer configuration
+    def producer_config
+      @producer_config ||= Lepus::Producers::Config.new
+    end
+
+    # @return [Lepus::Producers::MiddlewareChain] the global producer middleware chain
+    def producer_middleware_chain
+      @producer_middleware_chain ||= Lepus::Producers::MiddlewareChain.new
+    end
+
+    # Configure global producer middlewares.
+    # @yield [chain] Block to configure the middleware chain.
+    # @yieldparam chain [Lepus::Producers::MiddlewareChain] The middleware chain.
+    # @return [Lepus::Producers::MiddlewareChain]
+    def producer_middlewares
+      yield(producer_middleware_chain) if block_given?
+      producer_middleware_chain
+    end
+
+    # @return [Lepus::Consumers::MiddlewareChain] the global consumer middleware chain
+    def consumer_middleware_chain
+      @consumer_middleware_chain ||= Lepus::Consumers::MiddlewareChain.new
+    end
+
+    # Configure global consumer middlewares.
+    # @yield [chain] Block to configure the middleware chain.
+    # @yieldparam chain [Lepus::Consumers::MiddlewareChain] The middleware chain.
+    # @return [Lepus::Consumers::MiddlewareChain]
+    def consumer_middlewares
+      yield(consumer_middleware_chain) if block_given?
+      consumer_middleware_chain
+    end
+
+    # @param value [Logger] the logger to set
+    # @return [void]
+    def logger=(value)
+      Lepus.logger = value
+    end
+
     protected
 
     def connection_config

data/lib/lepus/connection_pool.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Lepus
+  # Connection pool for managing Bunny connections efficiently
+  # Similar to the connection_pool gem but using concurrent-ruby primitives
+  class ConnectionPool
+    DEFAULT_SIZE = 5
+    DEFAULT_TIMEOUT = 5.0
+
+    attr_reader :pool_size, :timeout, :conn_suffix
+
+    def initialize(size: DEFAULT_SIZE, timeout: DEFAULT_TIMEOUT, suffix: nil)
+      @pool_size = size
+      @timeout = timeout
+      @conn_suffix = suffix
+      @available = Concurrent::Array.new
+      @in_use = Concurrent::Array.new
+      @semaphore = Concurrent::Semaphore.new(pool_size)
+      @mutex = Concurrent::ReadWriteLock.new
+      @shutdown = Concurrent::AtomicBoolean.new(false)
+    end
+
+    def with_connection
+      connection = checkout
+      begin
+        yield connection
+      ensure
+        checkin(connection)
+      end
+    rescue Concurrent::TimeoutError
+      raise Lepus::ConnectionPoolTimeoutError, "Connection pool timeout after #{timeout} seconds"
+    end
+
+    def checkout
+      raise Lepus::ConnectionPoolError, "Connection pool is shut down" if @shutdown.value
+
+      # Try to acquire a permit with timeout
+      start_time = Time.now
+      acquired = false
+
+      while Time.now - start_time < timeout
+        if @semaphore.try_acquire
+          acquired = true
+          break
+        end
+        sleep(0.01) # Small sleep to avoid busy waiting
+      end
+
+      unless acquired
+        raise Concurrent::TimeoutError, "Connection pool timeout"
+      end
+
+      @mutex.with_read_lock do
+        # Try to reuse an existing connection
+        connection = @available.shift
+        if connection&.connected?
+          @in_use << connection
+          return connection
+        end
+      end
+
+      # Create a new connection
+      connection = Lepus.config.create_connection(suffix: @conn_suffix)
+      @mutex.with_write_lock do
+        @in_use << connection
+      end
+      connection
+    rescue => e
+      @semaphore.release
+      raise e
+    end
+
+    def checkin(connection)
+      return unless connection
+
+      @mutex.with_write_lock do
+        @in_use.delete(connection)
+        if connection.connected? && !@shutdown.value
+          @available << connection
+        else
+          begin
+            connection.close
+          rescue
+            nil
+          end
+        end
+      end
+      @semaphore.release
+    end
+
+    def shutdown
+      @shutdown.make_true
+
+      @mutex.with_write_lock do
+        (@available + @in_use).each do |connection|
+          connection.close
+        rescue
+          nil
+        end
+        @available.clear
+        @in_use.clear
+      end
+    end
+
+    def available?
+      !@shutdown.value
+    end
+
+    def size
+      @mutex.with_read_lock do
+        @available.length + @in_use.length
+      end
+    end
+
+    def available_count
+      @mutex.with_read_lock do
+        @available.length
+      end
+    end
+
+    def in_use_count
+      @mutex.with_read_lock do
+        @in_use.length
+      end
+    end
+  end
+
+  # Error raised when connection pool times out
+  class ConnectionPoolTimeoutError < StandardError; end
+
+  # Error raised when connection pool encounters an error
+  class ConnectionPoolError < StandardError; end
+end

data/lib/lepus/consumer.rb

@@ -26,32 +26,22 @@ module Lepus
         return @config if defined?(@config)
 
         name = Primitive::String.new(to_s).underscore.split("/").last
-        @config = ConsumerConfig.new(queue: name, exchange: name)
+        @config = Consumers::Config.new(queue: name, exchange: name)
       end
 
-      # List of registered middlewares. Register new middlewares with {.use}.
-      # @return [Array<Lepus::Middleware>]
-      def middlewares
-        @middlewares ||= []
+      # Returns the middleware chain for this consumer.
+      # @return [Lepus::Consumers::MiddlewareChain]
+      def middleware_chain
+        @middleware_chain ||= Consumers::MiddlewareChain.new
       end
 
-      # Registers a new middleware by instantiating +middleware+ and passing it +opts+.
+      # Registers a middleware to this consumer's chain.
       #
-      # @param [Symbol, Class<Lepus::Middleware>] middleware The middleware class to instantiate and register.
-      # @param [Hash] opts The options for instantiating the middleware.
+      # @param middleware [Symbol, String, Class<Lepus::Middleware>] The middleware to register.
+      # @param opts [Hash] Options passed to the middleware constructor.
+      # @return [Lepus::Consumers::MiddlewareChain]
       def use(middleware, opts = {})
-        if middleware.is_a?(Symbol) || middleware.is_a?(String)
-          begin
-            require_relative "middlewares/#{middleware}"
-            class_name = Primitive::String.new(middleware.to_s).classify
-            class_name = "JSON" if class_name == "Json"
-            middleware = Lepus::Middlewares.const_get(class_name)
-          rescue LoadError, NameError
-            raise ArgumentError, "Middleware #{middleware} not found"
-          end
-        end
-
-        middlewares << middleware.new(**opts)
+        middleware_chain.use(middleware, opts)
       end
 
       # Configures the consumer, setting queue, exchange and other options to be used by
@@ -64,7 +54,9 @@ module Lepus
       # @option opts [Boolean, Hash] :retry_queue (false) Whether a retry queue should be provided.
       # @option opts [Boolean, Hash] :error_queue (false) Whether an error queue should be provided.
       def configure(opts = {})
-        @config = ConsumerConfig.new(opts)
+        raise ArgumentError, "Cannot configure an abstract class" if abstract_class?
+
+        @config = Consumers::Config.new(opts)
         yield(@config) if block_given?
         @config
       end
@@ -95,24 +87,37 @@ module Lepus
     # @param [String] payload The payload of the received message.
     # @raise [InvalidConsumerReturnError] if you return something other than +:ack+, +:reject+ or +:requeue+ from {#perform}.
     def process_delivery(delivery_info, metadata, payload)
-      message = Message.new(delivery_info, metadata, payload)
-      self
-        .class
-        .middlewares
-        .reverse
-        .reduce(work_proc) do |next_middleware, middleware|
-          nest_middleware(middleware, next_middleware)
+      message = Message.coerce(delivery_info, metadata, payload)
+      message.consumer_class = self.class
+
+      combined_chain = MiddlewareChain.combine(
+        Lepus.config.consumer_middleware_chain,
+        self.class.middleware_chain
+      )
+
+      combined_chain.execute(message) do |msg|
+        perform(msg).tap do |result|
+          verify_result(result)
         end
-        .call(message)
+      end
     rescue Lepus::InvalidConsumerReturnError
       raise
-    rescue Exception => ex # rubocop:disable Lint/RescueException
-      # @TODO: add error handling
-      logger.error(ex)
+    rescue Exception # rubocop:disable Lint/RescueException
+      on_delivery_error
+      # In testing mode, re-raise exceptions if consumer_raise_errors? is enabled
+      if defined?(Lepus::Testing) && Lepus::Testing.consumer_raise_errors?
+        raise
+      end
 
       reject!
     end
 
+    # Returns whether the last delivery resulted in an error.
+    # Always false in core; overridden by Lepus::Web when loaded.
+    def last_delivery_errored?
+      false
+    end
+
     protected
 
     def logger
@@ -154,18 +159,31 @@ module Lepus
 
     private
 
-    def work_proc
-      ->(message) do
-        perform(message).tap do |result|
-          verify_result(result)
-        end
+    # Publishes a message using the consumer's own exchange configuration.
+    # When exchange_name is different from the consumer's exchange, uses default options.
+    #
+    # @param [String, Hash] message The message to publish
+    # @param [String, nil] exchange_name Override the exchange name (optional)
+    # @param [Hash] options Additional publish options
+    # @return [void]
+    def publish_message(message, exchange_name: nil, channel: nil, **options)
+      target_exchange = exchange_name || self.class.config.exchange_name
+      return unless Lepus::Producers.exchange_enabled?(target_exchange)
+
+      opts = (target_exchange == self.class.config.exchange_name) ? self.class.config.exchange_options : {}
+      opts.merge!(options)
+
+      channel ||= instance_variable_get(:@_handler_channel) # The Lepus::Consumers::Handler sets this variable
+      if channel
+        Lepus::Publisher.new(target_exchange, **opts).channel_publish(channel, message, **opts)
+      else
+        Lepus::Publisher.new(target_exchange, **opts).publish(message, **opts)
       end
     end
 
-    def nest_middleware(middleware, next_middleware)
-      ->(message) do
-        middleware.call(message, next_middleware)
-      end
+    # Hook called when a delivery raises an exception.
+    # No-op in core; overridden by Lepus::Web to track error state.
+    def on_delivery_error
     end
 
     def verify_result(result)

data/lib/lepus/consumers/config.rb

@@ -0,0 +1,183 @@
+require "bunny"
+
+module Lepus
+  module Consumers
+    # Parse the list of options for the consumer.
+    class Config
+      DEFAULT_EXCHANGE_OPTIONS = {
+        name: nil,
+        type: :topic, # The type of the exchange (:direct, :fanout, :topic or :headers).
+        durable: true
+      }.freeze
+
+      DEFAULT_CHANNEL_OPTIONS = {
+        pool_size: 1,
+        abort_on_exception: false,
+        shutdown_timeout: 60
+      }.freeze
+
+      DEFAULT_QUEUE_OPTIONS = {
+        name: nil,
+        durable: true
+      }.freeze
+
+      DEFAULT_PREFETCH_COUNT = 1
+
+      DEFAULT_WORKER_OPTIONS = {
+        name: "default",
+        threads: 1
+      }.freeze
+
+      DEFAULT_RETRY_QUEUE_OPTIONS = {
+        name: nil,
+        durable: true,
+        delay: 5000,
+        arguments: {}
+      }
+
+      DEFAULT_ERROR_QUEUE_OPTIONS = DEFAULT_QUEUE_OPTIONS
+
+      attr_reader :options, :prefetch_count
+
+      def initialize(options = {})
+        opts = Lepus::Primitive::Hash.new(options).deep_symbolize_keys
+
+        @worker_opts = DEFAULT_WORKER_OPTIONS.merge(
+          declaration_config(opts.delete(:worker))
+        )
+        @exchange_opts = DEFAULT_EXCHANGE_OPTIONS.merge(
+          declaration_config(opts.delete(:exchange))
+        )
+        @queue_opts = DEFAULT_QUEUE_OPTIONS.merge(
+          declaration_config(opts.delete(:queue))
+        )
+        if (value = opts.delete(:retry_queue))
+          @retry_queue_opts = DEFAULT_RETRY_QUEUE_OPTIONS.merge(
+            declaration_config(value)
+          )
+        end
+        if (value = opts.delete(:error_queue))
+          @error_queue_opts = DEFAULT_ERROR_QUEUE_OPTIONS.merge(
+            declaration_config(value)
+          )
+        end
+        @channel_opts = DEFAULT_CHANNEL_OPTIONS.merge(opts.delete(:channel) || {})
+        @bind_opts = opts.delete(:bind) || {}
+        if (routing_key = opts.delete(:routing_key))
+          @bind_opts[:routing_key] ||= routing_key
+        end
+        @prefetch_count = opts.key?(:prefetch) ? opts.delete(:prefetch) : DEFAULT_PREFETCH_COUNT
+        @options = opts
+      end
+
+      def channel_args
+        [
+          nil,
+          *@channel_opts.values_at(
+            :pool_size,
+            :abort_on_exception,
+            :shutdown_timeout
+          )
+        ]
+      end
+
+      def exchange_name
+        @exchange_opts[:name] || raise(InvalidConsumerConfigError, "Exchange name is required")
+      end
+
+      def exchange_options
+        @exchange_opts.reject { |k, v| k == :name }
+      end
+
+      def consumer_queue_args
+        opts = @queue_opts.reject { |k, v| k == :name }
+        return [queue_name, opts] unless retry_queue_args
+
+        opts[:arguments] ||= {}
+        opts[:arguments]["x-dead-letter-exchange"] = ""
+        opts[:arguments]["x-dead-letter-routing-key"] = retry_queue_name
+
+        [queue_name, opts]
+      end
+
+      def retry_queue_args
+        return unless @retry_queue_opts
+
+        delay = @retry_queue_opts[:delay]
+        args = (@retry_queue_opts[:arguments] || {}).merge(
+          "x-dead-letter-exchange" => "",
+          "x-dead-letter-routing-key" => queue_name,
+          "x-message-ttl" => delay
+        )
+        extra_keys = %i[name delay]
+        opts = @retry_queue_opts.reject { |k, v| extra_keys.include?(k) }
+        [retry_queue_name, opts.merge(arguments: args)]
+      end
+
+      def error_queue_args
+        return unless @error_queue_opts
+
+        [error_queue_name, @error_queue_opts.reject { |k, v| k == :name }]
+      end
+
+      def binds_args
+        arguments = @bind_opts.fetch(:arguments, {}).transform_keys(&:to_s)
+        opts = {}
+        opts[:arguments] = arguments unless arguments.empty?
+        if (routing_keys = @bind_opts[:routing_key]).is_a?(Array)
+          routing_keys.map { |key| opts.merge(routing_key: key) }
+        elsif (routing_key = @bind_opts[:routing_key])
+          [opts.merge(routing_key: routing_key)]
+        elsif @exchange_opts[:type] == :topic
+          [opts.merge(routing_key: "#")]
+        else
+          [opts]
+        end
+      end
+
+      def worker_name
+        @worker_opts.fetch(:name, DEFAULT_WORKER_OPTIONS[:name])
+      end
+
+      def worker_threads
+        threads = @worker_opts.fetch(:threads, DEFAULT_WORKER_OPTIONS[:threads])
+        if threads.to_i < 1
+          raise InvalidConsumerConfigError, "Worker threads must be at least 1"
+        end
+        threads
+      end
+
+      def queue_name
+        @queue_opts[:name] || raise(InvalidConsumerConfigError, "Queue name is required")
+      end
+
+      def retry_queue_name
+        name = @retry_queue_opts[:name]
+        name ||= "#{queue_name}.retry"
+        name
+      end
+
+      def error_queue_name
+        name = @error_queue_opts[:name]
+        name ||= "#{queue_name}.error"
+        name
+      end
+
+      protected
+
+      # Normalizes a declaration config (for exchanges and queues) into a configuration Hash.
+      #
+      # If the given `value` is a String, convert it to a Hash with the key `:name` and the value.
+      # If the given `value` is a Hash, leave it as is.
+      def declaration_config(value)
+        case value
+        when Hash then value
+        when String then {name: value}
+        when Symbol then {name: value.to_s}
+        when NilClass then {}
+        when TrueClass then {}
+        end
+      end
+    end
+  end
+end