heroics 0.0.1

data/lib/heroics/naming.rb

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

@@ -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

data/lib/heroics/schema.rb

@@ -0,0 +1,242 @@
+module Heroics
+  # A wrapper around a bare JSON schema to make it easier to use.
+  class Schema
+    attr_reader :schema
+
+    # Instantiate a schema.
+    #
+    # @param schema [Hash] The bare JSON schema to wrap.
+    def initialize(schema)
+      @schema = schema
+      @resources = {}
+      @schema['definitions'].each_key do |name|
+        @resources[name] = ResourceSchema.new(@schema, name)
+      end
+    end
+
+    # Get a schema for a named resource.
+    #
+    # @param name [String] The name of the resource.
+    # @raise [SchemaError] Raised if an unknown resource name is provided.
+    def resource(name)
+      resource_schema = @resources[name]
+      if @schema['definitions'].has_key?(name)
+        ResourceSchema.new(@schema, name)
+      else
+        raise SchemaError.new("Unknown resource '#{name}'.")
+      end
+    end
+
+    # The resource schema children that are part of this schema.
+    #
+    # @return [Array<ResourceSchema>] The resource schema children.
+    def resources
+      @resources.values
+    end
+  end
+
+  # A wrapper around a bare resource element in a JSON schema to make it
+  # easier to use.
+  class ResourceSchema
+    attr_reader :name
+
+    # Instantiate a resource schema.
+    #
+    # @param schema [Hash] The bare JSON schema to wrap.
+    # @param name [String] The name of the resource to identify in the schema.
+    def initialize(schema, name)
+      @schema = schema
+      @name = name
+      link_schema = schema['definitions'][name]['links']
+      @links = Hash[link_schema.each_with_index.map do |link, link_index|
+                      link_name = Heroics.ruby_name(link['title'])
+                      [link_name, LinkSchema.new(schema, name, link_index)]
+                    end]
+    end
+
+    # Get a schema for a named link.
+    #
+    # @param name [String] The name of the link.
+    # @raise [SchemaError] Raised if an unknown link name is provided.
+    def link(name)
+      schema = @links[name]
+      raise SchemaError.new("Unknown link '#{name}'.") unless schema
+      schema
+    end
+
+    # The link schema children that are part of this resource schema.
+    #
+    # @return [Array<LinkSchema>] The link schema children.
+    def links
+      @links.values
+    end
+  end
+
+  # A wrapper around a bare link element for a resource in a JSON schema to
+  # make it easier to use.
+  class LinkSchema
+    attr_reader :name, :resource_name, :description
+
+    # Instantiate a link schema.
+    #
+    # @param schema [Hash] The bare JSON schema to wrap.
+    # @param resource_name [String] The name of the resource to identify in
+    #   the schema.
+    # @param link_index [Fixnum] The index of the link in the resource schema.
+    def initialize(schema, resource_name, link_index)
+      @schema = schema
+      @resource_name = resource_name
+      @link_index = link_index
+      @name = Heroics.ruby_name(link_schema['title'])
+      @description = link_schema['description']
+    end
+
+    # Get the resource name in pretty form.
+    #
+    # @return [String] The pretty resource name.
+    def pretty_resource_name
+      Heroics.pretty_name(resource_name)
+    end
+
+    # Get the link name in pretty form.
+    #
+    # @return [String] The pretty link name.
+    def pretty_name
+      Heroics.pretty_name(name)
+    end
+
+    # Get the HTTP method for this link.
+    #
+    # @return [Symbol] The HTTP method.
+    def method
+      link_schema['method'].downcase.to_sym
+    end
+
+    # Get the names of the parameters this link expects.
+    #
+    # @return [Array<String>] The parameters.
+    def parameters
+      resolve_parameters(link_schema['href'].scan(PARAMETER_REGEX))
+    end
+
+    # Get an example request body.
+    #
+    # @return [Hash] A sample request body.
+    def example_body
+      if body_schema = link_schema['schema']
+        definitions = @schema['definitions'][@resource_name]['definitions']
+        Hash[body_schema['properties'].keys.map do |property|
+               # FIXME This is wrong! -jkakar
+               if definitions.has_key?(property)
+                 example = definitions[property]['example']
+               else
+                 example = ''
+               end
+               [property, example]
+             end]
+      end
+    end
+
+    # Inject parameters into the link href and return the body, if it exists.
+    #
+    # @param parameters [Array] The list of parameters to inject into the
+    #   path.
+    # @raise [ArgumentError] Raised if either too many or too few parameters
+    #   were provided.
+    # @return [String,Object] A path and request body pair.  The body value is
+    #   nil if a payload wasn't included in the list of parameters.
+    def format_path(parameters)
+      path = link_schema['href']
+      parameter_size = path.scan(PARAMETER_REGEX).size
+      too_few_parameters = parameter_size > parameters.size
+      # FIXME We should use the schema to detect when a request body is
+      # permitted and do the calculation correctly here. -jkakar
+      too_many_parameters = parameter_size < (parameters.size - 1)
+      if too_few_parameters || too_many_parameters
+        raise ArgumentError.new("wrong number of arguments " +
+                                "(#{parameters.size} for #{parameter_size})")
+      end
+
+      (0..parameter_size).each do |i|
+        path = path.sub(PARAMETER_REGEX, format_parameter(parameters[i]))
+      end
+      body = parameters.slice(parameter_size)
+      return path, body
+    end
+
+    private
+
+    # Match parameters in definition strings.
+    PARAMETER_REGEX = /\{\([%\/a-zA-Z0-9_]*\)\}/
+
+    # Get the raw link schema.
+    #
+    # @param [Hash] The raw link schema.
+    def link_schema
+      @schema['definitions'][@resource_name]['links'][@link_index]
+    end
+
+    # Get the names of the parameters this link expects.
+    #
+    # @param parameters [Array] The names of the parameter definitions to
+    #   convert to parameter names.
+    # @return [Array<String>] The parameters.
+    def resolve_parameters(parameters)
+      # FIXME This is all pretty terrible.  It'd be much better to
+      # automatically resolve $ref's based on the path instead of special
+      # casing everything. -jkakar
+      properties = @schema['definitions'][@resource_name]['properties']
+      definitions = Hash[properties.each_pair.map do |key, value|
+                           [value['$ref'], key]
+                         end]
+      parameters.map do |parameter|
+        definition_name = URI.unescape(parameter[2..-3])
+        if definitions.has_key?(definition_name)
+          definitions[definition_name]
+        else
+          definition_name = definition_name.split('/')[-1]
+          resource_definitions = @schema[
+            'definitions'][@resource_name]['definitions'][definition_name]
+          if resource_definitions.has_key?('anyOf')
+            resource_definitions['anyOf'].map do |property|
+              definitions[property['$ref']]
+            end.join('|')
+          else
+            resource_definitions['oneOf'].map do |property|
+              definitions[property['$ref']]
+            end.join('|')
+          end
+        end
+      end
+    end
+
+    # Convert a path parameter to a format suitable for use in a path.
+    #
+    # @param [Fixnum,String,TrueClass,FalseClass,Time] The parameter to format.
+    # @return [String] The formatted parameter.
+    def format_parameter(parameter)
+      parameter.instance_of?(Time) ? iso_format(parameter) : parameter.to_s
+    end
+
+    # Convert a time to an ISO 8601 combined data and time format.
+    #
+    # @param time [Time] The time to convert to ISO 8601 format.
+    # @return [String] An ISO 8601 date in `YYYY-MM-DDTHH:MM:SSZ` format.
+    def iso_format(time)
+      time.getutc.strftime('%Y-%m-%dT%H:%M:%SZ')
+    end
+  end
+
+  # Download a JSON schema from a URL.
+  #
+  # @param url [String] The URL for the schema.
+  # @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.
+  # @return [Schema] The downloaded JSON schema.
+  def self.download_schema(url, options={})
+    default_headers = options.fetch(:default_headers, {})
+    response = Excon.get(url, headers: default_headers, expects: [200, 201])
+    Schema.new(MultiJson.decode(response.body))
+  end
+end

