lepus 0.0.1.beta2 → 0.1.0

data/lib/lepus/prometheus/instrumentation.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "socket"
+
+module Lepus
+  module Prometheus
+    # Hooks that run inside each Lepus process and forward metrics to the
+    # prometheus_exporter server via Lepus::Prometheus.emit.
+    module Instrumentation
+      # Tracks per-delivery outcomes and latency. Always emits a metric, even
+      # when the underlying consumer raises, so error rates are observable.
+      module HandlerExtensions
+        def process_delivery(delivery_info, metadata, payload)
+          start = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+          result = nil
+          error_class = nil
+          begin
+            result = super
+          rescue => e
+            error_class = e.class.name
+            raise
+          ensure
+            Lepus::Prometheus.emit(
+              :delivery,
+              consumer: @consumer_class.name,
+              queue: queue_name_for_metric,
+              result: error_class ? "error" : result.to_s,
+              error: error_class.to_s,
+              duration: ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) - start
+            )
+          end
+          result
+        end
+
+        private
+
+        def queue_name_for_metric
+          q = queue
+          q.respond_to?(:name) ? q.name : q.to_s
+        rescue
+          ""
+        end
+      end
+
+      # Emits process-level gauges on each heartbeat tick. rss_memory is keyed
+      # on (kind, name) only to avoid leaking a new series per pid; pid and
+      # hostname stay available on the `lepus_process_info` info gauge.
+      module WorkerExtensions
+        def heartbeat
+          super
+        ensure
+          Lepus::Prometheus.emit(
+            :process,
+            kind: kind.to_s,
+            name: name,
+            rss_memory: safe_rss_memory_bytes
+          )
+          Lepus::Prometheus.emit(
+            :process_info,
+            kind: kind.to_s,
+            name: name,
+            pid: pid.to_s,
+            hostname: safe_hostname
+          )
+        end
+
+        private
+
+        def safe_rss_memory_bytes
+          Lepus::Processes::MEMORY_GRABBER.call(pid) * 1024
+        rescue
+          0
+        end
+
+        def safe_hostname
+          Socket.gethostname
+        rescue
+          ""
+        end
+      end
+
+      # Periodic poller that turns RabbitMQ queue stats into gauge events.
+      # Runs in a single thread inside whichever process enabled it.
+      class QueuePoller
+        @thread = nil
+        @mutex = Mutex.new
+
+        class << self
+          def start(interval:, api:)
+            @mutex.synchronize do
+              stop_locked
+              @thread = Thread.new { run_loop(interval, api) }
+            end
+          end
+
+          def stop
+            @mutex.synchronize { stop_locked }
+          end
+
+          def running?
+            @mutex.synchronize { !@thread.nil? && @thread.alive? }
+          end
+
+          private
+
+          def stop_locked
+            @thread&.kill
+            @thread = nil
+          end
+
+          def run_loop(interval, api)
+            loop do
+              poll_once(api)
+              sleep interval
+            end
+          end
+
+          def poll_once(api)
+            api.queues.each do |q|
+              Lepus::Prometheus.emit(
+                :queue,
+                name: q[:name],
+                messages: q[:messages].to_i,
+                messages_ready: q[:messages_ready].to_i,
+                messages_unacknowledged: q[:messages_unacknowledged].to_i,
+                consumers: q[:consumers].to_i,
+                memory: q[:memory].to_i
+              )
+            end
+            Lepus::Prometheus.emit(:queue_poll, timestamp: Time.now.to_f)
+          rescue => e
+            Lepus::Prometheus.emit(:queue_poll_error, error: e.class.name)
+            Lepus.logger.warn("[Lepus::Prometheus] queue poll failed: #{e.message}")
+          end
+        end
+      end
+
+      class << self
+        def install!
+          return if @installed
+
+          Lepus::Consumers::Handler.prepend(HandlerExtensions)
+          Lepus::Consumers::Worker.prepend(WorkerExtensions)
+          subscribe_publish_events
+          @installed = true
+        end
+
+        private
+
+        def subscribe_publish_events
+          return unless defined?(ActiveSupport::Notifications)
+
+          ActiveSupport::Notifications.subscribe(/\Apublish\.lepus\z/) do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            Lepus::Prometheus.emit(
+              :publish,
+              exchange: event.payload[:exchange].to_s,
+              routing_key: event.payload[:routing_key].to_s,
+              duration: event.duration / 1000.0
+            )
+          end
+        end
+      end
+    end
+  end
+end
+
+Lepus::Prometheus::Instrumentation.install!

