pgmq-ruby 0.1.0 → 0.4.0

data/lib/pgmq/client/multi_queue.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module PGMQ
+  class Client
+    # Multi-queue operations
+    #
+    # This module handles efficient operations across multiple queues using single
+    # database queries with UNION ALL for optimal performance.
+    module MultiQueue
+      # Reads from multiple queues in a single query
+      #
+      # This is the most efficient way to monitor multiple queues with a single
+      # database connection. Uses UNION ALL to read from all queues in one query.
+      #
+      # @param queue_names [Array<String>] array of queue names to read from
+      # @param vt [Integer] visibility timeout in seconds
+      # @param qty [Integer] max messages to read per queue
+      # @param limit [Integer, nil] max total messages across all queues (nil = all)
+      # @return [Array<PGMQ::Message>] array of messages with queue_name attribute
+      #
+      # @example Read from multiple queues (gets first available from any queue)
+      #   msg = client.read_multi(['orders', 'notifications', 'emails'], vt: 30, limit: 1).first
+      #   puts "Got message from: #{msg.queue_name}"
+      #
+      # @example Read up to 5 messages from any of the queues
+      #   messages = client.read_multi(['queue1', 'queue2', 'queue3'], vt: 30, qty: 5, limit: 5)
+      #   messages.each do |msg|
+      #     puts "Processing #{msg.queue_name}: #{msg.payload}"
+      #     client.delete(msg.queue_name, msg.msg_id)
+      #   end
+      #
+      # @example Poll all queues efficiently (single connection, single query)
+      #   loop do
+      #     messages = client.read_multi(
+      #       ['orders', 'emails', 'webhooks'],
+      #       vt: 30,
+      #       qty: 10,
+      #       limit: 10
+      #     )
+      #     break if messages.empty?
+      #     messages.each { |msg| process(msg) }
+      #   end
+      def read_multi(
+        queue_names,
+        vt: DEFAULT_VT,
+        qty: 1,
+        limit: nil
+      )
+        raise ArgumentError, 'queue_names must be an array' unless queue_names.is_a?(Array)
+        raise ArgumentError, 'queue_names cannot be empty' if queue_names.empty?
+        raise ArgumentError, 'queue_names cannot exceed 50 queues' if queue_names.size > 50
+
+        # Validate all queue names (prevents SQL injection)
+        queue_names.each { |qn| validate_queue_name!(qn) }
+
+        # Build UNION ALL query for all queues
+        # Note: Queue names are validated, so this is safe from SQL injection
+        union_queries = queue_names.map do |queue_name|
+          # Escape single quotes in queue name (though validation should prevent this)
+          escaped_name = queue_name.gsub("'", "''")
+          "SELECT '#{escaped_name}'::text as queue_name, * " \
+            "FROM pgmq.read('#{escaped_name}'::text, #{vt.to_i}, #{qty.to_i})"
+        end
+
+        sql = union_queries.join("\nUNION ALL\n")
+        sql += "\nLIMIT #{limit.to_i}" if limit
+
+        result = with_connection do |conn|
+          conn.exec(sql)
+        end
+
+        result.map do |row|
+          Message.new(row)
+        end
+      end
+
+      # Reads from multiple queues with long-polling (waits for messages)
+      #
+      # Efficiently polls multiple queues waiting for the first available message.
+      # This uses a single connection with periodic polling until a message arrives
+      # or the timeout is reached.
+      #
+      # @param queue_names [Array<String>] array of queue names to poll
+      # @param vt [Integer] visibility timeout in seconds
+      # @param qty [Integer] max messages to read per queue
+      # @param limit [Integer, nil] max total messages across all queues
+      # @param max_poll_seconds [Integer] maximum seconds to wait for messages
+      # @param poll_interval_ms [Integer] milliseconds between polls
+      # @return [Array<PGMQ::Message>] array of messages (empty if timeout)
+      #
+      # @example Wait for first available message from any queue
+      #   msg = client.read_multi_with_poll(
+      #     ['orders', 'notifications', 'emails'],
+      #     vt: 30,
+      #     max_poll_seconds: 5
+      #   ).first
+      #
+      # @example Worker loop with efficient multi-queue polling
+      #   loop do
+      #     messages = client.read_multi_with_poll(
+      #       ['queue1', 'queue2', 'queue3'],
+      #       vt: 30,
+      #       qty: 10,
+      #       limit: 10,
+      #       max_poll_seconds: 5
+      #     )
+      #
+      #     messages.each do |msg|
+      #       process(msg.queue_name, msg.payload)
+      #       client.delete(msg.queue_name, msg.msg_id)
+      #     end
+      #   end
+      def read_multi_with_poll(
+        queue_names,
+        vt: DEFAULT_VT,
+        qty: 1,
+        limit: nil,
+        max_poll_seconds: 5,
+        poll_interval_ms: 100
+      )
+        raise ArgumentError, 'queue_names must be an array' unless queue_names.is_a?(Array)
+        raise ArgumentError, 'queue_names cannot be empty' if queue_names.empty?
+        raise ArgumentError, 'queue_names cannot exceed 50 queues' if queue_names.size > 50
+
+        start_time = Time.now
+        poll_interval_seconds = poll_interval_ms / 1000.0
+
+        loop do
+          # Try to read from any queue
+          messages = read_multi(queue_names, vt: vt, qty: qty, limit: limit)
+          return messages if messages.any?
+
+          # Check timeout
+          elapsed = Time.now - start_time
+          break if elapsed >= max_poll_seconds
+
+          # Sleep for poll interval (or remaining time, whichever is less)
+          remaining = max_poll_seconds - elapsed
+          sleep [poll_interval_seconds, remaining].min
+        end
+
+        [] # Return empty array on timeout
+      end
+
+      # Pops a message from multiple queues (atomic read + delete)
+      #
+      # Efficiently gets and immediately deletes the first available message from
+      # any of the specified queues. Uses a single query with UNION ALL.
+      #
+      # @param queue_names [Array<String>] array of queue names
+      # @return [PGMQ::Message, nil] message with queue_name attribute, or nil if no messages
+      #
+      # @example Get first available message from any queue and auto-delete
+      #   msg = client.pop_multi(['orders', 'notifications', 'emails'])
+      #   if msg
+      #     puts "Got message from #{msg.queue_name}"
+      #     process(msg.payload)
+      #     # No need to delete - already deleted!
+      #   end
+      #
+      # @example Worker loop with atomic pop from multiple queues
+      #   loop do
+      #     msg = client.pop_multi(['queue1', 'queue2', 'queue3'])
+      #     break unless msg
+      #     process(msg.queue_name, msg.payload)
+      #   end
+      def pop_multi(queue_names)
+        raise ArgumentError, 'queue_names must be an array' unless queue_names.is_a?(Array)
+        raise ArgumentError, 'queue_names cannot be empty' if queue_names.empty?
+        raise ArgumentError, 'queue_names cannot exceed 50 queues' if queue_names.size > 50
+
+        # Validate all queue names
+        queue_names.each { |qn| validate_queue_name!(qn) }
+
+        # Build UNION ALL query for all queues
+        union_queries = queue_names.map do |queue_name|
+          escaped_name = queue_name.gsub("'", "''")
+          "SELECT '#{escaped_name}'::text as queue_name, * FROM pgmq.pop('#{escaped_name}'::text)"
+        end
+
+        sql = "#{union_queries.join("\nUNION ALL\n")}\nLIMIT 1"
+
+        result = with_connection do |conn|
+          conn.exec(sql)
+        end
+
+        return nil if result.ntuples.zero?
+
+        Message.new(result[0])
+      end
+    end
+  end
+end

