standard-procedure-plumbing 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54681502a7df050136406e706c4fd6b9d9bffea81e44c151e969379e6803c532
-  data.tar.gz: ed03cbc9476d43822792fd6a4788b0c2e6c629545056063342f15c0861dc7dd0
+  metadata.gz: ba7883be2c006839c549d70a37c96dced0cc0e38af1093676a3503bbbd9dcd95
+  data.tar.gz: 9ad82790ba2badcc614a795b559347b6413e810e35fe01db572f1a0f2ccbeb49
 SHA512:
-  metadata.gz: 1387fdd83a547157541f444ccf2dcb9465c261616f424dc530ef4c9c13dda52214c21c4d50c99eb825e4827268f4892d62a29d212af9be21bc5bd65dd83422a4
-  data.tar.gz: c0dcbde3271e4d34cd41d16bda9c488ee40bd838ac0f006fd46bd23eb2c0c1cc4ea18d86236de1d8e87f6b5b97fc5dc728bedbd5a3e354fa09886094866404c9
+  metadata.gz: 57f478c6b91598bdc88028ac99bceff692a34d620809ac71b3d89b24930794d8db5d9723b0cde844deaf3b9973bdda3c68ee7c77e1a8c9c824748b5278e5c606
+  data.tar.gz: 2dd95476896445746356141cbe5925490d9d7e4b96b9a60aefd0841b8b8851990d235c866bfb4073a8a0b5adb9588af1f88eff43988969ac1a5960ef091483ed

data/README.md

@@ -1,55 +1,59 @@
 # Plumbing
 
-## Configuration 
+## Configuration
 
-The most important configuration setting is the `mode`, which governs how messages are handled by Valves.   
+The most important configuration setting is the `mode`, which governs how messages are handled by Valves.
 
-By default it is `:inline`, so every command or query is handled synchronously.  
+By default it is `:inline`, so every command or query is handled synchronously.  This is the ruby behaviour you know and love.
 
