configuration_service 0.0.1

data/lib/configuration_service/test/orchestration_provider.rb

@@ -0,0 +1,252 @@
+require 'configuration_service'
+
+module ConfigurationService
+
+  module Test
+
+    ##
+    # Abstract Orchestrator provider
+    #
+    # Extend this class if you want your test orchestration provider to
+    # constrain your implementation's interface to work as a configuration
+    # service provider. If you have no intention of plugging your
+    # implementation into ConfigurationService::Base, build your own test
+    # orchestration provider from scratch, using Orchestrator as a guide.
+    #
+    # Extensions should implement #service_provider, #broken_service_provider,
+    # #token_for and #delete_configuration.
+    #
+    class OrchestrationProvider
+
+      ##
+      # * +:requesting_configurations+
+      # * +:publishing_configurations+
+      # * +:nothing+ (if possible, provide credentials that don't allow
+      #   operations on the configuration +identifier+)
+      ACTIVITY_ROLE_MAP = {
+        :requesting_configurations => :consumer,
+        :publishing_configurations => :publisher,
+        :nothing => :none
+      } unless defined?(ACTIVITY_ROLE_MAP)
+      ##
+      # * +:consumer+
+      # * +:publisher+
+      # * +:none+
+      #
+      ROLES = ACTIVITY_ROLE_MAP.values unless defined?(ROLES)
+
+      ##
+      # Returns a new Orchestrator provider
+      #
+      # The provider is always initialized with the same configuration +identifier+
+      #
+      def initialize
+        @identifier = "acme"
+      end
+
+      ##
+      # See Orchestrator#authorize
+      #
+      def authorize(role)
+        @token = token_for(role)
+      end
+
+      ##
+      # See Orchestrator#deauthorize
+      #
+      def deauthorize
+        @token = nil
+      end
+
+      ##
+      # See Orchestrator#given_metadata
+      #
+      def given_metadata
+        @metadata = {"version" => "1.0"}
+      end
+
+      ##
+      # See Orchestrator#given_metadata_filter
+      #
+      def given_metadata_filter
+        @metadata_filter = {"revision" => "d4d40eab-cf66-4af5-9a77-d956a11682de"}
+      end
+
+      ##
+      # See Orchestrator#given_existing_configuration
+      #
+      def given_existing_configuration
+        authorized_as(:publisher) do
+          @existing_configuration = publish_configuration
+        end
+      end
+
+      ##
+      # See Orchestrator#given_invalid_configuration
+      #
+      def given_invalid_configuration
+        @configuration = "This should be an object!"
+      end
+
+      ##
+      # See Orchestrator#given_missing_configuration
+      #
+      def given_missing_configuration
+        authorized_as(:publisher) do
+          delete_configuration
+          @existing_configuration = nil
+        end
+      end
+
+      ##
+      # See Orchestrator#given_existing_configuration_matching_metadata_filter
+      #
+      def given_existing_configuration_matching_metadata_filter
+        @metadata_matching_filter = (@metadata || {}).merge(@metadata_filter)
+        given_existing_configuration
+      end
+
+      ##
+      # See Orchestrator#given_existing_configuration_not_matching_metadata_filter
+      #
+      def given_existing_configuration_not_matching_metadata_filter
+        @metadata_matching_filter = {}
+        given_existing_configuration
+      end
+
+      ##
+      # See Orchestrator#existing_configuration
+      #
+      def existing_configuration
+        @existing_configuration.data
+      end
+
+      ##
+      # See Orchestrator#existing_revision
+      #
+      def existing_revision
+        @existing_configuration.revision
+      end
+
+      ##
+      # Perform a consuming operation against the service under test
+      #
+      # The response from the service is wrapped in a test Response.
+      #
+      def request_configuration
+        wrap_response do
+          if @metadata_filter
+            service.request_configuration(@metadata_filter)
+          else
+            service.request_configuration
+          end
+        end
+      end
+
+      ##
+      # Perform a publishing operation against the service under test
+      #
+      # The response from the service is wrapped in a test Response.
+      #
+      def publish_configuration
+        wrap_response do
+          if @metadata
+            service.publish_configuration(configuration, @metadata)
+          elsif @metadata_matching_filter
+            service.publish_configuration(configuration, @metadata_matching_filter)
+          else
+            service.publish_configuration(configuration)
+          end
+        end
+      end
+
+      ##
+      # Arrange for the next publication or consuming operation to fail
+      #
+      # This is done by using a #broken_service_provider to service the
+      # next operation.
+      #
+      def fail_next_request
+        @fail_next = true
+      end
+
+      private
+
+        ##
+        # Return a ConfigurationService::Base provider
+        #
+        # The provider should use a consistent +identifier+.
+        #
+        def service_provider # :doc:
+          raise NotImplementedError, "#{self.class} must implement service_provider"
+        end
+
+        ##
+        # Return a broken ConfigurationService::Base provider
+        #
+        # The provider's #publish_configuration and #request_configuration
+        # methods must raise an Error other than AuthorizationError.
+        #
+        def broken_service_provider # :doc:
+          raise NotImplementedError, "#{self.class} must implement broken_service_provider"
+        end
+
+        ##
+        # Delete the configuration identified by the consistent +identifier+
+        #
+        # Deleting non-existent configuration should not produce an error.
+        #
+        def delete_configuration # :doc:
+          raise NotImplementedError, "#{self.class} must implement delete_configuration"
+        end
+
+        ##
+        # Return a token that authorizes +role+
+        #
+        # Valid roles are:
+        #
+        # * +:consumer+
+        # * +:publisher+
+        # * +:nothing+
+        #
+        # Note that a token should be returned for +:nothing+, but the token should
+        # not be authorized to consume or publish to the +identifier+.
+        #
+        def token_for(role) # :doc:
+          raise NotImplementedError, "#{self.class} must implement token_for(role)"
+        end
+
+        def configuration
+          @configuration ||= {"verbose" => true}
+        end
+
+        def service
+          if @fail_next
+            @fail_next = false
+            ConfigurationService.new(broken_service_provider)
+          else
+            ConfigurationService.new(service_provider)
+          end
+        end
+
+        def authorized_as(role)
+          restore_token = @token
+          authorize(role)
+          yield.tap do
+            @token = restore_token
+          end
+        end
+
+        def wrap_response # :nodoc:
+          begin
+            ConfigurationService::Test::Response::Success.new(yield)
+          rescue ConfigurationService::Error => e
+            ConfigurationService::Test::Response::Failure.new(e)
+          end
+        end
+
+    end
+
+  end
+
+end

