pe-razor-client 0.15.2.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 74733b4a8fe748bab977062365bd2d8ed264facc
-  data.tar.gz: 52bdf2ad11d93cc78b64b55457fbc8726038a026
+  metadata.gz: e6c2760d424fcb90751a22b65217172feab26b6c
+  data.tar.gz: 51cca0cde398a43684ed9398eb709322874a817d
 SHA512:
-  metadata.gz: a40b6adabd53ef8fbbdeb1403eb8374b9dd528cf8451ebc840bf768c79b457bd605ebab4959aacf08119f614bc39a39f133d9a553b6002dc6ad6e6e987d036ee
-  data.tar.gz: 04f970bac6a6d7915869f6bf1f704072a86ddce68fe4042390ddc6cfe70192babbc4aff19aef6e8adfe89ed873586e41f7f69ea25e22d4c1b55981239a18078b
+  metadata.gz: 455603cb50328105b7fdf55e7e5454c01eab1d7f1043494f5619a98615cf9dd646c1d5ff3884a828e59a7ac569ad44af120e0e9e66332d37b6b4627471b18b5c
+  data.tar.gz: 26a4ba1316f72362e66501b9d7595b72886f4b1665dee5ef5a90d53235486f3574a209671e011e42fd88a027b3b9c76469fe3e409db2ba12b233f6865cc1b6dc

data/NEWS.md

@@ -1,5 +1,32 @@
 # Razor Client Release Notes
 
+## Next - TBD
+
+* NEW: RAZOR_CA_FILE environment variable allows TLS/SSL certificate
+  verification for requests.
+
+## 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

@@ -33,20 +33,45 @@ if parse.show_version?
 end
 
 if parse.show_help? and not parse.show_command_help?
-  puts parse.help
-  exit 0
+  output, exitcode = parse.help
+  puts output
+  exit exitcode
+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.rb

@@ -19,13 +19,19 @@ module Razor
         when :env
           super "URL '#{url}' in ENV variable RAZOR_API is not valid"
         when :opts
-          super "URL '#{url}' provided by -U or --url is not valid"
+          super "URL '#{url}' provided by -u or --url is not valid"
         else
           super "URL '#{url}' is not valid"
         end
       end
     end
 
+    class InvalidCAFileError < Error
+      def initialize(path)
+        super "CA file '#{path}' in ENV variable RAZOR_CA_FILE does not exist"
+      end
+    end
+
     class VersionCompatibilityError < Error
       def initialize(reason)
         super "Server version is not compatible with client version: #{reason}"
@@ -39,6 +45,9 @@ require_relative 'cli/version'
 require_relative 'cli/navigate'
 require_relative 'cli/parse'
 require_relative 'cli/format'
+require_relative 'cli/table_format'
 require_relative 'cli/document'
 require_relative 'cli/views'
-require_relative 'cli/transforms'
+require_relative 'cli/transforms'
+require_relative 'cli/query'
+require_relative 'cli/command'

data/lib/razor/cli/command.rb

@@ -0,0 +1,150 @@
+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'])
+    @cmd_schema = cmd_schema(@cmd_url)
+    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] !~ /^--/
+        arg = self.class.resolve_alias(arg, @cmd_schema)
+        body[arg] = self.class.convert_arg(arg, value, body[arg], @cmd_schema)
+      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_url)
+    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 self.arg_type(arg_name, cmd_schema)
+    # Short-circuit to allow this as a work-around for backwards compatibility.
+    return nil if arg_name == 'json'
+    return nil unless cmd_schema.is_a?(Hash)
+    return cmd_schema[arg_name]['type'] if cmd_schema.has_key?(arg_name)
+    return 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 self.convert_arg(arg_name, value, existing_value, cmd_schema)
+    value = nil if value == "null"
+
+    argument_type = arg_type(arg_name, cmd_schema)
+
+    # 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 && @parse.dump_response?
+
+    case argument_type
+      when "array"
+        existing_value ||= []
+        begin
+          existing_value + Array(MultiJson::load(value))
+        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
+
+  def self.resolve_alias(arg_name, cmd_schema)
+    return arg_name if cmd_schema[arg_name]
+    cmd_schema.find do |other_attr, metadata|
+      if metadata && metadata.has_key?('aliases')
+        return other_attr if metadata['aliases'].find {|aliaz| aliaz == arg_name}
+      end
+    end
+    # No results; return the same name to generate a reasonable error message.
+    arg_name
+  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,12 +11,14 @@ module Razor::CLI
       @parse = parse
       @segments = segments||[]
       @doc = entrypoint
-      @doc_url = parse.api_url
-      @userinfo = parse.api_url.userinfo
+      @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
@@ -53,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)
@@ -150,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)
@@ -187,16 +105,17 @@ module Razor::CLI
     end
 
     def get(url, headers={})
-      url = URI.parse(url.to_s)
-      url.userinfo = @userinfo
-      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 = {})
-      url = URI.parse(url.to_s)
-      url.userinfo = @userinfo
+    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]}"
@@ -205,11 +124,10 @@ module Razor::CLI
     end
 
     def json_post(url, body)
-      url = URI.parse(url.to_s)
-      url.userinfo = @userinfo
       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"
@@ -220,59 +138,13 @@ 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?,
+                                         :ssl_ca_file      =>  @parse.ssl_ca_file,
+                                         :user => @username,
+                                         :password => @password)
     end
   end
 end