cdc-sidekiq 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a814eddfc8362aa6e2ad54cf09a8034398327d23626aca65887a5fcee4d8b8cf
+  data.tar.gz: 175152c36354bf40d5831e0812c8d59eae68e5865c265e8c18e0a07ceb14d42e
+SHA512:
+  metadata.gz: ee9285ba79a7c605dd9d43bc251e3352bdb811ec919df7377b1379660dc638b8f35519a11581830ce1a295fe15147fe17ad2f3bae9ce1d6221d134bc0fc93088
+  data.tar.gz: b3739c02f483d35c4c447417743855ef462d5c07c2c0254e9aec50bb88846257ffa58c5ec3b46be50c24c866d02bfb6c0350d92029e2eaeee07455b627bf0b05

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+## [Unreleased]
+
+- Improved unit test coverage for runtime selection, configuration copying, class-level job declarations, failure policies, and batch payload behavior.
+- Expanded benchmark documentation with the 500,000-item Ruby 4.0.5 snapshot, interpretation, and runtime tuning guidance.
+- Documented runtime-selection guidance and the shared-state correctness boundary between cdc-sidekiq and consumer processors/sinks.
+- Updated gem metadata documentation URI and description.
+
+
+## [0.1.0] - 2026-06-08
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+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,321 @@
+# cdc-sidekiq
+
+`cdc-sidekiq` integrates Sidekiq with CDC execution primitives.
+
+Sidekiq remains the durable job system. It owns scheduling, retries, queues, Redis persistence, and operational behavior.
+
+`cdc-sidekiq` owns what happens inside selected jobs: processor contracts, runtime selection, fan-out/fan-in execution, and normalized processor results.
+
+```text
+Sidekiq Job
+      |
+      v
+CDC::Sidekiq::ProcessorJob
+      |
+      +--> cdc-parallel
+      |       Ractor fan-out / fan-in
+      |
+      +--> cdc-concurrent
+              Async task fan-out / fan-in
+```
+
+## Why cdc-sidekiq Exists
+
+Sidekiq is excellent at durable background job execution.
+
+It provides:
+
+- scheduling
+- retries
+- queues
+- Redis-backed persistence
+- operational familiarity
+
+However, Sidekiq intentionally leaves the internal execution strategy of a job to the application.
+
+`cdc-sidekiq` extends Sidekiq with CDC execution primitives:
+
+- processor contracts
+- parallel execution with `cdc-parallel`
+- concurrent execution with `cdc-concurrent`
+- fan-out / fan-in processing
+- ordered result collection
+- normalized processor results
+
+The goal is not to replace Sidekiq.
+
+The goal is to make execution topology an explicit choice inside Sidekiq jobs.
+
+```text
+Sidekiq schedules the work.
+CDC primitives execute the work.
+```
+
+---
+
+## Roadmap
+
+### Community Edition
+
+The open-source edition focuses on execution primitives.
+
+Current and planned OSS capabilities:
+
+- `:direct` runtime
+- `:concurrent` runtime
+- `:parallel` runtime
+- ProcessorJob abstraction
+- `process`
+- `process_many`
+- ordered result collection
+- normalized ProcessorResult handling
+
+### Commercial Orchestration Boundary
+
+The open-source edition focuses on Sidekiq integration and explicit execution primitives.
+
+Advanced orchestration belongs above this gem. Commercial orchestration features such as hybrid runtimes, nested worker topologies, worker-local resource pools, adaptive sizing, capacity guards, telemetry, and advanced failure policies live in the commercial orchestrator layer.
+
+```text
+cdc-sidekiq
+    Sidekiq integration
+    ProcessorJob abstraction
+    :direct / :concurrent / :parallel runtime selection
+
+cdc-orchestrator-pro
+    Hybrid runtime
+    Nested runtime / worker-local resource pools
+    orchestration, backpressure, telemetry, tuning
+```
+
+This keeps the OSS gem small and useful while leaving operational orchestration to the commercial layer.
+
+## Runtime Selection Guide
+
+Choose the smallest runtime that matches the work.
+
+| Runtime | Best fit | Avoid when |
+| --- | --- | --- |
+| `:direct` | Tiny, cheap, already-batched work | You need internal fan-out |
+| `:parallel` | CPU-heavy, Ractor-shareable processing | Payloads/processors are not shareable or work is too tiny |
+| `:concurrent` | I/O-heavy processing with scheduler-friendly waits | Work is CPU-bound or effectively no-op |
+
+A useful rule of thumb:
+
+```text
+Sidekiq controls how many jobs run.
+cdc-sidekiq controls how one selected job executes its internal payload.
+```
+
+Do not increase both Sidekiq concurrency and CDC runtime concurrency blindly. That can multiply downstream pressure on Redis, PostgreSQL, HTTP APIs, and other shared resources.
+
+## Correctness Boundary
+
+`cdc-sidekiq` controls execution topology. It does not make shared downstream state automatically safe.
+
+When multiple jobs or multiple internal work items update the same database rows, files, search documents, Redis keys, or external API resources, the processor or sink must provide the correctness policy. Common strategies include:
+
+- database transactions;
+- row-level locks such as `SELECT ... FOR UPDATE`;
+- optimistic locking;
+- idempotency keys;
+- conflict-safe writes;
+- single-writer sink patterns.
+
+The runtime can provide controlled execution. Application-specific correctness remains the responsibility of the processor and sink implementation.
+
+## Benchmarks
+
+See [benchmark/README.md](./benchmark/README.md) for the `bin/cdc-sidekiq-load` benchmark, recent 500,000-item snapshots, interpretation, and runtime tuning guidance.
+
+## Requirements
+
+Ruby 3.4 or newer.
+
+Runtime support depends on the selected CDC execution substrate:
+
+| Runtime | Ruby | Required gems |
+| --- | --- | --- |
+| `:direct` | 3.4+ | `cdc-core` |
+| `:concurrent` | 3.4+ | `cdc-core`, `cdc-concurrent` |
+| `:parallel` | 4.0+ | `cdc-core`, `cdc-parallel` |
+
+`cdc-parallel` remains optional because it requires Ruby 4+. Ruby 3.4 users can still use `:direct` and `:concurrent`.
+
+## Installation
+
+```ruby
+gem "cdc-sidekiq"
+```
+
+Runtime gems are installed by the application according to the execution model it uses:
+
+```ruby
+gem "cdc-parallel"   # for Ractor-backed execution
+gem "cdc-concurrent" # for Async-backed execution
+```
+
+## Configuration
+
+```ruby
+Sidekiq.configure_server do |_config|
+  CDC::Sidekiq.configure do |cdc|
+    cdc.default_runtime = :concurrent
+    cdc.parallel_size = Etc.nprocessors - 1
+    cdc.concurrency = 100
+    cdc.timeout = nil
+    cdc.preserve_order = true
+  end
+end
+```
+
+Sidekiq concurrency and CDC runtime concurrency are intentionally separate.
+
+```text
+Sidekiq concurrency
+  = how many Sidekiq jobs run at once
+
+CDC parallel size
+  = how many Ractors one CDC-enabled job may use internally
+
+CDC concurrency
+  = how many Async tasks one CDC-enabled job may use internally
+```
+
+## Usage
+
+### Parallel processor job
+
+```ruby
+class UserIndexer < CDC::Core::Processor
+  ractor_safe!
+
+  def process(user_id)
+    # CPU-heavy or shareable work
+    CDC::Core::ProcessorResult.success(user_id)
+  end
+end
+
+class ReindexUsersJob
+  include Sidekiq::Job
+  include CDC::Sidekiq::ProcessorJob
+
+  cdc_processor UserIndexer
+  cdc_runtime :parallel
+  cdc_parallel_size Etc.nprocessors - 1
+end
+
+ReindexUsersJob.perform_async([1, 2, 3, 4])
+```
+
+Array payloads are processed with `process_many` by default.
+
+```text
+Sidekiq job payload
+      |
+      v
+process_many
+      |
+      v
+cdc-parallel ProcessorPool
+      |
+      v
+ordered ProcessorResult array
+```
+
+### Concurrent processor job
+
+```ruby
+class WebhookDeliverer < CDC::Core::Processor
+  def concurrent_safe? = true
+
+  def process(webhook_payload)
+    # I/O-heavy scheduler-friendly work
+    CDC::Core::ProcessorResult.success(webhook_payload)
+  end
+end
+
+class DeliverWebhooksJob
+  include Sidekiq::Job
+  include CDC::Sidekiq::ProcessorJob
+
+  cdc_processor WebhookDeliverer
+  cdc_runtime :concurrent
+  cdc_concurrency 250
+  cdc_timeout 5.0
+end
+```
+
+### Per-job runtime override
+
+Global configuration provides defaults. Each job can override the runtime.
+
+```ruby
+class ProjectionJob
+  include Sidekiq::Job
+  include CDC::Sidekiq::ProcessorJob
+
+  cdc_processor ProjectionProcessor
+  cdc_runtime :parallel
+end
+```
+
+## Failure behavior
+
+By default, failed `ProcessorResult` objects raise `CDC::Sidekiq::ProcessorFailureError` so Sidekiq can apply its normal retry behavior.
+
+```ruby
+class BestEffortJob
+  include Sidekiq::Job
+  include CDC::Sidekiq::ProcessorJob
+
+  cdc_processor BestEffortProcessor
+  cdc_runtime :concurrent
+  cdc_raise_on_failure false
+end
+```
+
+
+## Benchmarking
+
+`cdc-sidekiq` includes `bin/cdc-sidekiq-load`, a benchmark aligned with Sidekiq's `bin/sidekiq-load` style.
+
+Sidekiq's benchmark creates many no-op jobs and drains them as fast as possible. `cdc-sidekiq-load` keeps the no-op workload shape but measures the downstream CDC runtime path inside one CDC-aware Sidekiq job.
+
+```bash
+COUNT=500000 RUNTIME=concurrent CDC_CONCURRENCY=100 \
+  bundle exec bin/cdc-sidekiq-load
+```
+
+```bash
+COUNT=500000 RUNTIME=parallel CDC_PARALLEL_SIZE=7 \
+  bundle exec bin/cdc-sidekiq-load
+```
+
+See [`benchmark/README.md`](benchmark/README.md) for interpretation notes and all benchmark knobs.
+
+## Current scope
+
+This gem currently implements the downstream/runtime integration only:
+
+```text
+Sidekiq Job
+    ↓
+CDC execution primitives
+
+Future:
+
+PostgreSQL WAL
+    ↓
+pgoutput*
+    ↓
+Sidekiq Job
+    ↓
+CDC execution primitives
+```
+
+A future upstream/source integration may map PostgreSQL logical replication events into Sidekiq work through the `pgoutput*` family and `pgoutput-source-adapter`, but that is intentionally out of scope for the initial release.
+
+## License
+
+[MIT](./LICENSE.txt).

