cdc-core 0.0.0 → 0.1.0

data/sig/cdc/core/event_metadata.rbs

@@ -0,0 +1,51 @@
+module CDC
+  module Core
+    # Immutable metadata container for CDC domain objects.
+    #
+    # Metadata keys are normalized to frozen strings. Nested hashes and arrays
+    # are recursively converted into Ractor-shareable objects. Values that Ruby
+    # cannot make shareable are stored as frozen #inspect strings.
+    class EventMetadata
+      @data: untyped
+
+      # @return [Hash{String=>Object}] normalized metadata
+      attr_reader data: untyped
+
+      # Build metadata from a hash-like structure.
+      #
+      # @param data [Hash] metadata values
+      def initialize: (?::Hash[untyped, untyped] data) -> void
+
+      # Fetch a metadata value by string or symbol key.
+      #
+      # @param key [String, Symbol] metadata key
+      # @return [Object, nil]
+      def []: (untyped key) -> untyped
+
+      # Return the normalized Ractor-shareable hash.
+      #
+      # @return [Hash{String=>Object}]
+      def to_h: () -> untyped
+
+      private
+
+      # Recursively normalize and freeze a hash.
+      #
+      # @param hash [Hash]
+      # @return [Hash{String=>Object}]
+      def deep_shareable_hash: (untyped hash) -> untyped
+
+      # Normalize metadata keys to frozen strings.
+      #
+      # @param key [Object]
+      # @return [String]
+      def normalize_key: (untyped key) -> untyped
+
+      # Normalize a metadata value into a shareable representation.
+      #
+      # @param value [Object]
+      # @return [Object]
+      def normalize_value: (untyped value) -> untyped
+    end
+  end
+end

data/sig/cdc/core/filter.rbs

@@ -0,0 +1,68 @@
+module CDC
+  module Core
+    # Predicate object used to decide whether a pipeline should process an event.
+    #
+    # Filters are composable with #& and #|. A filter only matches when its
+    # predicate returns true exactly, keeping accidental truthy values from
+    # silently passing events through a pipeline.
+    class Filter
+      @predicate: untyped
+
+      # Match every event.
+      #
+      # @return [Filter]
+      def self.all: () -> untyped
+
+      # Match events from a schema.
+      #
+      # @param name [#to_s] schema name
+      # @return [Filter]
+      def self.schema: (untyped name) -> untyped
+
+      # Match events from a table regardless of schema.
+      #
+      # @param name [#to_s] table name
+      # @return [Filter]
+      def self.table: (untyped name) -> untyped
+
+      # Match events from a fully qualified schema.table name.
+      #
+      # @param name [#to_s] qualified table name
+      # @return [Filter]
+      def self.qualified_table: (untyped name) -> untyped
+
+      # Match events by operation.
+      #
+      # @param operation [#to_sym] CDC operation
+      # @return [Filter]
+      def self.operation: (untyped operation) -> untyped
+
+      # Build a custom filter.
+      #
+      # @yieldparam event [ChangeEvent] event being tested
+      # @yieldreturn [Boolean] true to match the event
+      # @raise [ArgumentError] when no predicate block is provided
+      def initialize: () ?{ (?) -> untyped } -> void
+
+      # Whether this filter matches an event.
+      #
+      # @param event [ChangeEvent] event to test
+      # @return [Boolean]
+      def match?: (untyped event) -> untyped
+
+      alias =~ match?
+
+      # Compose this filter with another filter using logical AND.
+      #
+      # @param other [Filter] other filter
+      # @return [Filter]
+      def &: (untyped other) -> untyped
+
+      # Compose this filter with another filter using logical OR.
+      #
+      # @param other [Filter] other filter
+      # @return [Filter]
+      def |: (untyped other) -> untyped
+    end
+  end
+end

data/sig/cdc/core/operation.rbs

@@ -0,0 +1,44 @@
+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: untyped
+
+      # Minimal row-change operations used by the initial runtime surface.
+      MVP: untyped
+
+      # 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 self?.normalize: (untyped operation) -> untyped
+
+      # 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 self?.supported?: (untyped operation) -> untyped
+    end
+  end
+end

