pgbus 0.0.1 → 0.1.1

data/lib/pgbus/recurring/schedule.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Recurring
+    class Schedule
+      attr_reader :tasks
+
+      def initialize(config: Pgbus.configuration)
+        @config = config
+        @tasks = load_tasks
+      end
+
+      def due_tasks(time = Time.now)
+        tasks.select { |task| task_due?(task, time) }
+      end
+
+      def enqueue_task(task, run_at:)
+        queue = resolve_queue(task)
+
+        RecurringExecution.record(task.key, run_at) do
+          payload = build_payload(task)
+          headers = build_headers(task, run_at)
+
+          Pgbus.client.ensure_queue(queue)
+          Pgbus.client.send_message(queue, payload, headers: headers)
+
+          Pgbus.logger.info do
+            "[Pgbus] Enqueued recurring task #{task.key} (#{task.class_name || task.command}) " \
+              "for run_at=#{run_at.iso8601}"
+          end
+        end
+      rescue AlreadyRecorded
+        Pgbus.logger.debug { "[Pgbus] Recurring task #{task.key} already enqueued for #{run_at.iso8601}" }
+      end
+
+      def build_payload(task)
+        if task.command
+          {
+            "job_class" => "Pgbus::Recurring::CommandJob",
+            "arguments" => [task.command],
+            "queue_name" => task.queue_name || @config.default_queue,
+            "priority" => nil
+          }
+        else
+          {
+            "job_class" => task.class_name,
+            "arguments" => task.arguments,
+            "queue_name" => task.queue_name || @config.default_queue,
+            "priority" => task.priority.zero? ? nil : task.priority
+          }
+        end
+      end
+
+      private
+
+      def load_tasks
+        raw = @config.recurring_tasks || {}
+        raw.filter_map do |key, options|
+          options = options.transform_keys(&:to_s).transform_keys(&:to_sym) if options.is_a?(Hash)
+          task = Task.from_configuration(key, **(options || {}))
+          if task.valid?
+            task
+          else
+            Pgbus.logger.warn { "[Pgbus] Skipping invalid recurring task '#{key}': #{task.errors.join(", ")}" }
+            nil
+          end
+        end
+      end
+
+      def task_due?(task, time)
+        # A task is due when its most recent cron occurrence (previous_time)
+        # falls within the current tick window. We also check match? to
+        # handle the exact-boundary case where time == cron time.
+        cron = task.parsed_schedule
+        return false unless cron
+
+        # Check if `time` itself matches the cron (exact boundary hit)
+        return true if cron.match?(time)
+
+        # Check if the previous occurrence was recent enough that we should
+        # still fire it (handles the case where we tick slightly after the
+        # cron time). The window is the scheduler interval.
+        prev = task.previous_time(time)
+        return false unless prev
+
+        (time - prev) <= @config.recurring_schedule_interval
+      end
+
+      def resolve_queue(task)
+        @config.queue_name(task.queue_name || @config.default_queue)
+      end
+
+      def build_headers(task, run_at)
+        {
+          "pgbus.recurring_key" => task.key,
+          "pgbus.recurring_run_at" => run_at.iso8601,
+          "pgbus.recurring_schedule" => task.schedule
+        }
+      end
+    end
+  end
+end

