cdc-core 0.1.0 → 0.1.1

data/lib/cdc/core/ordering_scope.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CDC
+  module Core
+    # Canonical ordering scopes used by the CDC ecosystem.
+    #
+    # Ordering scopes describe how related events should be grouped when a
+    # runtime or sink needs to preserve relative order.
+    module OrderingScope
+      # Preserve exact stream order.
+      GLOBAL = :global
+      # Preserve transaction order and boundaries.
+      TRANSACTION = :transaction
+      # Preserve ordering per relation/table.
+      RELATION = :relation
+      # Preserve ordering per primary key.
+      PRIMARY_KEY = :primary_key
+      # Do not impose a strict ordering guarantee.
+      NONE = :none
+
+      # All supported ordering scopes.
+      SUPPORTED = Ractor.make_shareable([GLOBAL, TRANSACTION, RELATION, PRIMARY_KEY, NONE].freeze)
+
+      module_function
+
+      # Convert a scope-like value into a supported ordering scope symbol.
+      #
+      # @param scope [#to_sym] scope to normalize
+      # @return [Symbol] one of SUPPORTED
+      # @raise [InvalidOrderingScopeError] when the scope is not supported
+      def normalize(scope)
+        value = scope.to_sym
+        return value if SUPPORTED.include?(value)
+
+        raise InvalidOrderingScopeError, "unsupported CDC ordering scope: #{scope.inspect}"
+      rescue NoMethodError
+        raise InvalidOrderingScopeError, "unsupported CDC ordering scope: #{scope.inspect}"
+      end
+
+      # Check whether a scope-like value is supported.
+      #
+      # @param scope [#to_sym] scope to check
+      # @return [Boolean] true when the value normalizes to a supported scope
+      def supported?(scope)
+        SUPPORTED.include?(scope.to_sym)
+      rescue NoMethodError
+        false
+      end
+    end
+  end
+end

data/lib/cdc/core/pipeline.rb

@@ -10,15 +10,18 @@ module CDC
     class Pipeline
       # @return [#process] processor invoked for matching events
       # @return [Array<Filter>] filters that must all match before processing
-      attr_reader :processor, :filters
+      # @return [Observer] observer notified of dispatch events
+      attr_reader :processor, :filters, :observer
 
       # Build a pipeline.
       #
       # @param processor [#process] processor for matching events
       # @param filters [Array<Filter>] filters applied before processing
-      def initialize(processor:, filters: [])
+      # @param observer [Observer, nil] instrumentation observer
+      def initialize(processor:, filters: [], observer: NullObserver::INSTANCE)
         @processor = processor
         @filters = filters.freeze
+        @observer = observer || NullObserver::INSTANCE
       end
 
       # Process one event through the pipeline.
@@ -26,11 +29,16 @@ module CDC
       # @param event [ChangeEvent] event to process
       # @return [ProcessorResult]
       def process(event)
+        observer.dispatch_started(event)
         return ProcessorResult.skipped(event, metadata: { reason: 'filtered' }) unless matches?(event)
 
-        normalize_result(processor.process(event), event)
+        result = normalize_result(processor.process(event), event)
+        observe_result(result)
+        result
       rescue StandardError => e
-        ProcessorResult.failure(e, event:)
+        result = ProcessorResult.failure(e, event:, processor: processor.class.name)
+        observer.dispatch_failed(result)
+        result
       end
 
       # Process many events in order.
@@ -61,6 +69,17 @@ module CDC
 
         result ? ProcessorResult.success(event) : ProcessorResult.skipped(event)
       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.rb

@@ -29,6 +29,45 @@ module CDC
         self.class.ractor_safe?
       end
 
+      # Start the processor.
+      #
+      # Runtime layers can call this before dispatch begins. The default
+      # implementation is a no-op.
+      #
+      # @return [self]
+      def start
+        self
+      end
+
+      # Stop the processor.
+      #
+      # Runtime layers can call this during shutdown. The default implementation
+      # is a no-op.
+      #
+      # @return [self]
+      def stop
+        self
+      end
+
+      # Flush any buffered work.
+      #
+      # Runtime layers can call this before shutdown or checkpoints. The
+      # default implementation is a no-op.
+      #
+      # @return [self]
+      def flush
+        self
+      end
+
+      # Whether the processor is healthy and ready to accept work.
+      #
+      # The default implementation assumes the processor is healthy.
+      #
+      # @return [Boolean]
+      def healthy?
+        true
+      end
+
       # Process one event.
       #
       # Subclasses must override this method.

