razor-client 0.14.0 → 0.15.0

data/NEWS.md

@@ -0,0 +1,18 @@
+# Razor Client Release Notes
+
+## 0.15.0 - 2014-05-22
+
+Usability of the client has been greatly enhanced:
+
+* Tabular views of most collections: things like 'razor nodes' now display
+  a table of results with important details about each node.
+* Get help on commands via `razor help COMMAND`
+* Output now includes hints on how to get more details on the things displayed
+* No need to enter JSON on the command line for most commands (all but
+  create-tag)
+  + arrays can now be entered by repeating the same option, e.g. `razor
+    create-tag --name ... --tag t1 --tag t2`
+  + broker configuration is set using `razor create-broker --name
+  .. --configuration var1=value1 --configuration var2=value2 ...`
+* Clearer error message when server responds with 'Unauthorized'
+  (RAZOR-175)

data/bin/razor

@@ -27,7 +27,12 @@ rescue OptionParser::InvalidOption => e
   die e.message + "\nTry 'razor --help' for more information"
 end
 
-if parse.show_help?
+if parse.show_version?
+  puts parse.version
+  exit 0
+end
+
+if parse.show_help? and not parse.show_command_help?
   puts parse.help
   exit 0
 end
@@ -35,9 +40,7 @@ end
 begin
   document = parse.navigate.get_document
   url = parse.navigate.last_url
-  puts "From #{url}:\n\n#{format_document document}\n\n"
-rescue Razor::CLI::Error => e
-  die "#{e}\n#{parse.help}\n\n"
+  puts "From #{url}:\n\n#{format_document document, parse}\n\n"
 rescue SocketError, Errno::ECONNREFUSED => e
   puts "Error: Could not connect to the server at #{parse.api_url}"
   puts "       #{e}\n"
@@ -58,4 +61,6 @@ rescue RestClient::Exception => e
     puts r.body
   end
   die
+rescue StandardError => e
+  die "#{e.message}\nTry 'razor --help' for more information\n\n"
 end

data/lib/razor/cli.rb

@@ -26,9 +26,19 @@ module Razor
       end
     end
 
+    class VersionCompatibilityError < Error
+      def initialize(reason)
+        super "Server version is not compatible with client version: #{reason}"
+      end
+    end
+
   end
 end
 
+require_relative 'cli/version'
 require_relative 'cli/navigate'
 require_relative 'cli/parse'
 require_relative 'cli/format'
+require_relative 'cli/document'
+require_relative 'cli/views'
+require_relative 'cli/transforms'

data/lib/razor/cli/document.rb

@@ -0,0 +1,59 @@
+require 'forwardable'
+
+module Razor::CLI
+  class Document
+      extend Forwardable
+    attr_reader 'spec', 'items', 'format_view', 'original_items'
+    def initialize(doc, format_type)
+      if doc['spec'].is_a?(Array)
+        @spec, @remaining_navigation = doc['spec']
+      else
+        @spec = doc['spec']
+      end
+      @command = doc['command']
+      if doc.has_key?('items')
+        @type = :list
+      else
+        @type = :single
+      end
+      @items = doc['items'] || Array[doc]
+      @format_view = Razor::CLI::Views.find_formatting(@spec, format_type, @remaining_navigation)
+
+      # Untransformed and unordered for displaying nested views.
+      @original_items = @items
+      @items = hide_or_transform_elements!(items, format_view)
+    end
+
+    def is_list?
+      @type == :list
+    end
+
+    private
+    # This method:
+    # - rearranges columns per Razor::CLI::Views.
+    # - hides columns per Razor::CLI::Views.
+    # - transforms data using both Razor::CLI::Views and its `TRANSFORMS`.
+    def hide_or_transform_elements!(items, format_view)
+      if format_view.has_key?('+show')
+        items.map do |item|
+          Hash[
+            format_view['+show'].map do |item_format_spec|
+              # Allow both '+column' as overrides.
+              item_spec = (item_format_spec[1] or {})
+              item_label = item_format_spec[0]
+              item_column = (item_spec['+column'] or item_label)
+              value = Razor::CLI::Views.transform(item[item_column], item_spec['+format'])
+
+              [item_label, value]
+            end
+          ].tap do |hash|
+            # Re-add the special 'command' key and value if the key isn't already there.
+            hash['command'] = @command if @command and not hash.has_key?('command')
+          end
+        end
+      else
+        items
+      end
+    end
+  end
+end

data/lib/razor/cli/format.rb

@@ -1,8 +1,10 @@
+require 'forwardable'
 require 'terminal-table'
 
 module Razor::CLI
   module Format
-    PriorityKeys = %w[ id name ]
+    extend Forwardable
+    PriorityKeys = %w[ id name spec ]
     SpecNames = {
       "/spec/object/policy" => "Policy",
       "/spec/object/tag" => "Tag",
@@ -16,12 +18,41 @@ module Razor::CLI
       spec
     end
 
-    def format_document(doc)
-      case doc
-      when Array then format_objects(doc)
-      when Hash then format_object(doc)
-      else doc.to_s
-      end.chomp
+    def format_document(doc, parse = nil)
+      format = parse.format
+      arguments = parse.args
+      doc = Razor::CLI::Document.new(doc, format)
+
+      return "There are no items for this query." if doc.items.empty?
+      return format_objects(doc.items).chomp if parse.show_command_help?
+
+      case (doc.format_view['+layout'] or 'list')
+      when 'list'
+        format_objects(doc.items) + String(additional_details(doc, arguments)).chomp
+      when 'table'
+        case doc.items
+          when Array then
+            get_table(doc.items, doc.format_view) + String(additional_details(doc, arguments))
+          else doc.to_s
+        end
+      else
+        raise ArgumentError, "Unrecognized view format #{doc.format_view['+layout']}"
+      end
+    end
+
+    private
+    def get_table(doc, formatting)
+      # Use the formatting if it exists, otherwise build from the data.
+      headings = (formatting['+show'] and formatting['+show'].keys or [])
+      Terminal::Table.new do |t|
+        t.rows = doc.map do |page|
+          page.map do |item|
+            headings << item[0] unless headings.include? item[0]
+            item[1]
+          end
+        end
+        t.headings = headings
+      end.to_s
     end
 
     # We assume that all collections are homogenous
@@ -31,21 +62,16 @@ module Razor::CLI
       end.join "\n\n"
     end
 
-    def format_reference_object(ref, indent = 0)
-      output = ' '* indent + "#{ref['name']} => #{ref['id'].to_s.ljust 4}"
-    end
-
-
     def format_object(object, indent = 0)
-      if object.keys == ["id", "name"]
-        format_reference_object(object, indent)
+      if object.has_key?('help') and object.has_key?('name')
+        object['help']['full']
       else
         format_default_object(object, indent)
       end
     end
 
     def format_default_object(object, indent = 0 )
-      fields = (PriorityKeys & object.keys) + (object.keys - PriorityKeys)
+      fields = display_fields(object)
       key_indent = indent + fields.map {|f| f.length}.max
       output = ""
       fields.map do |f|
@@ -59,11 +85,13 @@ module Razor::CLI
             "\n" + format_object(value, key_indent + 4).rstrip
           end
         when Array
-           if value.all? { |v| v.is_a?(String) }
-             "[" + value.map(&:inspect).join(",") + "]"
-           else
-             "[\n" + format_objects(value, key_indent + 6) + ("\n"+' '*(key_indent+4)+"]")
-           end
+          if value.all? { |v| v.is_a?(String) }
+            "[" + value.map(&:to_s).join(",") + "]"
+          else
+            "[\n" + format_objects(value, key_indent + 6) + ("\n"+' '*(key_indent+4)+"]")
+          end
+        when String
+          value
         else
           case f
           when "spec" then "\"#{Format.spec_name(value)}\""
@@ -72,5 +100,27 @@ module Razor::CLI
         end
       end.join "\n"
     end
+
+    def display_fields(object)
+      keys = object.respond_to?(:keys) ? object.keys : []
+      (PriorityKeys & keys) + (keys - PriorityKeys) - ['+spec']
+    end
+
+    def additional_details(doc, arguments)
+      objects = doc.original_items
+      # If every element has the 'name' key, it has nested elements.
+      if doc.is_list? and objects.all? { |it| it.is_a?(Hash) && it.has_key?('name')}
+        "\n\nQuery an entry by including its name, e.g. `razor #{arguments.join(' ')} #{objects.first['name']}`"
+      elsif objects.any?
+        object = objects.first
+        fields = display_fields(object) - PriorityKeys
+        list = fields.select do |f|
+          object[f].is_a?(Hash) or object[f].is_a?(Array)
+        end.sort
+        if list.any?
+          "\n\nQuery additional details via: `razor #{arguments.join(' ')} [#{list.join(', ')}]`"
+        end
+      end
+    end
   end
 end

data/lib/razor/cli/navigate.rb

@@ -1,9 +1,11 @@
 require 'rest-client'
 require 'multi_json'
 require 'yaml'
+require 'forwardable'
 
 module Razor::CLI
   class Navigate
+    extend Forwardable
 
     def initialize(parse, segments)
       @parse = parse
@@ -28,6 +30,10 @@ module Razor::CLI
       entrypoint["commands"]
     end
 
+    def server_version
+      entrypoint.has_key?('version') and entrypoint['version']['server'] or 'Unknown'
+    end
+
     def query?
       collections.any? { |coll| coll["name"] == @segments.first }
     end
@@ -40,6 +46,8 @@ module Razor::CLI
       !! command(@segments.first)
     end
 
+    def_delegator '@parse', 'show_command_help?'
+
     def get_document
       if @segments.empty?
         entrypoint
@@ -48,15 +56,18 @@ module Razor::CLI
         while @segments.any?
           move_to @segments.shift
         end
+
+        # Get the next level if it's a list of objects.
+        if @doc.is_a?(Hash) and @doc['items'].is_a?(Array)
+          @doc['items'] = @doc['items'].map do |item|
+            item.is_a?(Hash) && item.has_key?('id') ? json_get(item['id']) : item
+          end
+        end
         @doc
       elsif command?
         # @todo lutter 2013-08-16: None of this has any tests, and error
         # handling is heinous at best
         cmd, body = extract_command
-        if body.empty?
-          raise Razor::CLI::Error,
-            "No arguments for command (did you forget --json ?)"
-        end
         # Ensure that we copy authentication data from our previous URL.
         url = cmd["id"]
         if @doc_url
@@ -64,7 +75,18 @@ module Razor::CLI
           url.userinfo = @doc_url.userinfo
         end
 
-        json_post(url, body)
+        if show_command_help?
+          json_get(url)
+        else
+          if body.empty?
+            raise Razor::CLI::Error,
+                  "No arguments for command (did you forget --json ?)"
+          end
+          result = json_post(url, body)
+          # Get actual object from the id.
+          result = result.merge(json_get(result['id'])) if result['id']
+          result
+        end
       else
         raise NavigationError.new(@doc_url, @segments, @doc)
       end
@@ -72,12 +94,36 @@ module Razor::CLI
 
     def extract_command
       cmd = command(@segments.shift)
+      @cmd_url = cmd['id']
       body = {}
       until @segments.empty?
-        if @segments.shift =~ /\A--([a-z-]+)(=(\S+))?\Z/
+        argument = @segments.shift
+        if argument =~ /\A--([a-z-]+)(=(.+))?\Z/
+          # `--arg=value` or `--arg value`
           arg, value = [$1, $3]
           value = @segments.shift if value.nil? && @segments[0] !~ /^--/
-          body[arg] = convert_arg(cmd["name"], arg, value)
+          if value =~ /\A([a-zA-Z._-]+)=(\S+)?\z/
+            # `--arg name=value`
+            unless body[arg].nil? or body[arg].is_a?(Hash)
+              # Error: `--arg value --arg name=value`
+              raise ArgumentError, "Cannot handle mixed types for argument #{arg}"
+            end
+            # Do not convert, assume the above is the conversion.
+            body[arg] = (body[arg].nil? ? {} : body[arg]).merge($1 => $2)
+          elsif body[arg].is_a?(Hash)
+            # Error: `--arg name=value --arg value`
+            raise ArgumentError, "Cannot handle mixed types for argument #{arg}"
+          else
+            value = convert_arg(cmd["name"], arg, value)
+            if body[arg].nil?
+              body[arg] = value
+            else
+              # Either/both `body[arg]` or/and `value` might be an array at this point.
+              body[arg] = Array(body[arg]) + Array(value)
+            end
+          end
+        else
+          raise ArgumentError, "Unexpected argument #{argument}"
         end
       end
 
@@ -89,15 +135,16 @@ module Razor::CLI
         raise Razor::CLI::Error, "File #{body["json"]} not found"
       rescue Errno::EACCES
         raise Razor::CLI::Error,
-          "Permission to read file #{body["json"]} denied"
+              "Permission to read file #{body["json"]} denied"
       end
       [cmd, body]
     end
 
     def move_to(key)
-      key = key.to_i if key.to_i.to_s == key
       if @doc.is_a? Array
         obj = @doc.find {|x| x.is_a?(Hash) and x["name"] == key }
+      elsif @doc.is_a?(Hash) && @doc['items'].is_a?(Array)
+        obj = @doc['items'].find {|x| x.is_a?(Hash) and x["name"] == key }
       elsif @doc.is_a? Hash
         obj = @doc[key]
       end
@@ -112,13 +159,27 @@ module Razor::CLI
         end
 
         @doc = json_get(url)
-        # strip the wrapper around collections
-        if @doc.is_a? Hash and @doc["items"].is_a? Array
-          @doc = @doc["items"]
-        end
         @doc_url = url
-      elsif obj.is_a? Hash
+      elsif obj.is_a?(Hash) && obj['spec']
         @doc = obj
+      elsif obj.is_a?(Hash)
+        # No spec string; use parent's and remember extra navigation.
+        if @doc['+spec'].is_a?(Array)
+          # Something's been added.
+          @doc['+spec'] << key
+        elsif @doc['+spec'].nil? || @doc['+spec'].is_a?(String)
+          @doc['+spec'] = [@doc['spec'], key]
+        end
+        @doc = obj.merge({'+spec' => @doc['+spec']})
+      elsif obj.is_a?(Array)
+        # No spec string; use parent's and remember extra navigation.
+        if @doc['+spec'].is_a?(Array)
+          # Something's already been added.
+          @doc['+spec'] << key
+        elsif @doc['+spec'].nil? || @doc['+spec'].is_a?(String)
+          @doc['+spec'] = [@doc['spec'], key]
+        end
+        @doc = {'+spec' => @doc['+spec'], 'items' => obj}
       else
         @doc = nil
       end
@@ -133,7 +194,7 @@ module Razor::CLI
     def json_get(url, headers = {})
       response = get(url,headers.merge(:accept => :json))
       unless response.headers[:content_type] =~ /application\/json/
-       raise "Received content type #{response.headers[:content_type]}"
+        raise "Received content type #{response.headers[:content_type]}"
       end
       MultiJson.load(response.body)
     end
@@ -152,25 +213,53 @@ module Razor::CLI
     end
 
     private
-    def self.annotations
-      @@annotations ||=
-        YAML::load_file(File::join(File::dirname(__FILE__), "navigate.yaml"))
+    def cmd_schema(cmd_name)
+      cmd = json_get(@cmd_url)
+      cmd['schema'] or raise VersionCompatibilityError, 'Server must supply the expected datatypes for command arguments'
     end
 
-    def self.arg_type(cmd_name, arg_name)
-      cmd = annotations["commands"][cmd_name]
-      cmd && cmd["args"][arg_name]
+    def arg_type(cmd_name, arg_name)
+      cmd = cmd_schema(cmd_name)
+      cmd && cmd[arg_name] && cmd[arg_name]['type'] or nil
     end
 
     def convert_arg(cmd_name, arg_name, value)
       value = nil if value == "null"
-      case self.class.arg_type(cmd_name, arg_name)
-        when "json"
-          MultiJson::load(value)
+
+      argument_type = arg_type(cmd_name, arg_name)
+
+      # This might be helpful, since there's no other method for debug-level logging on the client.
+      puts "Formatting argument #{arg_name} with value #{value} as #{argument_type}\n" if @parse.dump_response?
+
+      case argument_type
+        when "array"
+          # 'array' datatype arguments will never fail. At worst, they'll be wrapped in an array.
+          begin
+            MultiJson::load(value)
+          rescue MultiJson::LoadError => _
+            Array(value)
+          end
+        when "object"
+          begin
+            MultiJson::load(value)
+          rescue MultiJson::LoadError => error
+            raise ArgumentError, "Invalid JSON for argument '#{arg_name}': #{error.message}"
+          end
         when "boolean"
           ["true", nil].include?(value)
-        else
+        when "number"
+          begin
+            Integer(value)
+          rescue ArgumentError
+            raise ArgumentError, "Invalid integer for argument '#{arg_name}': #{value}"
+          end
+        when "null"
+          raise ArgumentError, "Expected nothing for argument '#{arg_name}', but was: '#{value}'" unless value.nil?
+          nil
+        when "string", nil # `nil` for 'might be an alias, send as-is'
           value
+        else
+          raise Razor::CLI::Error, "Unexpected datatype '#{argument_type}' for argument #{arg_name}"
       end
     end
   end