standard-procedure-plumbing 0.2.1 → 0.3.0

data/lib/plumbing/config.rb

@@ -0,0 +1,51 @@
+# Pipes, pipelines, valves and rubber ducks
+module Plumbing
+  Config = Data.define :mode, :valve_proxy_classes, :timeout do
+    def valve_proxy_class_for target_class
+      valve_proxy_classes[target_class]
+    end
+
+    def register_valve_proxy_class_for target_class, proxy_class
+      valve_proxy_classes[target_class] = proxy_class
+    end
+  end
+  private_constant :Config
+
+  # Access the current configuration
+  # @return [Config]
+  def self.config
+    configs.last
+  end
+
+  # Configure the plumbing
+  # @param params [Hash] the configuration options
+  # @option mode [Symbol] the mode to use (:inline is the default, :async uses fibers)
+  # @option timeout [Integer] the timeout (in seconds) to use (30s is the default)
+  # @yield optional block - after the block has completed its execution, the configuration is restored to its previous state (useful for test suites)
+  def self.configure(**params, &block)
+    new_config = Config.new(**config.to_h.merge(params).merge(valve_proxy_classes: {}))
+    if block.nil?
+      set_configuration_to new_config
+    else
+      set_configuration_and_yield new_config, &block
+    end
+  end
+
+  def self.set_configuration_to config
+    configs << config
+  end
+  private_class_method :set_configuration_to
+
+  def self.set_configuration_and_yield(new_config, &block)
+    set_configuration_to new_config
+    yield
+  ensure
+    configs.pop
+  end
+  private_class_method :set_configuration_and_yield
+
+  def self.configs
+    @configs ||= [Config.new(mode: :inline, timeout: 30, valve_proxy_classes: {})]
+  end
+  private_class_method :configs
+end

data/lib/plumbing/custom_filter.rb

@@ -0,0 +1,15 @@
+module Plumbing
+  # A pipe that can be subclassed to filter events from a source pipe
+  class CustomFilter < Pipe
+    # Chain this pipe to the source pipe
+    # @param source [Plumbing::Observable] the source from which to receive and filter events
+    def initialize source:
+      super()
+      source.as(Observable).add_observer { |event| received event }
+    end
+
+    protected
+
+    def received(event) = raise NoMethodError.new("Subclass should define #received")
+  end
+end

data/lib/plumbing/error.rb

@@ -10,10 +10,4 @@ module Plumbing
 
   # Error raised because an invalid [Event] object was pushed into the pipe
   class InvalidEvent < Error; end
-
-  # Error raised because an invalid observer was registered
-  class InvalidObserver < Error; end
-
-  # Error raised because a Pipe was connected to a non-Pipe
-  class InvalidSource < Plumbing::Error; end
 end

data/lib/plumbing/event.rb

@@ -1,5 +1,4 @@
 module Plumbing
   # An immutable data structure representing an Event
-  Event = Data.define :type, :data do
-  end
+  Event = Data.define :type, :data
 end

data/lib/plumbing/filter.rb

@@ -1,21 +1,20 @@
+require_relative "custom_filter"
 module Plumbing
   # A pipe that filters events from a source pipe
-  class Filter < Pipe
+  class Filter < CustomFilter
     # Chain this pipe to the source pipe
-    # @param source [Plumbing::Pipe]
+    # @param source [Plumbing::Observable] the source from which to receive and filter events
     # @param &accepts [Block] a block that returns a boolean value - true to accept the event, false to reject it
-    def initialize source:, dispatcher: nil, &accepts
-      super(dispatcher: dispatcher)
-      raise InvalidSource.new "#{source} must be a Plumbing::Pipe descendant" unless source.is_a? Plumbing::Pipe
-      @accepts = accepts
-      source.add_observer do |event|
-        filter_and_republish event
-      end
+    # @yield [Plumbing::Event] event the event that is currently being processed
+    # @yieldreturn [Boolean] true to accept the event, false to reject it
+    def initialize source:, &accepts
+      super(source: source)
+      @accepts = accepts.as(Callable)
     end
 
