cdc-core 0.0.0 → 0.1.0

data/lib/cdc/core/operation.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module CDC
+  module Core
+    # Canonical CDC operation names.
+    #
+    # Operations are represented as symbols to keep event objects small,
+    # immutable, and easy to compare. Use .normalize when accepting user input
+    # and .supported? when validating optional values.
+    module Operation
+      # Insert row operation.
+      INSERT = :insert
+      # Update row operation.
+      UPDATE = :update
+      # Delete row operation.
+      DELETE = :delete
+      # Truncate table operation.
+      TRUNCATE = :truncate
+      # Logical replication message operation.
+      MESSAGE = :message
+      # All operation names currently recognized by cdc-core.
+      SUPPORTED = Ractor.make_shareable([INSERT, UPDATE, DELETE, TRUNCATE, MESSAGE].freeze)
+      # Minimal row-change operations used by the initial runtime surface.
+      MVP = Ractor.make_shareable([INSERT, UPDATE, DELETE].freeze)
+
+      module_function
+
+      # Convert an operation-like value into a supported operation symbol.
+      #
+      # @param operation [#to_sym] value to normalize
+      # @return [Symbol] one of SUPPORTED
+      # @raise [InvalidOperationError] when the operation is not supported
+      def normalize(operation)
+        value = operation.to_sym
+        return value if SUPPORTED.include?(value)
+
+        raise InvalidOperationError, "unsupported CDC operation: #{operation.inspect}"
+      end
+
+      # Check whether an operation-like value is supported.
+      #
+      # @param operation [#to_sym] value to check
+      # @return [Boolean] true when the value normalizes to a supported operation
+      def supported?(operation)
+        SUPPORTED.include?(operation.to_sym)
+      rescue NoMethodError
+        false
+      end
+    end
+  end
+end

data/lib/cdc/core/pipeline.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module CDC
+  module Core
+    # Connects filters with a processor to form an event-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.
+    class Pipeline
+      # @return [#process] processor invoked for matching events
+      # @return [Array<Filter>] filters that must all match before processing
+      attr_reader :processor, :filters
+
+      # Build a pipeline.
+      #
+      # @param processor [#process] processor for matching events
+      # @param filters [Array<Filter>] filters applied before processing
+      def initialize(processor:, filters: [])
+        @processor = processor
+        @filters = filters.freeze
+      end
+
+      # Process one event through the pipeline.
+      #
+      # @param event [ChangeEvent] event to process
+      # @return [ProcessorResult]
+      def process(event)
+        return ProcessorResult.skipped(event, metadata: { reason: 'filtered' }) unless matches?(event)
+
+        normalize_result(processor.process(event), event)
+      rescue StandardError => e
+        ProcessorResult.failure(e, event:)
+      end
+
+      # Process many events in order.
+      #
+      # @param events [Enumerable<ChangeEvent>] events to process
+      # @return [Array<ProcessorResult>]
+      def process_many(events)
+        events.map { |event| process(event) }.freeze
+      end
+
+      private
+
+      # Check whether every filter matches an event.
+      #
+      # @param event [ChangeEvent]
+      # @return [Boolean]
+      def matches?(event)
+        filters.all? { |filter| filter.match?(event) }
+      end
+
+      # Normalize raw processor output into a ProcessorResult.
+      #
+      # @param result [Object] raw processor result
+      # @param event [ChangeEvent] processed event
+      # @return [ProcessorResult]
+      def normalize_result(result, event)
+        return result if result.is_a?(ProcessorResult)
+
+        result ? ProcessorResult.success(event) : ProcessorResult.skipped(event)
+      end
+    end
+  end
+end

