standard-procedure-plumbing 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 245665ccd98b92e9b49ae532c7efb1edb155b895e6db935cee4de16d8039a96c
-  data.tar.gz: 0a2b802e5e09dbc6f08259f0812c03bdb869002d90e04d5186f2ee716081ae44
+  metadata.gz: 54681502a7df050136406e706c4fd6b9d9bffea81e44c151e969379e6803c532
+  data.tar.gz: ed03cbc9476d43822792fd6a4788b0c2e6c629545056063342f15c0861dc7dd0
 SHA512:
-  metadata.gz: 84678167d2319c1e6af1a502485351ec3cb5decc4a6313396a89503e0f04a52803062081eec15fafdf30b55b93ce5bf8cbd6109d4a4872feabeb78fd2d9c959a
-  data.tar.gz: 6a49385767a68aa48c44d110016312563b6517963fd7b338d3b6b0d2106b759d1dc22bd324bec573b3e2b4b1b57aa4dfbc2df19b6ce71e71ed0a51666e3bc3c0
+  metadata.gz: 1387fdd83a547157541f444ccf2dcb9465c261616f424dc530ef4c9c13dda52214c21c4d50c99eb825e4827268f4892d62a29d212af9be21bc5bd65dd83422a4
+  data.tar.gz: c0dcbde3271e4d34cd41d16bda9c488ee40bd838ac0f006fd46bd23eb2c0c1cc4ea18d86236de1d8e87f6b5b97fc5dc728bedbd5a3e354fa09886094866404c9

data/README.md

@@ -156,7 +156,12 @@ An [actor](https://en.wikipedia.org/wiki/Actor_model) defines the messages an ob
 
 [Plumbing::Valve](/lib/plumbing/valve.rb) ensures that all messages received are channelled into a concurrency-safe queue. This allows you to take an existing class and ensures that messages received via its public API are made concurrency-safe.  
 
-Include the Plumbing::Valve module into your class, define the messages the objects can respond to and set the `Plumbing` configuration to set the desired concurrency model.  Messages themselves are split into two categories: commands and queries.  Commands have no return value so when the message is sent, the caller does not block and execution continues immediately.  Queries return a value so the caller must block until the actor has returned a value.  
+Include the Plumbing::Valve module into your class, define the messages the objects can respond to and set the `Plumbing` configuration to set the desired concurrency model.  Messages themselves are split into two categories: commands and queries.  
+
+- Commands have no return value so when the message is sent, the caller does not block, the task is called asynchronously and the caller continues immediately
+- Queries return a value so the caller blocks until the actor has returned a value
+- However, if you call a query and pass `ignore_result: true` then the query will not block, although you will not be able to access the return value - this is for commands that do something and then return a result based on that work (which you may or may not be interested in - see Plumbing::Pipe#add_observer)
+- None of the above applies if the `Plumbing mode` is set to `:inline` (which is the default) - in this case, the actor behaves like normal ruby code
 
 Instead of constructing your object with `.new`, use `.start`.  This builds a proxy object that wraps the target instance and dispatches messages through a safe mechanism.  Only messages that have been defined as part of the valve are available in this proxy - so you don't have to worry about callers bypassing the valve's internal context.  
 
@@ -175,7 +180,7 @@ Also be aware that if you use valves in one place, you need to use them everywhe
     attr_reader :name, :job_title
 
     include Plumbing::Valve
-    query :name, :job_title
+    query :name, :job_title, :greet_slowly
     command :promote
 
     def initialize(name)
@@ -187,6 +192,11 @@ Also be aware that if you use valves in one place, you need to use them everywhe
       sleep 0.5
       @job_title = "Sales manager"
     end
+
+    def greet_slowly 
+      sleep 0.2
+      "H E L L O"
+    end
   end
 ```
 
@@ -206,6 +216,12 @@ Also be aware that if you use valves in one place, you need to use them everywhe
   # this will block for 0.5 seconds
   puts @person.job_title
   # => "Sales manager"
+
+  @person.greet_slowly 
+  # this will block for 0.2 seconds before returning "H E L L O"
+
+  @person.greet_slowly(ignore_result: true)
+  # this will block for 0.2 seconds (as the mode is :inline) before returning nil
 ```
 
 [Using fibers](/spec/examples/valve_spec.rb) with concurrency but no parallelism
@@ -226,6 +242,12 @@ Also be aware that if you use valves in one place, you need to use them everywhe
   # this will return immediately without blocking
   puts @person.job_title
   # => "Sales manager" (this will block for 0.5s because #job_title query will not start until the #promote command has completed)
+
+  @person.greet_slowly 
+  # this will block for 0.2 seconds before returning "H E L L O"
+
+  @person.greet_slowly(ignore_result: true)
+  # this will not block and returns nil
 ```
 
 ## Plumbing::Pipe - a composable observer

data/lib/plumbing/valve/async.rb

@@ -30,6 +30,7 @@ module Plumbing
         rescue
           nil
         end
+        nil
       end
 
       private

data/lib/plumbing/valve/inline.rb

@@ -13,6 +13,7 @@ module Plumbing
       # Tell the target to execute the given message
       def tell(message, ...)
         @target.send(message, ...)
+        nil
       end
     end
   end

data/lib/plumbing/valve.rb

@@ -51,8 +51,8 @@ module Plumbing
       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)
+            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
 

data/lib/plumbing/version.rb

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

data/spec/become_equal_to_matcher.rb

@@ -0,0 +1,25 @@
+require "rspec/expectations"
+
+# Custom matcher that repeatedly evaluates the block until it matches the expected value or 5 seconds have elapsed
+#
+# This allows asynchronous operations to be tested in a synchronous manner with a timeout
+#
+# Example:
+#     expect("Hello").to become_equal_to { subject.greeting }
+#
+RSpec::Matchers.define :become_equal_to do
+  match do |expected|
+    counter = 0
+    matched = false
+    while (counter < 50) && (matched == false)
+      matched = true if (@result = block_arg.call) == expected
+      sleep 0.1
+      counter += 1
+    end
+    matched
+  end
+
+  failure_message do |expected|
+    "expected block to return #{expected} but was #{@result} after timeout expired"
+  end
+end

data/spec/examples/pipe_spec.rb

@@ -0,0 +1,109 @@
+require "spec_helper"
+require "async"
+
+RSpec.describe "Pipe examples" do
+  it "observes events" do
+    @source = Plumbing::Pipe.start
+
+    @result = []
+    @observer = @source.add_observer do |event|
+      @result << event.type
+    end
+
+    @source.notify "something_happened", message: "But what was it?"
+    expect(@result).to eq ["something_happened"]
+  end
+
+  it "filters events" do
+    @source = Plumbing::Pipe.start
+
+    @filter = Plumbing::Filter.start source: @source do |event|
+      %w[important urgent].include? event.type
+    end
+
+    @result = []
+    @observer = @filter.add_observer do |event|
+      @result << event.type
+    end
+
+    @source.notify "important", message: "ALERT! ALERT!"
+    expect(@result).to eq ["important"]
+
+    @source.notify "unimportant", message: "Nothing to see here"
+    expect(@result).to eq ["important"]
+  end
+
+  it "allows for custom filters" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class EveryThirdEvent < Plumbing::CustomFilter
+      def initialize source:
+        super
+        @events = []
+      end
+
+      def received event
+        @events << event
+        if @events.count >= 3
+          @events.clear
+          self << event
+        end
+      end
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    @source = Plumbing::Pipe.start
+    @filter = EveryThirdEvent.new(source: @source)
+
+    @result = []
+    @observer = @filter.add_observer do |event|
+      @result << event.type
+    end
+
+    1.upto 10 do |i|
+      @source.notify i.to_s
+    end
+
+    expect(@result).to eq ["3", "6", "9"]
+  end
+
+  it "joins multiple source pipes" do
+    @first_source = Plumbing::Pipe.start
+    @second_source = Plumbing::Pipe.start
+
+    @junction = Plumbing::Junction.start @first_source, @second_source
+
+    @result = []
+    @observer = @junction.add_observer do |event|
+      @result << event.type
+    end
+
+    @first_source.notify "one"
+    expect(@result).to eq ["one"]
+    @second_source.notify "two"
+    expect(@result).to eq ["one", "two"]
+  end
+
+  it "dispatches events asynchronously using fibers" do
+    Plumbing.configure mode: :async do
+      Sync do
+        @first_source = Plumbing::Pipe.start
+        @second_source = Plumbing::Pipe.start
+        @junction = Plumbing::Junction.start @first_source, @second_source
+        @filter = Plumbing::Filter.start source: @junction do |event|
+          %w[one-one two-two].include? event.type
+        end
+        @result = []
+        @filter.add_observer do |event|
+          @result << event.type
+        end
+
+        @first_source.notify "one-one"
+        @first_source.notify "one-two"
+        @second_source.notify "two-one"
+        @second_source.notify "two-two"
+
+        expect(["one-one", "two-two"]).to become_equal_to { @result }
+      end
+    end
+  end
+end

data/spec/examples/pipeline_spec.rb

@@ -0,0 +1,89 @@
+require "spec_helper"
+require "dry/validation"
+
+RSpec.describe "Pipeline examples" do
+  it "builds a simple pipeline of operations adding to an array with pre-conditions and post-conditions" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class BuildArray < Plumbing::Pipeline
+      perform :add_first
+      perform :add_second
+      perform :add_third
+
+      pre_condition :must_be_an_array do |input|
+        input.is_a? Array
+      end
+
+      post_condition :must_have_three_elements do |output|
+        output.length == 3
+      end
+
+      private
+
+      def add_first(input) = input << "first"
+
+      def add_second(input) = input << "second"
+
+      def add_third(input) = input << "third"
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    expect(BuildArray.new.call([])).to eq ["first", "second", "third"]
+    expect { BuildArray.new.call(1) }.to raise_error(Plumbing::PreConditionError)
+    expect { BuildArray.new.call(["extra element"]) }.to raise_error(Plumbing::PostConditionError)
+  end
+
+  it "builds a simple pipeline of operations using an external class to implement one of the steps" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class ExternalStep < Plumbing::Pipeline
+      perform :add_item_to_array
+
+      private
+
+      def add_item_to_array(input) = input << "external"
+    end
+
+    class BuildSequenceWithExternalStep < Plumbing::Pipeline
+      perform :add_first
+      perform :add_second, using: "ExternalStep"
+      perform :add_third
+
+      private
+
+      def add_first(input) = input << "first"
+
+      def add_third(input) = input << "third"
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    expect(BuildSequenceWithExternalStep.new.call([])).to eq ["first", "external", "third"]
+  end
+
+  it "uses a dry-validation contract to test the input parameters" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class SayHello < Plumbing::Pipeline
+      validate_with "SayHello::Input"
+      perform :say_hello
+
+      private
+
+      def say_hello input
+        "Hello #{input[:name]} - I will now send a load of annoying marketing messages to #{input[:email]}"
+      end
+
+      class Input < Dry::Validation::Contract
+        params do
+          required(:name).filled(:string)
+          required(:email).filled(:string)
+        end
+        rule :email do
+          key.failure("must be a valid email") unless /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i.match? value
+        end
+      end
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    SayHello.new.call(name: "Alice", email: "alice@example.com")
+
+    expect { SayHello.new.call(some: "other data") }.to raise_error(Plumbing::PreConditionError)
+  end
+end

data/spec/examples/rubber_duck_spec.rb

@@ -0,0 +1,26 @@
+require "spec_helper"
+
+RSpec.describe "Rubber Duck examples" do
+  it "casts objects as duck types" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    Person = Plumbing::RubberDuck.define :first_name, :last_name, :email
+    LikesFood = Plumbing::RubberDuck.define :favourite_food
+
+    PersonData = Struct.new(:first_name, :last_name, :email, :favourite_food)
+    CarData = Struct.new(:make, :model, :colour)
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    @porsche_911 = CarData.new "Porsche", "911", "black"
+    expect { @porsche_911.as Person }.to raise_error(TypeError)
+
+    @alice = PersonData.new "Alice", "Aardvark", "alice@example.com", "Ice cream"
+
+    @person = @alice.as Person
+    expect(@person.first_name).to eq "Alice"
+    expect(@person.email).to eq "alice@example.com"
+    expect { @person.favourite_food }.to raise_error(NoMethodError)
+
+    @hungry = @person.as LikesFood
+    expect(@hungry.favourite_food).to eq "Ice cream"
+  end
+end

data/spec/examples/valve_spec.rb

@@ -0,0 +1,88 @@
+require "spec_helper"
+
+RSpec.describe "Valve examples" do
+  # standard:disable Lint/ConstantDefinitionInBlock
+  class Employee
+    include Plumbing::Valve
+    query :name, :job_title, :greet_slowly
+    command :promote
+
+    def initialize(name)
+      @name = name
+      @job_title = "Sales assistant"
+    end
+
+    attr_reader :name, :job_title
+
+    def promote
+      sleep 0.5
+      @job_title = "Sales manager"
+    end
+
+    def greet_slowly
+      sleep 0.2
+      "H E L L O"
+    end
+  end
+  # standard:enable Lint/ConstantDefinitionInBlock
+
+  context "inline" do
+    it "queries an object" do
+      Plumbing.configure mode: :inline do
+        @person = Employee.start "Alice"
+
+        expect(@person.name).to eq "Alice"
+        expect(@person.job_title).to eq "Sales assistant"
+
+        @time = Time.now
+        expect(@person.greet_slowly).to eq "H E L L O"
+        expect(Time.now - @time).to be > 0.1
+
+        @time = Time.now
+        expect(@person.greet_slowly(ignore_result: true)).to be_nil
+        expect(Time.now - @time).to be > 0.1
+      end
+    end
+
+    it "commands an object" do
+      Plumbing.configure mode: :inline do
+        @person = Employee.start "Alice"
+
+        @person.promote
+
+        expect(@person.job_title).to eq "Sales manager"
+      end
+    end
+  end
+
+  context "async" do
+    around :example do |example|
+      Plumbing.configure mode: :async do
+        Kernel::Async(&example)
+      end
+    end
+
+    it "queries an object" do
+      @person = Employee.start "Alice"
+
+      expect(@person.name).to eq "Alice"
+      expect(@person.job_title).to eq "Sales assistant"
+
+      @time = Time.now
+      expect(@person.greet_slowly).to eq "H E L L O"
+      expect(Time.now - @time).to be > 0.1
+
+      @time = Time.now
+      expect(@person.greet_slowly(ignore_result: true)).to be_nil
+      expect(Time.now - @time).to be < 0.1
+    end
+
+    it "commands an object" do
+      @person = Employee.start "Alice"
+
+      @person.promote
+
+      expect(@person.job_title).to eq "Sales manager"
+    end
+  end
+end

data/spec/plumbing/a_pipe.rb

@@ -0,0 +1,106 @@
+RSpec.shared_examples "a pipe" do
+  it "adds a block observer" do
+    @pipe = described_class.start
+    @observer = @pipe.add_observer do |event|
+      puts event.type
+    end
+    expect(@pipe.is_observer?(@observer)).to eq true
+  end
+
+  it "adds a callable observer" do
+    @pipe = described_class.start
+    @proc = ->(event) { puts event.type }
+
+    @pipe.add_observer @proc
+
+    expect(@pipe.is_observer?(@proc)).to eq true
+  end
+
+  it "does not allow an observer without a #call method" do
+    @pipe = described_class.start
+
+    expect { @pipe.add_observer(Object.new) }.to raise_error(TypeError)
+  end
+
+  it "removes an observer" do
+    @pipe = described_class.start
+    @proc = ->(event) { puts event.type }
+
+    @pipe.remove_observer @proc
+
+    expect(@pipe.is_observer?(@proc)).to eq false
+  end
+
+  it "does not send notifications for objects  which are not events" do
+    @pipe = described_class.start
+    @results = []
+    @observer = @pipe.add_observer do |event|
+      @results << event
+    end
+
+    @pipe << Object.new
+
+    sleep 0.5
+    expect(@results).to eq []
+  end
+
+  it "notifies block observers" do
+    @pipe = described_class.start
+    @results = []
+    @observer = @pipe.add_observer do |event|
+      @results << event
+    end
+
+    @first_event = Plumbing::Event.new type: "first_event", data: {test: "event"}
+    @second_event = Plumbing::Event.new type: "second_event", data: {test: "event"}
+
+    @pipe << @first_event
+    expect([@first_event]).to become_equal_to { @results }
+
+    @pipe << @second_event
+    expect([@first_event, @second_event]).to become_equal_to { @results }
+  end
+
+  it "notifies callable observers" do
+    @pipe = described_class.start
+    @results = []
+    @observer = ->(event) { @results << event }
+    @pipe.add_observer @observer
+
+    @first_event = Plumbing::Event.new type: "first_event", data: {test: "event"}
+    @second_event = Plumbing::Event.new type: "second_event", data: {test: "event"}
+
+    @pipe << @first_event
+    expect([@first_event]).to become_equal_to { @results }
+
+    @pipe << @second_event
+    expect([@first_event, @second_event]).to become_equal_to { @results }
+  end
+
+  it "ensures all observers are notified even if an observer raises an exception" do
+    @pipe = described_class.start
+    @results = []
+    @failing_observer = @pipe.add_observer do |event|
+      raise "Failed processing #{event.type}"
+    end
+    @working_observer = @pipe.add_observer do |event|
+      @results << event
+    end
+
+    @event = Plumbing::Event.new type: "event", data: {test: "event"}
+
+    @pipe << @event
+
+    expect([@event]).to become_equal_to { @results }
+  end
+
+  it "shuts down the pipe" do
+    @pipe = described_class.start
+    @observer = ->(event) { @results << event }
+    @pipe.add_observer @observer
+
+    @pipe.shutdown
+
+    expect(@pipe.is_observer?(@observer)).to eq false
+  end
+end

data/spec/plumbing/custom_filter_spec.rb

@@ -0,0 +1,29 @@
+require "spec_helper"
+
+RSpec.describe Plumbing::CustomFilter do
+  it "raises a TypeError if it is connected to a non-Pipe" do
+    @invalid_source = Object.new
+
+    expect { described_class.start source: @invalid_source }.to raise_error(TypeError)
+  end
+
+  it "defines a custom filter" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    class ReversingFilter < Plumbing::CustomFilter
+      def received(event) = notify event.type.reverse, event.data
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+
+    @pipe = Plumbing::Pipe.start
+    @filter = ReversingFilter.new(source: @pipe)
+    @result = []
+    @filter.add_observer do |event|
+      @result << event.type
+    end
+
+    @pipe.notify "hello"
+    @pipe.notify "world"
+
+    expect(@result).to eq ["olleh", "dlrow"]
+  end
+end

data/spec/plumbing/filter_spec.rb

@@ -0,0 +1,32 @@
+require "spec_helper"
+
+RSpec.describe Plumbing::Filter do
+  it "raises a TypeError if it is connected to a non-Pipe" do
+    @invalid_source = Object.new
+
+    expect { described_class.start source: @invalid_source }.to raise_error(TypeError)
+  end
+
+  it "accepts event types" do
+    @pipe = Plumbing::Pipe.start
+
+    @filter = described_class.start source: @pipe do |event|
+      %w[first_type third_type].include? event.type.to_s
+    end
+
+    @results = []
+    @filter.add_observer do |event|
+      @results << event
+    end
+
+    @pipe << Plumbing::Event.new(type: "first_type", data: nil)
+    expect(@results.count).to eq 1
+
+    @pipe << Plumbing::Event.new(type: "second_type", data: nil)
+    expect(@results.count).to eq 1
+
+    # Use the alternative syntax
+    @pipe.notify "third_type"
+    expect(@results.count).to eq 2
+  end
+end

data/spec/plumbing/junction_spec.rb

@@ -0,0 +1,67 @@
+require "spec_helper"
+
+RSpec.describe Plumbing::Junction do
+  it "raises a TypeError if it is connected to a non-Pipe" do
+    @sources = [Plumbing::Pipe.start, Object.new, Plumbing::Pipe.start]
+
+    expect { described_class.start(*@sources) }.to raise_error(TypeError)
+  end
+
+  it "publishes events from a single source" do
+    @source = Plumbing::Pipe.start
+    @junction = described_class.start @source
+
+    @results = []
+    @junction.add_observer do |event|
+      @results << event
+    end
+
+    @event = Plumbing::Event.new type: "test_event", data: {test: "event"}
+    @source << @event
+
+    expect([@event]).to become_equal_to { @results }
+  end
+
+  it "publishes events from two sources" do
+    @first_source = Plumbing::Pipe.start
+    @second_source = Plumbing::Pipe.start
+    @junction = described_class.start @first_source, @second_source
+
+    @results = []
+    @junction.add_observer do |event|
+      @results << event
+    end
+
+    @first_event = Plumbing::Event.new type: "test_event", data: {test: "one"}
+    @first_source << @first_event
+    expect([@first_event]).to become_equal_to { @results }
+
+    @second_event = Plumbing::Event.new type: "test_event", data: {test: "two"}
+    @second_source << @second_event
+    expect([@first_event, @second_event]).to become_equal_to { @results }
+  end
+
+  it "publishes events from multiple sources" do
+    @first_source = Plumbing::Pipe.start
+    @second_source = Plumbing::Pipe.start
+    @third_source = Plumbing::Pipe.start
+    @junction = described_class.start @first_source, @second_source, @third_source
+
+    @results = []
+    @junction.add_observer do |event|
+      @results << event
+    end
+
+    @first_event = Plumbing::Event.new type: "test_event", data: {test: "one"}
+    @first_source << @first_event
+    expect([@first_event]).to become_equal_to { @results }
+
+    @second_event = Plumbing::Event.new type: "test_event", data: {test: "two"}
+    @second_source << @second_event
+    expect([@first_event, @second_event]).to become_equal_to { @results }
+
+    @third_event = Plumbing::Event.new type: "test_event", data: {test: "three"}
+    @third_source << @third_event
+    expect([@first_event, @second_event, @third_event]).to become_equal_to { @results }
+  end
+end