data/lib/cdc/core/processor_result.rb

@@ -8,6 +8,9 @@ module CDC
     # successful processing, skipped events, and failures without relying on
     # processor-specific return values.
     class ProcessorResult
+      # Allowed result statuses.
+      VALID_STATUSES = Ractor.make_shareable(%i[success failure skipped].freeze)
+
       # @return [Symbol] result status
       # @return [ChangeEvent, nil] event associated with the result
       # @return [Exception, nil] failure error, when status is :failure
@@ -25,9 +28,24 @@ module CDC
       #
       # @param error [Exception] processor error
       # @param event [ChangeEvent, nil] event being processed
+      # @param reason [String, nil] human-readable failure reason
+      # @param retryable [Boolean, nil] whether the failure can be retried
+      # @param processor [String, nil] processor name associated with the failure
+      # @param failed_at [String, nil] timestamp for when the failure occurred
       # @param metadata [Hash, EventMetadata] result metadata
       # @return [ProcessorResult]
-      def self.failure(error, event: nil, metadata: {}) = new(:failure, event:, error:, metadata:)
+      def self.failure(error, event: nil, reason: nil, retryable: nil, processor: nil, failed_at: nil,
+                       metadata: nil)
+        base_metadata = metadata.nil? ? EventMetadata.new.to_h : metadata.to_h
+        failure_metadata = base_metadata.merge(
+          reason: reason || error.message,
+          retryable: retryable,
+          processor: processor || error.class.name,
+          failed_at: failed_at || Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%6NZ')
+        ).compact
+
+        new(:failure, event:, error:, metadata: failure_metadata)
+      end
 
       # Build a skipped result.
       #
@@ -43,7 +61,7 @@ module CDC
       # @param error [Exception, nil] associated failure
       # @param metadata [Hash, EventMetadata] result metadata
       def initialize(status, event: nil, error: nil, metadata: {})
-        @status = status.to_sym
+        @status = normalize_status(status)
         @event = event
         @error = error
         @metadata = metadata.is_a?(EventMetadata) ? metadata : EventMetadata.new(metadata)
@@ -58,6 +76,82 @@ module CDC
 
       # @return [Boolean] true when status is :skipped
       def skipped? = status == :skipped
+
+      # Human-readable failure reason, when present.
+      #
+      # @return [String, nil]
+      def failure_reason
+        metadata[:reason]
+      end
+
+      # Whether the failure is retryable.
+      #
+      # @return [Boolean]
+      def retryable?
+        metadata[:retryable] == true
+      end
+
+      # Name of the processor associated with the failure, when present.
+      #
+      # @return [String, nil]
+      def processor_name
+        metadata[:processor]
+      end
+
+      # Timestamp for when the failure occurred, when present.
+      #
+      # @return [String, nil]
+      def failed_at
+        metadata[:failed_at]
+      end
+
+      # Error class name, when present.
+      #
+      # @return [String, nil]
+      def error_class
+        error&.class&.name
+      end
+
+      # Error message, when present.
+      #
+      # @return [String, nil]
+      def error_message
+        error&.message
+      end
+
+      # Error backtrace, when present.
+      #
+      # @return [Array<String>]
+      def error_backtrace
+        Array(error&.backtrace)
+      end
+
+      # Convert the result into a shareable hash.
+      #
+      # @return [Hash{String=>Object,nil}]
+      def to_h
+        payload = {
+          'status' => status,
+          'event' => event&.to_h,
+          'error_class' => error_class,
+          'error_message' => error_message,
+          'error_backtrace' => error_backtrace,
+          'metadata' => metadata.to_h
+        }
+
+        Ractor.make_shareable(payload.freeze)
+      end
+
+      private
+
+      def normalize_status(status)
+        value = status.to_sym
+        return value if VALID_STATUSES.include?(value)
+
+        raise ArgumentError, "unsupported processor result status: #{status.inspect}"
+      rescue NoMethodError
+        raise ArgumentError, "unsupported processor result status: #{status.inspect}"
+      end
     end
   end
 end