data/lib/lepus/prometheus.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "prometheus_exporter"
+require "prometheus_exporter/client"
+
+require_relative "prometheus/instrumentation"
+
+module Lepus
+  # Optional integration with the prometheus_exporter gem.
+  # Require "lepus/prometheus" in your Lepus process to start shipping
+  # metrics to a running prometheus_exporter server via the default client.
+  #
+  # On the prometheus_exporter server side, load the companion collector:
+  #   prometheus_exporter -a lepus/prometheus/collector
+  module Prometheus
+    DEFAULT_QUEUE_POLL_INTERVAL = 30
+
+    class << self
+      attr_writer :client
+
+      def client
+        @client ||= ::PrometheusExporter::Client.default
+      end
+
+      # Emit an opaque metric payload to the exporter server.
+      # Silently swallows transport errors so instrumentation cannot
+      # break the caller; non-transport bugs surface as debug logs.
+      def emit(metric, **data)
+        client.send_json(type: "lepus", metric: metric.to_s, **data)
+      rescue => e
+        Lepus.logger.debug { "[Lepus::Prometheus] emit(#{metric}) failed: #{e.class}: #{e.message}" }
+        nil
+      end
+
+      # Start polling the RabbitMQ management API for queue-level gauges.
+      # Safe to call once per process. Requires "lepus/web/management_api".
+      def watch_queues(interval: DEFAULT_QUEUE_POLL_INTERVAL, api: nil)
+        require "lepus/web/management_api"
+        api ||= Lepus::Web::ManagementAPI.new
+        Instrumentation::QueuePoller.start(interval: interval, api: api)
+      end
+
+      def stop_watching_queues
+        Instrumentation::QueuePoller.stop
+      end
+    end
+  end
+end

data/lib/lepus/publisher.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "multi_json"
+
+module Lepus
+  class Publisher
+    DEFAULT_EXCHANGE_OPTIONS = {
+      type: :topic,
+      durable: true,
+      auto_delete: false
+    }.freeze
+
+    DEFAULT_PUBLISH_OPTIONS = {
+      persistent: true
+    }.freeze
+
+    # @param exchange_name [String] The name of the exchange to publish messages to.
+    # @param options [Hash] Additional options for the exchange (type, durable, auto_delete).
+    # @return [void]
+    def initialize(exchange_name, **options)
+      @exchange_name = exchange_name
+      @exchange_options = DEFAULT_EXCHANGE_OPTIONS.merge(options)
+    end
+
+    def publish(message, **options)
+      return unless Producers.exchange_enabled?(exchange_name)
+
+      Lepus.config.producer_config.with_connection do |connection|
+        connection.with_channel do |channel|
+          channel_publish(channel, message, **options)
+        end
+      end
+    end
+
+    # @param [Bunny::Channel] channel The channel to publish the message to.
+    # @param [String, Hash] message The message to publish.
+    # @param [Hash] options Additional options for the publish.
+    # @return [void]
+    def channel_publish(channel, message, **options)
+      raise ArgumentError, "channel is required" unless channel
+      return unless Producers.exchange_enabled?(exchange_name)
+
+      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)
+      end
+    end
+
+    private
+
+    attr_reader :exchange_name, :exchange_options
+
+    def prepare_message(message, **options)
+      opts = DEFAULT_PUBLISH_OPTIONS.merge(options)
+      payload = if message.is_a?(String)
+        opts[:content_type] ||= "text/plain"
+        message
+      else
+        opts[:content_type] ||= "application/json"
+        MultiJson.dump(message)
+      end
+
+      [payload, opts]
+    end
+  end
+end

