configuration_service 2.1.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: edd7e401896ff28294ff48a3de1efcb4ff421ba4
-  data.tar.gz: 9d839d5159631e31c845a84165058a19ca369af3
+  metadata.gz: d695abf3843bb642d1bfed73e61ad6be4675007f
+  data.tar.gz: 23ff9de0ec5d4911aa5f83a96919527ed53f115a
 SHA512:
-  metadata.gz: 9a11deec68d0ec63f6a0502a62d1feae552b7f552bca92d63f8627a431860322f9c2acc39a79e1f4cbdc965102d877e98d3dbb24069461a9b9006bc8ce8728ef
-  data.tar.gz: 567661134fd7d41f715d96c5b48db0f8b5e6eb23a2017ad82518f3010767aa356b5f26df58ad7a4adb96f83281335bfd4c84f72cc123976c90f7ccc84dabaf7a
+  metadata.gz: 958979a72b6b19483a5983b8da46e1e6c01ce9febd67c0fac74c0a42128117d7218bcfd178a443fcadd3b214b4dc4d34e059e5f5183ffc23ee14b6632be28132
+  data.tar.gz: dec28262702b779b8ec85b453f1441dcb006475e68b859182772074f92ebbc6d2d0e47229659f7b17cccb9f706570ca229d649935b0b625b4e7dc05c5a76e4f5

data/.gitignore

@@ -35,3 +35,7 @@ build/
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
+
+# vim
+*.swp
+*.swo

data/README.rdoc

@@ -19,13 +19,13 @@ This is used to validate the test framework architecture, and may be used as a s
 
 Service providers are registered against the {ConfigurationService::ProviderRegistry}.
 
-Factories for creating and configuring service instances are provided in {ConfigurationService::Factory}.
+Clients can be constructed with by the {ConfigurationService::Factory}.
 
 == Usage
 
-The recommended approach to creating a configuration service client is to use a {ConfigurationService::Factory Factory}.
+The recommended approach to creating a configuration service client is to use the {ConfigurationService::Factory Factory}.
 
-For example, we can use the {ConfigurationService::Factory::EnvironmentContext EnvironmentContext} factory
+For example, we can use the 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:
@@ -33,7 +33,7 @@ Our +main.rb+ (or +config.ru+ or whatever) is simple:
   require 'bundler'
   Bundler.require(:default)
 
-  service = ConfigurationService::Factory::EnvironmentContext.create
+  service = ConfigurationService::Factory.create_client
   configuraton = service.request_configuration
   AcmeApplication.new(configuration.data).run
 
@@ -45,7 +45,7 @@ that contains whatever service provider we configure in the environment:
   gem 'configuration_service-provider-vault'
   gem 'acme_application'
 
-Now we use the process environment to configure the {ConfigurationService::Factory::EnvironmentContext EnvironmentContext} factory:
+Now we use the process environment to specify the factory context:
 
   CFGSRV_IDENTIFIER="acme" \
   CFGSRV_TOKEN="0b2a80f4-54ce-45f4-8267-f6558fee64af" \
