configuration_service 2.0.4 → 2.0.5

data/lib/configuration_service/test/orchestrator.rb

@@ -14,24 +14,24 @@ module ConfigurationService
     # 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.
+    # that do not adhere to the anticipated {ConfigurationService::Base} API,
+    # by writing their own test orchestration provider from scratch
+    # instead of extending {ConfigurationService::Test::OrchestrationProvider}.
     #
-    # However, implementors who are trying to produce ConfigurationService::Base
-    # providers should extend OrchestrationProvider, which anticipates a
-    # compatible provider API.
+    # However, implementors who are trying to produce {ConfigurationService::Base}
+    # providers should extend {ConfigurationService::Test::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.
+    # Note that the +@response+ instance variable is not domain state; it is
+    # a test artifact ({ConfigurationService::Test::Response} or similar)
+    # that orchestration providers use to wrap responses from the configuration service.
     #
     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.
+      # @param [Class] provider_class
+      #   the test orchestration provider class, which should have a default/nullary constructor
       #
       def initialize(provider_class)
         @provider = provider_class.new
@@ -68,9 +68,9 @@ module ConfigurationService
       ##
       # Return a published configuration fixture
       #
-      # E.g. as arranged by #given_existing_configuration.
+      # E.g. as arranged by {#given_existing_configuration}.
       #
-      # TODO remove; step definitions expect this to be Comparable
+      # @todo replace with predicate: this exposes domain state
       #
       def existing_configuration
         @provider.existing_configuration
@@ -79,24 +79,25 @@ module ConfigurationService
       ##
       # Return the revision of a published configuration fixture
       #
-      # E.g. as arranged by #given_existing_configuration.
+      # E.g. as arranged by {#given_existing_configuration}.
       #
-      # TODO remove; step definitions expect this to be Comparable
+      # @todo replace with predicate: this exposes domain state
       #
       def existing_revision
         @provider.existing_revision
       end
 
       ##
-      # Authorize the next consuming or publishing operation for +activity+
+      # Authorize the next publish or request activity
       #
-      # Valid activities (as per ACTIVITY_ROLE_MAP in ConfigurationService::Test::OrchestrationProvider) are:
+      # @param [Symbol] activity
+      #   Valid activities (as per {ConfigurationService::Test::OrchestrationProvider::ACTIVITY_ROLE_MAP}) are:
       #
-      # * +:requesting_configurations+
-      # * +:publishing_configurations+
-      # * +:nothing+
+      #   * +:requesting_configurations+
+      #   * +:publishing_configurations+
+      #   * +:nothing+
       #
-      # Where possible, the orchestration provider should authorize +:nothing+
+      # Where possible, the test orchestration provider should authorize +:nothing+
       # by providing valid credentials that don't allow operations on the
       # configuration +identifier+ that it tests against.
       #
@@ -108,60 +109,69 @@ module ConfigurationService
       ##
       # Remove any previous authorization
       #
-      # E.g. as arranged by #authorize.
+      # E.g. as arranged by {#authorize}.
       #
       def deauthorize
         @provider.deauthorize
       end
 
       ##
-      # Perform a consuming operation against the service under test
+      # Request configuration from the service under test
       #
-      # The provider is expected to wrap the response in a Response (or
-      # simimlar) and return that.
+      # The test orchestration provider is expected to wrap the response in a {ConfigurationService::Test::Response}
+      # (or simimlar) and return that.
       #
       def request_configuration
         @response = @provider.request_configuration
       end
 
       ##
-      # Perform a publishing operation against the service under test
+      # Publish configuration through the service under test
       #
-      # The provider is expected to wrap the response in a Response (or
-      # simimlar) and return that.
+      # The test orchestration provider is expected to wrap the response in a {ConfigurationService::Test::Response}
+      # (or simimlar) and return that.
       #
       def publish_configuration
         @response = @provider.publish_configuration
       end
 
       ##
-      # True if the last consuming or publishing operation was allowed
+      # Whether the last publish or request was allowed
+      #
+      # @see ConfigurationService::Test::Response::Success#allowed?
+      # @see ConfigurationService::Test::Response::Failure#allowed?
       #
       def request_allowed?
         @response.allowed?
       end
 
       ##
-      # True if the last consuming or publishing operation failed
+      # Whether the last publish or request was allowed but failed
       #
-      # Operations that were not allowed (as per #request_allowed?) or
-      # considered failed.
+      # @see ConfigurationService::Test::Response::Success#failed?
+      # @see ConfigurationService::Test::Response::Failure#failed?
       #
       def request_failed?
         @response.failed?
       end
 
       ##
-      # True if the last consuming operation did not return data
+      # True if the last request not return configuration data
+      #
+      # @see ConfigurationService::Test::Response::Success#found?
+      # @see ConfigurationService::Test::Response::Failure#found?
       #
       def request_not_found?
         not @response.found?
       end
 
       ##
-      # True if the last consuming operation did not return data
+      # True if the last request did consuming operation did not return data
       #
-      # TODO: distinguish #request_not_matched? to mean "found data, but filtered out by metadata filter"
+      # @see ConfigurationService::Test::Response::Success#found?
+      # @see ConfigurationService::Test::Response::Failure#found?
+      #
+      # @todo distinguish {#request_not_matched?} to mean "found data, but filtered out by metadata filter"
       #
       def request_not_matched?
         not @response.found?
@@ -170,7 +180,9 @@ module ConfigurationService
       ##
       # The last published or consumed configuration data
       #
-      # Note that this is the data itself, not a Configuration object.
+      # @return [Hash] configuration data (not a {ConfigurationService::Configuration} object)
+      #
+      # @todo replace with predicate: this exposes domain state
       #
       def published_configuration
         @response.data
@@ -178,7 +190,11 @@ module ConfigurationService
       alias :requested_configuration :published_configuration
 
       ##
-      # The revision of the last published or consumed configuration
+      # The revision of the last published or consumed configuration metadata
+      #
+      # @return [String] metadata revision
+      #
+      # @todo replace with predicate: this exposes domain state
       #
       def published_revision
         @response.revision
@@ -187,6 +203,10 @@ module ConfigurationService
       ##
       # The last published metadata
       #
+      # @return [Hash] configuration metadata
+      #
+      # @todo replace with predicate: this exposes domain state
+      #
       def published_metadata
         @response.metadata
       end
@@ -211,7 +231,7 @@ module ConfigurationService
       # Environmental service configuration is configuration for bootstrapping
       # a configuration service and provider.
       #
-      # TODO This method is imperative
+      # @todo replace with declarative test that delegates to orchestration provider
       #
       def given_environmental_service_configuration
         sp_env = @provider.service_provider_configuration.inject({}) do |m, (k, v)|
@@ -228,11 +248,10 @@ module ConfigurationService
       ##
       # Bootstrap a configuration service environmentally
       #
-      # Environmental service configuration (as arranged by
-      # #given_environmental_service_configuration) is given to an
-      # EnvironmentContext factory to create a service configuration instance.
+      # Environmental service configuration (as arranged by {#given_environmental_service_configuration})
+      # is given to an {ConfigurationService::Factory::EnvironmentContext} factory to create a service configuration instance.
       #
-      # TODO This method is imperative
+      # @todo replace with declarative test that delegates to orchestration provider
       #
       def bootstrap_configuration_service_environmentally
         factory = ConfigurationService::Factory::EnvironmentContext.new(@env, "CFGSRV")
@@ -242,7 +261,7 @@ module ConfigurationService
       ##
       # Tests that a bootstrapped configuration service is functional
       #
-      # TODO This method is imperative
+      # @todo replace with declarative test that delegates to orchestration provider
       #
       def bootstrapped_configuration_service_functional?
         response = begin
@@ -256,7 +275,7 @@ module ConfigurationService
       ##
       # Tests that environmental service configuration is scrubbed
       #
-      # TODO This method is imperative
+      # @todo replace with declarative test that delegates to orchestration provider
       #
       def environmental_service_configuration_scrubbed?
         !@env.include?("CFGSRV_TOKEN")