data/benchmark/README.md

@@ -0,0 +1,143 @@
+# Benchmarks
+
+## `bin/cdc-sidekiq-load`
+
+`bin/cdc-sidekiq-load` is intentionally aligned with Sidekiq's own `bin/sidekiq-load` benchmark style.
+
+Sidekiq's load benchmark creates a large number of no-op jobs and drains them as fast as possible. `cdc-sidekiq-load` keeps the no-op workload shape but measures the downstream `cdc-sidekiq` execution model:
+
+```text
+Sidekiq-style job payload
+      |
+      v
+CDC::Sidekiq::Runtime
+      |
+      +--> :direct
+      +--> :concurrent
+      +--> :parallel
+      |
+      v
+process_many(items)
+```
+
+This benchmark does **not** replace Sidekiq's Redis-backed load benchmark. It measures the inner execution primitive that a CDC-aware Sidekiq job can use after Sidekiq has already started the job.
+
+## Examples
+
+```bash
+COUNT=500000 RUNTIME=direct \
+  bundle exec bin/cdc-sidekiq-load
+```
+
+```bash
+COUNT=500000 RUNTIME=concurrent CDC_CONCURRENCY=100 \
+  bundle exec bin/cdc-sidekiq-load
+```
+
+```bash
+COUNT=500000 RUNTIME=parallel CDC_PARALLEL_SIZE=7 \
+  bundle exec bin/cdc-sidekiq-load
+```
+
+## Knobs
+
+| Environment variable | Purpose | Default |
+| --- | --- | --- |
+| `COUNT` | Total number of no-op work items | `500000` |
+| `BATCH_SIZE` | Number of items per `process_many` call | `COUNT` |
+| `RUNTIME` | `direct`, `concurrent`, or `parallel` | `concurrent` |
+| `CDC_CONCURRENCY` | Async task limit for `cdc-concurrent` | `100` |
+| `CDC_PARALLEL_SIZE` | Ractor worker count for `cdc-parallel` | `Etc.nprocessors - 1` |
+| `CDC_TIMEOUT` | Per-item timeout in seconds | unset |
+| `PRESERVE_ORDER` | Preserve result order for concurrent runtime | `true` |
+| `WARMUP` | Warmup items before timing | `min(COUNT / 50, 10000)` |
+| `JSON` | Print machine-readable JSON when set to `1` | unset |
+
+## Snapshot: 500,000 No-op Items
+
+Environment:
+
+```text
+ruby=ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +PRISM [x86_64-linux]
+count=500,000
+batch_size=500,000
+preserve_order=true
+warmup=10,000
+```
+
+Results:
+
+| Runtime | Knobs | Elapsed | Throughput | GC count |
+| --- | --- | ---: | ---: | ---: |
+| `direct` | default direct execution | `0.085821 sec` | `5,826,083 items/sec` | `0` |
+| `parallel` | `CDC_PARALLEL_SIZE=7` | `6.613177 sec` | `75,607 items/sec` | `58` |
+| `parallel` | `CDC_PARALLEL_SIZE=7` | `5.830767 sec` | `85,752 items/sec` | `44` |
+| `concurrent` | `CDC_CONCURRENCY=100` | `12.667181 sec` | `39,472 items/sec` | `45` |
+
+## Interpretation
+
+This snapshot is intentionally a no-op workload. It is useful for measuring runtime overhead, not real downstream work.
+
+The `:direct` runtime wins by a huge margin because it performs no fan-out, no Ractor messaging, no Async task scheduling, and no pool coordination. For tiny no-op processors, `:direct` should be expected to dominate.
+
+The `:parallel` runtime is slower than `:direct` for this workload because every item pays Ractor dispatch and result-collection cost. It is still faster than `:concurrent` in this snapshot, which suggests the Async task orchestration overhead is not worthwhile for a tiny CPU-free processor.
+
+The `:concurrent` runtime is intended for I/O-heavy processors. A no-op benchmark is a poor workload for proving its value because there is no socket wait, remote API latency, database latency, or scheduler-friendly blocking work to hide.
+
+## Tuning Recommendations
+
+Use `:direct` when:
+
+- each item is very cheap;
+- the processor does little or no I/O;
+- the payload is already batched efficiently;
+- predictable low overhead is more important than fan-out.
+
+Use `:parallel` when:
+
+- the processor is CPU-heavy;
+- the processor and payloads are Ractor-shareable;
+- batches are large enough to amortize Ractor dispatch overhead;
+- the machine has spare CPU cores.
+
+Start with:
+
+```bash
+CDC_PARALLEL_SIZE=$((nproc - 1))
+```
+
+then test lower values. More Ractors are not automatically better. Watch throughput, GC count, memory use, and downstream resource pressure.
+
+Use `:concurrent` when:
+
+- the processor is I/O-heavy;
+- work spends meaningful time waiting on HTTP, Redis, PostgreSQL, MySQL, object storage, or other external systems;
+- downstream services can tolerate the requested concurrency;
+- preserving result order is either required or intentionally disabled.
+
+Start with:
+
+```bash
+CDC_CONCURRENCY=25
+```
+
+then increase gradually. A concurrency value of `100` can be reasonable for I/O-bound workloads, but it is pure overhead for no-op work.
+
+## Benchmark Rule of Thumb
+
+```text
+Tiny/no-op work  -> :direct
+CPU-heavy work   -> :parallel
+I/O-heavy work   -> :concurrent
+Mixed topology   -> commercial orchestrator layer
+```
+
+The benchmark is useful for comparing:
+
+```text
+one Sidekiq job with many internal work items
+  vs.
+many Sidekiq jobs with one work item each
+```
+
+That distinction is the core `cdc-sidekiq` value proposition.