data/lib/pgmq/client/producer.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module PGMQ
+  class Client
+    # Message producing operations
+    #
+    # This module handles producing messages to queues, both individual messages
+    # and batches. Users must serialize messages to JSON strings themselves.
+    module Producer
+      # Produces a message to a queue
+      #
+      # @param queue_name [String] name of the queue
+      # @param message [String] message as JSON string (for PostgreSQL JSONB)
+      # @param headers [String, nil] optional headers as JSON string (for metadata, routing, tracing)
+      # @param delay [Integer] delay in seconds before message becomes visible
+      # @return [String] message ID as string
+      #
+      # @example Basic produce
+      #   msg_id = client.produce("orders", '{"order_id":123,"total":99.99}')
+      #
+      # @example With delay
+      #   msg_id = client.produce("orders", '{"data":"value"}', delay: 60)
+      #
+      # @example With headers for routing/tracing
+      #   msg_id = client.produce("orders", '{"order_id":123}',
+      #     headers: '{"trace_id":"abc123","priority":"high"}')
+      #
+      # @example With headers and delay
+      #   msg_id = client.produce("orders", '{"order_id":123}',
+      #     headers: '{"correlation_id":"req-456"}',
+      #     delay: 30)
+      #
+      # @note Users must serialize to JSON themselves. Higher-level frameworks
+      #       should handle serialization.
+      def produce(
+        queue_name,
+        message,
+        headers: nil,
+        delay: 0
+      )
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          if headers
+            conn.exec_params(
+              'SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::jsonb, $4::integer)',
+              [queue_name, message, headers, delay]
+            )
+          else
+            conn.exec_params(
+              'SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::integer)',
+              [queue_name, message, delay]
+            )
+          end
+        end
+
+        result[0]['send']
+      end
+
+      # Produces multiple messages to a queue in a batch
+      #
+      # @param queue_name [String] name of the queue
+      # @param messages [Array<String>] array of message payloads as JSON strings
+      # @param headers [Array<String>, nil] optional array of headers as JSON strings (must match messages length)
+      # @param delay [Integer] delay in seconds before messages become visible
+      # @return [Array<String>] array of message IDs
+      # @raise [ArgumentError] if headers array length doesn't match messages length
+      #
+      # @example Basic batch produce
+      #   ids = client.produce_batch("orders", [
+      #     '{"order_id":1}',
+      #     '{"order_id":2}',
+      #     '{"order_id":3}'
+      #   ])
+      #
+      # @example With headers (one per message)
+      #   ids = client.produce_batch("orders",
+      #     ['{"order_id":1}', '{"order_id":2}'],
+      #     headers: ['{"priority":"high"}', '{"priority":"low"}'])
+      #
+      # @example With headers and delay
+      #   ids = client.produce_batch("orders",
+      #     ['{"order_id":1}', '{"order_id":2}'],
+      #     headers: ['{"trace_id":"a"}', '{"trace_id":"b"}'],
+      #     delay: 60)
+      def produce_batch(
+        queue_name,
+        messages,
+        headers: nil,
+        delay: 0
+      )
+        validate_queue_name!(queue_name)
+        return [] if messages.empty?
+
+        if headers && headers.length != messages.length
+          raise ArgumentError,
+                "headers array length (#{headers.length}) must match messages array length (#{messages.length})"
+        end
+
+        # Use PostgreSQL array parameter binding for security
+        # PG gem will properly encode the array values
+        result = with_connection do |conn|
+          # Create array encoder for proper PostgreSQL array formatting
+          encoder = PG::TextEncoder::Array.new
+          encoded_messages = encoder.encode(messages)
+
+          if headers
+            encoded_headers = encoder.encode(headers)
+            conn.exec_params(
+              'SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::jsonb[], $4::integer)',
+              [queue_name, encoded_messages, encoded_headers, delay]
+            )
+          else
+            conn.exec_params(
+              'SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::integer)',
+              [queue_name, encoded_messages, delay]
+            )
+          end
+        end
+
+        result.map { |row| row['send_batch'] }
+      end
+    end
+  end
+end

