razor-client 1.1.0 → 1.2.0

data/NEWS.md

@@ -1,5 +1,18 @@
 # Razor Client Release Notes
 
+## 1.2.0 - 2016-03-08
+
+* BUGFIX: Razor client version will be reported even if the Razor server is
+  unreachable.
+* BUGFIX: Fixed insecure flag when supplied in addition to a server URL.
+* NEW: Added positional argument support, when supplied by the server. See
+  `razor <command> --help` for details on usage.
+* NEW: Added USAGE section to the command's help, which will include positional
+  arguments, if any exist.
+* IMPROVEMENT: Proper short form argument style is now followed.
+  Single-character arguments now require a single dash, e.g. `-c`.
+* IMPROVEMENT: Error messaging for SSL issues has been improved.
+
 ## 1.1.0 - 2015-11-12
 
 * IMPROVEMENT: By default, `razor` will point to port 8150.

data/bin/razor

@@ -28,8 +28,9 @@ rescue OptionParser::InvalidOption => e
 end
 
 if parse.show_version?
-  puts parse.version
-  exit 0
+  version, exit_code = parse.version
+  puts version
+  exit exit_code
 end
 
 if parse.show_help? and not parse.show_command_help?

data/lib/razor/cli/command.rb

@@ -1,54 +1,60 @@
 class Razor::CLI::Command
-  def initialize(parse, navigate, commands, segments)
-    @parse = parse
+  def initialize(parse, navigate, command, segments, cmd_url)
+    @dump_response = parse && parse.dump_response?
+    @show_command_help = parse && parse.show_command_help?
     @navigate = navigate
-    @commands = commands
+    @command = command
+    @cmd_schema = command ? command['schema'] : nil
+    @cmd_url = cmd_url
     @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)
+    body = extract_command
+    if @show_command_help
+      @command
     else
       if body.empty?
         raise Razor::CLI::Error,
               "No arguments for command (did you forget --json ?)"
       end
-      result = @navigate.json_post(url, body)
+      result = @navigate.json_post(@cmd_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 = {}
+    pos_index = 0
     until @segments.empty?
       argument = @segments.shift
-      if argument =~ /\A--([a-z-]+)(=(.+))?\Z/
-        # `--arg=value` or `--arg value`
-        arg, value = [$1, $3]
+      if argument =~ /\A--([a-z-]{2,})(=(.+))?\Z/ or
+          argument =~ /\A-([a-z])(=(.+))?\Z/
+        # `--arg=value`/`--arg value`
+        # `-a=value`/`-a value`
+        arg_name, 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)
+        arg_name = self.class.resolve_alias(arg_name, @cmd_schema)
+        body[arg_name] = self.class.convert_arg(arg_name, value, body[arg_name], @cmd_schema)
+      elsif argument =~ /\A-([a-z-]{2,})(=(.+))?\Z/ and
+            @cmd_schema[self.class.resolve_alias($1, @cmd_schema)]
+        # Short form, should be long; offer suggestion
+        raise ArgumentError, "Unexpected argument #{argument} (did you mean --#{$1}?)"
+      elsif argument =~ /\A--([a-z])(=(.+))?\Z/ and
+            @cmd_schema[self.class.resolve_alias($1, @cmd_schema)]
+        # Long form, should be short; offer suggestion
+        raise ArgumentError, "Unexpected argument #{argument} (did you mean -#{$1}?)"
       else
-        raise ArgumentError, "Unexpected argument #{argument}"
+        # This may be a positional argument.
+        arg_name = positional_argument(@cmd_schema, pos_index)
+        if arg_name
+          body[arg_name] = self.class.convert_arg(arg_name, argument, body[arg_name], @cmd_schema)
+          pos_index += 1
+        else
+          raise ArgumentError, "Unexpected argument #{argument}"
+        end
       end
     end
 
@@ -62,15 +68,14 @@ class Razor::CLI::Command
       raise Razor::CLI::Error,
             "Permission to read file #{body["json"]} denied"
     end
-    [cmd, body]
+    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
+  def positional_argument(cmd_schema, pos_index)
+    # Find a matching position and return its argument name.
+    cmd_schema && cmd_schema.select do |_, schema|
+      schema['position'] == pos_index
+    end.keys.first
   end
 
   def self.arg_type(arg_name, cmd_schema)
