fix(connection): detect SSL-layer EOF and match PG::ConnectionBad by class (mensfeld#99)

`connection_lost_error?` relied exclusively on message substrings, so a
transient Postgres drop that surfaces at the SSL layer as
`PQconsumeInput() SSL error: unexpected eof while reading` bypassed the
single-retry path in `with_connection` and propagated as
`PGMQ::Errors::ConnectionError` even though the connection would recover
on the next checkout.

Two complementary changes:

1. Match by class (`PG::ConnectionBad`, `PG::UnableToSend`) first. These
   are libpq's dedicated connection-failure classes; class-matching
   catches future OS/pooler/TLS variants without enumerating every
   message.
2. Add `"ssl error: unexpected eof"` and `"ssl syscall error"` to the
   substring list for the bare `PG::Error` cases.

Observed in production behind a managed Postgres pooler: three unrelated
controllers hit the same error in a six-minute window after an idle SSL
teardown, then recovered. An earlier cluster with `PQsocket() can't get
socket descriptor` (already in the list) was retried successfully,
confirming the machinery works and only the pattern was missing.

Refs mensfeld#98

Author: mhenrixon

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Connection Management
+- **[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

lib/pgmq/connection.rb

@@ -107,28 +107,42 @@ def stats
 
     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 two steps: first by class (`PG::ConnectionBad` /
+    # `PG::UnableToSend` are dedicated connection-failure classes libpq
+    # raises regardless of message), then by message substring for the
+    # bare `PG::Error` cases where libpq doesn't reach for the specific
+    # subclass.
+    #
     # @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"
-      ]
+      return true if error.is_a?(PG::ConnectionBad) || error.is_a?(PG::UnableToSend)
 
       message = error.message.to_s.downcase
-      lost_connection_messages.any? { |pattern| message.include?(pattern) }
+      LOST_CONNECTION_MESSAGES.any? { |pattern| message.include?(pattern) }
     end
 
     # Verifies a connection is alive and working.

test/lib/pgmq/connection_test.rb

@@ -282,6 +282,44 @@
 
       refute connection.send(:connection_lost_error?, error)
     end
+
+    it "matches SSL-layer EOF raised when libpq's read returns 0 on a dead socket" do
+      # Observed in production behind a managed Postgres pooler: an idle
+      # connection is torn down at the SSL layer and the next I/O raises
+      # this exact message. Semantically identical to "could not receive
+      # data from server" (which is already covered), just one layer down.
+      error = PG::ConnectionBad.new(
+        "PQconsumeInput() SSL error: unexpected eof while reading"
+      )
+
+      assert connection.send(:connection_lost_error?, error)
+    end
+
+    it "matches SSL SYSCALL teardown errors" do
+      error = PG::ConnectionBad.new(
+        "SSL SYSCALL error: EOF detected"
+      )
+
+      assert connection.send(:connection_lost_error?, error)
+    end
+
+    it "matches PG::ConnectionBad by class, even when the message is opaque" do
+      # libpq doesn't promise a stable message for every pooler/OS/TLS
+      # combination, but it does raise a dedicated class for connection
+      # failures. Class-matching catches future message variants without
+      # growing the string list.
+      error = PG::ConnectionBad.new("")
+
+      assert connection.send(:connection_lost_error?, error)
+    end
+
+    it "matches PG::UnableToSend by class" do
+      # Raised by libpq when the write side of the connection is gone —
+      # another dedicated connection-failure class.
+      error = PG::UnableToSend.new("")
+
+      assert connection.send(:connection_lost_error?, error)
+    end
   end
 
   describe "verify_connection! (private)" do