-    private
+    protected
 
-    def filter_and_republish event
+    def received(event)
       return nil unless @accepts.call event
       dispatch event
     end

data/lib/plumbing/junction.rb

@@ -2,17 +2,16 @@ module Plumbing
   # A pipe that filters events from a source pipe
   class Junction < Pipe
     # Chain multiple sources to this pipe
-    # @param [Array<Plumbing::Pipe>]
-    def initialize *sources, dispatcher: nil
-      super(dispatcher: dispatcher)
+    # @param sources [Array<Plumbing::Observable>] the sources which will be joined and relayed
+    def initialize *sources
+      super()
       @sources = sources.collect { |source| add(source) }
     end
 
     private
 
     def add source
-      raise InvalidSource.new "#{source} must be a Plumbing::Pipe descendant" unless source.is_a? Plumbing::Pipe
-      source.add_observer do |event|
+      source.as(Observable).add_observer do |event|
         dispatch event
       end
       source

data/lib/plumbing/pipe.rb

@@ -1,12 +1,10 @@
 module Plumbing
   # A basic pipe
   class Pipe
-    require_relative "event_dispatcher"
+    include Plumbing::Valve
 
-    # Subclasses should call `super()` to ensure the pipe is initialised corrected
-    def initialize dispatcher: nil
-      @dispatcher = dispatcher || EventDispatcher.new
-    end
+    command :notify, :<<, :remove_observer, :shutdown
+    query :add_observer, :is_observer?
 
     # Push an event into the pipe
     # @param event [Plumbing::Event] the event to push into the pipe
@@ -25,40 +23,33 @@ module Plumbing
     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, &)
-      @dispatcher.add_observer(observer, &)
+    # @param callable [#call] (optional)
+    # @param &block [Block] (optional)
+    # @return [#call]
+    def add_observer(observer = nil, &block)
+      observer ||= block.to_proc
+      observers << observer.as(Callable).target
+      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
+    # @param observer [#call] remove the observer from this pipe (where the observer was previously added by #add_observer)
     def remove_observer observer
-      @dispatcher.remove_observer observer
+      observers.delete observer
     end
 
     # Test whether the given observer is observing this pipe
-    # @param observer
-    # @return [boolean]
+    # @param [#call] observer
+    # @return [Boolean]
     def is_observer? observer
-      @dispatcher.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
-      @dispatcher.shutdown
-    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(*, **, &)
-      new(*, **, &)
+      observers.clear
     end
 
     protected
@@ -68,7 +59,16 @@ module Plumbing
     # 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
-      @dispatcher.dispatch event
+      observers.each do |observer|
+        observer.call event
+      rescue => ex
+        puts ex
+        ex
+      end
+    end
+
+    def observers
+      @observers ||= []
     end
   end
 end

data/lib/plumbing/pipeline/contracts.rb

@@ -1,14 +1,24 @@
 module Plumbing
   class Pipeline
+    # Validate input and output data with pre and post conditions or [Dry::Validation::Contract]s
     module Contracts
+      # @param name [Symbol] the name of the precondition
+      # @param &validator [Block] a block that returns a boolean value - true to accept the input, false to reject it
+      # @yield [Object] input the input data to be validated
+      # @yieldreturn [Boolean] true to accept the input, false to reject it
       def pre_condition name, &validator
         pre_conditions[name.to_sym] = validator
       end
 
+      # @param [String] contract_class the class name of the [Dry::Validation::Contract] that will be used to validate the input data
       def validate_with contract_class
         @validation_contract = contract_class
       end
 
+      # @param name [Symbol] the name of the postcondition
+      # @param &validator [Block] a block that returns a boolean value - true to accept the input, false to reject it
+      # @yield [Object] output the output data to be validated
+      # @yieldreturn [Boolean] true to accept the output, false to reject it
       def post_condition name, &validator
         post_conditions[name.to_sym] = validator
       end
@@ -25,19 +35,19 @@ module Plumbing
 
       def validate_contract_for input
         return true if @validation_contract.nil?
