RubyGems - komoju - Versions diffs - 0.0.0 → 0.0.3 - Mend

komoju 0.0.0 → 0.0.3

Files changed (37) hide show

checksums.yaml +4 -4
data/.gitignore +2 -14
data/.gitmodules +3 -0
data/Gemfile.lock +34 -0
data/LICENSE.txt +1 -1
data/README.md +14 -2
data/Rakefile +9 -0
data/bin/generate-client +11 -0
data/komoju.gemspec +15 -6
data/lib/komoju/client.rb +460 -0
data/lib/komoju/version.rb +1 -1
data/lib/komoju.rb +10 -2
data/test/client_test.rb +8 -0
data/test/helper.rb +1 -0
data/vendor/heroics/lib/heroics/cli.rb +88 -0
data/vendor/heroics/lib/heroics/client.rb +109 -0
data/vendor/heroics/lib/heroics/client_generator.rb +99 -0
data/vendor/heroics/lib/heroics/command.rb +67 -0
data/vendor/heroics/lib/heroics/errors.rb +6 -0
data/vendor/heroics/lib/heroics/link.rb +120 -0
data/vendor/heroics/lib/heroics/naming.rb +19 -0
data/vendor/heroics/lib/heroics/resource.rb +30 -0
data/vendor/heroics/lib/heroics/schema.rb +444 -0
data/vendor/heroics/lib/heroics/version.rb +3 -0
data/vendor/heroics/lib/heroics.rb +22 -0
data/vendor/heroics/test/cli_test.rb +236 -0
data/vendor/heroics/test/client_generator_test.rb +34 -0
data/vendor/heroics/test/client_test.rb +215 -0
data/vendor/heroics/test/command_test.rb +214 -0
data/vendor/heroics/test/helper.rb +204 -0
data/vendor/heroics/test/link_test.rb +398 -0
data/vendor/heroics/test/naming_test.rb +45 -0
data/vendor/heroics/test/resource_test.rb +35 -0
data/vendor/heroics/test/schema_test.rb +287 -0
data/vendor/heroics/test/version_test.rb +9 -0
data/vendor/heroics/test.rb +42 -0
metadata +139 -8

data/vendor/heroics/lib/heroics/cli.rb ADDED Viewed

@@ -0,0 +1,88 @@
+module Heroics
+  class CLI
+    # Instantiate a CLI for an API described by a JSON schema.
+    #
+    # @param name [String] The name of the CLI.
+    # @param schema [Schema] The JSON schema describing the API.
+    # @param client [Client] A client generated from the JSON schema.
+    # @param output [IO] The stream to write to.
+    def initialize(name, commands, output)
+      @name = name
+      @commands = commands
+      @output = output
+    end
+    # Run a command.
+    #
+    # @param parameters [Array] The parameters to use when running the
+    #   command.  The first parameters is the name of the command and the
+    #   remaining parameters are passed to it.
+    def run(*parameters)
+      name = parameters.shift
+      if name.nil? || name == 'help'
+        if command_name = parameters.first
+          command = @commands[command_name]
+          command.usage
+        else
+          usage
+        end
+      else
+        command = @commands[name]
+        if command.nil?
+          @output.write("There is no command called '#{name}'.\n")
+        else
+          command.run(*parameters)
+        end
+      end
+    end
+    private
+    # Write usage information to the output stream.
+    def usage
+      if @commands.empty?
+        @output.write 'No commands are available.'
+        return
+      end
+      @output.write <<-USAGE
+Usage: #{@name} <command> [<parameter> [...]] [<body>]
+Help topics, type "#{@name} help <topic>" for more details:
+USAGE
+      name_width = @commands.keys.max_by { |key| key.size }.size
+      @commands.sort.each do |name, command|
+        name = name.ljust(name_width)
+        description = command.description
+        @output.puts("  #{name}    #{description}")
+      end
+    end
+  end
+  # Create a CLI from a JSON schema.
+  #
+  # @param name [String] The name of the CLI.
+  # @param output [IO] The stream to write to.
+  # @param schema [Hash] The JSON schema to use with the CLI.
+  # @param url [String] The URL used by the generated CLI when it makes
+  #   requests.
+  # @param options [Hash] Configuration for links.  Possible keys include:
+  #   - default_headers: Optionally, a set of headers to include in every
+  #     request made by the CLI.  Default is no custom headers.
+  #   - cache: Optionally, a Moneta-compatible cache to store ETags.  Default
+  #     is no caching.
+  # @return [CLI] A CLI with commands generated from the JSON schema.
+  def self.cli_from_schema(name, output, schema, url, options={})
+    client = client_from_schema(schema, url, options)
+    commands = {}
+    schema.resources.each do |resource_schema|
+      resource_schema.links.each do |link_schema|
+        command = Command.new(name, link_schema, client, output)
+        commands[command.name] = command
+      end
+    end
+    CLI.new(name, commands, output)
+  end
+end

