pgmq-ruby 0.6.1 → 0.7.0

data/lib/pgmq/connection.rb

@@ -26,6 +26,92 @@ module PGMQ
     # Default connection pool timeout in seconds
     DEFAULT_POOL_TIMEOUT = 5
 
+    class << self
+      # Additional error message patterns (String or Regexp) that mean the connection is dead and a retry on a fresh
+      # socket is safe. Strings are matched as case-insensitive substrings; Regexps match the original message. The
+      # built-in LOST_CONNECTION_MESSAGES are always checked first - this list is appended to them.
+      #
+      # Thread-safe: reads are lock-free (frozen array swap); writes should be done at boot time before forking workers.
+      #
+      # @return [Array<String, Regexp>]
+      # @example
+      #   PGMQ::Connection.reconnectable_error_patterns << "connection reset by peer"
+      #   PGMQ::Connection.reconnectable_error_patterns << /\Abroken pipe\b/i
+      attr_reader :reconnectable_error_patterns
+
+      # Additional exception classes that mean the connection is dead. `PG::ConnectionBad` and `PG::UnableToSend` are
+      # always matched - this list is appended to them. Subclasses also match.
+      #
+      # Thread-safe: reads are lock-free; writes should be done at boot time.
+      #
+      # @return [Array<Class>]
+      # @example
+      #   PGMQ::Connection.reconnectable_error_classes << PG::ConnectionRefused
+      attr_reader :reconnectable_error_classes
+
+      # Replaces the extra reconnectable error patterns.
+      #
+      # @param patterns [Array<String, Regexp>]
+      # @raise [PGMQ::Errors::ConfigurationError] if any element is invalid
+      def reconnectable_error_patterns=(patterns)
+        @reconnectable_error_patterns = normalize_patterns(patterns)
+      end
+
+      # Replaces the extra reconnectable error classes.
+      #
+      # @param classes [Array<Class>]
+      # @raise [PGMQ::Errors::ConfigurationError] if any element is invalid
+      def reconnectable_error_classes=(classes)
+        @reconnectable_error_classes = normalize_classes(classes)
+      end
+
+      private
+
+      # Normalizes user-supplied reconnectable error patterns.
+      #
+      # Strings are downcased once at configuration time so the hot path (`connection_lost_error?`) only does substring
+      # checks. Regexps are passed through unchanged.
+      #
+      # @param patterns [Array<String, Regexp>, String, Regexp, nil]
+      # @return [Array<String, Regexp>]
+      def normalize_patterns(patterns)
+        Array(patterns).map do |pattern|
+          case pattern
+          when Regexp
+            pattern
+          when String
+            pattern.downcase
+          else
+            raise(
+              PGMQ::Errors::ConfigurationError,
+              "reconnectable_error_patterns must contain Strings or Regexps, got #{pattern.class}"
+            )
+          end
+        end.freeze
+      end
+
+      # Normalizes user-supplied reconnectable error classes.
+      #
+      # @param classes [Array<Class>, Class, nil]
+      # @return [Array<Class>]
+      def normalize_classes(classes)
+        Array(classes).map do |klass|
+          unless klass.is_a?(Class) && klass <= Exception
+            raise(
+              PGMQ::Errors::ConfigurationError,
+              "reconnectable_error_classes must contain Exception subclasses, got #{klass.inspect}"
+            )
+          end
+
+          klass
+        end.freeze
+      end
+    end
+
+    # Initialize class-level defaults (empty arrays, users append at boot)
+    @reconnectable_error_patterns = [].freeze
+    @reconnectable_error_classes = [].freeze
+
     # @return [ConnectionPool] the connection pool
     attr_reader :pool
 
@@ -107,37 +193,58 @@ module PGMQ
 
     private
 
-    # Checks if the error indicates a lost connection
+    # Messages libpq raises when the server/pooler has already torn down the socket. The list has grown organically with
+    # each pooler/TLS variant we see in the wild; the class check below catches future variants that libpq raises as
+    # `PG::ConnectionBad` or `PG::UnableToSend` without waiting for a new message to hit production.
+    LOST_CONNECTION_MESSAGES = [
+      "server closed the connection",
+      "connection not open",
+      "connection is closed",
+      "connection has been closed",
+      "no connection to the server",
+      "terminating connection",
+      "connection to server was lost",
+      "could not receive data from server",
+      "pqsocket() can't get socket descriptor",
+      "ssl error: unexpected eof",
+      "ssl syscall error"
+    ].freeze
+    private_constant :LOST_CONNECTION_MESSAGES
+
+    # Checks if the error indicates a lost connection.
+    #
+    # Matches in three steps: first by class (`PG::ConnectionBad` / `PG::UnableToSend` are dedicated connection-failure
+    # classes libpq raises regardless of message, plus any user-supplied classes), then by built-in message substrings
+    # for the bare `PG::Error` cases where libpq doesn't reach for the specific subclass, and finally by user-supplied
+    # patterns (strings matched as case-insensitive substrings, Regexps matched against the original message).
+    #
     # @param error [PG::Error] the error to check
