aws-sdk-core 2.0.0.rc14 → 2.0.0.rc15

data/lib/aws.rb

@@ -1,3 +1,5 @@
+require 'multi_json'
+
 module Aws
 
   # @api private
@@ -12,6 +14,7 @@ module Aws
 
   @service_added_callbacks = []
 
+  autoload :Client, "#{SRC}/client"
   autoload :CredentialProviderChain, "#{SRC}/credential_provider_chain"
   autoload :Credentials, "#{SRC}/credentials"
   autoload :EmptyStructure, "#{SRC}/empty_structure"
@@ -21,7 +24,6 @@ module Aws
   autoload :PageableResponse, "#{SRC}/pageable_response"
   autoload :RestBodyHandler, "#{SRC}/rest_body_handler"
   autoload :Service, "#{SRC}/service"
-  autoload :ServiceBuilder, "#{SRC}/service_builder"
   autoload :SharedCredentials, "#{SRC}/shared_credentials"
   autoload :Structure, "#{SRC}/structure"
   autoload :TreeHash, "#{SRC}/tree_hash"
@@ -30,10 +32,11 @@ module Aws
   # @api private
   module Api
     autoload :Customizer, "#{SRC}/api/customizer"
-    autoload :DocExample, "#{SRC}/api/doc_example"
-    autoload :Documentor, "#{SRC}/api/documentor"
+    autoload :Documenter, "#{SRC}/api/documenter"
     autoload :Manifest, "#{SRC}/api/manifest"
     autoload :ManifestBuilder, "#{SRC}/api/manifest_builder"
+    autoload :OperationDocumenter, "#{SRC}/api/operation_documenter"
+    autoload :OperationExample, "#{SRC}/api/operation_example"
     autoload :ServiceCustomizations, "#{SRC}/api/service_customizations"
   end
 
@@ -57,7 +60,9 @@ module Aws
   end
 
   module Plugins
+    autoload :CSDConditionalSigning, "#{SRC}/plugins/csd_conditional_signing"
     autoload :DynamoDBExtendedRetries, "#{SRC}/plugins/dynamodb_extended_retries"
+    autoload :DynamoDBSimpleAttributes, "#{SRC}/plugins/dynamodb_simple_attributes"
     autoload :EC2CopyEncryptedSnapshot, "#{SRC}/plugins/ec2_copy_encrypted_snapshot"
     autoload :GlacierAccountId, "#{SRC}/plugins/glacier_account_id"
     autoload :GlacierApiVersion, "#{SRC}/plugins/glacier_api_version"
@@ -76,6 +81,7 @@ module Aws
     autoload :S3Md5s, "#{SRC}/plugins/s3_md5s"
     autoload :S3Redirects, "#{SRC}/plugins/s3_redirects"
     autoload :S3SseCpk, "#{SRC}/plugins/s3_sse_cpk"
+    autoload :S3UrlEncodedKeys, "#{SRC}/plugins/s3_url_encoded_keys"
     autoload :SQSQueueUrls, "#{SRC}/plugins/sqs_queue_urls"
     autoload :SWFReadTimeouts, "#{SRC}/plugins/swf_read_timeouts"
     autoload :UserAgent, "#{SRC}/plugins/user_agent"
@@ -132,9 +138,8 @@ module Aws
       end
     end
 
-    # Adds a plugin to every AWS client class.  This registers the plugin
-    # with each versioned client for each service.
-    # @param [Plugin] plugin
+    # Applies the plugin to every AWS client class.
+    # @param [Seahorse::Client::Plugin] plugin
     # @return [void]
     def add_plugin(plugin)
       client_classes.each do |client_class|
@@ -142,9 +147,8 @@ module Aws
       end
     end
 
-    # Removes a plugin to from AWS client class.  This removes the plugin
-    # from each versioned client for each service.
-    # @param [Plugin] plugin
+    # Removes the plugin from every AWS client class.
+    # @param [Seahorse::Client::Plugin] plugin
     # @return [void]
     def remove_plugin(plugin)
       client_classes.each do |client_class|
@@ -152,76 +156,115 @@ module Aws
       end
     end
 
-    # @api private
-    def services
-      @services
-    end
-
-    # @return [Array<Class>]
-    # @api private
-    def client_classes
-      @services.values.map { |svc_module, options| svc_module.const_get(:Client) }
-    end
-
     # Yields to the given block for each service that has already been
     # defined via {add_service}. Also yields to the given block for
     # each new service added after the callback is registered.
     # @api private
     def service_added(&block)
       callback = Proc.new
+      services.each(&callback)
+      @service_added_callbacks << callback
+    end
+
+    # @api private
+    def services(&block)
+      return enum_for(:services) unless block_given?
       @services.each do |svc_name, (svc_module, options)|
-        callback.call(svc_name, svc_module, options)
+        yield(svc_name, svc_module, options)
       end
-      @service_added_callbacks << callback
     end
 
-    # Registers a new service. Creates a Client class and an Errors
-    # module.
-    #
-    #     # register a new service & API version
-    #     Aws.add_service('S3', {
-    #       'api' => '/path/to/api.json',
-    #       'paginators' => '/path/to/paginators.json',
-    #       'resources' => '/path/to/resources.json',
-    #     })
+    # @api private
+    def load_json(path)
+      path = File.join(GEM_ROOT, path) unless path.match(/^#{File::SEPARATOR}/)
+      MultiJson.load(File.open(path, 'r', encoding: 'UTF-8') { |f| f.read })
+    end
+
+    # Registers a new service.
     #
-    #     # create a versioned client
-    #     Aws::S3::Client.new
-    #     #=> #<Aws::S3::Client>
+    #     Aws.add_service('SvcName',
+    #       api: '/path/to/svc.api.json',
+    #       paginators: '/path/to/svc.paginators.json',
+    #       resources: '/path/to/svc.resources.json')
     #
-    # To register multiple API versions for the same service, use separate
-    # service names.
+    #     Aws::SvcName::Client.new
+    #     #=> #<Aws::SvcName::Client>
     #
-    # @param (see ServiceBuilder.new)
-    # @option (see ServiceBuilder.new)
-    # @return (see ServiceBuilder.new)
+    # @param [String] svc_name The name of the service. This will also be
+    #   the namespace under {Aws}.
+    # @option options[required,String,Hash,Seahorse::Model::Api] :api
+    # @option options[String,Hash,Paging::Provider] :paginators
+    # @option options[String] :resources
+    # @return [Module<Service>]
     def add_service(svc_name, options = {})
-      identifier = svc_name.downcase.to_sym
-      svc_module = ServiceBuilder.new(identifier, options)
+      svc_module = Module.new { extend Service }
       const_set(svc_name, svc_module)
-      @services[identifier] = [svc_module, options]
+      @services[svc_name] = [svc_module, options]
       @service_added_callbacks.each do |callback|
-        callback.call(identifier, svc_module, options)
+        callback.call(svc_name, *@services[svc_name])
       end
       svc_module
     end
 
+    private
+
+    def client_classes
+      @services.values.map { |svc_module, options| svc_module.const_get(:Client) }
+    end
+
+    def api_files
+      files = Dir.glob(File.join(GEM_ROOT, 'apis', '*.json'))
+      files.each.with_object({}) do |path, services|
+        svc_name, type = File.basename(path).split('.')
+        services[svc_name] ||= {}
+        services[svc_name][type.to_sym] = path
+      end
+    end
+
+  end
+
+  api_files.each do |service_name, files|
+    add_service(service_name, files)
+  end
+
+  # build service client classes
+  service_added do |name, svc_module, options|
+    svc_module.const_set(:Client, Client.define(name, options))
+    svc_module.const_set(:Errors, Module.new { extend Errors::DynamicErrors })
+  end
+
+  # build service paginators
+  service_added do |name, svc_module, options|
+    paginators = options[:paginators]
+    paginators = case paginators
+      when Paging::Provider then paginators
+      when Hash then Paging::Provider.new(paginators)
+      when String then Paging::Provider.new(Aws.load_json(paginators))
+      when nil then Paging::NullProvider.new
+      else raise ArgumentError, 'invalid :paginators option'
+    end
+    svc_module.const_get(:Client).paginators = paginators
   end
 
-  service_added do |identifier, svc_module, _|
-    define_singleton_method(identifier) do |options={}|
-      unless instance_variable_get("@#{identifier}_warned")
-        instance_variable_set("@#{identifier}_warned", true)
-        warn(<<-MSG.strip)
-Aws.#{identifier} deprecated as of v2.0.0.rc14 and will be removed as of v2.0.0.0 final; use #{svc_module.name}::Client.new() instead
-        MSG
+  # deprecated = define helper method for client class, this will be
+  # replaced eventually with a helper that returns a resource object
+  # for the service.
+  service_added do |name, svc_module, _|
+    method_name = name.downcase.to_sym
+    define_singleton_method(method_name) do |options={}|
+      unless instance_variable_get("@#{method_name}_warned")
+        instance_variable_set("@#{method_name}_warned", true)
+        msg = "Aws.#{method_name} is deprecated as of v2.0.0.rc14 and will be "
+        msg << "removed as of v2.0.0.0 final; use Aws::#{name}::Client.new "
+        msg << "instead"
+        warn(msg)
       end
-      svc_module::Client.new(options)
+      svc_module.const_get(:Client).new(options)
     end
   end
 
-  Api::Manifest.default_manifest.services.each do |service|
-    add_service(service.name, service.versions.values.last)
+  module DynamoDB
+    autoload :AttributeValue, "#{SRC}/dynamodb/attribute_value"
   end
 
 end

data/lib/aws/api/documenter.rb

@@ -0,0 +1,238 @@
+require 'multi_json'
+require 'erb'
+
+module Aws
+  module Api
+    class Documenter
+
+      def initialize(svc_module, docs_path)
+        @svc_module = svc_module
+        @svc_name = svc_module.name.split('::').last
+        @client_class = svc_module.const_get(:Client)
+        @api = @client_class.api
+        @full_name = @api.metadata('serviceFullName')
+        @error_names = @api.operations.map {|_,o| o.errors.map(&:name) }
+        @error_names = @error_names.flatten.uniq.sort
+        @namespace = YARD::Registry['Aws']
+        apply_docstrings(docs_path)
+      end
+
+      def apply
+        document_service
+        document_client
+        document_errors
+      end
+
+      private
+
+      def document_service
+        yard_mod = YARD::CodeObjects::ModuleObject.new(@namespace, @svc_name)
+        yard_mod.docstring = service_docstring
+        yard_mod.docstring.add_tag(YARD::Tags::Tag.new(:service, @svc_name))
+        @namespace = yard_mod
+      end
+
+      def service_docstring
+        path = "doc-src/services/#{@svc_name}/service.md"
+        path = 'doc-src/services/default/service.md' unless File.exists?(path)
+        template = read(path)
+        svc_name = @svc_name
+        api = @api
+        full_name = @full_name
+        ERB.new(template).result(binding)
+      end
+
+      def document_errors
+        yard_mod = YARD::CodeObjects::ModuleObject.new(@namespace, 'Errors')
+        yard_mod.docstring = errors_docstring
+
+        base_error = YARD::CodeObjects::ClassObject.new(yard_mod, 'ServiceError')
+        base_error.docstring = "Base class for all Aws::#{@svc_name} errors."
+        base_error.superclass = YARD::Registry['Aws::Errors::ServiceError']
+
+        @error_names.each do |error_name|
+          error_klass = YARD::CodeObjects::ClassObject.new(yard_mod, error_name)
+          error_klass.superclass = base_error
+        end
+      end
+
+      def errors_docstring
+        path = "doc-src/services/#{@svc_name}/errors.md"
+        path = 'doc-src/services/default/errors.md' unless File.exists?(path)
+        template = read(path)
+        svc_name = @svc_name
+        api = @api
+        full_name = @full_name
+        known_errors = @error_names
+        ERB.new(template).result(binding)
+      end
+
+      def document_client
+        yard_class = YARD::CodeObjects::ClassObject.new(@namespace, 'Client')
+        yard_class.superclass = YARD::Registry['Seahorse::Client::Base']
+        yard_class.docstring = client_docstring
+        document_client_constructor(yard_class)
+        document_client_operations(yard_class)
+      end
+
+      def client_docstring
+        path = "doc-src/services/#{@svc_name}/client.md"
+        path = 'doc-src/services/default/client.md' unless File.exists?(path)
+        render(path)
+      end
+
+      def render(path)
+        svc_name = @svc_name
+        api = @api
+        full_name = @full_name
+        ERB.new(File.read(path)).result(binding)
+      end
+
+      def document_client_constructor(namespace)
+        constructor = YARD::CodeObjects::MethodObject.new(namespace, :initialize)
+        constructor.group = 'Constructor'
+        constructor.scope = :instance
+        constructor.parameters << ['options', '{}']
+        constructor.docstring = client_constructor_docstring
+      end
+
+      def client_constructor_docstring
+        <<-DOCS.strip
+Constructs an API client.
+#{client_constructor_options}
+@return [#{@client_class.name}] Returns an API client.
+        DOCS
+      end
+
+      def client_constructor_options
+        options = {}
+        @client_class.plugins.each do |plugin|
+          if p = YARD::Registry[plugin.name]
+            p.tags.each do |tag|
+              if tag.tag_name == 'seahorse_client_option'
+                option_name = tag.text.match(/.+(:\w+)/)[1]
+                option_text = "@option options " + tag.text.split("\n").join("\n  ")
+                options[option_name] = option_text +
+                  "  See {#{plugin.name}} for more details."
+              end
+            end
+          end
+        end
+        options.sort_by { |k,v| k }.map(&:last).join("\n")
+      end
+
+      def document_client_operations(namespace)
+        @api.operations.each do |method_name, operation|
+          document_client_operation(namespace, method_name, operation)
+        end
+      end
+
+      def document_client_operation(namespace, method_name, operation)
+        m = YARD::CodeObjects::MethodObject.new(namespace, method_name)
+        m.group = 'Service Operations'
+        m.scope = :instance
+        m.parameters << ['params', '{}']
+        m.docstring = operation_docstring(method_name, operation)
+      end
+
+      def operation_docstring(method_name, operation)
+
+        documentor = OperationDocumenter.new(
+          svc_var_name: @svc_name.downcase,
+          method_name: method_name,
+          operation: operation)
+
+        tabs = Tabulator.new.tap do |t|
+          t.tab(method_name, 'Formatting Example') do
+            "<pre><code>#{documentor.example}</code></pre>"
+          end
+          t.tab(method_name, 'Request Parameters') do
+            documentor.input
+          end
+          t.tab(method_name, 'Response Structure') do
+            documentor.output
+          end
+        end
+
+        errors = (operation.errors || []).map { |shape| shape.name }
+        errors = errors.map { |e| "@raise [Errors::#{e}]" }.join("\n")
+
+        docstring = <<-DOCSTRING.strip
+<p>Calls the #{operation.name} operation.<p>
+#{documentor.api_ref(operation)}
+#{tabs}
+@param [Hash] params ({})
+@return [PageableResponse]
+#{errors}
+        DOCSTRING
+      end
+
+      class Tabulator
+
+        def initialize
+          @tabs = []
+          @tab_contents = []
+        end
+
+        def tab(method_name, tab_name, &block)
+          tab_class = tab_name.downcase.gsub(/[^a-z]+/i, '-')
+          tab_id = "#{method_name.to_s.gsub(/_/, '-')}-#{tab_class}"
+          class_names = ['tab-contents', tab_class]
+          @tabs << [tab_id, tab_name]
+          @tab_contents << "<div class=\"#{class_names.join(' ')}\" id=\"#{tab_id}\">"
+          @tab_contents << yield
+          @tab_contents << '</div>'
+        end
+
+        def to_html
+          lines = []
+          lines << '<div class="tab-box">'
+          lines << '<ul class="tabs">'
+          @tabs.each do |tab_id, tab_name|
+            lines << "<li data-tab-id=\"#{tab_id}\">#{tab_name}</li>"
+          end
+          lines << '</ul>'
+          lines.concat(@tab_contents)
+          lines << '</div>'
+          lines.join
+        end
+        alias inspect to_html
+        alias to_str to_html
+        alias to_s to_html
+
+      end
+
+      def apply_docstrings(path)
+        docs = MultiJson.load(read(path))
+        api = @api.definition
+
+        api['documentation'] = docs['service']
+
+        docs['operations'].each do |operation, doc|
+          api['operations'][operation]['documentation'] = doc
+        end
+
+        docs['shapes'].each do |shape_name, shape|
+          api['shapes'][shape_name]['documentation'] = shape['base']
+          shape['refs'].each do |ref,doc|
+            target_shape_name, member = ref.split('$')
+            target_shape = api['shapes'][target_shape_name]
+            case target_shape['type']
+            when 'structure' then target_shape['members'][member]['documentation'] = doc
+            when 'list' then target_shape[member]['documentation'] = doc
+            when 'map' then target_shape[member]['documentation'] = doc
+            else raise 'not handled'
+            end
+          end
+        end
+
+        @api = Seahorse::Model::Api.new(api)
+      end
+
+      def read(path)
+        File.open(path, 'r', encoding: 'UTF-8') { |f| f.read }
+      end
+
+    end
+  end
+end