furnish 0.0.4 → 0.1.0

data/CHANGELOG.md

@@ -1,3 +1,39 @@
+* 0.1.0 (04/09/2013)
+  * Furnish requires 1.9.3 or greater -- always has been the case, now rubygems enforces that for us.
+  * Runtime performance increased significantly. No hard numbers, but test
+    suite assertion count doubled and total test runtime actually dropped
+    compared to 0.0.4. Yay.
+  * Furnish::Provisioner::API is the new way to write provisioners. Please read its documentation.
+    * Related, any existing provisioners will need significant changes to meet new changes.
+    * Provisioners now have programmed property and object construction
+      semantics, and the properties can now be queried, allowing for abstract
+      provisioning logic.
+  * Recovery mode: provisioners can opt-in to being able to recover from
+    transient failures. See Furnish::ProvisionerGroup#recover for more
+    information.
+    * Related, Threaded mode schedulers no longer stop when when a provision
+      fails. It instead marks Furnish::Scheduler#needs_recovery?
+    * Failed provisions still keep any dependencies from starting, but
+      independent provisions can still run.
+    * Serial mode schedulers still have the same behavior when
+      Furnish::Scheduler#run is called, but you can attempt to recover the
+      scheduler from where the run threw an exception.
+  * Furnish::Protocol is a way to specify what input and output provisioners
+    operate on. Static checking will occur at scheduling time to ensure a
+    provision can succeed (this is not a guarantee it will, just a way to
+    determine if it definitely won't).
+    * state transitions are now represented as hashes and merged over and
+      passed on. this means for provisioner group consisting of A -> B -> C,
+      that A can provide information that C can use without B knowing any
+      better. This is enforced by the static checking Furnish::Protocol
+      provides.
+    * shutdown provisioner state transitions can now carry data between them.
+  * Upgrade to palsy 0.0.4, which brings many consistency/durability/state
+    management benefits for persistent storage use.
+  * API shorthand for Furnish::Scheduler:
+    * `<<` is now an alias for `schedule_provisioner_group`
+    * `s` and `sched` are now aliases for `schedule_provision`
+  * Probably some other shit I don't remember now.
 * 0.0.4 (03/25/2013)
   * Support for FURNISH_DEBUG environment variable for test suites.
   * Ruby 2.0.0-p0 Compatibility Fixes

data/Gemfile

@@ -2,5 +2,3 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in furnish.gemspec
 gemspec
-
-gem 'guard-rake', :git => "https://github.com/erikh/guard-rake", :branch => "failure_ok"

data/Guardfile

@@ -2,9 +2,9 @@
 guard 'minitest' do
   # with Minitest::Unit
   watch(%r!^test/(.*)\/?test_(.*)\.rb!)
-  watch(%r!^test/(?:helper|mt_cases)\.rb!) { "test" }
+  watch(%r!^test/(?:helper|mt_cases|dummy_classes)\.rb!) { "test" }
 end
 
-guard 'rake', :failure_ok => true, :run_on_all => false, :task => 'rdoc_cov' do
+guard 'rake', :run_on_all => false, :task => 'rdoc_cov' do
   watch(%r!^lib/(.*)([^/]+)\.rb!)
 end

data/furnish.gemspec

@@ -16,13 +16,14 @@ Gem::Specification.new do |gem|
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
+  gem.required_ruby_version = '>= 1.9.3'
 
-  gem.add_dependency 'palsy', '~> 0.0.2'
+  gem.add_dependency 'palsy', '~> 0.0.4'
 
   gem.add_development_dependency 'rake'
   gem.add_development_dependency 'minitest', '~> 4.5.0'
   gem.add_development_dependency 'guard-minitest'
-  gem.add_development_dependency 'guard-rake'
+  gem.add_development_dependency 'guard-rake', '~> 0.0.8'
   gem.add_development_dependency 'rdoc', '~> 4'
   gem.add_development_dependency 'rb-fsevent'
   gem.add_development_dependency 'simplecov'

data/lib/furnish.rb

@@ -4,10 +4,8 @@ require 'furnish/logger'
 require 'furnish/scheduler'
 
 #
-# Furnish is a scheduling system that has a massive readme which explains what
-# it does here:
-#
-# https://github.com/erikh/furnish
+# Furnish is a scheduling system. Check out the README for basic usage
+# instructions.
 #
 # You may also wish to read the Furnish::Scheduler, Furnish::Logger, and
 # Furnish::ProvisionerGroup documentation to learn more about it.

data/lib/furnish/protocol.rb

@@ -0,0 +1,226 @@
+module Furnish # :nodoc:
+  #
+  # Furnish::Protocol implements a validating protocol for state transitions.
+  # It is an optional feature and not necessary for using Furnish.
+  #
+  # A Furnish::ProvisionerGroup looks like this:
+  #
+  # thing_a -> thing_b -> thing_c
+  #
+  # Where these things are furnish provisioners. When the scheduler says it's
+  # ready to provision this group, it executes thing_a's startup routine,
+  # passes its results to thing_b's startup routine, and then thing_b's startup
+  # routine passes its things to thing_c's startup routine.
+  #
+  # Presuming this all succeeds (and returns truthy values), the group is
+  # marked as 'solved', the scheduler considers it finished and will ignore
+  # future requests to provision it again. It also will start working on
+  # anything that depends on its solved state.
+  #
+  # A problem is that you have to know ahead of time how a, b, and c interact
+  # for this to be successful. For example, you can't allocate an EC2 security
+  # group, then an instance, then a VPC, and expect the security group and
+  # instance to live in that VPC. It's not only out of order, but the security
+  # group doesn't know enough at the time it runs to leverage the VPC, because
+  # the VPC doesn't exist yet.
+  #
+  # Furnish::Protocol lets you describe what each provisioner requires, what it
+  # accepts, and what it yields, so that analysis can be performed at scheduler
+  # time (when it's configured) instead of provisioning time (when it actually
+  # runs). This surfaces issues quicker and has some additional advantages for
+  # interfaces where users may not have full visibility into what the
+  # provisioners do (such as closed source provisioners, or inadequately
+  # documented ones).
+  #
+  # Here's a description of how this logic works for two adjacent provisioners
+  # in the group, a and b:
+  #
+  # * if Provisioner A and Provisioner B implement Furnish::Protocol
+  #   * if B requires anything, and A yields all of it with the proper types
+  #     * if B accepts anything, and A yields any of it with the proper types
+  #       * success
+  #     * else failure
+  #   * if B accepts anything, and A yields any of it with the proper types
+  #     * success
+  #   * if B has #accepts_from_any set to true
+  #     * success
+  #   * if B accepts nothing
+  #     * success
+  #   * else failure
+  # * else success
+  #
+  # Provisioners at the head and tail do not get subject to acceptance tests
+  # because there's nothing to yield, or nothing to accept what is yielded.
+  #
+  class Protocol
+
+    ##
+    # :method:
+    # :call-seq:
+    #   requires(name)
+    #   requires(name, description)
+    #   requires(name, description, type)
+    #
+    # Specifies a requirement. The name is the key of the requirement, the
+    # description is a text explanantion of what the requirement is used for,
+    # for informational purposes. The name and type (which is a class) are
+    # compared to #yields in #requires_from and the logic behind that is
+    # explained in Furnish::Protocol.
+    #
+    # See Furnish::Provisioner::API.configure_startup for a usage example.
+    #
+
+    ##
+    # :method:
+    # :call-seq:
+    #   accepts(name)
+    #   accepts(name, description)
+    #   accepts(name, description, type)
+    #
+    # Specifies acceptance critieria. While #requires is "all", this is "any",
+    # and acceptance is further predicated by the #accepts_from_any status if
+    # acceptance checks fail. The attributes set here will be used in
+    # #accepts_from to validate against another provisioner.
+    #
+    # See the logic explanation in Furnish::Protocol for more information.
+    #
+    # See Furnish::Provisioner::API.configure_startup for a usage example.
+    #
+
+    ##
+    # :method:
+    # :call-seq:
+    #   yields(name)
+    #   yields(name, description)
+    #   yields(name, description, type)
+    #
+    # Specifies what the provisioner is expected to yield. This is the producer
+    # for the consumer counterparts #requires and #accepts. The configuration
+    # made here will be used in both #requires_from and #accepts_from for
+    # determining if two provisioners can talk to each other.
+    #
+    # See the logic explanation in Furnish::Protocol for more information.
+    #
+    # See Furnish::Provisioner::API.configure_startup for a usage example.
+    #
+
+    VALIDATOR_NAMES = [:requires, :accepts, :yields] # :nodoc:
+
+    #
+    # Construct a Furnish::Protocol object.
+    #
+    def initialize
+      @hash = Hash[VALIDATOR_NAMES.map { |n| [n, { }] }]
+      @configuring = false
+    end
+
+    #
+    # This runs the block given instance evaled against the current
+    # Furnish::Protocol object. It is used by Furnish::Provisioner::API's
+    # syntax sugar.
+    #
+    # Additionally it sets a simple lock to ensure the assertions
+    # Furnish::Protocol provides cannot be used during configuration time, like
+    # #accept_from and #requires_from.
+    #
+    def configure(&block)
+      @configuring = true
+      instance_eval(&block)
+      @configuring = false
+    end
+
+    #
+    # Allow #accepts_from to completely mismatch with yields from a compared
+    # provisioner and still succeed. Use with caution.
+    #
+    # See the logic discussion in Furnish::Protocol for a deeper explanation.
+    #
+    def accepts_from_any(val)
+      @hash[:accepts_from_any] = val
+    end
+
+    #
+    # look up a rule set -- generally should not be used by consumers.
+    #
+    def [](key)
+      @hash[key]
+    end
+
+    #
+    # For a passed Furnish::Protocol object, ensures that this protocol object
+    # satisfies its requirements based on what it yields.
+    #
+    # See the logic discussion in Furnish::Protocol for a deeper explanation.
+    #
+    def requires_from(protocol)
+      not_configurable(__method__)
+
+      return true unless protocol
+
+      yp = protocol[:yields]
+      rp = self[:requires]
+
+      rp.keys.empty? ||
+        (
+          (yp.keys & rp.keys).sort == rp.keys.sort &&
+          rp.keys.all? { |k| rp[k][:type].ancestors.include?(yp[k][:type]) }
+        )
+    end
+
+    #
+    # For a passed Furnish::Protocol object, ensures that at least one thing
+    # this protocol object accepts is satisfied by what that Furnish::Protocol
+    # object yields.
+    #
+    # See the logic discussion in Furnish::Protocol for a deeper explanation.
+    #
+    def accepts_from(protocol)
+      not_configurable(__method__)
+
+      return true unless protocol
+
+      yp = protocol[:yields]
+      ap = self[:accepts]
+
+      return true if ap.keys.empty?
+
+      if (yp.keys & ap.keys).empty?
+        return self[:accepts_from_any]
+      end
+
+      return (yp.keys & ap.keys).all? { |k| ap[k][:type].ancestors.include?(yp[k][:type]) }
+    end
+
+    VALIDATOR_NAMES.each do |vname|
+      class_eval <<-EOF
+        def #{vname}(name, description='', type=Object)
+          name = name.to_sym unless name.kind_of?(Symbol)
+          build(#{vname.inspect}, name, description, type)
+        end
+      EOF
+    end
+
+    private
+
+    #
+    # Just a little "pragma" to ensure certain methods cannot be used in
+    # #configure.
+    #
+    def not_configurable(meth_name)
+      if @configuring
+        raise RuntimeError, "cannot use method '#{meth_name}' during protocol configuration"
+      end
+    end
+
+    #
+    # Metaprogramming shim, delegated to by #requires, #accepts and #yields.
+    # Fills out the tables when classes use those methods.
+    #
+    def build(vtype, name, description, type)
+      @hash[vtype][name] = {
+        :description => description,
+        :type        => type
+      }
+    end
+  end
+end

data/lib/furnish/provisioner.rb

@@ -3,44 +3,7 @@ module Furnish
   # Furnish provides no Provisioners as a part of its package. To use
   # pre-packaged provisioners, you must install additional packages.
   #
-  # Provisioners are *objects* that have a simple API and as a result, there is
-  # no "interface" for them in the classic term. You implement it, and if it
-  # doesn't work, you'll know in a hurry.
-  #
-  # I'm going to say this again -- Furnish does not construct your object.
-  # That's your job.
-  #
-  # Provisioners need 3 methods and one attribute, outside of that, you can do
-  # anything you want.
-  #
-  # * name is an attribute (getter/setter) that holds a string. It is used in
-  #   numerous places, is set by the ProvisionerGroup, and must not be volatile.
-  # * startup(*args) is a method to bring the provisioner "up" that takes an
-  #   arbitrary number of arguments and returns truthy or falsey, and in
-  #   exceptional cases may raise. A falsey return value means that provisioning
-  #   failed and the Scheduler will stop. A truthy value is passed to the next
-  #   startup method in the ProvisionerGroup.
-  # * shutdown is a method to bring the provisioner "down" and takes no
-  #   arguments. Like startup, truthy means success and falsey means failed, and
-  #   exceptions are fine, but return values aren't chained.
-  # * report returns an array of strings, and is used for diagnostic functions.
-  #   You can provide anything that fits that description, such as IP addresses
-  #   or other identifiers.
-  #
-  # Tracking external state is not Furnish's job, that's for your provisioner.
-  # Palsy is a state management system that Furnish links deeply to, so any
-  # state tracking you do in your provisioner, presuming you do it with Palsy,
-  # will be tracked along with Furnish's state information in the same
-  # database. That said, you can do whatever you want. Furnish doesn't try to
-  # think about your provisioner deadlocking itself because it's sharing state
-  # with another provisioner, so be mindful of that.
-  #
-  # Additionally, while recovery of furnish's state is something it will do for
-  # you, managing recovery inside your provisioner (e.g., ensuring that EC2
-  # instance really did come up after the program died in the middle of waiting
-  # for it) is your job. Everything will be brought up as it was and
-  # provisioning will be restarted. Account for that.
-  #
+  # For information on writing a provisioner, see Furnish::Provisioner::API.
   module Provisioner
   end
 end

data/lib/furnish/provisioner_group.rb

@@ -1,6 +1,6 @@
 require 'delegate'
 require 'furnish/logger'
-require 'furnish/provisioner'
+require 'furnish/provisioners/api'
 
 module Furnish
   #
@@ -28,6 +28,8 @@ module Furnish
     attr_reader :name
     # The list of names the group depends on.
     attr_reader :dependencies
+    # group state object. should not be used outside of internals.
+    attr_reader :group_state
 
     #
     # Create a new Provisioner group.
@@ -35,24 +37,37 @@ module Furnish
     # * provisioners can be an array of provisioner objects or a single item
     #   (which will be boxed). This is what the array consists of that this
     #   object is.
-    # * name is a string. always.
+    # * furnish_group_name is a string. always.
     # * dependencies can either be passed as an Array or Set, and will be
     #   converted to a Set if they are not a Set.
     #
-    def initialize(provisioners, name, dependencies=[])
+    # See #assert_provisioner_protocol, Furnish::Protocol, and
+    # Furnish::Provisioner::API for information on how a set of provisioner
+    # objects will be validated during the construction of the group.
+    #
+    def initialize(provisioners, furnish_group_name, dependencies=[])
+      @group_state = Palsy::Map.new('vm_group_state', furnish_group_name)
+
       #
       # FIXME maybe move the naming construct to here instead of populating it
       #       out to the provisioners
       #
 
-      provisioners = [provisioners] unless provisioners.kind_of?(Array)
-      provisioners.each do |p|
-        p.name = name
+      provisioners = [provisioners].compact unless provisioners.kind_of?(Array)
+
+      if provisioners.empty?
+        raise ArgumentError, "A non-empty list of provisioners must be provided"
       end
 
-      @name         = name
+      provisioners.each do |prov|
+        prov.furnish_group_name = furnish_group_name
+      end
+
+      @name         = furnish_group_name
       @dependencies = dependencies.kind_of?(Set) ? dependencies : Set[*dependencies]
 
+      assert_provisioner_protocol(provisioners)
+
       super(provisioners)
     end
 
@@ -60,78 +75,279 @@ module Furnish
     # Provision this group.
     #
     # Initial arguments go to the first provisioner's startup method, and then
-    # the return values, if truthy, get passed to the next provisioner's
-    # startup method. Any falsey value causes a RuntimeError to be raised and
-    # provisioning halts, effectively creating a chain of responsibility
-    # pattern.
+    # the return values, if a Hash, get merged with what was passed, and then
+    # the result is passed to the next provisioner's startup method. Any falsey
+    # value causes a RuntimeError to be raised and provisioning halts,
+    # effectively creating a chain of responsibility pattern.
     #
     # If a block is provided, will yield self to it for each step through the
     # group.
     #
-    def startup(*args)
-      each do |this_prov|
-        unless args = this_prov.startup(args)
+    def startup(args={ })
+      @group_state['action'] = :startup
+
+      each_with_index do |this_prov, i|
+        next unless check_recovery(this_prov, i)
+        set_recovery(this_prov, i, args)
+
+        startup_args = args
+
+        unless args = this_prov.startup(startup_args)
           if_debug do
-            puts "Could not provision #{this_prov.name} with provisioner #{this_prov.class.name}"
+            puts "Could not provision #{this_prov}"
           end
 
-          raise "Could not provision #{this_prov.name} with provisioner #{this_prov.class.name}"
+          set_recovery(this_prov, i, startup_args)
+          raise "Could not provision #{this_prov}"
+        end
+
+        unless args.kind_of?(Hash)
+          set_recovery(this_prov, i, startup_args)
+          raise ArgumentError,
+            "#{this_prov.class} does not return data that can be consumed by the next provisioner"
         end
 
+        args = startup_args.merge(args)
+
         yield self if block_given?
       end
 
+      clean_state
+
       return true
     end
 
     #
     # Deprovision this group.
     #
-    # Provisioners are run in reverse order against the shutdown method. No
-    # arguments are seeded as in Furnish::ProvisionerGroup#startup. Raise
-    # semantics are the same as with Furnish::ProvisionerGroup#startup.
+    # Provisioners are run in reverse order against the shutdown method.
+    # Argument handling semantics are exactly the same as #startup.
     #
-    # If a true argument is passed to this method, the raise semantics will be
-    # ignored (but still logged), allowing all the provisioners to run their
-    # shutdown routines. See Furnish::Scheduler#force_deprovision for
-    # information on how to use this externally.
+    # If a true argument is passed to this method as the second argument, the
+    # raise semantics will be ignored (but still logged), allowing all the
+    # provisioners to run their shutdown routines. See
+    # Furnish::Scheduler#force_deprovision for information on how to use this
+    # externally.
     #
-    def shutdown(force=false)
-      reverse.each do |this_prov|
-        success = false
+    def shutdown(args={ }, force=false)
+      @group_state['action'] = :shutdown
+
+      reverse.each_with_index do |this_prov, i|
+        next unless check_recovery(this_prov, i)
+        set_recovery(this_prov, i, args)
+
+        shutdown_args = args
 
         begin
-          success = perform_deprovision(this_prov) || force
+          args = perform_deprovision(this_prov, shutdown_args)
         rescue Exception => e
-          if force
-            if_debug do
-              puts "Deprovision #{this_prov.class.name}/#{this_prov.name} had errors:"
-              puts "#{e.message}"
-            end
-          else
+          if_debug do
+            puts "Deprovision of #{this_prov} had errors:"
+            puts "#{e.message}"
+          end
+
+          unless force
+            set_recovery(this_prov, i, shutdown_args)
             raise e
           end
         end
 
-        unless success or force
-          raise "Could not deprovision #{this_prov.name}/#{this_prov.class.name}"
+        unless args or force
+          set_recovery(this_prov, i, shutdown_args)
+          raise "Could not deprovision #{this_prov}"
+        end
+
+        unless args.kind_of?(Hash) or force
+          set_recovery(this_prov, i, startup_args)
+          raise ArgumentError,
+            "#{this_prov.class} does not return data that can be consumed by the next provisioner"
+        end
+
+        args = shutdown_args.merge(args || { })
+      end
+
+      clean_state
+
+      return true
+    end
+
+    #
+    # Initiate recovery for this group. Reading
+    # Furnish::Provisioner::API#recover is essential for this documentation.
+    #
+    # This method should not be used directly -- see
+    # Furnish::Scheduler#recover.
+    #
+    # #startup and #shutdown track various bits of information about state as
+    # they run provisioners. #recover uses this information to find out where
+    # things stopped, and executes a Furnish::Provisioner::API#recover method
+    # with the action and last parameters supplied. If the result of the
+    # recovery is true, it then attempts to finish the provisioning process by
+    # starting with the action that failed the last time (the same provisioner
+    # the recover method was called on).
+    #
+    # #recover will return nil if it can't actually recover anything because it
+    # doesn't have enough information. It will also make no attempt to recover
+    # (and fail by returning false) if the provisioner does not allow recovery
+    # (see Furnish::Provisioner::API.allows_recovery?).
+    #
+    # If you pass a truthy argument, it will pass this on to #shutdown if the
+    # action is required -- this is required for forced deprovisioning and is
+    # dealt with by Furnish::Scheduler.
+    #
+    def recover(force_deprovision=false)
+      index             = @group_state['index']
+      action            = @group_state['action']
+      provisioner       = @group_state['provisioner']
+      provisioner_args  = @group_state['provisioner_args']
+
+      return nil unless action and provisioner and index
+
+      result = false
+
+      #
+      # The next few lines here work around mutable state needing to happen in
+      # the original provisioner, but since the one we looked up will actually
+      # not be the same object, we need to deal with that by dispatching
+      # recovery to the actual provisioner object in the group.
+      #
+      # The one stored is still useful for informational and validation
+      # purposes, but the index is the ultimate authority.
+      #
+      offset = case action
+               when :startup
+                 index
+               when :shutdown
+                 size - 1 - index
+               else
+                 raise "Wtf?"
+               end
+
+      orig_prov = self[offset]
+
+      unless orig_prov.class == provisioner.class
+        raise "index and provisioner data don't seem to agree"
+      end
+
+      if orig_prov.class.respond_to?(:allows_recovery?) and orig_prov.class.allows_recovery?
+        if orig_prov.recover(action, provisioner_args)
+          @start_index        = index
+          @start_provisioner  = orig_prov
+
+          result = case action
+                   when :startup
+                     startup(provisioner_args)
+                   when :shutdown
+                     shutdown(provisioner_args, force_deprovision)
+                   else
+                     raise "Wtf?"
+                   end
         end
       end
+
+      @start_index, @start_provisioner = nil, nil
+
+      return result # scheduler will take it from here
     end
 
     protected
 
+    #
+    # Similar to #clean_state, a helper for recovery tracking
+    #
+
+    def set_recovery(prov, index, args=nil)
+      @group_state['provisioner'] = prov
+      @group_state['index'] = index
+      @group_state['provisioner_args'] = args
+    end
+
+    #
+    # Returns false if this provision is to be skipped, controlled by #recover.
+    #
+    # Raises if something really goes wrong.
+    #
+    def check_recovery(prov, index)
+      if @start_index and @start_provisioner
+        if @start_index == index
+          unless @start_provisioner.class == prov.class
+            raise "Provisioner state during recovery is incorrect - something is very wrong"
+          end
+        end
+
+        return index >= @start_index
+      end
+
+      return true
+    end
+
+    #
+    # cleanup the group state after a group operation.
+    #
+    def clean_state
+      @group_state.delete('index')
+      @group_state.delete('action')
+      @group_state.delete('provisioner')
+      @group_state.delete('provisioner_args')
+    end
+
     #
     # Just a way to simplify the deprovisioning logic with some generic logging.
     #
-    def perform_deprovision(this_prov)
-      result = this_prov.shutdown
+    def perform_deprovision(this_prov, args)
+      result = this_prov.shutdown(args)
       unless result
         if_debug do
-          puts "Could not deprovision group #{this_prov.name}."
+          puts "Could not deprovision group #{this_prov}."
         end
       end
       return result
     end
+
+    #
+    # Asserts that all the provisioners can communicate with each other.
+    #
+    # This leverages the Furnish::Protocol#requires_from and
+    # Furnish::Protocol#accepts_from assertions and raises if they return
+    # false. Any previous provisioner in the chain may yield something that the
+    # current accepting provisioner can require or accept. See the merge
+    # semantics in #startup and #shutdown for more information.
+    #
+    def assert_provisioner_protocol(provisioners)
+      assert_ordered_protocol(provisioners.dup, :startup_protocol)
+      assert_ordered_protocol(provisioners.reverse, :shutdown_protocol)
+    end
+
+    #
+    # This carries out the logic in #assert_provisioner_protocol, catering
+    # towards which protocol we're validating.
+    #
+    def assert_ordered_protocol(iterator, protocol_method)
+      yielders = [iterator.shift.class]
+
+      while accepting = iterator.shift
+        accepting = accepting.class # meh
+
+        unless yielders.all? { |y| y.respond_to?(protocol_method) }
+          raise ArgumentError, "yielding classes do not implement protocol #{protocol_method} -- cannot continue"
+        end
+
+        unless accepting.respond_to?(protocol_method)
+          raise ArgumentError, "accepting class #{accepting} does not implement protocol #{protocol_method} -- cannot continue"
+        end
+
+        a_proto = accepting.send(protocol_method)
+
+        unless yielders.any? { |y| a_proto.requires_from(y.send(protocol_method)) }
+          raise ArgumentError, "#{accepting} requires information specified by #{protocol_method} that yielding classes do not yield"
+        end
+
+        unless yielders.any? { |y| a_proto.accepts_from(y.send(protocol_method)) }
+          raise ArgumentError, "#{accepting} expects information specified by #{protocol_method} that yielding classes will not deliver"
+        end
+
+        yielders.push(accepting)
+      end
+    end
   end
 end