standard-procedure-plumbing 0.2.2 → 0.3.1

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

@@ -0,0 +1 @@
+966c4bcf848d26272cf0b3bb3d74c9724aa9899a8bcbf5e25a6ce20608de1f529dc766056aa0cb99fbe1c7d6e16afe72acbcc0619fc14f57f01eb7921be7b653

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/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,20 +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)
+    # @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)
-      source.as(Observable).add_observer do |event|
-        filter_and_republish event
-      end
     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,9 +2,9 @@ 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
 

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.nil? ? EventDispatcher.new : dispatcher.as(DispatchesEvents)
-    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

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,6 +29,7 @@ module Plumbing
         operations << implementation
       end
 
+      # Internal use only
       def _call input, instance
         validate_contract_for input
         validate_preconditions_for input

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

@@ -1,6 +1,8 @@
 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

data/lib/plumbing/rubber_duck/proxy.rb

@@ -1,5 +1,6 @@
 module Plumbing
   class RubberDuck
+    # Proxy object that forwards the duck-typed methods to the target object
     class Proxy
       attr_reader :target
 
@@ -8,6 +9,8 @@ module Plumbing
         @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

data/lib/plumbing/rubber_duck.rb

@@ -9,16 +9,25 @@ module Plumbing
       @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

data/lib/plumbing/valve/async.rb

@@ -0,0 +1,43 @@
+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
+        nil
+      end
+
+      private
+
+      def timeout
+        Plumbing.config.timeout
+      end
+    end
+  end
+end

data/lib/plumbing/valve/inline.rb

@@ -0,0 +1,20 @@
+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, ...)
+        nil
+      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, ignore_result: false, **params, &block|
+              ignore_result ? tell(query, *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.2"
+  VERSION = "0.3.1"
 end

data/lib/plumbing.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Plumbing
+  require_relative "plumbing/config"
+  require_relative "plumbing/valve"
   require_relative "plumbing/rubber_duck"
   require_relative "plumbing/types"
   require_relative "plumbing/error"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.1
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-25 00:00:00.000000000 Z
+date: 2024-09-03 00:00:00.000000000 Z
 dependencies: []
 description: A composable event pipeline and sequential pipelines of operations
 email:
@@ -32,11 +32,13 @@ files:
 - 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
+- checksums/standard-procedure-plumbing-0.3.1.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
@@ -47,6 +49,10 @@ files:
 - 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

data/lib/plumbing/event_dispatcher/fiber.rb

@@ -1,61 +0,0 @@
-require "async/task"
-require "async/semaphore"
-
-module Plumbing
-  class EventDispatcher
-    class Fiber < EventDispatcher
-      def initialize limit: 4
-        super()
-        @semaphore = Async::Semaphore.new(limit)
-        @queue = Set.new
-        @paused = false
-      end
-
-      def dispatch event
-        @queue << event
-        dispatch_events unless @paused
-      end
-
-      def pause
-        @paused = true
-      end
-
-      def resume
-        @paused = false
-        dispatch_events
-      end
-
-      def queue_size
-        @queue.size
-      end
-
-      def shutdown
-        super
-        @queue.clear
-      end
-
-      private
-
-      def dispatch_events
-        @semaphore.async do |task|
-          events = @queue.dup
-          @queue.clear
-          events.each do |event|
-            dispatch_event event, task
-          end
-        end
-      end
-
-      def dispatch_event event, task
-        @observers.each do |observer|
-          task.async do
-            observer.call event
-          rescue => ex
-            puts ex
-            ex
-          end
-        end
-      end
-    end
-  end
-end

data/lib/plumbing/event_dispatcher.rb

@@ -1,34 +0,0 @@
-module Plumbing
-  class EventDispatcher
-    def initialize observers: []
-      @observers = observers.as(Collection)
-    end
-
-    def add_observer observer = nil, &block
-      observer ||= block.to_proc
-      @observers << observer.as(Callable).target
-      observer
-    end
-
-    def remove_observer observer
-      @observers.delete observer
-    end
-
-    def is_observer? observer
-      @observers.include? observer
-    end
-
-    def dispatch event
-      @observers.each do |observer|
-        observer.call event
-      rescue => ex
-        puts ex
-        ex
-      end
-    end
-
-    def shutdown
-      @observers = []
-    end
-  end
-end