razor-client 0.15.1 → 0.16.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a069f6a924314034052a7cb2f0d1f3192110570e
+  data.tar.gz: df77eb2e540658b2d7af2dfd9991f6ba731156db
+SHA512:
+  metadata.gz: dc9d5e138578e0d199bb6b044286aa357323810ba2e0d488aa0942ec7ee6ef13e415b6b842481a2c3c2aec80371684b832b843a0cf84c3211756c1da81e20017
+  data.tar.gz: dc84915443ae5e8b14291fd878ed7472ed84ce412e1e276da2558ca40afe8707751235ceacba56c63a13249ee5a7ca8468324ad190619194f5f665ca9bc383f1

data/NEWS.md

@@ -1,5 +1,27 @@
 # Razor Client Release Notes
 
+## 0.16.0 - 2015-01-05
+
+* BUGFIX: Commands were not always including authentication
+  information in every request.
+* IMPROVEMENT: Ruby version compatibility: Now works with Ruby < 1.9.2.
+* NEW: Separate API and CLI help examples: There are now two formats for help
+  examples. The new CLI format shows help text as a standard razor-client
+  command. CLI is used by default. The API format is the same as before,
+  and will show examples in JSON format.
+* NEW: The `events` collection is new and has a special client-side display.
+* NEW: RAZOR_API and `razor -u $url` URLs need to be explicit about `http:` 
+  and `https:`.
+* NEW: Event queries can be limited (`razor events --limit 5`) and offset
+  (`razor events --start 5`). This also works for `razor nodes $name log`.
+* IMPROVEMENT: Viewing all columns in a query is now possible via 
+  `razor $collection_path --full` rather than `razor --full $collection_path`.
+* NEW: razor-client now has an 'insecure' flag to ignore SSL verification 
+  errors.
+* IMPROVEMENT: Argument types were previously not very context-aware. Now,
+  for example, names can include the '=' character.
+* BUGFIX: A reasonable error will be thrown if help is requested but does not exist.
+
 ## 0.15.1 - 2014-06-12
 
 Server version compatibility

data/bin/razor

@@ -37,16 +37,40 @@ if parse.show_help? and not parse.show_command_help?
   exit 0
 end
 
+def unexpected_error(e)
+  die <<-ERROR
+An unexpected error has occurred.
+
+Backtrace:
+  #{e.backtrace.take(10).join('
+  ')}
+
+Error: #{e}
+
+Please inspect server logs for the cause, then report issue to:
+https://tickets.puppetlabs.com/browse/RAZOR
+
+  ERROR
+end
+
 begin
   document = parse.navigate.get_document
   url = parse.navigate.last_url
   puts "From #{url}:\n\n#{format_document document, parse}\n\n"
+rescue OptionParser::InvalidOption => e
+  # Occurs when invalid flags are passed in the navigation.
+  die e.message + "\nTry 'razor --help' for more information"
 rescue SocketError, Errno::ECONNREFUSED => e
   puts "Error: Could not connect to the server at #{parse.api_url}"
   puts "       #{e}\n"
   die
+rescue RestClient::SSLCertificateNotVerified
+  puts "Error: SSL certificate could not be verified against known CA certificates."
+  puts "       To turn off verification, use the -k or --insecure option."
+  die
 rescue RestClient::Exception => e
   r = e.response
+  unexpected_error(e) if r.nil?
   puts "Error from doing #{r.args[:method].to_s.upcase} #{r.args[:url]}"
   puts e.message
   begin

data/lib/razor/cli/command.rb

