standard-procedure-plumbing 0.3.2 → 0.4.0

data/lib/plumbing/actor.rb

@@ -0,0 +1,63 @@
+require_relative "actor/kernel"
+require_relative "actor/inline"
+
+module Plumbing
+  module Actor
+    def self.included base
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      # Create a new actor instance and build a proxy for it using the current mode
+      # @return [Object] the proxy for the actor instance
+      def start(*, **, &)
+        build_proxy_for(new(*, **, &))
+      end
+
+      # Define the async messages that this actor can respond to
+      # @param names [Array<Symbol>] the names of the async messages
+      def async(*names) = async_messages.concat(names.map(&:to_sym))
+
+      # List the async messages that this actor can respond to
+      def async_messages = @async_messages ||= []
+
+      def inherited subclass
+        subclass.async_messages.concat async_messages
+      end
+
+      private
+
+      def build_proxy_for(target)
+        proxy_class_for(target.class).new(target)
+      end
+
+      def proxy_class_for target_class
+        Plumbing.config.actor_proxy_class_for(target_class) || register_actor_proxy_class_for(target_class)
+      end
+
+      def proxy_base_class = const_get PROXY_BASE_CLASSES[Plumbing.config.mode]
+
+      PROXY_BASE_CLASSES = {
+        inline: "Plumbing::Actor::Inline",
+        async: "Plumbing::Actor::Async",
+        threaded: "Plumbing::Actor::Threaded",
+        rails: "Plumbing::Actor::Rails"
+      }.freeze
+      private_constant :PROXY_BASE_CLASSES
+
+      def register_actor_proxy_class_for target_class
+        Plumbing.config.register_actor_proxy_class_for(target_class, build_proxy_class)
+      end
+
+      def build_proxy_class
+        Class.new(proxy_base_class).tap do |proxy_class|
+          async_messages.each do |message|
+            proxy_class.define_method message do |*args, &block|
+              send_message(message, *args, &block)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plumbing/config.rb

@@ -1,12 +1,12 @@
-# Pipes, pipelines, valves and rubber ducks
+# Pipes, pipelines, actors 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]
+  Config = Data.define :mode, :actor_proxy_classes, :timeout do
+    def actor_proxy_class_for target_class
+      actor_proxy_classes[target_class]
     end
 
-    def register_valve_proxy_class_for target_class, proxy_class
-      valve_proxy_classes[target_class] = proxy_class
+    def register_actor_proxy_class_for target_class, proxy_class
+      actor_proxy_classes[target_class] = proxy_class
     end
   end
   private_constant :Config
@@ -23,7 +23,7 @@ module Plumbing
   # @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: {}))
+    new_config = Config.new(**config.to_h.merge(params).merge(actor_proxy_classes: {}))
     if block.nil?
       set_configuration_to new_config
     else
@@ -45,7 +45,7 @@ module Plumbing
   private_class_method :set_configuration_and_yield
 
   def self.configs
-    @configs ||= [Config.new(mode: :inline, timeout: 30, valve_proxy_classes: {})]
+    @configs ||= [Config.new(mode: :inline, timeout: 30, actor_proxy_classes: {})]
   end
   private_class_method :configs
 end

data/lib/plumbing/pipe.rb

@@ -1,10 +1,9 @@
 module Plumbing
   # A basic pipe
   class Pipe
-    include Plumbing::Valve
+    include Plumbing::Actor
 
-    command :notify, :<<, :remove_observer, :shutdown
-    query :add_observer, :is_observer?
+    async :notify, :<<, :remove_observer, :add_observer, :is_observer?, :shutdown
 
     # Push an event into the pipe
     # @param event [Plumbing::Event] the event to push into the pipe

data/lib/plumbing/rubber_duck/module.rb

@@ -0,0 +1,13 @@
+module Plumbing
+  class RubberDuck
+    ::Module.class_eval do
+      def rubber_duck
+        @rubber_duck ||= Plumbing::RubberDuck.define(*instance_methods)
+      end
+
+      def proxy_for object
+        rubber_duck.proxy_for object
+      end
+    end
+  end
+end

data/lib/plumbing/rubber_duck/object.rb

@@ -2,9 +2,10 @@ module Plumbing
   class RubberDuck
     ::Object.class_eval do
       # Cast the object to a duck-type
+      # @param type [Plumbing::RubberDuck, Module]
       # @return [Plumbing::RubberDuck::Proxy] the duck-type proxy
-      def as duck_type
-        duck_type.proxy_for self
+      def as type
+        Plumbing::RubberDuck.cast self, type: type
       end
     end
   end

data/lib/plumbing/rubber_duck.rb