data/vendor/heroics/lib/heroics/client.rb ADDED Viewed

@@ -0,0 +1,109 @@
+module Heroics
+  # An HTTP client with methods mapped to API resources.
+  class Client
+    # Instantiate an HTTP client.
+    #
+    # @param resources [Hash<String,Resource>] A hash that maps method names
+    #   to resources.
+    # @param url [String] The URL used by this client.
+    def initialize(resources, url)
+      @resources = resources
+      @url = url
+    end
+    # Find a resource.
+    #
+    # @param name [String] The name of the resource to find.
+    # @raise [NoMethodError] Raised if the name doesn't match a known resource.
+    # @return [Resource] The resource matching the name.
+    def method_missing(name)
+      resource = @resources[name.to_s]
+      if resource.nil?
+        raise NoMethodError.new("undefined method `#{name}' for #{to_s}")
+      end
+      resource
+    end
+    # Get a simple human-readable representation of this client instance.
+    def inspect
+      url = URI.parse(@url)
+      unless url.password.nil?
+        url.password = 'REDACTED'
+      end
+      "#<Heroics::Client url=\"#{url.to_s}\">"
+    end
+    alias to_s inspect
+  end
+  # Create an HTTP client from a JSON schema.
+  #
+  # @param schema [Schema] The JSON schema to build an HTTP client for.
+  # @param url [String] The URL the generated client should use when making
+  #   requests.  Include the username and password to use with HTTP basic
+  #   auth.
+  # @param options [Hash] Configuration for links.  Possible keys include:
+  #   - default_headers: Optionally, a set of headers to include in every
+  #     request made by the client.  Default is no custom headers.
+  #   - cache: Optionally, a Moneta-compatible cache to store ETags.  Default
+  #     is no caching.
+  # @return [Client] A client with resources and links from the JSON schema.
+  def self.client_from_schema(schema, url, options={})
+    resources = {}
+    schema.resources.each do |resource_schema|
+      links = {}
+      resource_schema.links.each do |link_schema|
+        links[link_schema.name] = Link.new(url, link_schema, options)
+      end
+      resources[resource_schema.name] = Resource.new(links)
+    end
+    Client.new(resources, url)
+  end
+  # Create an HTTP client with OAuth credentials from a JSON schema.
+  #
+  # @param oauth_token [String] The OAuth token to pass using the `Bearer`
+  #   authorization mechanism.
+  # @param schema [Schema] The JSON schema to build an HTTP client for.
+  # @param url [String] The URL the generated client should use when making
+  #   requests.
+  # @param options [Hash] Configuration for links.  Possible keys include:
+  #   - default_headers: Optionally, a set of headers to include in every
+  #     request made by the client.  Default is no custom headers.
+  #   - cache: Optionally, a Moneta-compatible cache to store ETags.  Default
+  #     is no caching.
+  # @return [Client] A client with resources and links from the JSON schema.
+  def self.oauth_client_from_schema(oauth_token, schema, url, options={})
+    authorization = "Bearer #{oauth_token}"
+    # Don't mutate user-supplied data.
+    options = Marshal.load(Marshal.dump(options))
+    if !options.has_key?(:default_headers)
+      options[:default_headers] = {}
+    end
+    options[:default_headers].merge!({"Authorization" => authorization})
+    client_from_schema(schema, url, options)
+  end
+  # Create an HTTP client with Token credentials from a JSON schema.
+  #
+  # @param oauth_token [String] The token to pass using the `Bearer`
+  #   authorization mechanism.
+  # @param schema [Schema] The JSON schema to build an HTTP client for.
+  # @param url [String] The URL the generated client should use when making
+  #   requests.
+  # @param options [Hash] Configuration for links.  Possible keys include:
+  #   - default_headers: Optionally, a set of headers to include in every
+  #     request made by the client.  Default is no custom headers.
+  #   - cache: Optionally, a Moneta-compatible cache to store ETags.  Default
+  #     is no caching.
+  # @return [Client] A client with resources and links from the JSON schema.
+  def self.token_client_from_schema(token, schema, url, options={})
+    authorization = "Token token=#{token}"
+    # Don't mutate user-supplied data.
+    options = Marshal.load(Marshal.dump(options))
+    if !options.has_key?(:default_headers)
+      options[:default_headers] = {}
+    end
+    options[:default_headers].merge!({"Authorization" => authorization})
+    client_from_schema(schema, url, options)
+  end
+end