@@ -0,0 +1,139 @@
+class Razor::CLI::Command
+  def initialize(parse, navigate, commands, segments)
+    @parse = parse
+    @navigate = navigate
+    @commands = commands
+    @segments = segments
+  end
+
+  def run
+    # @todo lutter 2013-08-16: None of this has any tests, and error
+    # handling is heinous at best
+    cmd, body = extract_command
+    # Ensure that we copy authentication data from our previous URL.
+    url = URI.parse(cmd["id"])
+    if @doc_resource
+      url          = URI.parse(url.to_s)
+    end
+
+    if @parse.show_command_help?
+      @navigate.json_get(url)
+    else
+      if body.empty?
+        raise Razor::CLI::Error,
+              "No arguments for command (did you forget --json ?)"
+      end
+      result = @navigate.json_post(url, body)
+      # Get actual object from the id.
+      result = result.merge(@navigate.json_get(URI.parse(result['id']))) if result['id']
+      result
+    end
+  end
+
+  def command(name)
+    @command ||= @commands.find { |coll| coll["name"] == name }
+  end
+
+  def extract_command
+    cmd = command(@segments.shift)
+    @cmd_url = URI.parse(cmd['id'])
+    body = {}
+    until @segments.empty?
+      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, body[arg])
+      else
+        raise ArgumentError, "Unexpected argument #{argument}"
+      end
+    end
+
+    begin
+      body = MultiJson::load(File::read(body["json"])) if body["json"]
+    rescue MultiJson::LoadError
+      raise Razor::CLI::Error, "File #{body["json"]} is not valid JSON"
+    rescue Errno::ENOENT
+      raise Razor::CLI::Error, "File #{body["json"]} not found"
+    rescue Errno::EACCES
+      raise Razor::CLI::Error,
+            "Permission to read file #{body["json"]} denied"
+    end
+    [cmd, body]
+  end
+
+  def cmd_schema(cmd_name)
+    begin
+      @navigate.json_get(@cmd_url)['schema']
+    rescue RestClient::ResourceNotFound => _
+      raise VersionCompatibilityError, 'Server must supply the expected datatypes for command arguments; use `--json` or upgrade razor-server'
+    end
+  end
+
+  def arg_type(cmd_name, arg_name)
+    # Short-circuit to allow this as a work-around for backwards compatibility.
+    return nil if arg_name == 'json'
+    cmd = cmd_schema(cmd_name)
+    cmd && cmd[arg_name] && cmd[arg_name]['type'] or nil
+  end
+
+  # `cmd_name`: The name of the command being executed.
+  # `arg_name`: The name of the argument being formatted.
+  # `value`: The original value provided by the user.
+  # `existing_value`: The value already assigned to this variable
+  #     by previous calls to this method. The new `value` will be
+  #     concatenated to an array or hash if an array/hash is
+  #     accepted by the command for the given argument.
+  def convert_arg(cmd_name, arg_name, value, existing_value)
+    value = nil if value == "null"
+
+    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"
+        existing_value ||= []
+        begin
+          MultiJson::load(value).tap do |value|
+            value = Array(value)
+            existing_value + value
+          end
+        rescue MultiJson::LoadError => _
+          existing_value + Array(value)
+        end
+      when "object"
+        existing_value ||= {}
+        begin
+          if value =~ /\A(.+?)=(.+)?\z/
+            # `--arg name=value`
+            existing_value.merge($1 => $2)
+          else
+            MultiJson::load(value).tap do |value|
+              value.is_a?(Hash) or raise ArgumentError, "Invalid object for argument '#{arg_name}'"
+              existing_value.merge(value)
+            end
+          end
+        rescue MultiJson::LoadError => error
+          raise ArgumentError, "Invalid object for argument '#{arg_name}': #{error.message}"
+        end
+      when "boolean"
+        ["true", nil].include?(value)
+      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

data/lib/razor/cli/document.rb

@@ -1,6 +1,7 @@
 require 'forwardable'
 
 module Razor::CLI
+  class HideColumnError < RuntimeError; end
   class Document
       extend Forwardable
     attr_reader 'spec', 'items', 'format_view', 'original_items'
@@ -42,10 +43,13 @@ module Razor::CLI
               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
+              begin
+                value = Razor::CLI::Views.transform(item[item_column], item_spec['+format'])
+                [item_label, value]
+              rescue Razor::CLI::HideColumnError
+                nil
+              end
+            end.reject {|k| k.nil? }
           ].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')