@@ -1,6 +1,7 @@
 module Plumbing
   # A type-checker for duck-types
   class RubberDuck
+    require_relative "rubber_duck/module"
     require_relative "rubber_duck/object"
     require_relative "rubber_duck/proxy"
 
@@ -26,10 +27,19 @@ module Plumbing
       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)
+    class << self
+      # Define a new rubber duck type
+      # @param *methods [Array<Symbol>] the methods that the duck-type should respond to
+      def define *methods
+        new(*methods)
+      end
+
+      # Cast the object to the given type
+      # @param object [Object] to be csat
+      # @param to [Module, Plumbing::RubberDuck] the type to cast into
+      def cast object, type:
+        type.proxy_for object
+      end
     end
 
     private

data/lib/plumbing/version.rb

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

data/lib/plumbing.rb

@@ -2,7 +2,7 @@
 
 module Plumbing
   require_relative "plumbing/config"
-  require_relative "plumbing/valve"
+  require_relative "plumbing/actor"
   require_relative "plumbing/rubber_duck"
   require_relative "plumbing/types"
   require_relative "plumbing/error"

data/spec/examples/actor_spec.rb

@@ -0,0 +1,81 @@
+require "spec_helper"
+
+RSpec.shared_examples "an example actor" do |runs_in_background|
+  it "queries an object" do
+    @person = Employee.start "Alice"
+
+    expect(await { @person.name }).to eq "Alice"
+    expect(await { @person.job_title }).to eq "Sales assistant"
+
+    @time = Time.now
+    # `greet_slowly` is a query so will block until a response is received
+    expect(await { @person.greet_slowly }).to eq "H E L L O"
+    expect(Time.now - @time).to be > 0.1
+
+    @time = Time.now
+    # we're not awaiting the result, so this should run in the background (unless we're using inline mode)
+    @person.greet_slowly
+
+    expect(Time.now - @time).to be < 0.1 if runs_in_background
+    expect(Time.now - @time).to be > 0.1 if !runs_in_background
+  end
+
+  it "commands an object" do
+    @person = Employee.start "Alice"
+    @person.promote
+    @job_title = await { @person.job_title }
+    expect(@job_title).to eq "Sales manager"
+  end
+end
+
+RSpec.describe "Actor example: " do
+  # standard:disable Lint/ConstantDefinitionInBlock
+  class Employee
+    include Plumbing::Actor
+    async :name, :job_title, :greet_slowly, :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 mode" do
+    around :example do |example|
+      Plumbing.configure mode: :inline, &example
+    end
+
+    it_behaves_like "an example actor", false
+  end
+
+  context "async mode" do
+    around :example do |example|
+      Plumbing.configure mode: :async do
+        Kernel::Async(&example)
+      end
+    end
+
+    it_behaves_like "an example actor", true
+  end
+
+  context "threaded mode" do
+    around :example do |example|
+      Plumbing.configure mode: :threaded, &example
+    end
+
+    it_behaves_like "an example actor", true
+  end
+end

data/spec/examples/pipe_spec.rb

@@ -6,7 +6,7 @@ RSpec.describe "Pipe examples" do
     @source = Plumbing::Pipe.start
 
     @result = []
-    @observer = @source.add_observer do |event|
+    @source.add_observer do |event|
       @result << event.type
     end
 
@@ -22,7 +22,7 @@ RSpec.describe "Pipe examples" do
     end
 
     @result = []
-    @observer = @filter.add_observer do |event|
+    @filter.add_observer do |event|
       @result << event.type
     end
 
@@ -55,7 +55,7 @@ RSpec.describe "Pipe examples" do
     @filter = EveryThirdEvent.new(source: @source)
 
     @result = []
-    @observer = @filter.add_observer do |event|
+    @filter.add_observer do |event|
       @result << event.type
     end
 
@@ -73,7 +73,7 @@ RSpec.describe "Pipe examples" do
     @junction = Plumbing::Junction.start @first_source, @second_source
 
     @result = []
-    @observer = @junction.add_observer do |event|
+    @junction.add_observer do |event|
       @result << event.type
     end
 

data/spec/examples/rubber_duck_spec.rb

@@ -1,26 +1,109 @@
 require "spec_helper"
 
 RSpec.describe "Rubber Duck examples" do
-  it "casts objects as duck types" do
+  it "casts objects into duck types" do
     # standard:disable Lint/ConstantDefinitionInBlock
-    Person = Plumbing::RubberDuck.define :first_name, :last_name, :email
-    LikesFood = Plumbing::RubberDuck.define :favourite_food
+    module DuckExample
+      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)
+    end
 