@@ -94,7 +99,7 @@ class Razor::CLI::Command
     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?
+    puts "Formatting argument #{arg_name} with value #{value} as #{argument_type}\n" if @dump_response
 
     case argument_type
       when "array"

data/lib/razor/cli/format.rb

@@ -65,33 +65,48 @@ module Razor::CLI
     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
+      if item['help'].has_key?('examples')
+        if show_api_help && item['help']['examples'].has_key?('api')
+          format_composed_help(item, item['help']['examples']['api']).chomp
+        else
+          format_composed_help(item).chomp
+        end
       else
         format_full_help(item['help']).chomp
       end
     end
 
-    def format_composed_help(object, examples = object['examples']['api'])
+    def positional_args_usage(object)
+      object['schema'].map do |k, v|
+        [v['position'], k] if v.has_key?('position')
+      end.compact.sort.map(&:last).
+          map {|attr| "[#{attr.gsub('_', '-')}] " }.join.strip
+    end
+    def format_composed_help(object, examples = object['help']['examples']['cli'])
+      help_obj = object['help']
       ret = ''
-      ret = ret + <<-SYNOPSIS if object.has_key?('summary')
+      ret = ret + <<-USAGE
+# USAGE
+
+  razor #{object['name']} #{positional_args_usage(object)} <flags>
+
+      USAGE
+      ret = ret + <<-SYNOPSIS if help_obj.has_key?('summary')
 # SYNOPSIS
-#{object['summary']}
+#{help_obj['summary']}
 
       SYNOPSIS
-      ret = ret + <<-DESCRIPTION if object.has_key?('description')
+      ret = ret + <<-DESCRIPTION if help_obj.has_key?('description')
 # DESCRIPTION
-#{object['description']}
+#{help_obj['description']}
 
-#{object['schema']}
+#{help_obj['schema']}
       DESCRIPTION
-      ret = ret + <<-RETURNS if object.has_key?('returns')
+      ret = ret + <<-RETURNS if help_obj.has_key?('returns')
 # RETURNS
-#{object['returns'].gsub(/^/, '  ')}
+#{help_obj['returns'].gsub(/^/, '  ')}
       RETURNS
-      ret = ret + <<-EXAMPLES if object.has_key?('examples') && object['examples'].has_key?('cli')
+      ret = ret + <<-EXAMPLES if examples
 # EXAMPLES
 
 #{examples.gsub(/^/, '  ')}

data/lib/razor/cli/navigate.rb

@@ -93,7 +93,15 @@ module Razor::CLI
       elsif query?
         Razor::CLI::Query.new(@parse, self, collections, @segments).run
       elsif command?
-        Razor::CLI::Command.new(@parse, self, commands, @segments).run
+        cmd = @segments.shift
+        command = commands.find { |coll| coll["name"] == cmd }
+        cmd_url = URI.parse(command['id'])
+        # Ensure that we copy authentication data from our previous URL.
+        if @doc_resource
+          cmd_url = URI.parse(cmd_url.to_s)
+        end
+        command = json_get(cmd_url)
+        Razor::CLI::Command.new(@parse, self, command, @segments, cmd_url).run
       else
         raise NavigationError.new(@doc_resource, @segments, @doc)
       end

data/lib/razor/cli/parse.rb

@@ -63,22 +63,19 @@ module Razor::CLI
     end
 
     def version
+      server_version = '(unknown)'
+      error = ''
       begin
-      <<-VERSION
-Razor Server version: #{navigate.server_version}
-Razor Client version: #{Razor::CLI::VERSION}
-      VERSION
+        server_version = navigate.server_version
       rescue RestClient::Unauthorized
-        puts <<-UNAUTH
-Error: Credentials are required to connect to the server at #{@api_url}"
-        UNAUTH
-        exit 1
+        error = "Error: Credentials are required to connect to the server at #{@api_url}."
       rescue
