pgmq-ruby 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 812f7254909aa9125fa79b5304cb3fad8461cce5372dd02206c7cfdf9b99afa9
-  data.tar.gz: 754f398b518800546fa2c2fe2bbaf3a3d3eb742ca5c162d9c89cd1415ac40a57
+  metadata.gz: bad592ec19aca0b0437ef08ef6cbcb8ecdb2f9155ddbc27196ef00e8b10b22ce
+  data.tar.gz: 8220e5b37d111f10afb169100c7a7d45231a19f7b6b31880b200a744abb427b5
 SHA512:
-  metadata.gz: 40b65d9001f469d2e88c04cc5f4bcf85b234b850a19ee4089e0b25f52b266bf45c8680398de43a61a042998a08760b867d3be1878aad518567caa6a0801cec80
-  data.tar.gz: 175b62d75d9fa46391570026e345b18c099ab75dabfe4518acd89e750de4fce97eebd01fcc8733ce771492343a74f50dbca9534c2305e47599eebe966dd04d9d
+  metadata.gz: c9236e3bba26ee065dcc21d87f945ff2a71439695202322fef2e1c87502b91e655e73d7cc498084109b75023073e56bcca060bf4f4da45fd403bfaa25c802049
+  data.tar.gz: f9c94727f9839d0cffad5928147015e90801ec41eeb3e32b4577fb8743da9891d5e2dc9cce622d3308853ac44abd15076d085165f56e6785c420752a2e8d56dd

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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
+- **[Fix]** `PGMQ::Connection#verify_connection!` now also resets connections whose status is `PG::CONNECTION_BAD`. Previously it only checked `conn.finished?`, which misses connections closed server-side by the database or an intermediate pooler (PgBouncer `server_idle_timeout` / `client_idle_timeout`, admin kill, TCP RST). A pooled connection with a dead socket would survive `verify_connection!` and fail on the next operation with `PQsocket() can't get socket descriptor`.
+- **[Fix]** `PGMQ::Connection#connection_lost_error?` now recognises `"PQsocket() can't get socket descriptor"` (plus `"connection is closed"` / `"connection has been closed"`). This is the exact error the `pg` gem raises from its C extension when the cached libpq socket FD is gone. Without the match, the `auto_reconnect` retry path in `with_connection` skipped this error and producers failed on the first call following a server-side close.
+
 ## 0.6.0 (2026-04-02)
 
 ### Breaking Changes

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,33 +198,73 @@ 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
-      lost_connection_messages = [
-        "server closed the connection",
-        "connection not open",
-        "no connection to the server",
-        "terminating connection",
-        "connection to server was lost",
-        "could not receive data from server"
-      ]
-
-      message = error.message.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
+    # 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.
+    #
     # @param conn [PG::Connection] connection to verify
-    # @raise [PG::Error] if connection is not working
+    # @raise [PG::Error] if the reset itself fails
     def verify_connection!(conn)
-      # Quick check - is connection object in bad state?
-      return unless conn.finished?
+      return conn.reset if conn.finished?
+      return conn.reset if conn.status == PG::CONNECTION_BAD
 
-      # Connection is finished/closed, try to reset it
-      conn.reset
+      nil
     end
 
     # Normalizes various connection parameter formats

data/lib/pgmq/version.rb

@@ -2,5 +2,5 @@
 
 module PGMQ
   # Current version of the pgmq-ruby gem
-  VERSION = "0.6.0"
+  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.0
+  version: 0.6.2
 platform: ruby
 authors:
 - Maciej Mensfeld