lepus 0.2.2 → 0.3.0

data/gemfiles/Gemfile.rails-8.0.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    lepus (0.2.2)
+    lepus (0.3.0)
       base64
       bunny
       concurrent-ruby

data/lib/lepus/configuration.rb

@@ -9,6 +9,7 @@ module Lepus
     DEFAULT_RECOVER_FROM_CONNECTION_CLOSE = true
     DEFAULT_CONSUMERS_DIRECTORY = Pathname.new("app/consumers")
     DEFAULT_CONNECTION = :default
+    DEFAULT_DELAY_QUEUE_EXPIRES = 3_600_000
 
     # @return [String] the connection string for RabbitMQ.
     attr_accessor :rabbitmq_url
@@ -60,6 +61,10 @@ module Lepus
     #   prometheus_exporter collector for delivery and publish latency.
     attr_accessor :prometheus_buckets
 
+    # @return [Integer, nil] milliseconds an unused delay queue is kept beyond its delay before
+    #   RabbitMQ deletes it (x-expires = delay + this value). nil disables x-expires.
+    attr_accessor :delay_queue_expires
+
     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
@@ -75,6 +80,7 @@ module Lepus
       @application_name = nil
       @management_api_url = nil
       @prometheus_buckets = DEFAULT_PROMETHEUS_BUCKETS
+      @delay_queue_expires = DEFAULT_DELAY_QUEUE_EXPIRES
     end
 
     # Builds the process registry backend based on configuration.

data/lib/lepus/consumer.rb

@@ -4,6 +4,8 @@ module Lepus
   # The abstract base class for consumers processing messages from queues.
   # @abstract Subclass and override {#work} to implement.
   class Consumer
+    CURRENT_DELIVERY_KEY = :lepus_consumer_delivery
+
     class << self
       def abstract_class?
         return @abstract_class == true if defined?(@abstract_class)
@@ -95,12 +97,16 @@ 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)
+      previous_delivery = Thread.current[CURRENT_DELIVERY_KEY]
       message = Message.coerce(delivery_info, metadata, payload)
       message.consumer_class = self.class
 
+      Thread.current[CURRENT_DELIVERY_KEY] = message
       Lepus.instrument(:process_delivery, **delivery_attributes(delivery_info)) do |event|
         event[:result] = deliver(message, delivery_info)
       end
+    ensure
+      Thread.current[CURRENT_DELIVERY_KEY] = previous_delivery
     end
 
     # Returns whether the last delivery resulted in an error.
@@ -148,6 +154,34 @@ module Lepus
     end
     alias_method :nack, :nack!
 
+    # Re-delivers the message being processed to this consumer's queue after the given delay,
+    # and acks the current delivery. The redelivery arrives through the default exchange, so its
+    # routing key is the queue name, and its {Lepus::Delay::COUNT_HEADER} header is incremented.
+    #
+    # @param value [Integer, Float, #in_milliseconds] The delay in milliseconds.
+    # @return [:ack]
+    # @raise [Lepus::Error] when the consumer is configured with +delays+ that don't include the value.
+    def delay!(value)
+      message = Thread.current[CURRENT_DELIVERY_KEY]
+      raise Lepus::Error, "delay! must be called while processing a message" unless message
+
+      opts = message.to_publish_options
+      opts.delete(:expiration)
+      headers = opts[:headers] || {}
+      opts[:headers] = headers.merge(Delay::COUNT_HEADER => headers[Delay::COUNT_HEADER].to_i + 1)
+      opts[:routing_key] = self.class.config.queue_name
+      opts[:delay] = Delay.resolve(value, self.class.config.delay_values)
+
+      publisher = Lepus::Publisher.new(Delay::DEFAULT_EXCHANGE)
+      if (channel = instance_variable_get(:@_handler_channel))
+        publisher.channel_publish(channel, message.payload, **opts)
+      else
+        publisher.publish(message.payload, **opts)
+      end
+      ack!
+    end
+    alias_method :delay, :delay!
+
     private
 
     # Publishes a message using the consumer's own exchange configuration.

