pg_pipeline 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ebb76f18598913316b77fdc0fd0ab4aa411fbd014cf1f3f10e427c1a5709967
-  data.tar.gz: cd51b3fc6b5f20f5896969e8eb3a4263d999f2544239606944194192f894e850
+  metadata.gz: ca8a6402d9ee49ae0393f519c135f4174248df64aa27332f0773e095eb3179c8
+  data.tar.gz: 3c01ed0c9be6950a3b4d264bc613e5fef94c56dc81cb8916c791902ffeac61b0
 SHA512:
-  metadata.gz: 6c1581a9ecc7f45b44342c49c529d12694c5d962808ef4ba7a0ec9d71aac5ae46852c99c242ec1b897c8c1b591d9ab66c55a24eacf0a4e6637de068624f36fc3
-  data.tar.gz: 3272e19424de3eed0f6c186b2bf14ac830ef226f9ce47207fd3c71fd38f622557a6542630c44934794cf9c650106a2e5a7e66ec475501220a685551799609111
+  metadata.gz: dc55189c229e3958e40781e30577ac82c3645f70fa55c2bce894baf9e0a423caa67d3ba533f77d5fce627943b424e0c7de2cea5f99a2ea25b0903022f438b3df
+  data.tar.gz: 508c35a99f8a9f5f3fa3665b741adaf58f593b6cc6c95fbfb86b48ded121adb010d4203fce6d9063274e510171e9f401ed0295b8691f2211ce273395cd7dcb9d

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## [0.3.1] - 2026-08-09
+
+Reliability and correctness fixes on top of 0.3.0. No public API changes other
+than the new error class below; no changes to wire behaviour.
+
+### Fixed
+
+- `SessionGuard` dollar-quote masking now recognises tags containing non-ASCII
+  identifier bytes (e.g. `$тег$...$тег$`). Previously an unrecognised tag left
+  the quoted body unmasked, so its raw text was scanned by the forbidden-pattern
+  checks instead of being treated as an opaque literal.
+- `Client#transaction` now distinguishes a lost `COMMIT` acknowledgement from an
+  ordinary server-side rejection. If `COMMIT` fails while the connection is
+  still healthy (`status == CONNECTION_OK`, not `finished?`), the original
+  `PG::Error` is raised unchanged -- the server gave a complete answer and the
+  transaction did not commit. If the connection itself is gone or broken
+  (`PG::ConnectionBad`, `finished?`, or a non-OK status), the outcome is
+  genuinely unknown, and this is now raised as the new
+  `PgPipeline::IndeterminateCommitError < IndeterminateResultError` instead of
+  a bare `PG::Error`, so callers can tell "definitely rolled back" apart from
+  "may have committed, do not retry blindly" without inspecting connection
+  internals themselves. See the updated "Failure model" table in the README.
+
+### Reverted
+
+- The reader/writer watcher shutdown mechanism briefly introduced in this cycle
+  (self-pipe `Runtime::Wakeup` + `IO.select` on every socket wait) has been
+  removed before release. It fixed a real gap -- on schedulers with no way to
+  interrupt a fiber blocked in `wait_readable`/`wait_writable`, closing the
+  socket alone does not reliably wake it pre-Ruby-4.0 -- but at an unacceptable
+  cost: it moved the connection driver's hottest loop from `io_wait` (native,
+  zero extra threads) onto `IO.select`, and both reference schedulers implement
+  that hook expensively. `Async::Scheduler#io_select` spawns a new OS thread per
+  call; `Itsi::Scheduler#io_select` with more than one IO (our case: socket +
+  wakeup pipe) falls onto Itsi's bounded `blocking_operation_wait` worker pool
+  and holds a worker for the full duration of every idle wait, which can
+  exhaust that pool under a modest number of pipeline connections.
+- Root-caused instead: `Async::Scheduler` and `Itsi::Scheduler` both already
+  implement `#fiber_interrupt` as an ordinary library method, independent of
+  Ruby core's own hook of the same name (Ruby >= 4.0). `Task#stop` already
+  tries `#fiber_interrupt` first, so on both of this gem's reference schedulers
+  a blocked watcher is woken immediately via `fiber.raise`, on the same
+  `wait_readable`/`wait_writable` fast path as 0.3.0 -- no self-pipe needed.
+  `ConnectionDriver` now only falls back to a bounded
+  `wait_readable(timeout)`/`wait_writable(timeout)` poll
+  (`DriverOps::WATCHER_POLL_INTERVAL`, 0.25s) when the active scheduler does
+  *not* respond to `#fiber_interrupt`, guaranteeing shutdown within one poll
+  interval instead of depending on socket-close propagation. Async and Itsi
+  never pay this poll; an unknown/minimal scheduler does, bounded and cheap.
+- `teardown_watchers` also reverts to closing the socket/connection
+  unconditionally regardless of whether the watcher tasks joined in time. The
+  self-pipe version returned early when a watcher missed
+  `WATCHER_JOIN_TIMEOUT`, before closing the wakeup pipes, the socket, or the
+  `PG::Connection` -- turning a leaked *task* into a leaked live DB connection
+  and file descriptors. Resources are now always closed; only the task's own
+  fiber can still leak (tracked via `stats[:leaked_watchers]`, unchanged).
+
 ## [0.3.0] - 2026-08-07
 
 Scheduler-agnostic control plane: the gem no longer depends on the `async` gem