@@ -56,22 +56,78 @@ Now we use the process environment to configure the {ConfigurationService::Facto
 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:
+=== Administrative client
 
-  # Bad example (hardcoding token into source):
+The factory in the example above uses the process environment and (on JRuby) system properties as its context
+because {ConfigurationService::Factory.create_client} defaults to {ConfigurationService::Factory::EnvironmentContext}.
+To better understand the factory context, consider the example of a simple configuration service frontend
+that needs an {ConfigurationService::AdminClient AdminClient} for administrative access to the service:
 
-  require 'configuration_service/provider/vault'
-  require 'acme_application'
-
-  service = ConfigurationService.new(
-    "acme",
-    "0b2a80f4-54ce-45f4-8267-f6558fee64af",
-    ConfigurationService::Provider::Vault.new(
-      address: "http://127.0.0.1:8200"
-    )
+  # Bad example (see below for discussion)
+  context = ConfigurationService::Factory::Context.new(
+    "token" => "c3935418-f621-40de-ada3-cc8169f1348a",
+    "provider_id" => "vault",
+    "provider_config" => {
+      "address" => "http://127.0.0.1:8200"
+    }
   )
-  configuraton = service.request_configuration
-  AcmeApplication.new(configuration.data).run
+  admin_client = ConfigurationService::Factory.create_admin_client(context)
+
+  app = Rack::Builder.new do
+    map "/configurations" do
+      run ->(env) { [200, {'Content-Type' => 'application/json'}, [admin_client.list_configurations.to_json] }
+    end
+  end
+  run app
+
+The example above is terrible because it hardcodes an administrative token into the source.
+In practice, the administrative context would most likely come from the configuration service itself.
+
+=== Complex example
+
+In the following example, the {ConfigurationService::Factory} defaults to using the
+{ConfigurationService::Factory::EnvironmentContext EnvironmentContext} to acquire application configuration
+from a non-administrative {ConfigurationService::Base} client.
+Part of the application configuration is then used as the context for an administrative {ConfigurationService::AdminClient},
+which is used as a model in the application.
+
+  configuration = ConfigurationService::Factory.create_client.request_configuration
+  app_name = configuration.data["app_name"]
+  admin_client = ConfigurationService::Factory.create_admin_client(configuration.data["cs_config"])
+
+  app = Rack::Builder.new do
+    map "/" do
+      run ->(env) { [200, {"Content-Type" => "application/json"}, ["Welcome to #{app_name}"]] }
+    end
+    map "/configurations" do
+      run ->(env) { [200, {'Content-Type' => 'application/json'}, [admin_client.list_configurations.to_json] }
+    end
+  end
+  run app
+
+The above code would rely on configuration data that looked something like this:
+
+  ---
+  app_name: ACME config service UI
+  cs_config:
+    token: c3935418-f621-40de-ada3-cc8169f1348a
+    interface: admin
+    provider_id: vault
+    provider_config:
+      address: http://127.0.0.1:8200
+
+If this configuration data was stored under the configuration identifier "acme", then access to the data
+(via {ConfigurationService::Factory::EnvironmentContext}) would be arranged with a process environment like this:
+
+  CFGSRV_IDENTIFIER="acme" \
+  CFGSRV_TOKEN="0b2a80f4-54ce-45f4-8267-f6558fee64af" \
+  CFGSRV_PROVIDER="vault" \
+  CFGSRV_PROVIDER_ADDRESS="http://127.0.0.1:8200" \
+  bundle exec main.rb
 
+So this application would use the token "0b2...4af" to access its configuration data
+under the identifier "acme"
+with a non-administrative {ConfigurationService::Base} client.
+Part of its configuration data, in this case under the key "cs_config",
+provides {ConfigurationService::Factory::Context} for creating an administrative {ConfigurationService::AdminClient},
+which it would then use the token "c39...48a" to operate over multiple configuration identifiers on behalf of users.

data/features/consuming.feature

@@ -1,7 +1,7 @@
 @consuming @consume
 Feature: Consuming configuration data
   In order to access configuration data
-  As a Consumer
+  As a consumer 
   I want to request access to configuration data
 
   Scenario: Metadata-free hit

data/features/listing.feature

@@ -0,0 +1,8 @@
+@listing @list
+Feature: Listing configurations
+    In order to identify a specific configuration
+    As an administrator
+    I want to see a list of published configurations
+
+    Scenario: pending
+

data/features/publishing.feature

@@ -1,7 +1,7 @@
 @publishing @publish
 Feature: Publishing configuration data
   In order to make configuration data available for retrieval
-  As a publisher
+  As a publisher 
   I want to publish configuration data
 
   Scenario: Revision added to metadata

data/lib/configuration_service/admin_client.rb

@@ -0,0 +1,44 @@
+require "configuration_service/utils"
+
+module ConfigurationService
+  class AdminClient
+
+    ##
+    # @param [String] token
+    # @param [String] provider
+    # @return [ConfigurationService::AdminClient] object
+    #
+    def initialize(token, provider)
+      @token = token
+      @provider = provider
+    end
+
+    ##
+    # @param [String] identifier
+    # @return [ConfigurationService::Configuration] the requested configuration
+    # @raise [ConfigurationService::ConfigurationNotFoundError]
+    #
+    def request_configuration(identifier)
+      @provider.request_configuration(identifier, @token) or 
+        raise ConfigurationNotFoundError, "configuration not found for identifier: #{identifier}"
+    end
+
+    ##
+    # @param [String] identifier
+    # @param [Hash] data
+    # @param [Hash] metadata
+    # @return [ConfigurationService::Configuration] the published configuration
+    # @raise [ConfigurationaService::Error] if data or metadata is not a hash
+    #
+    def publish_configuration(identifier, data, metadata = {})
+      Utils.dictionary?(data) or raise ConfigurationService::Error, "data must be a dictionary"
+      Utils.dictionary?(metadata) or raise ConfigurationService::Error, "metadata must be a dictionary"
+
+      metadata = Utils.decorate(metadata)
+      configuration = Configuration.new(identifier, data, metadata)
+      @provider.publish_configuration(configuration, @token)
+    end
+
+  end
+
+end

data/lib/configuration_service/base.rb

@@ -1,4 +1,5 @@
 require "securerandom"
+require "configuration_service/utils"
 
 module ConfigurationService
 
@@ -70,26 +71,14 @@ module ConfigurationService
     # @raise [ConfigurationService::Error] if publication failed
     #
     def publish_configuration(data, metadata = {})
-      dictionary?(data) or raise ConfigurationService::Error, "data must be a dictionary"
-      dictionary?(metadata) or raise ConfigurationService::Error, "metadata must be a dictionary"
+      Utils.dictionary?(data) or raise ConfigurationService::Error, "data must be a dictionary"
+      Utils.dictionary?(metadata) or raise ConfigurationService::Error, "metadata must be a dictionary"
 
-      metadata = decorate(metadata)
+      metadata = Utils.decorate(metadata)
       configuration = Configuration.new(@identifier, data, metadata)
       @provider.publish_configuration(configuration, @token)
     end
 
-    private
-
-      def dictionary?(o)
-        o.respond_to?(:to_hash) or o.respond_to?(:to_h)
-      end
-
-      def decorate(metadata)
-        revision = SecureRandom.uuid
-        metadata = metadata.merge("revision" => revision) unless metadata["revision"]
-        metadata = metadata.merge("timestamp" => Time.now.utc.iso8601) unless metadata["timestamp"]
-      end
-
   end
 
 end

data/lib/configuration_service/factory/context/symbolic_access_wrapper.rb

@@ -0,0 +1,44 @@
+module ConfigurationService
+
+  module Factory
+
+    class Context
+
+      class SymbolicAccessWrapper < Hash
+
+        def initialize(hash)
+          hash.each do |k, v|
+            if v.is_a?(Hash)
+              self.store(k.intern, self.class.new(v))
+            else
+              self.store(k.intern, v)
+            end
+          end
+          self.default_proc = indifferent_access_default_proc
+        end
+
+        private
+
+          def indifferent_access_default_proc
+            proc do |_, key|
+              try_string(key) or raise_key_error(key)
+            end
+          end
+
+          def try_string(k)
+            if (skey = k.intern rescue false) and self.include?(skey)
+              self.fetch(skey)
+            end
+          end
+
+          def raise_key_error(k)
+            raise KeyError, "missing key #{k}"
+          end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/configuration_service/factory/context.rb

@@ -0,0 +1,84 @@
+module ConfigurationService
+
+  module Factory
+
+    ##
+    # A factory context for static factory configuration
+    #
+    # The typical use case for this class is in constructing an {ConfigurationService::AdminClient AdminClient}
+    # using a data structure acquired from a secure source that does not need to be scrubbed.
+    #
+    # @see ConfigurationService::Factory.create_client
+    # @see ConfigurationService::Factory.create_admin_client
+    #
+    class Context
+
+      ##
+      # Returns a new factory context
+      #
+      # @param [Hash] source
+      #   a string- or symbol-keyed dictionary source
+      #
+      # The following keys are used by the {ConfigurationService::Factory}:
+      #
+      # [identifier]      the unique identity of the configuration data
+      #                   (see {ConfigurationService::Base#initialize})
+      # [token]           authorization token for the identified configuration data
+      #                   (see {ConfigurationService::Base#initialize})
+      # [provider_id]     the unique identity of the service provider
+      #                   (see {ConfigurationService::ProviderRegistry})
+      # [provider_config] configuration options for the service provider
+      #                   (see service provider documentation)
+      #
+      def initialize(source)
+        @env = SymbolicAccessWrapper.new(source)
+      end
+
+      ##
+      # The unique identity of the configuration data
+      #
+      # Required for {ConfigurationService::Base}. Not used by {ConfigurationService::AdminClient}.
+      #
+      def identifier
+        @env[:identifier]
+      end
+
+      ##
+      # Authorization token for the identified configuration data
+      #
+      def token
+        @env[:token]
+      end
+
+      ##
+      # The unique identity of the service provider
+      #
+      # @see ConfigurationService::ProviderRegistry
+      #
+      def provider_id
+        @env[:provider_id]
+      end
+
+      ##
+      # Configuration options for the service provider
+      #
+      # See service provider documentation.
+      #
+      def provider_config
+        @env[:provider_config]
+      end
+
+      ##
+      # Does nothing
+      #
+      # The source is assumed to be secure. Sources such as the process +ENV+ and (on JRuby) system properties
+      # should not be used with this class; instead, they should be accessed through {ConfigurationService::Factory::EnvironmentContext}.
+      #
+      def scrub!
+      end
+
+    end
+
+  end
+
+end

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

@@ -0,0 +1,89 @@
+module ConfigurationService
+
+  module Factory
+
+    class EnvironmentContext
+
+      ##
+      # Support {ConfigurationService::Factory::EnvironmentContext}'s deprecated use as a factory
+      #
+      # New code should use {ConfigurationService::Factory} instead.
+      #
+      module BackwardCompatibility
+
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        ##
+        # Create a configuration service bootstrapped with environmental configuration
+        #
+        # The environment is scanned for {#prefix} matches, within which the following variables are used:
+        #
+        # [IDENTIFIER] the unique identity of the configuration data
+        #              (see {ConfigurationService::Base#initialize})
+        # [TOKEN]      authorization token for the identified configuration data
+        #              (see {ConfigurationService::Base#initialize})
+        # [PROVIDER]   the unique identity of the service provider
+        #              (see {ConfigurationService::ProviderRegistry})
+        # [PROVIDER_*] configuration options for the service provider
+        #              (see service provider documentation)
+        #
+        # On JRuby, system properties are also scanned. Where a system property and environment variable of the
+        # same name exist, the environment variable is preferred.
+        #
+        # 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 {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). On JRuby, system properties are scrubbed of variables used as well,
+        # regardless of whether they were overridden by environment variables.
+        #
+        # @return [ConfigurationService::Base] the configuration service instance created
+        # @raise [ProviderNotFoundError] if no service provider has been registered with the name given by +PROVIDER+
+        #
+        # @deprecated Use {ConfigurationService::Factory} instead.
+        #
+        def create
+          ConfigurationService.new(@env[:identifier], @env[:token], provider).tap do
+            scrub!
+          end
+        end
+
+        module ClassMethods
+
+          ##
+          # Return a configuration service bootstrapped with environmental configuration
+          #
+          # Instantiates a new factory with the process +ENV+ and the {DEFAULT_PREFIX} and uses it to create a configuration service.
+          #
+          # @see ConfigurationService::Factory::EnvironmentContext::BackwardCompatibility#create
+          #
+          # @deprecated Use {ConfigurationService::Factory} instead.
+          #
+          def create
+            new.create
+          end
+
+        end
+
+        private
+
+          def provider
+            provider_id = @env[:provider]
+            provider_config = @env.subslice(:provider)
+            provider_class = ConfigurationService::ProviderRegistry.instance.lookup(provider_id)
+            provider_class or raise ProviderNotFoundError, "provider not registered: #{provider_id}"
+            provider_class.new(provider_config)
+          end
+
+      end
+
+    end
+
+  end
+
+end

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

@@ -24,11 +24,6 @@ module ConfigurationService
           end
         end
 
-        def subslice!(key)
-          delete_keys_prefixed_with!(key)
-          subslice(key)
-        end
-
         def scrub!
           @path or raise RuntimeError, "refusing to scrub without path"
 
@@ -84,14 +79,6 @@ module ConfigurationService
             end
           end
 
-          def delete_keys_prefixed_with!(key)
-            self.keys.each do |k|
-              if k.to_s.start_with?("#{key}_")
-                self.delete(k)
-              end
-            end
-          end
-
           def assert_not_scrubbed!
             !@scrubbed or raise SecurityError, "can't access scrubbed environment dictionary"
           end

data/lib/configuration_service/factory/environment_context.rb

@@ -1,41 +1,25 @@
+require_relative "environment_context/backward_compatibility"
+
 module ConfigurationService
 
   module Factory
 
     ##
-    # 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:
-    #   #
-    #   # CFGSRV_IDENTIFIER="acme"
-    #   # CFGSRV_TOKEN="0b2a80f4-54ce-45f4-8267-f6558fee64af"
-    #   # CFGSRV_PROVIDER="vault"
-    #   # CFGSRV_PROVIDER_ADDRESS="http://127.0.0.1:8200"
-    #
-    #   # And the following in Gemfile:
-    #   #
-    #   # source 'https://rubygems.org'
-    #   #
-    #   # gem 'configuration_service-provider-vault'
-    #   # gem 'acme_application'
-    #
-    #   # Now main.rb (or config.ru or whatever) is decoupled from provider
-    #   # selection and service configuration:
+    # A factory context for the process +ENV+ and (on JRuby) system properties
     #
-    #   require 'bundler'
-    #   Bundler.require(:default) # Registers the vault provider
+    # Most consumers will not need to interact with this class directly.
+    # It is used by {ConfigurationService::Factory} to create the default factory context
+    # if none is specified.
     #
-    #   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.
+    # Prior to version 2.2.0, this class provided factory functionality.
+    # Use of this class as a factory is deprecated, supported through the
+    # {ConfigurationService::Factory::EnvironmentContext::BackwardCompatibility} module.
+    # Consumers should use {ConfigurationService::Factory} instead.
     #
     class EnvironmentContext
 
+      include BackwardCompatibility
+
       attr_reader :prefix
 
       ##
@@ -44,25 +28,14 @@ module ConfigurationService
       DEFAULT_PREFIX = "CFGSRV" unless defined?(DEFAULT_PREFIX)
 
       ##
-      # Returns a new factory
+      # Returns a new factory context
       #
       # @param [Hash, Array<Hash>] sources
       #   one or a list of the string-keyed environments
       # @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+
-      # and uses that internally.
-      #
-      def initialize(sources = default_sources, prefix = DEFAULT_PREFIX)
-        @env = EnvDict.new(sources, prefix)
-      end
-
-      ##
-      # Create a configuration service bootstrapped with environmental configuration
-      #
-      # The environment is scanned for {#prefix} matches, within which the following variables are used:
+      # The sources are scanned for {#prefix} matches, within which the following variables are used:
       #
       # [IDENTIFIER] the unique identity of the configuration data
       #              (see {ConfigurationService::Base#initialize})
@@ -73,37 +46,49 @@ module ConfigurationService
       # [PROVIDER_*] configuration options for the service provider
       #              (see service provider documentation)
       #
-      # On JRuby, system properties are also scanned. Where a system property and environment variable of the
-      # same name exist, the environment variable is preferred.
-      #
-      # 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 {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). On JRuby, system properties are scrubbed of variables used as well,
-      # regardless of whether they were overridden by environment variables.
-      #
-      # @return [ConfigurationService::Base] the configuration service instance created
-      # @raise [ProviderNotFoundError] if no service provider has been registered with the name given by +PROVIDER+
+      # If sources are not specified, the process +ENV+ and (on JRuby) system properties are used.
+      # Where a system property and environment variable of the same name exist,
+      # the environment variable is preferred.
       #
-      def create
-        ConfigurationService.new(@env[:identifier], @env[:token], provider).tap do
-          @env.scrub!
-        end
+      def initialize(sources = default_sources, prefix = DEFAULT_PREFIX)
+        @env = EnvDict.new(sources, prefix)
+      end
+
+      ##
+      # @see ConfigurationService::Factory::Context#identifier
+      def identifier
+        @env[:identifier]
+      end
+
+      ##
+      # @see ConfigurationService::Factory::Context#token
+      def token
+        @env[:token]
       end
 
       ##
-      # Return a configuration service bootstrapped with environmental configuration
+      # @see ConfigurationService::Factory::Context#provider_id
+      def provider_id
+        @env[:provider]
+      end
+
+      ##
+      # @see ConfigurationService::Factory::Context#provider_config
+      def provider_config
+        @env.subslice(:provider)
+      end
+
+      ##
+      # Scrub sources
       #
-      # Instantiates a new factory with the process +ENV+ and the {DEFAULT_PREFIX} and uses it to create a configuration service.
+      # Called by the {ConfigurationService::Factory} after the client is created,
+      # to prevent in-process compromise of the context (e.g. by an exception handler
+      # that dumps the environment in a web application).
       #
-      # @see #create
+      # Every property that matches the prefix is removed from all sources.
       #
-      def self.create
-        new.create
+      def scrub!
+        @env.scrub!
       end
 
       private
@@ -112,14 +97,6 @@ module ConfigurationService
           (RUBY_PLATFORM == "java" ? [java.lang.System.properties, ENV] : ENV)
         end
 
-        def provider
-          provider_id = @env[:provider]
-          provider_config = @env.subslice(:provider)
-          provider_class = ConfigurationService::ProviderRegistry.instance.lookup(provider_id)
-          provider_class or raise ProviderNotFoundError, "provider not registered: #{provider_id}"
-          provider_class.new(provider_config)
-        end
-
     end
 
   end

data/lib/configuration_service/factory.rb

@@ -3,10 +3,101 @@ Dir.glob(File.expand_path("../factory/**/*.rb", __FILE__), &method(:require))
 module ConfigurationService
 
   ##
-  # Configuration service factories
+  # A factory for creating a configuration service client
+  #
+  # @example Requesting configuration from the {https://github.com/hetznerZA/configuration_service-provider-vault Vault service provider}
+  #
+  #   # With the following in the environment:
+  #   #
+  #   # CFGSRV_IDENTIFIER="acme"
+  #   # CFGSRV_TOKEN="0b2a80f4-54ce-45f4-8267-f6558fee64af"
+  #   # CFGSRV_PROVIDER="vault"
+  #   # CFGSRV_PROVIDER_ADDRESS="http://127.0.0.1:8200"
+  #
+  #   # And the following in Gemfile:
+  #   #
+  #   # source 'https://rubygems.org'
+  #   #
+  #   # gem 'configuration_service-provider-vault'
+  #   # gem 'acme_application'
+  #
+  #   # Now main.rb (or config.ru or whatever) is decoupled from provider
+  #   # selection and service configuration:
+  #
+  #   require 'bundler'
+  #   Bundler.require(:default) # Registers the vault provider
+  #
+  #   configuration_service = ConfigurationService::Factory.create_client
+  #   configuraton = configuration_service.request_configuration
+  #   AcmeApplication.new(configuration.data).run
+  #
+  # @example Creating an {ConfigurationService::AdminClient AdminClient} with static bootstrap configuration
+  #
+  #   admin_client = ConfigurationService::Factory.create_admin_client(
+  #     "token" => "c3935418-f621-40de-ada3-cc8169f1348a",
+  #     "provider_id" => "vault",
+  #     "provider_config" => {
+  #       "address" => "http://127.0.0.1:8200"
+  #     }
+  #   )
   #
   module Factory
 
+    ##
+    # Create a configuration service client
+    #
+    # @param [ConfigurationService::Factory::EnvironmentContext, ConfigurationService::Factory::Context, Hash] context
+    #   the factory context
+    # @return [ConfigurationService::Base] the configuration service client created
+    #
+    # When the +context+ is a Hash, it is wrapped in a {ConfigurationService::Factory::Context}, which does not scrub
+    # sources after the configuration service client is created. For this reason, the process +ENV+ should never
+    # be given as the +context+; rather give no +context+, so that the default {ConfigurationService::Factory::EnvironmentContext}
+    # will be used to safely scrub the process +ENV+ and (on JRuby) system properties after the configuration service client is created.
+    #
+    # The context must provide an +identifier+ property.
+    #
+    def self.create_client(context = EnvironmentContext.new)
+      context = Context.new(context) if context.is_a?(Hash)
+      provider = create_provider(context)
+      ConfigurationService::Base.new(context.identifier, context.token, provider)
+    ensure
+      context.scrub!
+    end
+
+    ##
+    # Create a configuration service admin client
+    #
+    # @param [ConfigurationService::Factory::EnvironmentContext, ConfigurationService::Factory::Context, Hash] context
+    #   the factory context
+    # @return [ConfigurationService::AdminClient] the configuration service admin client created
+    #
+    # When the +context+ is a Hash, it is wrapped in a {ConfigurationService::Factory::Context}, which does not scrub
+    # sources after the configuration service client is created. For this reason, the process +ENV+ should never
+    # be given as the +context+; rather give no +context+, so that the default {ConfigurationService::Factory::EnvironmentContext}
+    # will be used to safely scrub the process +ENV+ and (on JRuby) system properties after the configuration service client is created.
+    #
+    # Because the {ConfigurationService::AdminClient} operates over multiple configuration identifiers,
+    # it does not require an +identifier+ property from the context.
+    #
+    def self.create_admin_client(context = EnvironmentContext.new)
+      context = Context.new(context) if context.is_a?(Hash)
+      provider = create_provider(context)
+      ConfigurationService::AdminClient.new(context.token, provider)
+    ensure
+      context.scrub!
+    end
+
+    private
+
+    def self.create_provider(context)
+      provider_id = context.provider_id
+      provider_config = context.provider_config
+      provider_class = ConfigurationService::ProviderRegistry.instance.lookup(provider_id)
+      provider_class or raise ProviderNotFoundError, "provider not registered: #{provider_id}"
+      provider_class.new(provider_config)
+    end
+
   end
 
 end

data/lib/configuration_service/provider/stub.rb

@@ -19,6 +19,7 @@ module ConfigurationService
     class Stub
 
       BUILTIN_TOKENS = {
+        :admin => 'b72b9ae7-3849-a335-67b6-administrator',
         :consumer  => '64867ebd-6364-0bd3-3fda-81-requestor',
         :publisher => 'f53606cb-7f3c-4432-afe8-44-publisher',
         :nothing   => '2972abd7-b055-4841-8ad1-4a34-nothing',
@@ -74,7 +75,7 @@ module ConfigurationService
 
         def authorize_request(role, token)
           raise AuthorizationError.new("missing token") unless token
-          raise AuthorizationError.new("authorization failed") unless token == BUILTIN_TOKENS[role]
+          raise AuthorizationError.new("authorization failed") unless token == BUILTIN_TOKENS[role] or token == BUILTIN_TOKENS[:admin]
         end
 
     end

data/lib/configuration_service/test/orchestrator.rb

@@ -252,8 +252,8 @@ module ConfigurationService
       # @todo replace with declarative test that delegates to orchestration provider
       #
       def bootstrap_configuration_service_environmentally
-        factory = ConfigurationService::Factory::EnvironmentContext.new(@env, "CFGSRV")
-        @service = factory.create
+        context = ConfigurationService::Factory::EnvironmentContext.new(@env, "CFGSRV")
+        @service = ConfigurationService::Factory.create_client(context)
       end
 
       ##

data/lib/configuration_service/utils.rb

@@ -0,0 +1,15 @@
+module ConfigurationService
+  module Utils
+    
+    def self.dictionary?(o)
+      o.respond_to?(:to_hash) or o.respond_to?(:to_h)
+    end
+
+    def self.decorate(metadata)
+      revision = SecureRandom.uuid
+      metadata = metadata.merge("revision" => revision) unless metadata["revision"]
+      metadata = metadata.merge("timestamp" => Time.now.utc.iso8601) unless metadata["timestamp"]
+    end
+
+  end
+end

data/lib/configuration_service/version.rb

@@ -1,5 +1,5 @@
 module ConfigurationService
 
-  VERSION = "2.1.1"
+  VERSION = "2.2.0"
 
 end

data/lib/configuration_service.rb

@@ -1,3 +1,4 @@
+require "configuration_service/admin_client"
 require "configuration_service/base"
 require "configuration_service/configuration"
 require "configuration_service/errors"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: configuration_service
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.2.0
 platform: ruby
 authors:
 - Sheldon Hearn
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-05-11 00:00:00.000000000 Z
+date: 2016-06-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -99,6 +99,7 @@ files:
 - features/authorization.feature
 - features/bootstrapping.feature
 - features/consuming.feature
+- features/listing.feature
 - features/publishing.feature
 - features/step_definitions/authorization_steps.rb
 - features/step_definitions/bootstrapping_steps.rb
@@ -106,11 +107,15 @@ files:
 - features/step_definitions/publishing_steps.rb
 - features/support/env.rb
 - lib/configuration_service.rb
+- lib/configuration_service/admin_client.rb
 - lib/configuration_service/base.rb
 - lib/configuration_service/configuration.rb
 - lib/configuration_service/errors.rb
 - lib/configuration_service/factory.rb
+- lib/configuration_service/factory/context.rb
+- lib/configuration_service/factory/context/symbolic_access_wrapper.rb
 - lib/configuration_service/factory/environment_context.rb
+- lib/configuration_service/factory/environment_context/backward_compatibility.rb
 - lib/configuration_service/factory/environment_context/env_dict.rb
 - lib/configuration_service/provider.rb
 - lib/configuration_service/provider/broken.rb
@@ -124,6 +129,7 @@ files:
 - lib/configuration_service/test/orchestrator_environment_factory.rb
 - lib/configuration_service/test/response.rb
 - lib/configuration_service/test/stub_orchestration_provider.rb
+- lib/configuration_service/utils.rb
 - lib/configuration_service/version.rb
 homepage: https://github.com/hetznerZA/configuration_service
 licenses: []
@@ -149,4 +155,3 @@ signing_key:
 specification_version: 4
 summary: Configuration service
 test_files: []
-has_rdoc: