pgoutput-client 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4f6889c573693726868891513ab942b96ea305cef6c70407216a0fdf9046a32
-  data.tar.gz: 6ae8423d421ba51472c3f777451bc970f986c2b2b52c9cf6a234f97491c0ea70
+  metadata.gz: 9a0c63a95d0df00f5a4b8b5a0e85b01bbec1ed71688a41f853c065e2f2b01a03
+  data.tar.gz: 3e86b0d6e62c54c03edd73a86be9dce33997a60f2d5bd097459b3a2a0d75795a
 SHA512:
-  metadata.gz: 57d9bdda60c19cfc8c09e403d998af9f26bfcdf9ddb6dd81874f22142c00b8fd1e20cea7120fcbc7484886490870f1c3efe4fcab20a0e0a52283a2d456332977
-  data.tar.gz: 2840604c443d755c6850154284dfe412d60821adac80428b76fa3569f8db986109ee0457a695938b6e051f224e1b5bb69923cea13934a95184836595bfad6b4f
+  metadata.gz: 0577c07284f05bb0daa59ae055a39cdd456e2104f936c33b8a921473fb5554cf65dfae2f9d9d69ce82900e27dfb1a0f632c960654bae7526b73b62ab664f6007
+  data.tar.gz: e2ea5d853aee2079d280139f58f287063fc411e8ef846782c14b8f41c286bd1975027022ecfa395619f5494ce5622d640fc0a9b6bd1a0ca9a192ebbab5701d20

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.3.0 - 2026-07-17
+
+### Added
+
+- Added `Runner#slot_status` and `SlotInspector` for version-tolerant
+  `pg_replication_slots` inspection.
+- Added immutable `SlotStatus` snapshots exposing transport and slot-health
+  fields without imposing downstream recovery policy.
+
 ## 0.2.4 - 2026-06-17
 
 ### Added

data/README.md

@@ -58,6 +58,7 @@ Decoded row events
 - Supports `CREATE_REPLICATION_SLOT`
 - Supports `DROP_REPLICATION_SLOT`
 - Supports `START_REPLICATION SLOT ... LOGICAL ...`
+- Inspects version-dependent `pg_replication_slots` state
 - Parses XLogData envelopes
 - Parses primary keepalive messages
 - Builds standby feedback messages
@@ -175,6 +176,7 @@ It owns:
 - Keepalive handling
 - Standby status feedback
 - LSN conversion
+- Replication-slot catalog inspection
 
 ---
 
@@ -241,6 +243,45 @@ client = Pgoutput::Client::Runner.new(...)
 client.start { |payload, metadata| ... }
 ```
 
+Inspect the configured replication slot before applying a downstream recovery
+policy:
+
+```ruby
+status = client.slot_status
+
+if status.nil?
+  warn "replication slot is missing"
+else
+  puts status.restart_lsn
+  puts status.confirmed_flush_lsn
+  puts status.wal_status
+  puts status.invalidation_reason
+end
+```
+
+`SlotStatus` reflects the fields available on the connected PostgreSQL version.
+Optional fields are `nil` on versions that do not expose them. The client
+reports catalog state only; deciding whether a durable checkpoint is safe to
+resume remains the downstream runtime's responsibility.
+
+### Pgoutput::Client::SlotInspector
+
+Queries `pg_replication_slots` through a short-lived ordinary PostgreSQL
+connection. `#fetch(slot_name)` returns `nil` when the slot is missing and a
+`SlotStatus` snapshot otherwise. `Runner#slot_status` is the convenient entry
+point for inspecting the runner's configured slot.
+
+### Pgoutput::Client::SlotStatus
+
+Immutable replication-slot catalog snapshot. It exposes identity, activity,
+WAL position, retention, and invalidation fields including:
+
+- `slot_name`, `plugin`, `slot_type`, and `database`
+- `active`, `active_pid`, and `inactive_since`
+- `restart_lsn` and `confirmed_flush_lsn`
+- `wal_status`, `safe_wal_size`, and `catalog_xmin`
+- `conflicting` and `invalidation_reason`
+
 ### Pgoutput::Client::Configuration
 
 Immutable configuration object.
