cdc-solid-queue 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3f4a62ca92fb8b26d59aa1afa8fb4790aff8ae1703dca92aeee332cf9fb63e25
+  data.tar.gz: 5b15208473f3163aae05a65f17f3e0293344c38a85d4ad47415245ae3053b953
+SHA512:
+  metadata.gz: 8b1e6647bae6782d8952626f018e0579907db31bf31f99fe01bf9ec95ca48e649b61985e1af3ac0a5a1b8572e16533b9775435e237a7305792adb31b61260f09
+  data.tar.gz: c3759751bb907ee349ec68b92eb3ca9b8f9e7deaac5e26a762a3cbd94b3958180fd5e8ce0a01e3d3ddf17e98be66ae106144df24fcf6eebd552e52f56c88c25e

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Initial implementation skeleton.
+- Configuration object.
+- Event serializer.
+- Enqueuer.
+- ProcessorJob mixin.
+- Test coverage gate.
+- RBS signatures.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kenneth 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,87 @@
+# cdc-solid-queue
+
+Rails-native durable CDC job backend for Solid Queue.
+
+```text
+PostgreSQL WAL
+  -> pgoutput-client
+  -> pgoutput-parser / pgoutput-decoder
+  -> pgoutput-source-adapter
+  -> CDC::Core::ChangeEvent
+  -> cdc-solid-queue
+  -> Solid Queue
+  -> ApplicationJob
+```
+
+## Requirements
+
+- Ruby 3.4+
+- Rails 7.1+
+- Solid Queue 1.0+
+- PostgreSQL logical replication
+
+Only PostgreSQL is supported in the initial implementation.
+
+## Usage
+
+```ruby
+class UserChangedJob < ApplicationJob
+  include CDC::SolidQueue::ProcessorJob
+
+  def process(event)
+    # event is a CDC::Core::ChangeEvent
+  end
+end
+```
+
+```ruby
+CDC::SolidQueue.configure do |config|
+  config.processor_job = UserChangedJob
+  config.queue = "cdc"
+  config.preserve_order = true
+  config.ordering_key = :identity
+  config.checkpoint = CDC::SolidQueue::Checkpoint.new
+  config.postgresql = {
+    database_url: ENV.fetch("DATABASE_URL"),
+    slot: "cdc_solid_queue",
+    publication: "cdc_publication"
+  }
+end
+```
+
+`config.queue` is applied through Active Job's `set(queue:)` API when the job
+class supports it. When `preserve_order` is enabled, the enqueued payload also
+includes cdc-solid-queue metadata with the configured ordering key and computed
+ordering value.
+
+## Rails Task
+
+Rails applications can load the Railtie integration:
+
+```ruby
+require "cdc/solid_queue/railtie"
+```
+
+Then start ingestion with:
+
+```bash
+bin/rails cdc_solid_queue:start
+```
+
+The task wires `Pgoutput::Client::Runner`, `Pgoutput::RelationTracker`,
+`Pgoutput::Decoder`, and `Pgoutput::SourceAdapter::Cdc` into the
+`CDC::SolidQueue::Runner`.
+
+## MVP Checkpoint Rule
+
+A checkpoint advances after the Solid Queue job is durably inserted. Job execution success is handled by Solid Queue retry semantics.
+
+## Quality Gates
+
+The first implementation is designed around:
+
+- 100% line coverage
+- 100% branch coverage
+- RBS validation
+- RuboCop configuration
+- YARD documentation

data/lib/cdc/solid_queue/checkpoint.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CDC
+  module SolidQueue
+    # Minimal in-memory checkpoint store.
+    #
+    # Applications that need durable replay safety should provide a persistent
+    # object that responds to #advance(event, result).
+    class Checkpoint
+      # @return [Object, nil]
+      attr_reader :position
+
+      # Build an empty checkpoint.
+      def initialize
+        @position = nil
+      end
+
+      # Advance to the best known source position for an enqueued event.
+      #
+      # @param event [Object]
+      # @param result [Object]
+      # @return [Object, nil]
+      def advance(event, result = nil)
+        @position = position_for(event) || result_position(result) || @position
+      end
+
+      private
+
+      def position_for(event)
+        payload = EventSerializer.dump(event)
+        payload['source_position'] || payload['commit_lsn'] || payload.dig('metadata', 'wal_end_lsn')
+      rescue SerializationError
+        nil
+      end
+
+      def result_position(result)
+        return result.checkpoint_position if result.respond_to?(:checkpoint_position)
+
+        nil
+      end
+    end
+  end
+end

