standard-procedure-plumbing 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 717c30b41fce6d982c4f3f9d5a0c8ac5abb8187e7bf03b13151fee49f42a3955
-  data.tar.gz: e0857d6739d95a5861a66871168a9be8154d1854a03fd59534f939b4be06896c
+  metadata.gz: 45b26855ceaf54673b25fe4ca63a5e52ab302f585f7653731f444b312dec233f
+  data.tar.gz: 936af082c395b80018878f9a53842505473f2d9978c97fafc88aea48102153e4
 SHA512:
-  metadata.gz: 9de7d23847f7776acb4c4c8d6585451d26a565e3c2982afdf6ebff45293d9977fc27ad79b9996eb192b5f80de713afae7cb725641682d21577beeac4ec76530a
-  data.tar.gz: eecd88c9eba77690548c56ce683aec310d76955bf3e9d0c85a2f9a7f700a5df7e43206647cbedc18e1cd73530141c881570ee9451787bdca0e5cb4f2e9db7e43
+  metadata.gz: 1cce27319493e32407381bb3623734a5bcd87bd1fa986c83f6d8790afb05376c144f994adfd5e094dd9377ad11ee6bdef3d2348ec279d9f378706d52da49362c
+  data.tar.gz: 6594ec35d9753979414b79c524a27d3c033bf96739ec750a0774c1cbb0d7b6dc97ec7e64245026f93f42c8083cce1da91fa772cbcecc61edecba7e931e085c10

data/.rubocop.yml

@@ -0,0 +1,24 @@
+# We want Exclude directives from different
+# config files to get merged, not overwritten
+inherit_mode:
+  merge:
+    - Exclude
+
+require:
+  # Standard's config uses custom cops,
+  # so it must be loaded along with custom Standard gems
+  - standard
+  - standard-custom
+  - standard-performance
+  # rubocop-performance is required when using Performance cops
+  - rubocop-performance
+
+inherit_gem:
+  standard: config/base.yml
+  standard-performance: config/base.yml
+  standard-custom: config/base.yml
+
+# Global options, like Ruby version
+AllCops:
+  SuggestExtensions: false
+  TargetRubyVersion: 3.2

data/.solargraph.yml

@@ -0,0 +1,32 @@
+---
+include:
+  - "**/*.rb"
+exclude:
+  - spec/**/*
+  - test/**/*
+  - vendor/**/*
+  - ".bundle/**/*"
+require:
+  - actioncable
+  - actionmailer
+  - actionpack
+  - actionview
+  - activejob
+  - activemodel
+  - activerecord
+  - activestorage
+  - activesupport  
+domains: []
+reporters:
+  - rubocop
+  - require_not_found
+formatter:
+  rubocop:
+    cops: safe
+    except: []
+    only: []
+    extra_args: []
+require_paths: []
+plugins:
+  - solargraph-rails
+max_files: 5000

data/.standard.yml

@@ -1,3 +1,9 @@
-# For available configuration options, see:
-#   https://github.com/standardrb/standard
-ruby_version: 3.0
+fix: true               
+parallel: true          
+format: progress        
+default_ignores: true
+
+ignore:           
+  - 'vendor/**/*'
+  - 'Gemfile.lock'
+

data/CHANGELOG.md

@@ -1,5 +1,11 @@
-## [Unreleased]
+## [0.1.1] - 2024-08-14
+
+- Tidied up the code
+- Added Plumbing::Chain
 
 ## [0.1.0] - 2024-04-13
 
 - Initial release
+
+## [Unreleased]
+

data/README.md

@@ -1,50 +1,165 @@
 # Plumbing
 