-        result = const_get(@validation_contract).new.call(input)
+        result = const_get(@validation_contract).new.as(Callable).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) }
+        failed_preconditions = pre_conditions.select { |name, validator| !validator.as(Callable).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) }
+        failed_postconditions = post_conditions.select { |name, validator| !validator.as(Callable).call(output) }
         raise PostConditionError, failed_postconditions.keys.join(", ") if failed_postconditions.any?
         output
       end

data/lib/plumbing/pipeline/operations.rb

@@ -1,10 +1,26 @@
 module Plumbing
   class Pipeline
+    # Defining the operations that will be performed on the input data
     module Operations
+      # Add an operation to the pipeline
+      # Operations are processed in order, unless interrupted by an exception
+      # The output from the previous operation is fed in as the input to the this operation
+      # and the output from this operation is fed in as the input to the next operation
+      #
+      # @param method [Symbol] the method to be called on the input data
+      # @param using [String, Class] the optional class name or class that will be used to perform the operation
+      # @param &implementation [Block] the optional block that will be used to perform the operation (instead of calling a method)
+      # @yield [Object] input the input data to be processed
+      # @yieldreturn [Object] the output data
       def perform method, using: nil, &implementation
         using.nil? ? perform_internal(method, &implementation) : perform_external(method, using)
       end
 
+      # Add an operation which does not alter the input data to the pipeline
+      # The output from the previous operation is fed in as the input to the this operation
+      # but the output from this operation is discarded and the previous input is fed in to the next operation
+      #
+      # @param method [Symbol] the method to be called on the input data
       def execute method
         implementation ||= ->(input, instance) do
           instance.send(method, input)
@@ -13,12 +29,13 @@ module Plumbing
         operations << implementation
       end
 
+      # Internal use only
       def _call input, instance
         validate_contract_for input
         validate_preconditions_for input
         result = input
         operations.each do |operation|
-          result = operation.call(result, instance)
+          result = operation.as(Callable).call(result, instance)
         end
         validate_postconditions_for result
         result
@@ -37,7 +54,7 @@ module Plumbing
 
       def perform_external method, class_or_class_name
         external_class = class_or_class_name.is_a?(String) ? const_get(class_or_class_name) : class_or_class_name
-        implementation = ->(input, instance) { external_class.new.call(input) }
+        implementation = ->(input, instance) { external_class.new.as(Callable).call(input) }
         operations << implementation
       end
     end

data/lib/plumbing/pipeline.rb

@@ -7,6 +7,9 @@ module Plumbing
     extend Plumbing::Pipeline::Contracts
     extend Plumbing::Pipeline::Operations
 
+    # Start the pipeline operation with the given input
+    # @param input [Object] the input data to be processed
+    # @return [Object] the output data
     def call input
       self.class._call input, self
     end

data/lib/plumbing/rubber_duck/object.rb

@@ -0,0 +1,11 @@
+module Plumbing
+  class RubberDuck
+    ::Object.class_eval do
+      # Cast the object to a duck-type
+      # @return [Plumbing::RubberDuck::Proxy] the duck-type proxy
+      def as duck_type
+        duck_type.proxy_for self
+      end
+    end
+  end
+end

data/lib/plumbing/rubber_duck/proxy.rb

@@ -0,0 +1,19 @@
+module Plumbing
+  class RubberDuck
+    # Proxy object that forwards the duck-typed methods to the target object
+    class Proxy
+      attr_reader :target
+
+      def initialize target, duck_type
+        @target = target
+        @duck_type = duck_type
+      end
+
+      # Convert the proxy to the given duck-type, ensuring that existing proxies are not duplicated
+      # @return [Plumbing::RubberDuck::Proxy] the proxy for the given duck-type
+      def as duck_type
+        (duck_type == @duck_type) ? self : duck_type.proxy_for(target)
+      end
+    end
+  end
+end

data/lib/plumbing/rubber_duck.rb

