delphix 0.1.0

data/lib/delphix/utils.rb

@@ -0,0 +1,68 @@
+# encoding: UTF-8
+#
+# Author:    Stefano Harding <riddopic@gmail.com>
+# License:   Apache License, Version 2.0
+# Copyright: (C) 2014-2015 Stefano Harding
+#
+# 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 'securerandom'
+
+module Delphix
+  module Utils
+    # Return the date and time in "HTTP-date" format as defined by RFC 7231.
+    #
+    # @return [Date,Time] in "HTTP-date" format
+    def utc_httpdate
+      Time.now.utc.httpdate
+    end
+
+    # Generates a uniq UUID, this is then used to identify this session.
+    #
+    # @return [String]
+    #   Memoize a uniq UUID used to identify this session.
+    #
+    def request_id
+      @uuid ||= SecureRandom.uuid
+    end
+  end
+end
+
+class Hash
+  # Returns a new Hash, recursively downcasing and converting all
+  # keys to symbols.
+  #
+  # @return [Hash]
+  #
+  def recursively_normalize_keys
+    recursively_transform_keys { |key| key.downcase.to_sym rescue key }
+  end
+
+  private #   P R O P R I E T À   P R I V A T A   divieto di accesso
+
+  # support methods for recursively transforming nested hashes and arrays
+  #
+  def _recursively_transform_keys_in_object(object, &block)
+    case object
+    when Hash
+      object.each_with_object({}) do |(key, val), result|
+        result[yield(key)] = _recursively_transform_keys_in_object(val, &block)
+      end
+    when Array
+      object.map { |e| _recursively_transform_keys_in_object(e, &block) }
+    else
+      object
+    end
+  end
+end

data/lib/delphix/version.rb

@@ -0,0 +1,43 @@
+# encoding: UTF-8
+#
+# Author:    Stefano Harding <riddopic@gmail.com>
+# License:   Apache License, Version 2.0
+# Copyright: (C) 2014-2015 Stefano Harding
+#
+# 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.
+#
+
+# The version number of the Delphix Gem
+#
+# @return [String]
+#
+# @api public
+module Delphix
+  # Contains information about this gem's version
+  module Version
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+
+    # Returns a version string by joining MAJOR, MINOR, and PATCH with '.'
+    #
+    # @example
+    #   Version.string # => '1.0.1'
+    #
+    def self.string
+      [MAJOR, MINOR, PATCH].join('.')
+    end
+  end
+
+  VERSION = Delphix::Version.string
+end

data/lib/delphix/web_client.rb