data/lib/pgbus/recurring/scheduler.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Recurring
+    class Scheduler
+      include Process::SignalHandler
+
+      attr_reader :schedule, :config
+
+      def initialize(config: Pgbus.configuration)
+        @config = config
+        @schedule = Schedule.new(config: config)
+        @shutting_down = false
+        @last_runs = {}
+      end
+
+      def run
+        setup_signals
+        start_heartbeat
+
+        Pgbus.logger.info do
+          "[Pgbus] Scheduler started: #{schedule.tasks.size} recurring tasks, " \
+            "interval=#{config.recurring_schedule_interval}s"
+        end
+
+        loop do
+          break if @shutting_down
+
+          process_signals
+          break if @shutting_down
+
+          tick(Time.now)
+          break if @shutting_down
+
+          interruptible_sleep(config.recurring_schedule_interval)
+        end
+
+        shutdown
+      end
+
+      def tick(now)
+        schedule.due_tasks(now).each do |task|
+          run_at = task.previous_time(now)
+          next unless run_at
+
+          schedule.enqueue_task(task, run_at: run_at)
+          @last_runs[task.key] = now
+        rescue StandardError => e
+          Pgbus.logger.error do
+            "[Pgbus] Error scheduling recurring task #{task.key}: #{e.class}: #{e.message}"
+          end
+        end
+      end
+
+      def last_run_at(key)
+        @last_runs[key]
+      end
+
+      def task_statuses
+        schedule.tasks.map do |task|
+          {
+            key: task.key,
+            class_name: task.class_name,
+            command: task.command,
+            schedule: task.schedule,
+            human_schedule: task.human_schedule,
+            queue_name: task.queue_name,
+            arguments: task.arguments,
+            priority: task.priority,
+            description: task.description,
+            next_run_at: task.next_time,
+            last_run_at: @last_runs[task.key]
+          }
+        end
+      end
+
+      def graceful_shutdown
+        @shutting_down = true
+      end
+
+      def immediate_shutdown
+        @shutting_down = true
+      end
+
+      private
+
+      def start_heartbeat
+        @heartbeat = Process::Heartbeat.new(
+          kind: "scheduler",
+          metadata: { pid: ::Process.pid, tasks: schedule.tasks.size }
+        )
+        @heartbeat.start
+      end
+
+      def shutdown
+        @heartbeat&.stop
+        restore_signals
+        Pgbus.logger.info { "[Pgbus] Scheduler stopped" }
+      end
+    end
+  end
+end

data/lib/pgbus/recurring/task.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "fugit"
+
+module Pgbus
+  module Recurring
+    class Task
+      attr_reader :key, :class_name, :command, :schedule, :queue_name,
+                  :arguments, :priority, :description
+
+      def self.from_configuration(key, **options)
+        options = options.transform_keys(&:to_sym)
+        new(
+          key: key,
+          class_name: options[:class],
+          command: options[:command],
+          schedule: options[:schedule],
+          queue_name: options[:queue],
+          arguments: Array(options[:args]),
+          priority: options.fetch(:priority, 0).to_i,
+          description: options[:description]
+        )
+      end
+
+      def initialize(key:, class_name: nil, command: nil, schedule: nil,
+                     queue_name: nil, arguments: [], priority: 0, description: nil)
+        @key = key
+        @class_name = class_name
+        @command = command
+        @schedule = schedule
+        @queue_name = queue_name
+        @arguments = arguments || []
+        @priority = priority || 0
+        @description = description
+        @errors = []
+      end
+
+      def valid?
+        @errors = []
+        validate!
+        @errors.empty?
+      end
+
+      def errors
+        valid? unless defined?(@validated)
+        @errors
+      end
+
+      def parsed_schedule
+        @parsed_schedule ||= parse_schedule
+      end
+
+      def next_time(from = Time.now)
+        parsed_schedule&.next_time(from)&.to_t
+      end
+
+      def previous_time(from = Time.now)
+        parsed_schedule&.previous_time(from)&.to_t
+      end
+
+      def human_schedule
+        return nil unless parsed_schedule
+
+        parsed_schedule.to_cron_s
+      end
+
+      def job_class
+        class_name&.safe_constantize
+      end
+
+      def to_h
+        {
+          key: key,
+          class_name: class_name,
+          command: command,
+          schedule: schedule,
+          queue_name: queue_name,
+          arguments: arguments,
+          priority: priority,
+          description: description
+        }
+      end
+
+      private
+
+      def validate!
+        @validated = true
+
+        if schedule.nil? || schedule.to_s.strip.empty?
+          @errors << "Schedule is required"
+          return
+        end
+
+        @errors << "Either class or command is required" if class_name.to_s.strip.empty? && command.to_s.strip.empty?
+
+        return if parsed_schedule.is_a?(Fugit::Cron)
+
+        @errors << "Schedule '#{schedule}' is not a valid cron expression"
+      end
+
+      def parse_schedule
+        return nil if schedule.nil? || schedule.to_s.strip.empty?
+
+        parsed = Fugit.parse(schedule.to_s, multi: :fail)
+        parsed.is_a?(Fugit::Cron) ? parsed : nil
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/pgbus/serializer.rb