@@ -0,0 +1,59 @@
+module Plumbing
+  # A type-checker for duck-types
+  class RubberDuck
+    require_relative "rubber_duck/object"
+    require_relative "rubber_duck/proxy"
+
+    def initialize *methods
+      @methods = methods.map(&:to_sym)
+      @proxy_classes = {}
+    end
+
+    # Verify that the given object responds to the required methods
+    # @param object [Object] the object to verify
+    # @return [Object] the object if it passes the verification
+    # @raise [TypeError] if the object does not respond to the required methods
+    def verify object
+      missing_methods = @methods.reject { |method| object.respond_to? method }
+      raise TypeError, "Expected object to respond to #{missing_methods.join(", ")}" unless missing_methods.empty?
+      object
+    end
+
+    # Test if the given object is a proxy
+    # @param object [Object] the object to test
+    # @return [Boolean] true if the object is a proxy, false otherwise
+    def proxy_for object
+      is_a_proxy?(object) || build_proxy_for(object)
+    end
+
+    # Define a new rubber duck type
+    # @param *methods [Array<Symbol>] the methods that the duck-type should respond to
+    def self.define *methods
+      new(*methods)
+    end
+
+    private
+
+    def is_a_proxy? object
+      @proxy_classes.value?(object.class) ? object : nil
+    end
+
+    def build_proxy_for object
+      proxy_class_for(object).new(verify(object), self)
+    end
+
+    def proxy_class_for object
+      @proxy_classes[object.class] ||= define_proxy_class_for(object.class)
+    end
+
+    def define_proxy_class_for klass
+      Class.new(Plumbing::RubberDuck::Proxy).tap do |proxy_class|
+        @methods.each do |method|
+          proxy_class.define_method method do |*args, &block|
+            @target.send method, *args, &block
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plumbing/types.rb

@@ -0,0 +1,6 @@
+module Plumbing
+  Callable = RubberDuck.define :call
+  Observable = RubberDuck.define :add_observer, :remove_observer, :is_observer?
+  DispatchesEvents = RubberDuck.define :add_observer, :remove_observer, :is_observer?, :shutdown, :dispatch
+  Collection = RubberDuck.define :each, :<<, :delete, :include?
+end

data/lib/plumbing/valve/async.rb

@@ -0,0 +1,42 @@
+require "async"
+require "async/semaphore"
+require "timeout"
+
+module Plumbing
+  module Valve
+    class Async
+      attr_reader :target
+
+      def initialize target
+        @target = target
+        @queue = []
+        @semaphore = ::Async::Semaphore.new(1)
+      end
+
+      # Ask the target to answer the given message
+      def ask(message, *args, **params, &block)
+        task = @semaphore.async do
+          @target.send message, *args, **params, &block
+        end
+        Timeout.timeout(timeout) do
+          task.wait
+        end
+      end
+
+      # Tell the target to execute the given message
+      def tell(message, *args, **params, &block)
+        @semaphore.async do |task|
+          @target.send message, *args, **params, &block
+        rescue
+          nil
+        end
+      end
+
+      private
+
+      def timeout
+        Plumbing.config.timeout
+      end
+    end
+  end
+end

data/lib/plumbing/valve/inline.rb

@@ -0,0 +1,19 @@
+module Plumbing
+  module Valve
+    class Inline
+      def initialize target
+        @target = target
+      end
+
+      # Ask the target to answer the given message
+      def ask(message, ...)
+        @target.send(message, ...)
+      end
+
+      # Tell the target to execute the given message
+      def tell(message, ...)
+        @target.send(message, ...)
+      end
+    end
+  end
+end

data/lib/plumbing/valve/message.rb

@@ -0,0 +1,5 @@
+module Plumbing
+  module Valve
+    Message = Struct.new :message, :args, :params, :block, :result, :status
+  end
+end

data/lib/plumbing/valve.rb