data/lib/cdc/core/processor.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CDC
+  module Core
+    # Base class for CDC event processors.
+    #
+    # Subclasses implement #process and may opt into Ractor-safe execution by
+    # calling .ractor_safe!. cdc-core itself does not schedule Ractors; it only
+    # records processor capabilities for runtime layers such as cdc-ractor.
+    class Processor
+      # Mark this processor class as safe to execute in Ractor-aware runtimes.
+      #
+      # @return [true]
+      def self.ractor_safe!
+        @ractor_safe = true
+      end
+
+      # Whether this processor class has declared Ractor safety.
+      #
+      # @return [Boolean]
+      def self.ractor_safe?
+        @ractor_safe == true
+      end
+
+      # Whether this processor instance is Ractor-safe.
+      #
+      # @return [Boolean]
+      def ractor_safe?
+        self.class.ractor_safe?
+      end
+
+      # Process one event.
+      #
+      # Subclasses must override this method.
+      #
+      # @param _event [ChangeEvent] event to process
+      # @raise [NotImplementedError] when not implemented by a subclass
+      def process(_event)
+        raise NotImplementedError, "#{self.class} must implement #process"
+      end
+    end
+  end
+end

data/lib/cdc/core/processor_result.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module CDC
+  module Core
+    # Result returned by processors and pipelines.
+    #
+    # ProcessorResult standardizes processor outcomes so callers can distinguish
+    # successful processing, skipped events, and failures without relying on
+    # processor-specific return values.
+    class ProcessorResult
+      # @return [Symbol] result status
+      # @return [ChangeEvent, nil] event associated with the result
+      # @return [Exception, nil] failure error, when status is :failure
+      # @return [EventMetadata] result metadata
+      attr_reader :status, :event, :error, :metadata
+
+      # Build a successful result.
+      #
+      # @param event [ChangeEvent, nil] processed event
+      # @param metadata [Hash, EventMetadata] result metadata
+      # @return [ProcessorResult]
+      def self.success(event = nil, metadata: {}) = new(:success, event:, metadata:)
+
+      # Build a failure result.
+      #
+      # @param error [Exception] processor error
+      # @param event [ChangeEvent, nil] event being processed
+      # @param metadata [Hash, EventMetadata] result metadata
+      # @return [ProcessorResult]
+      def self.failure(error, event: nil, metadata: {}) = new(:failure, event:, error:, metadata:)
+
+      # Build a skipped result.
+      #
+      # @param event [ChangeEvent, nil] skipped event
+      # @param metadata [Hash, EventMetadata] result metadata
+      # @return [ProcessorResult]
+      def self.skipped(event = nil, metadata: {}) = new(:skipped, event:, metadata:)
+
+      # Build a processor result with an explicit status.
+      #
+      # @param status [#to_sym] result status
+      # @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: {})
+        @status = status.to_sym
+        @event = event
+        @error = error
+        @metadata = metadata.is_a?(EventMetadata) ? metadata : EventMetadata.new(metadata)
+        Ractor.make_shareable(self) unless error
+      end
+
+      # @return [Boolean] true when status is :success
+      def success? = status == :success
+
+      # @return [Boolean] true when status is :failure
+      def failure? = status == :failure
+
+      # @return [Boolean] true when status is :skipped
+      def skipped? = status == :skipped
+    end
+  end
+end