data/lib/pgmq/client/queue_management.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module PGMQ
+  class Client
+    # Queue management operations (create, drop, list)
+    #
+    # This module handles all queue lifecycle operations including creating queues
+    # (standard, partitioned, unlogged), dropping queues, and listing existing queues.
+    module QueueManagement
+      # Creates a new queue
+      #
+      # @param queue_name [String] name of the queue to create
+      # @return [Boolean] true if queue was created, false if it already existed
+      # @raise [PGMQ::Errors::InvalidQueueNameError] if queue name is invalid
+      # @raise [PGMQ::Errors::ConnectionError] if database operation fails
+      #
+      # @example
+      #   client.create("orders")  # => true (created)
+      #   client.create("orders")  # => false (already exists)
+      def create(queue_name)
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          existed = queue_exists?(conn, queue_name)
+          conn.exec_params('SELECT pgmq.create($1::text)', [queue_name])
+          !existed
+        end
+      end
+
+      # Creates a partitioned queue
+      #
+      # Requires pg_partman extension to be installed
+      #
+      # @param queue_name [String] name of the queue
+      # @param partition_interval [String] partition interval (e.g., "daily", "10000")
+      # @param retention_interval [String] retention interval (e.g., "7 days", "100000")
+      # @return [Boolean] true if queue was created, false if it already existed
+      #
+      # @example
+      #   client.create_partitioned("big_queue",
+      #     partition_interval: "daily",
+      #     retention_interval: "7 days"
+      #   )  # => true
+      def create_partitioned(
+        queue_name,
+        partition_interval: '10000',
+        retention_interval: '100000'
+      )
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          existed = queue_exists?(conn, queue_name)
+          conn.exec_params(
+            'SELECT pgmq.create_partitioned($1::text, $2::text, $3::text)',
+            [queue_name, partition_interval, retention_interval]
+          )
+          !existed
+        end
+      end
+
+      # Creates an unlogged queue for higher throughput (no crash recovery)
+      #
+      # @param queue_name [String] name of the queue
+      # @return [Boolean] true if queue was created, false if it already existed
+      #
+      # @example
+      #   client.create_unlogged("fast_queue")  # => true
+      def create_unlogged(queue_name)
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          existed = queue_exists?(conn, queue_name)
+          conn.exec_params('SELECT pgmq.create_unlogged($1::text)', [queue_name])
+          !existed
+        end
+      end
+
+      # Drops a queue and its archive table
+      #
+      # @param queue_name [String] name of the queue to drop
+      # @return [Boolean] true if queue was dropped
+      #
+      # @example
+      #   client.drop_queue("old_queue")
+      def drop_queue(queue_name)
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params('SELECT pgmq.drop_queue($1::text)', [queue_name])
+        end
+
+        return false if result.ntuples.zero?
+
+        result[0]['drop_queue'] == 't'
+      end
+
+      # Lists all queues
+      #
+      # @return [Array<PGMQ::QueueMetadata>] array of queue metadata objects
+      #
+      # @example
+      #   queues = client.list_queues
+      #   queues.each { |q| puts q.queue_name }
+      def list_queues
+        result = with_connection do |conn|
+          conn.exec('SELECT * FROM pgmq.list_queues()')
+        end
+
+        result.map { |row| QueueMetadata.new(row) }
+      end
+
+      private
+
+      # Checks if a queue exists in the pgmq.meta table
+      #
+      # @param conn [PG::Connection] database connection
+      # @param queue_name [String] name of the queue to check
+      # @return [Boolean] true if queue exists, false otherwise
+      def queue_exists?(conn, queue_name)
+        result = conn.exec_params(
+          'SELECT 1 FROM pgmq.meta WHERE queue_name = $1 LIMIT 1',
+          [queue_name]
+        )
+        result.ntuples.positive?
+      end
+    end
+  end
+end