data/README.md

@@ -265,8 +265,15 @@ If your workload mixes fast and slow queries, prefer one of:
 |---|---|---|
 | `NotDispatchedError` | query never reached the wire | ✅ yes |
 | `IndeterminateResultError` | query was sent, Sync not observed | ⚠️ only if idempotent |
+| `IndeterminateCommitError` | `Client#transaction`'s `COMMIT` acknowledgement was lost while the connection itself was gone/broken | ⚠️ never — the transaction may have committed |
 | `UnsafeMultiplexError` | session-mutating SQL on multiplexed path | — fix the call site |
 
+`IndeterminateCommitError < IndeterminateResultError`. It is raised only when the
+pinned connection looks dead (`PG::ConnectionBad`, `finished?`, or a non-OK
+status) at the moment `COMMIT` fails. If `COMMIT` fails while the connection is
+still healthy, that's the server giving a complete, unambiguous answer — the
+original `PG::Error` is raised as-is, and the transaction did not commit.
+
 Cancelling a fiber does **not** send `CancelRequest` to PostgreSQL — the query may
 still execute. For mutations, do not retry blindly after a timeout.
 

data/lib/pg_pipeline/connection_driver.rb

@@ -38,7 +38,6 @@ module PgPipeline
       @caps = ServerCaps.from_connection(conn)
       @caps.assert_supported!
       DriverOps.warn_flush_coupling_once(@caps)
-
       @requests = BoundedQueue.new(@max_pending)
       @events = Runtime::Queue.new
       @reader_rearm = Runtime::Queue.new
@@ -48,7 +47,6 @@ module PgPipeline
       @readable_events = @results_read = @units_completed = @flush_calls =
         @flush_incomplete = @dispatches = @leaked_watchers = @submitting = 0
       @socket = @owner_task = @reader_task = @writer_task = @dispatching = nil
-
       @inflight = []
     end
 
@@ -109,6 +107,7 @@ module PgPipeline
   module DriverOps
     WATCHER_JOIN_TIMEOUT = 2.0
     OWNER_JOIN_TIMEOUT = 5.0
+    WATCHER_POLL_INTERVAL = 0.25
 
     module_function
 
@@ -147,7 +146,6 @@ module PgPipeline
 
       d.conn.setnonblocking(true)
       d.conn.enter_pipeline_mode
-
       d.socket = d.conn.socket_io
       d.accepting = true
       d.running = true
@@ -233,7 +231,6 @@ module PgPipeline
 
     def process_event(d, event)
       input_changed = false