data/lib/cdc/core/transaction_envelope.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CDC
+  module Core
+    # Immutable group of change events committed in one transaction.
+    #
+    # TransactionEnvelope is useful when a downstream processor needs transaction
+    # boundaries instead of isolated row-level events. The contained events and
+    # metadata are Ractor-shareable when construction succeeds.
+    class TransactionEnvelope
+      # @return [Object] transaction identifier
+      # @return [Array<ChangeEvent>] events committed by the transaction
+      # @return [String, nil] commit log sequence number
+      # @return [Time, nil] commit timestamp
+      # @return [EventMetadata] transaction metadata
+      attr_reader :transaction_id, :events, :commit_lsn, :committed_at, :metadata
+
+      # Build a transaction envelope.
+      #
+      # @param transaction_id [Object] upstream transaction identifier
+      # @param events [Array<ChangeEvent>] committed events
+      # @param commit_lsn [#to_s, nil] commit log sequence number
+      # @param committed_at [Time, nil] commit timestamp
+      # @param metadata [Hash, EventMetadata] transaction metadata
+      def initialize(transaction_id:, events:, commit_lsn: nil, committed_at: nil, metadata: {})
+        @transaction_id = transaction_id
+        @events = Ractor.make_shareable(events.freeze)
+        @commit_lsn = commit_lsn&.to_s&.freeze
+        @committed_at = committed_at
+        @metadata = metadata.is_a?(EventMetadata) ? metadata : EventMetadata.new(metadata)
+        Ractor.make_shareable(self)
+      end
+
+      # Whether the envelope has no events.
+      #
+      # @return [Boolean]
+      def empty? = events.empty?
+
+      # Number of events in the envelope.
+      #
+      # @return [Integer]
+      def size = events.size
+
+      # Convert the transaction envelope into a Ractor-shareable hash.
+      #
+      # @return [Hash{String=>Object,nil}]
+      def to_h
+        Ractor.make_shareable({
+          'transaction_id' => transaction_id,
+          'events' => events.map(&:to_h).freeze,
+          'commit_lsn' => commit_lsn,
+          'committed_at' => committed_at,
+          'metadata' => metadata.to_h
+        }.freeze)
+      end
+    end
+  end
+end

data/lib/cdc/core/version.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-module Cdc
+module CDC
   module Core
-    VERSION = "0.0.0"
+    # Current gem version.
+    VERSION = '0.1.0'
   end
 end

data/lib/cdc/core.rb

@@ -1,10 +1,26 @@
 # frozen_string_literal: true
 
-require_relative "core/version"
+require_relative 'core/version'
+require_relative 'core/errors'
+require_relative 'core/operation'
+require_relative 'core/column_change'
+require_relative 'core/event_metadata'
+require_relative 'core/change_event'
+require_relative 'core/transaction_envelope'
+require_relative 'core/processor_result'
+require_relative 'core/processor'
+require_relative 'core/composite_processor'
+require_relative 'core/filter'
+require_relative 'core/pipeline'
 
-module Cdc
+# Top-level namespace for Change Data Capture libraries.
+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.
   module Core
-    class Error < StandardError; end
-    # Your code goes here...
   end
 end

data/lib/cdc_core.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Main entry point for the cdc-core gem.
+#
+# Requiring this file loads the public CDC::Core namespace and all runtime
+# primitives used to model, filter, and process change data capture events.
+require_relative 'cdc/core'

data/sig/cdc/core/change_event.rbs

