cdc-core 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a71182bac774b200c13556d0a887754a2788dc4e3581fc84a94288764900f365
-  data.tar.gz: a67bb53791b19347fb0c589b59603abfc6f085504597531d7c9932da3a3d8749
+  metadata.gz: b6b50778bfa61fb46ffb973eaa1975345cdbd6df15d4a719110dba339b63ed68
+  data.tar.gz: e461bc281b0147d2c8fdcfc1e3c95f209076070c3585858cc97c5c90585cc6ad
 SHA512:
-  metadata.gz: a96b523f2144fd94d0ecd633bf956fdcad791a994f3a2bf9e4559da9e4c713570f52c842e3cce15cb9a1491345190087c7cd1599612f5e4ecd5f933d22a6a9d6
-  data.tar.gz: 44acef005734403fea47a88e8d142cf8f9667ef032b032af24dfc25cf25c491d1c2a6caf3fab3bb06fc7790d63b8c88a8cb9984e61803dac315cd6d8118a2957
+  metadata.gz: 761888ea92dcd0c5f0a268bdb999016de811486fd69a3e2eaab457d1d4b21e1a79664214017961da69ec05adebcc2d99b98e2b433430a8d69e3f70e2967be8ca
+  data.tar.gz: 27c091d4e1f0b16a1c3503cc12af85ed9311e9650f028251fbf2334d81849359b15932d92b556e4ebd11f1ef51f7b37bfdbfe630f79087ff50c450b049f3c17e

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.1.2] - 2026-06-10
+
+- Added `CDC::Core::ProcessorChain` that feeds the successful value from one processor into the next processor
+- Updated and enriched the API and Architecture documenation
+
 ## [0.1.1] - 2026-06-09
 
 ### Added

data/README.md

@@ -15,7 +15,7 @@ Shared Change Data Capture vocabulary for Ruby.
 - Transaction grouping via `TransactionEnvelope`
 - Column-level change objects
 - Ordering vocabulary
-- Processor and composite processor contracts
+- Processor, composite processor, processor chain, and pipeline contracts
 - Event filters
 - Small pipeline orchestration object
 - Router for supported work item shapes
@@ -186,7 +186,23 @@ AnalyticsProcessor.new.ractor_safe?
 
 This declares intent only. `cdc-core` does not execute processors in Ractors. `cdc-parallel` can use this signal before moving processor work across Ractors.
 
-## Composite Processor
+## Downstream Workflow Primitives
+
+`cdc-core` defines three small workflow primitives. Runtime gems and
+application-specific integrations can execute these primitives without
+inventing their own composition vocabulary.
+
+### CompositeProcessor
+
+Use `CompositeProcessor` when many independent processors should receive the
+same input.
+
+```text
+event
+  ├─ AuditProcessor
+  ├─ AnalyticsProcessor
+  └─ WebhookProcessor
+```
 
 ```ruby
 processor = CDC::Core::CompositeProcessor.new([
@@ -197,7 +213,17 @@ processor = CDC::Core::CompositeProcessor.new([
 results = processor.process(event)
 ```
 
-## Filters and Pipeline
+### Pipeline
+
+Use `Pipeline` when one processor should run only after filters match.
+
+```text
+event
+  ↓
+filters
+  ↓
+processor
+```
 
 ```ruby
 pipeline = CDC::Core::Pipeline.new(
@@ -211,6 +237,46 @@ pipeline = CDC::Core::Pipeline.new(
 result = pipeline.process(event)
 ```
 
+### ProcessorChain
+
+Use `ProcessorChain` when each processor depends on the previous processor's
+successful value.
+
+```text
+user_ids
+  ↓
+LoadUsersProcessor
+  ↓
+users
+  ↓
+SendNotificationsProcessor
+```
+
+```ruby
+class LoadUsersProcessor < CDC::Core::Processor
+  def process(user_ids)
+    users = User.where(id: user_ids).to_a
+    CDC::Core::ProcessorResult.success(user_ids, value: users)
+  end
+end
+
+class SendNotificationsProcessor < CDC::Core::Processor
+  def process(users)
+    users.each { |user| NotificationMailer.notice(user).deliver_later }
+    CDC::Core::ProcessorResult.success(users, value: users.size)
+  end
+end
+
+chain = CDC::Core::ProcessorChain.new([
+  LoadUsersProcessor.new,
+  SendNotificationsProcessor.new
+])
+
+result = chain.process([1, 2, 3])
+result.value
+# => 3
+```
+
 ## Non-goals
 
 `cdc-core` does not:

