pgmq-ruby 0.6.1 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2a31db1ba5a65a0666bb496ae5b54e0a51de5cafe9b92ebf55b432ea309ef44
-  data.tar.gz: cbf292400bff6ca3f34bdb95ff8a7c6910df5da4db3cbabc574c7b3173864523
+  metadata.gz: bad592ec19aca0b0437ef08ef6cbcb8ecdb2f9155ddbc27196ef00e8b10b22ce
+  data.tar.gz: 8220e5b37d111f10afb169100c7a7d45231a19f7b6b31880b200a744abb427b5
 SHA512:
-  metadata.gz: 687e92a06cb6fd93f2015390153693fb267faebc7b4bc8c54fd547cfda2ec87a1621e2be47bb9f2ac70c40b1394a854daee85c4d069845b3756c980672fc49c0
-  data.tar.gz: cb4c6c32f6d69e6329dd12fba2e319865087b08994e894ce169e3360595bc59fb425c6b432ca2ee040b13c4367f0b20ccf307f6fadf9b4d9619dbfc3a509f0a4
+  metadata.gz: c9236e3bba26ee065dcc21d87f945ff2a71439695202322fef2e1c87502b91e655e73d7cc498084109b75023073e56bcca060bf4f4da45fd403bfaa25c802049
+  data.tar.gz: f9c94727f9839d0cffad5928147015e90801ec41eeb3e32b4577fb8743da9891d5e2dc9cce622d3308853ac44abd15076d085165f56e6785c420752a2e8d56dd

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## Unreleased
+
+## 0.6.2 (2026-05-08)
+
+### Connection Management
+- **[Feature]** Add class-level configuration for extending reconnectable error detection. `PGMQ::Connection.reconnectable_error_patterns` accepts additional `String` or `Regexp` patterns (strings matched as case-insensitive substrings; regexps against the original message). `PGMQ::Connection.reconnectable_error_classes` accepts additional `Exception` subclasses. This allows users to adapt to new pg gem / PostgreSQL / pooler disconnect signatures without waiting for a gem release.
+- **[Fix]** `PGMQ::Connection#connection_lost_error?` now detects SSL-layer teardown errors (`"PQconsumeInput() SSL error: unexpected eof while reading"`, `"SSL SYSCALL error: EOF detected"`). Observed in production behind a managed Postgres pooler: an idle connection torn down at the SSL layer caused the next enqueue to raise `PGMQ::Errors::ConnectionError` without triggering `with_connection`'s single-retry path, because the message didn't match any of the existing substrings.
+- **[Fix]** `PGMQ::Connection#connection_lost_error?` now also matches by class (`PG::ConnectionBad`, `PG::UnableToSend`) in addition to message substrings. These are dedicated connection-failure classes libpq raises when the socket is dead; class-matching catches future OS/pooler/TLS message variants without waiting for them to hit production.
+
 ## 0.6.1 (2026-04-16)
 
 ### Connection Management

data/README.md

@@ -290,10 +290,44 @@ client = PGMQ::Client.new(
 )
 ```
 
+#### Extending the lost-connection error matchers
+
+PGMQ-Ruby ships with a curated list of `PG::Error` messages and classes
+(`PG::ConnectionBad`, `PG::UnableToSend`) that trigger the auto-reconnect
+retry. Different `pg` gem versions, PostgreSQL versions, and connection
+poolers (PgBouncer, Supabase, RDS Proxy, etc.) occasionally surface new
+disconnect signatures. Rather than wait for an upstream patch, you can
+extend the matchers at boot time via class-level configuration:
+
+```ruby
+# In an initializer (e.g. config/initializers/pgmq.rb for Rails apps)
+# Strings are matched as case-insensitive substrings against the error
+# message; Regexps are matched against the original message.
+PGMQ::Connection.reconnectable_error_patterns = [
+  "connection reset by peer",
+  /\Abroken pipe\b/i
+]
+
+# Any Exception subclass is accepted. Subclasses also match.
+PGMQ::Connection.reconnectable_error_classes = [PG::ConnectionRefused]
+```
+
+The built-in defaults are always kept — your patterns and classes are
+appended to them. Configuration errors (e.g. passing an Integer as a
+pattern) raise `PGMQ::Errors::ConfigurationError` immediately so
+misconfiguration can't silently disable retries.
+
+> **Reserve these options for connection-level failures.** A "reconnectable"
+> error means the socket is dead and a retry on a fresh connection is safe.
+> Do **not** add patterns or classes for query-level errors (deadlocks,
+> constraint violations, statement timeouts) — those will replay your
+> operation against a healthy connection and may cause duplicate work or
+> mask bugs.
+
 **Connection Pool Benefits:**
 - **Thread-safe** - Multiple threads can safely share a single client
 - **Fiber-aware** - Works with Ruby 3.0+ Fiber Scheduler for non-blocking I/O (tested with the `async` gem)
-- **Auto-reconnect** - Recovers from lost connections (configurable)
+- **Auto-reconnect** - Recovers from lost connections (configurable, extendable)
 - **Health checks** - Verifies connections before use to prevent stale connection errors
 - **Monitoring** - Track pool utilization with `client.stats`
 

data/lib/pgmq/connection.rb

@@ -26,6 +26,97 @@ 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,28 +198,56 @@ 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.

data/lib/pgmq/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgmq-ruby
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors:
 - Maciej Mensfeld