lepus 0.0.1.rc2 → 0.1.0

data/lib/lepus/process_registry/file_backend.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "tmpdir"
+require "base64"
+
+module Lepus
+  class ProcessRegistry
+    # File-based backend for process registry storage.
+    # Stores process data in a file using Marshal serialization.
+    # This is the default backend for apps not using the web dashboard.
+    class FileBackend
+      include Backend
+
+      attr_reader :path
+
+      def initialize(path: nil)
+        @path = path
+      end
+
+      def start
+        @path ||= Pathname.new(Dir.tmpdir).join("lepus_process_registry.store")
+      end
+
+      def stop
+        path.delete if path&.exist?
+      end
+
+      def add(process, metrics: {})
+        transaction do |data|
+          data[process.id] = process.to_h
+        end
+      end
+
+      def delete(process)
+        transaction do |data|
+          data.delete(process.id)
+        end
+      end
+
+      def find(id)
+        raw = read.fetch(id) { raise(Lepus::Process::NotFoundError.new(id)) }
+        Lepus::Process.coerce(raw)
+      end
+
+      def exists?(id)
+        read.key?(id)
+      end
+
+      def all
+        read.keys.map { |id| find(id) }
+      end
+
+      def count
+        return 0 unless path
+
+        read.size
+      end
+
+      def clear
+        return unless path
+
+        write({})
+      end
+
+      private
+
+      def transaction
+        data = read
+        yield data
+        write(data)
+      end
+
+      def read
+        with_lock(File::LOCK_SH) do |f|
+          if f.size.zero?
+            {}
+          else
+            encoded = f.read
+            Marshal.load(Base64.strict_decode64(encoded))
+          end
+        end
+      end
+
+      def write(data)
+        with_lock(File::LOCK_EX) do |f|
+          f.rewind
+          f.truncate(0)
+          encoded = Base64.strict_encode64(Marshal.dump(data))
+          f.write(encoded)
+          f.flush
+        end
+      end
+
+      def with_lock(lock_type)
+        unless path
+          raise "ProcessRegistry not started. Call Lepus::ProcessRegistry.start first."
+        end
+        File.open(path, File::RDWR | File::CREAT | File::BINARY, 0o644) do |f|
+          f.flock(lock_type)
+          result = yield f
+          f.flock(File::LOCK_UN)
+          result
+        end
+      end
+    end
+  end
+end

data/lib/lepus/process_registry/message_builder.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lepus
+  class ProcessRegistry
+    # Builds heartbeat messages for RabbitMQ publishing.
+    class MessageBuilder
+      VERSION = "1.0"
+
+      def initialize(process, metrics: {})
+        @process = process
+        @metrics = metrics
+      end
+
+      def build_heartbeat
+        {
+          type: "heartbeat",
+          version: VERSION,
+          process: process_data,
+          metrics: metrics_data
+        }
+      end
+
+      def build_deregister
+        {
+          type: "deregister",
+          version: VERSION,
+          process_id: @process.id,
+          timestamp: Time.now.iso8601(6)
+        }
+      end
+
+      def to_json
+        JSON.generate(build_heartbeat)
+      end
+
+      private
+
+      def process_data
+        {
+          id: @process.id,
+          name: @process.name,
+          pid: @process.pid,
+          hostname: @process.hostname,
+          kind: @process.kind,
+          supervisor_id: @process.supervisor_id,
+          application: Lepus.config.application_name,
+          last_heartbeat_at: format_time(@process.last_heartbeat_at)
+        }
+      end
+
+      def metrics_data
+        {
+          rss_memory: @metrics[:rss_memory] || safe_rss_memory,
+          connections: @metrics[:connections] || 0,
+          consumers: @metrics[:consumers] || []
+        }
+      end
+
+      def safe_rss_memory
+        @process.rss_memory * 1024 # Convert kB to bytes (MEMORY_GRABBER returns kB)
+      rescue
+        0
+      end
+
+      def format_time(time)
+        time&.iso8601(6)
+      end
+    end
+  end
+end