data/lib/cdc/sidekiq/configuration.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "etc"
+
+module CDC
+  module Sidekiq
+    # Runtime defaults shared by CDC-aware Sidekiq jobs.
+    #
+    # The configuration intentionally describes only the CDC execution layer.
+    # Sidekiq still owns queue selection, scheduling, retries, durability, and
+    # job concurrency. cdc-sidekiq owns runtime selection for work performed
+    # inside a Sidekiq job.
+    class Configuration
+      # @return [Symbol] default runtime used when a job does not declare one.
+      attr_accessor :default_runtime
+
+      # @return [Integer] default number of Ractor workers for cdc-parallel jobs.
+      attr_accessor :parallel_size
+
+      # @return [Integer] default number of Async tasks for cdc-concurrent jobs.
+      attr_accessor :concurrency
+
+      # @return [Float, nil] default per-item timeout passed to CDC processor pools.
+      attr_accessor :timeout
+
+      # @return [Boolean] default result-ordering policy for cdc-concurrent jobs.
+      attr_accessor :preserve_order
+
+      # @return [Boolean] default failure policy for processor jobs.
+      attr_accessor :raise_on_failure
+
+      # @return [Boolean] whether array payloads should be processed with #process_many by default.
+      attr_accessor :batch_payloads
+
+      # @return [void]
+      def initialize
+        @default_runtime = :concurrent
+        @parallel_size = [Etc.nprocessors - 1, 1].max
+        @concurrency = 100
+        @timeout = nil
+        @preserve_order = true
+        @raise_on_failure = true
+        @batch_payloads = true
+      end
+
+      # Build an immutable copy so job-level overrides cannot mutate globals.
+      #
+      # @return [Configuration] independent copy of this configuration.
+      def dup
+        copy = self.class.new
+        copy.default_runtime = default_runtime
+        copy.parallel_size = parallel_size
+        copy.concurrency = concurrency
+        copy.timeout = timeout
+        copy.preserve_order = preserve_order
+        copy.raise_on_failure = raise_on_failure
+        copy.batch_payloads = batch_payloads
+        copy
+      end
+    end
+  end
+end

