pgoutput-decoder 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ef596cb600c9565a1d4088f34af0877c1dc135bf23e785800ba79cfabb4bc23
+  data.tar.gz: d64785d16df4da805dcb358c8193b70e360e4fc07d7afe2e676f4248c1588cb1
+SHA512:
+  metadata.gz: eb5c9be51c3ca6cf6a575f3ef2f8c6eca2e32730a9804f590576c0d53f2daa8e184af4d92c3131e4f3d370b793bd1373fe8e722a6d266f7e02072aa18c666bc0
+  data.tar.gz: 669771765199e459020de5a22b87a3d70d4927b1fd5a7a7d59e9159f7944c32304c619920dcd4550711630d143ff20b1444e5ff1ee2d3b8e4b4ec5f19ecf9177

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-05-31
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Keneth C. Demanawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,278 @@
+# pgoutput-decoder
+
+A high-level PostgreSQL `pgoutput` logical replication value decoder for Ruby.
+
+`pgoutput-decoder` is the companion layer to [`pgoutput-parser`](https://rubygems.org/gems/pgoutput-parser). It accepts immutable protocol messages produced by `pgoutput-parser` and turns tuple payloads into application-friendly Ruby row-change events.
+
+It does **not** parse PostgreSQL wire bytes and it does **not** open replication connections. Those concerns belong to lower-level parser and future client layers.
+
+---
+
+## Requirements
+
+- Ruby 3.4+
+- `pgoutput-parser` `~> 0.1`
+
+---
+
+## Architecture
+
+```text
+pgoutput-parser
+      │
+      ▼
+Protocol messages
+      │
+      ▼
+pgoutput-decoder
+      │
+      ▼
+Decoded row-change events
+```
+
+---
+
+## What This Gem Does
+
+- Decodes PostgreSQL OID-backed tuple values
+- Builds Ruby hashes from relation columns and tuple values
+- Tracks relation metadata from `Relation` messages
+- Tracks active transaction context from `Begin` / `Commit` messages
+- Attaches `transaction_id` to DML events
+- Returns immutable, Ractor-shareable event objects
+- Supports custom OID decoders
+
+---
+
+## What This Gem Does Not Do
+
+This gem intentionally does not:
+
+- Parse PostgreSQL `CopyData` bytes
+- Manage replication slots
+- Open replication connections
+- Maintain WAL acknowledgements
+- Reconnect to PostgreSQL
+- Publish events to queues
+- Integrate with ActiveRecord
+
+---
+
+## Installation
+
+```ruby
+gem "pgoutput-decoder"
+```
+
+Then:
+
+```bash
+bundle install
+```
+
+Require it with:
+
+```ruby
+require "pgoutput/decoder"
+```
+
+---
+
+## Quick Start
+
+```ruby
+require "pgoutput"
+require "pgoutput/decoder"
+
+stream = Pgoutput::RelationTracker.new
+decoder = Pgoutput::Decoder.new
+
+protocol_message = stream.process(payload)
+event = decoder.decode(protocol_message)
+```
+
+A `Relation` message updates decoder metadata and returns `nil`:
+
+```ruby
+decoder.decode(relation_message)
+# => nil
+```
+
+An insert message returns a decoded event:
+
+```ruby
+event = decoder.decode(insert_message)
+
+event.transaction_id
+# => 789
+
+event.schema
+# => "public"
+
+event.table
+# => "users"
+
+event.values
+# => { "id" => 7, "name" => "Alice", "active" => true }
+```
+
+---
+
+## Transaction Context
+
+PostgreSQL `pgoutput` carries the transaction ID in the `Begin` (`B`) message, not on every row-change message.
+
+The decoder remembers the active transaction and attaches it to decoded DML events:
+
+```ruby
+decoder.decode(begin_message)
+decoder.decode(relation_message)
+insert = decoder.decode(insert_message)
+
+insert.transaction_id
+# => 789
+```
+
+The transaction ID is useful for grouping changes, debugging, and CDC processing. It should not be treated as a globally permanent identifier because PostgreSQL transaction IDs can wrap around.
+
+---
+
+## Supported Events
+
+```ruby
+Pgoutput::Decoder::Events::Begin
+Pgoutput::Decoder::Events::Commit
+Pgoutput::Decoder::Events::Insert
+Pgoutput::Decoder::Events::Update
+Pgoutput::Decoder::Events::Delete
+```
+
+---
+
+## Default Type Support
+
+The default registry supports common scalar PostgreSQL OIDs:
+
+| OID  | Type             |
+| ---- | ---------------- |
+| 16   | boolean          |
+| 20   | bigint           |
+| 21   | smallint         |
+| 23   | integer          |
+| 25   | text             |
+| 114  | json             |
+| 700  | real             |
+| 701  | double precision |
+| 1043 | varchar          |
+| 1082 | date             |
+| 1114 | timestamp        |
+| 1184 | timestamptz      |
+| 1700 | numeric          |
+| 2950 | uuid             |
+| 3802 | jsonb            |
+
+Unsupported OIDs are returned as frozen raw strings.
+
+---
+
+## Binary Values
+
+Binary decoding is intentionally conservative.
+
+The decoder handles safe fixed-width binary scalar types such as:
+
+- boolean
+- int2
+- int4
+- int8
+- float4
+- float8
+
+Unsupported binary values are preserved as frozen raw bytes.
+
+---
+
+## Custom OID Decoders
+
+```ruby
+registry =
+  Pgoutput::Decoder::TypeRegistry.default.with_decoder(999_999) do |raw, format|
+    format == :text ? "custom:#{raw}" : raw
+  end
+
+decoder = Pgoutput::Decoder.new(type_registry: registry)
+```
+
+---
+
+## Update Events
+
+```ruby
+update = decoder.decode(update_message)
+
+update.old_key
+# => { "id" => 7 } or nil
+
+update.old_values
+# => { ... } or nil
+
+update.new_values
+# => { "id" => 7, "name" => "Bob" }
+```
+
+---
+
+## Delete Events
+
+```ruby
+delete = decoder.decode(delete_message)
+
+delete.old_key
+# => { "id" => 7 } or nil
+
+delete.old_values
+# => { ... } or nil
+```
+
+---
+
+## Ractor Safety
+
+Decoded events are deeply shareable:
+
+```ruby
+event = decoder.decode(update_message)
+
+Ractor.shareable?(event)
+# => true
+```
+
+The decoder instance itself is stateful and should not be shared across Ractors.
+
+---
+
+## Testing
+
+```bash
+bundle exec rake test
+```
+
+With coverage:
+
+```bash
+COVERAGE=true bundle exec rake test
+```
+
+---
+
+## Type Checking
+
+```bash
+bundle exec steep check
+```
+
+---
+
+## License
+
+MIT.

data/lib/pgoutput/decoder/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Pgoutput
+  module Decoder
+    VERSION = "0.0.0"
+  end
+end

data/lib/pgoutput/decoder.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "decoder/version"
+
+module Pgoutput
+  module Decoder
+    class Error < StandardError; end
+    # Your code goes here...
+  end
+end

data/sig/pgoutput/decoder.rbs

@@ -0,0 +1,6 @@
+module Pgoutput
+  module Decoder
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,163 @@
+--- !ruby/object:Gem::Specification
+name: pgoutput-decoder
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Ken C. Demanawa
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pgoutput-parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.0
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.27'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.27'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.87'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.87'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+- !ruby/object:Gem::Dependency
+  name: steep
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.44
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.44
+description: Decodes pgoutput-parser protocol messages into immutable Ruby row-change
+  events.
+email:
+- kenneth.c.demanawa@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/pgoutput/decoder.rb
+- lib/pgoutput/decoder/version.rb
+- sig/pgoutput/decoder.rbs
+homepage: https://github.com/kanutocd/pgoutput-decoder
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kanutocd/pgoutput-decoder
+  source_code_uri: https://github.com/kanutocd/pgoutput-decoder
+  changelog_uri: https://github.com/kanutocd/pgoutput-decoder/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: PostgreSQL pgoutput logical replication value decoder.
+test_files: []