standard-procedure-plumbing 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45b26855ceaf54673b25fe4ca63a5e52ab302f585f7653731f444b312dec233f
-  data.tar.gz: 936af082c395b80018878f9a53842505473f2d9978c97fafc88aea48102153e4
+  metadata.gz: 71e621c375dc0a17f928884eee2718fc7ed89a2f113374e90a5e6532914d71ea
+  data.tar.gz: 6632624c924bdee49e9dc4b273da36792916c434d12b867d874bcd1ddb880b8b
 SHA512:
-  metadata.gz: 1cce27319493e32407381bb3623734a5bcd87bd1fa986c83f6d8790afb05376c144f994adfd5e094dd9377ad11ee6bdef3d2348ec279d9f378706d52da49362c
-  data.tar.gz: 6594ec35d9753979414b79c524a27d3c033bf96739ec750a0774c1cbb0d7b6dc97ec7e64245026f93f42c8083cce1da91fa772cbcecc61edecba7e931e085c10
+  metadata.gz: aa02b3cc5688ebeed1ec98f22142077d9c26e952bc34772d9395d6d120f2a5103efc67a5cc0e3f7508c937f6392a294f3d6088d8adca9d7415cf81cb2e7f28e6
+  data.tar.gz: d2a164087e839fc3cd48d9b0c22cee9765541a388e4ffc48f5f614faa4690b69d7aa17a6bfc6d77d03ce2ed91e2af49cb8a02fa98e094117194414d7dbd49470

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [0.2.0] - 2024-08-14
+
+ - Added optional Dry::Validation support
+ - Use Async for fiber-based pipes
+
+## [0.1.2] - 2024-08-14
+
+ - Removed dependencies
+ - Removed Ractor-based concurrent pipe (as I don't trust it yet)
+
 ## [0.1.1] - 2024-08-14
 
 - Tidied up the code

data/README.md

@@ -95,13 +95,19 @@ end
 # => "two"
 ```
 
-There is also [Plumbing::Concurrent::Pipe](/lib/plumbing/concurrent/pipe.rb) that uses a Ractor to dispatch events.  Use with caution as Ractors are still experimental, plus they have strict conditions about the data that can be passed across Ractor boundaries.  
-
 ## Plumbing::Chain - a chain of operations that occur in sequence
 
 Define a sequence of operations that proceed in order, passing their output from one operation as the input to another.
 
-You can define pre-conditions (which validate the inputs supplied) or post-conditions (which validate the output).  
+Use `perform` to define a step that takes some input and returns a different output.  
+Use `execute` to define a step that takes some input and returns that same input.  
+Use `embed` to define a step that uses another `Plumbing::Chain` class to generate the output.  
+
+If you have [dry-validation](https://dry-rb.org/gems/dry-validation/1.10/) installed, you can validate your input using a `Dry::Validation::Contract`.  
+
+If you don't want to use dry-validation, you can instead define a `pre_condition` - there's nothing to stop you defining a contract as well as pre_conditions (with the contract being verified first).  
+
+You can also verify that the output generated is as expected by defining a `post_condition`.  
 
 ### Usage:
 
@@ -109,11 +115,12 @@ You can define pre-conditions (which validate the inputs supplied) or post-condi
 require "plumbing"
 class BuildSequence < Plumbing::Chain 
   pre_condition :must_be_an_array do |input| 
+    # you could replace this with a `validate` definition (using a Dry::Validation::Contract) if you prefer
     input.is_a? Array 
   end
 
   post_condition :must_have_three_elements do |output|
-    # yes, this is a stupid post-condition but it shows how you can ensure your outputs are valid
+    # yes, this is a stupid post-condition but 🤷🏾‍♂️
     output.length == 3
   end
 

data/checksums/standard-procedure-plumbing-0.1.2.gem.sha512

@@ -0,0 +1 @@
+18d6d3138d2879c1672ab60b1534a6bc382e99a67adb4f8eff9c60ffb96b78b148bffac54ff1f7e78a2da1fc36d000041806b3a73993416c62279ef3ca09beba

data/lib/plumbing/chain/contracts.rb

@@ -0,0 +1,46 @@
+module Plumbing
+  class Chain
+    module Contracts
+      def pre_condition name, &validator
+        pre_conditions[name.to_sym] = validator
+      end
+
+      def validate_with contract_class
+        @validation_contract = contract_class
+      end
+
+      def post_condition name, &validator
+        post_conditions[name.to_sym] = validator
+      end
+
+      private
+
+      def pre_conditions
+        @pre_conditions ||= {}
+      end
+
+      def post_conditions
+        @post_conditions ||= {}
+      end
+
+      def validate_contract_for input
+        return true if @validation_contract.nil?
+        result = const_get(@validation_contract).new.call(input)
+        raise PreConditionError, result.errors.to_h.to_yaml unless result.success?
+        input
+      end
+
+      def validate_preconditions_for input
+        failed_preconditions = pre_conditions.select { |name, validator| !validator.call(input) }
+        raise PreConditionError, failed_preconditions.keys.join(", ") if failed_preconditions.any?
+        input
+      end
+
+      def validate_postconditions_for output
+        failed_postconditions = post_conditions.select { |name, validator| !validator.call(output) }
+        raise PostConditionError, failed_postconditions.keys.join(", ") if failed_postconditions.any?
+        output
+      end
+    end
+  end
+end

data/lib/plumbing/chain/operations.rb

@@ -0,0 +1,40 @@
+module Plumbing
+  class Chain
+    module Operations
+      def perform method, &implementation
+        implementation ||= ->(input, instance) { instance.send(method, input) }
+        operations << implementation
+      end
+
+      def embed method, class_name
+        implementation = ->(input, instance) { const_get(class_name).new.call(input) }
+        operations << implementation
+      end
+
+      def execute method
+        implementation ||= ->(input, instance) do
+          instance.send(method, input)
+          input
+        end
+        operations << implementation
+      end
+
+      def _call input, instance
+        validate_contract_for input
+        validate_preconditions_for input
+        result = input
+        operations.each do |operation|
+          result = operation.call(result, instance)
+        end
+        validate_postconditions_for result
+        result
+      end
+
+      private
+
+      def operations
+        @operations ||= []
+      end
+    end
+  end
+end

data/lib/plumbing/chain.rb

@@ -1,59 +1,14 @@
+require_relative "chain/contracts"
+require_relative "chain/operations"
+
 module Plumbing
   # A chain of operations that are executed in sequence
   class Chain
-    def call params
-      self.class._call params, self
-    end
-
-    class << self
-      def pre_condition name, &validator
-        pre_conditions[name.to_sym] = validator
-      end
-
-      def perform method, &implementation
-        implementation ||= ->(params, instance) { instance.send(method, params) }
-        operations << implementation
-      end
-
-      def post_condition name, &validator
-        post_conditions[name.to_sym] = validator
-      end
-
-      def _call params, instance
-        validate_preconditions_for params
-        result = params
-        operations.each do |operation|
-          result = operation.call(result, instance)
-        end
-        validate_postconditions_for result
-        result
-      end
-
-      private
-
-      def operations
-        @operations ||= []
-      end
-
-      def pre_conditions
-        @pre_conditions ||= {}
-      end
-
-      def post_conditions
-        @post_conditions ||= {}
-      end
-
-      def validate_preconditions_for input
-        failed_preconditions = pre_conditions.select { |name, validator| !validator.call(input) }
-        raise PreConditionError, failed_preconditions.keys.join(", ") if failed_preconditions.any?
-        input
-      end
+    extend Plumbing::Chain::Contracts
+    extend Plumbing::Chain::Operations
 
-      def validate_postconditions_for output
-        failed_postconditions = post_conditions.select { |name, validator| !validator.call(output) }
-        raise PostConditionError, failed_postconditions.keys.join(", ") if failed_postconditions.any?
-        output
-      end
+    def call input
+      self.class._call input, self
     end
   end
 end

data/lib/plumbing/error.rb

@@ -9,10 +9,10 @@ module Plumbing
   class PostConditionError < Error; end
 
   # Error raised because an invalid [Event] object was pushed into the pipe
-  InvalidEvent = Dry::Types::ConstraintError
+  class InvalidEvent < Error; end
 
   # Error raised because an invalid observer was registered
-  InvalidObserver = Dry::Types::ConstraintError
+  class InvalidObserver < Error; end
 
   # Error raised because a BlockedPipe was used instead of an actual implementation of a Pipe
   class PipeIsBlocked < Plumbing::Error; end

data/lib/plumbing/event.rb

@@ -1,17 +1,5 @@
-require "dry/types"
-require "dry/struct"
-
 module Plumbing
   # An immutable data structure representing an Event
-  class Event < Dry::Struct
-    module Types
-      include Dry::Types()
-      SequenceNumber = Strict::Integer
-      Type = Strict::String
-      Data = Strict::Hash.map(Coercible::Symbol, Nominal::Any).default({}.freeze)
-    end
-
-    attribute :type, Types::Type
-    attribute :data, Types::Data
+  Event = Data.define :type, :data do
   end
 end

data/lib/plumbing/fiber/pipe.rb

@@ -0,0 +1,36 @@
+require "async/task"
+require "async/semaphore"
+
+module Plumbing
+  module Fiber
+    # An implementation of a pipe that uses Fibers
+    class Pipe < Plumbing::Pipe
+      attr_reader :active
+
+      def initialize limit: 4
+        super()
+        @limit = 4
+        @semaphore = Async::Semaphore.new(@limit)
+      end
+
+      def << event
+        raise Plumbing::InvalidEvent.new "event is not a Plumbing::Event" unless event.is_a? Plumbing::Event
+        @semaphore.async do |task|
+          dispatch event, task
+        end
+      end
+
+      protected
+
+      def dispatch event, task
+        @observers.collect do |observer|
+          task.async do
+            observer.call event
+          rescue => ex
+            puts "Error: #{ex}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plumbing/filter.rb

@@ -1,25 +1,20 @@
-require "dry/types"
-require_relative "blocked_pipe"
-
 module Plumbing
   # A pipe that filters events from a source pipe
-  class Filter < BlockedPipe
-    module Types
-      include Dry::Types()
-      Source = Instance(Plumbing::BlockedPipe)
-      EventTypes = Array.of(Plumbing::Event::Types::Type)
-    end
+  class Filter < Pipe
+    class InvalidFilter < Error; end
 
     # Chain this pipe to the source pipe
-    # @param source [Plumbing::BlockedPipe]
+    # @param source [Plumbing::Pipe]
     # @param accepts [Array[String]] event types that this filter will allow through (or pass [] to allow all)
     # @param rejects [Array[String]] event types that this filter will not allow through
     def initialize source:, accepts: [], rejects: []
       super()
-      @accepted_event_types = Types::EventTypes[accepts]
-      @rejected_event_types = Types::EventTypes[rejects]
-      Types::Source[source].add_observer do |event|
-        filter_and_republish(event)
+      raise InvalidFilter.new "source must be a Plumbing::Pipe descendant" unless source.is_a? Plumbing::Pipe
+      raise InvalidFilter.new "accepts and rejects must be arrays" unless accepts.is_a?(Array) && rejects.is_a?(Array)
+      @accepted_event_types = accepts
+      @rejected_event_types = rejects
+      source.add_observer do |event|
+        filter_and_republish event
       end
     end
 

data/lib/plumbing/pipe.rb

@@ -1,28 +1,79 @@
-require_relative "blocked_pipe"
-
 module Plumbing
-  # An implementation of a pipe that uses Fibers
-  class Pipe < BlockedPipe
+  # A basic pipe
+  class Pipe
+    # Subclasses should call `super()` to ensure the pipe is initialised corrected
     def initialize
-      super
-      @fiber = Fiber.new do |initial_event|
-        start_run_loop initial_event
-      end
+      @observers = []
     end
 
+    # Push an event into the pipe
+    # @param event [Plumbing::Event] the event to push into the pipe
     def << event
-      @fiber.resume Types::Event[event]
+      raise Plumbing::InvalidEvent.new event unless event.is_a? Plumbing::Event
+      dispatch event
+    end
+
+    # A shortcut to creating and then pushing an event
+    # @param event_type [String] representing the type of event this is
+    # @param data [Hash] representing the event-specific data to be passed to the observers
+    def notify event_type, data = nil
+      Event.new(type: event_type, data: data).tap do |event|
+        self << event
+      end
+    end
+
+    # Add an observer to this pipe
+    # @param callable [Proc] (optional)
+    # @param &block [Block] (optional)
+    # @return an object representing this observer (dependent upon the implementation of the pipe itself)
+    # Either a `callable` or a `block` must be supplied.  If the latter, it is converted to a [Proc]
+    def add_observer observer = nil, &block
+      observer ||= block.to_proc
+      raise Plumbing::InvalidObserver.new "observer_does_not_respond_to_call" unless observer.respond_to? :call
+      @observers << observer
     end
 
+    # Remove an observer from this pipe
+    # @param observer
+    # This removes the given observer from this pipe.  The observer should have previously been returned by #add_observer and is implementation-specific
+    def remove_observer observer
+      @observers.delete observer
+    end
+
+    # Test whether the given observer is observing this pipe
+    # @param observer
+    # @return [boolean]
+    def is_observer? observer
+      @observers.include? observer
+    end
+
+    # Close this pipe and perform any cleanup.
+    # Subclasses should override this to perform their own shutdown routines and call `super` to ensure everything is tidied up
     def shutdown
-      super
-      @fiber.resume :shutdown
+      # clean up and release any observers, just in case
+      @observers = []
+    end
+
+    # Start this pipe
+    # Subclasses may override this method to add any implementation specific details.
+    # By default any supplied parameters are called to the subclass' `initialize` method
+    def self.start(**params)
+      new(**params)
     end
 
     protected
 
-    def get_next_event
-      Fiber.yield
+    # Dispatch an event to all observers
+    # @param event [Plumbing::Event]
+    # Enumerates all observers and `calls` them with this event
+    # Discards any errors raised by the observer so that all observers will be successfully notified
+    def dispatch event
+      @observers.collect do |observer|
+        observer.call event
+      rescue => ex
+        puts ex
+        ex
+      end
     end
   end
 end

data/lib/plumbing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Plumbing
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/plumbing.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
-require "dry/types"
-module Plumbing
-  require_relative "plumbing/version"
+require_relative "plumbing/version"
+
+require_relative "plumbing/error"
+require_relative "plumbing/event"
+require_relative "plumbing/pipe"
+require_relative "plumbing/filter"
+require_relative "plumbing/chain"
 
-  require_relative "plumbing/error"
-  require_relative "plumbing/event"
-  require_relative "plumbing/pipe"
-  require_relative "plumbing/chain"
+module Plumbing
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Rahoul Baruah
@@ -9,36 +9,8 @@ autorequire:
 bindir: exe
 cert_chain: []
 date: 2024-08-14 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: dry-types
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: dry-struct
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: An event pipeline
+dependencies: []
+description: A composable event pipeline and sequential pipelines of operations
 email:
 - rahoulb@echodek.co
 executables: []
@@ -51,28 +23,29 @@ files:
 - ".standard.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
-- Guardfile
 - LICENSE
 - README.md
 - Rakefile
 - checksums/standard-procedure-plumbing-0.1.1.gem.sha512
+- checksums/standard-procedure-plumbing-0.1.2.gem.sha512
 - lib/plumbing.rb
-- lib/plumbing/blocked_pipe.rb
 - lib/plumbing/chain.rb
-- lib/plumbing/concurrent/pipe.rb
+- lib/plumbing/chain/contracts.rb
+- lib/plumbing/chain/operations.rb
 - lib/plumbing/error.rb
 - lib/plumbing/event.rb
+- lib/plumbing/fiber/pipe.rb
 - lib/plumbing/filter.rb
 - lib/plumbing/pipe.rb
 - lib/plumbing/version.rb
 - sig/plumbing.rbs
-homepage: https://theartandscienceofruby.com
+homepage: https://github.com/standard-procedure/plumbing
 licenses: []
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://theartandscienceofruby.com
-  source_code_uri: https://github.com
-  changelog_uri: https://github.com
+  homepage_uri: https://github.com/standard-procedure/plumbing
+  source_code_uri: https://github.com/standard-procedure/plumbing
+  changelog_uri: https://github.com/standard-procedure/plumbing/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -91,5 +64,5 @@ requirements: []
 rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
-summary: An event pipeline
+summary: Plumbing - various pipelines for your ruby application
 test_files: []

data/Guardfile

@@ -1,32 +0,0 @@
-ignore(/bin/, /log/, /public/, /storage/, /tmp/)
-
-group :formatting do
-  guard :standardrb, fix: true, all_on_start: true, progress: true do
-    watch(/.+\.rb$/)
-    watch(/.+\.thor$/)
-    watch(/.+\.rake$/)
-    watch(/Guardfile$/)
-    watch(/Rakefile$/)
-    watch(/Gemfile$/)
-  end
-end
-
-group :development do
-  guard :rspec, cmd: "bundle exec rspec" do
-    watch("spec/.+_helper.rb") { "spec" }
-    watch(%r{^spec/.+_spec\.rb$})
-    watch(%r{^lib/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
-  end
-
-  guard :bundler do
-    require "guard/bundler"
-    require "guard/bundler/verify"
-    helper = Guard::Bundler::Verify.new
-
-    files = ["Gemfile"]
-    files += Dir["*.gemspec"] if files.any? { |f| helper.uses_gemspec?(f) }
-
-    # Assume files are symlinked from somewhere
-    files.each { |file| watch(helper.real_path(file)) }
-  end
-end

data/lib/plumbing/blocked_pipe.rb

@@ -1,115 +0,0 @@
-require "dry/types"
-require_relative "error"
-require_relative "event"
-
-module Plumbing
-  # The "plumbing" for a Pipe.
-  # This class is "blocked", in that it won't push any events to registered observers.
-  # Instead, this is the basis for subclasses like [Plumbing::Pipe] which actually allow events to flow through them.
-  class BlockedPipe
-    module Types
-      include Dry::Types()
-      # Events must be Plumbing::Event instances or subclasses
-      Event = Instance(Plumbing::Event)
-      # Observers must have a `call` method
-      Observer = Interface(:call)
-    end
-
-    # Create a new BlockedPipe
-    # Subclasses should call `super()` to ensure the pipe is initialised corrected
-    def initialize
-      @observers = []
-    end
-
-    # Push an event into the pipe
-    # @param event [Plumbing::Event] the event to push into the pipe
-    # Subclasses should implement this method
-    def << event
-      raise PipeIsBlocked
-    end
-
-    # A shortcut to creating and then pushing an event
-    # @param event_type [String] representing the type of event this is
-    # @param data [Hash] representing the event-specific data to be passed to the observers
-    def notify event_type, **data
-      Event.new(type: event_type, data: data).tap do |event|
-        self << event
-      end
-    end
-
-    # Add an observer to this pipe
-    # @param callable [Proc] (optional)
-    # @param &block [Block] (optional)
-    # @return an object representing this observer (dependent upon the implementation of the pipe itself)
-    # Either a `callable` or a `block` must be supplied.  If the latter, it is converted to a [Proc]
-    def add_observer callable = nil, &block
-      callable ||= block.to_proc
-      Types::Observer[callable].tap do |observer|
-        @observers << observer
-      end
-    end
-
-    # Remove an observer from this pipe
-    # @param observer
-    # This removes the given observer from this pipe.  The observer should have previously been returned by #add_observer and is implementation-specific
-    def remove_observer observer
-      @observers.delete observer
-    end
-
-    # Test whether the given observer is observing this pipe
-    # @param observer
-    # @return [boolean]
-    def is_observer? observer
-      @observers.include? observer
-    end
-
-    # Close this pipe and perform any cleanup.
-    # Subclasses should override this to perform their own shutdown routines and call `super` to ensure everything is tidied up
-    def shutdown
-      # clean up and release any observers, just in case
-      @observers = []
-    end
-
-    # Start this pipe
-    # Subclasses may override this method to add any implementation specific details.
-    # By default any supplied parameters are called to the subclass' `initialize` method
-    def self.start(**params)
-      new(**params)
-    end
-
-    protected
-
-    # Get the next event from the queue
-    # @return [Plumbing::Event]
-    # Subclasses should implement this method
-    def get_next_event
-      raise PipeIsBlocked
-    end
-
-    # Start the event loop
-    # This loop keeps running until `shutdown` is called
-    # Some subclasses may need to replace this method to deal with their own specific implementations
-    # @param initial_event [Plumbing::Event] optional; the first event in the queue
-    def start_run_loop initial_event = nil
-      loop do
-        event = initial_event || get_next_event
-        break if event == :shutdown
-        dispatch event
-        initial_event = nil
-      end
-    end
-
-    # Dispatch an event to all observers
-    # @param event [Plumbing::Event]
-    # Enumerates all observers and `calls` them with this event
-    # Discards any errors raised by the observer so that all observers will be successfully notified
-    def dispatch event
-      @observers.collect do |observer|
-        observer.call event
-      rescue => ex
-        puts ex
-        ex
-      end
-    end
-  end
-end

data/lib/plumbing/concurrent/pipe.rb

@@ -1,72 +0,0 @@
-require "dry/types"
-require_relative "../blocked_pipe"
-
-module Plumbing
-  module Concurrent
-    class Pipe < Plumbing::BlockedPipe
-      module Types
-        include Dry::Types()
-        # Observers must be Ractors
-        Observer = Instance(Ractor)
-      end
-
-      def initialize
-        super
-        @queue = Ractor.new(self) do |instance|
-          while (message = Ractor.receive) != :shutdown
-            case message.first
-            when :add_observer then instance.send :add_observing_ractor, message.last
-            when :is_observer? then Ractor.yield(instance.send(:is_observing_ractor?, message.last))
-            when :remove_observer then instance.send :remove_observing_ractor, message.last
-            else instance.send :dispatch, message.last
-            end
-          end
-        end
-      end
-
-      def add_observer ractor = nil, &block
-        Plumbing::Concurrent::Pipe::Types::Observer[ractor].tap do |observer|
-          @queue << [:add_observer, observer]
-        end
-      end
-
-      def remove_observer ractor = nil, &block
-        @queue << [:remove_observer, ractor]
-      end
-
-      def is_observer? ractor
-        @queue << [:is_observer?, ractor]
-        @queue.take
-      end
-
-      def << event
-        @queue << [:dispatch, Plumbing::BlockedPipe::Types::Event[event]]
-      end
-
-      def shutdown
-        @queue << :shutdown
-        super
-      end
-
-      private
-
-      def dispatch event
-        @observers.each do |observer|
-          observer << event
-        end
-      end
-
-      def add_observing_ractor observer
-        @observers << observer
-      end
-
-      def is_observing_ractor? observer
-        @observers.include? observer
-      end
-
-      def remove_observing_ractor observer
-        @observers.delete observer
-      end
-    end
-  end
-end