data/lib/lepus/consumers/config.rb

@@ -37,7 +37,7 @@ module Lepus
 
       DEFAULT_ERROR_QUEUE_OPTIONS = DEFAULT_QUEUE_OPTIONS
 
-      attr_reader :options, :prefetch_count
+      attr_reader :options, :prefetch_count, :delay_values
 
       def initialize(options = {})
         opts = Lepus::Primitive::Hash.new(options).deep_symbolize_keys
@@ -67,6 +67,7 @@ module Lepus
           @bind_opts[:routing_key] ||= routing_key
         end
         @prefetch_count = opts.key?(:prefetch) ? opts.delete(:prefetch) : DEFAULT_PREFETCH_COUNT
+        @delay_values = Lepus::Delay.normalize_all(opts.delete(:delays))
         @options = opts
       end
 
@@ -152,15 +153,15 @@ module Lepus
       end
 
       def retry_queue_name
-        name = @retry_queue_opts[:name]
-        name ||= "#{queue_name}.retry"
-        name
+        return unless @retry_queue_opts
+
+        @retry_queue_opts[:name] || "#{queue_name}.retry"
       end
 
       def error_queue_name
-        name = @error_queue_opts[:name]
-        name ||= "#{queue_name}.error"
-        name
+        return unless @error_queue_opts
+
+        @error_queue_opts[:name] || "#{queue_name}.error"
       end
 
       protected

data/lib/lepus/consumers/stats.rb

@@ -5,7 +5,7 @@ require "concurrent"
 module Lepus
   module Consumers
     # Thread-safe per-consumer-class statistics tracker.
-    # Uses atomic counters to track processed/rejected/errored message counts.
+    # Uses atomic counters to track processed/rejected/errored/delayed message counts.
     class Stats
       attr_reader :consumer_class
 
@@ -14,6 +14,7 @@ module Lepus
         @processed = Concurrent::AtomicFixnum.new(0)
         @rejected = Concurrent::AtomicFixnum.new(0)
         @errored = Concurrent::AtomicFixnum.new(0)
+        @delayed = Concurrent::AtomicFixnum.new(0)
       end
 
       def record_processed
@@ -28,6 +29,10 @@ module Lepus
         @errored.increment
       end
 
+      def record_delayed
+        @delayed.increment
+      end
+
       def processed
         @processed.value
       end
@@ -40,6 +45,10 @@ module Lepus
         @errored.value
       end
 
+      def delayed
+        @delayed.value
+      end
+
       def to_h
         config = consumer_class.config
         {
@@ -47,10 +56,14 @@ module Lepus
           exchange: config.exchange_name,
           queue: config.queue_name,
           route: extract_route(config),
+          retry_queue: (config.retry_queue_name if config.retry_queue_args),
+          error_queue: (config.error_queue_name if config.error_queue_args),
           threads: config.worker_threads,
           processed: @processed.value,
           rejected: @rejected.value,
-          errored: @errored.value
+          errored: @errored.value,
+          delayed: @delayed.value,
+          delays: config.delay_values
         }
       end
 

