pg_pipeline 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ebb76f18598913316b77fdc0fd0ab4aa411fbd014cf1f3f10e427c1a5709967
-  data.tar.gz: cd51b3fc6b5f20f5896969e8eb3a4263d999f2544239606944194192f894e850
+  metadata.gz: c7fdda2e5d806be070a3255e8cef4a63b72acaeac87d7a7777d580bfb0fc0d0a
+  data.tar.gz: 2b23bf8808241eb64396672959a86ae86c26af05bb0d72049de646907cc9e99d
 SHA512:
-  metadata.gz: 6c1581a9ecc7f45b44342c49c529d12694c5d962808ef4ba7a0ec9d71aac5ae46852c99c242ec1b897c8c1b591d9ab66c55a24eacf0a4e6637de068624f36fc3
-  data.tar.gz: 3272e19424de3eed0f6c186b2bf14ac830ef226f9ce47207fd3c71fd38f622557a6542630c44934794cf9c650106a2e5a7e66ec475501220a685551799609111
+  metadata.gz: 37a5b065506fb61a675a72023057b0d24254ea7fa411ea358c68e255e0ffabf53079ab3a7214be59b2d09b02063aa2c09875576868a213df8c91526f90834ebd
+  data.tar.gz: fb0e3b15f73e8de66b56d09c7791b8e357477c859b83293474ec48c15d41d12298f91c974bd8ebeb0ae2cc6a3437ed598c442e6eb26e8a13787e71a3d35856f7

data/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## [0.3.2] - 2026-08-17
+
+Runtime correctness. Public SQL, Sync-per-unit, failure model, and the
+`Fiber::Scheduler` host contract are unchanged.
+
+### Fixed
+
+- Bounded waits (`Notification#wait`, `Task#wait`) park through
+  `scheduler.block(blocker, remaining)` and a monotonic deadline. They no
+  longer wrap `park` in `Timeout.timeout`. A wait timeout is not a work
+  timeout: `Notification#wait` no longer rescues `TimeoutError`, so an
+  enclosing `Runtime.with_timeout` cannot be swallowed by
+  `BoundedQueue#wait_on` or `wait_for_pinned_idle`. `wait(0)` polls.
+- `Runtime.with_timeout` (health probes and other work limits) calls
+  `scheduler.timeout_after(duration, Deadline, message)` when the hook
+  exists. `Deadline < Exception`, so `rescue => e` cannot eat it; the
+  method still raises `Runtime::TimeoutError` at its own boundary. A
+  scheduler without the hook falls back to stdlib `Timeout` and warns
+  once — `Thread#raise` can hit the wrong fiber.
+- `Notification#signal` and `Semaphore#release` skip a waiter that
+  `Task#stop` already released, or a fiber that is no longer alive. On a
+  deferred `unblock` the previous `shift` + wake handed the signal to the
+  stopped waiter and left the live one parked; a dead semaphore waiter
+  burned a pinned-pool slot. `park` also raises `Cancel` after a stop-wake
+  so the wait is not mistaken for a successful signal.
+
+### Unchanged
+
+- Per-fiber waiter-hash reuse, `Request` one-shot completion, watcher
+  `fiber_interrupt` / poll shutdown, and the host-installed scheduler
+  rule.
+
+## [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/runtime/notification.rb

@@ -7,19 +7,24 @@ module PgPipeline
         @waiters = []
       end
 
+      def waiting = @waiters.size
+
       def wait(timeout = nil)
+        wait_until(Runtime.deadline_for(timeout))
+      end
+
+      def wait_until(deadline = nil)
         Runtime.with_waiter(self, @waiters) do |waiter|
-          Runtime.with_timeout(timeout) { Runtime.park(self, waiter) { false } }
-          true
-        rescue TimeoutError
-          false
+          Runtime.park(self, waiter, deadline) { false }
         end
       end
 
       def signal
-        waiter = @waiters.shift or return false
-        Runtime.wake_dequeued(waiter, self)
-        true
+        while (waiter = @waiters.shift)
+          return true if Runtime.wake_dequeued(waiter, self)
+        end
+
+        false
       end
 
       def signal_all

data/lib/pg_pipeline/runtime/semaphore.rb

@@ -23,12 +23,12 @@ module PgPipeline
       end
 
       def release
-        if (node = @waiting.shift)
+        while (node = @waiting.shift)
           node.grant!
-          node.resume
-        else
-          @available += 1
+          return @available if node.resume
         end
+
+        @available += 1
         @available
       end
 
@@ -126,9 +126,10 @@ module PgPipeline
 
         def resume
           fiber = @fiber
-          return unless fiber.alive?
+          return false unless fiber.alive?
 
           @scheduler.unblock(@blocker, fiber)
+          true
         end
       end
 

data/lib/pg_pipeline/runtime/task.rb

@@ -22,7 +22,10 @@ module PgPipeline
       end
 
       def wait(timeout = nil)
-        Runtime.with_timeout(timeout) { join }
+        unless @done
+          deadline = Runtime.deadline_for(timeout)
+          raise TimeoutError, "task did not finish in time" unless join(deadline)
+        end
         raise @error if @error
 
         @result
@@ -94,8 +97,8 @@ module PgPipeline
 
       def release_blocker
         waiter = @blocker or return false
-        Runtime.wake(waiter, waiter[:blocker])
-        waiter[:fiber].alive?
+
+        Runtime.wake(waiter, waiter[:blocker]) && waiter[:fiber].alive?
       end
 
       def complete(result, error)
@@ -107,11 +110,11 @@ module PgPipeline
         wake_waiters
       end
 
-      def join
-        return if @done
+      def join(deadline)
+        return true if @done
 
         Runtime.with_waiter(self, @waiters) do |waiter|
-          Runtime.park(self, waiter) { @done }
+          Runtime.park(self, waiter, deadline) { @done }
         end
       end
 

data/lib/pg_pipeline/runtime.rb

@@ -7,12 +7,25 @@ require_relative "errors"
 module PgPipeline
   module Runtime
     class Cancel < Exception; end
+    class Deadline < Exception; end
     class TimeoutError < Error; end
 
     module_function
 
     CURRENT_TASK_KEY = :pg_pipeline_current_task
     WAITER_KEY = :pg_pipeline_waiter
+    DEADLINE_MESSAGE = "execution expired"
+
+    MISSING_TIMEOUT_HOOK_WARNING = <<~MESSAGE
+      pg_pipeline: %s does not implement #timeout_after.
+
+      Falling back to stdlib Timeout, which uses Thread#raise and can deliver
+      the timeout to an unrelated fiber. Use a scheduler that implements
+      #timeout_after (async, itsi-scheduler) or avoid Runtime.with_timeout
+      on this host.
+    MESSAGE
+
+    @warned_schedulers = {}
 
     def spawn(name: nil, &block)
       Task.spawn(name: name, &block)
@@ -22,6 +35,10 @@ module PgPipeline
       Fiber.scheduler or raise Error, "operation requires an active Fiber scheduler"
     end
 
+    def native_timeouts?(target = Fiber.scheduler)
+      !target.nil? && target.respond_to?(:timeout_after)
+    end
+
     def current_task
       Thread.current[CURRENT_TASK_KEY]
     end
@@ -44,16 +61,20 @@ module PgPipeline
       waiter
     end
 
-    def park(blocker, waiter)
+    def park(blocker, waiter, deadline = nil)
       scheduler = waiter[:scheduler]
       task = current_task
       task&.enter_block(waiter)
 
       until waiter[:ready] || yield
-        scheduler.block(blocker, nil)
+        remaining = deadline ? (deadline - monotonic_now) : nil
+        return false if deadline && remaining <= 0
+
+        scheduler.block(blocker, remaining)
         task&.raise_if_cancelled!
       end
-      nil
+      task&.raise_if_cancelled!
+      true
     ensure
       waiter[:blocker] = nil
       task&.exit_block
@@ -65,7 +86,10 @@ module PgPipeline
       waiters << waiter
       yield waiter
     ensure
-      waiters.delete(waiter) if waiter[:queued]
+      if waiter[:queued]
+        waiters.delete(waiter)
+        waiter[:queued] = false
+      end
     end
 
     def wake_dequeued(waiter, blocker)
@@ -73,21 +97,59 @@ module PgPipeline
       wake(waiter, blocker)
     end
 
+    def wake(waiter, blocker)
+      return false if waiter[:ready]
+
+      waiter[:ready] = true
+      fiber = waiter[:fiber]
+      return false unless fiber.alive?
+
+      waiter[:scheduler].unblock(blocker, fiber)
+      true
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def deadline_for(timeout)
+      return nil if timeout.nil?
+
+      seconds = Float(timeout)
+      raise ArgumentError, "timeout must be non-negative and finite" unless seconds.finite? && seconds >= 0
+
+      monotonic_now + seconds
+    end
+
     def with_timeout(duration)
       return yield if duration.nil?
 
-      timeout = Float(duration)
-      raise ArgumentError, "timeout must be non-negative and finite" unless timeout.finite? && timeout >= 0
+      seconds = Float(duration)
+      raise ArgumentError, "timeout must be non-negative and finite" unless seconds.finite? && seconds >= 0
 
-      ::Timeout.timeout(timeout, TimeoutError) { yield }
+      begin
+        arm_deadline(seconds) { yield }
+      rescue Deadline => e
+        raise TimeoutError, e.message
+      end
     end
 
-    def wake(waiter, blocker)
-      waiter[:ready] = true
-      fiber = waiter[:fiber]
-      return unless fiber.alive?
+    def arm_deadline(seconds, &block)
+      target = Fiber.scheduler
+      if native_timeouts?(target)
+        return target.timeout_after(seconds, Deadline, DEADLINE_MESSAGE, &block)
+      end
 
-      waiter[:scheduler].unblock(blocker, fiber)
+      warn_missing_timeout_hook(target) if target
+      ::Timeout.timeout(seconds, Deadline, DEADLINE_MESSAGE, &block)
+    end
+
+    def warn_missing_timeout_hook(target)
+      key = target.class
+      return if @warned_schedulers[key]
+
+      @warned_schedulers[key] = true
+      warn(format(MISSING_TIMEOUT_HOOK_WARNING, key))
     end
   end
 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.2"
 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.2
 platform: ruby
 authors:
 - Roman Hajdarov