cdc-parallel 0.2.2 → 0.2.3

data/lib/cdc/parallel.rb

@@ -13,7 +13,39 @@ require_relative "parallel/router"
 require_relative "parallel/runtime"
 
 module CDC
-  # Optional parallel Change Data Capture runtime for cdc-core processors.
+  # Optional parallel Change Data Capture runtime for `cdc-core` processors.
+  #
+  # `CDC::Parallel` is the CPU-bound execution layer of the CDC Ecosystem. It
+  # consumes work items that have already been normalized into `cdc-core`
+  # vocabulary objects and executes Ractor-safe processors across pre-warmed
+  # worker Ractors.
+  #
+  # The namespace intentionally avoids `CDC::Ractor` so it does not collide with
+  # Ruby's core `::Ractor` constant.
+  #
+  # ## Boundary
+  #
+  # `cdc-parallel` does not connect to PostgreSQL, parse `pgoutput`, decode
+  # values, normalize source payloads, or persist sink data. Those concerns live
+  # upstream in `pgoutput-*` libraries, source adapters, and downstream sinks.
+  #
+  # ## Main entry points
+  #
+  # * {CDC::Parallel::Runtime} - high-level facade for events and transactions
+  # * {CDC::Parallel::ProcessorPool} - low-level Ractor worker pool
+  # * {CDC::Parallel::TransactionPool} - transaction-envelope wrapper
+  # * {CDC::Parallel::Router} - work item router
+  #
+  # @example
+  #   runtime = CDC::Parallel::Runtime.new(
+  #     processor: AnalyticsProcessor.new,
+  #     size: 4
+  #   )
+  #
+  #   result = runtime.process(change_event)
+  #   runtime.shutdown
+  #
+  # @api public
   module Parallel
   end
 end

data/sig/cdc/parallel/configuration.rbs

@@ -1,8 +1,14 @@
 module CDC
   module Parallel
     # Immutable configuration for Ractor runtimes.
-    class Configuration
-      def initialize: (?size: untyped, ?timeout: untyped?) -> void
+    class Configuration < Data
+      attr_reader size: Integer
+
+      attr_reader timeout: Numeric?
+
+      def self.new: (?size: Integer, ?timeout: Numeric?) -> instance
+
+      def initialize: (?size: Integer, ?timeout: Numeric?) -> void
     end
   end
 end

data/sig/cdc/parallel/errors.rbs

@@ -18,19 +18,19 @@ module CDC
 
     # Raised when processor execution fails inside a worker Ractor.
     class ProcessorExecutionError < Error
-      @original_class: untyped
+      @original_class: String
 
-      @original_message: untyped
+      @original_message: String
 
-      @original_backtrace: untyped
+      @original_backtrace: Array[String]
 
-      attr_reader original_class: untyped
+      attr_reader original_class: String
 
-      attr_reader original_message: untyped
+      attr_reader original_message: String
 
-      attr_reader original_backtrace: untyped
+      attr_reader original_backtrace: Array[String]
 
-      def initialize: (original_class: untyped, original_message: untyped, ?original_backtrace: untyped) -> void
+      def initialize: (original_class: String?, original_message: String, ?original_backtrace: Array[String]) -> void
     end
 
     # Raised when a worker does not return a result before timeout.

data/sig/cdc/parallel/processor_pool.rbs

@@ -2,60 +2,77 @@ module CDC
   module Parallel
     # Executes one Ractor-safe processor in pre-warmed persistent Ractor workers.
     class ProcessorPool
-      @processor: untyped
+      type work_item = untyped
+      type result = CDC::Core::ProcessorResult
+      type worker_response = result | Hash[Symbol, untyped] | untyped
+      type reply_port = Ractor::Port
+      type worker_inbox = Ractor::Port
+      @processor: CDC::Core::Processor
 
-      @configuration: untyped
+      @configuration: Configuration
 
-      @workers: untyped
+      @workers: Array[Ractor]
+
+      @worker_inboxes: Array[worker_inbox]
 
       @next_worker: Integer
 
-      @shutdown: untyped
+      @dispatch_mutex: Mutex
+
+      @shutdown: bool
 
       # @param processor [CDC::Core::Processor]
       # @param size [Integer]
       # @param timeout [Float, nil]
       # @return [void]
-      def initialize: (processor: untyped, ?size: untyped, ?timeout: untyped?) -> void
+      def initialize: (processor: CDC::Core::Processor, ?size: Integer, ?timeout: Numeric?) -> void
 
       # Process one work item synchronously.
       #
       # @param item [Object]
       # @return [CDC::Core::ProcessorResult]
-      def process: (untyped item) -> untyped
+      def process: (work_item item) -> result
 
       # Process many work items using the pre-warmed worker pool.
       #
       # @param items [Array<Object>]
       # @return [Array<CDC::Core::ProcessorResult>]