@@ -0,0 +1,164 @@
+# encoding: UTF-8
+#
+# Author:    Stefano Harding <riddopic@gmail.com>
+# License:   Apache License, Version 2.0
+# Copyright: (C) 2014-2015 Stefano Harding
+#
+# 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 Delphix
+  class WebClient
+    def self.request(method, url, headers, body, timeout, &callback)
+      request = Delphix::WebRequest.new(method, url, headers, body)
+
+      if callback
+        Thread.new do
+          callback.call(internal_request(request, timeout))
+        end
+      else
+        internal_request(request, timeout)
+      end
+    end
+
+    def self.internal_request(request, timeout)
+      HTTP_HEADERS.each { |key, value| request.add_header(key, value) }
+      response = nil
+
+      begin
+        case request.method
+        when :get
+          response = RestClient::Request.execute(
+            method: :get,
+            url:     request.url,
+            headers: request.headers,
+            timeout: timeout
+          )
+        when :post
+          response = RestClient::Request.execute(
+            method: :post,
+            url:     request.url,
+            payload: request.body,
+            headers: request.headers,
+            timeout: timeout
+          )
+        when :delete
+          response = RestClient::Request.execute(
+            method: :delete,
+            url:     request.url,
+            payload: request.body,
+            headers: request.headers,
+            timeout: timeout
+          )
+        end
+      rescue RestClient::RequestTimeout
+        raise 'Request Timeout'
+      rescue RestClient::Exception => e
+        response = e.response
+      end
+
+      Delphix::WebResponse.new(response)
+    end
+  end
+
+  # @param [String, Symbol] name
+  #   A string or symbol used to identify the key portion of the HTTP headers.
+  # @param [String, Symbol, Array] value
+  #   A string, symbol or array containing the values of the HTTP header.
+  #
+  # @return [Hash]
+  #   The result of the key/value pair.
+  #
+  def self.default_header(name, value)
+    @@default_headers[name] = value
+  end
+
+  # @return [Hash]
+  #   The HTTP headers sent with a POST/GET/DELETE.
+  #
+  def self.clear_default_headers
+    @@default_headers = {}
+  end
+
+  # @param [Integer] seconds
+  #   Set the number of seconds to wait for an HTTP timeout.
+  #
+  # @return [undefined]
+  #
+  def self.timeout(seconds)
+    @@timeout = seconds
+  end
+
+  # Define the #get, #post, and #delete helper methods for sending HTTP
+  # requests to the Delphix engine. You shouldn't need to use these methods
+  # directly, but they can be useful for debugging.
+  #
+  # The following HTTP methods are supported by the Delphix Appliance:
+  #
+  #    GET - Retrieve data from the server where complex input is not needed.
+  #          All GET requests are guaranteed to be read-only, but not all
+  #          read-only requests are required to use GET. Simple input
+  #          (strings, number, boolean values) can be passed as query
+  #          parameters.
+  #   POST - Issue a read/write operation, or make a read-only call that
+  #          requires complex input. The optional body of the call is
+  #          expressed as JSON.
+  #   DELETE - Delete an object on the system. For languages that don't provide
+  #          a native wrapper for DELETE, or for delete operations with
+  #          optional input, all delete operations can also be invoked as POST
+  #          to the same URL with /delete appended to it.
+  #
+  # Each method returns a hash that responds to #code, #headers, #body and
+  # #raw_body obtained from parsing the JSON object in the response body.
+  #
+  # @param url [String<URL>] url the url of where to send the request
+  # @param [Hash{Symbol => String}] parameters key-value data of the HTTP
+  # API request
+  # @param [Block] block block to execute when the request returns
+  # @return [Fixnum, #code] the response code from Delphix engine
+  # @return [Hash, #headers] headers, beautified with symbols and underscores
+  # @return [Hash, #body] body parsed response body where applicable (JSON
+  # responses are parsed to Objects/Associative Arrays)
+  # @return [Hash, #raw_body] raw_body un-parsed response body
+  #
+  # @api semipublic
+  [:get, :post, :delete].each do |method|
+    define_singleton_method(method) do |url, parameters = {}, &callback|
+      WebClient.request(method.to_sym, url, @@default_headers,
+        parameters.to_json, @@timeout, &callback)
+    end
+  end
+
+  module InstanceMethods
+    private
+
+    # Returns the current api endpoint, if present.
+    #
+    # @return [nil, String] the current endpoint
+    def endpoint
+      nil
+    end
+  end
+
+  # @!classmethods
+  module ClassMethods
+    # When present, lets you specify the api for the given client.
+    #
+    # @param [String, nil] value the endpoint to use.
+    # @example Setting a string endpoint endpoint '/resources/json/delphix'
+    # @example Unsetting the string endpoint endpoint nil
+    def endpoint(value = nil)
+      define_method(:endpoint) { value }
+    end
+  end
+end

data/lib/delphix/web_request.rb

@@ -0,0 +1,96 @@
+# encoding: UTF-8
+#
+# Author:    Stefano Harding <riddopic@gmail.com>
+# License:   Apache License, Version 2.0
+# Copyright: (C) 2014-2015 Stefano Harding
+#
+# 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 'base64'
+require 'addressable/uri'
+
+module Delphix
+  class WebRequest
+    include Delphix::Utils
+
+    # @!attribute [r] method
+    #   The HTTP method used, 'GET', 'POST', or 'DELETE'.
+    #   @return [String]
+    attr_reader :method
+    # @!attribute [r] url
+    #   The API path/URL to POST, GET, DELETE from/to.
+    #   @return [String]
+    attr_reader :url
+    # @!attribute [r] headers
+    #   The HTTP headers, symbolized and underscored.
+    #   @return [Hash]
+    attr_reader :headers
+    # @!attribute [r] body
+    #   The parsed response body where applicable (JSON responses are parsed
+    #   to Objects/Associative Arrays).
+    #   @return [Hash]
+    attr_reader :body
+    # @!attribute [r] all
+    #   The raw_body un-parsed response body.
+    #   @return [JSON]
+    attr_reader :all
+
+    def add_header(name, value)
+      @headers[name] = value
+    end
+
+    def initialize(method, url, headers = {}, body = nil)
+      @method = method
+
+      if (method == :get)
+        if body.is_a?(Hash) && body.length > 0
+          if url.include? '?'
+            url += '&'
+          else
+            url += '?'
+          end
+
+          uri = Addressable::URI.new
+          uri.query_values = body
+          url += uri.query
+        end
+      else
+        @body = body
+      end
+
+      unless url =~ URI.regexp
+        raise 'Invalid URL: ' + url
+      end
+
+      @url = url.gsub(/\s+/, '%20')
+
+      @headers = {
+        'Date'       => utc_httpdate,
+        'Request-ID' => request_id
+      }
+
+      headers.each_pair { |key, value| @headers[key.downcase] = value }
+
+      Delphix.last_request = {
+        headers: @headers,
+        method: @method,
+        url: @url
+      }
+      begin
+        Delphix.last_request[:body] = JSON.parse(@body) if body.length > 2
+      rescue Exception
+      end
+    end
+  end
+end

