splunk-sdk-ruby 0.1.0

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

@@ -0,0 +1,28 @@
+#--
+# 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.
+#++
+
+module Splunk
+  ##
+  # Exception thrown when a request found multiple matching entities.
+  #
+  # An entity is uniquely defined by its name plus its namespace, so when you
+  # try to fetch an entity by name alone, it is possible to get multiple
+  # results. In that case, this error is thrown by methods that are supposed 
+  # to return only a single entity.
+  #
+  class AmbiguousEntityReference < StandardError
+  end
+end

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

@@ -0,0 +1,323 @@
+#--
+# 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.
+#++
+
+##
+# +atomfeed.rb+ provides an +AtomFeed+ class to parse the Atom XML feeds
+# returned by most of Splunk's endpoints.
+#
+
+require_relative 'xml_shim'
+
+#--
+# Nokogiri returns attribute values as objects on which we have to call
+# `#text`. REXML returns Strings. To make them both work, add a `text` method to
+# String that returns itself.
+#++
+class String # :nodoc:
+  def text
+    self
+  end
+end
+
+#--
+# For compatibility with Nokogiri, we add a method `text`, which, like 
+# Nokogiri's `text` method, returns the contents without escaping entities. 
+# This is identical to REXML's `value` method.
+#++
+#if $splunk_xml_library == :rexml
+#  class REXML::Text # :nodoc:
+#    def text
+#      value
+#    end
+#  end
+#end
+
+module Splunk
+  ##
+  # Reads an Atom XML feed into a Ruby object.
+  #
+  # +AtomFeed.new+ accepts either a string or any object with a +read+ method.
+  # It parses that as an Atom feed and exposes two read-only fields, +metadata+
+  # and +entries+. The +metadata+ field is a hash of all the header fields of 
+  # the feed. The +entries+ field is a list of hashes giving the details of 
+  # each entry in the feed.
+  #
+  # *Example:*
+  #
+  #     file = File.open("some_feed.xml")
+  #     feed = AtomFeed.new(file)
+  #     # or AtomFeed.new(file.read())
+  #     # or AtomFeed.new(file, xml_library=:rexml)
+  #     feed.metadata.is_a?(Hash) == true
+  #     feed.entries.is_a?(Array) == true
+  #
+  class AtomFeed
+    public
+    def initialize(text_or_stream)
+      if text_or_stream.respond_to?(:read)
+        text = text_or_stream.read()
+      else
+        text = text_or_stream
+      end
+      # Sanity checks
+      raise ArgumentError, 'text is nil' if text.nil?
+      text = text.strip
+      raise ArgumentError, 'text size is 0' if text.size == 0
+
+      if $splunk_xml_library == :nokogiri
+        doc = Nokogiri::XML(text)
+      else
+        doc = REXML::Document.new(text)
+      end
+      # Skip down to the content of the Atom feed. Most of Splunk's
+      # endpoints return a feed of the form
+      #
+      #     <feed>
+      #        ...metadata...
+      #        <entry>...details of entry...</entry>
+      #        <entry>...details of entry...</entry>
+      #        <entry>...details of entry...</entry>
+      #        ...
+      #     </feed>
+      #
+      # with the exception of fetching a single job entity from Splunk 4.3,
+      # where it returns
+      #
+      #     <entry>...details of entry...</entry>
+      #
+      # To handle both, we have to check whether <feed> is there
+      # before skipping.
+      if doc.root.name == "feed"
+        @metadata, @entries = read_feed(doc.root)
+      elsif doc.root.name == "entry"
+        @metadata = {}
+        @entries = [read_entry(doc.root)]
+      else
+        raise ArgumentError, 'root element of Atom must be feed or entry'
+      end
+    end
+
+    ##
+    # The header fields of the feed.
+    #
+    # Typically this has keys such as "+author+", "+title+", and
+    # "+totalResults+".
+    #
+    # Returns: a +Hash+ with +Strings+ as keys.
+    #
+    attr_reader :metadata
+
+    ##
+    # The entries in the feed.
+    #
+    # Returns: an +Array+ containing +Hashes+ that represent each entry in the feed.
+    #
+    attr_reader :entries
+
+    private # All methods below here are internal to AtomFeed.
+
+    ##
+    # Produces a +String+ from the children of _element_.
+    #
+    # _element_ should be either a REXML or Nokogiri element.
+    #
+    # Returns: a +String+.
+    #
+    def children_to_s(element) # :nodoc:
+      result = ""
+      element.children.each do |child|
+        if $splunk_xml_library == :nokogiri
+          result << child.text
+        else
+          result << child.value
+        end
+      end
+      result
+    end
+
+    ##
+    # Reads a feed from the the XML in _feed_.
+    #
+    # Returns: [+metadata, entries+], where +metadata+ is a hash of feed
+    # headers, and +entries+ is an +Array+ of +Hashes+ representing the feed.
+    #
+    def read_feed(feed)
+      metadata = {"links" => {}, "messages" => []}
+      entries = []
+
+      feed.elements.each do |element|
+        if element.name == "entry"
+          entries << read_entry(element)
+        elsif element.name == "author"
+          # The author tag has the form <author><name>...</name></author>
+          # so we have to fetch the value out of the inside of it.
+          metadata["author"] = read_author(element)
+        elsif element.name == "generator"
+          # To handle elements of the form:
+          #     <generator build="144175" version="5.0.2"/>
+          metadata["generator"] = {}
+          element.attributes.each do |name, attribute|
+            metadata["generator"][name] = attribute.text
+          end
+        elsif element.name == "link"
+          rel, uri = read_link(element)
+          metadata["links"][rel] = uri
+        elsif element.name == "id"
+          metadata[element.name] = URI(children_to_s(element))
+        elsif element.name == "messages"
+          element.elements.each do |element|
+            if element.name == "msg"
+              metadata["messages"] << {
+                  "type" => element.attributes["type"].text.intern,
+                  "message" => children_to_s(element)
+              }
+            end
+          end
+        else
+          metadata[element.name] = children_to_s(element)
+        end
+      end
+
+      return metadata, entries
+    end
+
+    ##
+    # Reads a single entry from the XML in _entry_.
+    #
+    # Returns: a +Hash+ representing the entry.
+    #
+    def read_entry(entry)
+      result = {"links" => {}}
+      entry.elements.each do |element|
+        name = element.name
+        if name == "link"
+          rel, uri = read_link(element)
+          result["links"][rel] = uri
+        else
+          value = read_entry_field(element)
+          result[name] = value
+        end
+      end
+
+      return result
+    end
+
+    ##
+    # Reads a name and link from the XML in _link_.
+    #
+    # Returns: [+name, link+], where _name_ is a +String+ giving the name of
+    # the link, and _link_ is a +URI+.
+    #
+    def read_link(link)
+      # To handle elements of the form:
+      #     <link href="/%252FUsers%252Ffross%252Ffile%20with%20spaces"
+      # Note that the link is already URL encoded.
+      uri = URI(link.attributes['href'].text)
+      rel = link.attributes['rel'].text
+      return rel, uri
+    end
+
+    ##
+    # Reads a single field of an entry from the XML in _field_.
+    #
+    # Returns: a single value (either a +String+ or a +URI+).
+    #
+    def read_entry_field(field)
+      # We have to coerce this to an Array to call length,
+      # since Nokogiri defines `#length` on element sets,
+      # but REXML does not.
+      elements = Array(field.elements)
+      if elements.length == 0 # This is a simple text field
+        return read_simple_entry_field(field)
+      elsif elements.length > 1
+        raise ArgumentError, "Entry fields should contain one element " +
+            "(found #{elements.length} in #{field.to_s}."
+      elsif field.name == "author"
+        return read_author(field)
+      end
+
+      # Coerce to Array because Nokogiri indexes from 0, and REXML from 1.
+      # Arrays always index from 0.
+      value_element = Array(field.elements)[0]
+      if value_element.name == "dict"
+        return read_dict(value_element)
+      elsif value_element.name == "list"
+        return read_list(value_element)
+      end
+    end
+
+    ##
+    # Reads a simple field.
+    #
+    # Returns: a +String+ or a +URI+.
+    #
+    def read_simple_entry_field(field)
+      value = children_to_s(field)
+      if field.name == "id"
+        return URI(value)
+      else
+        return value
+      end
+    end
+
+    ##
+    # Reads a dictionary from the XML in _dict_.
+    #
+    # Returns: a +Hash+.
+    #
+    def read_dict(dict)
+      result = {}
+      dict.elements.each do |element|
+        key = element.attributes["name"].text
+        value = read_entry_field(element)
+        result[key] = value
+      end
+
+      return result
+    end
+
+    ##
+    # Reads an +Array+ from the XML in _list_.
+    #
+    # Returns: an +Array+.
+    #
+    def read_list(list)
+      result = []
+      list.elements.each do |element|
+        value = read_entry_field(element)
+        result << value
+      end
+
+      return result
+    end
+
+    ##
+    # Reads the author from its special tag.
+    #
+    # Returns: a +String+.
+    #
+    def read_author(author)
+      # The author tag has the form <author><name>...</name></author>
+      # so we have to fetch the value out of the inside of it.
+      #
+      # In REXML, sets of elements are indexed starting at 1 to match
+      # XPath. In Nokogiri they are indexed starting at 0. To work around
+      # this, we coerce it to an array, which is always indexed starting at 0.
+      #
+      return Array(author.elements)[0].text
+    end
+  end
+end

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

