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

komoju 0.0.0 → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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