pgoutput-client 0.0.0 → 0.1.0

data/sig/pgoutput/client/feedback.rbs

@@ -0,0 +1,71 @@
+module Pgoutput
+  module Client
+    class FeedbackData < Data
+      attr_reader received_lsn: Integer
+      attr_reader flushed_lsn: Integer
+      attr_reader applied_lsn: Integer
+      attr_reader client_clock: Integer
+      attr_reader reply_requested: bool
+
+      def self.new: (
+        Integer received_lsn,
+        Integer flushed_lsn,
+        Integer applied_lsn,
+        Integer client_clock,
+        bool reply_requested
+      ) -> instance
+    end
+    
+    # Standby status feedback message builder.
+    #
+    # Logical replication clients periodically send standby status updates to
+    # tell PostgreSQL which WAL location has been received, flushed, and applied.
+    # `Feedback` models that update and can serialize itself into the CopyData
+    # payload expected by the replication protocol.
+    #
+    # @attr_reader received_lsn [Integer] latest WAL location received by the client
+    # @attr_reader flushed_lsn [Integer] latest WAL location flushed by the client
+    # @attr_reader applied_lsn [Integer] latest WAL location applied by the client
+    # @attr_reader client_clock [Integer] PostgreSQL timestamp in microseconds since 2000-01-01 UTC
+    # @attr_reader reply_requested [Boolean] whether this feedback is responding to an immediate-reply request
+    class Feedback < FeedbackData
+      def self.build: (
+        Integer received_lsn,
+        Integer flushed_lsn,
+        Integer applied_lsn,
+        ?reply_requested: bool
+      ) -> Feedback
+
+      # Build feedback using the current wall-clock time.
+      #
+      # By default, flushed and applied LSNs follow the received LSN. Callers can
+      # pass lower values if they need to distinguish receipt from durable flush
+      # or application progress.
+      #
+      # @param received_lsn [Integer] latest WAL location received by the client
+      # @param flushed_lsn [Integer] latest WAL location flushed by the client
+      # @param applied_lsn [Integer] latest WAL location applied by the client
+      # @param reply_requested [Boolean] whether this is an immediate reply
+      # @return [Feedback] immutable feedback value
+      def self.now: (received_lsn: untyped, ?flushed_lsn: untyped, ?applied_lsn: untyped, ?reply_requested: bool) -> untyped
+
+      # Build a protocol CopyData payload for standby status update.
+      #
+      # The payload begins with the standby status update tag `r`, followed by
+      # three unsigned 64-bit LSN fields, the PostgreSQL timestamp, and a
+      # one-byte reply-requested flag.
+      #
+      # @return [String] frozen binary CopyData payload
+      def to_copy_data: () -> untyped
+
+      # Current PostgreSQL protocol timestamp.
+      #
+      # PostgreSQL timestamps in replication messages are expressed as
+      # microseconds since 2000-01-01 00:00:00 UTC, not Unix epoch
+      # microseconds.
+      #
+      # @return [Integer] microseconds since 2000-01-01 UTC
+      def self.current_pg_time: () -> untyped
+    end
+  end
+end

data/sig/pgoutput/client/keepalive.rbs

@@ -0,0 +1,55 @@
+module Pgoutput
+  module Client   
+    class KeepaliveData < Data
+      attr_reader wal_end: Integer
+      attr_reader server_clock: Integer
+      attr_reader reply_requested: bool
+
+      def self.new: (
+        Integer wal_end,
+        Integer server_clock,
+        bool reply_requested
+      ) -> instance
+    end
+
+    # Immutable primary keepalive replication message.
+    #
+    # PostgreSQL sends keepalive CopyData payloads while a replication stream is
+    # active. The payload layout is:
+    #
+    # ```text
+    # Byte 0      : message tag `k`
+    # Bytes 1-8   : current server WAL end, unsigned 64-bit big-endian
+    # Bytes 9-16  : server clock, PostgreSQL timestamp format
+    # Byte 17     : reply-requested flag, 1 for immediate feedback
+    # ```
+    #
+    # The stream layer uses this message to advance its known WAL position and to
+    # decide whether to send standby status feedback immediately.
+    #
+    # @attr_reader wal_end [Integer] latest server WAL position
+    # @attr_reader server_clock [Integer] PostgreSQL server timestamp in
+    #   microseconds since 2000-01-01 UTC
+    # @attr_reader reply_requested [Boolean] whether PostgreSQL requested
+    #   immediate feedback
+    class Keepalive < KeepaliveData
+      # Parse a keepalive CopyData payload.
+      #
+      # @param bytes [String] raw CopyData payload beginning with `k`
+      # @return [Keepalive] immutable parsed keepalive message
+      # @raise [ProtocolError] if the payload is empty, has the wrong message
+      #   tag, or is too short to contain the required fields
+      def self.parse: (untyped bytes) -> untyped
+
+      # Latest server WAL position formatted as a PostgreSQL LSN string.
+      #
+      # @return [String]
+      def wal_end_lsn: () -> untyped
+
+      # @param binary [String]
+      # @param offset [Integer]
+      # @return [Integer]
+      def self.unpack_u64: (untyped binary, untyped offset) -> untyped
+    end
+  end
+end