data/lib/razor/cli/format.rb

@@ -1,5 +1,5 @@
 require 'forwardable'
-require 'terminal-table'
+require 'command_line_reporter'
 
 module Razor::CLI
   module Format
@@ -20,11 +20,11 @@ module Razor::CLI
 
     def format_document(doc, parse = nil)
       format = parse && parse.format
-      arguments = parse && parse.args
+      arguments = parse && parse.stripped_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 && parse.show_command_help?
+      return format_command_help(doc, parse.show_api_help?) if parse && parse.show_command_help?
 
       case (doc.format_view['+layout'] or 'list')
       when 'list'
@@ -43,25 +43,8 @@ module Razor::CLI
     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 get_headers(doc))
-      Terminal::Table.new do |table|
-        table.rows = doc.map do |page|
-          headings.map do |heading|
-            page[heading]
-          end
-        end
-        table.headings = headings
-      end.to_s
-    end
-
-    def get_headers(doc)
-      [].tap do |headers|
-        doc.map do |page|
-          page.map do |item|
-            headers << item[0] unless headers.include?(item[0])
-          end
-        end
-      end
+      column_overrides = formatting['+show'] && formatting['+show'].keys
+      Razor::CLI::TableFormat.new.run(doc, column_overrides)
     end
 
     # We assume that all collections are homogenous
@@ -79,6 +62,47 @@ module Razor::CLI
       end
     end
 
+    def format_command_help(doc, show_api_help)
+      item = doc.items.first
+      raise Razor::CLI::Error, 'Could not find help for that entry' unless item.has_key?('help')
+      if show_api_help and (item['help'].has_key?('summary') or item['help'].has_key?('description'))
+        format_composed_help(item['help']).chomp
+      elsif item['help'].has_key?('summary') or item['help'].has_key?('description')
+        format_composed_help(item['help'], item['help']['examples']['cli']).chomp
+      else
+        format_full_help(item['help']).chomp
+      end
+    end
+
+    def format_composed_help(object, examples = object['examples']['api'])
+      ret = ''
+      ret = ret + <<-SYNOPSIS if object.has_key?('summary')
+# SYNOPSIS
+#{object['summary']}
+
+      SYNOPSIS
+      ret = ret + <<-DESCRIPTION if object.has_key?('description')
+# DESCRIPTION
+#{object['description']}
+
+#{object['schema']}
+      DESCRIPTION
+      ret = ret + <<-RETURNS if object.has_key?('returns')
+# RETURNS
+#{object['returns'].gsub(/^/, '  ')}
+      RETURNS
+      ret = ret + <<-EXAMPLES if object.has_key?('examples') && object['examples'].has_key?('cli')
+# EXAMPLES
+
+#{examples.gsub(/^/, '  ')}
+      EXAMPLES
+      ret
+    end
+
+    def format_full_help(object)
+      object['full']
+    end
+
     def format_default_object(object, indent = 0 )
       fields = display_fields(object)
       key_indent = indent + fields.map {|f| f.length}.max

data/lib/razor/cli/navigate.rb

@@ -11,11 +11,14 @@ module Razor::CLI
       @parse = parse
       @segments = segments||[]
       @doc = entrypoint
-      @doc_url = parse.api_url
+      @username, @password = parse.api_url.userinfo.to_s.split(':')
+      @doc_resource = create_resource parse.api_url, {:accept => :json}
     end
 
+    attr_accessor :doc_resource
+
     def last_url
-      @doc_url
+      @doc_resource
     end
 
     def entrypoint
@@ -52,95 +55,16 @@ module Razor::CLI
       if @segments.empty?
         entrypoint
       elsif query?
-        @doc = collections
-        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
+        Razor::CLI::Query.new(@parse, self, collections, @segments).run
       elsif command?
-        # @todo lutter 2013-08-16: None of this has any tests, and error
-        # handling is heinous at best
-        cmd, body = extract_command
-        # Ensure that we copy authentication data from our previous URL.
-        url = cmd["id"]
-        if @doc_url
-          url          = URI.parse(url.to_s)
-          url.userinfo = @doc_url.userinfo
-        end
-
-        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
+        Razor::CLI::Command.new(@parse, self, commands, @segments).run
       else