data/lib/heroics/version.rb

@@ -0,0 +1,3 @@
+module Heroics
+  VERSION = "0.0.1"
+end

data/test.rb

@@ -0,0 +1,42 @@
+require 'netrc'
+
+_, token = Netrc.read['api.heroku.com']
+
+require './lib/heroics'
+
+heroics = Heroics.new(
+  :cache => Heroics::FileCache.new(token),
+  :token => token
+)
+
+heroics.apps.list
+apps = heroics.apps.list # should use cache
+puts(apps)
+puts
+
+app = heroics.apps.info('stringer-geemus')
+puts(app)
+puts
+
+puts(heroics.apps('stringer-geemus'))
+puts
+
+collaborators = app.collaborators.list
+puts(collaborators)
+puts
+
+collaborator_id = collaborators.first.id
+collaborator = app.collaborators.info(collaborator_id)
+puts(collaborator)
+puts
+
+regions = heroics.regions.list
+puts(regions)
+puts
+
+region_id = regions.first.id
+puts(heroics.regions.info(region_id))
+puts
+
+puts(heroics.regions(region_id))
+puts

data/test/cli_test.rb

@@ -0,0 +1,282 @@
+require 'helper'
+require 'stringio'
+
+class CLITest < MiniTest::Unit::TestCase
+  include ExconHelper
+
+  # CLI.run displays usage information when no arguments are provided.
+  def test_run_without_arguments
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    client = Heroics::client_from_schema(schema, 'https://example.com')
+    output = StringIO.new
+    command1 = Heroics::Command.new(
+      'cli', schema.resource('resource').link('list'), client, output)
+    command2 = Heroics::Command.new(
+      'cli', schema.resource('resource').link('info'), client, output)
+    cli = Heroics::CLI.new('cli', {'resource:list' => command1,
+                                   'resource:info' => command2}, output)
+    cli.run
+    expected = <<-USAGE
+Usage: cli <command> [<parameter> [...]] [<body>]
+
+Help topics, type "cli help <topic>" for more details:
+
+  resource:info    Show a sample resource
+  resource:list    Show all sample resources
+USAGE
+    assert_equal(expected, output.string)
+  end
+
+  # CLI.run displays usage information when the help command is specified.
+  def test_run_with_help_command
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    client = Heroics::client_from_schema(schema, 'https://example.com')
+    output = StringIO.new
+    command1 = Heroics::Command.new(
+      'cli', schema.resource('resource').link('list'), client, output)
+    command2 = Heroics::Command.new(
+      'cli', schema.resource('resource').link('info'), client, output)
+    cli = Heroics::CLI.new('cli', {'resource:list' => command1,
+                                   'resource:info' => command2}, output)
+    cli.run('help')
+    expected = <<-USAGE
+Usage: cli <command> [<parameter> [...]] [<body>]
+
+Help topics, type "cli help <topic>" for more details:
+
+  resource:info    Show a sample resource
+  resource:list    Show all sample resources
+USAGE
+    assert_equal(expected, output.string)
+  end
+
+  # CLI.run displays command-specific help when a command name is included
+  # with the 'help' command.
+  def test_run_with_help_command_and_explicit_command_name
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    client = Heroics::client_from_schema(schema, 'https://example.com')
+    output = StringIO.new
+    command1 = Heroics::Command.new(
+      'cli', schema.resource('resource').link('list'), client, output)
+    command2 = Heroics::Command.new(
+      'cli', schema.resource('resource').link('info'), client, output)
+    cli = Heroics::CLI.new('cli', {'resource:list' => command1,
+                                   'resource:info' => command2}, output)
+    cli.run('help', 'resource:info')
+    expected = <<-USAGE
+Usage: cli resource:info <uuid_field>
+
+Description:
+  Show a sample resource
+USAGE
+    assert_equal(expected, output.string)
+  end
+
+  # CLI.run displays an error message when no commands have been registered.
+  def test_run_without_commands
+    output = StringIO.new
+    cli = Heroics::CLI.new('cli', {}, output)
+    cli.run('help')
+    assert_equal('No commands are available.', output.string)
+  end
+
+  # CLI.run displays an error message when an unknown command name is used.
+  def test_run_with_unknown_name
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    client = Heroics::client_from_schema(schema, 'https://example.com')
+    output = StringIO.new
+    command = Heroics::Command.new(
+      'cli', schema.resource('resource').link('list'), client, output)
+    cli = Heroics::CLI.new('cli', {'resource:list' => command}, output)
+    cli.run('unknown:command')
+    assert_equal("There is no command called 'unknown:command'.\n",
+                 output.string)
+  end
+
+  # CLI.run runs the command matching the specified name.
+  def test_run_with_dashed_command_name
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    client = Heroics::client_from_schema(schema, 'https://example.com')
+    output = StringIO.new
+    command = Heroics::Command.new(
+      'cli', schema.resource('resource').link('identify_resource'), client,
+      output)
+    cli = Heroics::CLI.new('cli', {'resource:identify-resource' => command},
+                           output)
+
+    uuid = '1ab1c589-df46-40aa-b786-60e83b1efb10'
+    Excon.stub(method: :get) do |request|
+      assert_equal("/resource/#{uuid}", request[:path])
+      Excon.stubs.pop
+      {status: 200}
+    end
+
+    cli.run('resource:identify-resource', uuid)
+    assert_equal('', output.string)
+  end
+
+  # CLI.run runs the resource matching the specified name.
+  def test_run_with_dashed_resource_name
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    client = Heroics::client_from_schema(schema, 'https://example.com')
+    output = StringIO.new
+    command = Heroics::Command.new(
+      'cli', schema.resource('another-resource').link('list'), client, output)
+    cli = Heroics::CLI.new('cli', {'another-resource:list' => command},
+                           output)
+
+    result = {'Hello' => 'World!'}
+    Excon.stub(method: :get) do |request|
+      assert_equal("/another-resource", request[:path])
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(result)}
+    end
+
+    cli.run('another-resource:list')
+    assert_equal(MultiJson.dump(result, pretty: true) + "\n", output.string)
+  end
+
+  # CLI.run runs the command matching the specified name and passes parameters
+  # to it.
+  def test_run_with_parameters
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    client = Heroics::client_from_schema(schema, 'https://example.com')
+    output = StringIO.new
+    command = Heroics::Command.new(
+      'cli', schema.resource('resource').link('update'), client, output)
+    cli = Heroics::CLI.new('cli', {'resource:update' => command}, output)
+
+    uuid = '1ab1c589-df46-40aa-b786-60e83b1efb10'
+    body = {'Hello' => 'World!'}
+    result = {'Goodbye' => 'Universe!'}
+    Excon.stub(method: :patch) do |request|
+      assert_equal("/resource/#{uuid}", request[:path])
+      assert_equal('application/json', request[:headers]['Content-Type'])
+      assert_equal(body, MultiJson.load(request[:body]))
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(result)}
+    end
+
+    cli.run('resource:update', uuid, body)
+    assert_equal(MultiJson.dump(result, pretty: true) + "\n", output.string)
+  end
+end
+
+class CLIFromSchemaTest < MiniTest::Unit::TestCase
+  include ExconHelper
+
+  # cli_from_schema returns a CLI generated from the specified schema.
+  def test_cli_from_schema
+    uuid = '1ab1c589-df46-40aa-b786-60e83b1efb10'
+    body = {'Hello' => 'World!'}
+    result = {'Goodbye' => 'Universe!'}
+    Excon.stub(method: :patch) do |request|
+      assert_equal("/resource/#{uuid}", request[:path])
+      assert_equal('application/json', request[:headers]['Content-Type'])
+      assert_equal(body, MultiJson.load(request[:body]))
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(result)}
+    end
+
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    output = StringIO.new
+    cli = Heroics.cli_from_schema('cli', output, schema, 'https://example.com')
+    cli.run('resource:update', uuid, body)
+    assert_equal(MultiJson.dump(result, pretty: true) + "\n", output.string)
+  end
+
+  # cli_from_schema optionally accepts custom headers to pass with every
+  # request made by the generated CLI.
+  def test_cli_from_schema_with_custom_headers
+    uuid = '1ab1c589-df46-40aa-b786-60e83b1efb10'
+    body = {'Hello' => 'World!'}
+    result = {'Goodbye' => 'Universe!'}
+    Excon.stub(method: :patch) do |request|
+      assert_equal('application/vnd.heroku+json; version=3',
+                   request[:headers]['Accept'])
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(result)}
+    end
+
+    schema = Heroics::Schema.new(SAMPLE_SCHEMA)
+    output = StringIO.new
+    cli = Heroics.cli_from_schema(
+      'cli', output, schema, 'https://example.com',
+      default_headers: {'Accept' => 'application/vnd.heroku+json; version=3'})
+    cli.run('resource:update', uuid, body)
+    assert_equal(MultiJson.dump(result, pretty: true) + "\n", output.string)
+  end
+end
+
+class CLIFromSchemaURLTest < MiniTest::Unit::TestCase
+  include ExconHelper
+
+  # client_from_schema_url downloads a schema and returns a Client generated
+  # from it.
+  def test_cli_from_schema_url
+    Excon.stub(method: :get) do |request|
+      assert_equal('example.com', request[:host])
+      assert_equal('/schema', request[:path])
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(SAMPLE_SCHEMA)}
+    end
+
+    output = StringIO.new
+    cli = Heroics.cli_from_schema_url('cli', output,
+                                      'https://example.com/schema')
+
+    uuid = '1ab1c589-df46-40aa-b786-60e83b1efb10'
+    body = {'Hello' => 'World!'}
+    result = {'Goodbye' => 'Universe!'}
+    Excon.stub(method: :patch) do |request|
+      assert_equal("/resource/#{uuid}", request[:path])
+      assert_equal('application/json', request[:headers]['Content-Type'])
+      assert_equal(body, MultiJson.load(request[:body]))
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(result)}
+    end
+
+    cli.run('resource:update', uuid, body)
+    assert_equal(MultiJson.dump(result, pretty: true) + "\n", output.string)
+  end
+
+  # cli_from_schema_url optionally accepts custom headers to include in the
+  # request to download the schema.  The same headers are passed in requests
+  # made by the generated CLI.
+  def test_cli_from_schema_url_with_custom_headers
+    Excon.stub(method: :get) do |request|
+      assert_equal('example.com', request[:host])
+      assert_equal('/schema', request[:path])
+      assert_equal('application/vnd.heroku+json; version=3',
+                   request[:headers]['Accept'])
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(SAMPLE_SCHEMA)}
+    end
+
+    output = StringIO.new
+    cli = Heroics.cli_from_schema_url(
+      'cli', output, 'https://example.com/schema',
+      default_headers: {'Accept' => 'application/vnd.heroku+json; version=3'})
+
+    uuid = '1ab1c589-df46-40aa-b786-60e83b1efb10'
+    body = {'Hello' => 'World!'}
+    result = {'Goodbye' => 'Universe!'}
+    Excon.stub(method: :patch) do |request|
+      assert_equal('application/vnd.heroku+json; version=3',
+                   request[:headers]['Accept'])
+      Excon.stubs.pop
+      {status: 200, headers: {'Content-Type' => 'application/json'},
+       body: MultiJson.dump(result)}
+    end
+
+    cli.run('resource:update', uuid, body)
+    assert_equal(MultiJson.dump(result, pretty: true) + "\n", output.string)
+  end
+end