@@ -404,6 +445,11 @@ runner = Pgoutput::Client::Runner.new(
 )
 ```
 
+Existence alone does not prove that an existing or newly created slot can serve
+a downstream durable checkpoint. Use `Runner#slot_status` to obtain catalog
+state and apply continuity or recovery policy in the downstream runtime before
+streaming.
+
 Publication creation remains outside this gem. Create publications through
 application migrations, database bootstrap SQL, or infrastructure tooling.
 

data/lib/pgoutput/client/connection.rb

@@ -121,7 +121,7 @@ module Pgoutput
         socket = @pg_connection.socket_io
         return true unless socket
 
-        !!IO.select([socket], nil, nil, 0.1)
+        !!socket.wait_readable(0.1)
       end
 
       def exec(sql)

data/lib/pgoutput/client/runner.rb

@@ -70,6 +70,7 @@ module Pgoutput
       #   {Configuration#initialize}
       # @return [void]
       # @raise [ConfigurationError] if the supplied configuration is invalid
+      # rubocop:disable Style/ArgumentsForwarding -- YARD needs a named parameter
       def initialize(**options)
         @configuration = Configuration.new(
           **options # : untyped
@@ -84,6 +85,7 @@ module Pgoutput
         @last_error = nil
         @reconnect_attempts = 0
       end
+      # rubocop:enable Style/ArgumentsForwarding
 
       # Start streaming raw pgoutput payloads.
       #
@@ -144,9 +146,9 @@ module Pgoutput
       #
       # @yield [payload, metadata] called once for each XLogData payload
       # @return [void]
-      def restart(&block)
+      def restart(&)
         stop
-        start(&block)
+        start(&)
       end
 
       # Whether the runner is currently inside its streaming loop.
@@ -201,6 +203,17 @@ module Pgoutput
         )
       end
 
+      # Inspect the configured replication slot through PostgreSQL's catalog.
+      #
+      # This reports transport state without applying downstream checkpoint or
+      # recovery policy.
+      #
+      # @return [SlotStatus, nil] current slot state, or `nil` when missing
+      # @raise [ConnectionError] when PostgreSQL cannot be queried
+      def slot_status
+        SlotInspector.new(database_url: configuration.database_url).fetch(configuration.slot_name)
+      end
+
       private
 
       def setup_connection(connection)
@@ -222,12 +235,12 @@ module Pgoutput
         error.message.match?(/replication slot .* already exists/i)
       end
 
-      def run_stream_cycle(configuration, &block)
+      def run_stream_cycle(configuration, &)
         connection = Connection.open(configuration)
         setup_connection(connection)
         @connected_once = true
         @stream = Stream.new(connection:, configuration:, acked_lsn: @acked_lsn)
-        @stream.start(&block)
+        @stream.start(&)
         :done
       rescue ConnectionError => e
         @last_error = e

