lepus 0.0.1.beta2 → 0.1.0

data/lib/lepus/producers/definition.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Producers
+    # Definition class for producer-specific settings
+    class Definition
+      attr_reader :publish_options
+
+      def initialize(options = {})
+        opts = Lepus::Primitive::Hash.new(options).deep_symbolize_keys
+
+        # Handle exchange configuration
+        exchange_config = opts.delete(:exchange) || {}
+        @exchange_options = Lepus::Publisher::DEFAULT_EXCHANGE_OPTIONS.merge(declaration_config(exchange_config))
+
+        # Handle default publish options
+        @publish_options = Lepus::Publisher::DEFAULT_PUBLISH_OPTIONS.merge(opts.delete(:publish) || {})
+
+        # Store any remaining options for future use
+        @options = opts
+      end
+
+      def exchange_name
+        @exchange_options[:name] || raise(InvalidProducerConfigError, "Exchange name is required")
+      end
+
+      def exchange_options
+        @exchange_options.reject { |k, v| k == :name }
+      end
+
+      private
+
+      # Normalizes a declaration config (for exchanges) 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

data/lib/lepus/producers/hooks.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Producers
+    module Hooks
+      KEY = :lepus_producers
+
+      def self.reset!
+        Thread.current[KEY] = nil
+      end
+
+      # Global enable publishing callbacks. If no producer/exchange is specified, all producers will be enabled.
+      # @param targets [Array<Lepus::Producer, String, Symbol>] Producer classes, exchange names, or both
+      # @return [void]
+      def enable!(*targets)
+        if targets.empty?
+          # Enable all producers
+          all_producers.each { |producer| repo[:producers][producer] = true }
+        else
+          targets.each do |target|
+            case target
+            when Class
+              ensure_producer_class(target)
+              repo[:producers][target] = true
+            when String, Symbol
+              exchange_name = target.to_s
+              repo[:exchanges][exchange_name] = true
+            else
+              raise ArgumentError, "Invalid producer or exchange name: #{target.inspect}"
+            end
+          end
+        end
+      end
+
+      # Global disable publishing callbacks. If no producer/exchange is specified, all producers will be disabled.
+      # @param targets [Array<Lepus::Producer, String, Symbol>] Producer classes, exchange names, or both
+      # @return [void]
+      def disable!(*targets)
+        if targets.empty?
+          # Disable all producers
+          all_producers.each { |producer| repo[:producers][producer] = false }
+        else
+          targets.each do |target|
+            case target
+            when Class
+              ensure_producer_class(target)
+              repo[:producers][target] = false
+            when String, Symbol
+              exchange_name = target.to_s
+              repo[:exchanges][exchange_name] = false
+            else
+              raise ArgumentError, "Invalid producer or exchange name: #{target.inspect}"
+            end
+          end
+        end
+      end
+
+      # Check if the given producer is enabled for publishing. If no producer is specified, all producers will be checked.
+      #
+      # @param producers [Array<Lepus::Producer>]
+      # @return [Boolean]
+      def disabled?(*producers)
+        if producers.empty?
+          all_producers.all? { |producer| !producer_enabled?(producer) }
+        else
+          producers.all? { |producer| !producer_enabled?(producer) }
+        end
+      end
+
+      # Check if the given producer is enabled for publishing. If no producer is specified, all producers will be checked.
+      #
+      # @param producers [Array<Lepus::Producer>]
+      # @return [Boolean]
+      def enabled?(*producers)
+        if producers.empty?
+          all_producers.all? { |producer| producer_enabled?(producer) }
+        else
+          producers.all? { |producer| producer_enabled?(producer) }
+        end
+      end
+
+      # Check if the given exchange is enabled for publishing.
+      #
+      # @param exchange_name [String] The exchange name to check
+      # @return [Boolean]
+      def exchange_enabled?(exchange_name)
+        # Check if exchange is explicitly configured
+        if repo[:exchanges].key?(exchange_name)
+          return repo[:exchanges][exchange_name]
+        end
+
+        # Find all producers that use this exchange
+        matching_producers = all_producers.select do |producer|
+          producer.definition&.exchange_name == exchange_name
+        end
+
+        # If no producers use this exchange, consider it enabled by default
+        return true if matching_producers.empty?
+
+        # Check if all matching producers are enabled
+        matching_producers.all? { |producer| producer_enabled?(producer) }
+      end
+
+      # Disable publishing callbacks execution for the block execution.
+      # Example:
+      #  Lepus::Producers.without_publishing { User.create! }
+      #  Lepus::Producers.without_publishing(UsersIndex, "exchange_name") { User.create! }
+      def without_publishing(*targets)
+        state_before_disable = deep_copy_repo
+        disable!(*targets)
+
+        yield
+      ensure
+        restore_repo(state_before_disable)
+      end
+
+      # Enable the publishing callbacks execution for the block execution.
+      # Example:
+      #  Lepus::Producers.with_publishing { User.create! }
+      #  Lepus::Producers.with_publishing(UsersIndex, "exchange_name") { User.create! }
+      def with_publishing(*targets)
+        state_before_enable = deep_copy_repo
+        enable!(*targets)
+
+        yield
+      ensure
+        restore_repo(state_before_enable)
+      end
+
+      private
+
+      def all_producers
+        Lepus::Producer.descendants.reject(&:abstract_class?)
+      end
+
+      # Check if a specific producer is enabled
+      def producer_enabled?(producer)
+        repo[:producers][producer]
+      end
+
+      def ensure_producer_class(value)
+        (value <= Lepus::Producer) ? value : raise(ArgumentError, "Invalid producer class: #{value.inspect}")
+      end
+
+      def deep_copy_repo
+        {
+          producers: repo[:producers].dup,
+          exchanges: repo[:exchanges].dup
+        }
+      end
+
+      def restore_repo(saved_state)
+        Thread.current[KEY] = saved_state
+      end
+
+      # Data Structure:
+      #
+      # {
+      #   producers: { <Lepus::Producer class> => <true|false>, ... },
+      #   exchanges: { <String> => <true|false>, ... }
+      # }
+      def repo
+        Thread.current[KEY] ||= {
+          producers: all_producers.map { |k| [k, true] }.to_h,
+          exchanges: {}
+        }
+      end
+    end
+  end
+end