data/lib/lepus/supervisor/children_pipes.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Lepus
+  class Supervisor < Processes::Base
+    module ChildrenPipes
+      def self.included(base)
+        base.send :include, InstanceMethods
+        base.class_eval do
+          after_shutdown :close_pipes
+        end
+      end
+
+      module InstanceMethods
+        private
+
+        def close_pipes
+          pipes.each_value do |pipe|
+            pipe.close if pipe && !pipe.closed?
+          end
+          @pipes = {}
+        end
+      end
+    end
+  end
+end

data/lib/lepus/supervisor/lifecycle_hooks.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Lepus
+  class Supervisor < Processes::Base
+    module LifecycleHooks
+      def self.included(base)
+        base.extend ClassMethods
+        base.send :include, InstanceMethods
+        base.instance_variable_set(:@lifecycle_hooks, {start: [], stop: []})
+      end
+
+      module ClassMethods
+        attr_reader :lifecycle_hooks
+
+        def on_start(&block)
+          lifecycle_hooks[:start] << block
+        end
+
+        def on_stop(&block)
+          lifecycle_hooks[:stop] << block
+        end
+
+        def clear_hooks
+          lifecycle_hooks[:start] = []
+          lifecycle_hooks[:stop] = []
+        end
+      end
+
+      module InstanceMethods
+        private
+
+        def run_start_hooks
+          run_hooks_for :start
+        end
+
+        def run_stop_hooks
+          run_hooks_for :stop
+        end
+
+        def run_hooks_for(event)
+          self.class.lifecycle_hooks.fetch(event, []).each do |block|
+            block.call
+          rescue Exception => exception # rubocop:disable Lint/RescueException
+            handle_thread_error(exception)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lepus/supervisor/pidfiled.rb

@@ -15,7 +15,7 @@ module Lepus
         private
 
         def setup_pidfile
-          if (path = configuration.pidfile)
+          if (path = pidfile_path)
             @pidfile = Pidfile.new(path).tap(&:setup)
           end
         end

data/lib/lepus/supervisor/registry_cleaner.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Lepus
+  class Supervisor < Processes::Base
+    module RegistryCleaner
+      def self.included(base)
+        base.send :include, InstanceMethods
+        base.class_eval do
+          after_shutdown :cleanup_registry
+        end
+      end
+
+      module InstanceMethods
+        private
+
+        def cleanup_registry
+          ProcessRegistry.stop
+        end
+      end
+    end
+  end
+end

data/lib/lepus/supervisor.rb

@@ -2,24 +2,38 @@
 
 module Lepus
   class Supervisor < Processes::Base
+    SHUTDOWN_MSG = "shutdown"
+
     include LifecycleHooks
+    include ChildrenPipes
     include Maintenance
     include Signals
     include Pidfiled
+    include RegistryCleaner
 
     class << self
       def start(**options)
-        # Lepus.config.supervisor = true
-        config = Config.new(**options)
-        new(config).tap(&:start)
+        new(**options).tap(&:start)
       end
     end
 
-    def initialize(configuration)
-      @configuration = configuration
+    # @param require_file [String, nil] The file to require before loading consumers, typically the Rails environment file or similar.
+    # @param pidfile [String] The path to the pidfile where the supervisor's PID will be stored. Default is "tmp/pids/lepus.pid".
+    # @param shutdown_timeout [Integer] The timeout in seconds to wait for child processes to terminate gracefully before forcing termination. Default is 5 seconds.
+    # @param consumers [Array<String, Class>] An optional list of consumer class names (as strings or constants) to be run by this supervisor. If not provided, all discovered consumer classes will be used.
+    def initialize(require_file: nil, pidfile: "tmp/pids/lepus.pid", shutdown_timeout: 5, **kwargs)
+      @pidfile_path = pidfile
+      @require_file = require_file
+      @shutdown_timeout = shutdown_timeout.to_i
+      @consumer_class_names = Array(kwargs[:consumers]).map(&:to_s) if kwargs.key?(:consumers)
+
       @forks = {}
+      @pipes = {}
       @configured_processes = {}
-      ProcessRegistry.instance # Ensure the registry is initialized
+
+      super
+
+      @name ||= hostname
     end
 
     def start
@@ -27,7 +41,7 @@ module Lepus
 
       run_start_hooks
 
-      start_processes
+      build_and_start_workers
       launch_maintenance_task
 
       supervise
@@ -35,17 +49,43 @@ module Lepus
 
     def stop
       super
+
       run_stop_hooks
     end
 
     private
 
-    attr_reader :configuration, :forks, :configured_processes
+    # @return [String] The raw location of the pidfile used to store the supervisor's `#pidfile`.
+    attr_reader :pidfile_path
+
+    # @return [String] The file to require before loading consumers, typically the Rails environment file or similar.
+    attr_reader :require_file
+
+    # @return [Integer] The timeout in seconds to wait for child processes to terminate gracefully before forcing termination.
+    attr_reader :shutdown_timeout
+
+    # @return [Hash{Integer[pid] => Lepus::Consumers::Worker}] map of forked process IDs to their instances
+    attr_reader :forks
+
+    # @return [Hash{Integer[pid] => Lepus::Consumers::WorkerFactory}] map of forked process IDs to their immutable factory configurations
+    attr_reader :configured_processes
+
+    # @return [Hash{Integer[pid] => IO}] map of forked process IDs to their communication pipes
+    attr_reader :pipes
+
+    # @return [Array<Lepus::Consumer>] the full list of consumer classes to be run by this supervisor and its child processes.
+    def consumer_classes
+      @consumer_classes ||= if @consumer_class_names
+        @consumer_class_names.map { |name| Lepus::Primitive::String.new(name).constantize }
+      else
+        Lepus::Consumer.descendants
+      end.reject(&:abstract_class?)
+    end
 
     def boot
       Lepus.instrument(:start_process, process: self) do
-        if configuration.require_file
-          Kernel.require configuration.require_file
+        if require_file
+          Kernel.require(require_file)
         else
           begin
             require "rails"
@@ -56,6 +96,13 @@ module Lepus
           end
         end
 
+        # Start the registry *after* the host app is loaded. Mounting
+        # `Lepus::Web` in `routes.rb` (or any late `require "lepus/web"`) flips
+        # the default backend to :rabbitmq; starting the registry earlier
+        # would lock in the FileBackend and the later flip would point the
+        # registry at a backend that was never started.
+        ProcessRegistry.start
+
         setup_consumers
         check_bunny_connection
 
@@ -68,9 +115,24 @@ module Lepus
     def setup_consumers
       Lepus.eager_load_consumers!
 
-      if configuration.consumers.empty?
+      if consumer_classes.empty?
         abort "No consumers found. Exiting..."
       end
+
+      consumer_classes.each do |consumer_class|
+        if consumer_class.config.nil?
+          abort <<~MSG
+            Consumer class #{klass} is not configured. Please use the `configure' class method
+            to set at least the queue name.
+
+            Example:
+
+              class MyConsumer < Lepus::Consumer
+                configure queue: "my_queue"
+              end
+          MSG
+        end
+      end
     end
 
     def check_bunny_connection
@@ -78,9 +140,10 @@ module Lepus
       temp_bunny.close
     end
 
-    def start_processes
-      configuration.configured_processes.each do |configured_process|
-        start_process(configured_process)
+    def build_and_start_workers
+      consumer_classes.group_by { |klass| klass.config.worker_name }.map do |worker_name, classes|
+        frozen_factory = Lepus::Consumers::WorkerFactory.immutate_with(worker_name, consumers: classes)
+        start_process(frozen_factory)
       end
     end
 