data/lib/configuration_service/test/orchestrator_environment_factory.rb

@@ -3,25 +3,38 @@ module ConfigurationService
   module Test
 
     ##
-    # Builds an Orchestrator using a provider selected from the environment
+    # A factory for building a test orchestrator using an orchestration provider selected from the environment
+    #
+    # @example cucumber features/support/env.rb
+    #   require 'configuration_service/test'
+    #
+    #   Before do
+    #     begin
+    #       @test = ConfigurationService::Test::OrchestratorEnvironmentFactory.build
+    #     rescue
+    #       Cucumber.wants_to_quit = true
+    #       raise
+    #     end
+    #   end
     #
     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.
+      # Build a test orchestrator
+      #
+      # Looks up the test orchestration provider class registered to the {ConfigurationService::Test::OrchestrationProviderRegistry}
+      # with the name provided in the +TEST_ORCHESTRATION_PROVIDER+ environment variable,
+      # and returns a new {ConfigurationService::Test::Orchestrator} initialized with an instance of that provider class.
       #
-      # Returns a new Orchestrator, or raises a +RuntimeError+ if the
-      # +TEST_ORCHESTRATION_PROVIDER+ environment variable does not name a
-      # provider known to the OrchestrationProviderRegistry.
+      # @return [ConfigurationService::Test::Orchestrator] the test orchestrator
+      # @raise [RuntimeError] if the +TEST_ORCHESTRATION_PROVIDER+ environment variable
+      #                       does not name a provider known to the {ConfigurationService::Test::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)
+        ConfigurationService::Test::Orchestrator.new(provider)
       end
 
     end

data/lib/configuration_service/test/response.rb

@@ -5,68 +5,81 @@ module ConfigurationService
   module Test
 
     ##
-    # Encapsulation of ConfigurationService::Base responses
+    # Encapsulation of configuration service responses
     #
-    # See Success and Failure.
+    # Used by test orchestration providers to decouple the test orchestrator from the semantics of API responses.
     #
     module Response
 
       ##
-      # Encapsulates a non-error ConfigurationService::Base response
+      # Encapsulates a non-error configuration service response
       #
-      # This allows an OrchestrationProvider to decouple the Orchestrator
-      # from the implementation details of the service provider's responses.
+      # This allows an {ConfigurationService::Test::OrchestrationProvider}
+      # to decouple the {ConfigurationService::Test::Orchestrator} from the semantics of the configuration service'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+).
+        # @param [ConfigurationService::Configuration, nil] response
+        #   a configuration service response, or +nil+ if a {ConfigurationService::ConfigurationNotFoundError} was raised
         #
         def initialize(response)
           @response = response
         end
 
         ##
-        # Always true
+        # Whether the request was allowed
+        #
+        # @return [true] always
         #
         def allowed?
           true
         end
 
         ##
-        # Always false
+        # Whether the request was authorized but failed
+        #
+        # @return [false] always
         #
         def failed?
           false
         end
 
         ##
-        # True if the +response+ was not +nil+
+        # Whether the identified configuration was found
+        #
+        # @return [true] if the +response+ was not +nil+
+        # @return [false] if the +response+ was +nil+
         #
         def found?
           not @response.nil?
         end
 
         ##
-        # The configuration data dictionary of the response, or +nil+ if not #found?
+        # The configuration data dictionary of the response
+        #
+        # @return [Hash] if {#found?}
+        # @return [nil] if not {#found?}
         #
         def data
           @response and @response.data
         end
 
         ##
-        # The revision from the response's metadata, or +nil+ if not #found?
+        # The configuration metadata's revision
+        #
+        # @return [String] if {#found?}
+        # @return [nil] if not {#found?}
         #
         def revision
           @response and @response.metadata["revision"]
         end
 
         ##
-        # The metadata dictionary of the response, or +nil+ if not #found?
+        # The configuration metadata
+        #
+        # @return [Hash] if {#found?}
+        # @return [nil] if not {#found?}
         #
         def metadata
           @response and @response.metadata
@@ -75,58 +88,73 @@ module ConfigurationService
       end
 
       ##
-      # Encapsulates an error ConfigurationService::Base response
+      # Encapsulates a configuration service error
       #
-      # This allows an OrchestrationProvider to decouple the Orchestrator
-      # from the implementation details of the service provider's error
-      # handling.
+      # This allows a {ConfigurationService::Test::OrchestrationProvider}
+      # to decouple the {ConfigurationService::Test::Orchestrator}
+      # from the semantics of the configuration service's error handling.
       #
       class Failure
 
         ##
-        # Initialize a new Failure with an exception
+        # @param [ConfigurationService::Error] exception
+        #   a configuration service error
         #
         def initialize(exception)
           @exception = exception
         end
 
         ##
-        # True unless the exception was an AuthorizationError
+        # Whether the request was allowed
+        #
+        # @return [true] if the request was allowed
+        # @return [false] if the request was a not allowed
         #
         def allowed?
           !@exception.is_a?(ConfigurationService::AuthorizationError)
         end
 
         ##
-        # True if the exception was an Error but not an AuthorizationError
+        # Whether the request was authorized but failed
+        #
+        # @return [true] if the request was allowed but raised a {ConfigurationService::Error}
+        # @return [false] if the request was not allowed or raised an unexpected error
         #
         def failed?
           allowed? and @exception.is_a?(ConfigurationService::Error)
         end
 
         ##
-        # Always false
+        # Whether the identified configuration was found
+        #
+        # @return [false] always
         #
         def found?
           false
         end
 
         ##
-        # Raises +NotImplementedError+
+        # The configuration data dictionary of the response
+        #
+        # @raise [NotImplementedError] always
         #
         def data
           raise NotImplementedError, "configuration not available after #{@exception.inspect}"
         end
 
         ##
-        # Raises +NotImplementedError+
+        # The configuration metadata's revision
+        #
+        # @raise [NotImplementedError] always
         #
         def revision
           raise NotImplementedError, "revision not available after #{@exception.inspect}"
         end
 
         ##
-        # Raises +NotImplementedError+
+        # The configuration metadata's revision
+        #
+        # @raise [NotImplementedError] always
         #
         def metadata
           raise NotImplementedError, "metadata not available after #{@exception.inspect}"

data/lib/configuration_service/test/stub_orchestration_provider.rb

@@ -8,59 +8,67 @@ module ConfigurationService
   module Test
 
     ##
-    # Test Orchestrator provider for testing the Stub service provider
+    # Test orchestration provider for testing the {ConfigurationService::Provider::Stub} service provider
     #
-    # Registered to the OrchestrationProviderRegistry as +stub+.
+    # Registered to the {ConfigurationService::Test::OrchestrationProviderRegistry} as "stub".
     #
     class StubOrchestrationProvider < OrchestrationProvider
 
+      ##
+      # The registered identifier of the service provider under test
+      #
+      # @see ConfigurationService::Test::OrchestrationProvider#service_provider_id
+      #
       def service_provider_id
         "stub"
       end
 
       ##
-      # Return configuration for a Stub
+      # The configuration for the service provider under test
       #
-      def service_provider_configuration # :doc:
+      # @see ConfigurationService::Test::OrchestrationProvider#service_provider_configuration
+      #
+      def service_provider_configuration
         {name: "Stub configuration service provider"}
       end
 
-      private
-
-        ##
-        # Returns a new Stub
-        #
-        def service_provider # :doc:
-          ConfigurationService::Provider::Stub.new(service_provider_configuration)
-        end
+      ##
+      # The service provider under test
+      #
+      # @see ConfigurationService::Test::OrchestrationProvider#service_provider
+      #
+      def service_provider
+        ConfigurationService::Provider::Stub.new(service_provider_configuration)
+      end
 
