xn.rb 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ea2329de7679cd2d4e1d11d8e744d27b874421e1
+  data.tar.gz: 23b61587ef31d5aca7da249871c88e314ff802da
+SHA512:
+  metadata.gz: 28d2d444b53fdd371e7b169af8ab6d64dcd703a31cfc5c8b985da9950950c6694f564a4537fccff9939e6f5e843cdb559a5b775c5f92602addcc76a7a3fd9eb2
+  data.tar.gz: aff9f1d1aa456a3b296ed378252d3a91157c9fbc25b349f9099e55e8c078ca3c1fc80db5fe04ecd777476f6fd62347e2e3bd18bfb2970b27e51a780c7622ae77

data/.gitignore

@@ -0,0 +1,3 @@
+.bundle
+bin
+pkg

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+gemspec
+

data/Gemfile.lock

@@ -0,0 +1,17 @@
+PATH
+  remote: .
+  specs:
+    xn.rb (0.0.2)
+      highline
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    highline (1.6.15)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  xn.rb!

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 XN LOGIC CORPORATION
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,62 @@
+xn.rb
+=====
+
+Ruby API client for XN Logic based applications.
+
+Source code available at https://github.com/xnlogic/xn.rb and Pull Requests are welcome!
+
+Synopsis
+--------
+
+Set up and authentication:
+```
+require 'rubygems'
+require 'xn.rb'
+api_session = Xn::XnApiSession.new 'https://app.lightmesh.com', 'my@email.com'
+```
+This will prompt the terminal for your password.  If you are not writing an interactive script, set the LMTOKEN environment variable first and the XnApiSession constructor will use that.
+e.g.
+
+```
+~/my_project $ LMTOKEN='client_name XYZ1234' irb
+2.1.0p0 :001 > require 'rubygems'
+2.1.0p0 :002 > require 'xn.rb'
+2.1.0p0 :003 > api_session = Xn::XnApiSession.new 'https://app.lightmesh.com', 'my@email.com'
+2.1.0p0 :004 > Using token from env LMTOKEN
+ => #<Xn::XnApiSession:0x007feef5c65070.....>
+2.1.0p0 :005 > 
+```
+
+To query the API, there are a few helpers:
+```
+# NB: These two queries return subtly different results.  The first returns a Model record, with all Parts your user
+# has access to, whereas the second returns just the Part data. For more on the difference between Models and Parts see:
+# https://lightmesh.zendesk.com/entries/41374508-Concepts-Types-or-parts-and-Models for
+
+response_hash = api_session.find_vertex_by_model 'ip', '/filter/name?name=10.0.0.2'
+response_hash = api_session.find_vertex_by_part 'ip', '/filter/name?name=10.0.0.2'
+
+# Create, Update, Find-or-Create:
+new_ip_r_hash = api_session.create_vertex 'ip', name: '10.0.0.3', description: 'New reserved IP for projekt XYZ'
+response_hash = api_session.update_vertex new_ip_r_hash,          description: 'New reserved IP for project XYZ'
+response_hash = api_session.find_or_create_by_model_and_name('ip', '10.0.0.3', nil, description: 'New reserved IP for project XYZ')
+
+# Get all related vertices:
+api_session.related_vertices(new_ip_r_hash)
+
+# Execute an action:
+api_session.exec_action( new_ip_r_hash, 'set_subnet_from_ip', {} )  # Some actions take paramters in the form of a hash
+
+```
+We are always interested in hearing suggestions for more helpers (open an issue at https://github.com/xnlogic/xn.rb)
+
+but you can also use the API http wrapper directly for more advanced use-cases:
+```
+api_session.api.get "/v1/is/ip/filters/name/properties/name/?name[regex]=^(?!10)" do |response|
+  response.each do |id, ip|
+    puts "IP: #{ip}, xnid: /model/ip/#{id}"
+  end
+end
+```
+
+

data/Rakefile

@@ -0,0 +1,3 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+

data/lib/xn.rb

@@ -0,0 +1,206 @@
+if RUBY_VERSION == '1.8.7'
+  STDERR.puts <<WARNING
+WARNING: XnApiSession is developed using Ruby in 1.9.3 mode.
+We recommend you use ruby-1.9.3 or if using JRuby, start ruby in 1.9 mode,
+  either with the --1.9 flag, or by setting the environment variable
+  JRUBY_OPTS=--1.9
+WARNING
+end
+require 'rubygems'
+require 'bundler'
+require 'bundler/setup'
+
+require 'json'
+require 'net/http'
+raise "Missing Net::HTTP::Patch in #{RUBY_VERSION}" unless defined? Net::HTTP::Patch
+
+require File.join(File.dirname(__FILE__), 'xn', 'api_requestor')
+
+module Xn
+  class XnApiSession
+    if RUBY_PLATFORM == 'java'
+      require 'java'
+      include_class 'java.lang.System'
+      include_class 'java.io.Console'
+    else
+      require 'highline/import'
+    end
+
+    # Could make these configurable via xn.yml file in the future:
+    attr_reader :url, :login_path, :user, :api_suffix
+    attr_accessor :api
+
+    def initialize(server_url, user_email, api_suffix = "v1")
+      @url = URI(server_url)
+      @login_path = '/sessions.json'
+      @user = user_email
+      @api_suffix = api_suffix
+      @api = ApiRequestor.new url
+
+      if ENV['LMTOKEN']
+        @token = ENV['LMTOKEN']
+        puts "Using token from env LMTOKEN"
+      else
+        @token = token
+      end
+      @api.token = @token
+    end
+
+    # Get a user's password from the command line
+    # don't cache me...
+    def password
+      if RUBY_PLATFORM == 'java'
+        console = System.console
+        pass = console.read_password("Password: ")
+        java.lang.String.new(pass)
+      else
+        pass = ask("Password: ") { |q| q.echo = "*" }
+      end
+    end
+
+    # Login to the host and prompt for password.
+    # return the token
+    def login
+      request_hash = { user: { email: user, password: password } }
+      api.post login_path, request_hash do |response|
+        response['token']
+      end
+    end
+
+    def token
+      @token ||= login
+    end
+
+    # Fetch a single vertex of given model type from the server
+    # return a hash of the vertex or nil
+    def find_vertex_by_model(model, filter_string)
+      debug "find_vertex_by_model(#{model.downcase}, #{filter_string})"
+      raise "model is a required argument" if model.nil?
+      if filter_string and filter_string[/\?/]
+        filter_string = "#{filter_string}&limit=1"
+      else
+        filter_string = "#{filter_string}?limit=1"
+      end
+      request_path = "/#{api_suffix}/model/#{model.downcase}/#{filter_string}"
+      debug "GET #{request_path}"
+      api.get request_path do |response|
+        vertex = response.first
+        debug "found vertex [#{vertex}]"
+        vertex
+      end
+    end
+
+    # Fetch a single vertex of given part type from the server
+    # return a hash of the vertex or nil
+    def find_vertex_by_part(part, filter_string)
+      debug "find_vertex_by_part(#{part}, #{filter_string})"
+      raise "part is a required argument" if part.nil?
+      if filter_string and filter_string[/\?/]
+        filer_string = "#{filter_string}&limit=1"
+      else
+        filter_string = "#{filter_string}?limit=1"
+      end
+      request_path = "/#{api_suffix}/is/#{part.downcase}/#{filter_string}"
+      api.get request_path do |response|
+        vertex = response.first
+        debug "found vertex [#{vertex}]"
+        vertex
+      end
+    end
+
+    # Create a vertex of given model with given properties
+    # return a hash of the vertex or nil
+    def create_vertex(model, props)
+      debug "create_vertex(#{model}, #{props})"
+      raise "model and :name property are required" if model.nil? or props.nil? or props[:name].nil?
+
+      request_path = "/#{api_suffix}/model/#{model.downcase}"
+      api.put request_path, props do |response|
+        if response and response[0] != false
+          return vertex = response[2]
+        end
+      end
+    end
+
+    # update the given vertex with the given hash
+    # return a hash of the updates or nil
+    def update_vertex(vertex, update_hash)
+      debug "update_vertex(#{vertex}, #{update_hash})"
+      return nil if vertex.nil? or update_hash.nil?
+      if !vertex.is_a? Hash
+        vertex = find_vertex_by_part :record, vertex
+      end
+
+      request_path = "/#{api_suffix}/model/#{vertex['meta']['model_name']}/#{vertex['id']}"
+      debug "PATCH #{request_path} (#{update_hash.to_json})"
+      api.patch request_path, update_hash do |response|
+        debug "updated vertex [#{response}]"
+        response
+      end
+    end
+
+    # find or create a vertex by model and name and optionally provide
+    # a filter string to append to the model/xxx/ URL and properties to set
+    # if not found.
+    #
+    # (example filter_string: 'filter/name/?name[value]=myname')
+    def find_or_create_by_model_and_name(model, name, filter_string = nil, props = {})
+      debug "find_or_create_by_model_and_name(#{model}, #{name}, #{filter_string}, #{props})"
+      filter_string = "filter/name/?name[value]=#{name}" unless filter_string
+      props = props.merge name: name
+      obj = find_vertex_by_model(model, filter_string)
+      if obj.nil? or obj.empty?
+        debug "about to create a #{model} vertex with #{props} properties" if obj.nil? or obj.empty?
+        obj = create_vertex(model, props)
+      end
+      obj
+    end
+
+    # return all vertices related to the given one
+    def related_vertices(vertex)
+      debug "related_vertices(#{vertex})"
+      if vertex and vertex.is_a? Hash and vertex['meta']['model_name']
+        model = vertex['meta']['model_name']
+        request_path = "/#{api_suffix}/model/#{model}/#{vertex['id']}/rel"
+        api.get request_path do |parts|
+          debug "  parts: #{parts}"
+          related = parts.map do |part|
+            find_vertex_by_model model, "#{vertex['id']}/rel/#{part}"
+          end.compact.reject do |response|
+            response[:status] == 404   # No need to tell us what doesn't exist!
+          end
+          debug "found related: [#{related}]"
+          return related if related.any?
+        end
+      end
+    end
+
+    # execute the named action with any properties as args
+    def exec_action(vertex, action_name, props = {})
+      debug "exec_action(#{vertex}, #{action_name}, #{props})"
+      request_path = "/#{api_suffix}/model/#{vertex['meta']['model_name']}/#{vertex['id']}/action/#{action_name}"
+      debug "POST #{request_path} (#{props.to_json})"
+      api.post request_path, props do |response|
+        debug "executed #{action_name} on vertex [#{response}]"
+        response
+      end
+    end
+
+    protected
+
+    def debug(message = "")
+      if ENV['XN_VERBOSITY'] and ENV['XN_VERBOSITY'] == 'debug'
+        message = yield if block_given?
+        STDERR.puts "DEBUG: #{message}"
+      end
+    end
+
+    def verbose(message)
+      if ENV['XN_VERBOSITY']
+        message = yield if block_given?
+        STDERR.puts "#{message}"
+      end
+    end
+  end
+end
+

data/lib/xn/api_requestor.rb

@@ -0,0 +1,98 @@
+# Simple API request wrapper.  Instantiate multiple times to hit the
+# server in parallel.
+
+module Xn
+  class AuthorizationError < StandardError; end
+
+  class ApiRequestor
+    attr_accessor :uri, :token
+
+    def initialize(server_uri, token = nil)
+      raise "#{self.class} Err: First arg must be an instance of URI" if !server_uri.is_a? URI
+      @uri = server_uri
+      @token = token
+    end
+
+    # Request the resource(s) and a renderable JSON response
+    def get(resource_url, &block)
+      call_http_server Net::HTTP::Get.new( URI.encode(resource_url) ), &block
+    end
+
+    # Calls a method resource and returns a renderable JSON response
+    def post(resource_url, body = nil, &block)
+      http_post = Net::HTTP::Post.new resource_url, {'Content-Type' =>'application/json'}
+      if body
+        body = body.to_json if body.is_a? Enumerable
+        http_post.body = body
+      end
+      call_http_server http_post, &block
+    end
+
+    # Calls a method resource to create a vertex and returns a renderable JSON response
+    def put(resource_url, body = nil, &block)
+      http_put = Net::HTTP::Put.new resource_url, {'Content-Type' =>'application/json'}
+      http_put.body = json_body(body) if body
+      call_http_server http_put, &block
+    end
+
+    # Calls a method resource to update a vertex and returns a renderable JSON response
+    def patch(resource_url, body = nil, &block)
+      http_patch = Net::HTTP::Patch.new resource_url, {'Content-Type' =>'application/json'}
+      http_patch.body = json_body(body) if body
+      call_http_server http_patch, &block
+    end
+
+    private
+
+    # Ensure the body is json
+    def json_body(body)
+      if body.is_a? Enumerable
+        body.to_json
+      else
+        body
+      end
+    end
+
+    def call_http_server(request, &block)
+      request['AUTHORIZATION'] = token if token
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https' ) do |http|
+        response = nil
+        http.read_timeout = 240
+        start_time = Time.now
+        t = Thread.new { response = http.request(request) }
+        i = 0
+        while response.nil? and ( Time.now - start_time < http.read_timeout )
+          i += 1
+          print '.'
+          if i % 20 == 0
+            print "\r"
+          end
+          sleep 0.01
+        end
+        print "\r"
+        t.join
+
+        begin
+          json = JSON.parse(response.body)
+          raise AuthorizationError, "#{json['message']} (#{json['parsed_url']})" if response.code.to_i == 401
+        rescue JSON::ParserError => e
+          # Probably not JSON, return entire body
+          return { status: response.code.to_i, body: response.body }
+        end
+        if block and response.code.to_i < 300
+          block.call json
+        else
+          { status: response.code.to_i, json: json }
+        end
+      end
+      rescue Exception => e
+        raise e if e.is_a? AuthorizationError
+        raise e if e.is_a? Errno::ECONNREFUSED or e.is_a? Net::HTTPBadRequest
+        puts "ERROR making request from: "
+        puts request
+        puts e.message
+        puts e.backtrace
+    end
+  end
+end
+

data/lib/xn/version.rb

@@ -0,0 +1,3 @@
+module Xn
+  VERSION = "0.0.2"
+end

data/xn.rb.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "xn/version"
+
+Gem::Specification.new do |s|
+  s.name        = "xn.rb"
+  s.version     = Xn::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["David Colebatch", "Darrick Wiebe"]
+  s.email       = ["dc@xnlogic", "dw@xnlogic"]
+  s.homepage    = "http://www.xnlogic.com/"
+  s.summary     = %q{XN Logic API client - first used by LightMesh utilities}
+  s.description = %q{Aims to provide a semantic wrapper for the XN Logic graph-db application framework's REST API.}
+  
+  s.add_dependency 'highline'
+
+  s.rubyforge_project = "xn.rb"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ["lib"]
+end
+

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: xn.rb
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- David Colebatch
+- Darrick Wiebe
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: highline
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Aims to provide a semantic wrapper for the XN Logic graph-db application
+  framework's REST API.
+email:
+- dc@xnlogic
+- dw@xnlogic
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/xn.rb
+- lib/xn/api_requestor.rb
+- lib/xn/version.rb
+- xn.rb.gemspec
+homepage: http://www.xnlogic.com/
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: xn.rb
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: XN Logic API client - first used by LightMesh utilities
+test_files: []