configuration_service 2.0.4 → 2.0.5

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NWUxN2M4Yzc3YjM2MmJmZjE5NGQ4YWIwNmQxYjZiMzI3YTkzZDQ5NQ==
+    NjZmYTRlOWVjZTY2N2NlMjhlNjIwMTBmNmY2ZGU5YWVjZGYyMTY5OA==
   data.tar.gz: !binary |-
-    NTI2Yjg0YTgzYWEyZjU2OTdiNDIxYTgyY2ZjZWUyYWIwODg2ZWFhZQ==
+    YjQ2YzUwMWM1YTFlMWY5ZTM1MzBiOTgyM2I4ZDJlNWI3Y2U5OWVhYg==
 SHA512:
   metadata.gz: !binary |-
-    Y2M0NDZiYmYxMjQwNWE2NmI0ZmJlZjA0NTY1Yjg3ZDg1ZDhkNTk1OTQ5YjAy
-    ZWUwNzhkZGIyOWFmNWU0ZTA3Yjc3MGQ1YmE2MWU5NzVlYmMxYzA5Zjg5ODlk
-    NWMzYmJlZGIxZmFjYTcyNzYwYzU0NWY1NjQ2YmRiOWZmODc2MWE=
+    ZmU3YTI3OTcwMTBkMWQyYmMzNDZiNDQzMzU2MWMzODIzMGU3ZWY4ZWM1YWI3
+    ZGI2ZDYwOWNjOGUxMmQzOGEwYmQxMDUzZWEwMjkxNTIzNWVhNThmYjRmZWY2
+    YTQ3NmZiNmY4MzAzZDI2YTUwYTljY2RhYmU4YjQ1ZTcxMWFiYmU=
   data.tar.gz: !binary |-
-    ZGI1MjlkOTI5NzM0OWMzZTAyM2M0NmU0YTkzNzBlY2M0YTkxZmJjNmI4ODQ1
-    MjJlYjQ4MDliMTc4MWM3MjkyOTgzOGI1NWZjMWQyMjZlY2JkZmQ4NGFiNzBk
-    YjEyMGU5NWQzOTFhNjZlZTlkZDk1MjIyOWM2NzRkZGIwYmQ4ZTQ=
+    MTY0ZjJkZWYzNWI2ZDdlYjMzZDlkZWMzZmQ0MTg5Y2QyZDdjM2NjYWU4YjQ3
+    OWNiMzNhNzFkYzQ3OGJkMDc0NjQxNTAwMDExYzAzYjdiZWY0OWYzZDRiNDEx
+    OTNjMGZmZmY4YWY5NWQ5MGJjMGE1ZGUyNmVlNzRjYmY2NDk5MTY=

data/.yardopts