-If it is set to `:async`, commands and queries will be handled using fibers (via the [Async gem](https://socketry.github.io/async/index.html)).
+If it is set to `:async`, commands and queries will be handled asynchronously using fibers (via the [Async gem](https://socketry.github.io/async/index.html)).  Your code should include the "async" gem in its bundle, as Plumbing does not load it by default.
 
-The `timeout` setting is used when performing queries - it defaults to 30s.  
+If it is set to `:threaded`, commands and queries will be handled asynchronously by a thread pool (via [Concurrent Ruby](https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent/Promises.html)), using the default `:io` executor.  Your code should include the "concurrent-ruby" gem in its bundle, as Plumbing does not load it by default.
+
+If you want to use threads in a Rails application, set the mode to `:rails`.  This ensures that the work is wrapped in the Rails executor (which prevents multi-threading issues in the framework).  At present, the `:io` executor may cause issues as we may exceed the number of database connections in the Rails' connection pool.  We will fix this at some point in the future.
+
+The `timeout` setting is used when performing queries - it defaults to 30s.
 
 ```ruby
   require "plumbing"
-  puts Plumbing.config.mode 
+  puts Plumbing.config.mode
   # => :inline
 
   Plumbing.configure mode: :async, timeout: 10
 
-  puts Plumbing.config.mode 
+  puts Plumbing.config.mode
   # => :async
 ```
 
-If you are running a test suite, you can temporarily update the configuration by passing a block.  
+If you are running a test suite, you can temporarily update the configuration by passing a block.
 
 ```ruby
   require "plumbing"
-  puts Plumbing.config.mode 
+  puts Plumbing.config.mode
   # => :inline
 
-  Plumbing.configure mode: :async do 
-    puts Plumbing.config.mode 
+  Plumbing.configure mode: :async do
+    puts Plumbing.config.mode
     # => :async
     first_test
     second_test
   end
 
-  puts Plumbing.config.mode 
+  puts Plumbing.config.mode
   # => :inline
 ```
 
 ## Plumbing::Pipeline - transform data through a pipeline
 
-Define a sequence of operations that proceed in order, passing their output from one operation as the input to another.  [Unix pipes](https://en.wikipedia.org/wiki/Pipeline_(Unix)) in Ruby.  
+Define a sequence of operations that proceed in order, passing their output from one operation as the input to another.  [Unix pipes](https://en.wikipedia.org/wiki/Pipeline_(Unix)) in Ruby.
 
-Use `perform` to define a step that takes some input and returns a different output.  
-  Specify `using` to re-use an existing `Plumbing::Pipeline` as a step within this pipeline.  
-Use `execute` to define a step that takes some input, performs an action but passes the input, unchanged, to the next step.  
+Use `perform` to define a step that takes some input and returns a different output.
+  Specify `using` to re-use an existing `Plumbing::Pipeline` as a step within this pipeline.
+Use `execute` to define a step that takes some input, performs an action but passes the input, unchanged, to the next step.
 
-If you have [dry-validation](https://dry-rb.org/gems/dry-validation/1.10/) installed, you can validate your input using a `Dry::Validation::Contract`.  Alternatively, you can define a `pre_condition` to test that the inputs are valid.  
+If you have [dry-validation](https://dry-rb.org/gems/dry-validation/1.10/) installed, you can validate your input using a `Dry::Validation::Contract`.  Alternatively, you can define a `pre_condition` to test that the inputs are valid.
 
-You can also verify that the output generated is as expected by defining a `post_condition`.  
+You can also verify that the output generated is as expected by defining a `post_condition`.
 
 ### Usage:
 
@@ -116,7 +120,7 @@ You can also verify that the output generated is as expected by defining a `post
   end
 
   SayHello.new.call(name: "Alice", email: "alice@example.com")
-  # => Hello Alice - I will now send a load of annoying marketing messages to alice@example.com 
+  # => Hello Alice - I will now send a load of annoying marketing messages to alice@example.com
 
   SayHello.new.call(some: "other data")
   # => Plumbing::PreConditionError
@@ -152,30 +156,30 @@ You can also verify that the output generated is as expected by defining a `post
 
 ## Plumbing::Valve - safe asynchronous objects
 
-An [actor](https://en.wikipedia.org/wiki/Actor_model) defines the messages an object can receive, similar to a regular object.  However, a normal object if accessed concurrently can have data consistency issues and race conditions leading to hard-to-reproduce bugs.  Actors, however, ensure that, no matter which thread (or fiber) is sending the message, the internal processing of the message (the method definition) is handled sequentially.  This means the internal state of an object is never accessed concurrently, eliminating those issues.  
+An [actor](https://en.wikipedia.org/wiki/Actor_model) defines the messages an object can receive, similar to a regular object.  However, a normal object if accessed concurrently can have data consistency issues and race conditions leading to hard-to-reproduce bugs.  Actors, however, ensure that, no matter which thread (or fiber) is sending the message, the internal processing of the message (the method definition) is handled sequentially.  This means the internal state of an object is never accessed concurrently, eliminating those issues.
 
-[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.  
+[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.  
+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.  
+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.
 
-Even when using actors, there is one condition where concurrency may cause issues.  If object A makes a query to object B which in turn makes a query back to object A, you will hit a deadlock.  This is because A is waiting on the response from B but B is now querying, and waiting for, A.  This does not apply to commands because they do not wait for a response.  However, when writing queries, be careful who you interact with - the configuration allows you to set a timeout (defaulting to 30s) in case this happens.  
+Even when using actors, there is one condition where concurrency may cause issues.  If object A makes a query to object B which in turn makes a query back to object A, you will hit a deadlock.  This is because A is waiting on the response from B but B is now querying, and waiting for, A.  This does not apply to commands because they do not wait for a response.  However, when writing queries, be careful who you interact with - the configuration allows you to set a timeout (defaulting to 30s) in case this happens.
 
-Also be aware that if you use valves in one place, you need to use them everywhere - especially if you're using threads or ractors (coming soon).  This is because as the valve sends messages to its collaborators, those calls will be made from within the valve's internal context.  If the collaborators are also valves, the subsequent messages will be handled correctly, if not, data consistency bugs could occur.  
+Also be aware that if you use valves in one place, you need to use them everywhere - especially if you're using threads or ractors (coming soon).  This is because as the valve sends messages to its collaborators, those calls will be made from within the valve's internal context.  If the collaborators are also valves, the subsequent messages will be handled correctly, if not, data consistency bugs could occur.
 
-### Usage 
+### Usage
 
 [Defining an actor](/spec/examples/valve_spec.rb)
 
 ```ruby
   require "plumbing"
-  
+
   class Employee
     attr_reader :name, :job_title
 
@@ -193,7 +197,7 @@ Also be aware that if you use valves in one place, you need to use them everywhe
       @job_title = "Sales manager"
     end
 
-    def greet_slowly 
+    def greet_slowly
       sleep 0.2
       "H E L L O"
     end
@@ -204,7 +208,7 @@ Also be aware that if you use valves in one place, you need to use them everywhe
 
 ```ruby
   require "plumbing"
-    
+
   @person = Employee.start "Alice"
 
   puts @person.name
@@ -217,7 +221,7 @@ Also be aware that if you use valves in one place, you need to use them everywhe
   puts @person.job_title
   # => "Sales manager"
 
-  @person.greet_slowly 
+  @person.greet_slowly
   # this will block for 0.2 seconds before returning "H E L L O"
 
   @person.greet_slowly(ignore_result: true)
@@ -230,7 +234,7 @@ Also be aware that if you use valves in one place, you need to use them everywhe
   require "plumbing"
   require "async"
 
-  Plumbing.configure mode: :async 
+  Plumbing.configure mode: :async
   @person = Employee.start "Alice"
 
   puts @person.name
@@ -243,20 +247,47 @@ Also be aware that if you use valves in one place, you need to use them everywhe
   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 
+  @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
 ```
 
+[Using threads](/spec/examples/valve_spec.rb) with concurrency and some parallelism
+
+```ruby
+  require "plumbing"
+  require "concurrent"
+
+  Plumbing.configure mode: :threaded
+  @person = Employee.start "Alice"
+
+  puts @person.name
+  # => "Alice"
+  puts @person.job_title
+  # => "Sales assistant"
+
+  @person.promote
+  # 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
 
 [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)).
 
-[Plumbing::Pipe](lib/plumbing/pipe.rb) makes observers "composable".  Instead of simply just registering for notifications from a single observable, we can build sequences of pipes.  These sequences can filter notifications and route them to different listeners, or merge multiple sources into a single stream of notifications.  
+[Plumbing::Pipe](lib/plumbing/pipe.rb) makes observers "composable".  Instead of simply just registering for notifications from a single observable, we can build sequences of pipes.  These sequences can filter notifications and route them to different listeners, or merge multiple sources into a single stream of notifications.
 
-Pipes are implemented as valves, meaning that event notifications can be dispatched asynchronously.  The observer's callback will be triggered from within the pipe's internal context so you should immediately trigger a command on another valve to maintain safety.  
+Pipes are implemented as valves, meaning that event notifications can be dispatched asynchronously.  The observer's callback will be triggered from within the pipe's internal context so you should immediately trigger a command on another valve to maintain safety.
 
 ### Usage
 
@@ -279,7 +310,7 @@ Pipes are implemented as valves, meaning that event notifications can be dispatc
 
   @source = Plumbing::Pipe.start
   @filter = Plumbing::Filter.start source: @source do |event|
-    %w[important urgent].include? event.type 
+    %w[important urgent].include? event.type
   end
   @observer = @filter.add_observer do |event|
     puts event.type
@@ -349,16 +380,16 @@ Pipes are implemented as valves, meaning that event notifications can be dispatc
   require "plumbing"
   require "async"
 
-  Plumbing.configure mode: :async 
+  Plumbing.configure mode: :async
 
-  Sync do 
-    @first_source = Plumbing::Pipe.start 
+  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 
+      %w[one-one two-two].include? event.type
     end
 
     @first_source.notify "one-one"
@@ -370,19 +401,20 @@ Pipes are implemented as valves, meaning that event notifications can be dispatc
 
 ## Plumbing::RubberDuck - duck types and type-casts
 
-Define an [interface or protocol](https://en.wikipedia.org/wiki/Interface_(object-oriented_programming)) specifying which messages you expect to be able to send.  Then cast an object into that type, which first tests that the object can respond to those messages and then builds a proxy that responds to just those messages and no others (so no-one can abuse the specific type-casting you have specified).  However, if you take one of these proxies, you can safely re-cast it as another type (as long as the original target object is castable).
+Define an [interface or protocol](https://en.wikipedia.org/wiki/Interface_(object-oriented_programming)) specifying which messages you expect to be able to send.
 
+Then cast an object into that type.  This first tests that the object can respond to those messages and then builds a proxy that responds to those messages (and no others).  However, if you take one of these proxies, you can safely re-cast it as another type (as long as the original target object responds to the correct messages).
 
-### Usage 
+### Usage
 
-Define your interface (Person in this example), then cast your objects (instances of PersonData and CarData).  
+Define your interface (Person in this example), then cast your objects (instances of PersonData and CarData).
 
 [Casting objects as duck-types](/spec/examples/rubber_duck_spec.rb):
 ```ruby
   require "plumbing"
 
-  Person = Plumbing::RubberDuck.define :first_name, :last_name, :email 
-  LikesFood = Plumbing::RubberDuck.define :favourite_food 
+  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)
@@ -395,17 +427,54 @@ Define your interface (Person in this example), then cast your objects (instance
   @person = @alice.as Person
   @person.first_name
   # => "Alice"
-  @person.email 
+  @person.email
   # => "alice@example.com"
   @person.favourite_food
   # => NoMethodError - #favourite_food is not part of the Person rubber duck (even though it is part of the underlying PersonData struct)
 
   # Cast our Person into a LikesFood rubber duck
-  @hungry = @person.as LikesFood 
-  @hungry.favourite_food 
+  @hungry = @person.as LikesFood
+  @hungry.favourite_food
   # => "Ice cream"
 ```
 
+You can also use the same `@object.as type` to type-check instances against modules or classes.  This creates a RubberDuck proxy based on the module or class you're casting into.  So the cast will pass if the object responds to the correct messages, even if a strict `.is_a?` test would fail.
+
+```ruby
+  require "plumbing"
+
+  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)
+
+  @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"
+
+  @alics.is_a? Person
+  # => false - PersonData does not `include Person`
+  @person = @alice.as Person
+  # This cast is OK because PersonData responds to :first_name, :last_name and :email
+  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"
+```
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -418,6 +487,9 @@ Then:
 
 ```ruby
 require 'plumbing'
+
+# Set the mode for your Valves and Pipes
+Plumbing.config mode: :async
 ```
 
 ## Development

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/valve/rails.rb

@@ -0,0 +1,15 @@
+require_relative "threaded"
+
+module Plumbing
+  module Valve
+    class Rails < Threaded
+      protected
+
+      def future(&)
+        Concurrent::Promises.future do
+          Rails.application.executor.wrap(&)
+        end
+      end
+    end
+  end
+end

data/lib/plumbing/valve/threaded.rb

@@ -0,0 +1,67 @@
+require "concurrent/array"
+require "concurrent/mvar"
+require "concurrent/immutable_struct"
+require "concurrent/promises"
+
+module Plumbing
+  module Valve
+    class Threaded
+      attr_reader :target
+
+      def initialize target
+        @target = target
+        @queue = Concurrent::Array.new
+      end
+
+      # Ask the target to answer the given message
+      def ask(message, *, **, &)
+        add_message_to_queue(message, *, **, &).value
+      end
+
+      # Tell the target to execute the given message
+      def tell(message, *, **, &)
+        add_message_to_queue(message, *, **, &)
+        nil
+      rescue
+        nil
+      end
+
+      protected
+
+      def future(&)
+        Concurrent::Promises.future(&)
+      end
+
+      private
+
+      def send_messages
+        future do
+          while (message = @queue.shift)
+            message.call
+          end
+        end
+      end
+
+      def add_message_to_queue message_name, *args, **params, &block
+        Message.new(@target, message_name, args, params, block, Concurrent::MVar.new).tap do |message|
+          @queue << message
+          send_messages if @queue.size == 1
+        end
+      end
+
+      class Message < Concurrent::ImmutableStruct.new(:target, :name, :args, :params, :block, :result)
+        def value
+          result.take(Plumbing.config.timeout).tap do |value|
+            raise value if value.is_a? Exception
+          end
+        end
+
+        def call
+          result.put target.send(name, *args, **params, &block)
+        rescue => ex
+          result.put ex
+        end
+      end
+    end
+  end
+end

data/lib/plumbing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Plumbing
-  VERSION = "0.3.2"
+  VERSION = "0.3.3"
 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/examples/valve_spec.rb

@@ -1,6 +1,33 @@
 require "spec_helper"
 
-RSpec.describe "Valve examples" do
+RSpec.shared_examples "an example valve" do |runs_in_background|
+  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
+    # `greet_slowly` is a query so will block until a response is received
+    expect(@person.greet_slowly).to eq "H E L L O"
+    expect(Time.now - @time).to be > 0.1
+
+    @time = Time.now
+    # we're ignoring the result so this will not block (except :inline mode which does not run in the background)
+    expect(@person.greet_slowly(ignore_result: true)).to be_nil
+    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 = @person.job_title
+    expect(@job_title).to eq "Sales manager"
+  end
+end
+
+RSpec.describe "Valve example: " do
   # standard:disable Lint/ConstantDefinitionInBlock
   class Employee
     include Plumbing::Valve
@@ -26,63 +53,29 @@ RSpec.describe "Valve examples" do
   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
+  context "inline mode" do
+    around :example do |example|
+      Plumbing.configure mode: :inline, &example
     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
+    it_behaves_like "an example valve", false
   end
 
-  context "async" do
+  context "async mode" 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
+    it_behaves_like "an example valve", true
+  end
 
-      @time = Time.now
-      expect(@person.greet_slowly(ignore_result: true)).to be_nil
-      expect(Time.now - @time).to be < 0.1
+  context "threaded mode" do
+    around :example do |example|
+      Plumbing.configure mode: :threaded, &example
     end
 
-    it "commands an object" do
-      @person = Employee.start "Alice"
-
-      @person.promote
-
-      expect(@person.job_title).to eq "Sales manager"
-    end
+    it_behaves_like "an example valve", true
   end
 end

data/spec/plumbing/pipe_spec.rb

@@ -20,4 +20,12 @@ RSpec.describe Plumbing::Pipe do
 
     it_behaves_like "a pipe"
   end
+
+  context "threaded" do
+    around :example do |example|
+      Plumbing.configure mode: :threaded, &example
+    end
+
+    it_behaves_like "a pipe"
+  end
 end

data/spec/plumbing/rubber_duck_spec.rb

@@ -5,72 +5,70 @@ RSpec.describe Plumbing::RubberDuck do
   class Duck
     def quack = "Quack"
 
-    def swim place
-      "Swim in #{place}"
-    end
+    def swim(place) = "Swim in #{place}"
 
-    def fly &block
-      "Fly #{block.call}"
-    end
+    def fly(&block) = "Fly #{block.call}"
   end
   # standard:enable Lint/ConstantDefinitionInBlock
 
-  it "verifies that an object matches the RubberDuck type" do
-    @duck_type = described_class.define :quack, :swim, :fly
-    @duck = Duck.new
+  context "defining rubber ducks" do
+    it "verifies that an object matches the RubberDuck type" do
+      @duck_type = described_class.define :quack, :swim, :fly
+      @duck = Duck.new
 
-    expect(@duck_type.verify(@duck)).to eq @duck
-  end
+      expect(@duck_type.verify(@duck)).to eq @duck
+    end
 
-  it "casts the object to a duck type" do
-    @duck_type = described_class.define :quack, :swim, :fly
-    @duck = Duck.new
+    it "casts the object to a duck type" do
+      @duck_type = described_class.define :quack, :swim, :fly
+      @duck = Duck.new
 
-    @proxy = @duck.as @duck_type
+      @proxy = @duck.as @duck_type
 
-    expect(@proxy).to be_kind_of Plumbing::RubberDuck::Proxy
-    expect(@proxy).to respond_to :quack
-    expect(@proxy.quack).to eq "Quack"
-    expect(@proxy).to respond_to :swim
-    expect(@proxy.swim("the river")).to eq "Swim in the river"
-    expect(@proxy).to respond_to :fly
-    expect(@proxy.fly { "ducky fly" }).to eq "Fly ducky fly"
-  end
+      expect(@proxy).to be_kind_of Plumbing::RubberDuck::Proxy
+      expect(@proxy).to respond_to :quack
+      expect(@proxy.quack).to eq "Quack"
+      expect(@proxy).to respond_to :swim
+      expect(@proxy.swim("the river")).to eq "Swim in the river"
+      expect(@proxy).to respond_to :fly
+      expect(@proxy.fly { "ducky fly" }).to eq "Fly ducky fly"
+    end
 
-  it "does not forward methods that are not part of the duck type" do
-    @duck_type = described_class.define :swim, :fly
-    @duck = Duck.new
+    it "does not forward methods that are not part of the duck type" do
+      @duck_type = described_class.define :swim, :fly
+      @duck = Duck.new
 
-    @proxy = @duck.as @duck_type
+      @proxy = @duck.as @duck_type
 
-    expect(@proxy).to_not respond_to :quack
-  end
+      expect(@proxy).to_not respond_to :quack
+    end
 
-  it "does not wrap rubber ducks in a proxy" do
-    @duck_type = described_class.define :swim, :fly
-    @duck = Duck.new
+    it "does not wrap rubber ducks in a proxy" do
+      @duck_type = described_class.define :swim, :fly
+      @duck = Duck.new
 
-    @proxy = @duck.as @duck_type
+      @proxy = @duck.as @duck_type
 
-    expect(@proxy.as(@duck_type)).to eq @proxy
-  end
+      expect(@proxy.as(@duck_type)).to eq @proxy
+    end
 
-  it "allows rubber ducks to be expanded and cast to other types" do
-    @quackers = described_class.define :quack
-    @swimming_bird = described_class.define :swim, :fly
-    @duck = Duck.new
+    it "allows rubber ducks to be expanded and cast to other types" do
+      @quackers = described_class.define :quack
+      @swimming_bird = described_class.define :swim, :fly
+      @duck = Duck.new
 
-    @swimmer = @duck.as @swimming_bird
-    @quacker = @swimmer.as @quackers
+      @swimmer = @duck.as @swimming_bird
+      @quacker = @swimmer.as @quackers
 
-    expect(@swimmer).to respond_to :swim
-    expect(@quacker).to respond_to :quack
-  end
+      expect(@swimmer).to respond_to :swim
+      expect(@quacker).to respond_to :quack
+    end
 
-  it "raises a TypeError if the class responds to the given methods" do
-    cow_type = described_class.define :moo, :chew
-    duck = Duck.new
+    it "raises a TypeError if the object does not respond to the given methods" do
+      @cow_type = described_class.define :moo, :chew
+      @duck = Duck.new
 
-    expect { cow_type.verify(duck) }.to raise_error(TypeError)
+      expect { @cow_type.verify(@duck) }.to raise_error(TypeError)
+    end
   end
 end

data/spec/plumbing/valve_spec.rb

@@ -1,6 +1,8 @@
 require "spec_helper"
-require "async"
+
 require_relative "../../lib/plumbing/valve/async"
+require_relative "../../lib/plumbing/valve/threaded"
+require_relative "../../lib/plumbing/valve/rails"
 
 RSpec.describe Plumbing::Valve do
   # standard:disable Lint/ConstantDefinitionInBlock
@@ -124,44 +126,46 @@ RSpec.describe Plumbing::Valve do
     end
   end
 
-  context "async" do
-    around :example do |example|
-      Sync do
-        Plumbing.configure mode: :async, &example
+  [:threaded, :async].each do |mode|
+    context mode.to_s do
+      around :example do |example|
+        Sync do
+          Plumbing.configure mode: mode, &example
+        end
       end
-    end
 
-    it "sends all queries using fibers and waits for the response" do
-      @counter = Counter.start "async counter", initial_value: 100
-      @time = Time.now
+      it "performs queries in the background and waits for the response" do
+        @counter = Counter.start "async counter", initial_value: 100
+        @time = Time.now
 
-      expect(@counter.name).to eq "async counter"
-      expect(@counter.count).to eq 100
-      expect(Time.now - @time).to be < 0.1
+        expect(@counter.name).to eq "async counter"
+        expect(@counter.count).to eq 100
+        expect(Time.now - @time).to be < 0.1
 
-      expect(@counter.slow_query).to eq 100
-      expect(Time.now - @time).to be > 0.4
-    end
+        expect(@counter.slow_query).to eq 100
+        expect(Time.now - @time).to be > 0.4
+      end
 
-    it "ignores the response from a query and returns immediately" do
-      @counter = Counter.start "async counter", initial_value: 100
-      @time = Time.now
+      it "performs queries ignoring the response and returning immediately" do
+        @counter = Counter.start "threaded counter", initial_value: 100
+        @time = Time.now
 
-      expect(@counter.slow_query(ignore_result: true)).to be_nil
+        expect(@counter.slow_query(ignore_result: true)).to be_nil
 
-      expect(Time.now - @time).to be < 0.1
-    end
+        expect(Time.now - @time).to be < 0.1
+      end
 
-    it "sends all commands using fibers without waiting for the response" do
-      @counter = Counter.start "async counter", initial_value: 100
-      @time = Time.now
+      it "performs commands in the background and returning immediately" do
+        @counter = Counter.start "threaded counter", initial_value: 100
+        @time = Time.now
 
-      @counter.slowly_increment
-      expect(Time.now - @time).to be < 0.1
+        @counter.slowly_increment
+        expect(Time.now - @time).to be < 0.1
 
-      # wait for the async task to complete
-      expect(@counter.count).to become_equal_to { 101 }
-      expect(Time.now - @time).to be > 0.4
+        # wait for the threaded task to complete
+        expect(101).to become_equal_to { @counter.count }
+        expect(Time.now - @time).to be > 0.4
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: standard-procedure-plumbing
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Rahoul Baruah
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-13 00:00:00.000000000 Z
+date: 2024-09-14 00:00:00.000000000 Z
 dependencies: []
 description: A composable event pipeline and sequential pipelines of operations
 email:
@@ -31,6 +31,7 @@ files:
 - lib/plumbing/pipeline/contracts.rb
 - lib/plumbing/pipeline/operations.rb
 - lib/plumbing/rubber_duck.rb
+- lib/plumbing/rubber_duck/module.rb
 - lib/plumbing/rubber_duck/object.rb
 - lib/plumbing/rubber_duck/proxy.rb
 - lib/plumbing/types.rb
@@ -38,6 +39,8 @@ files:
 - lib/plumbing/valve/async.rb
 - lib/plumbing/valve/inline.rb
 - lib/plumbing/valve/message.rb
+- lib/plumbing/valve/rails.rb
+- lib/plumbing/valve/threaded.rb
 - lib/plumbing/version.rb
 - spec/become_equal_to_matcher.rb
 - spec/examples/pipe_spec.rb
@@ -76,7 +79,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
+rubygems_version: 3.5.12
 signing_key:
 specification_version: 4
 summary: Plumbing - various pipelines for your ruby application