cdc-solid-queue 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c617d6e5257bc18cc38e242fe0ad0ac8b885de15fe6d6bdfbf5df5965924495
-  data.tar.gz: 2f8a7b90d7edd8f39010d74821730fc6ad833774bb54136c0dc51068f87ff9f0
+  metadata.gz: f2a93bea7c30ca2f1c54bb53b00057967b662b16c8ca3a40bb5afb6c73ccb736
+  data.tar.gz: 1d413c1aeae90544b9430864d7cb753e1b510115a571d4640bf5c6a7c09caf20
 SHA512:
-  metadata.gz: f6c4cff53700e038fdfe3316c71972d61da38ca04937625143cc2790583e8cb64c7ee38d9f84da79f7425c04fdeef941c6dd65d41a78d0230cce7ba8c6ec55bb
-  data.tar.gz: '068730758e551e38b2f2abc65d9b79c21406dc243f00d022e3aea8885e96ddbb01cceb02c9b765c0ca5859e63f5ffe422435b1ee0bb3517840ac54873ae5a0ee'
+  metadata.gz: 50b5a0edeec10b23ef6eeb124bb39e77d31a0148aa25128264936678c4dbd7b995f1d3e1cae3341bd1458c5ec687d1a579f291c0d714ebdb3c9de2ff5b790c08
+  data.tar.gz: c73e0438419bc58f93f0fe641df7fbefc266f39c60d322ceea0bad96e1524afa0197ce89d12e857bab2898f55513d29f98f3f0228fc526037046e0ac739e1a61

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Unreleased
+
+## 0.1.2
+
+- Minimal Rails app example.
+- Local smoke tests.
+- Enqueue overhead benchmark.
+
 ## 0.1.1
 
 - Initial implementation skeleton.

data/README.md

@@ -72,6 +72,47 @@ The task wires `Pgoutput::Client::Runner`, `Pgoutput::RelationTracker`,
 `Pgoutput::Decoder`, and `Pgoutput::SourceAdapter::Cdc` into the
 `CDC::SolidQueue::Runner`.
 
+See `examples/rails_app` for a minimal Rails-side setup with a Solid Queue job,
+initializer, Railtie require, and a local PostgreSQL container configured for
+logical replication.
+
+## Smoke Tests
+
+Run local smoke tests without PostgreSQL or Rails:
+
+```bash
+bundle exec rake smoke:local
+```
+
+The smoke tests verify enqueue metadata, event rehydration, and
+checkpoint-after-enqueue behavior.
+
+## Benchmark
+
+Run the enqueue overhead benchmark:
+
+```bash
+bundle exec rake benchmark:enqueue
+```
+
+Set `CDC_SOLID_QUEUE_BENCH_EVENTS` to control the event count.
+
+Example local result on Ruby 3.4.9:
+
+```text
+events=1000000 elapsed=15.7210s rate=63609.14 events/s
+```
+
+This is an upper-bound microbenchmark for the Ruby-side enqueue translation
+layer. It measures event serialization, queue and ordering metadata calculation,
+and dispatch to a fake benchmark job. It does not measure real Solid Queue
+database inserts, Rails job execution, PostgreSQL replication, pgoutput
+decoding, network I/O, or checkpoint persistence.
+
+In that run, `cdc-solid-queue` translated and dispatched about 63.6k synthetic
+events per second, so real throughput will usually be dominated by Solid Queue
+persistence, database latency, job execution cost, and CDC source throughput.
+
 ## MVP Checkpoint Rule
 
 A checkpoint advances after the Solid Queue job is durably inserted. Job execution success is handled by Solid Queue retry semantics.

data/lib/cdc/solid_queue/cli.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CDC
+  module SolidQueue
+    # Command helpers used by Rails tasks and executable entrypoints.
+    module CLI
+      class << self
+        # Start PostgreSQL CDC ingestion using the global configuration.
+        #
+        # @return [Integer] number of enqueued events when the stream exits
+        def start
+          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
+    end
+  end
+end

data/lib/cdc/solid_queue/railtie.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
-require 'rails/railtie'
+require_relative '../solid_queue'
+begin
+  require 'rails/railtie'
+rescue LoadError
+  Rails::Railtie
+end
 
 module CDC
   module SolidQueue

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

@@ -3,10 +3,6 @@
 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
+    CDC::SolidQueue::CLI.start
   end
 end

data/lib/cdc/solid_queue/version.rb

@@ -3,6 +3,6 @@
 module CDC
   module SolidQueue
     # Current cdc-solid-queue gem version.
-    VERSION = '0.1.1'
+    VERSION = '0.1.2'
   end
 end

data/lib/cdc/solid_queue.rb

@@ -9,6 +9,7 @@ require_relative 'solid_queue/enqueuer'
 require_relative 'solid_queue/processor_job'
 require_relative 'solid_queue/postgresql_stream'
 require_relative 'solid_queue/runner'
+require_relative 'solid_queue/cli'
 
 # Namespace for Change Data Capture integrations.
 module CDC

data/sig/cdc/solid_queue.rbs

@@ -152,6 +152,10 @@ module CDC
       def metadata_value: (untyped metadata, Symbol name) -> untyped
     end
 
+    module CLI
+      def self.start: () -> Integer
+    end
+
     class Railtie < ::Rails::Railtie
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cdc-solid-queue
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -91,6 +91,7 @@ files:
 - README.md
 - lib/cdc/solid_queue.rb
 - lib/cdc/solid_queue/checkpoint.rb
+- lib/cdc/solid_queue/cli.rb
 - lib/cdc/solid_queue/configuration.rb
 - lib/cdc/solid_queue/enqueuer.rb
 - lib/cdc/solid_queue/error.rb