@@ -7,15 +7,19 @@ module Pgbus
     module_function
 
     def serialize_job(active_job)
-      data = active_job.serialize
-      # GlobalID is handled by ActiveJob's serialize — it converts AR objects
-      # to GlobalID URIs automatically. We just JSON-encode the result.
-      JSON.generate(data)
+      Instrumentation.instrument("pgbus.serializer.serialize", kind: :job) do
+        data = active_job.serialize
+        # GlobalID is handled by ActiveJob's serialize — it converts AR objects
+        # to GlobalID URIs automatically. We just JSON-encode the result.
+        JSON.generate(data)
+      end
     end
 
     def deserialize_job(json_string)
-      data = JSON.parse(json_string)
-      ActiveJob::Base.deserialize(data)
+      Instrumentation.instrument("pgbus.serializer.deserialize", kind: :job) do
+        data = JSON.parse(json_string)
+        ActiveJob::Base.deserialize(data)
+      end
     end
 
     def serialize_event(event)

data/lib/pgbus/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pgbus
-  VERSION = "0.0.1"
+  VERSION = "0.1.1"
 end

data/lib/pgbus/web/data_source.rb

@@ -23,24 +23,28 @@ module Pgbus
           total_visible: total_visible,
           active_processes: processes.count,
           failed_count: failed_events_count,
-          dlq_depth: dlq_depth
+          dlq_depth: dlq_depth,
+          recurring_count: recurring_tasks_count
         }
       end
 
-      # Queues
+      # Queues — query via ActiveRecord for reliability in web processes
+      # (avoids PGMQ client connection issues when the web server uses a
+      # different connection lifecycle than the worker processes).
       def queues_with_metrics
-        metrics = @client.metrics || []
-        Array(metrics).map { |m| format_metrics(m) }
+        queue_names = connection.select_values("SELECT queue_name FROM pgmq.meta ORDER BY queue_name")
+        queue_names.map { |name| queue_metrics_via_sql(name) }.compact
       rescue StandardError => e
-        Pgbus.logger.debug { "[Pgbus::Web] Error fetching queue metrics: #{e.message}" }
+        Pgbus.logger.error { "[Pgbus::Web] Error fetching queue metrics: #{e.class}: #{e.message}" }
         []
       end
 
+      # name is the full PGMQ queue name (e.g. "pgbus_default") as returned
+      # by queues_with_metrics. No prefix is added.
       def queue_detail(name)
-        m = @client.metrics(name)
-        m ? format_metrics(m) : nil
+        queue_metrics_via_sql(name)
       rescue StandardError => e
-        Pgbus.logger.debug { "[Pgbus::Web] Error fetching queue detail for #{name}: #{e.message}" }
+        Pgbus.logger.error { "[Pgbus::Web] Error fetching queue detail for #{name}: #{e.class}: #{e.message}" }
         nil
       end
 
@@ -63,9 +67,8 @@ module Pgbus
       end
 
       def job_detail(queue_name, msg_id)
-        full_name = Pgbus.configuration.queue_name(queue_name)
         row = connection.select_one(
-          "SELECT * FROM pgmq.q_#{sanitize_name(full_name)} WHERE msg_id = $1",
+          "SELECT * FROM pgmq.q_#{sanitize_name(queue_name)} WHERE msg_id = $1",
           "Pgbus Job Detail",
           [msg_id.to_i]
         )
@@ -76,8 +79,7 @@ module Pgbus
       end
 
       def retry_job(queue_name, msg_id)
-        full_name = Pgbus.configuration.queue_name(queue_name)
-        @client.set_visibility_timeout(full_name, msg_id.to_i, vt: 0)
+        @client.set_visibility_timeout(queue_name, msg_id.to_i, vt: 0)
       end
 
       def discard_job(queue_name, msg_id)
@@ -315,6 +317,127 @@ module Pgbus
         false
       end
 