@@ -0,0 +1,226 @@
+module CDC
+  module Core
+    # Immutable representation of one logical database change.
+    #
+    # ChangeEvent is the core data structure passed through filters, pipelines,
+    # and processors. It is database-agnostic but carries common CDC fields such
+    # as operation, schema, table, before/after values, primary key, LSN, and
+    # metadata.
+    class ChangeEvent
+      @operation: untyped
+
+      @schema: untyped
+
+      @table: untyped
+
+      @old_values: untyped
+
+      @new_values: untyped
+
+      @primary_key: untyped
+
+      @transaction_id: untyped
+
+      @commit_lsn: untyped
+
+      @sequence_number: untyped
+
+      @occurred_at: untyped
+
+      @metadata: untyped
+
+      # @return [Symbol] normalized CDC operation
+      # @return [String] database schema name
+      # @return [String] database table name
+      # @return [Hash, nil] values before the change
+      # @return [Hash, nil] values after the change
+      # @return [Hash, nil] primary key values for the changed row
+      # @return [Object, nil] transaction identifier from the upstream source
+      # @return [String, nil] commit log sequence number
+      # @return [Integer, nil] event sequence within a transaction or stream
+      # @return [Time, nil] timestamp associated with the event
+      # @return [EventMetadata] additional normalized metadata
+      attr_reader operation: untyped
+
+      # @return [Symbol] normalized CDC operation
+      # @return [String] database schema name
+      # @return [String] database table name
+      # @return [Hash, nil] values before the change
+      # @return [Hash, nil] values after the change
+      # @return [Hash, nil] primary key values for the changed row
+      # @return [Object, nil] transaction identifier from the upstream source
+      # @return [String, nil] commit log sequence number
+      # @return [Integer, nil] event sequence within a transaction or stream
+      # @return [Time, nil] timestamp associated with the event
+      # @return [EventMetadata] additional normalized metadata
+      attr_reader schema: untyped
+
+      # @return [Symbol] normalized CDC operation
+      # @return [String] database schema name
+      # @return [String] database table name
+      # @return [Hash, nil] values before the change
+      # @return [Hash, nil] values after the change
+      # @return [Hash, nil] primary key values for the changed row
+      # @return [Object, nil] transaction identifier from the upstream source
+      # @return [String, nil] commit log sequence number
+      # @return [Integer, nil] event sequence within a transaction or stream
+      # @return [Time, nil] timestamp associated with the event
+      # @return [EventMetadata] additional normalized metadata
+      attr_reader table: untyped
+
+      # @return [Symbol] normalized CDC operation
+      # @return [String] database schema name
+      # @return [String] database table name
+      # @return [Hash, nil] values before the change
+      # @return [Hash, nil] values after the change
+      # @return [Hash, nil] primary key values for the changed row
+      # @return [Object, nil] transaction identifier from the upstream source
+      # @return [String, nil] commit log sequence number
+      # @return [Integer, nil] event sequence within a transaction or stream
+      # @return [Time, nil] timestamp associated with the event
+      # @return [EventMetadata] additional normalized metadata
+      attr_reader old_values: untyped
+
+      # @return [Symbol] normalized CDC operation
+      # @return [String] database schema name
+      # @return [String] database table name
+      # @return [Hash, nil] values before the change
+      # @return [Hash, nil] values after the change
+      # @return [Hash, nil] primary key values for the changed row
+      # @return [Object, nil] transaction identifier from the upstream source
+      # @return [String, nil] commit log sequence number
+      # @return [Integer, nil] event sequence within a transaction or stream
+      # @return [Time, nil] timestamp associated with the event
+      # @return [EventMetadata] additional normalized metadata
+      attr_reader new_values: untyped
+
+      # @return [Symbol] normalized CDC operation
+      # @return [String] database schema name
+      # @return [String] database table name
+      # @return [Hash, nil] values before the change
+      # @return [Hash, nil] values after the change
+      # @return [Hash, nil] primary key values for the changed row
+      # @return [Object, nil] transaction identifier from the upstream source
+      # @return [String, nil] commit log sequence number
+      # @return [Integer, nil] event sequence within a transaction or stream
+      # @return [Time, nil] timestamp associated with the event
+      # @return [EventMetadata] additional normalized metadata
+      attr_reader primary_key: untyped
+
+      # @return [Symbol] normalized CDC operation
+      # @return [String] database schema name
+      # @return [String] database table name
+      # @return [Hash, nil] values before the change
+      # @return [Hash, nil] values after the change
+      # @return [Hash, nil] primary key values for the changed row
+      # @return [Object, nil] transaction identifier from the upstream source
+      # @return [String, nil] commit log sequence number
+      # @return [Integer, nil] event sequence within a transaction or stream
+      # @return [Time, nil] timestamp associated with the event
+      # @return [EventMetadata] additional normalized metadata
+      attr_reader transaction_id: untyped
+
+      # @return [Symbol] normalized CDC operation
+      # @return [String] database schema name
+      # @return [String] database table name
+      # @return [Hash, nil] values before the change
+      # @return [Hash, nil] values after the change
+      # @return [Hash, nil] primary key values for the changed row
+      # @return [Object, nil] transaction identifier from the upstream source
+      # @return [String, nil] commit log sequence number
+      # @return [Integer, nil] event sequence within a transaction or stream
+      # @return [Time, nil] timestamp associated with the event
+      # @return [EventMetadata] additional normalized metadata
+      attr_reader commit_lsn: untyped
+
+      # @return [Symbol] normalized CDC operation
+      # @return [String] database schema name
+      # @return [String] database table name
+      # @return [Hash, nil] values before the change
+      # @return [Hash, nil] values after the change
+      # @return [Hash, nil] primary key values for the changed row
+      # @return [Object, nil] transaction identifier from the upstream source
+      # @return [String, nil] commit log sequence number
+      # @return [Integer, nil] event sequence within a transaction or stream
+      # @return [Time, nil] timestamp associated with the event
+      # @return [EventMetadata] additional normalized metadata
+      attr_reader sequence_number: untyped
+
+      # @return [Symbol] normalized CDC operation
+      # @return [String] database schema name
+      # @return [String] database table name
+      # @return [Hash, nil] values before the change
+      # @return [Hash, nil] values after the change
+      # @return [Hash, nil] primary key values for the changed row
+      # @return [Object, nil] transaction identifier from the upstream source
+      # @return [String, nil] commit log sequence number
+      # @return [Integer, nil] event sequence within a transaction or stream
+      # @return [Time, nil] timestamp associated with the event
+      # @return [EventMetadata] additional normalized metadata
+      attr_reader occurred_at: untyped
+
+      # @return [Symbol] normalized CDC operation
+      # @return [String] database schema name
+      # @return [String] database table name
+      # @return [Hash, nil] values before the change
+      # @return [Hash, nil] values after the change
+      # @return [Hash, nil] primary key values for the changed row
+      # @return [Object, nil] transaction identifier from the upstream source
+      # @return [String, nil] commit log sequence number
+      # @return [Integer, nil] event sequence within a transaction or stream
+      # @return [Time, nil] timestamp associated with the event
+      # @return [EventMetadata] additional normalized metadata
+      attr_reader metadata: untyped
+
+      # Build a change event.
+      #
+      # @param operation [#to_sym] CDC operation
+      # @param schema [#to_s] schema name
+      # @param table [#to_s] table name
+      # @param old_values [Hash, nil] values before the change
+      # @param new_values [Hash, nil] values after the change
+      # @param primary_key [Hash, nil] primary key values
+      # @param transaction_id [Object, nil] source transaction identifier
+      # @param commit_lsn [#to_s, nil] commit log sequence number
+      # @param sequence_number [Integer, nil] event sequence number
+      # @param occurred_at [Time, nil] event timestamp
+      # @param metadata [Hash, EventMetadata] additional event metadata
+      def initialize: (operation: untyped, schema: untyped, table: untyped, ?old_values: untyped?, ?new_values: untyped?, ?primary_key: untyped?, ?transaction_id: untyped?, ?commit_lsn: untyped?, ?sequence_number: untyped?, ?occurred_at: untyped?, ?metadata: ::Hash[untyped, untyped]) -> void
+
+      # @return [Boolean] true for insert events
+      def insert?: () -> untyped
+
+      # @return [Boolean] true for update events
+      def update?: () -> untyped
+
+      # @return [Boolean] true for delete events
+      def delete?: () -> untyped
+
+      # Fully qualified table name in schema.table form.
+      #
+      # @return [String]
+      def qualified_table_name: () -> ::String
+
+      # Compute changed columns by comparing old and new values.
+      #
+      # Columns with equal old and new values are omitted. Insert and delete
+      # events can pass nil for one side; missing values are represented as nil.
+      #
+      # @return [Array<ColumnChange>] Ractor-shareable changed columns
+      def changes: () -> untyped
+
+      # Convert the event into a Ractor-shareable hash.
+      #
+      # @return [Hash{String=>Object,nil}]
+      def to_h: () -> untyped
+
+      private
+
+      # Convert a hash into immutable EventMetadata storage, preserving nil.
+      #
+      # @param hash [Hash, nil]
+      # @return [Hash, nil]
+      def freeze_hash_or_nil: (untyped hash) -> (nil | untyped)
+    end
+  end
+end