data/sig/pgoutput/client/lsn.rbs

@@ -0,0 +1,36 @@
+module Pgoutput
+  module Client
+    # PostgreSQL Log Sequence Number conversion helpers.
+    #
+    # PostgreSQL represents LSNs as two hexadecimal 32-bit halves separated by a
+    # slash, such as `0/16B6C50`. The replication protocol transmits the same WAL
+    # position as an unsigned 64-bit integer. This module converts between those
+    # two representations.
+    #
+    # @example Parse a textual LSN
+    #   Pgoutput::Client::LSN.parse("0/10")
+    #   # => 16
+    #
+    # @example Format an integer WAL position
+    #   Pgoutput::Client::LSN.format(16)
+    #   # => "0/10"
+    #
+    # @api public
+    module LSN
+      # Parse a PostgreSQL LSN string into an integer WAL position.
+      #
+      # @param value [#to_s] LSN string in `HEX/HEX` form
+      # @return [Integer] unsigned 64-bit WAL position
+      # @raise [ArgumentError] if the value is not a valid LSN string
+      def self?.parse: (untyped value) -> untyped
+
+      # Format an integer WAL position as a PostgreSQL LSN string.
+      #
+      # @param value [#to_int, #to_s] non-negative integer WAL position
+      # @return [String] LSN string in uppercase hexadecimal `HEX/HEX` form
+      # @raise [ArgumentError] if the value is negative or cannot be coerced to
+      #   an integer
+      def self?.format: (untyped value) -> ::String
+    end
+  end
+end

data/sig/pgoutput/client/stream.rbs

@@ -0,0 +1,68 @@
+module Pgoutput
+  module Client
+    # Logical replication stream loop.
+    #
+    # `Stream` consumes PostgreSQL CopyData payloads from a {Connection}. It
+    # understands the two replication envelope message types used by PostgreSQL's
+    # streaming replication protocol:
+    #
+    # * `w` — XLogData, containing logical decoding plugin payload bytes.
+    # * `k` — primary keepalive, optionally requesting immediate feedback.
+    #
+    # The stream yields only XLogData plugin payloads. Keepalive messages are
+    # handled internally by updating the latest known WAL position and sending
+    # standby feedback when requested.
+    #
+    # @api private
+    class Stream
+      @connection: untyped
+
+      @configuration: untyped
+
+      @latest_lsn: untyped
+
+      @last_feedback_at: untyped
+
+      @running: untyped
+
+      # Build a stream loop.
+      #
+      # @param connection [Connection] replication connection
+      # @param configuration [Configuration] stream configuration
+      # @return [void]
+      def initialize: (connection: untyped, configuration: untyped) -> void
+
+      # Start the stream loop.
+      #
+      # The method blocks while the stream is running. For every XLogData
+      # envelope, it yields the raw pgoutput payload and the parsed envelope
+      # metadata. When no CopyData payload is currently available, the loop
+      # continues and checks again.
+      #
+      # @yield [payload, metadata] called for each XLogData payload
+      # @yieldparam payload [String] frozen raw pgoutput payload bytes
+      # @yieldparam metadata [XLogData] parsed WAL envelope metadata
+      # @return [void]
+      # @raise [ArgumentError] if no block is provided
+      # @raise [ProtocolError] if an unknown or malformed replication message is
+      #   received
+      # @raise [ConnectionError] if standby feedback cannot be sent
+      def start: () ?{ (?) -> untyped } -> untyped
+
+      # Stop the stream loop after the current iteration.
+      #
+      # @return [void]
+      def stop: () -> untyped
+
+      private
+
+      def process_copy_data: (untyped copy_data) { (untyped, untyped) -> untyped } -> untyped
+
+      def send_periodic_feedback: () -> (nil | untyped)
+
+      def send_feedback: (reply_requested: untyped) -> untyped
+
+      def monotonic_time: () -> untyped
+    end
+  end
+end

data/sig/pgoutput/client/version.rbs

