splunker 0.0.0 → 0.0.1

data/README.md

@@ -2,6 +2,8 @@
 
 A Ruby client for the [RESTful Splunk API](http://dev.splunk.com/view/rest-api-overview/SP-CAAADP8)
 
+Consider this largely functional but alpha.  See the TODO list below.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -18,17 +20,75 @@ Or install it yourself as:
 
 ## Usage
 
-Models are on there way, but you can access resources by directly invoking the
+Models are on the way, but you can access resources by directly invoking the
 HTTP helper methods.
 
+# Console
+To make playing around with the API client a smooth(er) experience, you can fire up our IRB wrapper by:
+
+    $ bundle exec script/console 
+    Enabling console mode for local gem
+    Loading splunker gem...
+    Splunker:001:0> c = Splunker.client(:auth_mode => :http_auth)
+    #<Splunker::Client:0x007f9782b0d238 @endpoint="https://localhost:8089", @app="search", @ssl_verify=true, @request_handler=#<Splunker::Auth::HttpAuth:0x007f9782b0cf68 @client=#<Splunker::Client:0x007f9782b0d238 ...>>, @password=nil, @username=nil>
+
 # Basic Auth
     c = Splunker.client(:auth_mode => :http_auth, :username => "MYUSERNAME", 
       :password => "MYPASSWORD", :endpoint => "https://splunk.mysite.com")
     # Returns Nokogiri::XML::Document 
-    r = c.get("/servicesNS/joshua/search/saved/searches/MySearch/history")
+    # Note that /servicesNS/YOUR_USERNAME/YOUR_APPNAME is prepended automatically
+    # to your resource.
+    r = c.get("/saved/searches/MySearch/history")
     # Process away
     r.xpath("...")
     
+## Exceptions
+
+The API client raises an exception when a non-2XX [response codes](http://docs.splunk.com/Documentation/Splunk/latest/RESTAPI/RESTusing#Response_status) is received.
+
+<table>
+  <thead>
+    <tr>
+      <th>HTTP Code</th>
+      <th>Splunk API Error Code</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>401</td>
+      <td>Splunker::Errors::AuthenticationFailureError</td>
+    </tr>
+    <tr>
+      <td>402</td>
+      <td>Splunker::Errors::FeatureDisabledError</td>
+    </tr>
+    <tr>
+      <td>403</td>
+      <td>Splunker::Errors::PermissionDeniedError</td>
+    </tr>
+    <tr>
+      <td>404</td>
+      <td>Splunker::Errors::ObjectDoesNotExistError</td>
+    </tr>
+    <tr>
+      <td>405</td>
+      <td>Splunker::Errors::MethodNotAllowedError</td>
+    </tr>
+    <tr>
+      <td>409</td>
+      <td>Splunker::Errors::InvalidOperationError</td>
+    </tr>
+    <tr>
+      <td>500</td>
+      <td>Splunker::Errors::InternalServerError </td>
+    </tr>
+    <tr>
+      <td>Any other non-2xx response</td>
+      <td>Splunker::Errors::ClientError</td>
+    </tr>
+  </tbody>
+</table>
+
 ## Contributing
 
 1. Fork it
@@ -36,3 +96,8 @@ HTTP helper methods.
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
+
+# TODO
+* Token Auth
+* Resource creation handling, blocking & polling options, with a timeout.
+* Build console into gem (bin/)

data/VERSION

@@ -1 +1 @@
-0.0.0
+0.0.1

data/lib/splunker.rb

@@ -3,7 +3,21 @@ require "splunker/version"
 require "splunker/client"
 require "splunker/errors"
 
+# The parent Splunker module can directly invoke any method invokable by the 
+# client returned in Splunker.client, so long as Splunker.client has been
+# called once with options to instantiate a new client.
+#
+# If using the helper models, you must first configure Splunker with
+# Splunker.client({ :options => "..." }), as they all reference Splunker.client
+# when they make requests.
 module Splunker
+
+  # Returns a reference to the current Splunk API client if no options are
+  # supplied.  Otherwise, generates a new Splunker client.
+  #
+  # Parameters:
+  # * options => See Splunker::Client's initialize method for details.
+  # Returns an instance of Splunker::Client 
   def self.client(options={})
     unless options.empty?
       Thread.current[:splunker_client] = Splunker::Client.new(options)
@@ -12,6 +26,7 @@ module Splunker
     Thread.current[:splunker_client] 
   end
 
+  # A reference to the Splunker logger
   def self.logger
     if @logger.nil?
       @logger = Logger.new(STDOUT)
@@ -20,6 +35,8 @@ module Splunker
     @logger
   end
 
+  # Parameters:
+  # * custom_logger => A custom logger to use instead of Logger
   def self.logger=(custom_logger)
     @logger = custom_logger
   end

data/lib/splunker/auth.rb

@@ -7,9 +7,16 @@ end
 
 module Splunker
   module Auth
-    def self.create(auth_type, configuration)
+    # Factory to create a authenticated Request wrapper for a specified auth type.
+    # Parameters:
+    # * auth_type => A symbol representing the auth type to generate.  Should be a symbolized
+    #                class name for an existing implementation. (e.g. :http_auth, :token_auth)
+    # * client    => A reference to the Splunker client instance.
+    # Returns an instance of the authenticated request wrapper noted by auth_type
+    # Raises ArgumentError if auth_type is invalid
+    def self.create(auth_type, client)
       if (obj = Splunker::Auth.const_get("#{auth_type}".split('_').collect(&:capitalize).join))
-        obj.new(configuration)
+        obj.new(client)
       else
         raise ArgumentError, "Unknown auth type of #{auth_type}"
       end

data/lib/splunker/auth/http_auth.rb

@@ -1,5 +1,6 @@
 module Splunker
   module Auth
+    # Wraps Splunk API requests with basic authentication
     class HttpAuth < SplunkAuth
       def authenticate_connection(conn)
         return if self.configured?

data/lib/splunker/client.rb

@@ -2,9 +2,21 @@ require 'splunker/configuration'
 require 'splunker/auth'
 
 module Splunker
+  # The Splunk API client.
+  # Methods include get, post, put, and delete HTTP helpers:
+  #   c.get("...")
+  # See Splunker::Request for more details.
   class Client
     include Configuration
 
+    # Creates a new Splunker client instance.
+    # Options are:
+    # * :username   => Required. The username to make requests on behalf of
+    # * :password   => Required. The password to authenticate with
+    # * :auth_mode  => Required.  The authentication method to use.  :http_auth or :token_auth.
+    # * :endpoint   => ("https://localhost:8089") The host of the Splunk API
+    # * :ssl_verify => (true) If false, the SSL cert fro the Splunk server will not be verified.
+    # * :app        => ("search")
     def initialize(options={})
       self.reset
 

data/lib/splunker/connection.rb

@@ -7,6 +7,8 @@ module Splunker
       @connection = nil
     end
 
+    # Returns an existing, or new, Faraday instance.
+    # If a new connection is desired, #reset must be called.
     def connection
       if self.configuration[:endpoint].nil?
         raise ConfigurationError, "No endpoint set!"

data/lib/splunker/errors.rb

@@ -23,6 +23,14 @@ module Splunker
       500 => InternalServerError 
     } 
 
+    # Parameters:
+    # * http_status => The integer representing the HTTP status
+    # * body        => The response body.  Will be passed to the 
+    #                  error instance when raised, for additional
+    #                  information.
+    # Returns nil if no exception will be raised.
+    # Raises an error mapped to http_status in STATUS_CODE_TO_ERROR_MAP,
+    # or ClientError if status is not 2xx but no mapped error exists.
     def self.raise_error_for_status!(http_status, body)
       return nil if (200..299).include?(http_status)
 

data/lib/splunker/faraday_middleware.rb

@@ -6,7 +6,7 @@ module Splunker
     end
 
     def on_complete(env)
-      env[:body] = Nokogiri::XML(env[:body])
+      env[:body] = Nokogiri::Slop(env[:body])
       Splunker.logger.debug("Response Body: #{env[:body]}")
       Splunker::Errors.raise_error_for_status!(env[:status], env[:body])
       Splunker.logger.debug "Request successful!"

data/lib/splunker/models/resource.rb

@@ -16,11 +16,6 @@ module Splunker
 
       protected
 
-      # Basic path validation.  Does nothing useful atm. 
-      def self.assemble_path(path_str)
-        path_str.gsub(/\/+/,"/")
-      end
-
       # Escapes a object ID for use in a URI
       def self.escape_object_id(id_str)
         CGI.escape(id_str)

data/lib/splunker/request.rb

@@ -1,34 +1,81 @@
 require 'splunker/connection'
 
 module Splunker
+  # The Request module, to be used by classes that will make requests to
+  # the Splunk API.
+  #
+  # Note that any class that mixes in the Request module will also mix in
+  # Splunker::Connection automatically (see Splunker::Request.included)
   module Request
+    require 'addressable/uri'
 
+    # Authenticates the user (not the request) identified by
+    # :username and :password in the configuration.
     def authenticate; end
 
+    # true if #authenticate does _not_ need to be called.
     def authenticated?
       true
     end
 
+    # Attaches credentials to the supplied Faraday connection object.
     def authenticate_connection(conn)
       conn
     end
 
+    # HTTP GET helper method.
+    # Parameters:
+    # * resource   => The resource under configuration[:endpoint] to make the 
+    #                 request
+    # * parameters => GET parameters to supply with the request.
+    # Returns Nokogiri:XML:Document object, parsed from the response body.
+    # Raises an exception from Splunker::Errors in accordance with the status code.
     def get(resource, parameters={})
       request(:get, resource, parameters)
     end
 
-    #def post(resource, body={})
-    #  request(:post, resource, nil, body)
-    #end
+    def post(resource, body={})
+      request(:post, resource, nil, body)
+    end
 
     ###
     # put/delete can come as needed.
     ###
 
+    # HTTP request helper method.
+    # Parameters:
+    # * method     => A symbol representing the HTTP method (:get, :post, :put, :delete)
+    # * resource   => The resource under configuration[:endpoint] to make the 
+    #                 request
+    # * parameters => GET parameters to supply with the request.
+    # * body       => POST/PUT data
+    # Returns Nokogiri:XML:Document object, parsed from the response body.
+    # Raises an exception from Splunker::Errors in accordance with the status code.
     def request(method, resource, parameters={}, body={})
       authenticate unless authenticated?
       authenticate_connection(self.connection)
-      self.connection.send(method, resource).body
+      final_resource = resource_builder(resource, parameters)
+      self.connection.send(method, final_resource, body).body
+    end
+
+    # Returns a string representing the final resource path
+    def resource_builder(resource, parameters={})
+      u = Addressable::URI.new
+      u.path = assemble_path("/servicesNS/#{configuration[:username]}/#{configuration[:app]}/#{resource}")
+      unless parameters.nil? || parameters.empty?
+        # Let's remap and cast everything to a string.
+        # Addressable doesn't handle values like true well.
+        final_parameters = {}
+        parameters.map do |key, value|
+          final_parameters[key] = "#{value}"
+        end
+        u.query_values = final_parameters 
+      end
+      u.to_s
+    end
+
+    def assemble_path(path_str)
+      path_str.gsub(/\/+/,"/")
     end
 
     def self.included(base)

data/spec/functional/request_spec.rb

@@ -0,0 +1,40 @@
+require 'spec_helper'
+describe Splunker::Request do
+  context "successful requests" do
+    it "should return the response body as an Nokogiri::XML::Document" do
+      stub_fixture(client, "generic/search/results/get", "search_results_from_job.xml",
+                  :parameters => {:parameter1 => "OK"})
+      client.get("generic/search/results/get").should be_a(Nokogiri::XML::Document)
+    end
+
+    it "should successfully perform post requests" do
+      stub_fixture(client, "generic/search/results/post", "search_results_from_job.xml",
+                  :method => :post, :data => {:parameter1 => "OK"})
+      client.post("generic/search/results/post", :parameter1 => "OK").should be_a(Nokogiri::XML::Document)
+    end
+  end
+
+  context "authentication" do # TODO: Once we have token_auth in place.
+    it "should not authenticate unless needed" do
+    end
+    it "should authenticated if needed" do
+    end
+    it "should retry authentication once if a 401 is returned" do
+    end
+  end
+
+  context "http errors" do
+    it "should raise a mapped exception with a known HTTP error" do
+      stub_http_error(client, 405)
+      expect {
+        client.get("error/405")
+      }.to raise_error Splunker::Errors::MethodNotAllowedError
+    end
+    it "should raise a client error with an unknown status code" do
+      stub_http_error(client, 499)
+      expect {
+        client.get("error/499")
+      }.to raise_error Splunker::Errors::ClientError
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,4 +1,5 @@
 require 'rspec'
+require 'webmock/rspec'
 require 'splunker'
 require 'rspec_let_definitions'
 
@@ -6,4 +7,34 @@ RSpec.configure do |config|
   config.color_enabled = true
   config.formatter     = 'documentation'
   config.include Splunker::RspecLetDefinitions
+  config.include WebMock::API
+end
+
+def fixture(file)
+  File.new( File.expand_path('../fixtures', __FILE__) + "/" + file)
+end
+
+def basic_auth_resource_builder(client, resource)
+  path = client.resource_builder(resource)
+  endpoint = client.configuration[:endpoint]
+  endpoint.gsub!("https://", "https://#{client.configuration[:username]}:#{client.configuration[:password]}@")
+
+  "#{endpoint}#{path}"
+end
+
+def stub_basic_auth_request(client, resource, method=:get)
+  uri = basic_auth_resource_builder(client,resource)
+  stub_request(method, uri)
+end
+
+def stub_http_error(client, code, method=:get)
+  stub_basic_auth_request(client, "error/#{code}", method).to_return(:status => code)
+end
+
+def stub_fixture(client, resource, fixture_file, options={:method => :get, :status=>200, :parameters => {},
+                   :post_data => {}})
+  code = (options[:status] || 200)
+  method = (options[:method] || :get)
+  stub_basic_auth_request(client, resource, method).to_return(:status => code,
+    :body => fixture(fixture_file))
 end

data/spec/unit/request_spec.rb

@@ -0,0 +1,17 @@
+describe Splunker::Request do
+  context "assembling a path" do
+    it "should strip repeated slashes" do
+      client.assemble_path("//search//joshua/saved/searches").should eq("/search/joshua/saved/searches")
+    end
+  end
+
+  context "building a resource path" do
+    it "should assemble the path from the username and app name" do
+      client.resource_builder("saved/searches").should eq("/servicesNS/tido/search/saved/searches")
+    end
+    it "should assemble the path with query parameters" do
+      client.resource_builder("saved/searches", :parameter1 => "me", 
+                             :parameter2 => true).should eq("/servicesNS/tido/search/saved/searches?parameter1=me&parameter2=true")
+    end
+  end
+end

data/splunker.gemspec

@@ -17,6 +17,7 @@ Gem::Specification.new do |gem|
 
   gem.add_dependency "nokogiri"
   gem.add_dependency "faraday"
+  gem.add_dependency "addressable"
   gem.add_development_dependency "rspec", "~> 2.11"
   gem.add_development_dependency "rake", "~> 0.9.2"
   gem.add_development_dependency "webmock"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: splunker
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-09-10 00:00:00.000000000 Z
+date: 2012-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -43,6 +43,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -125,6 +141,7 @@ files:
 - lib/splunker/version.rb
 - script/console
 - spec/fixtures/search_results_from_job.xml
+- spec/functional/request_spec.rb
 - spec/rspec_let_definitions.rb
 - spec/spec_helper.rb
 - spec/unit/auth/http_auth_spec.rb
@@ -132,6 +149,7 @@ files:
 - spec/unit/client_spec.rb
 - spec/unit/configuration_spec.rb
 - spec/unit/errors_spec.rb
+- spec/unit/request_spec.rb
 - spec/unit/splunker_spec.rb
 - splunker.gemspec
 homepage: ''
@@ -160,6 +178,7 @@ specification_version: 3
 summary: A Ruby client for the Splunk API
 test_files:
 - spec/fixtures/search_results_from_job.xml
+- spec/functional/request_spec.rb
 - spec/rspec_let_definitions.rb
 - spec/spec_helper.rb
 - spec/unit/auth/http_auth_spec.rb
@@ -167,4 +186,5 @@ test_files:
 - spec/unit/client_spec.rb
 - spec/unit/configuration_spec.rb
 - spec/unit/errors_spec.rb
+- spec/unit/request_spec.rb
 - spec/unit/splunker_spec.rb