-    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)
+    @porsche_911 = DuckExample::CarData.new "Porsche", "911", "black"
+    expect { @porsche_911.as DuckExample::Person }.to raise_error(TypeError)
+
+    @alice = DuckExample::PersonData.new "Alice", "Aardvark", "alice@example.com", "Ice cream"
+
+    @person = @alice.as DuckExample::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 DuckExample::LikesFood
+    expect(@hungry.favourite_food).to eq "Ice cream"
+  end
+
+  it "casts objects into modules" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    module ModuleExample
+      module Person
+        def first_name = @first_name
+
+        def last_name = @last_name
+
+        def email = @email
+      end
+
+      module LikesFood
+        def favourite_food = @favourite_food
+      end
+
+      PersonData = Struct.new(:first_name, :last_name, :email, :favourite_food)
+      CarData = Struct.new(:make, :model, :colour)
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+    @porsche_911 = ModuleExample::CarData.new "Porsche", "911", "black"
+    expect { @porsche_911.as ModuleExample::Person }.to raise_error(TypeError)
+
+    @alice = ModuleExample::PersonData.new "Alice", "Aardvark", "alice@example.com", "Ice cream"
+
+    @person = @alice.as ModuleExample::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 ModuleExample::LikesFood
+    expect(@hungry.favourite_food).to eq "Ice cream"
+  end
+
+  it "casts objects into clases" do
+    # standard:disable Lint/ConstantDefinitionInBlock
+    module ClassExample
+      class Person
+        def initialize first_name, last_name, email
+          @first_name = first_name
+          @last_name = last_name
+          @email = email
+        end
+
+        attr_reader :first_name
+        attr_reader :last_name
+        attr_reader :email
+      end
+
+      class PersonWhoLikesFood < Person
+        def initialize first_name, last_name, email, favourite_food
+          super(first_name, last_name, email)
+          @favourite_food = favourite_food
+        end
+
+        attr_reader :favourite_food
+      end
+
+      class CarData
+        def initialize make, model, colour
+          @make = make
+          @model = model
+          @colour = colour
+        end
+      end
+    end
+    # standard:enable Lint/ConstantDefinitionInBlock
+    @porsche_911 = ClassExample::CarData.new "Porsche", "911", "black"
+    expect { @porsche_911.as ClassExample::Person }.to raise_error(TypeError)
 
-    @alice = PersonData.new "Alice", "Aardvark", "alice@example.com", "Ice cream"
+    @alice = ClassExample::PersonWhoLikesFood.new "Alice", "Aardvark", "alice@example.com", "Ice cream"
 
-    @person = @alice.as Person
+    @person = @alice.as ClassExample::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
+    @hungry = @person.as ClassExample::PersonWhoLikesFood
     expect(@hungry.favourite_food).to eq "Ice cream"
   end
 end

data/spec/plumbing/a_pipe.rb

@@ -1,10 +1,12 @@
 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
+    @observer = await do
+      @pipe.add_observer do |event|
+        puts event.type
+      end
     end
-    expect(@pipe.is_observer?(@observer)).to eq true
+    expect(await { @pipe.is_observer?(@observer) }).to eq true
   end
 
   it "adds a callable observer" do
@@ -13,13 +15,13 @@ RSpec.shared_examples "a pipe" do
 
     @pipe.add_observer @proc
 
