pgoutput-client 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a375cce8bbb2d330974bfd22bdc0a7542c1c1ed5fe73f448e41bba717532aac2
-  data.tar.gz: 3c20c8e182548d5556d4a8a503a92d2d8c89d5c926a59eaaf537812d4bb5cdca
+  metadata.gz: e4f6889c573693726868891513ab942b96ea305cef6c70407216a0fdf9046a32
+  data.tar.gz: 6ae8423d421ba51472c3f777451bc970f986c2b2b52c9cf6a234f97491c0ea70
 SHA512:
-  metadata.gz: 78fc7ede75ae5fcd4b27adddef61d1f6b59ba8a26943bb44bf93d0dc5f2d97a477f36d12ec935fdf083792cbc8d37418e0b2a9f84fb7d14d15aa7e5847f8d2fd
-  data.tar.gz: 58ea9e8475789846b3caad462fcfef693df07ad8ef9cf724e877f38ba2ca53a73b3e1476971a7b5b1c9ad47bb0b8c20fae2e31f47674a377bf03c7d09cb1533c
+  metadata.gz: 57d9bdda60c19cfc8c09e403d998af9f26bfcdf9ddb6dd81874f22142c00b8fd1e20cea7120fcbc7484886490870f1c3efe4fcab20a0e0a52283a2d456332977
+  data.tar.gz: 2840604c443d755c6850154284dfe412d60821adac80428b76fa3569f8db986109ee0457a695938b6e051f224e1b5bb69923cea13934a95184836595bfad6b4f

data/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 ## Unreleased
 
+## 0.2.4 - 2026-06-17
+
+### Added
+
+- Added socket-aware replication stream polling.
+- Added E2E coverage for PostgreSQL restart and replication stream recovery.
+- Added connection readiness checks to E2E infrastructure.
+
+### Changed
+
+- Improved replication stream handling during idle periods.
+- Improved reconnect behavior after PostgreSQL restarts.
+- Improved standby feedback reliability during long-running streams.
+- Improved E2E test stability across PostgreSQL startup and restart scenarios.
+- Normalized `PG#get_copy_data` idle responses to simplify stream processing.
+
+### Fixed
+
+- Fixed replication stream recovery after PostgreSQL restart.
+- Fixed handling of idle COPY stream reads.
+- Fixed reconnect loops triggered by PostgreSQL replication timeouts.
+- Fixed E2E race conditions during PostgreSQL initialization.
+- Fixed replication slot creation behavior when a slot already exists.
+- Fixed several edge cases uncovered by Mammoth integration testing.
+
+### Documentation
+
+- Expanded YARD documentation coverage to 98.95%.
+
 ## 0.2.3 - 2026-06-17
 
 ### Fixed

data/README.md