@@ -0,0 +1,3 @@
+--no-private
+-
+features/*.feature

data/README.rdoc

@@ -1,34 +1,32 @@
 = Configuration service
 
 The configuration service provides
-{authorized}[link:features/authorization_feature.html]
-{publication}[link:features/publishing_feature.html] and
-{consumption}[link:features/consuming_feature.html]
+{file:features/authorization.feature authorized}
+{file:features/publishing.feature publication} and
+{file:features/consuming.feature consumption}
 of identified configuration data with metadata.
+The service supports {file:features/bootstrapping.feature bootstrapping}.
 
-A pluggable Ruby API is provided in ConfigurationService::Base.
+A pluggable Ruby API is provided in {ConfigurationService::Base}.
 
-The declarative specification of the service is implemented with
-cucumber, using a pluggable imperative orchestration providers. This
-allows for implementations that are not providers to the Ruby API.
-See ConfigurationService::Test.
+The declarative specification of the service is implemented with cucumber, using a pluggable imperative orchestration providers.
+This allows for implementations that are not providers to the Ruby API.
+See {ConfigurationService::Test}.
 
-A stub service provider is provided in
-ConfigurationService::Provider::Stub. Other providers are avialable as gems.
+A stub service provider is provided in {ConfigurationService::Provider::Stub}.
+This is used to validate the test framework architecture, and may be used as a stub configuration service in tests.
+{https://rubygems.org/search?query=configuration_service-provider Other providers} are available as gems.
 
-Service providers are registered against the
-ConfigurationService::ProviderRegistry.
+Service providers are registered against the {ConfigurationService::ProviderRegistry}.
 
-Factories for creating and configuring service instances are provided in
-ConfigurationService::Factory.
+Factories for creating and configuring service instances are provided in {ConfigurationService::Factory}.
 
 == Usage
 
-The recommended approach to creating a configuration service client is to use
-a Factory.
+The recommended approach to creating a configuration service client is to use a {ConfigurationService::Factory Factory}.
 
-For example, we can use the EnvironmentContext factory to create and configure
-a configuration service client backed by the vault provider as follows.
+For example, we can use the {ConfigurationService::Factory::EnvironmentContext EnvironmentContext} factory
+to create and configure a configuration service client backed by the vault provider as follows.
 
 Our +main.rb+ (or +config.ru+ or whatever) is simple:
 
@@ -39,15 +37,15 @@ Our +main.rb+ (or +config.ru+ or whatever) is simple:
   configuraton = service.request_configuration
   AcmeApplication.new(configuration.data).run
 
-This relies on a bundler Gemfile to load the gem that contains whatever
-service provider we configure in the environment:
+This relies on a {http://bundler.io/ bundler} {http://bundler.io/gemfile.html Gemfile} to load the gem
+that contains whatever service provider we configure in the environment:
 
   source 'https://rubygems.org'
 
   gem 'configuration_service-provider-vault'
   gem 'acme_application'
 
-Now we use the process environment to configure the EnvironmentContext factory:
+Now we use the process environment to configure the {ConfigurationService::Factory::EnvironmentContext EnvironmentContext} factory:
 
   CFGSRV_IDENTIFIER="acme" \
   CFGSRV_TOKEN="0b2a80f4-54ce-45f4-8267-f6558fee64af" \
@@ -55,13 +53,14 @@ Now we use the process environment to configure the EnvironmentContext factory:
   CFGSRV_PROVIDER_ADDRESS="http://127.0.0.1:8200" \
   bundle exec main.rb
 
-Note that +main.rb+ is completely decoupled from the selection of provider and
-provider configuration. We could swap and/or reconfigure the provider by
-manipulating only the Gemfile and the environment.
+Note that +main.rb+ is completely decoupled from the selection of provider and provider configuration.
+We could swap and/or reconfigure the provider by manipulating only the +Gemfile+ and the environment.
 
-If you prefer to hard-code everything, or if your strategy for bootstrapping
-the configuration service isn't expressed by an existing factory yet, you can
-construct the service yourself:
+If you prefer to hard-code everything,
+or if your strategy for bootstrapping the configuration service isn't expressed by an existing factory yet,
+you can construct the service yourself:
+
+  # Bad example (hardcoding token into source):
 
   require 'configuration_service/provider/vault'
   require 'acme_application'

data/lib/configuration_service/base.rb

@@ -3,32 +3,28 @@ module ConfigurationService
   ##
   # The configuration service API
   #
-  # The service provides
-  # {authorized}[link:features/authorization_feature.html]
-  # {publication}[link:features/publishing_feature.html] and
-  # {consumption}[link:features/consuming_feature.html]
-  # of identified configuration data with metadata.
+  # See {file:README.rdoc} for a summary of the service, including links to user stories.
   #
-  # It is recommended that consumers use a Factory to create
-  # and configure the service.
+  # It is recommended that consumers use a {ConfigurationService::Factory} to create and configure the service.
   #
   class Base
 
     ##
-    # Creates a new API instance for the service +provider+
+    # Creates a new configuration service API instance
     #
-    # The +identifier+ is a string that uniquely identifies some configuration data and associated metadata.
-    # It might be the name of a service or service component. It might include an environment label (e.g.
-    # production, staging, etc.) For example:
+    # @param [String] identifier
+    #   the unique identity of some configuration data and its associated metadata.
+    #   It might be the name of a service or service component. It might include an environment label
+    #   (e.g. production, staging, etc.) For example:
     #
-    # * billing.acme.com
-    # * billing-web1.acme.com
-    # * billing/production/web1
-    #
-    # The +token+ is a string that authorizes the client to access the configuration data and associated metadata.
-    # Interpretation of the +token+ is provider-dependent; it is opaque to the API and client.
-    #
-    # The +provider+ is a configured service provider instance.
+    #   * billing.acme.com
+    #   * billing-web1.acme.com
+    #   * billing/production/web1
+    # @param [String] token
+    #   opaque string representing authority to access the configuration data and associated metadata.
+    #   Interpretation of the token is provider-dependent; it is opaque to the API and client.
+    # @param [Object] provider
+    #   a configured service provider instance, to which requests will be delegated.
     #
     def initialize(identifier, token, provider)
       @identifier = identifier
@@ -37,13 +33,13 @@ module ConfigurationService
     end
 
     ##
-    # Requests the configuration data and metadata for the +identifier+
+    # Requests the configuration data and metadata
     #
-    # Delegates the request to the provider.
+    # Delegates the request to the configured +provider+.
     #
-    # Returns a Configuration object or raises an Error on failure.
-    # Raises ConfigurationNotFoundError if no matching configuration
-    # was found.
+    # @return [ConfigurationService::Configuration] object containing the configuration data, metadata and identifier
+    # @raise [ConfigurationService::ConfigurationNotFoundError] if no configuration was found for the configured +identifier+
+    # @raise [ConfigurationService::Error] if the request failed
     #
     def request_configuration
       @provider.request_configuration(@identifier, @token) or
@@ -51,17 +47,25 @@ module ConfigurationService
     end
 
     ##
-    # Publishes configuration +data+ and optional +metadata+
+    # Publishes configuration data and metadata
     #
-    # The +data+ and the +metadata+ (if specified) must be dictionaries (responding to #to_hash or #to_h).
-    # The provider receives a a Configuration object, whose +metadata+ is decorated with the following keys:
+    # The +metadata+ is decorated with the following keys:
     #
     # * "timestamp" - the current UTC time in ISO8601 format
     # * "revision"  - a UUID for this publication
     #
-    # Returns a Configuration object or raises an Error on failure. When a Configuration object
-    # is returned, its +metadata+ is the decorated copy, allowing access to additional metadata
-    # added by the API or the provider.
+    # Delegates the request to the configured +provider+. The provider may further decorate the +metadata+.
+    #
+    # It is recommended that both the +data+ and +metadata+ dictionaries use strings as keys,
+    # and that values be limited to those that can be serialized to JSON.
+    #
+    # @param [Hash] data
+    #   dictionary of probably sensitive configuration data intended for an application, which providers are expected to secure
+    # @param [Hash] metadata
+    #   dictionary of data about the configuration data, which providers are not expected to secure
+    #
+    # @return [ConfigurationService::Configuration] object containing the configuration data, decorated metadata and identifier
+    # @raise [ConfigurationService::Error] if publication failed
     #
     def publish_configuration(data, metadata = {})
       dictionary?(data) or raise ConfigurationService::Error, "data must be a dictionary"

data/lib/configuration_service/configuration.rb

@@ -1,24 +1,28 @@
 module ConfigurationService
 
   ##
-  # Encapsulates configuration +data+ and its +metadata+
+  # Encapsulates identified configuration data and its metadata
   #
-  # * +identifier is the string identifier of the data and metadata.
-  # * +data+ is a dictionary of (possibly sensitive) configuration data,
-  #   which providers are expected to secure.
-  # * +metadata+ is a dictionary of data about the configuration data,
-  #   which providers are not expected to secure.
+  # @attr_reader [String] identifier
+  #   the unique identity of some configuration data and its associated metadata
+  # @attr_reader [Hash] data
+  #   dictionary of probably sensitive configuration data intended for an application, which providers are expected to secure
+  # @attr_reader [Hash] metadata
+  #   dictionary of data about the configuration data, which providers are not expected to secure
   #
-  # It is recommended that both dictionaries use strings as keys, and that
-  # values be limited to those that can be serialized to JSON.
+  # @see ConfigurationService::Base#publish_configuration
   #
   class Configuration
 
-    attr_reader :identifier, :data, :metadata # :nodoc:
+    attr_reader :identifier, :data, :metadata
 
     ##
     # Returns a new Configuration
     #
+    # @param [String] identifier unique identity
+    # @param [Hash] data sensitive configuration data
+    # @param [Hash] metadata non-sensitive configuration metadata
+    #
     def initialize(identifier, data, metadata)
       @identifier = identifier
       @data = data

data/lib/configuration_service/errors.rb

@@ -3,14 +3,11 @@ module ConfigurationService
   ##
   # The base of the configuration service exception tree
   #
-  # * Error
-  # * AuthorizationError
-  #
   class Error < StandardError
   end
 
   ##
-  # A configuration service authorization Error
+  # A configuration service authorization error
   #
   class AuthorizationError < Error
   end

data/lib/configuration_service/factory/environment_context/env_dict.rb

@@ -4,7 +4,7 @@ module ConfigurationService
 
     class EnvironmentContext
 
-      class EnvDict < Hash # :nodoc:
+      class EnvDict < Hash
 
         def initialize(env, *path)
           @env = env

data/lib/configuration_service/factory/environment_context.rb

@@ -3,7 +3,9 @@ module ConfigurationService
   module Factory
 
     ##
-    # Creates a Base bootstrapped with environmental configuration
+    # A factory for creating a configuration service bootstrapped from environmental configuration
+    #
+    # @example Requesting configuration from the {https://github.com/hetznerZA/configuration_service-provider-vault Vault service provider}
     #
     #   # With the following in the environment:
     #   #
@@ -25,17 +27,15 @@ module ConfigurationService
     #   require 'bundler'
     #   Bundler.require(:default) # Registers the vault provider
     #
-    #   service = ConfigurationService::Factory::EnvironmentContext.create
-    #   configuraton = service.request_configuration
+    #   configuration_service = ConfigurationService::Factory::EnvironmentContext.create
+    #   configuraton = configuration_service.request_configuration
     #   AcmeApplication.new(configuration.data).run
     #
+    # @attr_reader [String] prefix
+    #   prefix for matching environment variable names. Names match if they begin with the prefix and an underscore.
+    #
     class EnvironmentContext
 
-      ##
-      # The prefix for matching environment variable names
-      #
-      # Names match if they begin with the prefix and an underscore.
-      #
       attr_reader :prefix
 
       ##
@@ -46,11 +46,13 @@ module ConfigurationService
       ##
       # Returns a new factory
       #
-      # The +env+ defaults to the process ENV and the +prefix+ defaults
-      # to the DEFAULT_PREFIX.
+      # @param [Hash] env
+      #   the string-keyed environment
+      # @param [String] prefix
+      #   the prefix for matching environment variable names
       #
-      # Most consumers will not need to call this method; they can use
-      # .create which instantiates a factory with default +env+ and +prefix+
+      # Most consumers will not need to call this method;
+      # they can use {.create} which instantiates a factory with default +env+ and +prefix+
       # and uses that internally.
       #
       def initialize(env = ENV, prefix = DEFAULT_PREFIX)
@@ -58,33 +60,30 @@ module ConfigurationService
       end
 
       ##
-      # Return a Base bootstrapped with environmental configuration
+      # Create a configuration service bootstrapped with environmental configuration
       #
-      # The environment is scanned for #prefix matches, within which
-      # the following variables are used:
+      # The environment is scanned for {#prefix} matches, within which the following variables are used:
       #
       # [IDENTIFIER] the unique identity of the configuration data
-      #              (see Base#initialize)
+      #              (see {ConfigurationService::Base#initialize})
       # [TOKEN]      authorization token for the identified configuration data
-      #              (see Base#initialize)
+      #              (see {ConfigurationService::Base#initialize})
       # [PROVIDER]   the unique identity of the service provider
-      #              (see ProviderRegistry)
+      #              (see {ConfigurationService::ProviderRegistry})
       # [PROVIDER_*] configuration options for the service provider
-      #              (see provider documentation)
+      #              (see service provider documentation)
       #
-      # The service provider class is fetched from the ProviderRegistry using
-      # +PROVIDER+. A service provider instance is then constructed with a
-      # dictionary of the +PROVIDER_*+ variables, in which the keys are the
-      # name of the variable without +PROVIDER_+, downcased and intern'd.
+      # The service provider class is fetched from the {ConfigurationService::ProviderRegistry} using +PROVIDER+.
+      # A service provider instance is then constructed with a dictionary of the +PROVIDER_*+ variables,
+      # in which the keys are the name of the variable without +PROVIDER_+, downcased and intern'd.
       #
-      # Then a service Base is constructed with the +IDENTIFIER+, +TOKEN+
-      # and service provider instance.
+      # Then a service {ConfigurationService::Base} is constructed with the +IDENTIFIER+, +TOKEN+ and service provider instance.
       #
-      # And finally, the environment is scrubbed of the variables used, to
-      # protect them from accidental exposure (e.g. in an exception handler
-      # that prints the environment).
+      # And finally, the environment is scrubbed of the variables used, to protect them from accidental exposure
+      # (e.g. in an exception handler that prints the environment).
       #
-      # Returns the constructed service Base.
+      # @return [ConfigurationService::Base] the configuration service instance created
+      # @raise [ProviderNotFoundError] if no service provider has been registered with the name given by +PROVIDER+
       #
       def create
         ConfigurationService.new(@env[:identifier], @env[:token], provider).tap do
@@ -93,11 +92,11 @@ module ConfigurationService
       end
 
       ##
-      # Return a Base bootstrapped with environmental configuration
+      # Return a configuration service bootstrapped with environmental configuration
       #
-      # See #create.
+      # Instantiates a new factory with the process +ENV+ and the {DEFAULT_PREFIX} and uses it to create a configuration service.
       #
-      # Uses the process ENV and the DEFAULT_PREFIX.
+      # @see #create
       #
       def self.create
         new.create

data/lib/configuration_service/factory.rb

@@ -3,11 +3,7 @@ Dir.glob(File.expand_path("../factory/**/*.rb", __FILE__), &method(:require))
 module ConfigurationService
 
   ##