-        puts <<-ERR
-Error: Could not connect to the server at #{@api_url}. More help is available after pointing
-the client to a Razor server
-        ERR
-        exit 1
+        error = "Error: Could not connect to the server at #{@api_url}."
+      ensure
+        return [(<<-OUTPUT + "\n" + error).rstrip, error != '' ? 1 : 0]
+        Razor Server version: #{server_version}
+        Razor Client version: #{Razor::CLI::VERSION}
+        OUTPUT
       end
     end
 
@@ -105,10 +102,23 @@ HELP
 Error: Credentials are required to connect to the server at #{@api_url}"
 UNAUTH
         exit = 1
-      rescue
+      rescue SocketError, Errno::ECONNREFUSED => e
+        puts "Error: Could not connect to the server at #{@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 OpenSSL::SSL::SSLError => e
+        # Occurs in case of e.g. certificate mismatch (FQDN vs. hostname)
+        puts "Error: SSL certificate error from server at #{@api_url}"
+        puts "       #{e}"
+        die
+      rescue => e
         output << <<-ERR
-Error: Could not connect to the server at #{@api_url}. More help is available after pointing
-the client to a Razor server
+Error: Unknown error occurred while connecting to server at #{@api_url}:
+       #{e}
 ERR
         exit = 1
       end
@@ -143,23 +153,34 @@ ERR
     # The format can be determined from later segments.
     attr_accessor :format, :stripped_args, :ssl_ca_file
 
+    LINUX_PEM_FILE = '/etc/puppetlabs/puppet/ssl/certs/ca.pem'
+    WIN_PEM_FILE = 'C:\ProgramData\PuppetLabs\puppet\etc\ssl\certs\ca.pem'
     def initialize(args)
       parse_and_set_api_url(ENV["RAZOR_API"] || DEFAULT_RAZOR_API, :env)
       @args = args.dup
       # To be populated externally.
       @stripped_args = []
       @format = 'short'
+      @verify_ssl = true
+      env_pem_file = ENV['RAZOR_CA_FILE']
       # If this is set, it should actually exist.
-      if ENV['RAZOR_CA_FILE'] && !File.exists?(ENV['RAZOR_CA_FILE'])
-        raise Razor::CLI::InvalidCAFileError.new(ENV['RAZOR_CA_FILE'])
+      if env_pem_file && !File.exists?(env_pem_file)
+        raise Razor::CLI::InvalidCAFileError.new(env_pem_file)
+      end
+      pem_file_locations = [env_pem_file, LINUX_PEM_FILE, WIN_PEM_FILE]
+      pem_file_locations.each do |file|
+        if file && File.exists?(file)
+          @ssl_ca_file = file
+          break
+        end
       end
-      ca_file = ENV["RAZOR_CA_FILE"]
-      @ssl_ca_file = ca_file if ca_file && File.exists?(ca_file)
       @args = get_optparse.order(@args)
 
       # Localhost won't match the server's certificate; no verification required.
       # This needs to happen after get_optparse so `-k` and `-u` can take effect.
-      @verify_ssl ||= (@api_url.hostname != 'localhost')
+      if @api_url.hostname == 'localhost'
+        @verify_ssl = false
+      end
 
       @args = set_help_vars(@args)
       if @args == ['version'] or @show_version

data/lib/razor/cli/table_format.rb

@@ -54,7 +54,7 @@ class Razor::CLI::TableFormat
   def average_width(headings)
     # The 3 here = 2 for width gap + 1 for the column separator.
     # The 1 is for the last separator.
-    console_width = `stty size | cut -d ' ' -f 2`
+    console_width = `stty size | cut -d ' ' -f 2 2>/dev/null`
     if console_width.nil? || console_width.to_i <= 0
       console_width = 80
     end

data/lib/razor/cli/version.rb

@@ -18,7 +18,7 @@ module Razor
     #
     # The next line is the one that our packaging tools modify, so please make
     # sure that any change to it is discussed and agreed first.
-    version = '1.1.0'
+    version = '1.2.0'
 
     if version == "DEVELOPMENT"
       root = File.expand_path("../../..", File.dirname(__FILE__))

data/spec/cli/command_spec.rb

@@ -63,4 +63,100 @@ describe Razor::CLI::Command do
       result.should == 'abc'
     end
   end