-    # @return [Boolean] true if connection was lost
+    # @return [Boolean] true if the connection was lost and a retry on a
+    #   fresh connection is appropriate
     def connection_lost_error?(error)
-      # Common connection lost errors. Include the pg-gem C-extension message
-      # ("PQsocket() can't get socket descriptor") that is raised when the
-      # cached libpq socket descriptor is gone — e.g. after a server-side
-      # close by a connection pooler such as PgBouncer.
-      lost_connection_messages = [
-        "server closed the connection",
-        "connection not open",
-        "connection is closed",
-        "connection has been closed",
-        "no connection to the server",
-        "terminating connection",
-        "connection to server was lost",
-        "could not receive data from server",
-        "pqsocket() can't get socket descriptor"
-      ]
-
-      message = error.message.to_s.downcase
-      lost_connection_messages.any? { |pattern| message.include?(pattern) }
+      return true if error.is_a?(PG::ConnectionBad) || error.is_a?(PG::UnableToSend)
+
+      extra_classes = self.class.reconnectable_error_classes
+      return true if extra_classes.any? { |klass| error.is_a?(klass) }
+
+      original_message = error.message.to_s
+      downcased = original_message.downcase
+
+      return true if LOST_CONNECTION_MESSAGES.any? { |pattern| downcased.include?(pattern) }
+
+      self.class.reconnectable_error_patterns.any? do |pattern|
+        case pattern
+        when Regexp then pattern.match?(original_message)
+        else downcased.include?(pattern)
+        end
+      end
     end
 
     # Verifies a connection is alive and working.
     #
-    # Also resets when the connection reports `PG::CONNECTION_BAD`, which
-    # happens when the server (or an intermediate pooler such as PgBouncer)
-    # has closed the socket while the client-side `PG::Connection` object
-    # still exists. `#finished?` alone only catches connections closed
-    # explicitly from the client side.
+    # Also resets when the connection reports `PG::CONNECTION_BAD`, which happens when the server (or an intermediate
+    # pooler such as PgBouncer) has closed the socket while the client-side `PG::Connection` object still exists.
+    # `#finished?` alone only catches connections closed explicitly from the client side.
     #
     # @param conn [PG::Connection] connection to verify
     # @raise [PG::Error] if the reset itself fails
@@ -187,16 +294,15 @@ module PGMQ
       ConnectionPool.new(size: @pool_size, timeout: @pool_timeout) do
         conn = create_connection(params)
 
-        # Detect shared connections: if a callable returns the same PG::Connection
-        # object to multiple pool slots, concurrent use will corrupt libpq state
-        # (nil results, segfaults, wrong data). Fail fast with a clear message.
+        # Detect shared connections: if a callable returns the same PG::Connection object to multiple pool slots,
+        # concurrent use will corrupt libpq state (nil results, segfaults, wrong data). Fail fast with a clear message.
         if conn.is_a?(PG::Connection)
           seen_mutex.synchronize do
             if seen_connections.key?(conn)
               raise PGMQ::Errors::ConfigurationError,
                 "Connection callable returned the same PG::Connection object " \
                 "(object_id: #{conn.object_id}) to multiple pool slots. " \
-                "PG::Connection is NOT thread-safe — concurrent use causes nil results, " \
+                "PG::Connection is NOT thread-safe - concurrent use causes nil results, " \
                 "segfaults, and data corruption. Ensure your callable returns a unique " \
                 "PG::Connection instance on each invocation (for example, by calling " \
                 "PG.connect inside the callable)."
@@ -219,10 +325,10 @@ module PGMQ
       # If we have a callable (e.g., for Rails), call it to get the connection
       return params.call if params.respond_to?(:call)
 
-      # Create new connection from parameters
-      # Low-level library: return all values as strings from PostgreSQL
-      # No automatic type conversion - let higher-level frameworks handle parsing
-      # conn.type_map_for_results intentionally NOT set
+      # Create new connection from parameters.
+      # Low-level library: return all values as strings from PostgreSQL.
+      # No automatic type conversion - let higher-level frameworks handle parsing.
+      # conn.type_map_for_results intentionally NOT set.
       PG.connect(params[:conninfo] || params)
     rescue PG::Error => e
       raise PGMQ::Errors::ConnectionError, "Failed to connect to database: #{e.message}"