+      # Recurring tasks
+      def recurring_tasks
+        records = RecurringTask.order(:key).to_a
+        last_runs = RecurringExecution
+                    .where(task_key: records.map(&:key))
+                    .select("task_key, MAX(run_at) AS run_at")
+                    .group(:task_key)
+                    .index_by(&:task_key)
+
+        records.map do |record|
+          last_exec = last_runs[record.key]
+          task = Recurring::Task.from_configuration(record.key,
+                                                    class: record.class_name,
+                                                    command: record.command,
+                                                    schedule: record.schedule,
+                                                    queue: record.queue_name,
+                                                    args: parse_arguments(record.arguments),
+                                                    priority: record.priority,
+                                                    description: record.description)
+
+          {
+            id: record.id,
+            key: record.key,
+            class_name: record.class_name,
+            command: record.command,
+            schedule: record.schedule,
+            human_schedule: task.human_schedule,
+            queue_name: record.queue_name,
+            priority: record.priority,
+            description: record.description,
+            enabled: record.enabled,
+            static: record.static,
+            next_run_at: task.next_time,
+            last_run_at: last_exec&.run_at,
+            created_at: record.created_at,
+            updated_at: record.updated_at
+          }
+        end
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus::Web] Error fetching recurring tasks: #{e.class}: #{e.message}" }
+        []
+      end
+
+      def recurring_task(id)
+        record = RecurringTask.find_by(id: id)
+        return nil unless record
+
+        task = Recurring::Task.from_configuration(record.key,
+                                                  class: record.class_name,
+                                                  command: record.command,
+                                                  schedule: record.schedule,
+                                                  queue: record.queue_name,
+                                                  args: parse_arguments(record.arguments),
+                                                  priority: record.priority,
+                                                  description: record.description)
+
+        executions = RecurringExecution.for_task(record.key).recent(25).map do |exec|
+          { run_at: exec.run_at, created_at: exec.created_at }
+        end
+
+        {
+          id: record.id,
+          key: record.key,
+          class_name: record.class_name,
+          command: record.command,
+          schedule: record.schedule,
+          human_schedule: task.human_schedule,
+          queue_name: record.queue_name,
+          arguments: parse_arguments(record.arguments),
+          priority: record.priority,
+          description: record.description,
+          enabled: record.enabled,
+          static: record.static,
+          next_run_at: task.next_time,
+          executions: executions,
+          created_at: record.created_at,
+          updated_at: record.updated_at
+        }
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus::Web] Error fetching recurring task #{id}: #{e.class}: #{e.message}" }
+        nil
+      end
+
+      def toggle_recurring_task(id)
+        record = RecurringTask.find_by(id: id)
+        return false unless record
+
+        record.update!(enabled: !record.enabled)
+        true
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus::Web] Error toggling recurring task #{id}: #{e.message}" }
+        false
+      end
+
+      def enqueue_recurring_task_now(id)
+        record = RecurringTask.find_by(id: id)
+        return false unless record
+
+        task = Recurring::Task.from_configuration(record.key,
+                                                  class: record.class_name,
+                                                  command: record.command,
+                                                  schedule: record.schedule,
+                                                  queue: record.queue_name,
+                                                  args: parse_arguments(record.arguments),
+                                                  priority: record.priority)
+
+        schedule = Recurring::Schedule.new(config: Pgbus.configuration)
+        schedule.enqueue_task(task, run_at: Time.now.utc)
+        true
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus::Web] Error enqueuing recurring task #{id}: #{e.message}" }
+        false
+      end
+
+      def recurring_tasks_count
+        RecurringTask.count
+      rescue StandardError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Error counting recurring tasks: #{e.message}" }
+        0
+      end
+
       # Subscriber registry
       def registered_subscribers
         EventBus::Registry.instance.subscribers.map do |s|
@@ -328,12 +451,12 @@ module Pgbus
       private
 
       def connection
-        ActiveRecord::Base.connection
+        Pgbus::ApplicationRecord.connection
       end
 
+      # name is the full PGMQ queue name (already prefixed)
       def query_queue_messages(name, limit, offset)
-        full_name = Pgbus.configuration.queue_name(name)
-        query_queue_messages_raw(full_name, limit, offset).map { |m| m.merge(queue: name) }
+        query_queue_messages_raw(name, limit, offset).map { |m| m.merge(queue: name) }
       end
 
       def query_queue_messages_raw(full_name, limit, offset)
@@ -357,15 +480,45 @@ module Pgbus
         messages.sort_by { |m| -m[:msg_id].to_i }.slice(offset, limit) || []
       end
 
-      def format_metrics(m)
+      def queue_metrics_via_sql(queue_name)
+        qtable = "q_#{sanitize_name(queue_name)}"
+        seq_name = "#{qtable}_msg_id_seq"
+
+        row = connection.select_one(<<~SQL, "Pgbus Queue Metrics")
+          WITH q_summary AS (
+            SELECT
+              count(*) AS queue_length,
+              count(CASE WHEN vt <= NOW() THEN 1 END) AS queue_visible_length,
+              EXTRACT(epoch FROM (NOW() - max(enqueued_at)))::int AS newest_msg_age_sec,
+              EXTRACT(epoch FROM (NOW() - min(enqueued_at)))::int AS oldest_msg_age_sec
+            FROM pgmq.#{qtable}
+          ),
+          all_metrics AS (
+            SELECT CASE WHEN is_called THEN last_value ELSE 0 END AS total_messages
+            FROM pgmq.#{seq_name}
+          )
+          SELECT
+            q_summary.queue_length,
+            q_summary.queue_visible_length,
+            q_summary.newest_msg_age_sec,
+            q_summary.oldest_msg_age_sec,
+            all_metrics.total_messages
+          FROM q_summary, all_metrics
+        SQL
+
+        return nil unless row
+
         {
-          name: m.queue_name.to_s,
-          queue_length: m.queue_length.to_i,
-          queue_visible_length: m.queue_visible_length.to_i,
-          oldest_msg_age_sec: m.oldest_msg_age_sec&.to_i,
-          newest_msg_age_sec: m.newest_msg_age_sec&.to_i,
-          total_messages: m.total_messages.to_i
+          name: queue_name,
+          queue_length: row["queue_length"].to_i,
+          queue_visible_length: row["queue_visible_length"].to_i,
+          oldest_msg_age_sec: row["oldest_msg_age_sec"]&.to_i,
+          newest_msg_age_sec: row["newest_msg_age_sec"]&.to_i,
+          total_messages: row["total_messages"].to_i
         }
+      rescue StandardError => e
+        Pgbus.logger.error { "[Pgbus::Web] Error fetching metrics for #{queue_name}: #{e.class}: #{e.message}" }
+        nil
       end
 
       def format_message(row, queue_name)
@@ -401,6 +554,18 @@ module Pgbus
       def sanitize_name(name)
         name.gsub(/[^a-zA-Z0-9_]/, "")
       end
+
+      def parse_arguments(args)
+        case args
+        when Array then args
+        when String then JSON.parse(args)
+        when NilClass then []
+        else Array(args)
+        end
+      rescue JSON::ParserError => e
+        Pgbus.logger.debug { "[Pgbus::Web] Invalid recurring task arguments JSON: #{e.message}" }
+        []
+      end
     end
   end
 end

data/lib/pgbus.rb

@@ -16,6 +16,13 @@ module Pgbus
         loader = Zeitwerk::Loader.for_gem
         loader.inflector.inflect("pgbus" => "Pgbus", "cli" => "CLI", "dsl" => "DSL")
         loader.ignore("#{__dir__}/generators")
+        loader.ignore("#{__dir__}/active_job")
+        # Register app/models for non-Rails usage (specs, standalone).
+        # When Rails is running, the Engine handles autoloading app/models.
+        unless defined?(Rails::Engine)
+          models_dir = File.expand_path("../app/models", __dir__)
+          loader.push_dir(models_dir) if File.directory?(models_dir)
+        end
         loader
       end
     end
@@ -46,4 +53,5 @@ module Pgbus
   loader.setup
 end
 
+require "active_job/queue_adapters/pgbus_adapter" if defined?(ActiveJob)
 require "pgbus/engine" if defined?(Rails::Engine)