-Composable Observer
+## Plumbing::Pipe - a composable observer
 
 [Observers](https://ruby-doc.org/3.3.0/stdlibs/observer/Observable.html) in Ruby are a pattern where objects (observers) register their interest in another object (the observable).  This pattern is common throughout programming languages (event listeners in Javascript, the dependency protocol in [Smalltalk](https://en.wikipedia.org/wiki/Smalltalk)).
 
-Unlike ruby's in-built observers, this gem makes observers "composable".  Instead of simply registering for notifications from the observable, we observe a stream of notifications, which could be produced by multiple observables, all being sent through the same pipe.  We can then chain observers together, composing a "pipeline" of operations from a single source of events.
+[Plumbing::Pipe](lib/plumbing/pipe.rb) makes observers "composable".  Instead of simply registering for notifications from the observable, we observe a stream of notifications, which could be produced by multiple observables, all being sent through the same pipe.  We can then chain observers together, composing a "pipeline" of operations from a single source of events.
 
-For example, in a social-networking application, you may push all events associated with a user through a single pipe.  But one module within the application is only interested in follow requests, another module in comments.  So the "followers" module would attach a "filter pipe" to the "users" pipe, filtering out everything except follow requests.  Then the code within that module observes this "filter pipe" so only gets notified about follow requests.  And similarly, the "comments" module attaches a "filter pipe" to the "users" pipe, filtering out everything except "comments".
+### Usage
 
-However, the pipeline can do much more than simple filtering.
+A simple observer:
+```ruby
+require "plumbing"
 
-In a search engine application, it is important to keep a record of what has been searched for, but more importantly, which of those search results resulted in a click - as you can then use this data to improve your search results in future.  We could implement a chain of observers, from the pipe that records all search related events, a filter that looks at the events from a single user, to another observer that maintains a log of every search result for a given user from the last 30 minutes and then matches any clicks to those results - sending those matches to an analytics service.
+@source = Plumbing::Pipe.start
 
-The key fact is that each element in the chain of observers is only aware of the stream of events from the element just before it.  And when it outputs its own events, any observers to that stream are only aware of the element they have subscribed to.  This means that the chain works in a similar manner to unix pipes.
+@observer = @source.add_observer do |event|
+  puts event.type
+end
 
-In unix, you can use `cat logfile | grep -o "some text" | ec -l` to easily count the number of times "some text" occurs in your logfile.  Each individual command in that pipeline is extremely simple and optimised for its one task.  But piping them together gives you incredible flexibility and power.
+@source.notify "something_happened", message: "But what was it?"
+# => "something_happened"
+```
 
-The same is true when you compose a pipeline of observers, each of which watches the events in a stream.  You can attach observers which buffer the incoming events, so the receivers aren't swamped.  You can attach observers which manipulate the incoming data (see the inline emoji writer in the examples folder), or de-duplicate or merge events (which is very useful if you want to prevent flicker and unnecessary redraws in your user-interface).  And observers can republish events to different streams - we could take events on one stream and send those same events, or a subset, to a web-socket.
+Simple filtering:
+```ruby
+require "plumbing"
 
+@source = Plumbing::Pipe.start
 
-## Installation
-
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+@filter = Plumbing::Filter.start source: @source, accepts: %w[important urgent]
 
-Install the gem and add to the application's Gemfile by executing:
+@observer = @filter.add_observer do |event|
+  puts event.type
+end
 
-    $ bundle add standard-procedure-plumbing
+@source.notify "important", message: "ALERT! ALERT!"
+# => "important"
 
-## Usage
+@source.notify "unimportant", message: "Nothing to see here"
+# => <no output>
+```
 
-Create a pipe, chain pipes together, add observers and push events
+Custom filtering:
+```ruby
+require "plumbing"
 
-    require 'plumbing'
+class EveryThirdEvent < Plumbing::CustomFilter
+  def initialize source:
+    super source: source
+    @events = []
+  end
 
-    @pipe = Plumbing::Pipe.start
-    @filter = Plumbing::Filter.start source: @pipe, accepts: %w[important urgent]
-    @observer = @filter.add_observer do |event|
-      puts event.type
+  def received event
+    @events << event
+    # if we've already stored 2 events in the buffer then broadcast the newest event and clear the buffer
+    if @events.count >= 2
+      @events.clear
+      self << event
     end
+  end
+end
+
+@source = Plumbing::Pipe.start
+@filter = EveryThirdEvent.new(source: @source)
+
+@observer = @filter.add_observer do |event|
+  puts event.type
+end
+
+1.upto 10 do |i|
+  @source.notify i.to_s
+end
+# => "3"
+# => "6"
+# => "9"
+```
+
+Joining multiple sources
+```ruby
+require "plumbing"
+
+@first_source = Plumbing::Pipe.start
+@second_source = Plumbing::Pipe.start
+
+@join = Plumbing::Junction.start @first_source, @second_source
+
+@observer = @join.add_observer do |event|
+  puts event.type
+end
+
+@first_source.notify "one"
+# => "one"
+@second_source.notify "two"
+# => "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).  
+
+### Usage:
+
+```ruby
+require "plumbing"
+class BuildSequence < Plumbing::Chain 
+  pre_condition :must_be_an_array do |input| 
+    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
+    output.length == 3
+  end
+
+  perform :add_first
+  perform :add_second
+  perform :add_third
+
+  private 
+
+  def add_first input 
+    input << "first"
+  end
+
+  def add_second input 
+    input << "second" 
+  end
+
+  def add_third input 
+    input << "third"
+  end
+end
+
+BuildSequence.new.call []
+# => ["first", "second", "third"]
+
+BuildSequence.new.call 1
+# => Plumbing::PreconditionError("must_be_an_array")
+
+BuildSequence.new.call ["extra element"]
+# => Plumbing::PostconditionError("must_have_three_elements")
+```
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```sh
+bundle add standard-procedure-plumbing
+```
+
+Then:
 
-    @pipe << Event.new(type: "unimportant", data: { some: "data"})
-    # => no output
-    @pipe << Event.new(type: "important", data: { some: "data"})
-    # => "important"
+```ruby
+require 'plumbing'
+```
 
-    @filter.remove_observer @observer
 
 ## Development
 

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

@@ -0,0 +1 @@
+30cc1d4b434b322269e0100acd3a42088d93359e0d34b7a947ac272c55b2e82788ab6f0926f2cc95552d746b71791470412a7cdfa34605d4b20309df0de97a33

data/lib/plumbing/blocked_pipe.rb

@@ -0,0 +1,115 @@
+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/chain.rb

@@ -0,0 +1,59 @@
+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
+
+      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/concurrent/pipe.rb

@@ -0,0 +1,72 @@
+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

data/lib/plumbing/error.rb

@@ -0,0 +1,19 @@
+module Plumbing
+  # Base error class for all Plumbing errors
+  class Error < StandardError; end
+
+  # Error raised because a pre-condition failed
+  class PreConditionError < Error; end
+
+  # Error raised because a post-condition failed
+  class PostConditionError < Error; end
+
+  # Error raised because an invalid [Event] object was pushed into the pipe
+  InvalidEvent = Dry::Types::ConstraintError
+
+  # Error raised because an invalid observer was registered
+  InvalidObserver = Dry::Types::ConstraintError
+
+  # Error raised because a BlockedPipe was used instead of an actual implementation of a Pipe
+  class PipeIsBlocked < Plumbing::Error; end
+end

data/lib/plumbing/event.rb

@@ -2,15 +2,16 @@ 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
-      EventType = Strict::String
-      EventData = Strict::Hash.default({}.freeze)
+      Type = Strict::String
+      Data = Strict::Hash.map(Coercible::Symbol, Nominal::Any).default({}.freeze)
     end
 
-    attribute :type, Types::EventType
-    attribute :data, Types::EventData
+    attribute :type, Types::Type
+    attribute :data, Types::Data
   end
 end

data/lib/plumbing/filter.rb

@@ -1,14 +1,19 @@
 require "dry/types"
-require_relative "pipe"
+require_relative "blocked_pipe"
 
 module Plumbing
-  class Filter < Pipe
+  # A pipe that filters events from a source pipe
+  class Filter < BlockedPipe
     module Types
       include Dry::Types()
-      Source = Instance(Plumbing::Pipe)
-      EventTypes = Array.of(Plumbing::Event::Types::EventType)
+      Source = Instance(Plumbing::BlockedPipe)
+      EventTypes = Array.of(Plumbing::Event::Types::Type)
     end
 
+    # Chain this pipe to the source pipe
+    # @param source [Plumbing::BlockedPipe]
+    # @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]
@@ -23,7 +28,7 @@ module Plumbing
     def filter_and_republish event
       return nil if @accepted_event_types.any? && !@accepted_event_types.include?(event.type)
       return nil if @rejected_event_types.include? event.type
-      self << event
+      dispatch event
     end
   end
 end

data/lib/plumbing/pipe.rb

@@ -1,31 +1,12 @@
-require "dry/types"
-require_relative "event"
+require_relative "blocked_pipe"
 
 module Plumbing
-  InvalidEvent = Dry::Types::ConstraintError
-  InvalidObserver = Dry::Types::ConstraintError
-
-  class Pipe
-    module Types
-      include Dry::Types()
-      Event = Instance(Plumbing::Event)
-      Observer = Interface(:call)
-    end
-
+  # An implementation of a pipe that uses Fibers
+  class Pipe < BlockedPipe
     def initialize
-      @observers = []
-      @fiber = Fiber.new do |event|
-        loop do
-          break if event == :shutdown
-          @observers.each do |observer|
-            observer.call event
-          rescue
-            nil
-          end
-          event = Fiber.yield
-        end
-        # clean up and release any observers, just in case
-        @observers = []
+      super
+      @fiber = Fiber.new do |initial_event|
+        start_run_loop initial_event
       end
     end
 
@@ -33,23 +14,15 @@ module Plumbing
       @fiber.resume Types::Event[event]
     end
 
-    def add_observer callable = nil, &block
-      callable ||= block.to_proc
-      Types::Observer[callable].tap do |observer|
-        @observers << observer
-      end
-    end
-
-    def remove_observer callable
-      @observers.delete callable
-    end
-
     def shutdown
+      super
       @fiber.resume :shutdown
     end
 
-    def self.start(**params)
-      new(**params)
+    protected
+
+    def get_next_event
+      Fiber.yield
     end
   end
 end

data/lib/plumbing/version.rb

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

data/lib/plumbing.rb

@@ -2,10 +2,10 @@
 
 require "dry/types"
 module Plumbing
-  class Error < StandardError; end
-
   require_relative "plumbing/version"
 
+  require_relative "plumbing/error"
   require_relative "plumbing/event"
   require_relative "plumbing/pipe"
+  require_relative "plumbing/chain"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-14 00:00:00.000000000 Z
+date: 2024-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-types
@@ -46,6 +46,8 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
+- ".rubocop.yml"
+- ".solargraph.yml"
 - ".standard.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
@@ -53,8 +55,12 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- checksums/standard-procedure-plumbing-0.1.1.gem.sha512
 - lib/plumbing.rb
-- lib/plumbing/.DS_Store
+- lib/plumbing/blocked_pipe.rb
+- lib/plumbing/chain.rb
+- lib/plumbing/concurrent/pipe.rb
+- lib/plumbing/error.rb
 - lib/plumbing/event.rb
 - lib/plumbing/filter.rb
 - lib/plumbing/pipe.rb
@@ -82,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.6
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: An event pipeline