@@ -0,0 +1,71 @@
+require_relative "valve/inline"
+
+module Plumbing
+  module Valve
+    def self.included base
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Create a new valve instance and build a proxy for it using the current mode
+      # @return [Plumbing::Valve::Base] the proxy for the valve instance
+      def start(*, **, &)
+        build_proxy_for(new(*, **, &))
+      end
+
+      # Define the queries that this valve can answer
+      # @param names [Array<Symbol>] the names of the queries
+      def query(*names) = queries.concat(names.map(&:to_sym))
+
+      # List the queries that this valve can answer
+      def queries = @queries ||= []
+
+      # Define the commands that this valve can execute
+      # @param names [Array<Symbol>] the names of the commands
+      def command(*names) = commands.concat(names.map(&:to_sym))
+
+      # List the commands that this valve can execute
+      def commands = @commands ||= []
+
+      def inherited subclass
+        subclass.commands.concat commands
+        subclass.queries.concat queries
+      end
+
+      private
+
+      def build_proxy_for(target)
+        proxy_class_for(target.class).new(target)
+      end
+
+      def proxy_class_for target_class
+        Plumbing.config.valve_proxy_class_for(target_class) || register_valve_proxy_class_for(target_class)
+      end
+
+      def proxy_base_class = const_get "Plumbing::Valve::#{Plumbing.config.mode.to_s.capitalize}"
+
+      def register_valve_proxy_class_for target_class
+        Plumbing.config.register_valve_proxy_class_for(target_class, build_proxy_class)
+      end
+
+      def build_proxy_class
+        Class.new(proxy_base_class).tap do |proxy_class|
+          queries.each do |query|
+            proxy_class.define_method query do |*args, **params, &block|
+              ask(query, *args, **params, &block)
+            end
+          end
+
+          commands.each do |command|
+            proxy_class.define_method command do |*args, **params, &block|
+              tell(command, *args, **params, &block)
+              nil
+            rescue
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plumbing/version.rb

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

data/lib/plumbing.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
-require_relative "plumbing/version"
-
-require_relative "plumbing/error"
-require_relative "plumbing/event"
-require_relative "plumbing/pipe"
-require_relative "plumbing/filter"
-require_relative "plumbing/junction"
-require_relative "plumbing/pipeline"
-
 module Plumbing
+  require_relative "plumbing/config"
+  require_relative "plumbing/valve"
+  require_relative "plumbing/rubber_duck"
+  require_relative "plumbing/types"
+  require_relative "plumbing/error"
+  require_relative "plumbing/event"
+  require_relative "plumbing/pipe"
+  require_relative "plumbing/filter"
+  require_relative "plumbing/junction"
+  require_relative "plumbing/pipeline"
+  require_relative "plumbing/version"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-25 00:00:00.000000000 Z
+date: 2024-08-28 00:00:00.000000000 Z
 dependencies: []
 description: A composable event pipeline and sequential pipelines of operations
 email:
@@ -31,17 +31,27 @@ files:
 - checksums/standard-procedure-plumbing-0.1.2.gem.sha512
 - checksums/standard-procedure-plumbing-0.2.0.gem.sha512
 - checksums/standard-procedure-plumbing-0.2.1.gem.sha512
+- checksums/standard-procedure-plumbing-0.2.2.gem.sha512
+- checksums/standard-procedure-plumbing-0.3.0.gem.sha512
 - lib/plumbing.rb
+- lib/plumbing/config.rb
+- lib/plumbing/custom_filter.rb
 - lib/plumbing/error.rb
 - lib/plumbing/event.rb
-- lib/plumbing/event_dispatcher.rb
-- lib/plumbing/event_dispatcher/fiber.rb
 - lib/plumbing/filter.rb
 - lib/plumbing/junction.rb
 - lib/plumbing/pipe.rb
 - lib/plumbing/pipeline.rb
 - lib/plumbing/pipeline/contracts.rb
 - lib/plumbing/pipeline/operations.rb
+- lib/plumbing/rubber_duck.rb
+- lib/plumbing/rubber_duck/object.rb
+- lib/plumbing/rubber_duck/proxy.rb
+- lib/plumbing/types.rb
+- lib/plumbing/valve.rb
+- lib/plumbing/valve/async.rb
+- lib/plumbing/valve/inline.rb
+- lib/plumbing/valve/message.rb
 - lib/plumbing/version.rb
 - sig/plumbing.rbs
 homepage: https://github.com/standard-procedure/plumbing