data/lib/delphix/web_response.rb

@@ -0,0 +1,89 @@
+# encoding: UTF-8
+#
+# Author:    Stefano Harding <riddopic@gmail.com>
+# License:   Apache License, Version 2.0
+# Copyright: (C) 2014-2015 Stefano Harding
+#
+# 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 'json'
+
+module Delphix
+  class WebResponse
+    include Net::HTTPHeader
+
+    # @!attribute [r] code
+    #   The HTTP response code from Delphix engine.
+    #   @return [#code]
+    attr_reader :code
+    # @!attribute [r] method
+    #   The raw_body un-parsed response body from the Delphix engine.
+    #   @return [#raw_body]
+    attr_reader :raw_body
+    # @!attribute [r] method
+    #   The parsed response body where applicable (JSON responses are parsed
+    #   to Objects/Associative Arrays).
+    #   @return [#body]
+    attr_reader :body
+    # @!attribute [r] method
+    #   The HTTP headers, symbolized and underscored.
+    #   @return [#headers]
+    attr_reader :headers
+    # @!attribute [r] method
+    #   The current session cookies.
+    #   @return [#raw_body]
+    attr_reader :cookies
+
+    def initialize(response)
+      @code = response.code
+      @headers = response.headers
+      @raw_body = response
+      @body = @raw_body
+      @cookies = response.cookies
+
+      Delphix.last_response = {
+        code: response.code,
+        headers: response.headers,
+        body: JSON.parse(response.body),
+        cookies: response.cookies,
+        description: response.description
+      }.recursively_normalize_keys
+
+      begin
+        @body = JSON.parse(@raw_body)
+      rescue Exception
+      end
+    end
+
+    def ==(other)
+      @headers == other
+    end
+
+    def inspect
+      @headers.inspect
+    end
+
+    def method_missing(name, *args, &block)
+      if @headers.respond_to?(name)
+        @headers.send(name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to?(method)
+      super || @headers.respond_to?(method)
+    end
+  end
+end

data/lib/delphix.rb

@@ -0,0 +1,205 @@
+# encoding: UTF-8
+#
+# Author:    Stefano Harding <riddopic@gmail.com>
+# License:   Apache License, Version 2.0
+# Copyright: (C) 2014-2015 Stefano Harding
+#
+# 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 'rest-client'
+require_relative 'delphix/utils'
+require_relative 'delphix/web_client'
+require_relative 'delphix/web_request'
+require_relative 'delphix/web_response'
+require_relative 'delphix/version'
+
+# A library for supporting connections to the Delphix API. The module Delphix
+# is based on the singleton pattern, which restricts instantiation of a class
+# to only one instance that is globally available.
+#
+# @example
+#   To establish a session with the Delphix appliance and get a cookie for
+#   your effort you issue the following sequence:
+#
+#   * Configure the Delphix client to use the specified version of the API, in
+#     hash format as `{ major: 1, micro: 0, minor: 0 }`, for example:
+#       Delphix.api_version = {
+#         type: 'APIVersion',
+#         major: { major: 1, micro: 0, minor: 0 }
+#       }
+#   * Specify the Delphix server to connect to.
+#       Delphix.server = 'delphix.example.com'
+#   * Specify the Delphix username to connect with.
+#       Delphix.api_user = 'delphix'
+#   * Specify the Delphix password to use.
+#       Delphix.api_passwd = 'delphix'
+#   * Now you have an established session, go crazy.
+#
+module Delphix
+  include Utils
+
+  API_ENDPOINT = '/resources/json/delphix'
+  HTTP_HEADERS = {
+    'Accept'       =>  'application/json; charset=UTF-8',
+    'Content-Type' =>  'application/json; charset=UTF-8',
+    'User-Agent'   =>  'Delphix-Ruby-Client/1.0.0'
+  }
+
+  # Default timeout value in seconds.
+  @@timeout = 10
+
+  # Default headers
+  @@default_headers = {}
+
+  class << self
+    # @!attribute [rw] last_request
+    #   @return [Hash] retruns the last request
+    attr_accessor :last_request
+    # @!attribute [rw] last_response
+    #   @return [Hash] retruns the last response
+    attr_accessor :last_response
+    # @!attribute [rw] session
+    #   @return [Hash] retruns current session state
+    #   @return [#code] the response code from Delphix engine
+    #   @return [#headers] beautified with symbols and underscores
+    #   @return [#body] parsed response body
+    #   @return [#raw_body] un-parsed response body
+    attr_accessor :session
+    # @!attribute [rw] api_version
+    #   @return [Hash] containing the major, minor and micro version numbers.
+    attr_accessor :api_version
+    # @!attribute [rw] server
+    #   @return [String] Delphix server address
+    attr_accessor :server
+    # @!attribute [rw] api_user
+    #   @return [String] username to authenticate with
+    attr_accessor :api_user
+    # @!attribute [rw] api_passwd
+    #   @return [String] password for authentication
+    attr_accessor :api_passwd
+    # @!attribute [rw] verbose
+    #   @return [Nothing] enables verbosity
+    attr_accessor :verbose
+  end
+
+  # Returns the API endpoint for a given resource namespace by combining the
+  # server address with the appropriate HTTP headers.
+  #
+  # @param resource [Resource] namespace
+  #
+  # @return [URL] return the URL for the API endpoint
+  #
+  # @api public
+  def self.api_url(resource = nil)
+    'http://' + @server + resource
+  end
+
+  def self.session
+    Delphix.default_header(:cookies, cookies)
+    @session ||= login(@api_user, @api_passwd)
+  end
+
+  # Establish a session with the Delphix engine and return an identifier
+  # through browser cookies. This session will be reused in subsequent calls,
+  # the same session credentials and state are preserved without requiring a
+  # re-authentication call. Sessions do not persisit between incovations.
+  #
+  # @return [Hash] cookies
+  #   containing the new session cookies
+  #
+  # @api public
+  def self.cookies
+    @resp ||= Delphix.post session_url,
+      type: 'APISession', version: @api_version
+    @resp.cookies
+  end
+
+  # Authenticates the session so that API calls can be made. Only supports basic
+  # password authentication.
+  #
+  # @param [String] user
+  #   user name to authenticate with
+  # @param [String] passwd
+  #   password to authenticate with
+  #
+  # @return [Fixnum, #code]
+  #   the response code from Delphix engine
+  # @return [Hash, #headers]
+  #   headers, beautified with symbols and underscores
+  # @return [Hash, #body] body
+  #   parsed response body where applicable (JSON responses are parsed to
+  #   Objects/Associative Arrays)
+  # @return [Hash, #raw_body] raw_body
+  #   un-parsed response body
+  #
+  # @api public
+  def self.login(user = @api_user, passwd = @api_passwd)
+    Delphix.post login_url,
+      type: 'LoginRequest', username: user, password: passwd
+  end
+
+  # @!method session
+  #   A helper method to return the URL for the resource by using the
+  #   resource_url shorthand.
+  #   @return [String] The API path to session.
+  #
+  # @!method login
+  #   A helper method to return the URL for the resource by using the
+  #   resource_url shorthand.
+  #   @return [String] The API path to login.
+  #
+  # @!method environment
+  #   A helper method to return the URL for the resource by using the
+  #   resource_url shorthand.
+  #   @return [String] The API path to environment.
+  #
+  # @!method alert
+  #   A helper method to return the URL for the resource by using the
+  #   resource_url shorthand.
+  #   @return [String] The API path to alert.
+  #
+  # @!method database
+  #   A helper method to return the URL for the resource by using the
+  #   resource_url shorthand.
+  #   @return [String] The API path to database.
+  #
+  # @!method source
+  #   A helper method to return the URL for the resource by using the
+  #   resource_url shorthand.
+  #   @return [String] The API path to source.
+  #
+  [:session, :login, :environment, :alert, :database, :source].each do |name|
+    define_singleton_method(name.to_s + '_url') do
+      api_url('/resources/json/delphix/' + name.to_s)
+    end
+  end
+
+  # @return [String] object inspection
+  # @!visibility private
+  def inspect
+    instance_variables.inject([
+      "\n#<#{self.class}:0x#{object_id.to_s(16)}>",
+      "\tInstance variables:"
+    ]) do |result, item|
+      result << "\t\t#{item} = #{instance_variable_get(item)}"
+      result
+    end.join("\n")
+  end
+
+  # @return [String] string of instance
+  # @!visibility private
+  def to_s
+    "<#{self.class}:0x#{object_id.to_s(16)} session=#{@session}>"
+  end
+end