data/lib/cdc/core/composite_processor.rb

@@ -2,11 +2,12 @@
 
 module CDC
   module Core
-    # Processor that delegates each event to multiple processors.
+    # Fan-out processor that delegates the same input to multiple processors.
     #
-    # CompositeProcessor enables fan-out processing while preserving a simple
-    # sequential execution model. It normalizes truthy/falsey processor returns
-    # into ProcessorResult objects and can stop at the first failure.
+    # CompositeProcessor is for independent downstream side effects. Every
+    # configured processor receives the same input, and their results are
+    # collected independently. Use ProcessorChain when Processor B must receive
+    # Processor A's output.
     class CompositeProcessor < Processor
       # @return [Array<Processor>] processors executed for each event
       # @return [Boolean] whether processing stops on the first failure

data/lib/cdc/core/pipeline.rb

@@ -2,11 +2,12 @@
 
 module CDC
   module Core
-    # Connects filters with a processor to form an event-processing unit.
+    # Connects filters with one processor to form a guarded processing unit.
     #
-    # A Pipeline first evaluates all filters. Matching events are handed to the
-    # processor, while filtered events produce skipped results. Processor errors
-    # are captured as failure results instead of escaping to the caller.
+    # A Pipeline evaluates all filters before invoking its processor. Matching
+    # inputs are processed, while filtered inputs produce skipped results. Use
+    # CompositeProcessor for fan-out to many processors and ProcessorChain for
+    # dependent step-by-step workflows.
     class Pipeline
       # @return [#process] processor invoked for matching events
       # @return [Array<Filter>] filters that must all match before processing

data/lib/cdc/core/processor_chain.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module CDC
+  module Core
+    # Sequential processor workflow where each successful result feeds the next processor.
+    #
+    # ProcessorChain models dependent workflows. Unlike CompositeProcessor,
+    # which sends the same input to every processor, ProcessorChain sends the
+    # value returned by one processor to the next processor. This is useful for
+    # downstream workflows such as loading records, enriching them, and then
+    # sending the enriched payload to a sink.
+    #
+    # Each processor result is normalized into a ProcessorResult. The chain stops
+    # at the first failure or skipped result because later processors depend on
+    # the previous processor's successful value.
+    class ProcessorChain < Processor
+      # @return [Array<#process>] processors executed in dependency order
+      # @return [Observer] observer notified of dispatch events
+      attr_reader :processors, :observer
+
+      # Build a processor chain.
+      #
+      # @param processors [Array<#process>] processors executed in dependency order
+      # @param observer [Observer, nil] instrumentation observer for each processor result
+      def initialize(processors, observer: NullObserver::INSTANCE) # rubocop:disable Lint/MissingSuper
+        @processors = processors.freeze
+        @observer = observer || NullObserver::INSTANCE
+      end
+
+      # Process one input through each processor in sequence.
+      #
+      # The first processor receives the original input. Each later processor
+      # receives the previous successful ProcessorResult#value. The returned
+      # value is the final ProcessorResult produced by the chain.
+      #
+      # @param input [Object] initial input for the first processor
+      # @return [ProcessorResult] final processor result or the first failed/skipped result
+      def process(input)
+        observer.dispatch_started(input)
+        current_input = input
+
+        processors.each do |processor|
+          result = process_with(processor, current_input)
+          observe_result(result)
+          return result unless result.success?
+
+          current_input = result.value
+        end
+
+        ProcessorResult.success(current_input, value: current_input)
+      end
+
+      # Process many inputs in order.
+      #
+      # @param inputs [Enumerable<Object>] inputs to process through the chain
+      # @return [Array<ProcessorResult>] final result for each input
+      def process_many(inputs)
+        inputs.map { |input| process(input) }.freeze
+      end
+
+      private
+
+      # Normalize processor return values into ProcessorResult objects.
+      #
+      # @param result [Object] raw processor result
+      # @param input [Object] input given to the processor
+      # @return [ProcessorResult] normalized result
+      def normalize_result(result, input)
+        return result if result.is_a?(ProcessorResult)
+
+        result ? ProcessorResult.success(input, value: result) : ProcessorResult.skipped(input)
+      end
+
+      def process_with(processor, input)
+        normalize_result(processor.process(input), input)
+      rescue StandardError => e
+        ProcessorResult.failure(e, event: input, processor: processor.class.name)
+      end
+
+      def observe_result(result)
+        case result.status
+        when :success
+          observer.dispatch_succeeded(result)
+        when :failure
+          observer.dispatch_failed(result)
+        when :skipped
+          observer.dispatch_skipped(result)
+        end
+      end
+    end
+  end
+end