data/lib/cdc/solid_queue/configuration.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module CDC
+  module SolidQueue
+    # Runtime configuration for PostgreSQL CDC ingestion into Solid Queue.
+    #
+    # The configuration object is intentionally small in the first release. It
+    # describes the target job class, Solid Queue queue name, ordering behavior,
+    # and PostgreSQL replication settings.
+    class Configuration
+      # The only CDC source supported by the initial implementation.
+      SUPPORTED_SOURCE = :postgresql
+      # Supported ordering scopes for serialized CDC events.
+      ORDERING_KEYS = %i[identity primary_key relation transaction global none].freeze
+
+      attr_accessor :processor_job, :queue, :preserve_order, :ordering_key, :postgresql, :checkpoint
+
+      # Build a configuration with safe defaults.
+      def initialize
+        @processor_job = nil
+        @queue = 'cdc'
+        @preserve_order = true
+        @ordering_key = :identity
+        @postgresql = {}
+        @checkpoint = Checkpoint.new
+      end
+
+      # Validate this configuration.
+      #
+      # @return [true]
+      # @raise [ConfigurationError] if required values are missing
+      # @raise [UnsupportedSourceError] if a non-PostgreSQL source is supplied
+      # rubocop:disable Naming/PredicateMethod
+      def validate!
+        validate_processor_job!
+        validate_queue!
+        validate_ordering_key!
+        validate_postgresql!
+        validate_checkpoint!
+        true
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Return a normalized source name.
+      #
+      # @return [Symbol]
+      def source
+        configured = @postgresql.fetch(:source, SUPPORTED_SOURCE)
+        configured.to_sym
+      end
+
+      private
+
+      def validate_processor_job!
+        return if @processor_job.respond_to?(:perform_later) || @processor_job.respond_to?(:perform_now)
+
+        raise ConfigurationError, 'processor_job must respond to perform_later or perform_now'
+      end
+
+      def validate_queue!
+        return if @queue.is_a?(String) && !@queue.empty?
+
+        raise ConfigurationError, 'queue must be a non-empty String'
+      end
+
+      def validate_ordering_key!
+        return if ORDERING_KEYS.include?(@ordering_key)
+
+        raise ConfigurationError, "ordering_key must be one of: #{ORDERING_KEYS.join(', ')}"
+      end
+
+      def validate_postgresql!
+        raise UnsupportedSourceError, 'cdc-solid-queue supports only PostgreSQL' unless source == SUPPORTED_SOURCE
+        return unless @postgresql.empty?
+
+        raise ConfigurationError, 'postgresql settings are required'
+      end
+
+      def validate_checkpoint!
+        return if @checkpoint.nil? || @checkpoint.respond_to?(:advance)
+
+        raise ConfigurationError, 'checkpoint must respond to advance'
+      end
+    end
+  end
+end