-      def process_many: (untyped items) -> untyped
+      def process_many: (Array[work_item] items) -> Array[result]
 
       # Shut down the pool.
       #
       # @return [void]
-      def shutdown: () -> untyped
+      def shutdown: () -> nil?
 
       private
 
-      def signal_workers: () -> untyped
+      def self.run_worker_loop: (untyped safe_processor, untyped inbox) -> nil
+
+      def self.worker_response: (untyped safe_processor, work_item item) -> worker_response
+
+      def dispatch: (Array[work_item] work_items, reply_port reply_port) -> Array[work_item]
+
+      def signal_workers: () -> Array[worker_inbox]
 
       def wait_for_workers: () -> untyped
 
       def wait_for_workers_with_timeout: () -> untyped
 
-      def validate_processor!: (untyped processor) -> (nil | untyped)
+      def validate_processor!: (CDC::Core::Processor processor) -> nil
+
+      def build_worker: (CDC::Core::Processor processor) -> ([Ractor, worker_inbox] | Array[untyped])
 
-      def build_worker: (untyped processor) -> untyped
+      def start_worker: (CDC::Core::Processor processor, Ractor::Port boot_port) -> Ractor
 
-      def next_worker: () -> untyped
+      def next_worker_inbox: () -> worker_inbox
 
-      def collect_results: (untyped reply_port, Integer count) -> untyped
+      def collect_results: (reply_port reply_port, Integer count) -> Array[result]
 
-      def collect_results_without_timeout: (untyped reply_port, untyped results) -> untyped
+      def collect_results_without_timeout: (reply_port reply_port, Array[result?] results) -> untyped
 
-      def collect_results_with_timeout: (untyped reply_port, untyped results) -> untyped
+      def collect_results_with_timeout: (reply_port reply_port, Array[result?] results) -> untyped
 
-      def timeout_results: (untyped results) -> untyped
+      def timeout_results: (Array[result?] results) -> Array[result]
     end
   end
 end

data/sig/cdc/parallel/result_collector.rbs

@@ -4,25 +4,27 @@ module CDC
     class ResultCollector
       FAILURE_MARKER: :__cdc_parallel_failure__
 
+      type failure_payload = Hash[Symbol, :__cdc_parallel_failure__ | String | Array[String] | nil]
+
       # Build a shareable success payload that can safely cross a Ractor boundary.
       #
       # @param value [Object]
       # @return [Object]
-      def self.worker_success: (untyped value) -> untyped
+      def self.worker_success: [T] (T value) -> T
 
       # Build a shareable failure payload that can safely cross a Ractor boundary.
       #
       # @param error [Exception]
       # @return [Hash]
-      def self.worker_failure: (untyped error) -> untyped
+      def self.worker_failure: (Exception error) -> failure_payload
 
       # Normalize a worker return value into a ProcessorResult.
       #
       # @param value [Object]
       # @return [CDC::Core::ProcessorResult]
-      def self.normalize: (untyped value) -> untyped
+      def self.normalize: (CDC::Core::ProcessorResult | failure_payload | untyped value) -> CDC::Core::ProcessorResult
 
-      def self.worker_failure?: (untyped value) -> untyped
+      def self.worker_failure?: (untyped value) -> bool
     end
   end
 end

data/sig/cdc/parallel/router.rbs

@@ -2,19 +2,22 @@ module CDC
   module Parallel
     # Routes supported CDC objects to the correct runtime pool.
     class Router
-      @processor_pool: untyped
+      type work_item = CDC::Core::ChangeEvent | CDC::Core::TransactionEnvelope
 
-      @transaction_pool: untyped
+      @processor_pool: ProcessorPool
+
+      @transaction_pool: TransactionPool
 
       # @param processor_pool [ProcessorPool]
       # @param transaction_pool [TransactionPool]
-      def initialize: (processor_pool: untyped, transaction_pool: untyped) -> void
+      def initialize: (processor_pool: ProcessorPool, transaction_pool: TransactionPool) -> void
 
       # Process a supported CDC work item.
       #
       # @param item [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope]
       # @return [CDC::Core::ProcessorResult]
-      def process: (untyped item) -> untyped
+      def process: (work_item item) -> CDC::Core::ProcessorResult
+                 | (untyped item) -> CDC::Core::ProcessorResult
     end
   end
 end

data/sig/cdc/parallel/runtime.rbs

@@ -2,36 +2,39 @@ module CDC
   module Parallel
     # High-level Ractor runtime facade for cdc-core processors.
     class Runtime
-      @processor_pool: untyped
+      type work_item = CDC::Core::ChangeEvent | CDC::Core::TransactionEnvelope
 
-      @transaction_pool: untyped
+      @processor_pool: ProcessorPool
 