data/lib/pgmq/client.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module PGMQ
+  # Low-level client for interacting with PGMQ (Postgres Message Queue)
+  #
+  # This is a thin wrapper around PGMQ SQL functions. For higher-level
+  # abstractions (job processing, retries, Rails integration), use pgmq-framework.
+  #
+  # @example Basic usage
+  #   client = PGMQ::Client.new(
+  #     host: 'localhost',
+  #     dbname: 'mydb',
+  #     user: 'postgres',
+  #     password: 'postgres'
+  #   )
+  #   client.create('my_queue')
+  #   msg_id = client.produce('my_queue', '{"data":"value"}')
+  #   msg = client.read('my_queue', vt: 30)
+  #   client.delete('my_queue', msg.msg_id)
+  #
+  # @example With Rails/ActiveRecord (reuses Rails connection pool)
+  #   client = PGMQ::Client.new(-> { ActiveRecord::Base.connection.raw_connection })
+  #
+  # @example With connection string
+  #   client = PGMQ::Client.new('postgres://localhost/mydb')
+  class Client
+    # Include functional modules (order matters for discoverability)
+    include Transaction          # Transaction support (already existed)
+    include QueueManagement      # Queue lifecycle (create, drop, list)
+    include Producer             # Message producing operations
+    include Consumer             # Single-queue reading operations
+    include MultiQueue           # Multi-queue operations
+    include MessageLifecycle     # Message state transitions (pop, delete, archive)
+    include Maintenance          # Queue maintenance (purge, detach_archive)
+    include Metrics              # Monitoring and metrics
+
+    # Default visibility timeout in seconds
+    DEFAULT_VT = 30
+
+    # @return [PGMQ::Connection] the connection manager
+    attr_reader :connection
+
+    # Creates a new PGMQ client
+    #
+    # @param conn_params [String, Hash, Proc, PGMQ::Connection, nil] connection parameters
+    # @param pool_size [Integer] connection pool size
+    # @param pool_timeout [Integer] connection pool timeout in seconds
+    # @param auto_reconnect [Boolean] automatically reconnect on connection errors (default: true)
+    #
+    # @example Connection string
+    #   client = PGMQ::Client.new('postgres://user:pass@localhost/db')
+    #
+    # @example Connection hash
+    #   client = PGMQ::Client.new(host: 'localhost', dbname: 'mydb', user: 'postgres')
+    #
+    # @example Inject existing connection (for Rails)
+    #   client = PGMQ::Client.new(-> { ActiveRecord::Base.connection.raw_connection })
+    #
+    # @example Disable auto-reconnect
+    #   client = PGMQ::Client.new(auto_reconnect: false)
+    def initialize(
+      conn_params = nil,
+      pool_size: Connection::DEFAULT_POOL_SIZE,
+      pool_timeout: Connection::DEFAULT_POOL_TIMEOUT,
+      auto_reconnect: true
+    )
+      @connection = if conn_params.is_a?(Connection)
+                      conn_params
+                    else
+                      Connection.new(
+                        conn_params,
+                        pool_size: pool_size,
+                        pool_timeout: pool_timeout,
+                        auto_reconnect: auto_reconnect
+                      )
+                    end
+    end
+
+    # Closes all connections in the pool
+    # @return [void]
+    def close
+      @connection.close
+    end
+
+    # Returns connection pool statistics
+    #
+    # @return [Hash] statistics about the connection pool
+    # @example
+    #   stats = client.stats
+    #   # => { size: 5, available: 3 }
+    def stats
+      @connection.stats
+    end
+
+    private
+
+    # Executes a block with a database connection
+    # @yield [PG::Connection] database connection
+    # @return [Object] result of the block
+    def with_connection(&)
+      @connection.with_connection(&)
+    end
+
+    # Validates a queue name
+    # @param queue_name [String] queue name to validate
+    # @return [void]
+    # @raise [PGMQ::Errors::InvalidQueueNameError] if name is invalid
+    def validate_queue_name!(queue_name)
+      if queue_name.nil? || queue_name.to_s.strip.empty?
+        raise(
+          Errors::InvalidQueueNameError,
+          'Queue name cannot be empty'
+        )
+      end
+
+      # PGMQ creates tables with prefixes (pgmq.q_<name>, pgmq.a_<name>)
+      # PostgreSQL has a 63-character limit for identifiers, but PGMQ enforces 48
+      # to account for prefixes and potential suffixes
+      if queue_name.to_s.length >= 48
+        raise(
+          Errors::InvalidQueueNameError,
+          "Queue name '#{queue_name}' exceeds maximum length of 48 characters " \
+          "(current length: #{queue_name.to_s.length})"
+        )
+      end
+
+      # PostgreSQL identifier rules: start with letter or underscore,
+      # contain only letters, digits, underscores
+      return if queue_name.to_s.match?(/\A[a-zA-Z_][a-zA-Z0-9_]*\z/)
+
+      raise(
+        Errors::InvalidQueueNameError,
+        "Invalid queue name '#{queue_name}': must start with a letter or underscore " \
+        'and contain only letters, digits, and underscores'
+      )
+    end
+  end
+end