data/lib/cdc/solid_queue/enqueuer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module CDC
+  module SolidQueue
+    # Enqueues normalized CDC events as Solid Queue-backed Active Job jobs.
+    class Enqueuer
+      # @return [Configuration]
+      attr_reader :configuration
+
+      # @param configuration [Configuration]
+      def initialize(configuration)
+        @configuration = configuration
+        @configuration.validate!
+      end
+
+      # Enqueue one CDC event.
+      #
+      # @param event [Object, Hash]
+      # @return [Object] Active Job return value
+      def enqueue(event)
+        payload = EventSerializer.dump(event)
+        payload = EventSerializer.with_enqueue_metadata(payload, enqueue_metadata(payload))
+        job = configuration.processor_job
+        return async_job(job).perform_later(payload) if job.respond_to?(:perform_later)
+
+        job.perform_now(payload)
+      end
+
+      private
+
+      def async_job(job)
+        return job.set(queue: configuration.queue) if job.respond_to?(:set)
+
+        job
+      end
+
+      def enqueue_metadata(payload)
+        {
+          'queue' => configuration.queue,
+          'preserve_order' => configuration.preserve_order,
+          'ordering_key' => configuration.ordering_key,
+          'ordering_value' => ordering_value(payload)
+        }
+      end
+
+      def ordering_value(payload)
+        return nil unless configuration.preserve_order
+
+        EventSerializer.ordering_value(payload, configuration.ordering_key)
+      end
+    end
+  end
+end

data/lib/cdc/solid_queue/error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CDC
+  module SolidQueue
+    # Base error for all cdc-solid-queue failures.
+    class Error < StandardError; end
+
+    # Raised when configuration is missing or invalid.
+    class ConfigurationError < Error; end
+
+    # Raised when an unsupported source is configured.
+    class UnsupportedSourceError < ConfigurationError; end
+
+    # Raised when an event cannot be serialized for job execution.
+    class SerializationError < Error; end
+  end
+end

data/lib/cdc/solid_queue/event_serializer.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module CDC
+  module SolidQueue
+    # Converts CDC events into Solid Queue-safe payloads.
+    #
+    # Payloads are plain hashes so Active Job can serialize them without needing
+    # to load the original event object in the queue database.
+    class EventSerializer
+      # Reserved payload key for cdc-solid-queue enqueue metadata.
+      INTERNAL_METADATA_KEY = '_cdc_solid_queue'
+
+      # Serialize an event-like object.
+      #
+      # @param event [Object] event object or Hash
+      # @return [Hash] serializable event payload
+      # @raise [SerializationError] when the event cannot be represented
+      def self.dump(event)
+        payload = if event.is_a?(Hash)
+                    event
+                  elsif event.respond_to?(:to_h)
+                    event.to_h
+                  else
+                    raise SerializationError, 'event must respond to to_h or be a Hash'
+                  end
+
+        normalize_hash(payload)
+      end
+
+      # Load a serialized event payload.
+      #
+      # @param payload [Hash]
+      # @return [Hash]
+      # @raise [SerializationError] when payload is invalid
+      def self.load(payload)
+        raise SerializationError, 'payload must be a Hash' unless payload.is_a?(Hash)
+
+        strip_internal_metadata(normalize_hash(payload))
+      end
+
+      # Load a serialized event payload into a CDC event when possible.
+      #
+      # @param payload [Hash]
+      # @return [CDC::Core::ChangeEvent, Hash]
+      def self.load_event(payload)
+        normalized = load(payload)
+        return normalized unless change_event_payload?(normalized)
+
+        build_change_event(normalized)
+      end
+
+      # Attach enqueue metadata without changing the event representation.
+      #
+      # @param payload [Hash]
+      # @param metadata [Hash]
+      # @return [Hash]
+      def self.with_enqueue_metadata(payload, metadata)
+        normalized = normalize_hash(payload)
+        normalized.merge(INTERNAL_METADATA_KEY => normalize_hash(metadata))
+      end
+
+      # Return cdc-solid-queue metadata from an enqueued payload.
+      #
+      # @param payload [Hash]
+      # @return [Hash]
+      def self.enqueue_metadata(payload)
+        normalized = normalize_hash(payload)
+        metadata = normalized[INTERNAL_METADATA_KEY]
+        metadata.is_a?(Hash) ? metadata : {}
+      end
+
+      # Return the ordering value for a serialized event.
+      #
+      # @param payload [Hash]
+      # @param key [Symbol]
+      # @return [Object, nil]
+      def self.ordering_value(payload, key)
+        normalized = load(payload)
+        case key
+        when :identity, :primary_key
+          normalized['identity'] || normalized['primary_key']
+        when :relation
+          [normalized['namespace'] || normalized['schema'], normalized['entity'] || normalized['table']]
+        when :transaction
+          normalized['transaction_id']
+        when :global
+          normalized['source_position'] || normalized['commit_lsn']
+        when :none
+          nil
+        end
+      end
+
+      # Normalize hash keys to strings recursively.
+      #
+      # @param value [Object]
+      # @return [Object]
+      def self.normalize_hash(value)
+        case value
+        when Hash
+          # @type var normalized: Hash[String, untyped]
+          normalized = {}
+          value.each_with_object(normalized) do |(key, child), normalized|
+            normalized[key.to_s] = normalize_hash(child)
+          end
+        when Array
+          value.map { |child| normalize_hash(child) }
+        when String, Symbol, Numeric, true, false, nil
+          value
+        else
+          value.to_s
+        end
+      end
+      private_class_method :normalize_hash
+
+      def self.build_change_event(normalized)
+        CDC::Core::ChangeEvent.new(
+          operation: normalized.fetch('operation'),
+          schema: normalized.fetch('schema'),
+          table: normalized.fetch('table'),
+          old_values: normalized['old_values'],
+          new_values: normalized['new_values'],
+          primary_key: normalized['primary_key'],
+          transaction_id: normalized['transaction_id'],
+          commit_lsn: normalized['commit_lsn'],
+          sequence_number: normalized['sequence_number'],
+          occurred_at: normalized['occurred_at'],
+          metadata: normalized['metadata'] || {}
+        )
+      end
+      private_class_method :build_change_event
+
+      def self.strip_internal_metadata(payload)
+        payload.reject { |key, _value| key == INTERNAL_METADATA_KEY }
+      end
+      private_class_method :strip_internal_metadata
+
+      def self.change_event_payload?(payload)
+        payload.key?('operation') && payload.key?('schema') && payload.key?('table')
+      end
+      private_class_method :change_event_payload?
+    end
+  end
+end