data/lib/cdc/sidekiq/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CDC
+  module Sidekiq
+    # Base error for all cdc-sidekiq failures.
+    class Error < StandardError; end
+
+    # Raised when a job declares an unsupported CDC runtime.
+    class UnsupportedRuntimeError < Error; end
+
+    # Raised when a Sidekiq processor job does not declare a processor.
+    class MissingProcessorError < Error; end
+
+    # Raised when processor execution returns one or more failed results.
+    class ProcessorFailureError < Error
+      # @return [Array<Object>] failed processor results that triggered the error.
+      attr_reader :failures
+
+      # @param failures [Array<Object>] failed processor results that should be exposed to Sidekiq retry handling.
+      # @return [void]
+      def initialize(failures)
+        @failures = failures.freeze
+        super("CDC processor failed for #{failures.length} item(s)")
+      end
+    end
+  end
+end

data/lib/cdc/sidekiq/processor_job.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module CDC
+  module Sidekiq
+    # Sidekiq job mixin that executes work through CDC runtime primitives.
+    #
+    # The job remains a normal Sidekiq job. Sidekiq still owns scheduling,
+    # retries, queues, and persistence. cdc-sidekiq only changes how the job
+    # executes its payload once Sidekiq has started the job.
+    #
+    # @example Process many items through cdc-parallel
+    #   class ReindexUsersJob
+    #     include Sidekiq::Job
+    #     include CDC::Sidekiq::ProcessorJob
+    #
+    #     cdc_processor UserIndexer
+    #     cdc_runtime :parallel
+    #   end
+    #
+    # @example Process I/O-heavy items through cdc-concurrent
+    #   class DeliverWebhooksJob
+    #     include Sidekiq::Job
+    #     include CDC::Sidekiq::ProcessorJob
+    #
+    #     cdc_processor WebhookDeliverer
+    #     cdc_runtime :concurrent
+    #     cdc_concurrency 250
+    #   end
+    module ProcessorJob
+      # Add CDC processor-job class methods to the including job class.
+      #
+      # @param base [Class] Sidekiq job class including this module.
+      # @return [void]
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Execute a Sidekiq payload through the configured CDC runtime.
+      #
+      # Array payloads are processed with #process_many when cdc_batch_payloads
+      # is enabled. Other payloads are processed with #process.
+      #
+      # @param payload [Object, Array<Object>] Sidekiq job payload or batch payload.
+      # @return [Object, Array<Object>] CDC processor result or frozen result array.
+      # @raise [MissingProcessorError] when the job does not declare a CDC processor.
+      # @raise [ProcessorFailureError] when raise-on-failure is enabled and one or more results failed.
+      def perform(payload)
+        results = process_payload(payload)
+        handle_processor_failures(results)
+        results
+      end
+
+      private
+
+      def process_payload(payload)
+        runtime = self.class.__cdc_sidekiq_runtime
+        if payload.is_a?(Array) && self.class.__cdc_sidekiq_batch_payloads
+          runtime.process_many(payload)
+        else
+          runtime.process(payload)
+        end
+      end
+
+      def handle_processor_failures(results)
+        return unless self.class.__cdc_sidekiq_raise_on_failure
+
+        failures = Array(results).select { |result| result.respond_to?(:failure?) && result.failure? }
+        raise ProcessorFailureError, failures unless failures.empty?
+      end
+
+      # Class-level declaration helpers for CDC-aware Sidekiq jobs.
+      module ClassMethods
+        # Declare or read the processor used by this job.
+        #
+        # @param value [Class, Object, nil] processor class or processor instance.
+        # @return [Class, Object, nil] configured processor when called without an argument.
+        def cdc_processor(value = nil)
+          return @cdc_processor if value.nil?
+
+          @cdc_processor = value
+        end
+
+        # Declare or read the CDC runtime used by this job.
+        #
+        # @param value [Symbol, String, nil] runtime name, such as :parallel, :concurrent, or :direct.
+        # @return [Symbol, nil] configured runtime when called without an argument.
+        def cdc_runtime(value = nil)
+          return @cdc_runtime if value.nil?
+
+          @cdc_runtime = value.to_sym
+        end
+
+        # Declare or read the cdc-parallel worker count for this job.
+        #
+        # @param value [Integer, nil] number of Ractor workers for this job.
+        # @return [Integer, nil] configured worker count when called without an argument.
+        def cdc_parallel_size(value = nil)
+          return @cdc_parallel_size if value.nil?
+
+          @cdc_parallel_size = Integer(value)
+        end
+
+        # Declare or read the cdc-concurrent task concurrency for this job.
+        #
+        # @param value [Integer, nil] maximum Async task count for this job.
+        # @return [Integer, nil] configured concurrency when called without an argument.
+        def cdc_concurrency(value = nil)
+          return @cdc_concurrency if value.nil?
+
+          @cdc_concurrency = Integer(value)
+        end
+
+        # Declare or read the runtime timeout for this job.
+        #
+        # @param value [Float, Integer, nil] timeout in seconds, or nil for no timeout.
+        # @return [Float, nil] configured timeout when called without an argument.
+        def cdc_timeout(value = :__cdc_sidekiq_read__)
+          return @cdc_timeout if value == :__cdc_sidekiq_read__
+
+          @cdc_timeout = value.nil? ? nil : Float(value)
+        end
+
+        # Declare or read result ordering for cdc-concurrent.
+        #
+        # @param value [Boolean, nil] true to preserve input order, false to keep completion order.
+        # @return [Boolean, nil] configured ordering policy when called without an argument.
+        def cdc_preserve_order(value = nil)
+          return @cdc_preserve_order if value.nil?
+
+          @cdc_preserve_order = value == true
+        end
+
+        # Declare or read whether array payloads use #process_many.
+        #
+        # @param value [Boolean, nil] true to batch array payloads, false to process the array as one item.
+        # @return [Boolean, nil] configured batching policy when called without an argument.
+        def cdc_batch_payloads(value = nil)
+          return @cdc_batch_payloads if value.nil?
+
+          @cdc_batch_payloads = value == true
+        end
+
+        # Declare or read whether failed ProcessorResult objects raise.
+        #
+        # @param value [Boolean, nil] true to raise on failed results so Sidekiq retries the job.
+        # @return [Boolean, nil] configured failure policy when called without an argument.
+        def cdc_raise_on_failure(value = nil)
+          return @cdc_raise_on_failure if value.nil?
+
+          @cdc_raise_on_failure = value == true
+        end
+
+        # Build the runtime used by one Sidekiq job invocation.
+        #
+        # @return [Runtime] runtime configured for this job class.
+        # @raise [MissingProcessorError] when no processor has been declared.
+        def __cdc_sidekiq_runtime
+          Runtime.new(
+            processor: __cdc_sidekiq_processor,
+            runtime: __cdc_sidekiq_runtime_name,
+            parallel_size: __cdc_sidekiq_parallel_size,
+            concurrency: __cdc_sidekiq_concurrency,
+            timeout: __cdc_sidekiq_timeout,
+            preserve_order: __cdc_sidekiq_preserve_order
+          )
+        end
+
+        # @return [Boolean] true when array payloads should use #process_many.
+        def __cdc_sidekiq_batch_payloads
+          configured_boolean(@cdc_batch_payloads, CDC::Sidekiq.configuration.batch_payloads)
+        end
+
+        # @return [Boolean] true when failed results should raise.
+        def __cdc_sidekiq_raise_on_failure
+          configured_boolean(@cdc_raise_on_failure, CDC::Sidekiq.configuration.raise_on_failure)
+        end
+
+        private
+
+        def __cdc_sidekiq_processor
+          processor = @cdc_processor
+          raise MissingProcessorError, "#{name} must declare cdc_processor" unless processor
+
+          processor.is_a?(Class) ? processor.new : processor
+        end
+
+        def __cdc_sidekiq_runtime_name
+          @cdc_runtime || CDC::Sidekiq.configuration.default_runtime
+        end
+
+        def __cdc_sidekiq_parallel_size
+          @cdc_parallel_size || CDC::Sidekiq.configuration.parallel_size
+        end
+
+        def __cdc_sidekiq_concurrency
+          @cdc_concurrency || CDC::Sidekiq.configuration.concurrency
+        end
+
+        def __cdc_sidekiq_timeout
+          defined?(@cdc_timeout) ? @cdc_timeout : CDC::Sidekiq.configuration.timeout
+        end
+
+        def __cdc_sidekiq_preserve_order
+          configured_boolean(@cdc_preserve_order, CDC::Sidekiq.configuration.preserve_order)
+        end
+
+        def configured_boolean(value, fallback)
+          value.nil? ? fallback : value
+        end
+      end
+    end
+  end
+end