data/vendor/heroics/lib/heroics/client_generator.rb ADDED Viewed

@@ -0,0 +1,99 @@
+module Heroics
+  # Generate a static client that uses Heroics under the hood.  This is a good
+  # option if you want to ship a gem or generate API documentation using Yard.
+  #
+  # @param module_name [String] The name of the module, as rendered in a Ruby
+  #   source file, to use for the generated client.
+  # @param schema [Schema] The schema instance to generate the client from.
+  # @param url [String] The URL for the API service.
+  # @param options [Hash] Configuration for links.  Possible keys include:
+  #   - default_headers: Optionally, a set of headers to include in every
+  #     request made by the client.  Default is no custom headers.
+  #   - cache: Optionally, a Moneta-compatible cache to store ETags.  Default
+  #     is no caching.
+  def self.generate_client(module_name, schema, url, options)
+    filename = File.dirname(__FILE__) + '/views/client.erb'
+    eruby = Erubis::Eruby.new(File.read(filename))
+    context = build_context(module_name, schema, url, options)
+    eruby.evaluate(context)
+  end
+  private
+  # Process the schema to build up the context needed to render the source
+  # template.
+  def self.build_context(module_name, schema, url, options)
+    resources = []
+    schema.resources.each do |resource_schema|
+      links = []
+      resource_schema.links.each do |link_schema|
+        links << GeneratorLink.new(link_schema.name.gsub('-', '_'),
+                                   link_schema.description,
+                                   link_schema.parameter_details)
+      end
+      resources << GeneratorResource.new(resource_schema.name.gsub('-', '_'),
+                                         resource_schema.description,
+                                         links)
+    end
+    {
+      module_name: module_name,
+      url: url,
+      default_headers: options.fetch(:default_headers, {}),
+      cache: options.fetch(:cache, {}),
+      description: schema.description,
+      schema: MultiJson.dump(schema.schema, pretty:true),
+      resources: resources
+    }
+  end
+  # A representation of a resource for use when generating source code in the
+  # template.
+  class GeneratorResource
+    attr_reader :name, :description, :links
+    def initialize(name, description, links)
+      @name = name
+      @description = description
+      @links = links
+    end
+    # The name of the resource class in generated code.
+    def class_name
+      Heroics.camel_case(name)
+    end
+  end
+  # A representation of a link for use when generating source code in the
+  # template.
+  class GeneratorLink
+    attr_reader :name, :description, :parameters
+    def initialize(name, description, parameters)
+      @name = name
+      @description = description
+      @parameters = parameters
+    end
+    # List of parameters for the method signature
+    def signatures
+      @parameters.map { |info| info.signature }.join(', ')
+    end
+    # The list of parameters to render in generated source code for the method
+    # signature for the link.
+    def parameter_list
+      @parameters.map { |info| info.name }.join(', ')
+    end
+  end
+  # Convert a lower_case_name to CamelCase.
+  def self.camel_case(text)
+    return text if text !~ /_/ && text =~ /[A-Z]+.*/
+    text = text.split('_').map{ |element| element.capitalize }.join
+    [/^Ssl/, /^Http/, /^Xml/].each do |replace|
+      text.sub!(replace) { |match| match.upcase }
+    end
+    text
+  end
+end

data/vendor/heroics/lib/heroics/command.rb ADDED Viewed

@@ -0,0 +1,67 @@
+module Heroics
+  class Command
+    # Instantiate a command.
+    #
+    # @param cli_name [String] The name of the CLI.
+    # @param link_schema [LinkSchema] The schema for the underlying link this
+    #   command represents.
+    # @param client [Client] The client to use when making requests.
+    # @param output [IO] The stream to write output to.
+    def initialize(cli_name, link_schema, client, output)
+      @cli_name = cli_name
+      @link_schema = link_schema
+      @client = client
+      @output = output
+    end
+    # The command name.
+    def name
+      "#{@link_schema.pretty_resource_name}:#{@link_schema.pretty_name}"
+    end
+    # The command description.
+    def description
+      @link_schema.description
+    end
+    # Write usage information to the output stream.
+    def usage
+      parameters = @link_schema.parameters.map { |parameter| "<#{parameter}>" }
+      parameters = parameters.empty? ? '' : " #{parameters.join(' ')}"
+      example_body = @link_schema.example_body
+      body_parameter = example_body.nil? ? '' : ' <body>'
+      @output.write <<-USAGE
+Usage: #{@cli_name} #{name}#{parameters}#{body_parameter}
+Description:
+  #{description}
+USAGE
+      if example_body
+        example_body = MultiJson.dump(example_body, pretty: true)
+        example_body = example_body.lines.map do |line|
+          "  #{line}"
+        end.join
+        @output.write <<-USAGE
+Body example:
+#{example_body}
+USAGE
+      end
+    end
+    # Run the command and write the results to the output stream.
+    #
+    # @param parameters [Array] The parameters to pass when making a request
+    #   to run the command.
+    def run(*parameters)
+      resource_name = @link_schema.resource_name
+      name = @link_schema.name
+      result = @client.send(resource_name).send(name, *parameters)
+      result = result.to_a if result.instance_of?(Enumerator)
+      if result && !result.instance_of?(String)
+        result = MultiJson.dump(result, pretty: true)
+      end
+      @output.puts(result) unless result.nil?
+    end
+  end
+end

data/vendor/heroics/lib/heroics/errors.rb ADDED Viewed

@@ -0,0 +1,6 @@
+module Heroics
+  # Raised when a schema has an error that prevents it from being parsed
+  # correctly.
+  class SchemaError < StandardError
+  end
+end

data/vendor/heroics/lib/heroics/link.rb ADDED Viewed