data/sig/cdc/core/pipeline.rbs

@@ -0,0 +1,55 @@
+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
+      @processor: untyped
+
+      @filters: untyped
+
+      # @return [#process] processor invoked for matching events
+      # @return [Array<Filter>] filters that must all match before processing
+      attr_reader processor: untyped
+
+      # @return [#process] processor invoked for matching events
+      # @return [Array<Filter>] filters that must all match before processing
+      attr_reader filters: 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
+
+      # Process one event through the pipeline.
+      #
+      # @param event [ChangeEvent] event to process
+      # @return [ProcessorResult]
+      def process: (untyped event) -> untyped
+
+      # Process many events in order.
+      #
+      # @param events [Enumerable<ChangeEvent>] events to process
+      # @return [Array<ProcessorResult>]
+      def process_many: (untyped events) -> untyped
+
+      private
+
+      # Check whether every filter matches an event.
+      #
+      # @param event [ChangeEvent]
+      # @return [Boolean]
+      def matches?: (untyped event) -> untyped
+
+      # Normalize raw processor output into a ProcessorResult.
+      #
+      # @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/processor.rbs

@@ -0,0 +1,35 @@
+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
+      self.@ractor_safe: untyped
+
+      # Mark this processor class as safe to execute in Ractor-aware runtimes.
+      #
+      # @return [true]
+      def self.ractor_safe!: () -> untyped
+
+      # Whether this processor class has declared Ractor safety.
+      #
+      # @return [Boolean]
+      def self.ractor_safe?: () -> untyped
+
+      # Whether this processor instance is Ractor-safe.
+      #
+      # @return [Boolean]
+      def ractor_safe?: () -> untyped
+
+      # Process one event.
+      #
+      # Subclasses must override this method.
+      #
+      # @param _event [ChangeEvent] event to process
+      # @raise [NotImplementedError] when not implemented by a subclass
+      def process: (untyped _event) -> untyped
+    end
+  end
+end

data/sig/cdc/core/processor_result.rbs

@@ -0,0 +1,81 @@
+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
+      @status: untyped
+
+      @event: untyped
+
+      @error: untyped
+
+      @metadata: untyped
+
+      # @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: untyped
+
+      # @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 event: untyped
+
+      # @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 error: untyped
+
+      # @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 metadata: untyped
+
+      # Build a successful result.
+      #
+      # @param event [ChangeEvent, nil] processed event
+      # @param metadata [Hash, EventMetadata] result metadata
+      # @return [ProcessorResult]
+      def self.success: (?untyped? event, ?metadata: ::Hash[untyped, untyped]) -> untyped
+
+      # 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: (untyped error, ?event: untyped?, ?metadata: ::Hash[untyped, untyped]) -> untyped
+
+      # Build a skipped result.
+      #
+      # @param event [ChangeEvent, nil] skipped event
+      # @param metadata [Hash, EventMetadata] result metadata
+      # @return [ProcessorResult]
+      def self.skipped: (?untyped? event, ?metadata: ::Hash[untyped, untyped]) -> untyped
+
+      # 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: (untyped status, ?event: untyped?, ?error: untyped?, ?metadata: ::Hash[untyped, untyped]) -> void
+
+      # @return [Boolean] true when status is :success
+      def success?: () -> untyped
+
+      # @return [Boolean] true when status is :failure
+      def failure?: () -> untyped
+
+      # @return [Boolean] true when status is :skipped
+      def skipped?: () -> untyped
+    end
+  end
+end

data/sig/cdc/core/transaction_envelope.rbs

@@ -0,0 +1,79 @@
+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
+      @transaction_id: untyped
+
+      @events: untyped
+
+      @commit_lsn: untyped
+
+      @committed_at: untyped
+
+      @metadata: untyped
+
+      # @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: untyped
+
+      # @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 events: untyped
+
+      # @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 commit_lsn: untyped
+
+      # @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 committed_at: untyped
+
+      # @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 metadata: untyped
+
+      # 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: untyped, events: untyped, ?commit_lsn: untyped?, ?committed_at: untyped?, ?metadata: ::Hash[untyped, untyped]) -> void
+
+      # Whether the envelope has no events.
+      #
+      # @return [Boolean]
+      def empty?: () -> untyped
+
+      # Number of events in the envelope.
+      #
+      # @return [Integer]
+      def size: () -> untyped
+
+      # Convert the transaction envelope into a Ractor-shareable hash.
+      #
+      # @return [Hash{String=>Object,nil}]
+      def to_h: () -> untyped
+    end
+  end
+end

data/sig/cdc/core/version.rbs

@@ -0,0 +1,6 @@
+module CDC
+  module Core
+    # Current gem version.
+    VERSION: "0.1.0"
+  end
+end

data/sig/cdc/core.rbs

@@ -1,6 +1,11 @@
-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
-    VERSION: String
-    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
   end
 end

metadata

@@ -1,15 +1,18 @@
 --- !ruby/object:Gem::Specification
 name: cdc-core
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
 - Ken C. Demanawa
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: Write a longer description or delete this line.
+description: 'CDC Core provides immutable, Ractor-safe Change Data Capture domain
+  objects, processor contracts, filters, and pipeline primitives.
+
+  '
 email:
 - kenneth.c.demanawa@gmail.com
 executables: []
@@ -17,13 +20,36 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/cdc/core.rb
+- lib/cdc/core/change_event.rb
+- lib/cdc/core/column_change.rb
+- lib/cdc/core/composite_processor.rb
+- lib/cdc/core/errors.rb
+- lib/cdc/core/event_metadata.rb
+- lib/cdc/core/filter.rb
+- lib/cdc/core/operation.rb
+- lib/cdc/core/pipeline.rb
+- lib/cdc/core/processor.rb
+- lib/cdc/core/processor_result.rb
+- lib/cdc/core/transaction_envelope.rb
 - lib/cdc/core/version.rb
+- lib/cdc_core.rb
 - sig/cdc/core.rbs
+- sig/cdc/core/change_event.rbs
+- sig/cdc/core/column_change.rbs
+- sig/cdc/core/composite_processor.rbs
+- sig/cdc/core/errors.rbs
+- sig/cdc/core/event_metadata.rbs
+- sig/cdc/core/filter.rbs
+- sig/cdc/core/operation.rbs
+- sig/cdc/core/pipeline.rbs
+- sig/cdc/core/processor.rbs
+- sig/cdc/core/processor_result.rbs
+- sig/cdc/core/transaction_envelope.rbs
+- sig/cdc/core/version.rbs
+- sig/cdc_core.rbs
 homepage: https://github.com/kanutocd/cdc-core
 licenses:
 - MIT
@@ -31,6 +57,7 @@ metadata:
   homepage_uri: https://github.com/kanutocd/cdc-core
   source_code_uri: https://github.com/kanutocd/cdc-core
   changelog_uri: https://github.com/kanutocd/cdc-core/blob/main/CHANGELOG.md
+  documentation_uri: https://kanutocd.github.io/cdc-core/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -46,7 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Write a short summary, because RubyGems requires one.
+summary: Database-agnostic Change Data Capture domain primitives for Ruby.
 test_files: []

data/CODE_OF_CONDUCT.md

@@ -1,10 +0,0 @@
-# Code of Conduct
-
-"cdc-core" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
-
-* Participants will be tolerant of opposing views.
-* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
-* When interpreting the words and actions of others, participants should always assume good intentions.
-* Behaviour which can be reasonably considered harassment will not be tolerated.
-
-If you have any concerns about behaviour within this project, please contact us at ["kenneth.c.demanawa@gmail.com"](mailto:"kenneth.c.demanawa@gmail.com").

data/Rakefile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
-
-RSpec::Core::RakeTask.new(:spec)
-
-require "rubocop/rake_task"
-
-RuboCop::RakeTask.new
-
-task default: %i[spec rubocop]