data/lib/lepus/producers/middleware_chain.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Producers
+    # Manages middleware registration and execution for producers.
+    # Middlewares can modify the message (payload, headers, routing_key, etc.)
+    # before it is published to RabbitMQ.
+    class MiddlewareChain < Lepus::MiddlewareChain
+      private
+
+      def load_middleware(name, opts)
+        require_relative "middlewares/#{name}"
+        class_name = Primitive::String.new(name.to_s).classify
+        class_name = "JSON" if class_name == "Json"
+        klass = Lepus::Producers::Middlewares.const_get(class_name)
+        klass.new(**opts)
+      rescue LoadError, NameError => e
+        raise ArgumentError, "Producer middleware '#{name}' not found: #{e.message}"
+      end
+    end
+  end
+end

data/lib/lepus/producers/middlewares/correlation_id.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Producers
+    module Middlewares
+      # A middleware that auto-generates a correlation_id if missing.
+      class CorrelationId < Lepus::Middleware
+        # @param opts [Hash] The options for the middleware.
+        # @option opts [Proc, nil] :generator A custom generator proc.
+        #   Defaults to SecureRandom.uuid.
+        def initialize(**opts)
+          super
+          @generator = opts.fetch(:generator, -> { SecureRandom.uuid })
+        end
+
+        def call(message, app)
+          if message.metadata&.correlation_id.nil? || message.metadata.correlation_id.to_s.empty?
+            correlation_id = generator.respond_to?(:call) ? generator.call : generator.to_s
+            new_metadata = update_metadata(message.metadata, correlation_id: correlation_id)
+            message = message.mutate(metadata: new_metadata)
+          end
+
+          app.call(message)
+        end
+
+        private
+
+        attr_reader :generator
+
+        def update_metadata(metadata, **attrs)
+          current = metadata&.to_h || {}
+          Message::Metadata.new(**current.merge(attrs))
+        end
+      end
+    end
+  end
+end

data/lib/lepus/producers/middlewares/header.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Producers
+    module Middlewares
+      # A middleware that adds default headers to messages.
+      # Headers can be static values or dynamic procs.
+      class Header < Lepus::Middleware
+        # @param opts [Hash] The options for the middleware.
+        # @option opts [Hash] :defaults ({}) Default headers to add.
+        #   Values can be Procs that will be called with the message.
+        def initialize(**opts)
+          super
+          @defaults = opts.fetch(:defaults, {})
+        end
+
+        def call(message, app)
+          new_headers = resolve_headers(message)
+          existing_headers = message.metadata&.headers || {}
+          merged_headers = new_headers.merge(existing_headers)
+
+          new_metadata = update_metadata(message.metadata, headers: merged_headers)
+          app.call(message.mutate(metadata: new_metadata))
+        end
+
+        private
+
+        attr_reader :defaults
+
+        def resolve_headers(message)
+          defaults.each_with_object({}) do |(key, value), headers|
+            headers[key.to_s] = if value.respond_to?(:call)
+              (value.arity == 0) ? value.call : value.call(message)
+            else
+              value
+            end
+          end
+        end
+
+        def update_metadata(metadata, **attrs)
+          current = metadata&.to_h || {}
+          Message::Metadata.new(**current.merge(attrs))
+        end
+      end
+    end
+  end
+end

data/lib/lepus/producers/middlewares/instrumentation.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Producers
+    module Middlewares
+      # A middleware that emits instrumentation events via Lepus.instrument.
+      class Instrumentation < Lepus::Middleware
+        # @param opts [Hash] The options for the middleware.
+        # @option opts [String] :event_name ("publish") The event name suffix.
+        def initialize(**opts)
+          super
+          @event_name = opts.fetch(:event_name, "publish")
+        end
+
+        def call(message, app)
+          exchange = message.delivery_info&.exchange
+          routing_key = message.delivery_info&.routing_key
+
+          Lepus.instrument(event_name, exchange: exchange, routing_key: routing_key, message: message) do
+            app.call(message)
+          end
+        end
+
+        private
+
+        attr_reader :event_name
+      end
+    end
+  end
+end

data/lib/lepus/producers/middlewares/json.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "multi_json"
+
+module Lepus
+  module Producers
+    module Middlewares
+      # A middleware that serializes Hash payloads to JSON and sets the content_type.
+      class JSON < Lepus::Middleware
+        # @param opts [Hash] The options for the middleware.
+        # @option opts [Boolean] :only_hash (true) Only serialize Hash payloads.
+        def initialize(**opts)
+          super
+          @only_hash = opts.fetch(:only_hash, true)
+        end
+
+        def call(message, app)
+          payload = message.payload
+
+          if should_serialize?(payload)
+            serialized_payload = MultiJson.dump(payload)
+            new_metadata = update_metadata(message.metadata, content_type: "application/json")
+            message = message.mutate(payload: serialized_payload, metadata: new_metadata)
+          end
+
+          app.call(message)
+        end
+
+        private
+
+        attr_reader :only_hash
+
+        def should_serialize?(payload)
+          return false if payload.is_a?(String)
+          return payload.is_a?(Hash) if only_hash
+
+          true
+        end
+
+        def update_metadata(metadata, **attrs)
+          current = metadata&.to_h || {}
+          Message::Metadata.new(**current.merge(attrs))
+        end
+      end
+    end
+  end
+end

data/lib/lepus/producers/middlewares/unique.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Producers
+    module Middlewares
+      # A middleware that prevents duplicate messages from being published
+      # using the de-dupe gem for Redis-based distributed locking.
+      #
+      # When a lock is acquired, the middleware adds x-dedupe-lock-key and
+      # x-dedupe-lock-id headers to the message so that a consumer middleware
+      # can release the lock after successful processing.
+      #
+      # @example
+      #   class StoryCreatedProducer < Lepus::Producer
+      #     configure(exchange: "story_created")
+      #     use :unique, lock_key: "story", lock_id: ->(msg) { msg.payload[:story_id].to_s }
+      #   end
+      class Unique < Lepus::Middleware
+        HEADER_LOCK_KEY = "x-dedupe-lock-key"
+        HEADER_LOCK_ID = "x-dedupe-lock-id"
+        HEADER_LOCK_TTL = "x-dedupe-lock-ttl"
+
+        # @param lock_key [String] Shared lock namespace (e.g., "story").
+        # @param lock_id [Proc] Callable that extracts a unique ID from the message.
+        # @param ttl [Integer, nil] Lock TTL in seconds. Defaults to DeDupe configuration.
+        def initialize(lock_key:, lock_id:, ttl: nil)
+          super()
+          @lock_key = lock_key
+          @lock_id = lock_id
+          @ttl = ttl
+        end
+
+        def call(message, app)
+          id = @lock_id.call(message)
+          return app.call(message) if id.nil?
+
+          lock_opts = {}
+          lock_opts[:ttl] = @ttl if @ttl
+          lock = DeDupe::Lock.new(lock_key: @lock_key, lock_id: id.to_s, **lock_opts)
+          return unless lock.acquire
+
+          message = add_dedupe_headers(message, id)
+          app.call(message)
+        end
+
+        private
+
+        def add_dedupe_headers(message, lock_id)
+          existing_headers = message.metadata&.headers || {}
+          new_headers = existing_headers.merge(
+            HEADER_LOCK_KEY => @lock_key,
+            HEADER_LOCK_ID => lock_id.to_s
+          )
+          new_headers[HEADER_LOCK_TTL] = @ttl if @ttl
+
+          new_metadata = update_metadata(message.metadata, headers: new_headers)
+          message.mutate(metadata: new_metadata)
+        end
+
+        def update_metadata(metadata, **attrs)
+          current = metadata&.to_h || {}
+          Message::Metadata.new(**current.merge(attrs))
+        end
+      end
+    end
+  end
+end

data/lib/lepus/producers.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Lepus
+  module Producers
+    extend Hooks
+  end
+end