data/lib/configuration_service/test/orchestration_provider_registry.rb

@@ -0,0 +1,52 @@
+require "singleton"
+
+module ConfigurationService
+
+  module Test
+
+    # The Singleton module deletes the instance on include!
+    unless defined?(OrchestrationProviderRegistry)
+
+      ##
+      # Singleton registry of Orchestrator providers
+      #
+      class OrchestrationProviderRegistry
+        include Singleton
+
+        def initialize ## :nodoc:
+          @providers = {}
+        end
+
+        ##
+        # Register a +provider+ identified by the string +identifier+
+        #
+        # The +provider+ should be a class with a default (nullary) constructor.
+        #
+        def register(identifier, provider)
+          @providers[identifier] = provider
+        end
+
+        ##
+        # Return the +provider+ identified by the string +identifier+
+        #
+        # The +provider must already have been registered with #register,
+        # and should be a class with a default (nullary) constructor.
+        #
+        # Returns +nil+ if no provider has been registered with the given
+        # +identifier+.
+        #
+        def lookup(identifier)
+          @providers[identifier]
+        end
+
+        ##
+        # Return the singleton registry instance
+        # :singleton-method: instance
+
+      end
+
+    end
+
+  end
+
+end

data/lib/configuration_service/test/orchestrator.rb