@@ -0,0 +1,120 @@
+module Heroics
+  # A link invokes requests with an HTTP server.
+  class Link
+    # Instantiate a link.
+    #
+    # @param url [String] The URL to use when making requests.  Include the
+    #   username and password to use with HTTP basic auth.
+    # @param link_schema [LinkSchema] The schema for this link.
+    # @param options [Hash] Configuration for the link.  Possible keys
+    #   include:
+    #   - default_headers: Optionally, a set of headers to include in every
+    #     request made by the client.  Default is no custom headers.
+    #   - cache: Optionally, a Moneta-compatible cache to store ETags.
+    #     Default is no caching.
+    def initialize(url, link_schema, options={})
+      @root_url, @path_prefix = unpack_url(url)
+      @link_schema = link_schema
+      @default_headers = options[:default_headers] || {}
+      @cache = options[:cache] || Moneta.new(:Null)
+    end
+    # Make a request to the server.
+    #
+    # JSON content received with an ETag is cached.  When the server returns a
+    # *304 Not Modified* status code content is loaded and returned from the
+    # cache.  The cache considers headers, in addition to the URL path, when
+    # creating keys so that requests to the same path, such as for paginated
+    # results, don't cause cache collisions.
+    #
+    # When the server returns a *206 Partial Content* status code the result
+    # is assumed to be an array and an enumerator is returned.  The enumerator
+    # yields results from the response until they've been consumed at which
+    # point, if additional content is available from the server, it blocks and
+    # makes a request to fetch the subsequent page of data.  This behaviour
+    # continues until the client stops iterating the enumerator or the dataset
+    # from the server has been entirely consumed.
+    #
+    # @param parameters [Array] The list of parameters to inject into the
+    #   path.  A request body can be passed as the final parameter and will
+    #   always be converted to JSON before being transmitted.
+    # @raise [ArgumentError] Raised if either too many or too few parameters
+    #   were provided.
+    # @return [String,Object,Enumerator] A string for text responses, an
+    #   object for JSON responses, or an enumerator for list responses.
+    def run(*parameters)
+      path, body = @link_schema.format_path(parameters)
+      path = "#{@path_prefix}#{path}" unless @path_prefix == '/'
+      headers = @default_headers
+      if body
+        headers = headers.merge({'Content-Type' => @link_schema.content_type})
+        body = @link_schema.encode(body)
+      end
+      cache_key = "#{path}:#{headers.hash}"
+      if @link_schema.method == :get
+        etag = @cache["etag:#{cache_key}"]
+        headers = headers.merge({'If-None-Match' => etag}) if etag
+      end
+      connection = Excon.new(@root_url, thread_safe_sockets: true)
+      response = connection.request(method: @link_schema.method, path: path,
+                                    headers: headers, body: body,
+                                    expects: [200, 201, 202, 204, 206, 304])
+      content_type = response.headers['Content-Type']
+      if response.status == 304
+        MultiJson.load(@cache["data:#{cache_key}"])
+      elsif content_type && content_type =~ /application\/.*json/
+        etag = response.headers['ETag']
+        if etag
+          @cache["etag:#{cache_key}"] = etag
+          @cache["data:#{cache_key}"] = response.body
+        end
+        body = MultiJson.load(response.body)
+        if response.status == 206
+          next_range = response.headers['Next-Range']
+          Enumerator.new do |yielder|
+            while true do
+              # Yield the results we got in the body.
+              body.each do |item|
+                yielder << item
+              end
+              # Only make a request to get the next page if we have a valid
+              # next range.
+              break unless next_range
+              headers = headers.merge({'Range' => next_range})
+              response = connection.request(method: @link_schema.method,
+                                            path: path, headers: headers,
+                                            expects: [200, 201, 206])
+              body = MultiJson.load(response.body)
+              next_range = response.headers['Next-Range']
+            end
+          end
+        else
+          body
+        end
+      elsif !response.body.empty?
+        response.body
+      end
+    end
+    private
+    # Unpack the URL and split it into a root URL and a path prefix, if one
+    # exists.
+    #
+    # @param url [String] The complete base URL to use when making requests.
+    # @return [String,String] A (root URL, path) prefix pair.
+    def unpack_url(url)
+      root_url = []
+      path_prefix = ''
+      parts = URI.split(url)
+      root_url << "#{parts[0]}://"
+      root_url << "#{parts[1]}@" unless parts[1].nil?
+      root_url << "#{parts[2]}"
+      root_url << ":#{parts[3]}" unless parts[3].nil?
+      path_prefix = parts[5]
+      return root_url.join(''), path_prefix
+    end
+  end
+end

data/vendor/heroics/lib/heroics/naming.rb ADDED Viewed

@@ -0,0 +1,19 @@
+module Heroics
+  # Process a name to make it suitable for use as a Ruby method name.
+  #
+  # @param name [String] The name to process.
+  # @return [String] The new name with capitals converted to lowercase, and
+  #   dashes and spaces converted to underscores.
+  def self.ruby_name(name)
+    name.downcase.gsub(/[- ]/, '_')
+  end
+  # Process a name to make it suitable for use as a pretty command name.
+  #
+  # @param name [String] The name to process.
+  # @return [String] The new name with capitals converted to lowercase, and
+  #   underscores and spaces converted to dashes.
+  def self.pretty_name(name)
+    name.downcase.gsub(/[_ ]/, '-')
+  end
+end

data/vendor/heroics/lib/heroics/resource.rb ADDED Viewed

@@ -0,0 +1,30 @@
+module Heroics
+  # A resource with methods mapped to API links.
+  class Resource
+    # Instantiate a resource.
+    #
+    # @param links [Hash<String,Link>] A hash that maps method names to links.
+    def initialize(links)
+      @links = links
+    end
+    private
+    # Find a link and invoke it.
+    #
+    # @param name [String] The name of the method to invoke.
+    # @param parameters [Array] The arguments to pass to the method.  This
+    #   should always be a `Hash` mapping parameter names to values.
+    # @raise [NoMethodError] Raised if the name doesn't match a known link.
+    # @return [String,Array,Hash] The response received from the server.  JSON
+    #   responses are automatically decoded into Ruby objects.
+    def method_missing(name, *parameters)
+      link = @links[name.to_s]
+      if link.nil?
+        address = "<#{self.class.name}:0x00#{(self.object_id << 1).to_s(16)}>"
+        raise NoMethodError.new("undefined method `#{name}' for ##{address}")
+      end
+      link.run(*parameters)
+    end
+  end
+end