data/lib/cdc/core/router.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module CDC
+  module Core
+    # Routes CDC work items to the appropriate handler.
+    #
+    # Router keeps the dispatch vocabulary in core while leaving execution
+    # strategy to the caller. It can route single change events, transaction
+    # envelopes, and arrays of events.
+    class Router
+      # @return [#process] handler for individual change events
+      # @return [#process, nil] handler for transaction envelopes
+      # @return [Observer] observer notified of dispatch events
+      attr_reader :processor, :transaction_processor, :observer
+
+      # Build a router.
+      #
+      # @param processor [#process] handler for change events
+      # @param transaction_processor [#process, nil] handler for transaction envelopes
+      # @param observer [Observer, nil] instrumentation observer
+      def initialize(processor:, transaction_processor: nil, observer: NullObserver::INSTANCE)
+        @processor = processor
+        @transaction_processor = transaction_processor
+        @observer = observer || NullObserver::INSTANCE
+      end
+
+      # Process a CDC work item.
+      #
+      # @param item [ChangeEvent, TransactionEnvelope, Array<ChangeEvent>]
+      # @return [Object]
+      # @raise [UnsupportedWorkItemError] when the item cannot be routed
+      def process(item)
+        observer.dispatch_started(item)
+        case item
+        when ChangeEvent
+          result = processor.process(item)
+          observe_result(result)
+          result
+        when TransactionEnvelope
+          route_transaction(item)
+        when Array
+          route_many(item)
+        else
+          raise UnsupportedWorkItemError, "unsupported CDC work item: #{item.class}"
+        end
+      end
+
+      private
+
+      # Route a transaction envelope to the configured transaction processor.
+      #
+      # @param transaction [TransactionEnvelope]
+      # @return [Object]
+      def route_transaction(transaction)
+        return transaction_processor.process(transaction) if transaction_processor
+
+        raise UnsupportedWorkItemError,
+              "unsupported CDC work item: #{transaction.class} (transaction processor not configured)"
+      end
+
+      # Route many change events through the configured processor.
+      #
+      # @param items [Array]
+      # @return [Object]
+      def route_many(items)
+        unless items.all?(ChangeEvent)
+          raise UnsupportedWorkItemError, "unsupported CDC work item: Array(#{items.first.class})"
+        end
+
+        return processor.process_many(items) if processor.respond_to?(:process_many)
+
+        items.map { |event| processor.process(event) }.freeze
+      end
+
+      def observe_result(result)
+        return result unless result.is_a?(ProcessorResult)
+
+        case result.status
+        when :success
+          observer.dispatch_succeeded(result)
+        when :failure
+          observer.dispatch_failed(result)
+        when :skipped
+          observer.dispatch_skipped(result)
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/cdc/core/source_adapter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module CDC
+  module Core
+    # Abstract base class for source adapters that normalize upstream payloads
+    # into CDC core domain objects.
+    #
+    # SourceAdapter is intentionally narrow. It does not own transport,
+    # polling, connection management, worker scheduling, or protocol parsing.
+    # It only defines the contract for turning source-specific inputs into
+    # {ChangeEvent}, {TransactionEnvelope}, or arrays of those objects.
+    #
+    # The concrete PostgreSQL implementation currently lives in the pgoutput*
+    # family. This class only defines the shared boundary other adapters can
+    # implement later.
+    class SourceAdapter
+      # Normalize one source payload into CDC core objects.
+      #
+      # Subclasses must override this method.
+      #
+      # @param _input [Object] source-specific payload
+      # @return [ChangeEvent, TransactionEnvelope, Array<ChangeEvent>, Array<TransactionEnvelope>]
+      # @raise [NotImplementedError] when not implemented by a subclass
+      def normalize(_input)
+        raise NotImplementedError, "#{self.class} must implement #normalize"
+      end
+
+      # Normalize many source payloads into CDC core objects.
+      #
+      # The default implementation maps each input through {#normalize} and
+      # flattens one level so adapters can return a single object or a batch of
+      # objects for each payload.
+      #
+      # @param inputs [Enumerable] source-specific payloads
+      # @return [Array]
+      def normalize_many(inputs)
+        Array(inputs).flat_map { |input| normalize(input) }.freeze
+      end
+    end
+  end
+end

data/lib/cdc/core/version.rb

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

data/lib/cdc/core.rb

@@ -5,12 +5,20 @@ require_relative 'core/errors'
 require_relative 'core/operation'
 require_relative 'core/column_change'
 require_relative 'core/event_metadata'