-  # Module containing configuration service factory classes
-  #
-  # Current implementations provided by this package:
-  #
-  # * EnvironmentContext
+  # Configuration service factories
   #
   module Factory
 

data/lib/configuration_service/provider/broken.rb

@@ -3,21 +3,21 @@ module ConfigurationService
   module Provider
 
     ##
-    # A stub broken ConfigurationService::Base service provider
+    # A stub broken {ConfigurationService::Base} service provider
     #
     # Used to validate the test framework architecture.
     #
     class Broken
 
       ##
-      # Raises Error
+      # @raise [ConfigurationService::Error] always
       #
       def publish_configuration(configuration, token)
         raise ConfigurationService::Error, "error requested by test"
       end
 
       ##
-      # Raises Error
+      # @raise [ConfigurationService::Error] always
       #
       def request_configuration(identifier, token)
         raise ConfigurationService::Error, "error requested by test"

data/lib/configuration_service/provider/stub.rb

@@ -10,17 +10,14 @@ module ConfigurationService
   module Provider
 
     ##
-    # A stub ConfigurationService::Base service provider
+    # A stub configuration service provider
     #
     # Used to validate the test framework architecture.
     #
-    # Registered into the ProviderRegistry with identifier "stub".
+    # It is registered into the {ConfigurationService::ProviderRegistry} with identifier "stub".
     #
     class Stub
 