-        ##
-        # Returns a new Broken
-        #
-        def broken_service_provider # :doc:
-          ConfigurationService::Provider::Broken.new
-        end
+      ##
+      # A broken service provider
+      #
+      # @see ConfigurationService::Test::OrchestrationProvider#broken_service_provider
+      #
+      def broken_service_provider
+        ConfigurationService::Provider::Broken.new
+      end
 
-        ##
-        # Returns a token for +role+
-        #
-        # The token is taken from +BUILTIN_TOKENS+ in Stub
-        #
-        def token_for(role) # :doc:
-          ConfigurationService::Provider::Stub::BUILTIN_TOKENS[role]
-        end
+      ##
+      # Provide a token that authorizes a role
+      #
+      # The token is taken from {ConfigurationService::Provider::Stub::BUILTIN_TOKENS}
+      #
+      # @see ConfigurationService::Test::OrchestrationProvider#token_for
+      #
+      def token_for(role)
+        ConfigurationService::Provider::Stub::BUILTIN_TOKENS[role]
+      end
 
-        ##
-        # Delete configuration from the StubStore
-        #
-        # The consistently used configuration +identifier+ is used to identify
-        # the configuration to be deleted.
-        #
-        # Deleting non-existent configuration is not an error.
-        #
-        def delete_configuration # :doc:
-          ConfigurationService::Provider::StubStore.instance.delete(@identifier)
-        end
+      ##
+      # Delete configuration data
+      #
+      # @see ConfigurationService::Test::OrchestrationProvider#delete_configuration
+      #
+      def delete_configuration
+        ConfigurationService::Provider::StubStore.instance.delete(@identifier)
+      end
 
     end
 

data/lib/configuration_service/test.rb

@@ -8,15 +8,16 @@ module ConfigurationService
   # The following are used directly by the cucumber test suite, and
   # should not be of immediate interest to implementors:
   #
-  # * Orchestrator
-  # * OrchestratorEnvironmentFactory
-  # * StubOrchestrationProvider
+  # * {ConfigurationService::Test::Orchestrator} the declarative test orchestration API
+  # * {ConfigurationService::Test::OrchestratorEnvironmentFactory} test orchestrator factory
+  # * {ConfigurationService::Test::StubOrchestrationProvider} imperative test orchestration provider
+  #   for the {ConfigurationService::Provider::Stub Stub} configuration service provider
   #
   # The following are of interest to implementors:
   #
-  # * OrchestrationProviderRegistry
-  # * Response
-  # * OrchestrationProvider
+  # * {ConfigurationService::Test::OrchestrationProviderRegistry} registry of imperative test orchestration providers
+  # * {ConfigurationService::Test::Response} configuration service response wrappers
+  # * {ConfigurationService::Test::OrchestrationProvider} abstract imperative test orchestration provider
   #
   module Test
 

data/lib/configuration_service/version.rb

@@ -1,5 +1,5 @@
 module ConfigurationService
 
-  VERSION = "2.0.4"
+  VERSION = "2.0.5"
 
 end

data/lib/configuration_service.rb

@@ -6,14 +6,14 @@ require "configuration_service/provider_registry"
 require "configuration_service/version"
 
 ##
-# See ConfigurationService::Base.
+# See {ConfigurationService::Base}.
 #
 module ConfigurationService
 
   ##
-  # Creates a new ConfigurationService::Base for the +provider+
+  # Creates a new {ConfigurationService::Base}
   #
-  # See Base.new.
+  # @see ConfigurationService::Base#initialize
   #
   def self.new(identifier, token, provider)
     ConfigurationService::Base.new(identifier, token, provider)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: configuration_service
 version: !ruby/object:Gem::Version
-  version: 2.0.4
+  version: 2.0.5
 platform: ruby
 authors:
 - Sheldon Hearn
@@ -91,8 +91,8 @@ files:
 - .gitignore
 - .rspec
 - .travis.yml
+- .yardopts
 - Gemfile
-- README.md
 - README.rdoc
 - Rakefile
 - features/authorization.feature
@@ -148,3 +148,4 @@ signing_key:
 specification_version: 4
 summary: Configuration service
 test_files: []
+has_rdoc: