splunk-sdk-ruby 0.1.0 → 0.8.1

data/lib/splunk-sdk-ruby/collection/input_kinds.rb

@@ -0,0 +1,136 @@
+#--
+# Copyright 2011-2013 Splunk, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"): you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#++
+
+require_relative '../collection'
+
+##
+# Provide a class representing a collection of input kinds.
+#
+module Splunk
+  ##
+  # A collection of input types.
+  #
+  # Inputs in the Splunk REST API are arranged in what looks like a
+  # directory structure, as in
+  #
+  #     monitor/
+  #     tcp/
+  #       cooked/
+  #       raw/
+  #     udp/
+  #
+  # You get the top level directory by calling +inputs+ on your +Service+.
+  # Then you can use it as if it were a Hash. If you fetch an entry that has
+  # subtypes, such as +tcp+, you get another +InputKinds+ containing the types
+  # in that entry. If you fetch an entry that doesn't have subtypes, such as
+  # "udp", then you get an +Inputs+ object (a subclass of +Collection+)
+  # containing specific inputs.
+  #
+  # *Example*:
+  #
+  #      # Returns an InputKinds collection
+  #      tcp_inputs = service.inputs["tcp"]
+  #      tcp_inputs.has_key?("raw")    # ==> true
+  #      tcp_inputs.has_key?("cooked") # ==> true
+  #
+  #      # A read only collection of all the inputs in Splunk.
+  #      service.inputs["all"]
+  #
+  #      # An Inputs object containing all the UDP inputs in Splunk.
+  #      service.inputs["udp"]
+  #
+  class InputKinds < ReadOnlyCollection
+    def fetch(name, namespace=nil)
+      request_args = {:resource => @resource + [name]}
+      if not namespace.nil?
+        request_args[:namespace] = namespace
+      end
+
+      begin
+        response = @service.request(request_args)
+      rescue SplunkHTTPError => err
+        if err.code == 404
+          return nil
+        else
+          raise err
+        end
+      end
+
+      feed = AtomFeed.new(response.body)
+      if feed.metadata["links"].has_key?("create")
+        Inputs.new(@service, resource + [name])
+      elsif name == "all"
+        ReadOnlyCollection.new(@service, resource + [name])
+      else
+        InputKinds.new(@service, resource + [name])
+      end
+    end
+  end
+
+  ##
+  # A collection of specific inputs.
+  #
+  class Inputs < Collection
+    def initialize(service, resource)
+      super(service, resource)
+      @always_fetch = true
+    end
+
+    def create(name, args={})
+      body_args = args.clone()
+      body_args["name"] = name
+
+      request_args = {
+          :method => :POST,
+          :resource => @resource,
+          :body => body_args
+      }
+      if args.has_key?(:namespace)
+        request_args[:namespace] = body_args.delete(:namespace)
+      end
+
+      @service.request(request_args)
+
+      # If we have created a oneshot input, no actual entity
+      # is created. We return nil here in that case.
+      if @resource == ["data", "inputs", "oneshot"]
+        return nil
+      end
+
+      # TCP and UDP inputs have a key restrictToHost. If it is set
+      # then they are created with hostname:port as their resource
+      # instead of just port, and we must adjust our behavior
+      # accordingly.
+      if args.has_key?(:restrictToHost)
+        name = args[:restrictToHost] + ":" + name
+      end
+
+      fetch_args = {:method => :GET,
+                    :resource => @resource + [name]}
+      if args.has_key?(:namespace)
+        fetch_args[:namespace] = args[:namespace]
+      end
+      response = @service.request(fetch_args)
+
+      feed = AtomFeed.new(response.body)
+      raise StandardError.new("No entities returned") if feed.entries.empty?
+      entity = atom_entry_to_entity(feed.entries[0])
+      raise StandardError.new("Found nil entity.") if entity.nil?
+      return entity
+    end
+
+  end
+end

data/lib/splunk-sdk-ruby/collection/jobs.rb

@@ -51,7 +51,7 @@ module Splunk
     # Creates an asynchronous search job.
     #
     # The search job requires a _query_, and takes a hash of other, optional
-    # arguments, which are documented in the {Splunk REST documentation}[http://docs.splunk.com/Documentation/Splunk/latest/RESTAPI/RESTsearch#search.2Fjobs - POST].
+    # arguments, which are documented in the {Splunk REST documentation}[http://docs.splunk.com/Documentation/Splunk/latest/RESTAPI/RESTsearch#search.2Fjobs].
     #
     def create(query, args={})
       if args.has_key?(:exec_mode)
@@ -81,6 +81,10 @@ module Splunk
     def create_oneshot(query, args={})
       args[:search] = query
       args[:exec_mode] = 'oneshot'
+      # Suppress segmentation (<sg> tags in the XML response) by default:
+      if !args.has_key?(:segmentation)
+        args[:segmentation] = "none"
+      end
       response = @service.request(:method => :POST,
                                   :resource => @resource,
                                   :body => args)
@@ -100,6 +104,10 @@ module Splunk
     #
     def create_export(query, args={})
       args["search"] = query
+      # Suppress segmentation (<sg> tags in the XML response) by default:
+      if !args.has_key?(:segmentation)
+        args[:segmentation] = "none"
+      end
       response = @service.request(:method => :GET,
                                   :resource => @resource + ["export"],
                                   :query => args)

data/lib/splunk-sdk-ruby/context.rb

@@ -232,13 +232,13 @@ module Splunk
     # * +method+: The HTTP method to use (one of +:GET+, +:POST+, or +:DELETE+;
     #   default: +:GET+).
     # * +namespace+: The namespace to request a resource from Splunk in. Must
-    #   be a +Namespace+ object. (default: the value of +@namespace+ on
+    #   be a +Namespace+ object. (default: the value of @+namespace+ on
     #   this +Context+)
     # * +resource+: An array of strings specifying the components of the path
     #   to the resource after the namespace. The strings should not be URL
     #   encoded, as that will be handled by +request+. (default: [])
     # * +query+: A hash containing the values to be encoded as
-    #   the query (the part following +?+) in the URL. Nothing should be URL
+    #   the query (the part following "?") in the URL. Nothing should be URL
     #   encoded as +request+ will do the encoding. If you need to pass multiple
     #   values for the same key, insert them as an Array as the value of their
     #   key into the Hash, and they will be properly encoded as a sequence of
@@ -332,7 +332,7 @@ module Splunk
     #   make a request to.
     # * +:method+: (+:GET+, +:POST+, or +:DELETE+) The HTTP method to use.
     # * +query+: A hash containing the values to be encoded as
-    #   the query (the part following +?+) in the URL. Nothing should be URL
+    #   the query (the part following "?") in the URL. Nothing should be URL
     #   encoded as +request+ will do the encoding. If you need to pass multiple
     #   values for the same key, insert them as an +Array+ as the value of their
     #   key into the Hash, and they will be properly encoded as a sequence of
@@ -445,7 +445,8 @@ module Splunk
                             " of the Splunk Ruby SDK"})
 
       # Make the actual restart request.
-      request(:resource => ["server", "control", "restart"])
+      request(:method => :POST,
+              :resource => ["server", "control", "restart"])
 
       # Clear our old token, which will no longer work after the restart.
       logout()
@@ -478,6 +479,8 @@ module Splunk
         request(:resource => ["data", "indexes"])
       rescue Errno::ECONNREFUSED, EOFError, Errno::ECONNRESET
         return false
+      rescue OpenSSL::SSL::SSLError
+        return false
       rescue SplunkHTTPError
         # Splunk is up, because it responded with a proper HTTP error
         # that our SplunkHTTPError parser understood.

data/lib/splunk-sdk-ruby/entity.rb

@@ -21,24 +21,12 @@ require_relative 'synonyms'
 
 module Splunk
   ##
-  # Class representing individual entities in Splunk.
-  #
-  # +Entity+ objects represent individual items such as indexes, users, roles,
-  # etc. They are usually contained within +Collection+ objects.
+  # ReadOnlyEntity represents entities that can be read, but not created or
+  # updated, via the REST API. The canonical example is a modular input kind.
   #