+require_relative 'core/ordering_scope'
+require_relative 'core/event_position'
+require_relative 'core/ordering_key'
+require_relative 'core/ordering_policy'
 require_relative 'core/change_event'
 require_relative 'core/transaction_envelope'
+require_relative 'core/source_adapter'
 require_relative 'core/processor_result'
 require_relative 'core/processor'
 require_relative 'core/composite_processor'
+require_relative 'core/observer'
+require_relative 'core/null_observer'
 require_relative 'core/filter'
+require_relative 'core/router'
 require_relative 'core/pipeline'
 
 # Top-level namespace for Change Data Capture libraries.
@@ -18,9 +26,10 @@ module CDC
   # Database-agnostic Change Data Capture domain primitives.
   #
   # CDC::Core intentionally contains only lightweight runtime abstractions:
-  # events, metadata, processors, filters, pipelines, and processor results.
-  # Transport, PostgreSQL protocol parsing, and value decoding live in sibling
-  # gems so this layer can remain independently useful.
+  # events, metadata, source adapters, processors, filters, pipelines, and
+  # processor results. Transport, PostgreSQL protocol parsing, and value
+  # decoding live in sibling gems so this layer can remain independently
+  # useful.
   module Core
   end
 end

data/sig/cdc/core/composite_processor.rbs

@@ -10,6 +10,8 @@ module CDC
 
       @fail_fast: untyped
 
+      @observer: untyped
+
       # @return [Array<Processor>] processors executed for each event
       # @return [Boolean] whether processing stops on the first failure
       attr_reader processors: untyped
@@ -18,11 +20,15 @@ module CDC
       # @return [Boolean] whether processing stops on the first failure
       attr_reader fail_fast: untyped
 
+      # @return [Observer] observer notified of dispatch events
+      attr_reader observer: untyped
+
       # Build a composite processor.
       #
       # @param processors [Array<#process>] processors to execute
       # @param fail_fast [Boolean] whether to stop after the first failure
-      def initialize: (untyped processors, ?fail_fast: bool) -> void
+      # @param observer [Observer, nil] instrumentation observer
+      def initialize: (untyped processors, ?fail_fast: bool, ?observer: untyped?) -> void
 
       # Process an event through each configured processor.
       #
@@ -48,6 +54,11 @@ module CDC
       # @param event [ChangeEvent] processed event
       # @return [ProcessorResult]
       def normalize_result: (untyped result, untyped event) -> untyped
+
+      def collect_results: (untyped event) -> untyped
+      def process_with: (untyped processor, untyped event) -> untyped
+      def observe_results: (untyped results) -> untyped
+      def freeze_results: (untyped results) -> untyped
     end
   end
 end

data/sig/cdc/core/errors.rbs

@@ -8,6 +8,18 @@ module CDC
     class InvalidOperationError < Error
     end
 
+    # Raised when an ordering scope cannot be normalized to a supported value.
+    class InvalidOrderingScopeError < Error
+    end
+
+    # Raised when an ordering position cannot be normalized to a supported value.
+    class InvalidOrderingPositionError < Error
+    end
+
+    # Raised when a router receives an unsupported CDC work item.
+    class UnsupportedWorkItemError < Error
+    end
+
     # Raised by processors when a processor-specific failure needs wrapping.
     class ProcessorError < Error
     end

data/sig/cdc/core/event_position.rbs

@@ -0,0 +1,21 @@
+module CDC
+  module Core
+    # Immutable representation of an event's position metadata.
+    class EventPosition
+      @strategy: untyped
+      @value: untyped
+      @transaction_id: untyped
+      @sequence_number: untyped
+      @occurred_at: untyped
+
+      attr_reader strategy: untyped
+      attr_reader value: untyped
+      attr_reader transaction_id: untyped
+      attr_reader sequence_number: untyped
+      attr_reader occurred_at: untyped
+
+      def initialize: (strategy: untyped, value: untyped, ?transaction_id: untyped?, ?sequence_number: untyped?, ?occurred_at: untyped?) -> void
+      def to_h: () -> untyped
+    end
+  end
+end

data/sig/cdc/core/null_observer.rbs

@@ -0,0 +1,8 @@
+module CDC
+  module Core
+    # No-op observer for callers that do not need instrumentation.
+    class NullObserver < Observer
+      INSTANCE: untyped
+    end
+  end
+end

data/sig/cdc/core/observer.rbs

