heroics 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+vendor/

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in heroics.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 geemus
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,53 @@
+# Heroics
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'heroics'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install heroics
+
+## Usage
+
+TODO: Write usage instructions here
+
+The interface is designed to match the workings of the (Heroku Platform API)[https://devcenter.heroku.com/articles/platform-api-reference].
+
+```
+heroics = Heroics.new(token: ENV['HEROKU_API_TOKEN'])
+
+# apps
+heroics.apps.create(name: 'example')  # returns new app named 'example'
+heroics.apps.list                     # returns list of all apps
+heroics.apps.info('example')          # returns app with id or name of 'example'
+
+app = heroics.apps('example')       # returns local reference to app with id or name 'example'
+app.update(name: 'rename')          # returns updated app
+app.delete                          # returns deleted app
+
+# addons
+app = heroics.apps('example')                               # returns local reference to app with id or name 'example'
+app.addons.create(plan: { name: 'heroku-postgresql:dev' })  # returns new add-on with plan:name 'heroku-postgresql:dev'
+app.addons.list                                             # returns list of all add-ons for app with id or name of 'example'
+
+addon = app.addons.info('heroku-postgresql:dev')            # returns add-on with id or name 'heroku-postgresql:dev'
+addon.update(plan: { name: 'heroku-postgresql:basic' })     # returns updated add-on
+addon.delete                                                # returns deleted add-on
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |task|
+  task.verbose = true
+  task.ruby_opts << '-r turn/autorun'
+  task.ruby_opts << '-I test'
+  task.test_files = FileList['test/**/*_test.rb', 'test/**/*_spec.rb']
+end
+
+task :default => :test

data/TODO

@@ -0,0 +1,3 @@
+how to handle ranges (note that this probably implies more complex cache behavior also)
+
+how to recognize/handle singular resources (ie account and config-vars)

data/bin/heroku-api

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+
+require 'heroics'
+require 'netrc'
+
+netrc = Netrc.read
+username, token = netrc['api.heroku.com']
+if username && token
+  username = username.split('@').first
+  url = "https://#{username}:#{token}@api.heroku.com/schema"
+  options = {
+    default_headers: {'Accept' => 'application/vnd.heroku+json; version=3'},
+    cache: Moneta.new(:File, dir: "#{Dir.home}/.heroics/heroku-api")}
+  cli = Heroics.cli_from_schema_url('heroku-api', STDOUT, url, options)
+  cli.run(*ARGV)
+else
+  puts "ERROR Couldn't find credentials for api.heroku.com in ~/.netrc."
+  puts "      Login with the Heroku Toolbelt by running 'heroku login'."
+  1
+end

data/heroics.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'heroics/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'heroics'
+  spec.version       = Heroics::VERSION
+  spec.authors       = ['geemus', 'jkakar']
+  spec.email         = ['geemus@gmail.com', 'jkakar@kakar.ca']
+  spec.description   = 'A Ruby client for HTTP APIs described using a JSON schema'
+  spec.summary       = 'A Ruby client for HTTP APIs described using a JSON schema'
+  spec.homepage      = ''
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep('^(test|spec|features)/')
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'minitest', '4.7.4'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'turn'
+
+  spec.add_dependency 'excon'
+  spec.add_dependency 'netrc'
+  spec.add_dependency 'moneta'
+  spec.add_dependency 'multi_json'
+end

data/lib/heroics.rb

@@ -0,0 +1,18 @@
+require 'excon'
+require 'moneta'
+require 'multi_json'
+require 'uri'
+require 'zlib'
+
+# Heroics is an HTTP client for an API described by a JSON schema.
+module Heroics
+end
+
+require 'heroics/errors'
+require 'heroics/naming'
+require 'heroics/link'
+require 'heroics/resource'
+require 'heroics/client'
+require 'heroics/schema'
+require 'heroics/command'
+require 'heroics/cli'

data/lib/heroics/cli.rb

@@ -0,0 +1,92 @@
+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
+
+  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
+
+  # Download a JSON schema and create a CLI with it.
+  #
+  # @param name [String] The name of the CLI.
+  # @param output [IO] The stream to write to.
+  # @param url [String] The URL for the schema.  The URL will be 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_url(name, output, url, options={})
+    schema = download_schema(url, options)
+    cli_from_schema(name, output, schema, url, options)
+  end
+end

data/lib/heroics/client.rb

@@ -0,0 +1,65 @@
+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.
+    def initialize(resources)
+      @resources = resources
+    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?
+        address = "<#{self.class.name}:0x00#{(self.object_id << 1).to_s(16)}>"
+        raise NoMethodError.new("undefined method `#{name}' for ##{address}")
+      end
+      resource
+    end
+  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)
+  end
+
+  # Download a JSON schema and create an HTTP client with it.
+  #
+  # @param url [String] The URL for the schema.  The URL will be used by the
+  #   generated client 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 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_url(url, options={})
+    schema = download_schema(url, options)
+    client_from_schema(schema, URI::join(url, '/').to_s, options)
+  end
+end

data/lib/heroics/command.rb

@@ -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/lib/heroics/errors.rb

@@ -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/lib/heroics/link.rb

@@ -0,0 +1,100 @@
+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={})
+      @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)
+      headers = @default_headers
+      if body
+        headers = headers.merge({'Content-Type' => 'application/json'})
+        body = MultiJson.dump(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(@url)
+      response = connection.request(method: @link_schema.method, path: path,
+                                    headers: headers, body: body,
+                                    expects: [200, 201, 202, 206, 304])
+      content_type = response.headers['Content-Type']
+      if response.status == 304
+        MultiJson.load(@cache["data:#{cache_key}"])
+      elsif content_type && content_type.include?('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
+  end
+end