-  # The basic, identifying information for an +Entity+ (name, namespace, path
-  # of the collection containing entity, and the service it's on) is all
-  # accessible via getters (+name+, +namespace+, +resource+, +service+). All
-  # the fields containing the +Entity+'s state, such as the capabilities of
-  # a role or whether an app should check for updates, are accessible with 
-  # the [] operator (for instance, +role+["+capabilities+"] or 
-  # +app+["+check_for_updates+"]).
-  #
-  # +Entity+ objects cache their state, so each lookup of a field does not
-  # make a roundtrip to the server. The state may be refreshed by calling
-  # the +refresh+ method on the +Entity+.
-  #
-  class Entity
+  class ReadOnlyEntity
+    # ReadOnlyEntity was factored out of Entity to avoid having to add
+    # special behavior to modular input kinds.
     extend Synonyms
 
     def initialize(service, namespace, resource, name, state=nil) # :nodoc:
@@ -86,17 +74,6 @@ module Splunk
     #
     attr_reader :service
 
-    ##
-    # Deletes this entity from the server.
-    #
-    # Returns: +nil+.
-    #
-    def delete()
-      @service.request({:method => :DELETE,
-                        :namespace => @namespace,
-                        :resource => @resource + [name]})
-    end
-
     ##
     # Fetches the field _key_ on this entity.
     #
@@ -138,7 +115,7 @@ module Splunk
     # +Entity+. If you specify one or more +Strings+ or +Arrays+ of +Strings+,
     # all the keys specified in the arguments will be returned in the +Hash+.
     #
-    # Returns: a +Hash+ with +Strings+ as keys, and +Strings+ or +Hashes+ or 
+    # Returns: a +Hash+ with +Strings+ as keys, and +Strings+ or +Hashes+ or
     # +Arrays+ as values.
     #
     def read(*field_list)
@@ -187,6 +164,37 @@ module Splunk
       @state = feed.entries[0]
       self
     end
+  end
+
+  ##
+  # Class representing individual entities in Splunk.
+  #
+  # +Entity+ objects represent individual items such as indexes, users, roles,
+  # etc. They are usually contained within +Collection+ objects.
+  #
+  # The basic, identifying information for an +Entity+ (name, namespace, path
+  # of the collection containing entity, and the service it's on) is all
+  # accessible via getters (+name+, +namespace+, +resource+, +service+). All
+  # the fields containing the +Entity+'s state, such as the capabilities of
+  # a role or whether an app should check for updates, are accessible with 
+  # the [] operator (for instance, +role+["+capabilities+"] or 
+  # +app+["+check_for_updates+"]).
+  #
+  # +Entity+ objects cache their state, so each lookup of a field does not
+  # make a roundtrip to the server. The state may be refreshed by calling
+  # the +refresh+ method on the +Entity+.
+  #
+  class Entity < ReadOnlyEntity
+    ##
+    # Deletes this entity from the server.
+    #
+    # Returns: +nil+.
+    #
+    def delete()
+      @service.request({:method => :DELETE,
+                        :namespace => @namespace,
+                        :resource => @resource + [name]})
+    end
 
     ##
     # Updates the values on the Entity specified in the arguments.

data/lib/splunk-sdk-ruby/entity/job.rb

@@ -105,10 +105,14 @@ module Splunk
     # Returns: a stream that can be read with +ResultsReader+.
     #
     def events(args={})
+      # Suppress segmentation (<sg> tags in the XML response) by default:
+      if !args.has_key?(:segmentation)
+        args[:segmentation] = "none"
+      end
       response = @service.request(
           :method => :GET,
           :resource => @resource + [sid, "events"],
-          :body => args)
+          :query => args)
       return response.body
     end
 
@@ -192,10 +196,14 @@ module Splunk
     # Returns: a stream readable by +ResultsReader+.
     #
     def preview(args={})
+      # Suppress segmentation (<sg> tags in the XML response) by default:
+      if !args.has_key?(:segmentation)
+        args[:segmentation] = "none"
+      end
       response = @service.request(:method => :GET,
                                   :resource => @resource +
                                       [sid, "results_preview"],
-                                  :body => args)
+                                  :query => args)
       return response.body
     end
 
@@ -247,7 +255,7 @@ module Splunk
     end
 
     ##