-        raise NavigationError.new(@doc_url, @segments, @doc)
+        raise NavigationError.new(@doc_resource, @segments, @doc)
       end
     end
 
-    def extract_command
-      cmd = command(@segments.shift)
-      @cmd_url = cmd['id']
-      body = {}
-      until @segments.empty?
-        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] !~ /^--/
-          if value =~ /\A(.+?)=(\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
-
-      begin
-        body = MultiJson::load(File::read(body["json"])) if body["json"]
-      rescue MultiJson::LoadError
-        raise Razor::CLI::Error, "File #{body["json"]} is not valid JSON"
-      rescue Errno::ENOENT
-        raise Razor::CLI::Error, "File #{body["json"]} not found"
-      rescue Errno::EACCES
-        raise Razor::CLI::Error,
-              "Permission to read file #{body["json"]} denied"
-      end
-      [cmd, body]
-    end
-
-    def move_to(key)
+    def move_to(key, doc = @doc, params = {})
+      @doc = doc
       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)
@@ -149,17 +73,12 @@ module Razor::CLI
         obj = @doc[key]
       end
 
-      raise NavigationError.new(@doc_url, key, @doc) unless obj
+      raise NavigationError.new(@doc_resource, key, @doc) unless obj
 
       if obj.is_a?(Hash) && obj["id"]
-        url = obj["id"]
-        if @doc_url
-          url          = URI.parse(url.to_s)
-          url.userinfo = @doc_url.userinfo
-        end
+        url = URI.parse(obj["id"])
 
-        @doc = json_get(url)
-        @doc_url = url
+        @doc = json_get(url, {}, params)
       elsif obj.is_a?(Hash) && obj['spec']
         @doc = obj
       elsif obj.is_a?(Hash)
@@ -186,12 +105,17 @@ module Razor::CLI
     end
 
     def get(url, headers={})
-      response = RestClient.get url.to_s, headers
+      resource = create_resource(url, headers)
+      response = resource.get
       print "GET #{url.to_s}\n#{response.body}\n\n" if @parse.dump_response?
       response
     end
 
-    def json_get(url, headers = {})
+    def json_get(url, headers = {}, params = {})
+      # Add extra parameters to URL.
+      url.query = URI.encode_www_form(params)
+      url.query = nil if url.query.empty? # Remove dangling '?' from URL.
+
       response = get(url,headers.merge(:accept => :json))
       unless response.headers[:content_type] =~ /application\/json/
         raise "Received content type #{response.headers[:content_type]}"
@@ -202,7 +126,8 @@ module Razor::CLI
     def json_post(url, body)
       headers = {  :accept=>:json, "Content-Type" => :json }
       begin
-        response = RestClient.post url.to_s, MultiJson::dump(body), headers
+        resource = create_resource(url, headers)
+        response = resource.post MultiJson::dump(body)
       ensure
         if @parse.dump_response?
           print "POST #{url.to_s}\n#{body}\n-->\n"
@@ -213,59 +138,12 @@ module Razor::CLI
     end
 
     private
-    def cmd_schema(cmd_name)
-      begin
-        json_get(@cmd_url)['schema']
-      rescue RestClient::ResourceNotFound => _
-        raise VersionCompatibilityError, 'Server must supply the expected datatypes for command arguments; use `--json` or upgrade razor-server'
-      end
-    end
 
-    def arg_type(cmd_name, arg_name)
-      # Short-circuit to allow this as a work-around for backwards compatibility.
-      return nil if arg_name == 'json'
-      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"
-
-      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)
-        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
+    def create_resource(url, headers)
+      @doc_resource = RestClient::Resource.new(url.to_s, :headers => headers,
+                                         :verify_ssl => @parse.verify_ssl?,
+                                         :user => @username,
+                                         :password => @password)
     end
   end
 end