pgbus 0.0.1

data/lib/pgbus/concurrency/blocked_execution.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pgbus
+  module Concurrency
+    module BlockedExecution
+      class << self
+        # Insert a blocked execution for a job that hit the concurrency limit.
+        def insert(concurrency_key:, queue_name:, payload:, duration:, priority: 0)
+          expires_at = Time.now.utc + duration
+
+          execute(<<~SQL, "Pgbus Blocked Insert", [concurrency_key, queue_name, JSON.generate(payload), priority, expires_at])
+            INSERT INTO pgbus_blocked_executions
+              (concurrency_key, queue_name, payload, priority, expires_at)
+            VALUES ($1, $2, $3, $4, $5)
+          SQL
+        end
+
+        # Release the next blocked execution for a given concurrency key.
+        # Returns the released row (queue_name, payload) or nil if none.
+        def release_next(concurrency_key)
+          return nil unless defined?(ActiveRecord::Base)
+
+          result = execute(<<~SQL, "Pgbus Blocked Release", [concurrency_key])
+            DELETE FROM pgbus_blocked_executions
+            WHERE id = (
+              SELECT id FROM pgbus_blocked_executions
+              WHERE concurrency_key = $1
+              ORDER BY priority ASC, created_at ASC
+              LIMIT 1
+              FOR UPDATE SKIP LOCKED
+            )
+            RETURNING queue_name, payload
+          SQL
+
+          row = result.first
+          return nil unless row
+
+          { queue_name: row["queue_name"], payload: JSON.parse(row["payload"]) }
+        end
+
+        # Delete blocked executions that have expired.
+        # Returns the count of deleted rows.
+        def expire_stale
+          result = execute(<<~SQL, "Pgbus Blocked Expire", [Time.now.utc])
+            DELETE FROM pgbus_blocked_executions
+            WHERE expires_at < $1
+            RETURNING id
+          SQL
+
+          result.to_a.size
+        end
+
+        # Count blocked executions for a given key. Useful for testing/monitoring.
+        def count_for(concurrency_key)
+          result = execute(<<~SQL, "Pgbus Blocked Count", [concurrency_key])
+            SELECT COUNT(*) AS cnt FROM pgbus_blocked_executions WHERE concurrency_key = $1
+          SQL
+
+          result.first&.fetch("cnt", 0).to_i
+        end
+
+        private
+
+        def execute(sql, name, binds)
+          return [] unless defined?(ActiveRecord::Base)
+
+          ActiveRecord::Base.connection.exec_query(sql, name, binds)
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/concurrency/semaphore.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module Concurrency
+    module Semaphore
+      class << self
+        # Attempt to acquire a slot in the semaphore for the given key.
+        # Returns :acquired if a slot was available, :blocked if the limit is reached.
+        def acquire(key, max_value, duration)
+          expires_at = Time.now.utc + duration
+
+          result = execute(<<~SQL, "Pgbus Semaphore Acquire", [key, max_value, expires_at])
+            INSERT INTO pgbus_semaphores (key, value, max_value, expires_at)
+            VALUES ($1, 1, $2, $3)
+            ON CONFLICT (key) DO UPDATE
+              SET value = pgbus_semaphores.value + 1,
+                  max_value = EXCLUDED.max_value,
+                  expires_at = GREATEST(pgbus_semaphores.expires_at, EXCLUDED.expires_at)
+              WHERE pgbus_semaphores.value < pgbus_semaphores.max_value
+            RETURNING value
+          SQL
+
+          result.any? ? :acquired : :blocked
+        end
+
+        # Release one slot in the semaphore. Called after a job completes.
+        def release(key)
+          execute(<<~SQL, "Pgbus Semaphore Release", [key])
+            UPDATE pgbus_semaphores
+            SET value = GREATEST(value - 1, 0)
+            WHERE key = $1
+          SQL
+        end
+
+        # Delete semaphores that have expired (safety net for crashed workers).
+        # Returns the number of deleted rows.
+        def expire_stale
+          result = execute(<<~SQL, "Pgbus Semaphore Expire", [Time.now.utc])
+            DELETE FROM pgbus_semaphores
+            WHERE expires_at < $1 OR value <= 0
+            RETURNING key
+          SQL
+
+          result.to_a
+        end
+
+        # Check current value for a key. Useful for testing/monitoring.
+        def current_value(key)
+          result = execute(<<~SQL, "Pgbus Semaphore Value", [key])
+            SELECT value FROM pgbus_semaphores WHERE key = $1
+          SQL
+
+          result.first&.fetch("value", nil)&.to_i
+        end
+
+        private
+
+        def execute(sql, name, binds)
+          return [] unless defined?(ActiveRecord::Base)
+
+          ActiveRecord::Base.connection.exec_query(sql, name, binds)
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/concurrency.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Pgbus
+  module Concurrency
+    extend ActiveSupport::Concern
+
+    METADATA_KEY = "pgbus_concurrency_key"
+
+    class_methods do
+      # Limit concurrent execution of jobs with the same key.
+      #
+      #   limits_concurrency to: 1, key: ->(order) { "ProcessOrder-#{order.id}" }
+      #   limits_concurrency to: 3, key: ->(user_id) { "ImportUser-#{user_id}" }, on_conflict: :discard
+      #
+      # Options:
+      #   to:          Maximum concurrent jobs for the same key (required)
+      #   key:         Proc receiving job arguments, returns a string key. Default: job class name.
+      #   duration:    Safety expiry for semaphore (default: 15 minutes)
+      #   on_conflict: What to do when limit is reached — :block, :discard, or :raise (default: :block)
+      def limits_concurrency(to:, key: nil, duration: 15 * 60, on_conflict: :block) # rubocop:disable Naming/MethodParameterName
+        raise ArgumentError, "to: must be a positive integer" unless to.is_a?(Integer) && to.positive?
+        raise ArgumentError, "on_conflict must be :block, :discard, or :raise" unless %i[block discard raise].include?(on_conflict)
+
+        @pgbus_concurrency = {
+          limit: to,
+          key: key || ->(*) { name },
+          duration: duration,
+          on_conflict: on_conflict
+        }
+      end
+
+      def pgbus_concurrency
+        @pgbus_concurrency
+      end
+    end
+
+    class << self
+      # Resolve the concurrency key for a given job instance.
+      # Returns nil if the job class has no concurrency config.
+      def resolve_key(active_job)
+        return nil unless active_job.class.respond_to?(:pgbus_concurrency)
+
+        config = active_job.class.pgbus_concurrency
+        return nil unless config
+
+        config[:key].call(*active_job.arguments)
+      end
+
+      # Inject the resolved concurrency key into the job's serialized payload.
+      def inject_metadata(active_job, payload_hash)
+        key = resolve_key(active_job)
+        return payload_hash unless key
+
+        payload_hash.merge(METADATA_KEY => key)
+      end
+
+      # Extract the concurrency key from a deserialized payload.
+      def extract_key(payload)
+        payload[METADATA_KEY]
+      end
+    end
+  end
+end

data/lib/pgbus/config_loader.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "erb"
+
+module Pgbus
+  module ConfigLoader
+    module_function
+
+    def load(path, env: nil)
+      env ||= defined?(Rails) ? Rails.env : ENV.fetch("PGBUS_ENV", "development")
+      raw = File.read(path)
+      parsed = YAML.safe_load(ERB.new(raw).result, permitted_classes: [Symbol], aliases: true)
+      config_hash = parsed.fetch(env, parsed)
+      apply(config_hash)
+    end
+
+    def apply(hash)
+      config = Pgbus.configuration
+      hash.each do |key, value|
+        setter = :"#{key}="
+        config.public_send(setter, value) if config.respond_to?(setter)
+      end
+      config
+    end
+  end
+end

data/lib/pgbus/configuration.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module Pgbus
+  class Configuration
+    # Connection settings
+    attr_accessor :database_url, :connection_params, :pool_size, :pool_timeout
+
+    # Queue settings
+    attr_accessor :default_queue, :queue_prefix
+
+    # Worker settings
+    attr_accessor :workers, :polling_interval, :visibility_timeout
+
+    # Worker recycling
+    attr_accessor :max_jobs_per_worker, :max_memory_mb, :max_worker_lifetime
+
+    # Dispatcher settings
+    attr_accessor :dispatch_interval
+
+    # Dead letter queue
+    attr_accessor :max_retries, :dead_letter_queue_suffix
+
+    # Event bus
+    attr_accessor :idempotency_ttl
+
+    # Logging
+    attr_accessor :logger
+
+    # LISTEN/NOTIFY
+    attr_accessor :listen_notify, :notify_throttle_ms
+
+    # Event consumers
+    attr_accessor :event_consumers
+
+    # Web dashboard
+    attr_accessor :web_auth, :web_refresh_interval, :web_per_page, :web_live_updates, :web_data_source
+
+    def initialize
+      @database_url = nil
+      @connection_params = nil
+      @pool_size = 5
+      @pool_timeout = 5
+
+      @default_queue = "default"
+      @queue_prefix = "pgbus"
+
+      @workers = [{ queues: %w[default], threads: 5 }]
+      @polling_interval = 0.1
+      @visibility_timeout = 30
+
+      @max_jobs_per_worker = nil
+      @max_memory_mb = nil
+      @max_worker_lifetime = nil
+
+      @dispatch_interval = 1.0
+
+      @max_retries = 5
+      @dead_letter_queue_suffix = "_dlq"
+
+      @idempotency_ttl = 7 * 24 * 3600 # 7 days
+
+      @logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+
+      @listen_notify = true
+      @notify_throttle_ms = 250
+
+      @event_consumers = nil
+
+      @web_auth = nil
+      @web_refresh_interval = 5000
+      @web_per_page = 25
+      @web_live_updates = true
+      @web_data_source = nil
+    end
+
+    def queue_name(name)
+      "#{queue_prefix}_#{name}"
+    end
+
+    def dead_letter_queue_name(name)
+      "#{queue_name(name)}#{dead_letter_queue_suffix}"
+    end
+
+    def connection_options
+      if database_url
+        database_url
+      elsif connection_params
+        connection_params
+      elsif defined?(ActiveRecord::Base)
+        -> { ActiveRecord::Base.connection.raw_connection }
+      else
+        raise ConfigurationError, "No database connection configured. " \
+                                  "Set Pgbus.configuration.database_url, connection_params, or use with Rails."
+      end
+    end
+  end
+end