data/lib/cdc/sidekiq/runtime.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module CDC
+  module Sidekiq
+    # Executes a CDC processor through one of the CDC runtime primitives.
+    #
+    # Runtime is intentionally selected outside Sidekiq's own concurrency
+    # setting. Sidekiq concurrency controls how many jobs run at once. This
+    # object controls how one CDC-aware job fans work out internally.
+    class Runtime
+      # @param processor [Object] CDC processor object that responds to #process.
+      # @param runtime [Symbol] execution runtime, currently :parallel, :concurrent, or :direct.
+      # @param parallel_size [Integer] number of Ractors used by cdc-parallel.
+      # @param concurrency [Integer] number of Async tasks used by cdc-concurrent.
+      # @param timeout [Float, nil] optional timeout passed to the selected runtime.
+      # @param preserve_order [Boolean] whether cdc-concurrent should preserve input order.
+      # @return [void]
+      def initialize(processor:, runtime:, parallel_size:, concurrency:, timeout:, preserve_order:)
+        @processor = processor
+        @runtime = runtime.to_sym
+        @parallel_size = parallel_size
+        @concurrency = concurrency
+        @timeout = timeout
+        @preserve_order = preserve_order
+      end
+
+      # Process one work item through the selected runtime.
+      #
+      # @param item [Object] work item passed to the processor.
+      # @return [Object] processor result returned by the selected runtime.
+      def process(item)
+        with_pool { |pool| pool.process(item) }
+      end
+
+      # Process many work items through the selected runtime.
+      #
+      # @param items [Array<Object>] work items passed to the processor.
+      # @return [Array<Object>] processor results returned by the selected runtime.
+      def process_many(items)
+        with_pool { |pool| pool.process_many(items) }
+      end
+
+      private
+
+      attr_reader :processor, :runtime, :parallel_size, :concurrency, :timeout, :preserve_order
+
+      def with_pool
+        pool = build_pool
+        yield pool
+      ensure
+        pool.shutdown if pool.respond_to?(:shutdown)
+      end
+
+      def build_pool
+        case runtime
+        when :parallel
+          require "cdc/parallel"
+          CDC::Parallel::ProcessorPool.new(processor:, size: parallel_size, timeout:)
+        when :concurrent
+          require "cdc/concurrent"
+          CDC::Concurrent::ProcessorPool.new(processor:, concurrency:, timeout:, preserve_order:)
+        when :direct
+          DirectPool.new(processor)
+        else
+          raise UnsupportedRuntimeError, "unsupported CDC Sidekiq runtime: #{runtime.inspect}"
+        end
+      end
+
+      # Minimal runtime used for tests and simple sequential execution.
+      class DirectPool
+        # @param processor [Object] CDC processor object that responds to #process.
+        # @return [void]
+        def initialize(processor)
+          @processor = processor
+        end
+
+        # @param item [Object] work item passed to the processor.
+        # @return [Object] processor result returned by the processor.
+        def process(item)
+          @processor.process(item)
+        end
+
+        # @param items [Array<Object>] work items passed to the processor.
+        # @return [Array<Object>] processor results returned by the processor.
+        def process_many(items)
+          items.map { |item| process(item) }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/cdc/sidekiq/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module CDC
+  module Sidekiq
+    # Current cdc-sidekiq gem version.
+    VERSION = "0.1.0"
+  end
+end