@@ -0,0 +1,417 @@
+#--
+# 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.
+#++
+
+##
+# Provides the +Collection+ class, which represents a collection in Splunk.
+#
+
+require_relative 'ambiguous_entity_reference'
+require_relative 'atomfeed'
+require_relative 'entity'
+require_relative 'splunk_http_error'
+require_relative 'synonyms'
+
+module Splunk
+  # Class representing a collection in Splunk.
+  #
+  # A +Collection+ is a group of items, usually of class +Entity+ or one of its
+  # subclasses, but occasionally another +Collection+. Usually you obtain a
+  # +Collection+ by calling one of the convenience methods on +Service+.
+  #
+  # A +Collection+ is enumerable, and implements many of the methods found on
+  # +Hash+, so methods like +each+, +select+, and +delete_if+ all work, as does
+  # fetching a member of the +Collection+ with [].
+  #
+  class Collection
+    include Enumerable
+    extend Synonyms
+
+    def initialize(service, resource, entity_class=Entity)
+      @service = service
+      @resource = resource
+      @entity_class = entity_class
+
+      # @infinite_count declares the value used for listing all the entities
+      # in a collection. It is usually -1, but some collections use 0.
+      @infinite_count = -1
+
+      # @always_fetch tells whether, when creating an entity in this collection,
+      # to bother trying to parse the response and always fetch the new state 
+      # after the fact. This is necessary for some collections, such as users, 
+      # which don't return the newly created object.
+      @always_fetch = false
+    end
+
+    ##
+    # The service through which this +Collection+ refers to Splunk.
+    #
+    # Returns: a +Service+.
+    #
+    attr_reader :service
+
+    ##
+    # The path after the namespace to reach this collection.
+    #
+    # For example, for apps +resource+ will be ["+apps+", "+local+"].
+    #
+    # Returns: an +Array+ of +Strings+.
+    #
+    attr_reader :resource
+
+    ##
+    # The class used to represent members of this +Collection+.
+    #
+    # By default this will be +Entity+, but many collections such as jobs
+    # will use a subclass of it (in the case of jobs, the +Job+ class), or
+    # even another collection (+ConfigurationFile+ in the case of
+    # configurations).
+    #
+    # Returns: a class.
+    #
+    attr_reader :entity_class
+
+    ##
+    # Find the first entity in the collection with the given name.
+    #
+    # Optionally, you may provide a _namespace_. If there are multiple entities
+    # visible in this collection named _name_, you _must_ provide a namespace
+    # or +assoc+ will raise an +AmbiguousEntityReference+ error.
+    #
+    # Returns: an +Array+ of [_name_, _entity_] or +nil+ if there is
+    # no matching element.
+    #
+    def assoc(name, namespace=nil)
+      entity = fetch(name, namespace)
+      if entity.nil?
+        return nil
+      else
+        return [entity.name, entity]
+      end
+    end
+
+    ##
+    # Convert an Atom entry into an entity in this collection.
+    #
+    # The Atom entry should be in the form of an entry from +AtomFeed+.
+    #
+    # Returns: An object of class @+entity_class+.
+    #
+    def atom_entry_to_entity(entry)
+      name = entry["title"]
+      namespace = Splunk::eai_acl_to_namespace(entry["content"]["eai:acl"])
+
+      @entity_class.new(service=@service,
+                        namespace=namespace,
+                        resource=@resource,
+                        name=name,
+                        state=entry)
+    end
+
+    ##
+    # Creates an item in this collection.
+    #
+    # The _name_ argument is required. All other arguments are passed as a hash,
+    # though they vary from collection to collection.
+    #
+    # Returns: the created entity.
+    #
+    # *Example:*
+    #     service = Splunk::connect(:username => 'admin', :password => 'foo')
+    #     service.users.create('jack',
+    #       :password => 'mypassword',
+    #       :realname => 'Jack_be_nimble',
+    #       :roles => ['user'])
+    #
+    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
+
+      response = @service.request(request_args)
+
+      if @always_fetch
+        fetch_args = {:method => :GET,
+                      :resource => @resource + [name]}
+        if args.has_key?(:namespace)
+          fetch_args[:namespace] = args[:namespace]
+        end
+        response = @service.request(fetch_args)
+      end
+      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
+
+    ##
+    # Deletes an item from the collection.
+    #
+    # Entities from different namespaces may have the same name, so if you are
+    # connected to Splunk using a namespace with wildcards in it, there may
+    # be multiple entities in the collection with the same name. In this case
+    # you must specify a namespace as well, or the +delete+ method will raise an
+    # AmbiguousEntityReference error.
+    #
+    # *Example:*
+    #     service = Splunk::connect(:username => 'admin', :password => 'foo')
+    #     props = service.confs['props']
+    #     props.delete('sdk-tests')
+    #
+    def delete(name, namespace=nil)
+      if namespace.nil?
+        namespace = @service.namespace
+      end
+
+      # We don't want to handle any cases about deleting ambiguously named
+      # entities.
+      if !namespace.is_exact?
+        raise StandardError.new("Must provide an exact namespace to delete an entity.")
+      end
+
+      @service.request(:method => :DELETE,
+                       :namespace => namespace,
+                       :resource => @resource + [name])
+      return self
+    end
+
+    ##
+    # Deletes all entities on this collection for which the block returns true.
+    #
+    # If block is omitted, returns an enumerator over all members of the
+    # collection.
+    #
+    def delete_if(&block)
+      # Without a block, just return an enumerator
+      return each() if !block_given?
+
+      values.each() do |entity|
+        if block.call(entity)
+          delete(entity.name, entity.namespace)
+        end
+      end
+
+    end
+
+    ##
+    # Calls block once for each item in the collection.
+    #
+    # The +each+ method takes three optional arguments as well:
+    #
+    # * +count+ sets the maximum number of entities to fetch (integer >= 0)
+    # * +offset+ sets how many items to skip before returning items in the
+    #   collection (integer >= 0)
+    # * +page_size+ sets how many items at a time should be fetched from the
+    #   server and processed before fetching another set
+    #
+    # The block is called with the entity as its argument.
+    #
+    # If the block is omitted, returns an enumerator over all members of the
+    # entity.
+    #
+    # *Example:*
+    #     service = Splunk::connect(:username => 'admin', :password => 'foo')
+    #     service.loggers.each do |key, logger|
+    #       puts logger.name + ":" + logger['level']
+    #     end
+    #
+    def each(args={})
+      enum = Enumerator.new() do |yielder|
+        count = args.fetch(:count, @infinite_count)
+        offset = args.fetch(:offset, 0)
+        page_size = args.fetch(:page_size, nil)
+
+        if !page_size.nil?
+          # Do pagination. Fetch page_size at a time
+          current_offset = offset
+          remaining_count = count
+          while remaining_count > 0
+            n_entities = 0
+            each(:offset => current_offset,
+                 :count => [remaining_count, page_size].min) do |entity|
+              n_entities += 1
+              yielder << entity
+            end
+
+            if n_entities < page_size
+              break # We've reached the end of the collection.
+            else
+              remaining_count -= n_entities
+              current_offset += n_entities
+            end
+          end
+        else
+          # Fetch the specified range in one pass.
+          response = @service.request(:resource => @resource,
+                                      :query => {"count" => count.to_s,
+                                                 "offset" => offset.to_s})
+          feed = AtomFeed.new(response.body)
+          feed.entries.each() do |entry|
+            entity = atom_entry_to_entity(entry)
+            yielder << entity
+          end
+        end
+      end
+
+      if block_given?
+        enum.each() { |e| yield e }
+      else
+        return enum
+      end
+    end
+
+    ##
+    # Identical to the +each+ method.
+    #
+    synonym "each_value", "each"
+
+    ##
+    # Identical to the +each+ method, but the block is passed the entity's name.
+    #
+    def each_key(args={}, &block)
+      each(args).map() { |e| e.name }.each(&block)
+    end
+
+    ##
+    # Identical to the +each+ method, but the block is passed both the entity's 
+    # name, and the entity.
+    #
+    def each_pair(args={}, &block)
+      each(args).map() { |e| [e.name, e] }.each(&block)
+    end
+
+    ##
+    # Returns whether there are any entities in this collection.
+    #
+    # Returns: +true+ or +false+.
+    #
+    def empty?()
+      return length() == 0
+    end
+
+    ##
+    # Fetches _name_ from this collection.
+    #
+    # If _name_ does not exist, returns +nil+. Otherwise returns the element.
+    # If, due to wildcards in your namespace, there are two entities visible
+    # in the collection with the same name, fetch will raise an
+    # AmbiguousEntityReference error. You must specify a namespace in this
+    # case to disambiguate the fetch.
+    #
+    def fetch(name, namespace=nil)
+      request_args = {:resource => @resource + [name]}
+      if !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.entries.length > 1
+        raise AmbiguousEntityReference.new("Found multiple entities with " +
+                                               "name #{name}. Please specify a disambiguating namespace.")
+      else
+        atom_entry_to_entity(feed.entries[0])
+      end
+    end
+
+    synonym "[]", "fetch"
+
+    ##
+    # Returns whether there is an entity named _name_ in this collection.
+    #
+    # Returns: a boolean.
+    # Synonyms: contains?, include?, key?, member?
+    #
+    def has_key?(name)
+      begin
+        response = @service.request(:resource => @resource + [name])
+        return true
+      rescue SplunkHTTPError => err
+        if err.code == 404
+          return false
+        else
+          raise err
+        end
+      end
+    end
+
+    synonym "contains?", "has_key?"
+    synonym "include?", "has_key?"
+    synonym "key?", "has_key?"
+    synonym "member?", "has_key?"
+
+    ##
+    # Returns an +Array+ of all entity names in the +Collection+.
+    #
+    # Returns: an +Array+ of +Strings+.
+    #
+    def keys()
+      return values().map() { |e| e.name }
+    end
+
+    ##
+    # Returns the number of entities in this collection.
+    #
+    # Returns: a nonnegative +Integer+.
+    # Synonyms: +size+.
+    #
+    def length()
+      return values().length()
+    end
+
+    synonym "size", "length"
+
+    ##
+    # Returns an +Array+ of the entities in this collection.
+    #
+    # The +values+ method takes three optional arguments:
+    #
+    # * +count+ sets the maximum number of entities to fetch (integer >= 0)
+    # * +offset+ sets how many items to skip before returning items in the
+    #   collection (integer >= 0)
+    # * +page_size+ sets how many items at a time should be fetched from the
+    #   server and processed before fetching another set
+    #
+    # Returns: an +Array+ of @entity_class.
+    # Synonyms: +list+, +to_a+.
+    #
+    def values(args={})
+      each(args).to_a()
+    end
+
+    synonym "list", "values"
+    synonym "to_a", "values"
+  end
+
+end