data/sig/cdc/core/column_change.rbs

@@ -0,0 +1,56 @@
+module CDC
+  module Core
+    # Represents a single column-level value change.
+    #
+    # ColumnChange is immutable and Ractor-shareable. Values that cannot be made
+    # shareable by Ruby are represented by their frozen #inspect string so the
+    # enclosing event can still cross Ractor boundaries safely.
+    class ColumnChange
+      @name: untyped
+
+      @old_value: untyped
+
+      @new_value: untyped
+
+      # @return [String] column name
+      # @return [Object, nil] value before the change
+      # @return [Object, nil] value after the change
+      attr_reader name: untyped
+
+      # @return [String] column name
+      # @return [Object, nil] value before the change
+      # @return [Object, nil] value after the change
+      attr_reader old_value: untyped
+
+      # @return [String] column name
+      # @return [Object, nil] value before the change
+      # @return [Object, nil] value after the change
+      attr_reader new_value: untyped
+
+      # Build a column-level change object.
+      #
+      # @param name [#to_s] column name
+      # @param old_value [Object, nil] previous value
+      # @param new_value [Object, nil] new value
+      def initialize: (name: untyped, old_value: untyped, new_value: untyped) -> void
+
+      # Whether the old and new values differ.
+      #
+      # @return [Boolean]
+      def changed?: () -> untyped
+
+      # Convert the change into a Ractor-shareable hash.
+      #
+      # @return [Hash{String=>Object,nil}]
+      def to_h: () -> untyped
+
+      private
+
+      # Convert a value into a Ractor-shareable representation.
+      #
+      # @param value [Object, nil]
+      # @return [Object, String, nil]
+      def make_value_shareable: (untyped value) -> untyped
+    end
+  end
+end