data/lib/cdc/solid_queue/postgresql_stream.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'pgoutput_client'
+require 'pgoutput'
+require 'pgoutput/decoder'
+require 'pgoutput/source_adapter'
+
+module CDC
+  module SolidQueue
+    # Enumerable stream that normalizes PostgreSQL pgoutput payloads into CDC events.
+    class PostgresqlStream
+      # @param configuration [Configuration]
+      # @param client_runner [Object, nil]
+      # @param relation_tracker [Object]
+      # @param decoder [Object]
+      # @param adapter [Object, nil]
+      def initialize(configuration, client_runner: nil, relation_tracker: Pgoutput::RelationTracker.new,
+                     decoder: Pgoutput::Decoder.new, adapter: nil)
+        @configuration = configuration
+        @client_runner = client_runner || build_client_runner
+        @relation_tracker = relation_tracker
+        @decoder = decoder
+        @adapter = adapter || build_adapter
+        @transport_metadata = nil
+      end
+
+      # Stream normalized CDC::Core::ChangeEvent instances.
+      #
+      # @yieldparam event [CDC::Core::ChangeEvent]
+      # @return [void]
+      def each
+        return enum_for(:each) unless block_given?
+
+        @client_runner.start do |payload, metadata|
+          @transport_metadata = metadata
+          event = normalize(payload)
+          yield event unless event.nil?
+        ensure
+          @transport_metadata = nil
+        end
+      end
+
+      private
+
+      def build_client_runner
+        Pgoutput::Client::Runner.new(**postgresql_options)
+      end
+
+      def postgresql_options
+        settings = @configuration.postgresql
+        {
+          database_url: settings.fetch(:database_url) { ENV.fetch('DATABASE_URL') },
+          slot_name: settings.fetch(:slot) { settings.fetch(:slot_name) },
+          publication_names: settings.fetch(:publication) { settings.fetch(:publication_names) },
+          start_lsn: settings[:start_lsn],
+          auto_create_slot: settings.fetch(:auto_create_slot, false),
+          temporary_slot: settings.fetch(:temporary_slot, false),
+          binary: settings.fetch(:binary, false),
+          messages: settings.fetch(:messages, false)
+        }.compact
+      end
+
+      def build_adapter
+        Pgoutput::SourceAdapter::Cdc.new(metadata_builder: method(:metadata_for))
+      end
+
+      def normalize(payload)
+        message = @relation_tracker.process(payload)
+        decoded = @decoder.decode(message)
+        return nil if decoded.nil?
+
+        @adapter.normalize(decoded)
+      end
+
+      def metadata_for(_event)
+        metadata = @transport_metadata
+        return {} if metadata.nil?
+
+        {
+          'wal_end_lsn' => metadata_value(metadata, :wal_end_lsn),
+          'server_time' => metadata_value(metadata, :server_time)
+        }.compact
+      end
+
+      def metadata_value(metadata, name)
+        metadata.public_send(name) if metadata.respond_to?(name)
+      end
+    end
+  end
+end