-      @router: untyped
+      @transaction_pool: TransactionPool
 
-      @shutdown: untyped
+      @router: Router
+
+      @shutdown: bool
 
       # @param processor [CDC::Core::Processor]
       # @param size [Integer]
       # @param timeout [Float, nil]
       # @return [void]
-      def initialize: (processor: untyped, ?size: untyped, ?timeout: untyped?) -> void
+      def initialize: (processor: CDC::Core::Processor, ?size: Integer, ?timeout: Numeric?) -> void
 
       # Process a ChangeEvent or TransactionEnvelope.
       #
       # @param item [CDC::Core::ChangeEvent, CDC::Core::TransactionEnvelope]
       # @return [CDC::Core::ProcessorResult]
-      def process: (untyped item) -> untyped
+      def process: (work_item item) -> CDC::Core::ProcessorResult
+                 | (untyped item) -> CDC::Core::ProcessorResult
 
       # Alias for transaction-oriented processing.
       #
       # @param transaction [CDC::Core::TransactionEnvelope]
       # @return [CDC::Core::ProcessorResult]
-      def process_transaction: (untyped transaction) -> untyped
+      def process_transaction: (CDC::Core::TransactionEnvelope transaction) -> CDC::Core::ProcessorResult
 
       # Shut down all runtime resources.
       #
       # @return [void]
-      def shutdown: () -> (nil | untyped)
+      def shutdown: () -> nil
     end
   end
 end

data/sig/cdc/parallel/transaction_pool.rbs

@@ -2,23 +2,23 @@ module CDC
   module Parallel
     # Processes a TransactionEnvelope as a single ordering-preserving unit.
     class TransactionPool
-      @processor_pool: untyped
+      @processor_pool: ProcessorPool
 
       # @param processor [CDC::Core::Processor]
       # @param size [Integer]
       # @param timeout [Float, nil]
-      def initialize: (processor: untyped, ?size: untyped, ?timeout: untyped?) -> void
+      def initialize: (processor: CDC::Core::Processor, ?size: Integer, ?timeout: Numeric?) -> void
 
       # Process all events inside a transaction envelope.
       #
       # @param transaction [CDC::Core::TransactionEnvelope]
       # @return [CDC::Core::ProcessorResult]
-      def process: (untyped transaction) -> untyped
+      def process: (CDC::Core::TransactionEnvelope transaction) -> CDC::Core::ProcessorResult
 
       # Shut down worker resources.
       #
       # @return [void]
-      def shutdown: () -> untyped
+      def shutdown: () -> nil
     end
   end
 end

data/sig/cdc/parallel/version.rbs

@@ -1,6 +1,6 @@
 module CDC
   module Parallel
     # Current cdc-parallel version.
-    VERSION: "0.2.0"
+    VERSION: "0.2.3"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cdc-parallel
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Ken C. Demanawa
@@ -13,30 +13,16 @@ dependencies:
   name: cdc-core
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0.1'
-- !ruby/object:Gem::Dependency
-  name: ractor-pool
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.4.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.4.0
 description: |
   cdc-parallel provides optional Ractor-backed parallel execution for
   cdc-core. It accelerates PostgreSQL Change Data Capture (CDC) event
@@ -70,15 +56,11 @@ files:
 - sig/cdc/parallel/transaction_pool.rbs
 - sig/cdc/parallel/version.rbs
 - sig/cdc_parallel.rbs
-- sig/shims/cdc_core.rbs
-- sig/shims/data_define.rbs
-- sig/shims/etc.rbs
-- sig/shims/timeout.rbs
-homepage: https://kanutocd.github.io/cdc-parallel/
+homepage: https://github.com/kanutocd/cdc-parallel
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://kanutocd.github.io/cdc-parallel/
+  homepage_uri: https://github.com/kanutocd/cdc-parallel
   source_code_uri: https://github.com/kanutocd/cdc-parallel
   changelog_uri: https://github.com/kanutocd/cdc-parallel/blob/main/CHANGELOG.md
   documentation_uri: https://kanutocd.github.io/cdc-parallel/

data/sig/shims/cdc_core.rbs

@@ -1,14 +0,0 @@
-module CDC
-  module Core
-    class ProcessorResult
-      def self.success: (untyped event) -> ProcessorResult
-      def self.failure: (untyped error, ?event: untyped) -> ProcessorResult
-    end
-
-    class ChangeEvent
-    end
-
-    class TransactionEnvelope
-    end
-  end
-end

data/sig/shims/etc.rbs

@@ -1,3 +0,0 @@
-module Etc
-  def self.nprocessors: () -> Integer
-end

data/sig/shims/timeout.rbs

@@ -1,3 +0,0 @@
-module Timeout
-  def self.timeout: (untyped sec, untyped klass) { () -> untyped } -> untyped
-end