data/sig/cdc/core/composite_processor.rbs

@@ -0,0 +1,53 @@
+module CDC
+  module Core
+    # Processor that delegates each event 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.
+    class CompositeProcessor < Processor
+      @processors: untyped
+
+      @fail_fast: untyped
+
+      # @return [Array<Processor>] processors executed for each event
+      # @return [Boolean] whether processing stops on the first failure
+      attr_reader processors: untyped
+
+      # @return [Array<Processor>] processors executed for each event
+      # @return [Boolean] whether processing stops on the first failure
+      attr_reader fail_fast: 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
+
+      # Process an event through each configured processor.
+      #
+      # @param event [ChangeEvent] event to process
+      # @return [Array<ProcessorResult>] result from each attempted processor
+      def process: (untyped event) -> untyped
+
+      # Processors that declared Ractor safety.
+      #
+      # @return [Array<Processor>]
+      def ractor_safe_processors: () -> untyped
+
+      # Processors that should remain sequential in the core runtime.
+      #
+      # @return [Array<Processor>]
+      def sequential_processors: () -> untyped
+
+      private
+
+      # Normalize processor return values into ProcessorResult objects.
+      #
+      # @param result [Object] raw processor result
+      # @param event [ChangeEvent] processed event
+      # @return [ProcessorResult]
+      def normalize_result: (untyped result, untyped event) -> untyped
+    end
+  end
+end

data/sig/cdc/core/errors.rbs

@@ -0,0 +1,15 @@
+module CDC
+  module Core
+    # Base error class for all cdc-core specific failures.
+    class Error < StandardError
+    end
+
+    # Raised when an operation cannot be normalized to a supported CDC action.
+    class InvalidOperationError < Error
+    end
+
+    # Raised by processors when a processor-specific failure needs wrapping.
+    class ProcessorError < Error
+    end
+  end
+end