data/lib/pgmq/message.rb

@@ -3,8 +3,8 @@
 module PGMQ
   # Represents a message read from a PGMQ queue
   #
-  # Returns raw values from PostgreSQL without transformation.
-  # Higher-level frameworks should handle parsing, deserialization, etc.
+  # Returns raw values from PostgreSQL without transformation. Higher-level frameworks should handle parsing,
+  # deserialization, etc.
   #
   # @example Reading a message (raw values)
   #   msg = client.read("my_queue", vt: 30)
@@ -24,9 +24,8 @@ module PGMQ
       # @param row [Hash] database row from PG result
       # @return [Message]
       def new(row, **)
-        # Return raw values as-is from PostgreSQL
-        # No parsing, no deserialization, no transformation
-        # The pg gem returns JSONB as String by default
+        # Return raw values as-is from PostgreSQL. No parsing, no deserialization, no transformation.
+        # The pg gem returns JSONB as String by default.
         super(
           msg_id: row["msg_id"],
           read_ct: row["read_ct"],

data/lib/pgmq/notify_throttle.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PGMQ
+  # Represents the NOTIFY throttle configuration for a queue
+  #
+  # @example Inspecting notification configuration
+  #   throttles = client.list_notify_insert_throttles
+  #   throttles.each do |t|
+  #     puts "#{t.queue_name}: #{t.throttle_interval_ms}ms (last notified: #{t.last_notified_at})"
+  #   end
+  class NotifyThrottle < Data.define(:queue_name, :throttle_interval_ms, :last_notified_at)
+    class << self
+      # Creates a new NotifyThrottle from a database row
+      # @param row [Hash] database row from PG result
+      # @return [NotifyThrottle]
+      def new(row, **)
+        super(
+          queue_name: row["queue_name"],
+          throttle_interval_ms: row["throttle_interval_ms"],
+          last_notified_at: row["last_notified_at"]
+        )
+      end
+    end
+  end
+end

data/lib/pgmq/queue_name.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module PGMQ
+  # Queue name validation, normalization, and sanitization.
+  #
+  # PGMQ interpolates a queue's name into PostgreSQL identifiers (it creates tables named +pgmq.q_<name>+ and
+  # +pgmq.a_<name>+), so a name has to be a valid, length-bounded SQL identifier. This module is the single source of
+  # truth for those rules and offers tiers depending on how much you trust the input:
+  #
+  # 1. {.validate!} / {.valid?} - assert a name is already valid. Use for names you control. {PGMQ::Client} calls
+  #    {.validate!} before every operation.
+  # 2. {.normalize} - lightly rewrite a name that is *meant* to be valid but uses a friendlier separator. Maps the
+  #    common stream separators (hyphens, dots, colons) to underscores, strips any other invalid character, then
+  #    validates - so a Turbo Stream channel like +"chat:room-7"+ becomes +"chat_room_7"+. Raises if the result still
+  #    can't be a valid name (empty, or starts with a digit).
+  # 3. {.sanitize!} - coerce *untrusted* input into a valid name by stripping every invalid character, then validate.
+  #    Raises if nothing valid remains. Use this as a SQL-identifier guard: the result is always either a name you
+  #    know is safe, or an exception - never a silent substitute.
+  # 4. {.sanitize} - the lenient sibling of {.sanitize!}: best-effort coercion that *never* raises for content and
+  #    always returns a usable identifier (falling back to a default). Convenient, but see the collision caveat on
+  #    the method - distinct inputs can map to the same name.
+  #
+  # @example
+  #   PGMQ::QueueName.valid?("orders")           # => true
+  #   PGMQ::QueueName.validate!("my-queue")      # => raises InvalidQueueNameError
+  #   PGMQ::QueueName.normalize("chat:room-7")   # => "chat_room_7"
+  #   PGMQ::QueueName.sanitize!("orders!!")      # => "orders"
+  #   PGMQ::QueueName.sanitize!("!!!")           # => raises InvalidQueueNameError
+  #   PGMQ::QueueName.sanitize("99 Problems!")   # => "q_99_problems"
+  module QueueName
+    # Maximum queue name length. PGMQ creates tables with prefixes (+q_+, +a_+) and PostgreSQL caps identifiers at 63
+    # characters; PGMQ enforces 48 to leave room for those prefixes and suffixes.
+    MAX_LENGTH = 48
+
+    # A valid queue name: starts with a letter or underscore, then letters, digits, or underscores.
+    PATTERN = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
+    # Prefix used by {.sanitize} when the input would otherwise start with an illegal leading character (e.g. a
+    # digit) but still has usable trailing characters.
+    SANITIZE_PREFIX = "q_"
+
+    # Name {.sanitize} falls back to when the input has no usable characters at all.
+    SANITIZE_FALLBACK = "queue"
+
+    module_function
+
+    # Returns true if the name is already a valid queue name.
+    #
+    # @param name [String, #to_s] candidate queue name
+    # @return [Boolean]
+    def valid?(name)
+      str = name.to_s
+      !str.empty? && str.length < MAX_LENGTH && str.match?(PATTERN)
+    end
+
+    # Validates a queue name, returning it unchanged when valid and raising otherwise.
+    #
+    # @param name [String, #to_s] candidate queue name
+    # @return [String] the validated name (as a String)
+    # @raise [PGMQ::Errors::InvalidQueueNameError] if the name is empty, too long, or not a valid identifier
+    def validate!(name)
+      str = name.to_s
+
+      if name.nil? || str.strip.empty?
+        raise Errors::InvalidQueueNameError, "Queue name cannot be empty"
+      end
+
+      if str.length >= MAX_LENGTH
+        raise Errors::InvalidQueueNameError,
+          "Queue name '#{str}' exceeds maximum length of #{MAX_LENGTH} characters " \
+          "(current length: #{str.length})"
+      end
+
+      return str if str.match?(PATTERN)
+
+      raise Errors::InvalidQueueNameError,
+        "Invalid queue name '#{str}': must start with a letter or underscore " \
+        "and contain only letters, digits, and underscores"
+    end
+
+    # Rewrites a name that is meant to be valid but uses friendlier separators, then validates it.
+    #
+    # Maps the common stream-name separators - hyphens, dots, and colons - to underscores, strips any *other* invalid
+    # character, then collapses repeated underscores and trims them from the ends. So +"chat:room-7"+ becomes
+    # +"chat_room_7"+ and +"order.events"+ becomes +"order_events"+, while a stray +"a@b"+ becomes +"ab"+ (the +@+ is
+    # dropped, not turned into a separator). The result is validated, so names that still can't be valid (empty, or
+    # starting with a digit) raise rather than being silently mangled.
+    #
+    # Colons in particular are the turbo-rails stream-name separator, so they are mapped to a safe character rather
+    # than stripped - otherwise +"a:b"+ and +"ab"+ would collide on the same queue.
+    #
+    # @param name [String, #to_s] a name using friendly separators
+    # @return [String] the normalized, validated queue name
+    # @raise [PGMQ::Errors::InvalidQueueNameError] if the normalized result is not a valid queue name
+    def normalize(name)
+      str = name.to_s
+      return validate!(str) if str.match?(PATTERN)
+
+      normalized = str
+        .gsub(/[-.:]/, "_")          # hyphens / dots / colons -> underscores
+        .gsub(/[^a-zA-Z0-9_]/, "")   # strip any remaining invalid character
+        .squeeze("_")                # collapse consecutive underscores
+        .gsub(/\A_+|_+\z/, "")       # trim leading / trailing underscores
+
+      validate!(normalized)
+    end
+
+    # Strips every invalid character from untrusted input, then validates the result.
+    #
+    # This is the SQL-identifier guard: it removes anything outside +[A-Za-z0-9_]+ and passes the remainder through
+    # {.validate!}. If nothing valid remains (empty result, leading digit, too long) it raises, so a caller can never
+    # accidentally operate on a different queue than intended. Use this for names from untrusted sources (URL params,
+    # external systems) where a wrong-but-valid name would be worse than an error.
+    #
+    # @param name [String, #to_s] untrusted input
+    # @return [String] the sanitized, validated queue name
+    # @raise [PGMQ::Errors::InvalidQueueNameError] if nothing valid remains after stripping
+    def sanitize!(name)
+      validate!(name.to_s.gsub(/[^a-zA-Z0-9_]/, ""))
+    end
+
+    # Best-effort coercion of arbitrary input into a valid queue name; the lenient sibling of {.sanitize!}.
+    #
+    # Never raises for content: it lowercases, replaces every illegal character run with an underscore, trims
+    # underscores, prefixes {SANITIZE_PREFIX} when the first surviving character is not a valid identifier start (e.g.
+    # a digit), truncates to fit {MAX_LENGTH}, and falls back to {SANITIZE_FALLBACK} when nothing usable remains. The
+    # return value always satisfies {.valid?}.
+    #
+    # @note Because it coerces rather than rejects, distinct inputs can map to the *same* name (e.g. +"a/b"+ and
+    #   +"a-b"+ both become +"a_b"+; +"!!!"+ and +""+ both become +"queue"+). If your name selects a queue table,
+    #   that means two logically different inputs could share one queue. When that matters - especially for untrusted
+    #   input - prefer {.sanitize!}, which raises instead of substituting.
+    #
+    # @param name [String, #to_s] arbitrary input
+    # @return [String] a guaranteed-valid queue name
+    def sanitize(name)
+      cleaned = name.to_s.downcase
+        .gsub(/[^a-z0-9_]+/, "_").squeeze("_")
+        .gsub(/\A_+|_+\z/, "")
+
+      # Nothing usable survived the scrub - use the fallback rather than emit a bare prefix like "q_".
+      return SANITIZE_FALLBACK if cleaned.empty?
+
+      # A valid identifier can't start with a digit; prefix so the leading character is legal.
+      cleaned = "#{SANITIZE_PREFIX}#{cleaned}" unless cleaned.match?(/\A[a-z_]/)
+
+      # Keep under MAX_LENGTH (valid? requires strictly less than), trimming any underscore left at the cut.
+      cleaned = cleaned[0, MAX_LENGTH - 1].sub(/_+\z/, "") if cleaned.length >= MAX_LENGTH
+
+      cleaned.empty? ? SANITIZE_FALLBACK : cleaned
+    end
+  end
+end

data/lib/pgmq/transaction.rb

@@ -3,12 +3,11 @@
 module PGMQ
   # Low-level transaction support for PGMQ operations
   #
-  # Provides atomic execution of PGMQ operations within PostgreSQL transactions.
-  # Transactions are a database primitive - this is a thin wrapper around
-  # PostgreSQL's native transaction support.
+  # Provides atomic execution of PGMQ operations within PostgreSQL transactions. Transactions are a database primitive -
+  # this is a thin wrapper around PostgreSQL's native transaction support.
   #
-  # This is analogous to rdkafka-ruby providing Kafka transaction support -
-  # it's a protocol/database feature, not a framework abstraction.
+  # This is analogous to rdkafka-ruby providing Kafka transaction support - it's a protocol/database feature, not a
+  # framework abstraction.
   #
   # @example Atomic multi-queue operations
   #   client.transaction do |txn|
@@ -24,8 +23,8 @@ module PGMQ
   module Transaction
     # Executes PGMQ operations atomically within a database transaction
     #
-    # Obtains a connection from the pool, starts a transaction, and yields
-    # a client that uses that transaction for all operations.
+    # Obtains a connection from the pool, starts a transaction, and yields a client that uses that transaction for all
+    # operations.
     #
     # @yield [PGMQ::Client] transactional client using the same connection
     # @return [Object] result of the block

data/lib/pgmq/version.rb

@@ -2,5 +2,5 @@
 
 module PGMQ
   # Current version of the pgmq-ruby gem
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

data/lib/pgmq.rb

@@ -12,9 +12,8 @@ loader.eager_load
 
 # PGMQ - Low-level Ruby client for Postgres Message Queue
 #
-# This is a low-level library providing direct access to PGMQ operations.
-# For higher-level abstractions, job processing, and framework integrations,
-# see pgmq-framework (similar to how rdkafka-ruby relates to Karafka).
+# This is a low-level library providing direct access to PGMQ operations. For higher-level abstractions, job processing,
+# and framework integrations, see pgmq-framework (similar to how rdkafka-ruby relates to Karafka).
 #
 # @example Basic usage
 #   require 'pgmq'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgmq-ruby
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -64,6 +64,7 @@ files:
 - README.md
 - lib/pgmq.rb
 - lib/pgmq/client.rb
+- lib/pgmq/client/autovacuum.rb
 - lib/pgmq/client/consumer.rb
 - lib/pgmq/client/maintenance.rb
 - lib/pgmq/client/message_lifecycle.rb
@@ -76,7 +77,9 @@ files:
 - lib/pgmq/errors.rb
 - lib/pgmq/message.rb
 - lib/pgmq/metrics.rb
+- lib/pgmq/notify_throttle.rb
 - lib/pgmq/queue_metadata.rb
+- lib/pgmq/queue_name.rb
 - lib/pgmq/transaction.rb
 - lib/pgmq/version.rb
 - pgmq-ruby.gemspec
@@ -104,7 +107,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Ruby client for PGMQ (Postgres Message Queue)
 test_files: []