@@ -0,0 +1,8 @@
+module Pgoutput
+  module Client
+    # Current pgoutput-client gem version.
+    #
+    # @return [String]
+    VERSION: "0.1.0"
+  end
+end

data/sig/pgoutput/client/xlog_data.rbs

@@ -0,0 +1,63 @@
+module Pgoutput
+  module Client
+    class ReplicationXLogData < Data
+      attr_reader wal_start: Integer
+      attr_reader wal_end: Integer
+      attr_reader server_clock: Integer
+      attr_reader payload: String
+
+      def self.new: (
+        Integer wal_start,
+        Integer wal_end,
+        Integer server_clock,
+        String payload
+      ) -> instance
+    end
+
+    # Immutable XLogData replication envelope.
+    #
+    # PostgreSQL wraps logical decoding plugin output in an XLogData CopyData
+    # payload while streaming replication is active. The payload layout is:
+    #
+    # ```text
+    # Byte 0      : message tag `w`
+    # Bytes 1-8   : WAL start position, unsigned 64-bit big-endian
+    # Bytes 9-16  : WAL end position, unsigned 64-bit big-endian
+    # Bytes 17-24 : server clock, PostgreSQL timestamp format
+    # Bytes 25..  : logical decoding plugin payload
+    # ```
+    #
+    # Instances are created through {.parse} and made shareable so they can cross
+    # Ractor boundaries with their frozen payload bytes.
+    #
+    # @attr_reader wal_start [Integer] WAL position where this message begins
+    # @attr_reader wal_end [Integer] WAL position after this message
+    # @attr_reader server_clock [Integer] PostgreSQL server timestamp in
+    #   microseconds since 2000-01-01 UTC
+    # @attr_reader payload [String] frozen raw logical decoding plugin payload
+    class XLogData < ReplicationXLogData
+      # Parse an XLogData CopyData payload.
+      #
+      # @param bytes [String] raw CopyData payload beginning with `w`
+      # @return [XLogData] immutable parsed envelope
+      # @raise [ProtocolError] if the payload is empty, has the wrong message
+      #   tag, or is too short to contain the required fields
+      def self.parse: (untyped bytes) -> untyped
+
+      # Starting WAL position formatted as a PostgreSQL LSN string.
+      #
+      # @return [String]
+      def wal_start_lsn: () -> untyped
+
+      # Ending WAL position formatted as a PostgreSQL LSN string.
+      #
+      # @return [String]
+      def wal_end_lsn: () -> untyped
+
+      # @param binary [String]
+      # @param offset [Integer]
+      # @return [Integer]
+      def self.unpack_u64: (untyped binary, untyped offset) -> untyped
+    end
+  end
+end

data/sig/pgoutput/client.rbs

@@ -1,6 +1,97 @@
 module Pgoutput
+  # Namespace for PostgreSQL logical replication transport support.
+  #
+  # `Pgoutput::Client` is the replication transport layer of the CDC Ecosystem.
+  # It is responsible for connecting to PostgreSQL in replication mode, creating
+  # or consuming replication slots, issuing `START_REPLICATION`, reading CopyData
+  # messages, and sending standby feedback.
+  #
+  # This namespace intentionally does not parse pgoutput plugin payloads into
+  # table-level changes. Raw plugin bytes are yielded to downstream protocol and
+  # type layers such as `pgoutput-parser` and `pgoutput-decoder`.
+  #
+  # @api public
   module Client
-    VERSION: String
-    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    # High-level logical replication client facade.
+    #
+    # `Runner` is the simplest public entry point for consumers that want to
+    # stream raw pgoutput payloads without manually managing a replication
+    # connection. It owns the connection lifecycle for one logical replication
+    # stream:
+    #
+    # 1. Build an immutable {Configuration} from keyword arguments.
+    # 2. Open a PostgreSQL replication connection.
+    # 3. Optionally create the configured replication slot.
+    # 4. Start logical replication.
+    # 5. Yield raw pgoutput payload bytes and {XLogData} metadata.
+    # 6. Close the connection when streaming exits.
+    #
+    # @example Stream raw pgoutput messages
+    #   runner = Pgoutput::Client::Runner.new(
+    #     database_url: "postgres://localhost/app",
+    #     slot_name: "cdc_slot",
+    #     publication_names: ["app_publication"]
+    #   )
+    #
+    #   runner.start do |payload, metadata|
+    #     puts "received #{payload.bytesize} bytes at #{metadata.wal_end_lsn}"
+    #   end
+    #
+    # @see Configuration
+    # @see Connection
+    # @see Stream
+    # @api public
+    class Runner
+      @configuration: untyped
+
+      @stopped: untyped
+
+      # Configuration used by this runner.
+      #
+      # @return [Configuration]
+      attr_reader configuration: untyped
+
+      # Build a runner from configuration keyword arguments.
+      #
+      # The accepted keywords are the same as {Configuration#initialize}. The
+      # resulting configuration object is immutable and reused for the lifetime
+      # of this runner.
+      #
+      # @param options [Hash{Symbol=>Object}] configuration options forwarded to
+      #   {Configuration#initialize}
+      # @return [void]
+      # @raise [ConfigurationError] if the supplied configuration is invalid
+      def initialize: (**untyped options) -> void
+
+      # Start streaming raw pgoutput payloads.
+      #
+      # This method blocks until the stream stops or the underlying connection
+      # raises an error. The yielded payload is the raw logical decoding plugin
+      # payload contained inside PostgreSQL's XLogData envelope; callers normally
+      # pass this payload to a pgoutput parser.
+      #
+      # @yield [payload, metadata] called once for each XLogData payload
+      # @yieldparam payload [String] frozen raw pgoutput payload bytes
+      # @yieldparam metadata [XLogData] WAL envelope metadata for the payload
+      # @return [void]
+      # @raise [ArgumentError] if no block is provided
+      # @raise [ConnectionError] if a PostgreSQL connection or command fails
+      # @raise [ProtocolError] if an invalid replication message is received
+      def start: () ?{ (?) -> untyped } -> untyped
+
+      # Request graceful stop.
+      #
+      # This method records the caller's intent to stop. The current
+      # implementation does not yet interrupt an active {Stream}; it exists as
+      # part of the public lifecycle API and may be wired into cooperative stream
+      # shutdown in a future release.
+      #
+      # @return [void]
+      def stop: () -> nil
+
+      private
+
+      def setup_connection: (untyped connection) -> untyped
+    end
   end
 end

metadata

@@ -1,15 +1,30 @@
 --- !ruby/object:Gem::Specification
 name: pgoutput-client
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Ken C. Demanawa
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: Write a longer description or delete this line.
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+description: Transport-only PostgreSQL logical replication client for receiving pgoutput
+  CopyData payloads.
 email:
 - kenneth.c.demanawa@gmail.com
 executables: []
@@ -17,20 +32,41 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/pgoutput/client.rb
+- lib/pgoutput/client/commands.rb
+- lib/pgoutput/client/configuration.rb
+- lib/pgoutput/client/connection.rb
+- lib/pgoutput/client/errors.rb
+- lib/pgoutput/client/feedback.rb
+- lib/pgoutput/client/keepalive.rb
+- lib/pgoutput/client/lsn.rb
+- lib/pgoutput/client/stream.rb
 - lib/pgoutput/client/version.rb
+- lib/pgoutput/client/xlog_data.rb
+- lib/pgoutput_client.rb
+- sig/pg.rbs
 - sig/pgoutput/client.rbs
-homepage: https://github.com/kanutocd/pgoutput-client
+- sig/pgoutput/client/commands.rbs
+- sig/pgoutput/client/configuration.rbs
+- sig/pgoutput/client/connection.rbs
+- sig/pgoutput/client/errors.rbs
+- sig/pgoutput/client/feedback.rbs
+- sig/pgoutput/client/keepalive.rbs
+- sig/pgoutput/client/lsn.rbs
+- sig/pgoutput/client/stream.rbs
+- sig/pgoutput/client/version.rbs
+- sig/pgoutput/client/xlog_data.rbs
+homepage: https://kanutocd.github.io/pgoutput-client/
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/kanutocd/pgoutput-client
+  homepage_uri: https://kanutocd.github.io/pgoutput-client/
   source_code_uri: https://github.com/kanutocd/pgoutput-client
   changelog_uri: https://github.com/kanutocd/pgoutput-client/blob/main/CHANGELOG.md
+  documentation_uri: https://kanutocd.github.io/pgoutput-client/
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -45,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Write a short summary, because RubyGems requires one.
+summary: PostgreSQL pgoutput logical replication transport client.
 test_files: []

data/CODE_OF_CONDUCT.md

@@ -1,10 +0,0 @@
-# Code of Conduct
-
-"pgoutput-client" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
-
-* Participants will be tolerant of opposing views.
-* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
-* When interpreting the words and actions of others, participants should always assume good intentions.
-* Behaviour which can be reasonably considered harassment will not be tolerated.
-
-If you have any concerns about behaviour within this project, please contact us at ["kenneth.c.demanawa@gmail.com"](mailto:"kenneth.c.demanawa@gmail.com").

data/Rakefile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]