data/lib/pgoutput/client/slot_inspector.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pgoutput
+  module Client
+    # Reads PostgreSQL replication-slot catalog state.
+    #
+    # Inspection uses a short-lived ordinary database connection because
+    # catalog queries are separate from the long-lived replication protocol
+    # connection. Querying the whole catalog row through `to_jsonb` keeps the
+    # result compatible with PostgreSQL versions that expose different optional
+    # slot-health columns.
+    #
+    # @api public
+    class SlotInspector
+      # Version-tolerant catalog query for one replication slot.
+      #
+      # @return [String]
+      QUERY = <<~SQL
+        SELECT to_jsonb(slot) AS slot
+        FROM pg_catalog.pg_replication_slots AS slot
+        WHERE slot.slot_name = $1
+      SQL
+
+      # @return [String] PostgreSQL connection URL
+      attr_reader :database_url
+
+      # @param database_url [String] PostgreSQL connection URL
+      # @param connection_factory [#call, nil] optional connection factory for tests
+      def initialize(database_url:, connection_factory: nil)
+        @database_url = database_url
+        @connection_factory = connection_factory
+      end
+
+      # Fetch the configured slot's current catalog state.
+      #
+      # @param slot_name [String] replication slot name
+      # @return [SlotStatus, nil] snapshot, or `nil` when the slot is missing
+      # @raise [ConnectionError] when PostgreSQL cannot be queried
+      def fetch(slot_name)
+        connection = open_connection
+        row = connection.exec_params(QUERY, [String(slot_name)]).first
+        return nil unless row
+
+        SlotStatus.from_catalog(parse_catalog(row.fetch("slot")))
+      rescue pg_error_class => e
+        raise ConnectionError, e.message
+      ensure
+        connection&.close unless connection&.finished?
+      end
+
+      private
+
+      def open_connection
+        return @connection_factory.call(database_url) if @connection_factory
+
+        require "pg"
+        PG.connect(database_url)
+      end
+
+      def parse_catalog(value)
+        return value if value.is_a?(Hash)
+
+        JSON.parse(value)
+      end
+
+      def pg_error_class
+        require "pg"
+        PG::Error
+      end
+    end
+  end
+end

data/lib/pgoutput/client/slot_status.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Pgoutput
+  module Client
+    # Immutable snapshot of one PostgreSQL logical replication slot.
+    #
+    # Fields introduced by newer PostgreSQL versions are `nil` when the server
+    # does not expose them. The client reports transport/catalog state only;
+    # downstream runtimes remain responsible for deciding whether a checkpoint
+    # can safely resume from this slot.
+    #
+    # @api public
+    SlotStatusData = Data.define(
+      :slot_name,
+      :plugin,
+      :slot_type,
+      :database,
+      :active,
+      :active_pid,
+      :catalog_xmin,
+      :restart_lsn,
+      :confirmed_flush_lsn,
+      :wal_status,
+      :safe_wal_size,
+      :inactive_since,
+      :conflicting,
+      :invalidation_reason
+    )
+
+    # Typed replication-slot catalog snapshot.
+    #
+    # @api public
+    class SlotStatus < SlotStatusData
+      # Build a snapshot from a `pg_replication_slots` JSON object.
+      #
+      # @param attributes [Hash{String, Symbol=>Object}] catalog attributes
+      # @return [SlotStatus]
+      def self.from_catalog(attributes)
+        fetch = lambda do |key|
+          next attributes[key] if attributes.key?(key)
+
+          attributes[key.to_sym]
+        end
+
+        new(
+          slot_name: fetch.call("slot_name"),
+          plugin: fetch.call("plugin"),
+          slot_type: fetch.call("slot_type"),
+          database: fetch.call("database"),
+          active: fetch.call("active") == true,
+          active_pid: fetch.call("active_pid"),
+          catalog_xmin: fetch.call("catalog_xmin"),
+          restart_lsn: fetch.call("restart_lsn"),
+          confirmed_flush_lsn: fetch.call("confirmed_flush_lsn"),
+          wal_status: fetch.call("wal_status"),
+          safe_wal_size: fetch.call("safe_wal_size"),
+          inactive_since: fetch.call("inactive_since"),
+          conflicting: fetch.call("conflicting"),
+          invalidation_reason: fetch.call("invalidation_reason")
+        )
+      end
+    end
+  end
+end

data/lib/pgoutput/client/stream.rb

@@ -71,7 +71,7 @@ module Pgoutput
       # @raise [ProtocolError] if an unknown or malformed replication message is
       #   received
       # @raise [ConnectionError] if standby feedback cannot be sent
-      def start(&block)
+      def start(&)
         raise ArgumentError, "block required" unless block_given?
 
         @running = true
@@ -83,7 +83,7 @@ module Pgoutput
             next
           end
 
-          process_copy_data(copy_data, &block)
+          process_copy_data(copy_data, &)
           send_periodic_feedback
         end
       ensure

data/lib/pgoutput/client/version.rb

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

data/lib/pgoutput/client.rb

@@ -8,6 +8,8 @@ require_relative "client/xlog_data"
 require_relative "client/keepalive"
 require_relative "client/feedback"
 require_relative "client/state"
+require_relative "client/slot_status"
+require_relative "client/slot_inspector"
 require_relative "client/commands"
 require_relative "client/connection"
 require_relative "client/stream"

data/sig/json.rbs

@@ -0,0 +1,3 @@
+module JSON
+  def self.parse: (String source) -> Hash[(String | Symbol), untyped]
+end

data/sig/pgoutput/client/runner.rbs

@@ -79,6 +79,8 @@ module Pgoutput
 
       def monitor: () -> Pgoutput::Client::RunnerState
 
+      def slot_status: () -> (Pgoutput::Client::SlotStatus | nil)
+
       private
 
       def setup_connection: (untyped connection) -> untyped

data/sig/pgoutput/client/slot_inspector.rbs

@@ -0,0 +1,18 @@
+module Pgoutput
+  module Client
+    class SlotInspector
+      QUERY: String
+
+      attr_reader database_url: String
+
+      def initialize: (database_url: String, ?connection_factory: untyped) -> void
+      def fetch: (String slot_name) -> (SlotStatus | nil)
+
+      private
+
+      def open_connection: () -> untyped
+      def parse_catalog: (untyped value) -> Hash[(String | Symbol), untyped]
+      def pg_error_class: () -> singleton(::PG::Error)
+    end
+  end
+end

data/sig/pgoutput/client/slot_status.rbs

@@ -0,0 +1,41 @@
+module Pgoutput
+  module Client
+    class SlotStatusData < Data
+      attr_reader slot_name: String
+      attr_reader plugin: String?
+      attr_reader slot_type: String
+      attr_reader database: String?
+      attr_reader active: bool
+      attr_reader active_pid: Integer?
+      attr_reader catalog_xmin: String?
+      attr_reader restart_lsn: String?
+      attr_reader confirmed_flush_lsn: String?
+      attr_reader wal_status: String?
+      attr_reader safe_wal_size: Integer?
+      attr_reader inactive_since: String?
+      attr_reader conflicting: bool?
+      attr_reader invalidation_reason: String?
+
+      def self.new: (
+        slot_name: String,
+        plugin: String?,
+        slot_type: String,
+        database: String?,
+        active: bool,
+        active_pid: Integer?,
+        catalog_xmin: String?,
+        restart_lsn: String?,
+        confirmed_flush_lsn: String?,
+        wal_status: String?,
+        safe_wal_size: Integer?,
+        inactive_since: String?,
+        conflicting: bool?,
+        invalidation_reason: String?
+      ) -> instance
+    end
+
+    class SlotStatus < SlotStatusData
+      def self.from_catalog: (Hash[(String | Symbol), untyped] attributes) -> SlotStatus
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgoutput-client
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -53,11 +53,14 @@ files:
 - lib/pgoutput/client/keepalive.rb
 - lib/pgoutput/client/lsn.rb
 - lib/pgoutput/client/runner.rb
+- lib/pgoutput/client/slot_inspector.rb
+- lib/pgoutput/client/slot_status.rb
 - lib/pgoutput/client/state.rb
 - lib/pgoutput/client/stream.rb
 - lib/pgoutput/client/version.rb
 - lib/pgoutput/client/xlog_data.rb
 - lib/pgoutput_client.rb
+- sig/json.rbs
 - sig/pg.rbs
 - sig/pgoutput/client/commands.rbs
 - sig/pgoutput/client/configuration.rbs
@@ -67,6 +70,8 @@ files:
 - sig/pgoutput/client/keepalive.rbs
 - sig/pgoutput/client/lsn.rbs
 - sig/pgoutput/client/runner.rbs
+- sig/pgoutput/client/slot_inspector.rbs
+- sig/pgoutput/client/slot_status.rbs
 - sig/pgoutput/client/state.rbs
 - sig/pgoutput/client/stream.rbs
 - sig/pgoutput/client/version.rbs