@@ -92,6 +155,7 @@ module Lepus
         process_signal_queue
 
         unless stopped?
+          check_for_shutdown_messages
           reap_and_replace_terminated_forks
           interruptible_sleep(1)
         end
@@ -100,32 +164,40 @@ module Lepus
       shutdown
     end
 
-    def start_process(configured_process)
-      process_instance = configured_process.instantiate.tap do |instance|
-        instance.supervised_by process
-        instance.mode = :fork
-      end
+    def start_process(factory)
+      process_instance = factory.instantiate_process
+      process_instance.supervised_by(process)
+      process_instance.mode = :fork
 
+      reader, writer = IO.pipe
       process_instance.before_fork
       pid = fork do
-        process_instance.after_fork
-        process_instance.start
+        reader.close
+        begin
+          process_instance.after_fork
+          process_instance.start
+        rescue Lepus::ShutdownError
+          writer.puts(SHUTDOWN_MSG)
+          raise
+        ensure
+          writer.close
+        end
       end
 
-      configured_processes[pid] = configured_process
+      configured_processes[pid] = factory
       forks[pid] = process_instance
+      pipes[pid] = reader
     end
 
     def set_procline
-      procline "supervising #{supervised_processes.join(", ")}"
+      procline "#{kind.downcase}: supervising #{supervised_processes.join(", ")}"
     end
 
     def terminate_gracefully
       Lepus.instrument(:graceful_termination, process_id: process_id, supervisor_pid: ::Process.pid, supervised_processes: supervised_processes) do |payload|
         term_forks
 
-        shutdown_timeout = 5
-        puts "\nWaiting up to #{shutdown_timeout} seconds for processes to terminate gracefully..."
+        # puts "\nWaiting up to #{shutdown_timeout} seconds for processes to terminate gracefully..."
         Timer.wait_until(shutdown_timeout, -> { all_forks_terminated? }) do
           reap_terminated_forks
         end
@@ -167,6 +239,24 @@ module Lepus
       signal_processes(forks.keys, :QUIT)
     end
 
+    def check_for_shutdown_messages
+      open_pipes = pipes.values.reject(&:closed?)
+      return if open_pipes.empty?
+
+      # Check if any pipe has data available to read without blocking
+      ready_pipes, = IO.select(open_pipes, nil, nil, 0)
+      return unless ready_pipes
+
+      ready_pipes.each do |pipe|
+        message = pipe.gets&.chomp
+        initiate_shutdown_sequence_from_child(pipe) if message == SHUTDOWN_MSG
+      rescue IOError, Errno::EPIPE
+        # Pipe was closed or broken, clean it up
+      end
+    rescue IOError
+      # Handle any IO errors during select
+    end
+
     def reap_and_replace_terminated_forks
       loop do
         pid, status = ::Process.waitpid2(-1, ::Process::WNOHANG)
@@ -181,6 +271,8 @@ module Lepus
         pid, _ = ::Process.waitpid2(-1, ::Process::WNOHANG)
         break unless pid
 
+        pipes.delete(pid)&.close
+        forks.delete(pid)
         configured_processes.delete(pid)
       end
     rescue SystemCallError
@@ -189,6 +281,7 @@ module Lepus
 
     def replace_fork(pid, status)
       Lepus.instrument(:replace_fork, supervisor_pid: ::Process.pid, pid: pid, status: status) do |payload|
+        pipes.delete(pid)&.close
         if (terminated_fork = forks.delete(pid))
           payload[:fork] = terminated_fork
 
@@ -200,5 +293,16 @@ module Lepus
     def all_forks_terminated?
       forks.empty?
     end
+
+    def initiate_shutdown_sequence_from_child(pipe)
+      if (pid = pipes.key(pipe))
+        pipes.delete(pid)
+        forks.delete(pid)
+        configured_processes.delete(pid)
+      end
+      pipe.close
+      quit_forks
+      stop
+    end
   end
 end