-      ##
-      # Maps roles to authorization tokens
-      #
       BUILTIN_TOKENS = {
         :consumer  => '64867ebd-6364-0bd3-3fda-81-requestor',
         :publisher => 'f53606cb-7f3c-4432-afe8-44-publisher',
@@ -28,10 +25,10 @@ module ConfigurationService
       } unless defined?(BUILTIN_TOKENS)
 
       ##
-      # Returns a new Stub
       #
-      # It requires an arbitrary +name+, used solely for testing factory
-      # methods.
+      # @param [Hash] options
+      # @option options [String]
+      #   :name arbitrary name, used solely for testing factory methods
       #
       def initialize(options = {})
         @name = options[:name] or raise ArgumentError, "missing required argument: name"
@@ -39,16 +36,15 @@ module ConfigurationService
       end
 
       ##
-      # Requests configuration data and metadata
-      #
-      # See Base#request_configuration.
+      # Request configuration
       #
-      # Fetches configuration from the singleton StubStore.
+      # Fetches configuration from the singleton {ConfigurationService::StubStore}.
       #
-      # Returns a Configuration object or raises AuthorizationError if the
-      # +token+ is not for the +:consumer+ role.
+      # @return [ConfigurationService::Configuration] if authorized and found
+      # @return [nil] if not found
+      # @raise [ConfigurationService::AuthorizationError] if not authorized for the +:consumer+ role
       #