data/lib/lepus/delay.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Lepus
+  # Delayed delivery built on per-delay TTL queues that dead-letter back to their target,
+  # so it works without the rabbitmq-delayed-message-exchange plugin.
+  #
+  # Exchange delays: messages are published to a headers exchange named "<exchange>.delayed"
+  # with a {HEADER} header. Each delay value has its own "<exchange>.delayed.<ms>" queue bound by
+  # that header; the queue dead-letters into the target exchange keeping the original routing key.
+  #
+  # Queue delays: messages are published through the default exchange to "<queue>.delay.<ms>",
+  # which dead-letters straight into the target queue.
+  module Delay
+    HEADER = "lepus-delay"
+    COUNT_HEADER = "x-lepus-delayed-count"
+    DEFAULT_EXCHANGE = ""
+    REDECLARE_INTERVAL = 60
+
+    @declarations = {}
+    @known_queues = Set.new
+    @mutex = Mutex.new
+
+    class << self
+      # @param value [Integer, Float, #in_milliseconds] The delay in milliseconds.
+      # @return [Integer] The delay in whole milliseconds.
+      # @raise [ArgumentError] when the value is not a positive number of milliseconds.
+      def normalize(value)
+        ms = case value
+        when Numeric then value
+        else value.respond_to?(:in_milliseconds) ? value.in_milliseconds : value
+        end
+        raise ArgumentError, "Invalid delay #{value.inspect}, expected milliseconds" unless finite_number?(ms)
+
+        ms = ms.round
+        raise ArgumentError, "Delay must be greater than zero, got #{value.inspect}" unless ms > 0
+
+        ms
+      end
+
+      # Normalizes the delay and checks it against the allowed delays, when given.
+      # @param allowed [Array<Integer>, nil] The only delays accepted, in milliseconds.
+      # @return [Integer] The delay in whole milliseconds.
+      # @raise [Lepus::Error] when the delay is not one of the allowed values.
+      def resolve(value, allowed = nil)
+        ms = normalize(value)
+        if allowed && !allowed.include?(ms)
+          raise Lepus::Error, "Delay #{ms}ms is not allowed, expected one of #{allowed.inspect} (delays option)"
+        end
+
+        ms
+      end
+
+      # @return [Array<Integer>, nil] The normalized, sorted and unique delays, or nil when none are given.
+      def normalize_all(values)
+        return if values.nil?
+
+        Array(values).map { |value| normalize(value) }.uniq.sort.freeze
+      end
+
+      def exchange_name_for(exchange)
+        "#{exchange}.delayed"
+      end
+
+      def exchange_queue_name_for(exchange, ms)
+        "#{exchange}.delayed.#{ms}"
+      end
+
+      def queue_delay_name_for(queue, ms)
+        "#{queue}.delay.#{ms}"
+      end
+
+      def queue_args_for_exchange(exchange, ms)
+        with_expires(ms,
+          "x-message-ttl" => ms,
+          "x-dead-letter-exchange" => exchange)
+      end
+
+      def queue_args_for_queue(queue, ms)
+        with_expires(ms,
+          "x-message-ttl" => ms,
+          "x-dead-letter-exchange" => DEFAULT_EXCHANGE,
+          "x-dead-letter-routing-key" => queue)
+      end
+
+      # Declares the delayed headers exchange and the queue for the given delay.
+      # @return [String] The name of the delayed exchange to publish to.
+      def declare_for_exchange!(channel, exchange, ms)
+        delayed_exchange = exchange_name_for(exchange)
+        queue = exchange_queue_name_for(exchange, ms)
+        args = queue_args_for_exchange(exchange, ms)
+
+        declare(channel, queue, args) do |ch|
+          ch.exchange_declare(delayed_exchange, :headers, durable: true)
+          ch.queue_declare(queue, durable: true, arguments: args)
+          ch.queue_bind(queue, delayed_exchange, arguments: {"x-match" => "all", HEADER => ms})
+        end
+        delayed_exchange
+      end
+
+      # Declares the queue that delays deliveries to the given queue.
+      # @return [String] The name of the delay queue to publish to.
+      def declare_for_queue!(channel, queue, ms)
+        delay_queue = queue_delay_name_for(queue, ms)
+        args = queue_args_for_queue(queue, ms)
+
+        declare(channel, delay_queue, args) do |ch|
+          ch.queue_declare(delay_queue, durable: true, arguments: args)
+        end
+        delay_queue
+      end
+
+      def reset!
+        mutex.synchronize do
+          declarations.clear
+          known_queues.clear
+        end
+      end
+
+      private
+
+      def finite_number?(value)
+        return false unless value.is_a?(Numeric) && value.real?
+
+        !value.respond_to?(:finite?) || value.finite?
+      end
+
+      def with_expires(ms, args)
+        padding = Lepus.config.delay_queue_expires
+        return args unless padding
+
+        args.merge("x-expires" => ms + padding)
+      end
+
+      # Declarations run on a short-lived channel so a failure does not close the caller's channel.
+      # RabbitMQ only counts declarations and consumers as queue usage for x-expires, and a message
+      # published at t must outlive t + delay while the queue only lives until the last declaration
+      # + delay + padding, so declarations are refreshed before half of the padding elapses.
+      # The refresh is also capped so a queue deleted behind our back is declared again soon.
+      def declare(channel, queue, args)
+        connection = channel.connection
+        key = [connection, queue, args]
+        return if declared?(key)
+
+        begin
+          connection.with_channel { |ch| yield ch }
+        rescue Bunny::PreconditionFailed => e
+          raise Lepus::Error, "Cannot declare delay queue #{queue.inspect} with #{args.inspect}: #{e.message}. " \
+            "Delete the queue or keep its previous arguments."
+        end
+
+        first = mutex.synchronize do
+          declarations[key] = monotonic_now + redeclare_interval
+          known_queues.add?(queue)
+        end
+        Lepus.logger.info("[Lepus::Delay] Declared delay queue #{queue.inspect} (#{known_queues.size} in this process)") if first
+      end
+
+      def declared?(key)
+        mutex.synchronize do
+          next false unless declarations.key?(key)
+
+          monotonic_now < declarations[key]
+        end
+      end
+
+      def redeclare_interval
+        padding = Lepus.config.delay_queue_expires
+        return REDECLARE_INTERVAL unless padding
+
+        [padding / 2000.0, REDECLARE_INTERVAL].min
+      end
+
+      def monotonic_now
+        ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      end
+
+      attr_reader :declarations, :known_queues, :mutex
+    end
+  end
+end

data/lib/lepus/primitive/string.rb

@@ -1,17 +1,7 @@
 # frozen_string_literal: true
 
-begin
-  require "dry/inflector"
-rescue LoadError
-  # noop
-end
-
-begin
-  require "active_support/inflector"
-rescue LoadError
-  # noop
-end
-
+# Uses dry-inflector or ActiveSupport only when the host app has already
+# loaded one, so Lepus never pulls either in by itself.
 module Lepus::Primitive
   class String < ::String
     def classify

data/lib/lepus/producer.rb

@@ -87,6 +87,7 @@ module Lepus
       # @param connection [Symbol, String, nil] The named connection to publish through,
       #   overriding the one set in {.configure}.
       # @param options [Hash] Additional publish options (routing_key, headers, etc.).
+      # @option options [Integer, #in_milliseconds] :delay Delivers the message after this many milliseconds.
       # @return [void]
       def publish(payload, connection: nil, **options)
         if definition.nil?
@@ -99,6 +100,8 @@ module Lepus
         return unless Producers.enabled?(self)
 
         publish_opts = definition.publish_options.merge(options)
+        delay = publish_opts.delete(:delay)
+        delay = Delay.resolve(delay, definition.delay_values) if delay
         message = build_message(payload, publish_opts)
         combined_chain = MiddlewareChain.combine(
           Lepus.config.producer_middleware_chain,
@@ -106,7 +109,9 @@ module Lepus
         )
 
         combined_chain.execute(message) do |msg|
-          publisher(connection).publish(msg.payload, **msg.to_publish_options)
+          opts = msg.to_publish_options
+          opts[:delay] = delay if delay
+          publisher(connection).publish(msg.payload, **opts)
         end
       end
 

data/lib/lepus/producers/definition.rb

@@ -4,7 +4,7 @@ module Lepus
   module Producers
     # Definition class for producer-specific settings
     class Definition
-      attr_reader :publish_options, :connection
+      attr_reader :publish_options, :connection, :delay_values
 
       def initialize(options = {})
         opts = Lepus::Primitive::Hash.new(options).deep_symbolize_keys
@@ -18,6 +18,8 @@ module Lepus
 
         @connection = (opts.delete(:connection) || Lepus::Configuration::DEFAULT_CONNECTION).to_sym
 
+        @delay_values = Lepus::Delay.normalize_all(opts.delete(:delays))
+
         # Store any remaining options for future use
         @options = opts
       end