data/lib/cdc/core/processor_result.rb

@@ -12,17 +12,19 @@ module CDC
       VALID_STATUSES = Ractor.make_shareable(%i[success failure skipped].freeze)
 
       # @return [Symbol] result status
-      # @return [ChangeEvent, nil] event associated with the result
+      # @return [ChangeEvent, Object, nil] event or input associated with the result
+      # @return [Object, nil] value produced by the processor
       # @return [Exception, nil] failure error, when status is :failure
       # @return [EventMetadata] result metadata
-      attr_reader :status, :event, :error, :metadata
+      attr_reader :status, :event, :value, :error, :metadata
 
       # Build a successful result.
       #
       # @param event [ChangeEvent, nil] processed event
       # @param metadata [Hash, EventMetadata] result metadata
+      # @param value [Object, nil] value produced by the processor; defaults to event for compatibility
       # @return [ProcessorResult]
-      def self.success(event = nil, metadata: {}) = new(:success, event:, metadata:)
+      def self.success(event = nil, metadata: {}, value: event) = new(:success, event:, metadata:, value:)
 
       # Build a failure result.
       #
@@ -60,12 +62,14 @@ module CDC
       # @param event [ChangeEvent, nil] associated event
       # @param error [Exception, nil] associated failure
       # @param metadata [Hash, EventMetadata] result metadata
-      def initialize(status, event: nil, error: nil, metadata: {})
+      # @param value [Object, nil] value produced by the processor
+      def initialize(status, event: nil, error: nil, metadata: {}, value: event)
         @status = normalize_status(status)
         @event = event
+        @value = value
         @error = error
         @metadata = metadata.is_a?(EventMetadata) ? metadata : EventMetadata.new(metadata)
-        Ractor.make_shareable(self) unless error
+        make_shareable_when_possible
       end
 
       # @return [Boolean] true when status is :success
