pgmq-ruby 0.1.0 → 0.4.0

data/lib/pgmq/client/consumer.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module PGMQ
+  class Client
+    # Single-queue message reading operations
+    #
+    # This module handles reading messages from a single queue, including basic reads,
+    # batch reads, and long-polling for efficient message consumption.
+    module Consumer
+      # Reads a message from the queue
+      #
+      # @param queue_name [String] name of the queue
+      # @param vt [Integer] visibility timeout in seconds
+      # @param conditional [Hash] optional JSONB filter for message payload
+      # @return [PGMQ::Message, nil] message object or nil if queue is empty
+      #
+      # @example
+      #   msg = client.read("orders", vt: 30)
+      #   if msg
+      #     process(msg.payload)
+      #     client.delete("orders", msg.msg_id)
+      #   end
+      #
+      # @example With conditional filtering
+      #   msg = client.read("orders", vt: 30, conditional: { type: "priority", status: "pending" })
+      def read(
+        queue_name,
+        vt: DEFAULT_VT,
+        conditional: {}
+      )
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          if conditional.empty?
+            conn.exec_params(
+              'SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer)',
+              [queue_name, vt, 1]
+            )
+          else
+            conn.exec_params(
+              'SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer, $4::jsonb)',
+              [queue_name, vt, 1, conditional.to_json]
+            )
+          end
+        end
+
+        return nil if result.ntuples.zero?
+
+        Message.new(result[0])
+      end
+
+      # Reads multiple messages from the queue
+      #
+      # @param queue_name [String] name of the queue
+      # @param vt [Integer] visibility timeout in seconds
+      # @param qty [Integer] number of messages to read
+      # @param conditional [Hash] optional JSONB filter for message payload
+      # @return [Array<PGMQ::Message>] array of messages
+      #
+      # @example
+      #   messages = client.read_batch("orders", vt: 30, qty: 10)
+      #   messages.each do |msg|
+      #     process(msg.payload)
+      #     client.delete("orders", msg.msg_id)
+      #   end
+      #
+      # @example With conditional filtering
+      #   messages = client.read_batch(
+      #     "orders",
+      #     vt: 30,
+      #     qty: 10,
+      #     conditional: { priority: "high" }
+      #   )
+      def read_batch(
+        queue_name,
+        vt: DEFAULT_VT,
+        qty: 1,
+        conditional: {}
+      )
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          if conditional.empty?
+            conn.exec_params(
+              'SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer)',
+              [queue_name, vt, qty]
+            )
+          else
+            conn.exec_params(
+              'SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer, $4::jsonb)',
+              [queue_name, vt, qty, conditional.to_json]
+            )
+          end
+        end
+
+        result.map { |row| Message.new(row) }
+      end
+
+      # Reads messages with long-polling support
+      #
+      # Polls the queue for messages, waiting up to max_poll_seconds if queue is empty
+      #
+      # @param queue_name [String] name of the queue
+      # @param vt [Integer] visibility timeout in seconds
+      # @param qty [Integer] number of messages to read
+      # @param max_poll_seconds [Integer] maximum time to poll in seconds
+      # @param poll_interval_ms [Integer] interval between polls in milliseconds
+      # @param conditional [Hash] optional JSONB filter for message payload
+      # @return [Array<PGMQ::Message>] array of messages
+      #
+      # @example
+      #   messages = client.read_with_poll("orders",
+      #     vt: 30,
+      #     qty: 5,
+      #     max_poll_seconds: 10,
+      #     poll_interval_ms: 250
+      #   )
+      #
+      # @example With conditional filtering
+      #   messages = client.read_with_poll("orders",
+      #     vt: 30,
+      #     qty: 5,
+      #     conditional: { status: "pending" }
+      #   )
+      def read_with_poll(
+        queue_name,
+        vt: DEFAULT_VT,
+        qty: 1,
+        max_poll_seconds: 5,
+        poll_interval_ms: 100,
+        conditional: {}
+      )
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          if conditional.empty?
+            conn.exec_params(
+              'SELECT * FROM pgmq.read_with_poll($1::text, $2::integer, $3::integer, $4::integer, $5::integer)',
+              [queue_name, vt, qty, max_poll_seconds, poll_interval_ms]
+            )
+          else
+            sql = 'SELECT * FROM pgmq.read_with_poll($1::text, $2::integer, $3::integer, ' \
+                  '$4::integer, $5::integer, $6::jsonb)'
+            conn.exec_params(
+              sql,
+              [queue_name, vt, qty, max_poll_seconds, poll_interval_ms, conditional.to_json]
+            )
+          end
+        end
+
+        result.map { |row| Message.new(row) }
+      end
+    end
+  end
+end

data/lib/pgmq/client/maintenance.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module PGMQ
+  class Client
+    # Queue maintenance operations
+    #
+    # This module handles queue maintenance tasks such as purging messages
+    # and detaching archive tables.
+    module Maintenance
+      # Purges all messages from a queue
+      #
+      # @param queue_name [String] name of the queue
+      # @return [Integer] number of messages purged
+      #
+      # @example
+      #   count = client.purge_queue("old_queue")
+      #   puts "Purged #{count} messages"
+      def purge_queue(queue_name)
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params('SELECT pgmq.purge_queue($1::text)', [queue_name])
+        end
+
+        result[0]['purge_queue']
+      end
+
+      # Detaches the archive table from PGMQ management
+      #
+      # @param queue_name [String] name of the queue
+      # @return [void]
+      #
+      # @example
+      #   client.detach_archive("orders")
+      def detach_archive(queue_name)
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          conn.exec_params('SELECT pgmq.detach_archive($1::text)', [queue_name])
+        end
+
+        nil
+      end
+
+      # Enables PostgreSQL NOTIFY when messages are inserted into a queue
+      #
+      # When enabled, PostgreSQL will send a NOTIFY event on message insert,
+      # allowing clients to use LISTEN instead of polling. The throttle interval
+      # prevents notification storms during high-volume inserts.
+      #
+      # @param queue_name [String] name of the queue
+      # @param throttle_interval_ms [Integer] minimum ms between notifications (default: 250)
+      # @return [void]
+      #
+      # @example Enable with default throttle (250ms)
+      #   client.enable_notify_insert("orders")
+      #
+      # @example Enable with custom throttle (1 second)
+      #   client.enable_notify_insert("orders", throttle_interval_ms: 1000)
+      #
+      # @example Disable throttling (notify on every insert)
+      #   client.enable_notify_insert("orders", throttle_interval_ms: 0)
+      def enable_notify_insert(queue_name, throttle_interval_ms: 250)
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          conn.exec_params(
+            'SELECT pgmq.enable_notify_insert($1::text, $2::integer)',
+            [queue_name, throttle_interval_ms]
+          )
+        end
+
+        nil
+      end
+
+      # Disables PostgreSQL NOTIFY for a queue
+      #
+      # @param queue_name [String] name of the queue
+      # @return [void]
+      #
+      # @example
+      #   client.disable_notify_insert("orders")
+      def disable_notify_insert(queue_name)
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          conn.exec_params('SELECT pgmq.disable_notify_insert($1::text)', [queue_name])
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/pgmq/client/message_lifecycle.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+module PGMQ
+  class Client
+    # Message lifecycle operations (pop, delete, archive, visibility timeout)
+    #
+    # This module handles message state transitions including popping (atomic read+delete),
+    # deleting, archiving, and updating visibility timeouts.
+    module MessageLifecycle
+      # Pops a message (atomic read + delete)
+      #
+      # @param queue_name [String] name of the queue
+      # @return [PGMQ::Message, nil] message object or nil if queue is empty
+      #
+      # @example
+      #   msg = client.pop("orders")
+      #   process(msg.payload) if msg
+      def pop(queue_name)
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params('SELECT * FROM pgmq.pop($1::text)', [queue_name])
+        end
+
+        return nil if result.ntuples.zero?
+
+        Message.new(result[0])
+      end
+
+      # Pops multiple messages atomically (atomic read + delete for batch)
+      #
+      # @param queue_name [String] name of the queue
+      # @param qty [Integer] maximum number of messages to pop
+      # @return [Array<PGMQ::Message>] array of message objects (empty if queue is empty)
+      #
+      # @example Pop up to 10 messages
+      #   messages = client.pop_batch("orders", 10)
+      #   messages.each { |msg| process(msg.payload) }
+      def pop_batch(queue_name, qty)
+        validate_queue_name!(queue_name)
+        return [] if qty <= 0
+
+        result = with_connection do |conn|
+          conn.exec_params('SELECT * FROM pgmq.pop($1::text, $2::integer)', [queue_name, qty])
+        end
+
+        result.map { |row| Message.new(row) }
+      end
+
+      # Deletes a message from the queue
+      #
+      # @param queue_name [String] name of the queue
+      # @param msg_id [Integer] message ID to delete
+      # @return [Boolean] true if message was deleted
+      #
+      # @example
+      #   client.delete("orders", 123)
+      def delete(
+        queue_name,
+        msg_id
+      )
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params(
+            'SELECT pgmq.delete($1::text, $2::bigint)',
+            [queue_name, msg_id]
+          )
+        end
+
+        return false if result.ntuples.zero?
+
+        result[0]['delete'] == 't'
+      end
+
+      # Deletes multiple messages from the queue
+      #
+      # @param queue_name [String] name of the queue
+      # @param msg_ids [Array<Integer>] array of message IDs to delete
+      # @return [Array<Integer>] array of successfully deleted message IDs
+      #
+      # @example
+      #   deleted = client.delete_batch("orders", [101, 102, 103])
+      def delete_batch(
+        queue_name,
+        msg_ids
+      )
+        validate_queue_name!(queue_name)
+        return [] if msg_ids.empty?
+
+        # Use PostgreSQL array parameter binding
+        result = with_connection do |conn|
+          encoder = PG::TextEncoder::Array.new
+          encoded_array = encoder.encode(msg_ids)
+
+          conn.exec_params(
+            'SELECT * FROM pgmq.delete($1::text, $2::bigint[])',
+            [queue_name, encoded_array]
+          )
+        end
+
+        result.map { |row| row['delete'] }
+      end
+
+      # Deletes specific messages from multiple queues in a single transaction
+      #
+      # Efficiently deletes messages across different queues atomically.
+      # Useful when processing related messages from different queues.
+      #
+      # @param deletions [Hash] hash of queue_name => array of msg_ids
+      # @return [Hash] hash of queue_name => array of deleted msg_ids
+      #
+      # @example Delete messages from multiple queues
+      #   client.delete_multi({
+      #     'orders' => [1, 2, 3],
+      #     'notifications' => [5, 6],
+      #     'emails' => [10]
+      #   })
+      #   # => { 'orders' => [1, 2, 3], 'notifications' => [5, 6], 'emails' => [10] }
+      #
+      # @example Clean up after batch processing across queues
+      #   messages = client.read_multi(['q1', 'q2', 'q3'], qty: 10)
+      #   deletions = messages.group_by(&:queue_name).transform_values { |mss| mss.map(&:msg_id) }
+      #   client.delete_multi(deletions)
+      def delete_multi(deletions)
+        raise ArgumentError, 'deletions must be a hash' unless deletions.is_a?(Hash)
+        return {} if deletions.empty?
+
+        # Validate all queue names
+        deletions.each_key { |qn| validate_queue_name!(qn) }
+
+        transaction do |txn|
+          result = {}
+          deletions.each do |queue_name, msg_ids|
+            next if msg_ids.empty?
+
+            deleted_ids = txn.delete_batch(queue_name, msg_ids)
+            result[queue_name] = deleted_ids
+          end
+          result
+        end
+      end
+
+      # Archives a message
+      #
+      # @param queue_name [String] name of the queue
+      # @param msg_id [Integer] message ID to archive
+      # @return [Boolean] true if message was archived
+      #
+      # @example
+      #   client.archive("orders", 123)
+      def archive(
+        queue_name,
+        msg_id
+      )
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params(
+            'SELECT pgmq.archive($1::text, $2::bigint)',
+            [queue_name, msg_id]
+          )
+        end
+
+        return false if result.ntuples.zero?
+
+        result[0]['archive'] == 't'
+      end
+
+      # Archives multiple messages
+      #
+      # @param queue_name [String] name of the queue
+      # @param msg_ids [Array<Integer>] array of message IDs to archive
+      # @return [Array<Integer>] array of successfully archived message IDs
+      #
+      # @example
+      #   archived = client.archive_batch("orders", [101, 102, 103])
+      def archive_batch(
+        queue_name,
+        msg_ids
+      )
+        validate_queue_name!(queue_name)
+        return [] if msg_ids.empty?
+
+        # Use PostgreSQL array parameter binding
+        result = with_connection do |conn|
+          encoder = PG::TextEncoder::Array.new
+          encoded_array = encoder.encode(msg_ids)
+
+          conn.exec_params(
+            'SELECT * FROM pgmq.archive($1::text, $2::bigint[])',
+            [queue_name, encoded_array]
+          )
+        end
+
+        result.map { |row| row['archive'] }
+      end
+
+      # Archives specific messages from multiple queues in a single transaction
+      #
+      # Efficiently archives messages across different queues atomically.
+      #
+      # @param archives [Hash] hash of queue_name => array of msg_ids
+      # @return [Hash] hash of queue_name => array of archived msg_ids
+      #
+      # @example Archive messages from multiple queues
+      #   client.archive_multi({
+      #     'orders' => [1, 2],
+      #     'notifications' => [5]
+      #   })
+      def archive_multi(archives)
+        raise ArgumentError, 'archives must be a hash' unless archives.is_a?(Hash)
+        return {} if archives.empty?
+
+        # Validate all queue names
+        archives.each_key { |qn| validate_queue_name!(qn) }
+
+        transaction do |txn|
+          result = {}
+          archives.each do |queue_name, msg_ids|
+            next if msg_ids.empty?
+
+            archived_ids = txn.archive_batch(queue_name, msg_ids)
+            result[queue_name] = archived_ids
+          end
+          result
+        end
+      end
+
+      # Updates the visibility timeout for a message
+      #
+      # @param queue_name [String] name of the queue
+      # @param msg_id [Integer] message ID
+      # @param vt_offset [Integer] visibility timeout offset in seconds
+      # @return [PGMQ::Message, nil] updated message or nil if not found
+      #
+      # @example
+      #   # Extend processing time by 60 more seconds
+      #   msg = client.set_vt("orders", 123, vt_offset: 60)
+      def set_vt(
+        queue_name,
+        msg_id,
+        vt_offset:
+      )
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params(
+            'SELECT * FROM pgmq.set_vt($1::text, $2::bigint, $3::integer)',
+            [queue_name, msg_id, vt_offset]
+          )
+        end
+
+        return nil if result.ntuples.zero?
+
+        Message.new(result[0])
+      end
+
+      # Updates visibility timeout for multiple messages
+      #
+      # @param queue_name [String] name of the queue
+      # @param msg_ids [Array<Integer>] array of message IDs
+      # @param vt_offset [Integer] visibility timeout offset in seconds
+      # @return [Array<PGMQ::Message>] array of updated messages
+      #
+      # @example
+      #   # Extend processing time for multiple messages
+      #   messages = client.set_vt_batch("orders", [101, 102, 103], vt_offset: 60)
+      def set_vt_batch(
+        queue_name,
+        msg_ids,
+        vt_offset:
+      )
+        validate_queue_name!(queue_name)
+        return [] if msg_ids.empty?
+
+        result = with_connection do |conn|
+          encoder = PG::TextEncoder::Array.new
+          encoded_array = encoder.encode(msg_ids)
+
+          conn.exec_params(
+            'SELECT * FROM pgmq.set_vt($1::text, $2::bigint[], $3::integer)',
+            [queue_name, encoded_array, vt_offset]
+          )
+        end
+
+        result.map { |row| Message.new(row) }
+      end
+
+      # Updates visibility timeout for messages across multiple queues in a single transaction
+      #
+      # Efficiently updates visibility timeouts across different queues atomically.
+      # Useful when processing related messages from different queues and needing
+      # to extend their visibility timeouts together.
+      #
+      # @param updates [Hash] hash of queue_name => array of msg_ids
+      # @param vt_offset [Integer] visibility timeout offset in seconds (applied to all)
+      # @return [Hash] hash of queue_name => array of updated PGMQ::Message objects
+      #
+      # @example Extend visibility timeout for messages from multiple queues
+      #   client.set_vt_multi({
+      #     'orders' => [1, 2, 3],
+      #     'notifications' => [5, 6],
+      #     'emails' => [10]
+      #   }, vt_offset: 60)
+      #   # => { 'orders' => [<Message>, ...], 'notifications' => [...], 'emails' => [...] }
+      #
+      # @example Extend timeout after batch reading from multiple queues
+      #   messages = client.read_multi(['q1', 'q2', 'q3'], qty: 10)
+      #   updates = messages.group_by(&:queue_name).transform_values { |msgs| msgs.map(&:msg_id) }
+      #   client.set_vt_multi(updates, vt_offset: 120)
+      def set_vt_multi(updates, vt_offset:)
+        raise ArgumentError, 'updates must be a hash' unless updates.is_a?(Hash)
+        return {} if updates.empty?
+
+        # Validate all queue names
+        updates.each_key { |qn| validate_queue_name!(qn) }
+
+        transaction do |txn|
+          result = {}
+          updates.each do |queue_name, msg_ids|
+            next if msg_ids.empty?
+
+            updated_messages = txn.set_vt_batch(queue_name, msg_ids, vt_offset: vt_offset)
+            result[queue_name] = updated_messages
+          end
+          result
+        end
+      end
+    end
+  end
+end