data/lib/pgbus/engine.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Pgbus
+  class Engine < ::Rails::Engine
+    isolate_namespace Pgbus
+
+    initializer "pgbus.configure" do |app|
+      config_path = app.root.join("config", "pgbus.yml")
+      Pgbus::ConfigLoader.load(config_path) if config_path.exist?
+    end
+
+    initializer "pgbus.active_job" do
+      ActiveSupport.on_load(:active_job) do
+        require "pgbus/active_job/adapter"
+      end
+    end
+
+    initializer "pgbus.logger" do
+      ActiveSupport.on_load(:after_initialize) do
+        Pgbus.configuration.logger ||= Rails.logger
+      end
+    end
+
+    initializer "pgbus.web" do
+      require "pgbus/web/authentication"
+      require "pgbus/web/data_source"
+    end
+  end
+end

data/lib/pgbus/event.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Pgbus
+  class Event
+    attr_reader :event_id, :payload, :published_at, :routing_key, :headers
+
+    def initialize(event_id:, payload:, published_at: nil, routing_key: nil, headers: nil)
+      @event_id = event_id
+      @payload = payload
+      @published_at = published_at || Time.now.utc
+      @routing_key = routing_key
+      @headers = headers || {}
+    end
+
+    def [](key)
+      payload.is_a?(Hash) ? payload[key.to_s] : nil
+    end
+
+    def to_h
+      {
+        "event_id" => event_id,
+        "payload" => payload,
+        "published_at" => published_at.iso8601(6),
+        "routing_key" => routing_key,
+        "headers" => headers
+      }
+    end
+  end
+end