-    # Return the +Job's+ search id.
+    # Return the +Job+'s search id.
     #
     # Returns: a +String+.
     #
@@ -268,7 +276,7 @@ module Splunk
     # duration), and +:time+ (a string representing the bucket's time in human
     # readable form).
     #
-    # Returns: an +Array+ of +Hash+es describing each time bucket.
+    # Returns: an +Array+ of Hashes describing each time bucket.
     #
     def timeline(args={})
       response = @service.request(:resource => @resource + [sid, "timeline"],

data/lib/splunk-sdk-ruby/entity/modular_input_kind.rb

@@ -0,0 +1,47 @@
+#--
+# Copyright 2011-2013 Splunk, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"): you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#++
+
+require_relative '../entity'
+
+module Splunk
+  ##
+  # Class representing a family of user defined inputs on the server.
+  #
+  # Modular input kinds define new, first-class input kinds on the server.
+  # This endpoint provides access to a list of the arguments and parameters
+  # of the various kinds defined. The actual inputs of these kinds can be
+  # accessed via the Serve#inputs method.
+  #
+  # Modular input kinds are read only, so there is no update or delete method
+  # on this class.
+  #
+  class ModularInputKind < ReadOnlyEntity
+    ##
+    # Return a Hash of all the arguments support by this modular input kind.
+    #
+    # The keys in the Hash are the names of the arguments. The values are
+    # additional Hashes giving the metadata about each argument. The possible
+    # keys in those Hashes are +"title"+, +"description"+,
+    # +"required_on_create``+, +"required_on_edit"+, +"data_type"+. Each value is
+    # a string. It should be one of +"true"+ or +"false"+ for
+    # +"required_on_create"+ and +"required_on_edit"+, and one of +"boolean"+,
+    # +"string"+, or +"number"+ for +"data_type"+.
+    #
+    def arguments
+      @state["content"]["endpoint"]["args"]
+    end
+  end
+end

data/lib/splunk-sdk-ruby/resultsreader.rb

@@ -98,6 +98,18 @@ module Splunk
   #   in this set, in the order they should be displayed (if you're going
   #   to make a table or the like)
   #
+  # The values yielded by calling +each+ and similar methods on +ResultsReader+
+  # are of class +Event+, which is a subclass of +Hash+ with one extra method,
+  # +segmented_raw+. The fields of the event are available as values in the hash,
+  # with no escaped characters and no XML tags. The +_raw+ field, however, is
+  # returned with extra XML specifying how terms should be highlighted for
+  # display, and this full XML form is available by called the +segmented_raw+
+  # method. The XML returned looks something like:
+  #
+  #     "<v xml:space=\"preserve\" trunc=\"0\">127.0.0.1 - admin
+  #     [11/Feb/2013:10:42:49.790 -0800] \"POST /services/search/jobs/export
+  #     HTTP/1.1\" 200 440404 - - - 257ms</v>"
+  #
   # *Example*:
   #
   #     require 'splunk-sdk-ruby'
@@ -105,11 +117,12 @@ module Splunk
   #     service = Splunk::connect(:username => "admin", :password => "changeme")
   #
   #     stream = service.jobs.create_oneshot("search index=_internal | head 10")
-  #     reader = ResultsReader.new(stream)
+  #     reader = Splunk::ResultsReader.new(stream)
   #     puts reader.is_preview?
   #     # Prints: false
   #     reader.each do |result|
-  #       puts result
+  #       puts result # Prints the fields in the result as a Hash
+  #       puts result.segmented_raw() # Prints the XML version of the _raw field
   #     end
   #     # Prints a sequence of Hashes containing events.
   #
@@ -137,7 +150,7 @@ module Splunk
     def initialize(text_or_stream)
       if text_or_stream.nil?
         stream = StringIO.new("")
-      elsif stream.is_a?(ExportStream)
+      elsif text_or_stream.is_a?(ExportStream)
         # The sensible behavior on streams from the export endpoints is to
         # skip all preview results and concatenate all others. The export
         # functions wrap their streams in ExportStream to mark that they need
@@ -154,11 +167,9 @@ module Splunk
         stream = text_or_stream
       end
 
-      if stream.eof?
+      if !stream.nil? and stream.eof?
         @is_preview = nil
         @fields = []
-      elsif stream.is_a?(ExportStream)
-
       else
         # We use a SAX parser. +listener+ is the event handler, but a SAX
         # parser won't usually transfer control during parsing. 
@@ -186,8 +197,7 @@ module Splunk
       if @is_export
         warn "[DEPRECATED] Do not use ResultsReader on the output of the " +
                  "export endpoint. Use MultiResultsReader instead."
-        reader = MultiResultsReader.new(@stream).final_results()
-        enum = reader.each()
+        enum = @reader.each()
       else
         enum = Enumerator.new() do |yielder|
           if !@iteration_fiber.nil? # Handle the case of empty files
@@ -219,6 +229,24 @@ module Splunk
     end
   end
 
+  ##
+  # +Event+ represents a single event returned from a +ResultsReader+.
+  #
+  # +Event+ is a subclass of +Hash+, adding a single method +segmented_raw()+
+  # which returns a string containing the XML of the raw event, as opposed
+  # to the unescaped, raw strings returned by fetching a particular field
+  # via [].
+  #
+  class Event < Hash
+    @raw_xml = nil
+
+    attr_writer :raw_xml
+
+    def segmented_raw
+      @raw_xml
+    end
+  end
+
   ##
   # +ResultsListener+ is the SAX event handler for +ResultsReader+.
   #
@@ -269,7 +297,7 @@ module Splunk
                 elsif name == "result"
                   @state = :result
                   @current_offset = Integer(attributes["offset"])
-                  @current_result = {}
+                  @current_result = Event.new()
                 end
               end,
               :end_element => lambda do |name|
@@ -326,7 +354,23 @@ module Splunk
                   @current_value = nil
                 elsif name == "text" || name == "v"
                   @state = :field_values
-                  @current_scratch = ""
+                  @current_text = ""
+                  s = ["v"] + attributes.map do |entry|
+                    key, value = entry
+                    # Nokogiri and REXML both drop the namespaces of attributes,
+                    # and there is no way to recover them. To reconstruct the
+                    # XML (since we can't get at its raw form) we put in the
+                    # one instance of a namespace on an attribute that shows up
+                    # in what Splunk returns. Yes, this is a terribly, ugly
+                    # kludge.
+                    if key == "space"
+                      prefixed_key = "xml:space"
+                    else
+                      prefixed_key = key
+                    end
+                    "#{prefixed_key}=\"#{value}\""
+                  end
+                  @current_xml = "<" + s.join(" ") + ">"
                 end
               end,
               :end_element => lambda do |name|
@@ -346,6 +390,11 @@ module Splunk
                   else
                     @current_result[@current_field] = @current_value
                   end
+
+                  if @current_field == "_raw"
+                    @current_result.raw_xml = @current_xml
+                  end
+
                   @current_field = nil
                   @current_value = nil
                 end
@@ -356,19 +405,23 @@ module Splunk
               :end_element => lambda do |name|
                 if name == "text" || name == "v"
                   if @current_value == nil
-                    @current_value = @current_scratch
+                    @current_value = @current_text
                   elsif @current_value.is_a?(Array)
-                    @current_value << @current_scratch
+                    @current_value << @current_text
                   else
-                    @current_value = [@current_value, @current_scratch]
+                    @current_value = [@current_value, @current_text]
+                  end
+
+                  if name == "v"
+                    @current_xml << "</v>"
                   end
 
-                  @current_scratch = nil
+                  @current_text = nil
                   @state = :result
                 elsif name == "sg"
                   # <sg> is emitted to delimit text that should be displayed
                   # highlighted. We preserve it in field values.
-                  @current_scratch << "</sg>"
+                  @current_xml << "</sg>"
                 end
               end,
               :start_element => lambda do |name, attributes|
@@ -378,11 +431,12 @@ module Splunk
                     "#{key}=\"#{value}\""
                   end
                   text = "<" + s.join(" ") + ">"
-                  @current_scratch << text
+                  @current_xml << text
                 end
               end,
               :characters => lambda do |text|
-                @current_scratch << text
+                @current_text << text
+                @current_xml << Splunk::escape_string(text)
               end
           }
       }