data/lib/cdc/sidekiq.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "sidekiq/version"
+require_relative "sidekiq/errors"
+require_relative "sidekiq/configuration"
+require_relative "sidekiq/runtime"
+require_relative "sidekiq/processor_job"
+
+module CDC
+  # Integration layer between Sidekiq and CDC execution primitives.
+  module Sidekiq
+    class << self
+      # Read the process-wide cdc-sidekiq configuration.
+      #
+      # @return [Configuration] mutable global configuration object.
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Configure process-wide defaults for CDC-aware Sidekiq jobs.
+      #
+      # @yieldparam configuration [Configuration] mutable configuration object.
+      # @return [Configuration] configured global configuration object.
+      def configure
+        yield configuration if block_given?
+        configuration
+      end
+
+      # Reset process-wide configuration to defaults.
+      #
+      # @return [Configuration] new default configuration object.
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+    end
+  end
+end

data/lib/cdc_sidekiq.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "cdc/sidekiq"

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: cdc-sidekiq
+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'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: sidekiq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: |
+  Adds CDC-aware processor jobs and runtime selection to Sidekiq,
+  allowing selected jobs to execute payloads directly, through cdc-parallel, or through cdc-concurrent.
+email:
+- kenneth.c.demanawa@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- benchmark/README.md
+- lib/cdc/sidekiq.rb
+- lib/cdc/sidekiq/configuration.rb
+- lib/cdc/sidekiq/errors.rb
+- lib/cdc/sidekiq/processor_job.rb
+- lib/cdc/sidekiq/runtime.rb
+- lib/cdc/sidekiq/version.rb
+- lib/cdc_sidekiq.rb
+homepage: https://github.com/kanutocd/cdc-sidekiq
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kanutocd/cdc-sidekiq
+  source_code_uri: https://github.com/kanutocd/cdc-sidekiq
+  changelog_uri: https://github.com/kanutocd/cdc-sidekiq/blob/main/CHANGELOG.md
+  documentation_uri: https://kanutocd.github.io/cdc-sidekiq/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Sidekiq integration for CDC execution runtimes.
+test_files: []