data/lib/pgmq/client/metrics.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module PGMQ
+  class Client
+    # Queue metrics and monitoring
+    #
+    # This module handles retrieving queue metrics such as queue length,
+    # message age, and total message counts.
+    module Metrics
+      # Gets metrics for a specific queue
+      #
+      # @param queue_name [String] name of the queue
+      # @return [PGMQ::Metrics] metrics object
+      #
+      # @example
+      #   metrics = client.metrics("orders")
+      #   puts "Queue length: #{metrics.queue_length}"
+      #   puts "Oldest message: #{metrics.oldest_msg_age_sec}s"
+      def metrics(queue_name)
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params('SELECT * FROM pgmq.metrics($1::text)', [queue_name])
+        end
+
+        return nil if result.ntuples.zero?
+
+        PGMQ::Metrics.new(result[0])
+      end
+
+      # Gets metrics for all queues
+      #
+      # @return [Array<PGMQ::Metrics>] array of metrics objects
+      #
+      # @example
+      #   all_metrics = client.metrics_all
+      #   all_metrics.each do |m|
+      #     puts "#{m.queue_name}: #{m.queue_length} messages"
+      #   end
+      def metrics_all
+        result = with_connection do |conn|
+          conn.exec('SELECT * FROM pgmq.metrics_all()')
+        end
+
+        result.map { |row| PGMQ::Metrics.new(row) }
+      end
+    end
+  end
+end