-      # Returns +nil+ if no configuration was found for the +identifier+.
+      # @see ConfigurationService::Base#request_configuration
       #
       def request_configuration(identifier, token)
         authorize_request(:consumer, token)
@@ -59,13 +55,14 @@ module ConfigurationService
       end
 
       ##
-      # Publishes configuration
+      # Publish configuration
       #
-      # See Base#publish_configuration.
+      # @param [ConfigurationService::Configuration] configuration configuration to publish
       #
-      # +configuration+ should be a Configuration object or similar.
+      # @return [ConfigurationService::Configuration] published configuration
+      # @raise [ConfigurationService::Error] on failure.
       #
-      # Returns a Configuration object or raises an Error on failure.
+      # @see ConfigurationService::Base#publish_configuration
       #
       def publish_configuration(configuration, token)
         authorize_request(:publisher, token)

data/lib/configuration_service/provider/stub_store.rb

@@ -9,45 +9,65 @@ unless defined?(ConfigurationService::Provider::StubStore)
       ##
       # A singleton store for the Stub service provider
       #
+      # @example Storing data and metadata
+      #
+      #   data = {"username" => "sheldonh", "password" => "secret123"}
+      #   metadata = {"version" => "1.0.0"}
+      #   StubStore.instance.store("acme", data, metadata)
+      #
+      # @example Fetching data and metadata
+      #
+      #   data, metadata = StubStore.instance.fetch("acme")
+      #   # data     -> {"username" => "sheldonh", "password" => "secret123"}
+      #   # metadata -> {"version" => "1.0.0"}
+      #
+      # @!method self.instance
+      #   The singleton registry instance
+      #
+      #   @return [ConfigurationService::ProviderRegistry] singleton instance
+      #
       class StubStore
 
         include Singleton
 