+
+  context "extract_command" do
+
+    def extract(schema, run_array)
+      c = Razor::CLI::Command.new(nil, nil, schema, run_array, nil)
+      c.extract_command
+    end
+    context "flag length" do
+
+      it "fails with a single dash for long flags" do
+        expect{extract({'schema' => {'name' => {'type' => 'array'}}}, ['-name', 'abc'])}.
+            to raise_error(ArgumentError, 'Unexpected argument -name (did you mean --name?)')
+      end
+      it "fails with a double dash for short flags" do
+        expect{extract({'schema' => {'n' => {'type' => 'array'}}}, ['--n', 'abc'])}.
+            to raise_error(ArgumentError, 'Unexpected argument --n (did you mean -n?)')
+      end
+      it "fails with a double dash for short flags if argument does not exist" do
+        c = Razor::CLI::Command.new(nil, nil, {'schema' => {}},
+                                    ['--n', 'abc'], '/foobar')
+        expect{extract({'schema' => {}}, ['--n', 'abc'])}.
+            to raise_error(ArgumentError, 'Unexpected argument --n')
+      end
+      it "succeeds with a double dash for long flags" do
+        extract({'schema' => {'name' => {'type' => 'array'}}},
+                ['--name', 'abc'])['name'].should == ['abc']
+      end
+      it "succeeds with a single dash for short flags" do
+        c = Razor::CLI::Command.new(nil, nil, {'schema' => {'n' => {'type' => 'array'}}},
+                                    ['-n', 'abc'], nil)
+        extract({'schema' => {'n' => {'type' => 'array'}}}, ['-n', 'abc'])['n'].should == ['abc']
+      end
+    end
+
+    context "positional arguments" do
+      let(:schema) do
+        {'schema' => {'n' => {'position' => 1},
+                      'o' => {'position' => 0}}}
+      end
+      it "fails without a command schema" do
+        expect{extract(nil, ['123'])}.
+            to raise_error(ArgumentError, 'Unexpected argument 123')
+      end
+      it "fails if no positional arguments exist for a command" do
+        expect{extract({'schema' => {'n' => {}}}, ['abc'])}.
+            to raise_error(ArgumentError, 'Unexpected argument abc')
+      end
+      it "succeeds if no position is supplied" do
+        extract({'schema' => {'n' => {'position' => 0}}}, ['-n', '123'])['n'].
+            should == '123'
+      end
+      it "succeeds if position exists and is supplied" do
+        extract({'schema' => {'n' => {'position' => 0}}}, ['123'])['n'].
+            should == '123'
+      end
+      it "succeeds if multiple positions exist and are supplied" do
+        body = extract(schema, ['123', '456'])
+        body['o'].should == '123'
+        body['n'].should == '456'
+      end
+      it "fails if too many positions are supplied" do
+        expect{extract(schema, ['123', '456', '789'])}.
+            to raise_error(ArgumentError, 'Unexpected argument 789')
+      end
+      it "succeeds if multiple positions exist and one is supplied" do
+        body = extract(schema, ['123'])
+        body['o'].should == '123'
+        body['n'].should == nil
+      end
+      it "succeeds with a combination of positional and flags" do
+        body = extract(schema, ['123', '-n', '456'])
+        body['o'].should == '123'
+        body['n'].should == '456'
+      end
+      it "prefers the later between positional and flags" do
+        body = extract(schema, ['123', '-o', '456'])
+        body['o'].should == '456'
+        body = extract(schema, ['-o', '456', '123'])
+        body['o'].should == '123'
+      end
+      it "correctly sets datatypes" do
+        schema =
+            {'schema' => {'n' => {'type' => 'array', 'position' => 0},
+                          'o' => {'type' => 'number', 'position' => 1},
+                          'w' => {'type' => 'boolean', 'position' => 2},
+                          'a' => {'type' => 'object', 'position' => 3},
+                          'i' => {'type' => 'object', 'position' => 4}}}
+        body = extract(schema, ['arr', '123', 'true', '{}', 'abc=123'])
+        body['n'].should == ['arr']
+        body['o'].should == 123
+        body['w'].should == true
+        body['a'].should == {}
+        body['i'].should == {'abc' => '123'}
+      end
+    end
+  end
 end