@@ -0,0 +1,240 @@
+require 'configuration_service'
+
+module ConfigurationService
+
+  module Test
+
+    ##
+    # The declarative test orchestration API
+    #
+    # This is the declarative API that describes what must be done to test a
+    # configuration service provider. It catalogues all the services that the
+    # cucumber step definitions expect from a test orchestration provider.
+    #
+    # It keeps no domain state, because that would couple it to the
+    # service implementation. By making no assumptions at all about the API
+    # or data, it allows implementors to produce service implementations
+    # that do not adhere to the anticipated ConfigurationService::Base API,
+    # by writing their own OrchestrationProvider from scratch.
+    #
+    # However, implementors who are trying to produce ConfigurationService::Base
+    # providers should extend OrchestrationProvider, which anticipates a
+    # compatible provider API.
+    #
+    # Note that the +response+ instance variable is not domain state; it is
+    # a test artifact (Response or similar) that orchestration providers use
+    # to wrap responses from the service provider.
+    #
+    class Orchestrator
+
+      ##
+      # Return a new orchestrator initialized with a new instance of +provider_class+.
+      #
+      # The provider is expected to use a consistent configuration +identifier+ for
+      # all publishing and consuming operations.
+      #
+      def initialize(provider_class)
+        @provider = provider_class.new
+      end
+
+      ##
+      # Include metadata in the next publishing operation
+      #
+      def given_metadata
+        @provider.given_metadata
+      end
+
+      ##
+      # Include a metadata filter in the next consuming operation
+      #
+      def given_metadata_filter
+        @provider.given_metadata_filter
+      end
+
+      ##
+      # Arrange a published configuration fixture
+      def given_existing_configuration
+        @provider.given_existing_configuration
+      end
+
+      ##
+      # Use invalid configuration data in the next publishing operation
+      #
+      def given_invalid_configuration
+        @provider.given_invalid_configuration
+      end
+
+      ##
+      # Delete any existing configuration
+      #
+      def given_missing_configuration
+        @provider.given_missing_configuration
+      end
+
+      ##
+      # Arrange a published configuration fixture
+      #
+      # Use a metadata filter that matches the fixture's metadata in the next consuming operation.
+      #
+      def given_existing_configuration_matching_metadata_filter
+        @provider.given_existing_configuration_matching_metadata_filter
+      end
+
+      ##
+      # Arrange a published configuration fixture
+      #
+      # Use a metadata filter that does not match the fixture's metadata in the next consuming operation.
+      #
+      def given_existing_configuration_not_matching_metadata_filter
+        @provider.given_existing_configuration_not_matching_metadata_filter
+      end
+
+      ##
+      # Return a published configuration fixture
+      #
+      # E.g. as arranged by #given_existing_configuration.
+      #
+      # TODO remove; step definitions expect this to be Comparable
+      #
+      def existing_configuration
+        @provider.existing_configuration
+      end
+
+      ##
+      # Return the revision of a published configuration fixture
+      #
+      # E.g. as arranged by #given_existing_configuration.
+      #
+      # TODO remove; step definitions expect this to be Comparable
+      #
+      def existing_revision
+        @provider.existing_revision
+      end
+
+      ##
+      # Authorize the next consuming or publishing operation for +activity+
+      #
+      # Valid activities (as per ACTIVITY_ROLE_MAP in ConfigurationService::Test::OrchestrationProvider) are:
+      #
+      # * +:requesting_configurations+
+      # * +:publishing_configurations+
+      # * +:nothing+
+      #
+      # Where possible, the orchestration provider should authorize +:nothing+
+      # by providing valid credentials that don't allow operations on the
+      # configuration +identifier+ that it tests against.
+      #
+      def authorize(activity)
+        role = role_for(activity) or raise "unknown authorizable activity #{activity.inspect}"
+        @provider.authorize(role)
+      end
+
+      ##
+      # Remove any previous authorization
+      #
+      # E.g. as arranged by #authorize.
+      #
+      def deauthorize
+        @provider.deauthorize
+      end
+
+      ##
+      # Perform a consuming operation against the service under test
+      #
+      # The provider is expected to wrap the response in a Response (or
+      # simimlar) and return that.
+      #
+      def request_configuration
+        @response = @provider.request_configuration
+      end
+
+      ##
+      # Perform a publishing operation against the service under test
+      #
+      # The provider is expected to wrap the response in a Response (or
+      # simimlar) and return that.
+      #
+      def publish_configuration
+        @response = @provider.publish_configuration
+      end
+
+      ##
+      # True if the last consuming or publishing operation was allowed
+      #
+      def request_allowed?
+        @response.allowed?
+      end
+
+      ##
+      # True if the last consuming or publishing operation failed
+      #
+      # Operations that were not allowed (as per #request_allowed?) or
+      # considered failed.
+      #
+      def request_failed?
+        @response.failed?
+      end
+
+      ##
+      # True if the last consuming operation did not return data
+      #
+      def request_not_found?
+        not @response.found?
+      end
+
+      ##
+      # True if the last consuming operation did not return data
+      #
+      # TODO: distinguish #request_not_matched? to mean "found data, but filtered out by metadata filter"
+      def request_not_matched?
+        not @response.found?
+      end
+
+      ##
+      # The last published or consumed configuration data
+      #
+      # Note that this is the data itself, not a Configuration object.
+      #
+      def published_configuration
+        @response.data
+      end
+      alias :requested_configuration :published_configuration
+
+      ##
+      # The revision of the last published or consumed configuration
+      #
+      def published_revision
+        @response.revision
+      end
+
+      ##
+      # The last published metadata
+      #
+      def published_metadata
+        @response.metadata
+      end
+
+      ##
+      # Arrange for the next publication operation to fail
+      #
+      def given_publication_failure
+        @provider.fail_next_request
+      end
+
+      ##
+      # Arrange for the next consuming operation to fail
+      #
+      def given_request_failure
+        @provider.fail_next_request
+      end
+
+      private
+
+        def role_for(activity)
+          ConfigurationService::Test::OrchestrationProvider::ACTIVITY_ROLE_MAP[activity]
+        end
+    end
+
+  end
+
+end