data/lib/lepus/prometheus/collector.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# This file is intended to be loaded by the prometheus_exporter server:
+#
+#   prometheus_exporter -a lepus/prometheus/collector
+#
+# It intentionally avoids requiring the rest of the Lepus gem so it can
+# run standalone inside the exporter process. When Lepus is loaded in the
+# same process, latency buckets fall back to Lepus.config.prometheus_buckets.
+
+require "prometheus_exporter"
+require "prometheus_exporter/server"
+
+module Lepus
+  module Prometheus
+    class Collector < ::PrometheusExporter::Server::TypeCollector
+      DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10].freeze
+
+      def initialize
+        @metrics = {}
+      end
+
+      def type
+        "lepus"
+      end
+
+      def metrics
+        @metrics.values
+      end
+
+      def collect(obj)
+        case obj["metric"]
+        when "delivery" then collect_delivery(obj)
+        when "publish" then collect_publish(obj)
+        when "process" then collect_process(obj)
+        when "process_info" then collect_process_info(obj)
+        when "queue" then collect_queue(obj)
+        when "queue_poll" then collect_queue_poll(obj)
+        when "queue_poll_error" then collect_queue_poll_error(obj)
+        end
+      end
+
+      private
+
+      def collect_delivery(obj)
+        labels = {
+          consumer: obj["consumer"],
+          queue: obj["queue"],
+          result: obj["result"],
+          error: obj["error"].to_s
+        }
+        counter(
+          "lepus_messages_processed_total",
+          "Total messages delivered to Lepus consumers, labeled by result and error class."
+        ).observe(1, labels)
+
+        duration = obj["duration"].to_f
+        histogram(
+          "lepus_delivery_duration_seconds",
+          "Time spent processing a single Lepus message.",
+          buckets
+        ).observe(duration, consumer: obj["consumer"], queue: obj["queue"])
+      end
+
+      def collect_publish(obj)
+        counter(
+          "lepus_messages_published_total",
+          "Total messages published through Lepus producers."
+        ).observe(1, exchange: obj["exchange"], routing_key: obj["routing_key"])
+
+        duration = obj["duration"].to_f
+        histogram(
+          "lepus_publish_duration_seconds",
+          "Time spent publishing a single Lepus message.",
+          buckets
+        ).observe(duration, exchange: obj["exchange"], routing_key: obj["routing_key"])
+      end
+
+      def collect_process(obj)
+        labels = {kind: obj["kind"], name: obj["name"]}
+        gauge(
+          "lepus_process_rss_memory_bytes",
+          "Resident-set memory of a Lepus process."
+        ).observe(obj["rss_memory"].to_f, labels)
+      end
+
+      def collect_process_info(obj)
+        labels = {
+          kind: obj["kind"],
+          name: obj["name"],
+          pid: obj["pid"].to_s,
+          hostname: obj["hostname"].to_s
+        }
+        gauge(
+          "lepus_process_info",
+          "Info gauge for a Lepus process (always 1); use for joining pid/hostname labels."
+        ).observe(1, labels)
+      end
+
+      def collect_queue(obj)
+        labels = {name: obj["name"]}
+        gauge("lepus_queue_messages", "Total messages in a RabbitMQ queue.")
+          .observe(obj["messages"].to_f, labels)
+        gauge("lepus_queue_messages_ready", "Messages ready for delivery in a RabbitMQ queue.")
+          .observe(obj["messages_ready"].to_f, labels)
+        gauge("lepus_queue_messages_unacknowledged", "Unacknowledged messages in a RabbitMQ queue.")
+          .observe(obj["messages_unacknowledged"].to_f, labels)
+        gauge("lepus_queue_consumers", "Number of consumers attached to a RabbitMQ queue.")
+          .observe(obj["consumers"].to_f, labels)
+        gauge("lepus_queue_memory_bytes", "Memory used by a RabbitMQ queue.")
+          .observe(obj["memory"].to_f, labels)
+      end
+
+      def collect_queue_poll(obj)
+        gauge(
+          "lepus_queue_poll_last_success_timestamp_seconds",
+          "Unix timestamp of the last successful RabbitMQ management API poll."
+        ).observe(obj["timestamp"].to_f, {})
+      end
+
+      def collect_queue_poll_error(obj)
+        counter(
+          "lepus_queue_poll_errors_total",
+          "Total errors encountered while polling the RabbitMQ management API, labeled by error class."
+        ).observe(1, error: obj["error"].to_s)
+      end
+
+      def counter(name, help)
+        @metrics[name] ||= ::PrometheusExporter::Metric::Counter.new(name, help)
+      end
+
+      def gauge(name, help)
+        @metrics[name] ||= ::PrometheusExporter::Metric::Gauge.new(name, help)
+      end
+
+      def histogram(name, help, buckets)
+        @metrics[name] ||= ::PrometheusExporter::Metric::Histogram.new(name, help, buckets: buckets)
+      end
+
+      def buckets
+        if defined?(::Lepus) && ::Lepus.respond_to?(:config) && ::Lepus.config.respond_to?(:prometheus_buckets)
+          ::Lepus.config.prometheus_buckets
+        else
+          DEFAULT_BUCKETS
+        end
+      end
+    end
+  end
+end