data/lib/lepus/process_registry/rabbitmq_backend.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "json"
+require "timeout"
+
+module Lepus
+  class ProcessRegistry
+    # RabbitMQ-based backend for process registry.
+    # Publishes heartbeats to a fanout exchange for web dashboard aggregation.
+    # Also writes locally via FileBackend for local queries when aggregator is unavailable.
+    class RabbitmqBackend
+      include Backend
+
+      HEARTBEAT_EXCHANGE = "lepus.heartbeat"
+
+      attr_reader :fallback
+
+      def initialize(fallback: nil)
+        @fallback = fallback || FileBackend.new
+        @connection = nil
+        @channel = nil
+        @exchange = nil
+        @mutex = Mutex.new
+      end
+
+      def start
+        @fallback.start
+        setup_channel_and_exchange
+      end
+
+      def stop
+        @fallback.stop
+        close_channel
+      end
+
+      def add(process, metrics: {})
+        @fallback.add(process)
+        publish_heartbeat(process, metrics: metrics)
+      end
+
+      def delete(process)
+        @fallback.delete(process)
+        publish_deregister(process)
+      end
+
+      def find(id)
+        @fallback.find(id)
+      end
+
+      def exists?(id)
+        @fallback.exists?(id)
+      end
+
+      def all
+        @fallback.all
+      end
+
+      def count
+        @fallback.count
+      end
+
+      def clear
+        @fallback.clear
+      end
+
+      def path
+        @fallback.path
+      end
+
+      private
+
+      def setup_channel_and_exchange
+        return unless rabbitmq_available?
+
+        @mutex.synchronize do
+          return if @channel&.open?
+
+          @connection = Lepus.config.create_connection(suffix: "(registry)")
+          @channel = @connection.create_channel
+          @exchange = @channel.fanout(
+            HEARTBEAT_EXCHANGE,
+            durable: false,
+            auto_delete: false
+          )
+        end
+      rescue => e
+        Lepus.logger.warn("[ProcessRegistry] Failed to setup RabbitMQ channel: #{e.message}")
+        @connection = nil
+        @channel = nil
+        @exchange = nil
+      end
+
+      # Tear down the dedicated registry connection on supervisor shutdown.
+      # Bunny's graceful close waits up to 15s per channel for a broker
+      # `close-ok` continuation; during forked supervisor shutdown the broker
+      # sometimes never replies and SIGTERM handling blows past its 10s budget,
+      # timing out the integration specs. We bound the graceful attempt at 2s
+      # and fall back to closing the socket directly so the process can exit.
+      CLOSE_TIMEOUT = 2
+
+      def close_channel
+        @mutex.synchronize do
+          force_close_connection if @connection
+        end
+      ensure
+        @connection = nil
+        @channel = nil
+        @exchange = nil
+      end
+
+      def force_close_connection
+        Timeout.timeout(CLOSE_TIMEOUT) { @connection.close(false) } if @connection.open?
+      rescue => e
+        Lepus.logger.warn("[ProcessRegistry] Failed to close RabbitMQ connection: #{e.message}")
+        begin
+          @connection.instance_variable_get(:@transport)&.close
+        rescue
+          nil
+        end
+      end
+
+      def publish_heartbeat(process, metrics: {})
+        return unless @exchange
+
+        message = MessageBuilder.new(process, metrics: metrics)
+        @exchange.publish(
+          message.to_json,
+          content_type: "application/json"
+        )
+      rescue => e
+        Lepus.logger.warn("[ProcessRegistry] Failed to publish heartbeat: #{e.message}")
+      end
+
+      def publish_deregister(process)
+        return unless @exchange
+
+        message = MessageBuilder.new(process).build_deregister
+        @exchange.publish(
+          JSON.generate(message),
+          content_type: "application/json"
+        )
+      rescue => e
+        Lepus.logger.warn("[ProcessRegistry] Failed to publish deregister: #{e.message}")
+      end
+
+      def rabbitmq_available?
+        Lepus.config.rabbitmq_url.present?
+      rescue
+        true
+      end
+    end
+  end
+end

data/lib/lepus/process_registry.rb

@@ -1,24 +1,27 @@
 # frozen_string_literal: true
 
-require "pathname"
-require "tmpdir"
-require "base64"
-
 module Lepus
-  # we are storing the process registry in a file using Marshal serialization
-  # but the plan is to move to a Rabbitmq or Redis based implementation in the future
-  # to let it available to outside services like the web dashboard.
-  # I'll refactor this class later when we have a better idea of the requirements.
+  # Process registry that delegates to a configurable backend.
+  # Default backend is FileBackend for local file-based storage.
+  # Use RabbitmqBackend to share process data across apps via web dashboard.
   class ProcessRegistry
     class << self
-      attr_reader :path
+      def backend
+        @backend ||= Lepus.config.build_process_registry_backend
+      end
+
+      attr_writer :backend
+
+      def reset_backend!
+        @backend = nil
+      end
 
       def start
-        @path ||= Pathname.new(Dir.tmpdir).join("lepus_process_registry.store")
+        backend.start
       end
 
       def stop
-        path.delete if path&.exist?
+        backend.stop
       end
 
       def reset!
@@ -27,82 +30,40 @@ module Lepus
       end
 
       def add(process)
-        transaction do |data|
-          data[process.id] = process.to_h
-        end
+        backend.add(process)
+      end
+
+      def update(process, metrics: {})
+        backend.update(process, metrics: metrics)
       end
-      alias_method :update, :add
 
       def delete(process)
-        transaction do |data|
-          data.delete(process.id)
-        end
+        backend.delete(process)
       end
 
       def find(id)
-        raw = read.fetch(id) { raise(Lepus::Process::NotFoundError.new(id)) }
-        Lepus::Process.coerce(raw)
+        backend.find(id)
       end
 
       def exists?(id)
-        read.key?(id)
+        backend.exists?(id)
       end
 
       def all
-        read.keys.map { |id| find(id) }
+        backend.all
       end
 
       def count
-        return 0 unless path
-
-        read.size
+        backend.count
       end
 
       def clear
-        return unless path
-
-        write({})
-      end
-
-      private
-
-      def transaction
-        data = read
-        yield data
-        write(data)
-      end
-
-      def read
-        with_lock(File::LOCK_SH) do |f|
-          if f.size.zero?
-            {}
-          else
-            encoded = f.read
-            Marshal.load(Base64.strict_decode64(encoded))
-          end
-        end
-      end
-
-      def write(data)
-        with_lock(File::LOCK_EX) do |f|
-          f.rewind
-          f.truncate(0)
-          encoded = Base64.strict_encode64(Marshal.dump(data))
-          f.write(encoded)
-          f.flush
-        end
+        backend.clear
       end
 
-      def with_lock(lock_type)
-        unless path
-          raise "ProcessRegistry not started. Call Lepus::ProcessRegistry.start first."
-        end
-        File.open(path, File::RDWR | File::CREAT | File::BINARY, 0o644) do |f|
-          f.flock(lock_type)
-          result = yield f
-          f.flock(File::LOCK_UN)
-          result
-        end
+      # For backward compatibility with tests that check @path
+      def path
+        backend.respond_to?(:path) ? backend.path : nil
       end
     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