data/lib/lepus/publisher.rb

@@ -27,6 +27,11 @@ module Lepus
     # @return [Symbol] the named connection this publisher uses
     attr_reader :connection
 
+    # @param message [String, Hash] The message to publish.
+    # @param options [Hash] Publish options. Accepts +delay:+ in milliseconds (or anything responding
+    #   to +in_milliseconds+) to deliver the message later. On the default exchange the +routing_key+
+    #   is the queue that receives the delayed message.
+    # @return [void]
     def publish(message, **options)
       return unless Producers.exchange_enabled?(exchange_name)
 
@@ -41,14 +46,19 @@ module Lepus
     # @param [String, Hash] message The message to publish.
     # @param [Hash] options Additional options for the publish.
     # @return [void]
-    def channel_publish(channel, message, **options)
+    def channel_publish(channel, message, delay: nil, **options)
       raise ArgumentError, "channel is required" unless channel
       return unless Producers.exchange_enabled?(exchange_name)
 
+      delay = Delay.normalize(delay) if delay
       payload, opts = prepare_message(message, **options)
       exchange = channel.exchange(exchange_name, exchange_options)
-      Lepus.instrument(:publish, exchange: exchange_name, routing_key: opts[:routing_key]) do
-        exchange.publish(payload, opts)
+      Lepus.instrument(:publish, exchange: exchange_name, routing_key: opts[:routing_key], delay: delay) do
+        if delay
+          delayed_publish(channel, payload, delay, opts)
+        else
+          exchange.publish(payload, opts)
+        end
       end
     end
 
@@ -56,6 +66,22 @@ module Lepus
 
     attr_reader :exchange_name, :exchange_options
 
+    def delayed_publish(channel, payload, delay, opts)
+      opts = opts.dup
+      routing_key = opts.delete(:routing_key)
+
+      if exchange_name == Delay::DEFAULT_EXCHANGE
+        raise ArgumentError, "routing_key (the target queue) is required to delay through the default exchange" unless routing_key
+
+        delay_queue = Delay.declare_for_queue!(channel, routing_key, delay)
+        channel.basic_publish(payload, Delay::DEFAULT_EXCHANGE, delay_queue, opts)
+      else
+        delayed_exchange = Delay.declare_for_exchange!(channel, exchange_name, delay)
+        opts[:headers] = (opts[:headers] || {}).merge(Delay::HEADER => delay)
+        channel.basic_publish(payload, delayed_exchange, routing_key, opts)
+      end
+    end
+
     def prepare_message(message, **options)
       opts = DEFAULT_PUBLISH_OPTIONS.merge(options)
       payload = if message.is_a?(String)

data/lib/lepus/testing/rspec_matchers.rb

@@ -10,6 +10,7 @@ module Lepus
           @expected_exchange = nil
           @expected_routing_key = nil
           @expected_payload = nil
+          @expected_delay = nil
         end
 
         # Support block expectations
@@ -37,7 +38,7 @@ module Lepus
             return false
           end
 
-          matches_count? && matches_exchange? && matches_routing_key? && matches_payload?
+          matches_count? && matches_exchange? && matches_routing_key? && matches_payload? && matches_delay?
         end
 
         def failure_message
@@ -59,6 +60,11 @@ module Lepus
             message += " with payload matching #{@expected_payload} (#{matching_payload} matched)"
           end
 
+          if @expected_delay
+            matching_delay = get_recent_messages(@published_count).count { |msg| msg[:delay] == @expected_delay }
+            message += " with delay #{@expected_delay}ms (#{matching_delay} matched)"
+          end
+
           message
         end
 
@@ -86,6 +92,11 @@ module Lepus
           self
         end
 
+        def with_delay(delay)
+          @expected_delay = Lepus::Delay.normalize(delay)
+          self
+        end
+
         private
 
         def expected_description
@@ -93,6 +104,7 @@ module Lepus
           desc += " to exchange '#{@expected_exchange}'" if @expected_exchange
           desc += " with routing key '#{@expected_routing_key}'" if @expected_routing_key
           desc += " with payload matching #{@expected_payload}" if @expected_payload