@@ -0,0 +1,25 @@
+module CDC
+  module Core
+    # Observer interface for CDC runtime instrumentation.
+    class Observer
+      METRIC_NAMES: untyped
+
+      def self.metric_tags: (untyped payload) -> untyped
+      def self.started_metric_name: () -> String
+      def self.succeeded_metric_name: () -> String
+      def self.failed_metric_name: () -> String
+      def self.skipped_metric_name: () -> String
+      private
+
+      def self.change_event_metric_tags: (untyped event) -> untyped
+      def self.transaction_envelope_metric_tags: (untyped transaction) -> untyped
+      def self.processor_result_metric_tags: (untyped result) -> untyped
+      def self.batch_metric_tags: (untyped batch) -> untyped
+
+      def dispatch_started: (untyped _event) -> void
+      def dispatch_succeeded: (untyped _result) -> void
+      def dispatch_failed: (untyped _result) -> void
+      def dispatch_skipped: (untyped _result) -> void
+    end
+  end
+end

data/sig/cdc/core/ordering_key.rbs

@@ -0,0 +1,16 @@
+module CDC
+  module Core
+    # Immutable grouping key for ordering-related dispatch.
+    class OrderingKey
+      @scope: untyped
+      @components: untyped
+
+      attr_reader scope: untyped
+      attr_reader components: untyped
+
+      def initialize: (scope: untyped, ?components: ::Hash[untyped, untyped]) -> void
+      def empty?: () -> bool
+      def to_h: () -> untyped
+    end
+  end
+end

data/sig/cdc/core/ordering_policy.rbs

@@ -0,0 +1,27 @@
+module CDC
+  module Core
+    # Immutable description of how ordered CDC work should be grouped.
+    class OrderingPolicy
+      @scope: untyped
+      @position: untyped
+      @transaction_aware: untyped
+
+      SUPPORTED_POSITIONS: untyped
+
+      attr_reader scope: untyped
+      attr_reader position: untyped
+      attr_reader transaction_aware: untyped
+
+      def initialize: (scope: untyped, ?position: untyped?, ?transaction_aware: bool) -> void
+      def transaction_aware?: () -> bool
+      def key_for: (untyped event) -> untyped
+      def position_for: (untyped event) -> untyped
+      def to_h: () -> untyped
+
+      private
+
+      def normalize_position: (untyped position) -> untyped
+      def key_components: (untyped event) -> untyped
+    end
+  end
+end

data/sig/cdc/core/ordering_scope.rbs

@@ -0,0 +1,19 @@
+module CDC
+  module Core
+    # Canonical ordering scopes used by the CDC ecosystem.
+    module OrderingScope
+      GLOBAL: :global
+      TRANSACTION: :transaction
+      RELATION: :relation
+      PRIMARY_KEY: :primary_key
+      NONE: :none
+      SUPPORTED: untyped
+
+      def normalize: (untyped scope) -> untyped
+      def supported?: (untyped scope) -> bool
+
+      def self.normalize: (untyped scope) -> untyped
+      def self.supported?: (untyped scope) -> bool
+    end
+  end
+end

data/sig/cdc/core/pipeline.rbs

@@ -10,6 +10,8 @@ module CDC
 
       @filters: untyped
 
+      @observer: untyped
+
       # @return [#process] processor invoked for matching events
       # @return [Array<Filter>] filters that must all match before processing
       attr_reader processor: untyped
@@ -18,11 +20,15 @@ module CDC
       # @return [Array<Filter>] filters that must all match before processing
       attr_reader filters: untyped
 
+      # @return [Observer] observer notified of dispatch events
+      attr_reader observer: untyped
+
       # Build a pipeline.
       #
       # @param processor [#process] processor for matching events
       # @param filters [Array<Filter>] filters applied before processing
-      def initialize: (processor: untyped, ?filters: untyped) -> void
+      # @param observer [Observer, nil] instrumentation observer
+      def initialize: (processor: untyped, ?filters: untyped, ?observer: untyped?) -> void
 
       # Process one event through the pipeline.
       #
@@ -50,6 +56,9 @@ module CDC
       # @param event [ChangeEvent] processed event
       # @return [ProcessorResult]
       def normalize_result: (untyped result, untyped event) -> untyped
+
+      def dispatch: (untyped event) -> untyped
+      def observe_result: (untyped result) -> untyped
     end
   end
 end