data/lib/configuration_service/test/orchestrator_environment_factory.rb

@@ -0,0 +1,31 @@
+module ConfigurationService
+
+  module Test
+
+    ##
+    # Builds an Orchestrator using a provider selected from the environment
+    #
+    module OrchestratorEnvironmentFactory
+
+      ##
+      # Looks up the provider registered to the OrchestrationProviderRegistry
+      # with the name provided in the +TEST_ORCHESTRATION_PROVIDER+ environment
+      # variable, and returns a new Orchestrator initialized with that
+      # provider.
+      #
+      # Returns a new Orchestrator, or raises a +RuntimeError+ if the
+      # +TEST_ORCHESTRATION_PROVIDER+ environment variable does not name a
+      # provider known to the OrchestrationProviderRegistry.
+      #
+      def self.build
+        identifier = ENV["TEST_ORCHESTRATION_PROVIDER"] or raise "missing environment variable: TEST_ORCHESTRATION_PROVIDER"
+        registry = ConfigurationService::Test::OrchestrationProviderRegistry.instance
+        provider = registry.lookup(identifier) or raise "unknown test orchestration provider: #{identifier}"
+        @test = ConfigurationService::Test::Orchestrator.new(provider)
+      end
+
+    end
+
+  end
+
+end

data/lib/configuration_service/test/response.rb

@@ -0,0 +1,141 @@
+require "configuration_service"
+
+module ConfigurationService
+
+  module Test
+
+    ##
+    # Encapsulation of ConfigurationService::Base responses
+    #
+    # See Success and Failure.
+    #
+    module Response
+
+      ##
+      # Encapsulates a non-error ConfigurationService::Base response
+      #
+      # This allows an OrchestrationProvider to decouple the Orchestrator
+      # from the implementation details of the service provider's responses.
+      #
+      class Success
+
+        ##
+        # Initialize a new Success with a response
+        #
+        # The response should be a Configuration object or +nil+ (because
+        # the ConfigurationService::Base API communicates +not found+ as
+        # +nil+).
+        #
+        def initialize(response)
+          @response = response
+        end
+
+        ##
+        # Always true
+        #
+        def allowed?
+          true
+        end
+
+        ##
+        # Always false
+        #
+        def failed?
+          false
+        end
+
+        ##
+        # True if the +response+ was not +nil+
+        #
+        def found?
+          not @response.nil?
+        end
+
+        ##
+        # The configuration data dictionary of the response, or +nil+ if not #found?
+        #
+        def data
+          @response and @response.data
+        end
+
+        ##
+        # The revision from the response's metadata, or +nil+ if not #found?
+        #
+        def revision
+          @response and @response.revision
+        end
+
+        ##
+        # The metadata dictionary of the response, or +nil+ if not #found?
+        #
+        def metadata
+          @response and @response.metadata
+        end
+
+      end
+
+      ##
+      # Encapsulates an error ConfigurationService::Base response
+      #
+      # This allows an OrchestrationProvider to decouple the Orchestrator
+      # from the implementation details of the service provider's error
+      # handling.
+      #
+      class Failure
+
+        ##
+        # Initialize a new Failure with an exception
+        #
+        def initialize(exception)
+          @exception = exception
+        end
+
+        ##
+        # True unless the exception was an AuthorizationError
+        #
+        def allowed?
+          !@exception.is_a?(ConfigurationService::AuthorizationError)
+        end
+
+        ##
+        # True if the exception was an Error but not an AuthorizationError
+        #
+        def failed?
+          allowed? and @exception.is_a?(ConfigurationService::Error)
+        end
+
+        ##
+        # Always false
+        #
+        def found?
+          false
+        end
+
+        ##
+        # Raises +NotImplementedError+
+        #
+        def data
+          raise NotImplementedError, "configuration not available after #{@exception.inspect}"
+        end
+
+        ##
+        # Raises +NotImplementedError+
+        #
+        def revision
+          raise NotImplementedError, "revision not available after #{@exception.inspect}"
+        end
+
+        ##
+        # Raises +NotImplementedError+
+        #
+        def metadata
+          raise NotImplementedError, "metadata not available after #{@exception.inspect}"
+        end
+
+      end
+
+    end
+
+  end
+
+end