sis_ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 584c4065727e96b0b4c0172fe31b6ab7d8a1d39a
+  data.tar.gz: 99dd517363e6e832f3e2c910f2b7a36ecb925a9e
+SHA512:
+  metadata.gz: 001f9546fc5f481bb3b4677071f9d4dd924975810ab34ee25c83f3e749fb7ecfe367d5d74104bf04f76852fa05fb605f37c56c1e371ce9d3b7f063b623b75f91
+  data.tar.gz: 08a35bf1b678a39e0cb5b0826ee5c2c391c97fdec62df27e7c5833a61830ce3924fcb76f47228ff3757f9d0d7d1c71ab796104301e2885f6c041e4ff5d997e6f

data/.gitignore

@@ -0,0 +1,41 @@
+### Ruby template
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Created by .ignore support plugin (hsz.mobi)
+
+.idea/

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,28 @@
+This software is licensed under the BSD 3-Clause license.
+
+Copyright (c) 2016, Verisign, Inc. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,188 @@
+# sis_ruby
+
+A Ruby client to talk to a SIS server (https://github.com/sis-cmdb/sis-api).
+
+Currently only the v1.1 API is supported.
+
+Initial commit represents work by Neel Goyal, formerly at Verisign,
+and Keith Bennett, currently at Verisign (http://www.verisign.com/).
+
+
+## Usage
+
+Example code:
+
+```
+require 'sis_ruby'
+
+# Create a client
+client = SisRuby::Client.new(sis_server_url)
+
+# Get the host information endpoint
+hosts = client.entities('host')
+
+# Use all possible Params options to list records of a given entity:
+params = SisRuby::Params.new.sort('hostname').offset(9000).limit(2).fields('hostname', 'environment') 
+records = hosts.list(params)
+
+# Get record counts:
+puts "Total host count is #{hosts.count}"
+puts "Total qa host count is  #{hosts.count('environment' => 'qa')}"
+
+# Get up to 10 hooks
+hook_list = client.hooks.list(SisRuby::Params.new.limit(10))
+
+# Get 1 schema
+schema_list = client.schemas.list(SisRuby::Params.new.limit(1)).first
+
+# Hiera Entry Creation
+hiera_entry = client.hiera.create({ 'name' => 'entry', 'hieradata' => { 'key1' => 'value1' }});
+
+# Entity Deletion: Delete the entity of type 'entity_name' with id 'foo':
+was_deleted = client.entities('entity_name').delete('foo');
+```
+
+## Client Initialization
+
+The client constructor takes the following parameters:
+ 
+* (required) a URL indicating the base URL of the SIS endpoints
+* (optional) a hash containing neither, one, or both of:
+  * **:auth_token** - an authorization token field to be sent in the `x-auth-token` header
+  * **:api_version** - a version string to use in the request URL's instead of the default API version
+
+```
+client = SisRuby::Client.new(sis_server_url)
+client = SisRuby::Client.new(sis_server_url, auth_token: auth_token)
+```
+
+## Client Authentication
+
+The client may also acquire and use a temporary token to use against the SIS endpoint 
+via the `authenticate` method.  Below are examples:
+
+```
+# This method will raise an SisRuby::Client::AuthenticationError if authentication fails.
+token = client.authenticate(userid, password)
+
+# You can also combine the client creation and authentication into a single expression
+# since the authenticate method returns the client:
+client = SisRuby::Client.new(sis_server_url).authenticate(userid, password)
+```
+
+Although `authenticate` returns the token, there is no need to save it;
+it is stored in the client instance for subsequent requests.
+
+## Entity, Hook, Schema, and Hiera Methods
+
+The object returned by `client.hooks`, `client.schemas`, `client.hiera`, and 
+`client.entities(entity_name)` all interact with the appropriate endpoints
+and expose the following interface:
+
+
+### list(query)
+
+This maps to a GET `/` request against the appropriate endpoint for the default or specified API version.
+
+List parameters can be specified in the form of any object responding to
+`to_hash` and returning a hash (including, of course, a `Hash`).
+
+Values in the hash can contain:
+
+* **sort** - field name(s) on which to sort the records, precede fieldname with `-` for descending
+* **limit** - limit the result set size to the specified number of records
+* **fields** - only return the fields passed to this method; however:
+  * currently there is a bug that results in array type fields being returned even if they
+are not included in the field list
+  * the _id field will always be returned even if it is not specified
+* **offset** - the offset into the sorted results at which to start adding records to the result set
+(Note: offset is not reliable unless a sort order is specified; there is no default sort order
+and the random order may change from call to call.
+
+For your convenience, a `Params` class has been provided with chainable methods (see code example).
+
+Also, there is a `count` method that will return the total record count. If passed a filter, it will
+return the count of records that meet the filter criteria.
+
+An array of hashes is returned on success.  For your convenience, there is also a
+`list_as_openstructs` method that returns each record as an `OpenStruct` instance for easier access.
+OpenStruct instances allow you to call methods whose names correspond to the original hash's keys,
+e.g. `host.site` instead of `host['site']`.
+This approach is not recommended for large numbers of records, as it requires more memory and processing.
+
+
+### get(id)
+
+This maps to a GET `/id` request against the approprivate endpoint for the default or specified API version.
+
+* id : a string representing the ID of the object to receive.  For schemas, hooks, and hiera, this is the `name`.  
+For entities, it is the `_id`.
+
+A single hash representing the object is returned on success.
+
+
+### create(obj)
+
+This maps to a POST `/` request against the appropriate endpoint for the default or specified API version.
+
+* obj : a valid Hash conforming to the endpoint specification
+
+The created object as a hash is returned on success.
+
+
+### update(obj)
+
+This maps to a PUT '/' request against the appropriate endpoint for the default or specified API version.
+
+* obj : a valid hash conforming to the endpoint specification.  Typically retrieved from `list` or `get`.
+
+The updated hash representing the object is returned on success.
+
+
+### delete(obj)
+
+This maps to a DELETE '/id' request against the appropriate endpoint for the default or specified API version.
+
+* obj : either a string id or an object retrieved from `list` or `get`
+
+The boolean `true` is returned on success.
+
+
+## Error handling
+
+An instance of `SisRuby::Client` will raise an exception if an HTTP request returns a status code above and including 400.
+
+
+## Running the Tests
+
+Test code is divided into different top-level directories:
+
+### `spec`
+ 
+These are tests not requiring a SIS server.
+
+### `spec_reading`
+ 
+These are tests requiring a SIS server containing a 'host' entity populated with records
+
+### `spec_writing`
+ 
+These are tests requiring a SIS server that can be used for writing; for these
+you'll probably want to set up a local server.  Instructions for this are at 
+https://github.com/sis-cmdb/sis-api#building-and-testing.
+
+If the tests should ever fail and the data base is not correctly restored to
+its original empty state, you can delete the Mongo data 
+by running the Mongo shell ('mongo') and issuing the following commands:
+
+```
+use test
+db.dropDatabase();
+```
+
+To verify the user id and password, you can issue the following command, replacing 'test' and
+'abc123' with the real user id and password:
+
+```
+curl -D- -u test:abc123 -X POST -H "Content-Type: application/json" http://localhost:3000/api/v1.1/users/auth_token
+```

data/RELEASE_NOTES.md

@@ -0,0 +1,3 @@
+## v1.0.0
+
+Code base copied from @ngoyal's original version internal to Verisign, with extensive modifications.

data/Rakefile

@@ -0,0 +1,35 @@
+# From https://github.com/goncalossilva/gem_template
+begin
+  require "bundler"
+  Bundler.setup
+rescue LoadError
+  $stderr.puts "You need to have Bundler installed to be able build this gem."
+end
+
+gemspec = eval(File.read('sis_ruby.gemspec'))
+
+desc "Validate the gemspec"
+task :gemspec do
+  gemspec.validate
+end
+
+desc "Build gem locally"
+task :build => :gemspec do
+  system "gem build #{gemspec.name}.gemspec"
+  FileUtils.mkdir_p "pkg"
+  FileUtils.mv "#{gemspec.name}-#{gemspec.version}.gem", "pkg"
+end
+
+desc "Install gem locally"
+task :install => :build do
+  system "gem install pkg/#{gemspec.name}-#{gemspec.version}.gem"
+end
+
+desc "Clean automatically generated files"
+task :clean do
+  FileUtils.rm_rf "pkg"
+end
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')

data/lib/sis_ruby/client.rb

@@ -0,0 +1,85 @@
+require_relative 'common'
+require 'sis_ruby/endpoint'
+require 'typhoeus'
+
+module SisRuby
+
+class Client
+
+  attr_reader :api_version, :auth_token, :base_url, :entity_endpoints, :hiera, :hooks, :hosts, :schemas
+
+  DEFAULT_API_VERSION = '1.1'
+
+  # @param url the base URL of the service (excluding ''/api/v...'')
+  # @param options (can include :version, :auth_token)
+  def initialize(url, options = {})
+    @base_url = url
+    @api_version = options[:api_version] || DEFAULT_API_VERSION
+    @auth_token = options[:auth_token]
+
+    @entity_endpoints = {}
+    @hooks   = create_endpoint('hooks',   'name')
+    @schemas = create_endpoint('schemas', 'name')
+    @hiera   = create_endpoint('hiera',   'name')
+  end
+
+
+  def create_endpoint(endpoint_suffix, id_fieldname = :default)
+    Endpoint.new(self, endpoint_suffix, id_fieldname)
+  end
+
+
+  def entities(name, id_fieldname = DEFAULT_ID_FIELDNAME)
+    @entity_endpoints[name] ||= create_endpoint("entities/#{name}", id_fieldname)
+  end
+
+
+  def tokens(username)
+    create_endpoint("users/#{username}/tokens", 'name')
+  end
+
+
+  # Returns the schema for the specified collection_name, or nil if it's not found.
+  def schema_for(collection_name)
+    params = Params.new.limit(1).filter('name' => collection_name)
+    schemas.list(params).first
+  end
+
+
+  # Authenticates the username and password. Get the token by calling client.auth_token.
+  # @return self for chaining this method after the constructor
+  def authenticate(username, password)
+    dest = "#{base_url}/api/v#{api_version}/users/auth_token"
+    options = {
+        userpwd: username + ':' + password,
+        headers: { 'Accept' => 'application/json', 'Content-Type' => 'application/json' }
+    }
+    response = Typhoeus.post(dest, options)
+    unless response.options[:response_code] == 201
+      raise AuthenticationError.new(response)
+    end
+
+    @auth_token = JSON.parse(response.response_body)['name']
+    self
+  end
+
+
+  def to_s
+    self.class.name + ": base_url = #{@base_url}"
+  end
+
+
+
+  class AuthenticationError < Exception
+
+    def initialize(response)
+      @response = response
+    end
+
+    def to_s
+      @response.options[:response_headers].split("\r\n").first
+    end
+  end
+
+end
+end

data/lib/sis_ruby/common.rb

@@ -0,0 +1,5 @@
+module SisRuby
+
+  DEFAULT_ID_FIELDNAME = '_id'
+
+end

data/lib/sis_ruby/endpoint.rb

@@ -0,0 +1,108 @@
+require 'typhoeus'
+require 'json'
+
+require_relative 'client'
+require_relative 'common'
+require_relative 'get_helper'
+require_relative 'result_enumerable'
+require_relative 'exceptions/missing_id_error'
+
+module SisRuby
+
+class Endpoint
+
+  include GetHelper
+
+  attr_reader :client, :id_field, :url
+
+
+  def initialize(client, endpoint_name, id_field = DEFAULT_ID_FIELDNAME)
+    @client = client
+    @url = "#{client.base_url}/api/v#{client.api_version}/#{endpoint_name}"
+    @id_field = id_field
+  end
+
+
+  # This method is used to allow callers to pass either the id itself,
+  # or the record including an id key/value pair.
+  def id_from_param(object)
+    id = object.is_a?(Hash) ? object[@id_field] : object
+    id ? id : raise(MissingIdError.new("Missing required id field #{@id_field}}"))
+  end
+
+
+  def create_enumerable(params = {}, chunk_size = ResultEnumerable::DEFAULT_CHUNK_RECORD_COUNT)
+    ResultEnumerable.new(self, params, chunk_size)
+  end
+
+
+  # Gets the total count of records, with optional filter
+  def count(filter = {})
+    params = Params.new.filter(filter).limit(1).to_hash
+    response = Typhoeus::Request.new(@url, params: params, headers: create_headers(true)).run
+    response.headers['x-total-count'].to_i
+  end
+
+
+  # Anything implementing a to_hash method can be passed as the query.
+  # This enables the passing in of SisParams objects.
+  def list(params = {})
+    create_enumerable(params).each.to_a
+  end
+
+
+  # Anything implementing a to_hash method can be passed as the query.
+  # This enables the passing in of SisParams objects.
+  def list_as_openstructs(query = {})
+    list(query).map { |h| OpenStruct.new(h) }
+  end
+
+
+  def get(id)
+    request = Typhoeus::Request.new("#{url}/#{id}", headers: create_headers(true))
+    response = request.run
+    validate_response_success(response)
+    JSON.parse(response.body)
+  end
+
+
+  def create(obj)
+    http_response = Typhoeus.post(@url, { body: obj.to_json, headers: get_headers(true) } )
+    validate_response_success(http_response)
+    JSON.parse(http_response.body)
+  end
+
+
+  def delete(id)
+    id = id_from_param(id)
+    http_response = Typhoeus.delete("#{@url}/#{id}", headers: get_headers(false))
+    validate_response_success(http_response)
+    JSON.parse(http_response.body)
+  end
+
+
+  def update(obj)
+    id = id_from_param(obj)
+    http_response = self.class.put("#{@url}/#{id}", {body: obj.to_json, headers: get_headers(true) })
+    validate_response_success(http_response)
+    JSON.parse(http_response.body)
+  end
+
+
+  def to_s
+    self.class.name + ": endpoint = #{@url}, client = #{@client}"
+  end
+
+
+  def ==(other)
+    client.equal?(other.client) && url == other.url && id_field == other.id_field
+  end
+
+  private
+
+  def get_headers(specify_content_type)
+    create_headers(specify_content_type, @client.auth_token)
+  end
+end
+
+end

data/lib/sis_ruby/exceptions/bad_response_error.rb

@@ -0,0 +1,35 @@
+module SisRuby
+
+class BadResponseError < RuntimeError
+
+  attr_reader :response
+
+  def initialize(response)
+    @response = response
+  end
+
+
+  def to_s
+
+    first_header_line = if response && response.options[:response_headers]
+      header_lines = response.options[:response_headers].split("\r\n")
+      header_lines.any? ? header_lines.first : nil
+    else
+      nil
+    end
+
+    body = if response && response.options[:response_body]
+     response.options[:response_body].rstrip
+    else
+      nil
+    end
+
+    code = response.code
+
+    string = "#{self.class.name}: #{code}"
+    string << ": #{body}" if body
+    string << (first_header_line ? " (#{first_header_line})" : '')
+    string
+  end
+end
+end

data/lib/sis_ruby/exceptions/missing_id_error.rb

@@ -0,0 +1,12 @@
+module SisRuby
+class MissingIdError < RuntimeError
+
+  def initialize(id_field_name)
+    @id_field_name = id_field_name
+  end
+
+  def to_s
+    "Missing required id field #{@id_field_name}}"
+  end
+end
+end

data/lib/sis_ruby/get_helper.rb

@@ -0,0 +1,41 @@
+require_relative 'exceptions/bad_response_error'
+
+
+# Methods for helping get data from SIS.
+module SisRuby
+  module GetHelper
+
+    # Creates the header for a request.
+    def create_headers(specify_content_type, auth_token = nil)
+      headers = {
+          'Accept' => 'application/json'
+      }
+
+      if auth_token
+        headers['x-auth-token'] = auth_token
+      end
+
+      if specify_content_type
+        headers['Content-Type'] = 'application/json'
+      end
+
+      headers
+    end
+
+
+    # Raises an error on response failure.
+    def validate_response_success(response)
+      unless response.code.between?(200, 299)
+        raise BadResponseError.new(response)
+      end
+    end
+
+
+    # Returns a Typhoeus response.
+    def typhoeus_get(query)
+      # TODO: Simplify w/Typhoeus.get ?
+      Typhoeus::Request.new(url,  params: query, headers: get_headers(true) ).run
+    end
+
+  end
+end

data/lib/sis_ruby/hash_builder.rb

@@ -0,0 +1,31 @@
+
+# Takes methods and builds an internal hash where the method calls
+# are keys, and their parameter is the value.
+class HashBuilder
+
+  attr_reader :key_type
+
+  def initialize(key_type = String)
+    raise ArgumentError.new("Invalid key type '#{key_type}'") unless [String, Symbol].include?(key_type)
+    @key_type = key_type
+    @data = {}
+  end
+
+
+  def method_missing(method_name, *args)
+    value = args.first
+    key = (@key_type == String) ? method_name.to_s : method_name.to_sym
+    @data[key] = value
+    self
+  end
+
+
+  def respond_to_missing?(method_name, include_private)
+    true  # TODO: exclude ancestor methods?
+  end
+
+
+  def to_h
+    @data
+  end
+end