data/lib/pgbus/event_bus/handler.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module EventBus
+    class Handler
+      class << self
+        def idempotent!
+          @idempotent = true
+        end
+
+        def idempotent?
+          @idempotent == true
+        end
+      end
+
+      def process(message)
+        raw = JSON.parse(message.message)
+        event = build_event(raw)
+
+        if self.class.idempotent?
+          return :skipped if already_processed?(event.event_id)
+
+          mark_processed!(event.event_id)
+        end
+
+        handle(event)
+        instrument("pgbus.event_processed", event_id: event.event_id, handler: self.class.name)
+        :handled
+      end
+
+      def handle(event)
+        raise NotImplementedError, "#{self.class.name} must implement #handle(event)"
+      end
+
+      private
+
+      def build_event(raw)
+        payload = raw["payload"]
+        payload = GlobalID::Locator.locate(payload["_global_id"]) if payload.is_a?(Hash) && payload["_global_id"]
+
+        Event.new(
+          event_id: raw["event_id"],
+          payload: payload,
+          published_at: raw["published_at"] ? Time.parse(raw["published_at"]) : nil
+        )
+      end
+
+      def instrument(event_name, payload = {})
+        return unless defined?(ActiveSupport::Notifications)
+
+        ActiveSupport::Notifications.instrument(event_name, payload)
+      end
+
+      def already_processed?(event_id)
+        return false unless defined?(ActiveRecord::Base)
+
+        ActiveRecord::Base.connection.select_value(
+          "SELECT 1 FROM pgbus_processed_events WHERE event_id = $1 AND handler_class = $2",
+          "Pgbus Idempotency Check",
+          [event_id, self.class.name]
+        )
+      end
+
+      def mark_processed!(event_id)
+        return unless defined?(ActiveRecord::Base)
+
+        ActiveRecord::Base.connection.exec_insert(
+          "INSERT INTO pgbus_processed_events (event_id, handler_class, processed_at) " \
+          "VALUES ($1, $2, $3) ON CONFLICT (event_id, handler_class) DO NOTHING",
+          "Pgbus Idempotency Mark",
+          [event_id, self.class.name, Time.now.utc]
+        )
+      end
+    end
+  end
+end

data/lib/pgbus/event_bus/publisher.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module EventBus
+    module Publisher
+      module_function
+
+      def publish(routing_key, payload, headers: nil, delay: 0)
+        event_data = build_event_data(payload)
+
+        if Pgbus.client.pgmq.respond_to?(:produce_topic)
+          Pgbus.client.publish_to_topic(routing_key, event_data, headers: headers, delay: delay)
+        else
+          # Fallback: send directly to queues matching the routing key
+          Pgbus.client.send_message(routing_key, event_data, headers: headers, delay: delay)
+        end
+      end
+
+      def publish_later(routing_key, payload, delay:, headers: nil)
+        publish(routing_key, payload, headers: headers, delay: delay)
+      end
+
+      def build_event_data(payload)
+        event_id = SecureRandom.uuid
+
+        serialized_payload = if payload.respond_to?(:to_global_id)
+                               { "_global_id" => payload.to_global_id.to_s }
+                             elsif payload.is_a?(Hash)
+                               payload
+                             else
+                               { "value" => payload }
+                             end
+
+        {
+          "event_id" => event_id,
+          "payload" => serialized_payload,
+          "published_at" => Time.now.utc.iso8601(6)
+        }
+      end
+    end
+  end
+end

data/lib/pgbus/event_bus/registry.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module Pgbus
+  module EventBus
+    class Registry
+      include Singleton
+
+      attr_reader :subscribers
+
+      def initialize
+        @subscribers = []
+        @mutex = Mutex.new
+      end
+
+      def subscribe(pattern, handler_class, queue_name: nil)
+        subscriber = Subscriber.new(
+          pattern: pattern,
+          handler_class: handler_class,
+          queue_name: queue_name
+        )
+
+        @mutex.synchronize do
+          @subscribers << subscriber
+        end
+
+        subscriber
+      end
+
+      def setup_all!
+        @subscribers.each(&:setup!)
+      end
+
+      def handlers_for(routing_key)
+        @subscribers.select { |s| matches?(s.pattern, routing_key) }
+      end
+
+      def clear!
+        @mutex.synchronize { @subscribers.clear }
+      end
+
+      private
+
+      def matches?(pattern, routing_key)
+        regex = pattern
+                .gsub(".", "\\.")
+                .gsub("*", "[^.]+")
+                .gsub("#", ".*")
+        routing_key.match?(/\A#{regex}\z/)
+      end
+    end
+  end
+end

data/lib/pgbus/event_bus/subscriber.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module EventBus
+    class Subscriber
+      attr_reader :pattern, :handler_class, :queue_name
+
+      def initialize(pattern:, handler_class:, queue_name: nil)
+        @pattern = pattern
+        @handler_class = handler_class
+        @queue_name = queue_name || derive_queue_name
+      end
+
+      def setup!
+        Pgbus.client.ensure_queue(queue_name)
+        Pgbus.client.bind_topic(pattern, queue_name)
+      end
+
+      private
+
+      def derive_queue_name
+        handler_class.name
+                     .gsub("::", "_")
+                     .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                     .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                     .downcase
+      end
+    end
+  end
+end