@@ -363,6 +363,57 @@ Equivalent Rake task:
 bundle exec rake e2e:run
 ```
 
+## Transport lifecycle behavior
+
+`pgoutput-client` owns PostgreSQL logical replication transport and lifecycle
+management. It opens the replication connection, optionally creates the logical
+replication slot, starts streaming, sends standby status feedback, and retries
+reconnectable failures.
+
+### Idle standby feedback
+
+Long-running replication streams can be quiet for long periods when no WAL
+changes are produced. During those idle periods the client wakes periodically
+and sends standby status feedback so PostgreSQL does not terminate the walsender
+for replication timeout.
+
+Control the feedback cadence with `feedback_interval`:
+
+```ruby
+runner = Pgoutput::Client::Runner.new(
+  database_url: ENV.fetch("DATABASE_URL"),
+  slot_name: "mammoth_live",
+  publication_names: ["mammoth_publication"],
+  feedback_interval: 10.0
+)
+```
+
+### Idempotent automatic slot creation
+
+When `auto_create_slot` is enabled, the client treats slot creation as
+"ensure this slot exists". Missing slots are created before streaming; existing
+slots are reused and do not cause startup failure.
+
+```ruby
+runner = Pgoutput::Client::Runner.new(
+  database_url: ENV.fetch("DATABASE_URL"),
+  slot_name: "mammoth_live",
+  publication_names: ["mammoth_publication"],
+  auto_create_slot: true,
+  temporary_slot: false
+)
+```
+
+Publication creation remains outside this gem. Create publications through
+application migrations, database bootstrap SQL, or infrastructure tooling.
+
+### Restart recovery
+
+After a stream has connected successfully, transient PostgreSQL outages are
+retried through the reconnect lifecycle. This includes ordinary container or
+process restart windows where PostgreSQL temporarily refuses connections or
+reports that the database system is starting up.
+
 ---
 
 ## License

data/lib/pgoutput/client/connection.rb

@@ -76,14 +76,19 @@ module Pgoutput
 
       # Receive one CopyData payload from the server.
       #
-      # The call is non-blocking because the underlying `pg` call receives
-      # `false` for its blocking argument. `nil` means no complete CopyData
-      # payload is currently available.
+      # The stream must not block forever while PostgreSQL is idle, because the
+      # caller needs opportunities to send periodic standby feedback. Wait
+      # briefly for socket readability, then use the pg driver's blocking
+      # CopyData read only when data is available. `nil` means the stream is
+      # currently idle.
       #
       # @return [String, nil] raw CopyData payload or `nil`
       # @raise [ConnectionError] if receiving fails
       def get_copy_data # rubocop:disable Naming/AccessorMethodName
-        @pg_connection.get_copy_data(false)
+        return nil unless copy_data_readable?
+
+        copy_data = @pg_connection.get_copy_data(false)
+        copy_data == false ? nil : copy_data
       rescue PG::Error => e
         raise ConnectionError, e.message
       end
@@ -110,6 +115,15 @@ module Pgoutput
 
       private
 
+      def copy_data_readable?
+        return true unless @pg_connection.respond_to?(:socket_io)
+
+        socket = @pg_connection.socket_io
+        return true unless socket
+
+        !!IO.select([socket], nil, nil, 0.1)
+      end
+
       def exec(sql)
         @pg_connection.exec(sql)
       rescue PG::Error => e

data/lib/pgoutput/client/feedback.rb

@@ -2,6 +2,9 @@
 
 module Pgoutput
   module Client
+    # Internal immutable base class generated by `Data.define` for {Feedback}.
+    #
+    # @api private
     FeedbackData = Data.define(:received_lsn, :flushed_lsn, :applied_lsn, :client_clock, :reply_requested)
 
     # Standby status feedback message builder.

data/lib/pgoutput/client/keepalive.rb

@@ -2,6 +2,9 @@
 
 module Pgoutput
   module Client
+    # Internal immutable base class generated by `Data.define` for {Keepalive}.
+    #
+    # @api private
     KeepaliveData = Data.define(:wal_end, :server_clock, :reply_requested)
 
     # Immutable primary keepalive replication message.

data/lib/pgoutput/client/runner.rb

@@ -37,7 +37,17 @@ module Pgoutput
     # @see Stream
     # @api public
     class Runner
+      # Default number of reconnect attempts after a previously healthy stream
+      # fails. The default is intentionally large enough to survive ordinary
+      # PostgreSQL restart windows.
+      #
+      # @return [Integer]
       DEFAULT_RECONNECT_ATTEMPTS = 30
+
+      # Base reconnect backoff, in seconds. Attempt `n` sleeps for
+      # `n * DEFAULT_RECONNECT_BACKOFF`.
+      #
+      # @return [Float]
       DEFAULT_RECONNECT_BACKOFF = 0.5
 
       # Configuration used by this runner.

data/lib/pgoutput/client/state.rb

@@ -2,6 +2,9 @@
 
 module Pgoutput
   module Client
+    # Internal immutable base class generated by `Data.define` for {RunnerState}.
+    #
+    # @api private
     RunnerStateData = Data.define(
       :running,
       :stop_requested,

data/lib/pgoutput/client/version.rb

@@ -5,6 +5,6 @@ module Pgoutput
     # Current pgoutput-client gem version.
     #
     # @return [String]
-    VERSION = "0.2.3"
+    VERSION = "0.2.4"
   end
 end

data/lib/pgoutput/client/xlog_data.rb

@@ -2,6 +2,9 @@
 
 module Pgoutput
   module Client
+    # Internal immutable base class generated by `Data.define` for {XLogData}.
+    #
+    # @api private
     ReplicationXLogData = Data.define(:wal_start, :wal_end, :server_clock, :payload)
 
     # Immutable XLogData replication envelope.

data/lib/pgoutput/client.rb

@@ -13,6 +13,13 @@ require_relative "client/connection"
 require_relative "client/stream"
 require_relative "client/runner"
 
+# Namespace for PostgreSQL pgoutput logical replication components.
+#
+# The top-level namespace is shared by pgoutput ecosystem gems. This gem
+# defines only the `Pgoutput::Client` transport namespace and leaves protocol
+# parsing, value decoding, and CDC normalization to sibling libraries.
+#
+# @api public
 module Pgoutput
   # Namespace for PostgreSQL logical replication transport support.
   #

data/sig/pgoutput/client/connection.rbs

@@ -61,9 +61,11 @@ module Pgoutput
 
       # Receive one CopyData payload from the server.
       #
-      # The call is non-blocking because the underlying `pg` call receives
-      # `false` for its blocking argument. `nil` means no complete CopyData
-      # payload is currently available.
+      # The stream must not block forever while PostgreSQL is idle, because the
+      # caller needs opportunities to send periodic standby feedback. Wait
+      # briefly for socket readability, then use the pg driver's blocking
+      # CopyData read only when data is available. `nil` means the stream is
+      # currently idle.
       #
       # @return [String, nil] raw CopyData payload or `nil`
       # @raise [ConnectionError] if receiving fails
@@ -85,6 +87,8 @@ module Pgoutput
 
       private
 
+      def copy_data_readable?: () -> bool
+
       def exec: (untyped sql) -> untyped
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgoutput-client
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - Ken C. Demanawa