-    expect(@pipe.is_observer?(@proc)).to eq true
+    expect(await { @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)
+    expect { await { @pipe.add_observer(Object.new) } }.to raise_error(TypeError)
   end
 
   it "removes an observer" do
@@ -28,10 +30,10 @@ RSpec.shared_examples "a pipe" do
 
     @pipe.remove_observer @proc
 
-    expect(@pipe.is_observer?(@proc)).to eq false
+    expect(await { @pipe.is_observer?(@proc) }).to eq false
   end
 
-  it "does not send notifications for objects  which are not events" do
+  it "does not send notifications for objects which are not events" do
     @pipe = described_class.start
     @results = []
     @observer = @pipe.add_observer do |event|
@@ -40,7 +42,7 @@ RSpec.shared_examples "a pipe" do
 
     @pipe << Object.new
 
-    sleep 0.5
+    sleep 0.1
     expect(@results).to eq []
   end
 
@@ -101,6 +103,6 @@ RSpec.shared_examples "a pipe" do
 
     @pipe.shutdown
 
-    expect(@pipe.is_observer?(@observer)).to eq false
+    expect(await { @pipe.is_observer?(@observer) }).to eq false
   end
 end

data/spec/plumbing/actor/transporter_spec.rb

@@ -0,0 +1,158 @@
+require "spec_helper"
+require_relative "../../../lib/plumbing/actor/transporter"
+
+RSpec.describe Plumbing::Actor::Transporter do
+  # standard:disable Lint/ConstantDefinitionInBlock
+  class Record
+    include GlobalID::Identification
+    attr_reader :id
+    def initialize id
+      @id = id
+    end
+
+    def == other
+      other.id == @id
+    end
+  end
+  # standard:enable Lint/ConstantDefinitionInBlock
+  before do
+    GlobalID.app = "rspec"
+    GlobalID::Locator.use :rspec do |gid, options|
+      Record.new gid.model_id
+    end
+  end
+
+  context "marshalling" do
+    it "passes simple arguments" do
+      @transporter = described_class.new
+
+      @transport = @transporter.marshal "Hello"
+      expect(@transport).to eq ["Hello"]
+
+      @transport = @transporter.marshal 1, 2, 3
+      expect(@transport).to eq [1, 2, 3]
+    end
+
+    it "copies arrays" do
+      @transporter = described_class.new
+
+      @source = [[1, 2, 3], [:this, :that]]
+
+      @transport = @transporter.marshal(*@source)
+      expect(@transport).to eq @source
+      expect(@transport.first.object_id).to_not eq @source.first.object_id
+      expect(@transport.last.object_id).to_not eq @source.last.object_id
+    end
+
+    it "copies hashss" do
+      @transporter = described_class.new
+
+      @source = [{first: "1", second: 2}]
+
+      @transport = @transporter.marshal(*@source)
+      expect(@transport).to eq @source
+      expect(@transport.first.object_id).to_not eq @source.first.object_id
+    end
+
+    it "converts objects to Global ID strings" do
+      @transporter = described_class.new
+
+      @record = Record.new 123
+      @global_id = @record.to_global_id.to_s
+
+      @transport = @transporter.marshal @record
+
+      expect(@transport).to eq [@global_id]
+    end
+
+    it "converts objects within arrays to Global ID strings" do
+      @transporter = described_class.new
+
+      @record = Record.new 123
+      @global_id = @record.to_global_id.to_s
+
+      @transport = @transporter.marshal [:this, @record]
+
+      expect(@transport).to eq [[:this, @global_id]]
+    end
+
+    it "converts objects within hashes to Global ID strings" do
+      @transporter = described_class.new
+
+      @record = Record.new 123
+      @global_id = @record.to_global_id.to_s
+
+      @transport = @transporter.marshal this: "that", the_other: {embedded: @record}
+
+      expect(@transport).to eq [{this: "that", the_other: {embedded: @global_id}}]
+    end
+  end
+
+  context "unmarshalling" do
+    it "passes simple arguments" do
+      @transporter = described_class.new
+
+      @transport = @transporter.unmarshal "Hello"
+      expect(@transport).to eq ["Hello"]
+
+      @transport = @transporter.unmarshal 1, 2, 3
+      expect(@transport).to eq [1, 2, 3]
+    end
+
+    it "passes arrays" do
+      @transporter = described_class.new
+
+      @transport = @transporter.unmarshal [1, 2, 3], [:this, :that]
+
+      expect(@transport.first.object_id).to_not eq [1, 2, 3]
+      expect(@transport.last.object_id).to_not eq [:this, :that]
+    end
+
+    it "passes hashss and keyword arguments" do
+      @transporter = described_class.new
+
+      @transport = @transporter.unmarshal first: "1", second: 2
+      expect(@transport).to eq [{first: "1", second: 2}]
+    end
+
+    it "passes mixtures of arrays and hashes" do
+      @transporter = described_class.new
+
+      @transport = @transporter.unmarshal :this, :that, first: "1", second: 2
+      expect(@transport).to eq [:this, :that, {first: "1", second: 2}]
+    end
+
+    it "converts Global ID strings to objects" do
+      @transporter = described_class.new
+
+      @record = Record.new "123"
+      @global_id = @record.to_global_id.to_s
+
+      @transport = @transporter.unmarshal @global_id
+
+      expect(@transport).to eq [@record]
+    end
+
+    it "converts Global ID strings within arrays to objects" do
+      @transporter = described_class.new
+
+      @record = Record.new "123"
+      @global_id = @record.to_global_id.to_s
+
+      @transport = @transporter.unmarshal :this, @global_id
+
+      expect(@transport).to eq [:this, @record]
+    end
+
+    it "converts Global ID strings within hashes to objects" do
+      @transporter = described_class.new
+
+      @record = Record.new "123"
+      @global_id = @record.to_global_id.to_s
+
+      @transport = @transporter.unmarshal this: "that", the_other: {embedded: @global_id}
+
+      expect(@transport).to eq [{this: "that", the_other: {embedded: @record}}]
+    end
+  end
+end