+          desc += " with delay #{@expected_delay}ms" if @expected_delay
           desc
         end
 
@@ -140,6 +152,13 @@ module Lepus
           recent_messages.any? { |msg| payload_matcher.matches?(msg[:payload]) }
         end
 
+        def matches_delay?
+          return true unless @expected_delay
+          return false if @published_count == 0
+
+          get_recent_messages(@published_count).any? { |msg| msg[:delay] == @expected_delay }
+        end
+
         def count_all_messages
           Lepus::Testing::Exchange.all.values.sum(&:size)
         end

data/lib/lepus/testing.rb

@@ -194,6 +194,8 @@ module Lepus
               payload: message, # Store the original message, not the JSON string
               routing_key: opts[:routing_key],
               headers: opts[:headers],
+              delay: opts[:delay] && Lepus::Delay.normalize(opts[:delay]),
+              expiration: opts[:expiration],
               persistent: opts[:persistent],
               mandatory: opts[:mandatory],
               immediate: opts[:immediate],

data/lib/lepus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lepus
-  VERSION = "0.2.2"
+  VERSION = "0.3.0"
 end

data/lib/lepus/web/api.rb

@@ -3,6 +3,10 @@
 module Lepus
   module Web
     class API
+      POLL_INTERVALS = [0, 2, 5, 15, 60].freeze
+      DEFAULT_POLL_INTERVAL = 5
+      HISTORY_AGES = {600 => 10, 3600 => 60}.freeze
+
       def initialize(aggregator: nil, management_api: nil)
         @aggregator = aggregator
         @management_api = management_api
@@ -21,6 +25,12 @@ module Lepus
           connections_data
         when "/exchanges"
           exchanges_data
+        when "/topology"
+          topology_data
+        when "/overview"
+          overview_data(req)
+        when "/meta"
+          meta_data
         else
           Web::RespondWith.json(template: :not_found)
         end
@@ -83,6 +93,40 @@ module Lepus
         Web::RespondWith.json(template: :ok, body: [])
       end
 
+      def topology_data
+        topology = Topology.new(
+          management_api: management_api,
+          aggregator: aggregator,
+          show_all_exchanges: Lepus.config.web_show_all_exchanges
+        )
+        Web::RespondWith.json(template: :ok, body: topology.to_h)
+      end
+
+      def overview_data(req)
+        return Web::RespondWith.json(template: :ok, body: {management: false}) unless management_api
+
+        age = req.params["age"].to_i
+        age = HISTORY_AGES.keys.first unless HISTORY_AGES.key?(age)
+        payload = management_api.overview(age: age, increment: HISTORY_AGES[age])
+        Web::RespondWith.json(template: :ok, body: payload.merge(management: true, age: age))
+      rescue => e
+        Lepus.logger.warn("[Web::API] Failed to fetch overview: #{e.message}")
+        Web::RespondWith.json(template: :ok, body: {management: false, error: ManagementAPI.client_message(e)})
+      end
+
+      def meta_data
+        config = Lepus.config
+        Web::RespondWith.json(template: :ok, body: {
+          version: Lepus::VERSION,
+          heartbeat_interval: config.process_heartbeat_interval,
+          alive_threshold: config.process_alive_threshold,
+          poll_interval: DEFAULT_POLL_INTERVAL,
+          poll_intervals: POLL_INTERVALS,
+          history_ages: HISTORY_AGES.keys,
+          show_all_exchanges: config.web_show_all_exchanges ? true : false
+        })
+      end
+
       def annotate_queues_with_apps(queues)
         return queues unless aggregator&.running?
 
@@ -102,6 +146,7 @@ module Lepus
         known_exchanges = build_known_exchange_names
         return exchanges if known_exchanges.empty?
 
+        known_exchanges += known_exchanges.map { |name| Delay.exchange_name_for(name) }
         exchanges.select { |e| known_exchanges.include?(e[:name]) }
       end