pg_pipeline 0.2.5 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bc5e0b7e4d8a274bc84e16fc7205774f0c20a0d4b2ee2ed9482a676eb15b986
-  data.tar.gz: fd0f6c75af1815f9574b2133caff20c092db8f45f4ee04085bf975f51be231e0
+  metadata.gz: ca8a6402d9ee49ae0393f519c135f4174248df64aa27332f0773e095eb3179c8
+  data.tar.gz: 3c01ed0c9be6950a3b4d264bc613e5fef94c56dc81cb8916c791902ffeac61b0
 SHA512:
-  metadata.gz: 3a284e77a674fc31d6e1b0263ff32cd254814f8f535e84060227e30d5e7ffe284b104dc764dfb9cd9062dc4f56b5319b088d9649ff6213e60498775806930637
-  data.tar.gz: fa814de3830232f0f9136d3f582917bd91c426fc540f1d4cc19ded4872eb9eed4d45f936738d35f34c9377beb6057fe9e4c204b413f1654aa31b3d431e2c3266
+  metadata.gz: dc55189c229e3958e40781e30577ac82c3645f70fa55c2bce894baf9e0a423caa67d3ba533f77d5fce627943b424e0c7de2cea5f99a2ea25b0903022f438b3df
+  data.tar.gz: 508c35a99f8a9f5f3fa3665b741adaf58f593b6cc6c95fbfb86b48ded121adb010d4203fce6d9063274e510171e9f401ed0295b8691f2211ce273395cd7dcb9d

data/CHANGELOG.md

@@ -1,5 +1,106 @@
 # 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
+at runtime. Any `Fiber::Scheduler` host works (Async::Scheduler, Itsi::Scheduler,
+or another `Fiber.set_scheduler` implementation).
+
+This unlocks hosts that were previously impossible. On our stand, Itsi with
+0.3.0 serves ~26% more req/s than the 0.2.5 Falcon baseline (29350 vs 23254,
+4 workers, `oha -z 60s -c 1000`) — a configuration 0.2.5 could not run at all,
+since it required an Async reactor. Falcon throughput itself is unchanged
+(23007 vs 23254, inside run-to-run spread): this is a portability change, and
+the speedup comes from being free to pick the host.
+
+### Changed
+
+- New `PgPipeline::Runtime` primitives (`Notification`, `Queue`, `Semaphore`,
+  `Task`, `spawn`, `with_timeout`, `Cancel`) built on `Fiber.scheduler`.
+- Driver/pool background work uses `Runtime.spawn` instead of `parent.async`.
+- Pinned-connection ownership keys on `Fiber.current` (not `Async::Task.current`).
+- Watcher shutdown closes queues + connection, then joins tasks with a timeout.
+- Timeouts go through `Timeout.timeout` (correct `timeout_after` arity), never a
+  direct one-arg `scheduler.timeout_after` call.
+- Closed `Runtime::Queue#enqueue` is a no-op; supervisor sleep errors are recorded
+  and `stats` exposes `supervisor_alive`.
+- `Client#start` / `Pool#start` / `ConnectionDriver#start` no longer take
+  `parent:` (no Async task-tree ownership; use `Runtime.spawn` on the active
+  scheduler). Call sites that passed `start(parent: task)` should use `#start`.
+- Runtime dependency: only `pg`. `async` is a development dependency for the
+  existing Async-based test harness.
+
+### Migration
+
+Hosts must install a Fiber scheduler before `Client#start`. Under Async:
+
+```ruby
+require "async"
+Sync { client.start; ... }
+```
+
+Under Itsi, the server installs `Itsi::Scheduler` for you — just `client.start`.
+
+Apps that previously relied on `pg_pipeline` pulling in `async` transitively
+should add `gem "async"` themselves if they still use Async.
+
 ## [0.2.5] - 2026-08-03
 
 Control-plane cleanup on the multiplexed query path: fewer per-query allocations,

data/README.md

@@ -24,13 +24,66 @@ At 10 ms RTT a naïve pool does ~100 queries/s per connection.
 A pipelined connection can do thousands — the wire stays full instead of sitting idle.
 
 `pg_pipeline` is the Ruby control plane that does exactly this: it multiplexes
-independent queries from many Async fibers onto a small pool of libpq connections,
+independent queries from many fibers onto a small pool of libpq connections,
 routes FIFO results back to the right fiber, and keeps transactional/session work
 on separate pinned connections. All wire protocol work stays in libpq; zero C code here.
 
 The single-owner connection model, FIFO result ownership, and lifecycle approach
 are directly inspired by tokio-postgres.
 
+## Any Fiber scheduler, not just Async
+
+Up to 0.2.x the control plane was built on the `async` gem: `Async::Task`,
+`Async::Queue`, `Async::Semaphore`, and a task tree rooted in Async's reactor.
+That made Falcon the only realistic host.
+
+0.3.0 removes that. The control plane is built on Ruby's `Fiber::Scheduler`
+interface — `Fiber.schedule` plus the scheduler's `block` / `unblock` — and on
+nothing else. The host installs whichever scheduler it likes; the gem never
+installs one and never calls a scheduler hook directly. `async` is now a
+development dependency only, and the sole runtime dependency is `pg`.
+
+```ruby
+# Falcon / any Async host — unchanged, still works
+Async do
+  client = PgPipeline::Client.open(ENV["DATABASE_URL"])
+  client.query("SELECT * FROM users WHERE id = $1", [id]).first
+end
+
+# Itsi, with its own scheduler — no Async anywhere
+# Itsi.rb:
+#   fiber_scheduler "Itsi::Scheduler"
+client = PgPipeline::Client.open(ENV["DATABASE_URL"])
+client.query("SELECT * FROM users WHERE id = $1", [id]).first
+```
+
+The call site does not change: `query` blocks the *fiber*, not the thread, so
+application code reads synchronously with no `await` and no coloured functions.
+The only hard requirement is that some scheduler is installed on the current
+thread — under a web server running requests in `Fiber.schedule` that is free,
+while a plain script or rake task must set one up itself.
+
+### What it buys
+
+On our benchmark stand (4 workers, `oha -z 60s -c 1000`, single-row lookup by
+primary key, local PostgreSQL 16):
+
+| gem | server | scheduler | req/s |
+|---|---|---|---:|
+| 0.2.5 | Falcon | Async | 23254 |
+| 0.3.0 | Falcon | Async | 23007 |
+| 0.3.0 | Itsi | Async | 29206 |
+| 0.3.0 | Itsi | Itsi::Scheduler | 29350 |
+
+Falcon throughput is unchanged — this was a portability change, not a
+Falcon optimisation. The gain comes from being *able* to move: an Itsi host is
+roughly **26% faster than the 0.2.5 Falcon baseline**, and that configuration
+simply could not run before, because 0.2.5 required an Async reactor.
+
+Numbers from one stand on one machine; treat them as a direction, not a
+guarantee. Your own ratio depends on payload size, RTT, and how much of the
+request is spent outside the database.
+
 ## Installation
 
 ```ruby
@@ -212,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/bounded_queue.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require "async/notification"
-
 require_relative "errors"
+require_relative "runtime"
 
 module PgPipeline
   class BoundedQueue
@@ -12,15 +11,14 @@ module PgPipeline
     rescue ArgumentError, TypeError
       raise ArgumentError, "limit must be an integer >= 1"
     else
-      @items = []
-      @consumers = []
-      @producers = []
+      @items, @consumers, @producers = [], [], []
+
       @closed = false
       @close_error = nil
     end
 
     def enqueue(item)
-      loop do
+      while true
         raise_close_error if @closed
 
         if @items.size < @limit
@@ -34,7 +32,7 @@ module PgPipeline
     end
 
     def dequeue
-      loop do
+      while true
         unless @items.empty?
           item = @items.shift
           wake_one(@producers)
@@ -72,13 +70,13 @@ module PgPipeline
     private
 
     def wait_on(list)
-      notification = Async::Notification.new
+      notification = Runtime::Notification.new
       list << notification
       completed = false
-      begin
-        notification.wait
-        completed = true
-      ensure
+      notification.wait
+      completed = true
+    ensure
+      if notification
         still_queued = list.delete(notification)
         wake_one(list) if !completed && still_queued.nil? && !@closed
       end

data/lib/pg_pipeline/client.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "async"
-
 require_relative "errors"
 require_relative "pool"
 require_relative "request"
@@ -15,18 +13,18 @@ module PgPipeline
     attr_reader :guard
 
     def initialize(connection_args = nil, guard: :default, **pool_opts)
+      @owner_thread, @scheduler = nil, nil
+
       @guard = SessionGuard.normalize_mode!(guard)
       @pool = Pool.new(connection_args, **pool_opts)
       @started = false
-      @owner_thread = nil
-      @scheduler = nil
     end
 
     def self.open(connection_args = nil, **opts, &block)
       ClientOps.open(connection_args, opts, &block)
     end
 
-    def start(parent: Async::Task.current) = ClientOps.start(self, parent)
+    def start = ClientOps.start(self)
     def query(sql, params = RequestOps::EMPTY_PARAMS) = ClientOps.query(self, sql, params)
     def prepare(name, sql, param_types = nil) = ClientOps.prepare(self, name, sql, param_types)
     def stats = ClientOps.stats(self)
@@ -54,17 +52,16 @@ module PgPipeline
 
     def open(connection_args, opts)
       client = Client.new(connection_args, **opts).start
-      begin
-        yield client
-      ensure
-        client.close
-      end
+      yield client
+    ensure
+      client.close if client
     end
 
-    def start(client, parent)
+    def start(client)
       raise Error, "client already started" if started?(client)
+      raise Error, "client start requires an active Fiber scheduler" unless Fiber.scheduler
 
-      pool(client).start(parent: parent)
+      pool(client).start
       client.__send__(:owner_thread=, Thread.current)
       client.__send__(:scheduler=, Fiber.scheduler)
       client.__send__(:started=, true)
@@ -98,11 +95,9 @@ module PgPipeline
 
     def wait_for_request
       request = yield
-      begin
-        request.wait
-      ensure
-        request.cancel! unless request.settled?
-      end
+      request.wait
+    ensure
+      request.cancel! if request && !request.settled?
     end
 
     def submit_with_failover(client)