cdc-core 0.1.2 → 0.1.3

data/lib/cdc/core/processor_result.rb

@@ -10,6 +10,10 @@ module CDC
     class ProcessorResult
       # Allowed result statuses.
       VALID_STATUSES = Ractor.make_shareable(%i[success failure skipped].freeze)
+      EMPTY_METADATA = Ractor.make_shareable(
+        {} # : Hash[untyped, untyped]
+          .freeze
+      )
 
       # @return [Symbol] result status
       # @return [ChangeEvent, Object, nil] event or input associated with the result
@@ -23,8 +27,8 @@ module CDC
       # @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: {}, value: event) = new(:success, event:, metadata:, value:)
+      # @return [ProcessorResult] successful processor result
+      def self.success(event = nil, metadata: EMPTY_METADATA, value: event) = new(:success, event:, metadata:, value:)
 
       # Build a failure result.
       #
@@ -35,7 +39,7 @@ module CDC
       # @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]
+      # @return [ProcessorResult] failed processor result
       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
@@ -53,8 +57,8 @@ module CDC
       #
       # @param event [ChangeEvent, nil] skipped event
       # @param metadata [Hash, EventMetadata] result metadata
-      # @return [ProcessorResult]
-      def self.skipped(event = nil, metadata: {}) = new(:skipped, event:, metadata:)
+      # @return [ProcessorResult] skipped processor result
+      def self.skipped(event = nil, metadata: EMPTY_METADATA) = new(:skipped, event:, metadata:)
 
       # Build a processor result with an explicit status.
       #
@@ -63,7 +67,7 @@ module CDC
       # @param error [Exception, nil] associated failure
       # @param metadata [Hash, EventMetadata] result metadata
       # @param value [Object, nil] value produced by the processor
-      def initialize(status, event: nil, error: nil, metadata: {}, value: event)
+      def initialize(status, event: nil, error: nil, metadata: EMPTY_METADATA, value: event)
         @status = normalize_status(status)
         @event = event
         @value = value
@@ -83,56 +87,56 @@ module CDC
 
       # Human-readable failure reason, when present.
       #
-      # @return [String, nil]
+      # @return [String, nil] human-readable failure reason
       def failure_reason
         metadata[:reason]
       end
 
       # Whether the failure is retryable.
       #
-      # @return [Boolean]
+      # @return [Boolean] true when metadata marks the failure retryable
       def retryable?
         metadata[:retryable] == true
       end
 
       # Name of the processor associated with the failure, when present.
       #
-      # @return [String, nil]
+      # @return [String, nil] processor name associated with the failure
       def processor_name
         metadata[:processor]
       end
 
       # Timestamp for when the failure occurred, when present.
       #
-      # @return [String, nil]
+      # @return [String, nil] timestamp for when the failure occurred
       def failed_at
         metadata[:failed_at]
       end
 
       # Error class name, when present.
       #
-      # @return [String, nil]
+      # @return [String, nil] class name of the associated error
       def error_class
         error&.class&.name
       end
 
       # Error message, when present.
       #
-      # @return [String, nil]
+      # @return [String, nil] message from the associated error
       def error_message
         error&.message
       end
 
       # Error backtrace, when present.
       #
-      # @return [Array<String>]
+      # @return [Array<String>] backtrace from the associated error
       def error_backtrace
         Array(error&.backtrace)
       end
 
       # Convert the result into a shareable hash.
       #
-      # @return [Hash{String=>Object,nil}]
+      # @return [Hash{String=>Object,nil}] Ractor-shareable result representation
       def to_h
         payload = {
           'status' => status,

data/lib/cdc/core/router.rb

@@ -26,8 +26,8 @@ module CDC
 
       # Process a CDC work item.
       #
-      # @param item [ChangeEvent, TransactionEnvelope, Array<ChangeEvent>]
-      # @return [Object]
+      # @param item [ChangeEvent, TransactionEnvelope, Array<ChangeEvent>] work item to route
+      # @return [Object] value returned by the selected handler
       # @raise [UnsupportedWorkItemError] when the item cannot be routed
       def process(item)
         observer.dispatch_started(item)
@@ -49,8 +49,8 @@ module CDC
 
       # Route a transaction envelope to the configured transaction processor.
       #
-      # @param transaction [TransactionEnvelope]
-      # @return [Object]
+      # @param transaction [TransactionEnvelope] transaction envelope to route
+      # @return [Object] value returned by the transaction processor
       def route_transaction(transaction)
         return transaction_processor.process(transaction) if transaction_processor
 
@@ -60,8 +60,8 @@ module CDC
 
       # Route many change events through the configured processor.
       #
-      # @param items [Array]
-      # @return [Object]
+      # @param items [Array] change events to route as a batch
+      # @return [Object] batch processor result or array of per-event results
       def route_many(items)
         unless items.all?(ChangeEvent)
           raise UnsupportedWorkItemError, "unsupported CDC work item: Array(#{items.first.class})"

data/lib/cdc/core/source_adapter.rb

@@ -19,7 +19,7 @@ module CDC
       # Subclasses must override this method.
       #
       # @param _input [Object] source-specific payload
-      # @return [ChangeEvent, TransactionEnvelope, Array<ChangeEvent>, Array<TransactionEnvelope>]
+      # @return [ChangeEvent,TransactionEnvelope, Array<ChangeEvent>, Array<TransactionEnvelope>] normalized core object or objects # rubocop:disable Layout/LineLength
       # @raise [NotImplementedError] when not implemented by a subclass
       def normalize(_input)
         raise NotImplementedError, "#{self.class} must implement #normalize"
@@ -32,7 +32,7 @@ module CDC
       # objects for each payload.
       #
       # @param inputs [Enumerable] source-specific payloads
-      # @return [Array]
+      # @return [Array] flattened normalized core objects
       def normalize_many(inputs)
         Array(inputs).flat_map { |input| normalize(input) }.freeze
       end

data/lib/cdc/core/transaction_envelope.rb

@@ -8,6 +8,11 @@ module CDC
     # boundaries instead of isolated row-level events. The contained events and
     # metadata are Ractor-shareable when construction succeeds.
     class TransactionEnvelope
+      EMPTY_METADATA = Ractor.make_shareable(
+        {} # : Hash[untyped, untyped]
+          .freeze
+      )
+
       # @return [Object] transaction identifier
       # @return [Array<ChangeEvent>] events committed by the transaction
       # @return [String, nil] commit log sequence number
@@ -22,7 +27,7 @@ module CDC
       # @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: {})
+      def initialize(transaction_id:, events:, commit_lsn: nil, committed_at: nil, metadata: EMPTY_METADATA)
         @transaction_id = transaction_id
         @events = Ractor.make_shareable(events.freeze)
         @commit_lsn = commit_lsn&.to_s&.freeze
@@ -33,17 +38,17 @@ module CDC
 
       # Whether the envelope has no events.
       #
-      # @return [Boolean]
+      # @return [Boolean] true when the envelope has no events
       def empty? = events.empty?
 
       # Number of events in the envelope.
       #
-      # @return [Integer]
+      # @return [Integer] number of events in the envelope
       def size = events.size
 
       # Convert the transaction envelope into a Ractor-shareable hash.
       #
-      # @return [Hash{String=>Object,nil}]
+      # @return [Hash{String=>Object,nil}] Ractor-shareable transaction representation
       def to_h
         Ractor.make_shareable({
           'transaction_id' => transaction_id,

data/lib/cdc/core/version.rb

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

data/sig/cdc/core/change_event.rbs

@@ -1,226 +1,44 @@
 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
+      EMPTY_METADATA: metadata_hash
+
+      attr_reader operation: Symbol
+      attr_reader schema: String
+      attr_reader table: String
+      attr_reader old_values: event_values?
+      attr_reader new_values: event_values?
+      attr_reader primary_key: event_values?
       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
+      attr_reader commit_lsn: String?
+      attr_reader sequence_number: Integer?
+      attr_reader occurred_at: ::Time?
+      attr_reader metadata: EventMetadata
+
+      def initialize: (
+        operation: Symbol | String,
+        schema: String | Symbol,
+        table: String | Symbol,
+        ?old_values: metadata_hash?,
+        ?new_values: metadata_hash?,
+        ?primary_key: metadata_hash?,
+        ?transaction_id: untyped,
+        ?commit_lsn: String?,
+        ?sequence_number: Integer?,
+        ?occurred_at: ::Time?,
+        ?metadata: EventMetadata | metadata_hash
+      ) -> void
+
+      def insert?: () -> bool
+      def update?: () -> bool
+      def delete?: () -> bool
+      def qualified_table_name: () -> String
+      def changes: () -> ::Array[ColumnChange]
+      def to_h: () -> shareable_hash
 
       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)
+      def freeze_hash_or_nil: (metadata_hash? hash) -> event_values?
     end
   end
 end

data/sig/cdc/core/column_change.rbs

@@ -1,55 +1,16 @@
 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 name: String
       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
+      def initialize: (name: String | Symbol, old_value: untyped, new_value: untyped) -> void
+      def changed?: () -> bool
+      def to_h: () -> shareable_hash
 
       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

data/sig/cdc/core/composite_processor.rbs

@@ -1,64 +1,21 @@
 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
+      attr_reader processors: ::Array[_ProcessorLike]
+      attr_reader fail_fast: bool
+      attr_reader observer: Observer
 
-      @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
-
-      # @return [Array<Processor>] processors executed for each event
-      # @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
-      # @param observer [Observer, nil] instrumentation observer
-      def initialize: (untyped processors, ?fail_fast: bool, ?observer: untyped?) -> 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
+      def initialize: (::Array[_ProcessorLike] processors, ?fail_fast: bool, ?observer: Observer?) -> void
+      def process: (untyped event) -> ::Array[ProcessorResult]
+      def ractor_safe_processors: () -> ::Array[_ProcessorLike]
+      def sequential_processors: () -> ::Array[_ProcessorLike]
 
       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
-
-      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
+      def normalize_result: (untyped result, untyped event) -> ProcessorResult
+      def collect_results: (untyped event) -> ::Array[ProcessorResult]
+      def process_with: (_ProcessorLike processor, untyped event) -> ProcessorResult
+      def observe_results: (::Array[ProcessorResult] results) -> void
     end
   end
 end

data/sig/cdc/core/errors.rbs

@@ -1,26 +1,20 @@
 module CDC
   module Core
-    # Base error class for all cdc-core specific failures.
-    class Error < StandardError
+    class Error < ::StandardError
     end
 
-    # Raised when an operation cannot be normalized to a supported CDC action.
     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
   end