@@ -132,7 +136,8 @@ module CDC
       def to_h
         payload = {
           'status' => status,
-          'event' => event&.to_h,
+          'event' => event.respond_to?(:to_h) ? event.to_h : event,
+          'value' => value.respond_to?(:to_h) ? value.to_h : value,
           'error_class' => error_class,
           'error_message' => error_message,
           'error_backtrace' => error_backtrace,
@@ -144,6 +149,16 @@ module CDC
 
       private
 
+      def make_shareable_when_possible
+        Ractor.make_shareable(self) unless error
+      rescue Ractor::Error, TypeError
+        # ProcessorResult may carry application-specific values such as ActiveRecord
+        # result sets. Those values are valid in sequential/fiber runtimes even when
+        # they cannot be shared with Ractors. Ractor runtimes remain responsible for
+        # validating shareability at their boundary.
+        self
+      end
+
       def normalize_status(status)
         value = status.to_sym
         return value if VALID_STATUSES.include?(value)

data/lib/cdc/core/version.rb

@@ -3,6 +3,6 @@
 module CDC
   module Core
     # Current gem version.
-    VERSION = '0.1.1'
+    VERSION = '0.1.2'
   end
 end

data/lib/cdc/core.rb

@@ -15,6 +15,7 @@ require_relative 'core/source_adapter'
 require_relative 'core/processor_result'
 require_relative 'core/processor'
 require_relative 'core/composite_processor'
+require_relative 'core/processor_chain'
 require_relative 'core/observer'
 require_relative 'core/null_observer'
 require_relative 'core/filter'

data/sig/cdc/core/processor_chain.rbs

@@ -0,0 +1,45 @@
+module CDC
+  module Core
+    # Sequential processor workflow where each successful result feeds the next processor.
+    class ProcessorChain < Processor
+      @processors: untyped
+      @observer: untyped
+
+      # @return [Array<#process>] processors executed in dependency order
+      attr_reader processors: untyped
+
+      # @return [Observer] observer notified of dispatch events
+      attr_reader observer: untyped
+
+      # Build a processor chain.
+      #
+      # @param processors [Array<#process>] processors executed in dependency order
+      # @param observer [Observer, nil] instrumentation observer for each processor result
+      def initialize: (untyped processors, ?observer: untyped?) -> void
+
+      # Process one input through each processor in sequence.
+      #
+      # @param input [Object] initial input for the first processor
+      # @return [ProcessorResult] final processor result or the first failed/skipped result
+      def process: (untyped input) -> untyped
+
+      # Process many inputs in order.
+      #
+      # @param inputs [Enumerable<Object>] inputs to process through the chain
+      # @return [Array<ProcessorResult>] final result for each input
+      def process_many: (untyped inputs) -> untyped
+
+      private
+
+      # Normalize processor return values into ProcessorResult objects.
+      #
+      # @param result [Object] raw processor result
+      # @param input [Object] input given to the processor
+      # @return [ProcessorResult] normalized result
+      def normalize_result: (untyped result, untyped input) -> untyped
+
+      def process_with: (untyped processor, untyped input) -> untyped
+      def observe_result: (untyped result) -> untyped
+    end
+  end
+end

data/sig/cdc/core/processor_result.rbs

@@ -11,6 +11,8 @@ module CDC
 
       @event: untyped
 
+      @value: untyped
+
       @error: untyped
 
       @metadata: untyped
@@ -27,6 +29,9 @@ module CDC
       # @return [EventMetadata] result metadata
       attr_reader event: untyped
 
+      # @return [Object, nil] value produced by the processor
+      attr_reader value: untyped
+
       # @return [Symbol] result status
       # @return [ChangeEvent, nil] event associated with the result
       # @return [Exception, nil] failure error, when status is :failure
@@ -44,7 +49,7 @@ module CDC
       # @param event [ChangeEvent, nil] processed event
       # @param metadata [Hash, EventMetadata] result metadata
       # @return [ProcessorResult]
-      def self.success: (?untyped? event, ?metadata: ::Hash[untyped, untyped]) -> untyped
+      def self.success: (?untyped? event, ?metadata: ::Hash[untyped, untyped], ?value: untyped?) -> untyped
 
       # Build a failure result.
       #
@@ -71,7 +76,7 @@ module CDC
       # @param event [ChangeEvent, nil] associated event
       # @param error [Exception, nil] associated failure
       # @param metadata [Hash, EventMetadata] result metadata
-      def initialize: (untyped status, ?event: untyped?, ?error: untyped?, ?metadata: ::Hash[untyped, untyped]) -> void
+      def initialize: (untyped status, ?event: untyped?, ?error: untyped?, ?metadata: ::Hash[untyped, untyped], ?value: untyped?) -> void
 
       # @return [Boolean] true when status is :success
       def success?: () -> untyped
@@ -124,6 +129,8 @@ module CDC
 
       private
 
+      def make_shareable_when_possible: () -> untyped
+
       def normalize_status: (untyped status) -> untyped
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cdc-core
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -9,10 +9,9 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: 'CDC Core provides immutable, Ractor-safe Change Data Capture domain
-  objects, processor contracts, filters, and pipeline primitives.
-
-  '
+description: |
+  CDC Core provides immutable, Ractor-safe Change Data Capture contracts and domain primitives,
+  including source adapters, change events, processors, routing, ordering policies, and pipelines.
 email:
 - kenneth.c.demanawa@gmail.com
 executables: []
@@ -38,6 +37,7 @@ files:
 - lib/cdc/core/ordering_scope.rb
 - lib/cdc/core/pipeline.rb
 - lib/cdc/core/processor.rb
+- lib/cdc/core/processor_chain.rb
 - lib/cdc/core/processor_result.rb
 - lib/cdc/core/router.rb
 - lib/cdc/core/source_adapter.rb
@@ -60,6 +60,7 @@ files:
 - sig/cdc/core/ordering_scope.rbs
 - sig/cdc/core/pipeline.rbs
 - sig/cdc/core/processor.rbs
+- sig/cdc/core/processor_chain.rbs
 - sig/cdc/core/processor_result.rbs
 - sig/cdc/core/router.rbs
 - sig/cdc/core/source_adapter.rbs
@@ -91,5 +92,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Database-agnostic Change Data Capture domain primitives for Ruby.
+summary: Source-agnostic Change Data Capture contracts and domain primitives for Ruby..
 test_files: []