-
       case event
       when :requests
         d.request_event_pending = false
@@ -275,7 +272,6 @@ module PgPipeline
 
     def pump_requests(d)
       dispatched = false
-
       while d.inflight.size < d.max_in_flight && !d.requests.empty?
         request = d.requests.dequeue
         break unless request
@@ -356,7 +352,6 @@ module PgPipeline
       return unless d.running
 
       d.flush_calls += 1
-
       if d.conn.sync_flush
         d.needs_flush = false
       else
@@ -398,7 +393,6 @@ module PgPipeline
           end
 
           status = result.result_status
-
           case status
           when PG::PGRES_TUPLES_OK
             ensure_before_query_boundary!(request, status)
@@ -459,7 +453,6 @@ module PgPipeline
     def finish_graceful_close(d)
       d.accepting = false
       d.running = false
-
       d.conn.exit_pipeline_mode
     rescue PG::Error => e
       fail_all(d, ConnectionLostError.new("failed to exit pipeline mode: #{e.message}"))
@@ -511,10 +504,32 @@ module PgPipeline
       )
     end
 
+    def watcher_wait_timeout
+      scheduler = Fiber.scheduler
+      return nil if scheduler&.respond_to?(:fiber_interrupt)
+
+      WATCHER_POLL_INTERVAL
+    end
+
+    def wait_socket_readable(d, timeout)
+      loop do
+        return false unless d.running
+        return true if d.socket.wait_readable(timeout)
+      end
+    end
+
+    def wait_socket_writable(d, timeout)
+      loop do
+        return false unless d.running
+        return true if d.socket.wait_writable(timeout)
+      end
+    end
+
     def reader_watcher(d)
+      timeout = watcher_wait_timeout
+
       while d.running
-        d.socket.wait_readable
-        break unless d.running
+        break unless wait_socket_readable(d, timeout)
 
         d.events.enqueue(:readable)
         command = d.reader_rearm.dequeue
@@ -527,11 +542,13 @@ module PgPipeline
     end
 
     def writer_watcher(d)
+      timeout = watcher_wait_timeout
+
       while d.running
         command = d.writer_commands.dequeue
         break unless command == :wait_writable && d.running
+        break unless wait_socket_writable(d, timeout)
 
-        d.socket.wait_writable
         d.events.enqueue(:writable) if d.running
       end
     rescue StandardError => e
@@ -616,8 +633,8 @@ module PgPipeline
       warn(
         "pg_pipeline: task #{task.name.inspect} did not exit within " \
         "#{timeout}s and has been leaked (total #{d.leaked_watchers}). " \
-        "Closing the duplexed socket_io / connection did not release the fiber " \
-        "(often parked in wait_readable/wait_writable)."
+        "Closing the socket and, on schedulers without #fiber_interrupt, the " \
+        "#{WATCHER_POLL_INTERVAL}s watcher poll did not release the fiber in time."
       )
     end
 

data/lib/pg_pipeline/errors.rb

@@ -8,6 +8,7 @@ module PgPipeline
   class ConnectionLostError < Error; end
   class NotDispatchedError < ConnectionLostError; end
   class IndeterminateResultError < ConnectionLostError; end
+  class IndeterminateCommitError < IndeterminateResultError; end
   class ShutdownError < Error; end
   class ProtocolError < Error; end
   class RecursiveCheckoutError < Error; end

data/lib/pg_pipeline/session_guard.rb

@@ -18,7 +18,6 @@ module PgPipeline
       "select-into-temp" => /\binto\s+(?:(?:global|local)\s+)?temp(?:orary)?\b/i,
       "select-into-pg-temp" => /\binto\s+(?:table\s+)?pg_temp(?:_\d+)?\s*\./i
     }.freeze
-
     STRICT_FORBIDDEN = {
       "nextval" => /\bnextval\s*\(/i,
       "setval" => /\bsetval\s*\(/i,
@@ -28,9 +27,9 @@ module PgPipeline
       "session-advisory-unlock" => /\bpg_advisory_unlock(?:_shared|_all)?\s*\(/i,
       "pg_export_snapshot" => /\bpg_export_snapshot\s*\(/i
     }.freeze
-
     PATTERN_PREFILTER = /\binto\b/i
-    NEEDS_MASK = /['"]|--|\/\*|\$[A-Za-z_0-9]*\$/
+    DOLLAR_QUOTE_TAG = /\A\$(?:(?:[A-Za-z_]|[^\x00-\x7F])(?:[A-Za-z0-9_]|[^\x00-\x7F])*)?\$/
+    NEEDS_MASK = /['"]|--|\/\*|\$(?:(?:[A-Za-z_]|[^\x00-\x7F])(?:[A-Za-z0-9_]|[^\x00-\x7F])*)?\$/
     LEADING_KEYWORD = /\A\s*([a-zA-Z_]+)/
     WHITESPACE_BYTES = [9, 10, 11, 12, 13, 32].freeze
 
@@ -84,7 +83,6 @@ module PgPipeline
       FORBIDDEN_PATTERNS.each do |name, pattern|
         return name if code.match?(pattern)
       end
-
       if mode == :strict
         STRICT_FORBIDDEN.each do |name, pattern|
           return "strict:#{name}" if code.match?(pattern)
@@ -111,7 +109,6 @@ module PgPipeline
       while index < size
         byte = source.getbyte(index)
         nxt = index + 1 < size ? source.getbyte(index + 1) : nil
-
         if block_depth.positive?
           if byte == 47 && nxt == 42
             block_depth += 1
@@ -159,7 +156,7 @@ module PgPipeline
 
         if byte == 36
           remainder = source.byteslice(index, size - index)
-          tag = remainder.match(/\A\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/)&.[](0)
+          tag = DOLLAR_QUOTE_TAG.match(remainder)&.[](0)
           if tag
             closing = source.index(tag, index + tag.bytesize)
             finish = closing ? closing + tag.bytesize : size
@@ -182,7 +179,6 @@ module PgPipeline
 
       while index < source.bytesize
         byte = source.getbyte(index)
-
         if escape_backslash && byte == 92
           output << " "
           index += 1
@@ -203,7 +199,6 @@ module PgPipeline
           index += 1
         end
       end
-
       index
     end
     private_class_method :mask_quoted

data/lib/pg_pipeline/transaction.rb

@@ -39,7 +39,7 @@ module PgPipeline
       tx.__send__(:open=, true)
       begin
         result = yield tx
-        conn.exec("COMMIT")
+        commit(conn)
         tx.__send__(:open=, false)
         result
       rescue Exception
@@ -48,6 +48,28 @@ module PgPipeline
       end
     end
 
+    def commit(conn)
+      conn.exec("COMMIT")
+    rescue PG::Error => error
+      raise unless indeterminate_commit_failure?(conn, error)
+
+      raise IndeterminateCommitError.new(
+        "COMMIT acknowledgement was not received; the transaction may have committed " \
+        "and must not be retried blindly (#{error.class}: #{error.message})"
+      ), cause: error
+    end
+
+    def indeterminate_commit_failure?(conn, error)
+      return true if defined?(PG::ConnectionBad) && error.is_a?(PG::ConnectionBad)
+      return true if conn.finished?
+
+      conn.status != PG::CONNECTION_OK
+    rescue PG::Error
+      true
+    rescue NoMethodError
+      false
+    end
+
     def savepoint(tx, name)
       SessionOps.ensure_active!(tx)
       raise Error, "savepoint requires an open transaction" unless tx.open?
@@ -57,7 +79,6 @@ module PgPipeline
       tx.__send__(:savepoint_seq=, seq)
       point = name || "pgp_sp_#{seq}"
       ident = conn.quote_ident(point)
-
       conn.exec("SAVEPOINT #{ident}")
       begin
         result = yield tx

data/lib/pg_pipeline/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgPipeline
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pg_pipeline
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Roman Hajdarov