-        def initialize # :nodoc:
-          @configurations = {}
-        end
-
         ##
-        # Returns the configuration data and metadata for +identifier+
+        # Fetch configuration data and metadata
         #
-        # The dictionaries are returned as an array, to be used as follows:
+        # @param [String] identifier the configuration identifier
         #
-        #   data, metadata = StubStore.instance.fetch("acme")
+        # @return [Array<Hash>] data and metadata as a tuple
         #
         def fetch(identifier)
           @configurations.fetch(identifier)
         end
 
         ##
-        # Stores the +data+ and +metadata associated with the +identifier+
+        # Store configuration data and metadata
+        #
+        # @param [String] identifier the configuration identifier
+        # @param [Hash] data the configuration data
+        # @param [Hash] metadata the configuration metadata
         #
         def store(identifier, data, metadata)
           @configurations.store(identifier, [data, metadata])
         end
 
         ##
-        # Deletes the data and metadata associated with the +identifier+
+        # Delete configuration data and metadata
+        #
+        # It is not an error to delete non-existent configuration
         #
-        # It is not an error to delete a non-existent +identifier+
+        # @param [String] identifier the configuration identifier
         #
         def delete(identifier)
           @configurations.delete(identifier)
           nil
         end
 
-        ##
-        # Return the singleton store instance
-        # :singleton-method: instance
+        # @private
+        def initialize
+          @configurations = {}
+        end
 
       end
 

data/lib/configuration_service/provider.rb

@@ -1,11 +1,10 @@
 module ConfigurationService
 
   ##
-  # A configuration service provider is an imperative implementation
-  # of the ConfigurationService API, to be plugged into a
-  # ConfigurationService::Base.
+  # A configuration service provider is an imperative implementation of the configuration service API,
+  # to be plugged into a {ConfigurationService::Base}.
   #
-  # A Stub implementation is provided to validate the test framework architecture.
+  # A {ConfigurationService::Provider::Stub} implementation is provided to validate the test framework architecture.
   #
   module Provider
   end