data/lib/cdc/solid_queue/processor_job.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module CDC
+  module SolidQueue
+    # Mixin for Rails ApplicationJob classes that consume CDC event payloads.
+    #
+    # Including classes implement #process(event). Active Job calls #perform,
+    # this mixin deserializes the payload, then delegates to #process.
+    module ProcessorJob
+      # Add a default queue name when Active Job provides queue_as.
+      #
+      # @param base [Class]
+      # @return [void]
+      def self.included(base)
+        base.queue_as(:cdc) if base.respond_to?(:queue_as)
+      end
+
+      # Active Job entrypoint.
+      #
+      # @param payload [Hash]
+      # @return [Object] process return value
+      def perform(payload)
+        process(EventSerializer.load_event(payload))
+      end
+
+      # Process a normalized CDC event payload.
+      #
+      # @param event [Hash]
+      # @raise [NotImplementedError] when the including job does not override it
+      def process(event)
+        raise NotImplementedError, "#{self.class} must implement #process"
+      end
+    end
+  end
+end

data/lib/cdc/solid_queue/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module CDC
+  module SolidQueue
+    # Rails integration for cdc-solid-queue tasks.
+    class Railtie < Rails::Railtie
+      rake_tasks do
+        load File.expand_path('tasks/cdc_solid_queue.rake', File.dirname(__FILE__))
+      end
+    end
+  end
+end

data/lib/cdc/solid_queue/runner.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CDC
+  module SolidQueue
+    # Minimal ingestion runner boundary.
+    #
+    # The runner accepts any stream object that yields PostgreSQL-derived CDC
+    # events. This keeps the class testable while production code can supply a
+    # pgoutput-client backed stream.
+    class Runner
+      # @param stream [#each]
+      # @param enqueuer [Enqueuer]
+      def initialize(stream:, enqueuer:)
+        raise ArgumentError, 'stream must respond to #each' unless stream.respond_to?(:each)
+
+        @stream = stream
+        @enqueuer = enqueuer
+      end
+
+      # Start reading events and enqueueing jobs.
+      #
+      # @return [Integer] number of enqueued events
+      def start
+        count = 0
+        @stream.each do |event|
+          result = @enqueuer.enqueue(event)
+          checkpoint(event, result)
+          count += 1
+        end
+        count
+      end
+
+      private
+
+      def checkpoint(event, result)
+        store = @enqueuer.configuration.checkpoint
+        store&.advance(event, result)
+      end
+    end
+  end
+end

data/lib/cdc/solid_queue/tasks/cdc_solid_queue.rake

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+namespace :cdc_solid_queue do
+  desc 'Start PostgreSQL CDC ingestion into Solid Queue'
+  task start: :environment do
+    configuration = CDC::SolidQueue.configuration
+    enqueuer = CDC::SolidQueue::Enqueuer.new(configuration)
+    stream = CDC::SolidQueue::PostgresqlStream.new(configuration)
+
+    CDC::SolidQueue::Runner.new(stream:, enqueuer:).start
+  end
+end

data/lib/cdc/solid_queue/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CDC
+  module SolidQueue
+    # Current cdc-solid-queue gem version.
+    VERSION = '0.1.0'
+  end
+end

data/lib/cdc/solid_queue.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'solid_queue/version'
+require_relative 'solid_queue/error'
+require_relative 'solid_queue/event_serializer'
+require_relative 'solid_queue/checkpoint'
+require_relative 'solid_queue/configuration'
+require_relative 'solid_queue/enqueuer'
+require_relative 'solid_queue/processor_job'
+require_relative 'solid_queue/postgresql_stream'
+require_relative 'solid_queue/runner'
+
+# Namespace for Change Data Capture integrations.
+module CDC
+  # Rails-native durable CDC job backend built on Solid Queue.
+  module SolidQueue
+    class << self
+      # Return the global configuration.
+      #
+      # @return [Configuration]
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Configure cdc-solid-queue.
+      #
+      # @yieldparam config [Configuration]
+      # @return [Configuration]
+      def configure
+        yield configuration
+        configuration
+      end
+
+      # Reset configuration. Intended for tests and console experiments.
+      #
+      # @return [Configuration]
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+    end
+  end
+end

data/sig/cdc/solid_queue.rbs

@@ -0,0 +1,158 @@
+module Rails
+  class Railtie
+    def self.rake_tasks: () { () -> untyped } -> untyped
+  end
+end
+
+module Pgoutput
+  class RelationTracker
+    def initialize: () -> void
+    def process: (untyped payload) -> untyped
+  end
+
+  class Decoder
+    def initialize: (?type_registry: untyped) -> void
+    def decode: (untyped message) -> untyped
+  end
+
+  module Client
+    class Runner
+      attr_reader configuration: untyped
+      def initialize: (**untyped options) -> void
+      def start: () { (String payload, untyped metadata) -> untyped } -> void
+    end
+  end
+
+  module SourceAdapter
+    class Cdc
+      def initialize: (?primary_key_resolver: untyped, ?metadata_builder: untyped) -> void
+      def normalize: (untyped event) -> untyped
+    end
+  end
+end
+
+module CDC
+  module SolidQueue
+    VERSION: String
+
+    def self.configuration: () -> Configuration
+    def self.configure: () { (Configuration) -> untyped } -> Configuration
+    def self.reset_configuration!: () -> Configuration
+
+    class Error < StandardError
+    end
+
+    class ConfigurationError < Error
+    end
+
+    class UnsupportedSourceError < ConfigurationError
+    end
+
+    class SerializationError < Error
+    end
+
+    class Configuration
+      SUPPORTED_SOURCE: Symbol
+      ORDERING_KEYS: Array[Symbol]
+
+      attr_accessor processor_job: untyped
+      attr_accessor queue: String
+      attr_accessor preserve_order: bool
+      attr_accessor ordering_key: Symbol
+      attr_accessor postgresql: Hash[Symbol, untyped]
+      attr_accessor checkpoint: untyped
+
+      def initialize: () -> void
+      def validate!: () -> true
+      def source: () -> Symbol
+
+      private
+
+      def validate_processor_job!: () -> nil
+      def validate_queue!: () -> nil
+      def validate_ordering_key!: () -> nil
+      def validate_postgresql!: () -> nil
+      def validate_checkpoint!: () -> nil
+    end
+
+    class EventSerializer
+      INTERNAL_METADATA_KEY: String
+
+      def self.dump: (untyped event) -> Hash[String, untyped]
+      def self.load: (Hash[untyped, untyped] payload) -> Hash[String, untyped]
+      def self.load_event: (Hash[untyped, untyped] payload) -> untyped
+      def self.with_enqueue_metadata: (Hash[untyped, untyped] payload, Hash[untyped, untyped] metadata) -> Hash[String, untyped]
+      def self.enqueue_metadata: (Hash[untyped, untyped] payload) -> Hash[String, untyped]
+      def self.ordering_value: (Hash[untyped, untyped] payload, Symbol key) -> untyped
+
+      private
+
+      def self.normalize_hash: (untyped value) -> untyped
+      def self.build_change_event: (Hash[String, untyped] normalized) -> untyped
+      def self.strip_internal_metadata: (Hash[String, untyped] payload) -> Hash[String, untyped]
+      def self.change_event_payload?: (Hash[String, untyped] payload) -> bool
+    end
+
+    class Checkpoint
+      attr_reader position: untyped
+      def initialize: () -> void
+      def advance: (untyped event, ?untyped result) -> untyped
+
+      private
+
+      def position_for: (untyped event) -> untyped
+      def result_position: (untyped result) -> untyped
+    end
+
+    class Enqueuer
+      attr_reader configuration: Configuration
+      def initialize: (Configuration configuration) -> void
+      def enqueue: (untyped event) -> untyped
+
+      private
+
+      def async_job: (untyped job) -> untyped
+      def enqueue_metadata: (Hash[untyped, untyped] payload) -> Hash[String, untyped]
+      def ordering_value: (Hash[untyped, untyped] payload) -> untyped
+    end
+
+    module ProcessorJob
+      def self.included: (untyped base) -> void
+      def perform: (Hash[untyped, untyped] payload) -> untyped
+      def process: (Hash[String, untyped] event) -> untyped
+    end
+
+    class Runner
+      def initialize: (stream: untyped, enqueuer: Enqueuer) -> void
+      def start: () -> Integer
+
+      private
+
+      def checkpoint: (untyped event, untyped result) -> untyped
+    end
+
+    class PostgresqlStream
+      def initialize: (
+        Configuration configuration,
+        ?client_runner: untyped,
+        ?relation_tracker: untyped,
+        ?decoder: untyped,
+        ?adapter: untyped
+      ) -> void
+      def each: () { (untyped event) -> untyped } -> void
+              | () -> Enumerator[untyped, void]
+
+      private
+
+      def build_client_runner: () -> untyped
+      def postgresql_options: () -> Hash[Symbol, untyped]
+      def build_adapter: () -> untyped
+      def normalize: (untyped payload) -> untyped
+      def metadata_for: (untyped event) -> Hash[String, untyped]
+      def metadata_value: (untyped metadata, Symbol name) -> untyped
+    end
+
+    class Railtie < ::Rails::Railtie
+    end
+  end
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: cdc-solid-queue
+version: !ruby/object:Gem::Version
+  version: 0.1.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: cdc-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.3
+- !ruby/object:Gem::Dependency
+  name: pgoutput-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.4
+- !ruby/object:Gem::Dependency
+  name: pgoutput-decoder
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+- !ruby/object:Gem::Dependency
+  name: pgoutput-parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+- !ruby/object:Gem::Dependency
+  name: pgoutput-source-adapter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+description: Bridges PostgreSQL CDC events into Solid Queue-backed Active Job processors.
+email:
+- kenneth.c.demanawa@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/cdc/solid_queue.rb
+- lib/cdc/solid_queue/checkpoint.rb
+- lib/cdc/solid_queue/configuration.rb
+- lib/cdc/solid_queue/enqueuer.rb
+- lib/cdc/solid_queue/error.rb
+- lib/cdc/solid_queue/event_serializer.rb
+- lib/cdc/solid_queue/postgresql_stream.rb
+- lib/cdc/solid_queue/processor_job.rb
+- lib/cdc/solid_queue/railtie.rb
+- lib/cdc/solid_queue/runner.rb
+- lib/cdc/solid_queue/tasks/cdc_solid_queue.rake
+- lib/cdc/solid_queue/version.rb
+- sig/cdc/solid_queue.rbs
+homepage: https://github.com/kanutocd/cdc-solid-queue
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/kanutocd/cdc-solid-queue
+  source_code_uri: https://github.com/kanutocd/cdc-solid-queue/tree/main
+  changelog_uri: https://github.com/kanutocd/cdc-solid-queue/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: Rails-native durable CDC job backend for Solid Queue.
+test_files: []