sunstone 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5c574fe947ca4f3c808d4b1d843ae0e2bb4ce9ea
+  data.tar.gz: a2410c511c64d0f2b7a85dbc5cbbff3b23a2f7a1
+SHA512:
+  metadata.gz: 3837b844459bdf78f20fd3562f44b6a91cb53c3fa3f4474d32bf3e7375b96400a2b39a45e907ff0fc2cf0d60730d2984606f01a13bfa7b03a01e330878d5be75
+  data.tar.gz: bf4c9c42165f389bc6e5e1475b19641a24d41ed6b7f8007fa37a549fdf6917656db7ebdcb609156b649d3c793eac053db84aa9fad2be3fabcc603430e8009d61

data/.gitignore

@@ -0,0 +1,29 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.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
+
+# Text Editor scraps
+*~

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in sunstone.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Jon Bracy
+
+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,4 @@
+sunstone
+========
+
+A library for interacting with REST APIs

data/Rakefile.rb

@@ -0,0 +1,37 @@
+require 'bundler/setup'
+require "bundler/gem_tasks"
+Bundler.require(:development)
+require 'rake/testtask'
+require 'rdoc/task'
+
+task :console do
+  exec 'irb -I lib -r sunstone.rb'
+end
+task :c => :console
+
+Rake::TestTask.new do |t|
+    t.libs << 'lib' << 'test'
+    t.test_files = FileList['test/**/*_test.rb']
+    #t.warning = true
+    #t.verbose = true
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = 'README.md'
+  rd.title = 'Sunstone Documentation'
+  rd.rdoc_dir = 'doc'
+  
+  rd.options << '-f' << 'sdoc'
+  rd.options << '-T' << '42floors'
+  rd.options << '-g' # Generate github links
+  
+  rd.rdoc_files.include('README.rdoc')
+  rd.rdoc_files.include('lib/**/*.rb')
+end
+
+desc "Run tests"
+task :default => :test
+
+namespace :pages do
+  #TODO: https://github.com/defunkt/sdoc-helpers/blob/master/lib/sdoc_helpers/pages.rb
+end

data/TODO.md

@@ -0,0 +1,89 @@
+- Check if `Sunstone#to_key` needs to be added
+
+- Add `Sunstone::Model::Persistance` with the following methods:
+
+  - `#new_record?`
+  - `#persisted?`
+  - `#save`
+  - `#save!`
+  - `#update`
+  - `#update!`
+  - `#create`
+  - `#to_param` ?
+  - `::all`
+  - `::where` (probably goes in an Arel like engine)
+  - `::build`
+  - `::create!`
+  - `#==`
+  - `::create`
+
+      ```ruby
+      # Creates an object and saves it to the MLS. The resulting object is returned
+      # whether or no the object was saved successfully to the MLS or not.
+      #
+      # ==== Examples
+      #  #!ruby
+      #  # Create a single new object
+      #  User.create(:first_name => 'Jamie')
+      #  
+      #  # Create a single object and pass it into a block to set other attributes.
+      #  User.create(:first_name => 'Jamie') do |u|
+      #    u.is_admin = false
+      #  end
+      def self.create(attributes={}, &block) # TODO: testme
+        model = self.new(attributes)
+        yield(model) if block_given?
+        model.save
+        model
+      end
+      
+
+- Look at https://gist.github.com/malomalo/91f360fe52db3dbe1c99 files for inspiration, came from
+  Rails code I think
+  
+- Simplify `Sunstone::Type::Value` to `Sunstone::Type`
+
+- Add a `find_class(type)` in `Sunstone::Schema`
+
+- Possibly use Classes to hold information about each attribute in addition to the type
+
+   ```ruby
+   class MLS::Attribute
+   
+     DEFAULT_OPTIONS = { :serialize => true }
+  
+     attr_reader :model, :name, :instance_variable_name, :options, :default
+     attr_reader :reader_visibility, :writer_visibility
+
+     def initialize(name, options={})
+       @name                   = name
+       @instance_variable_name = "@#{@name}".freeze
+       @options                = DEFAULT_OPTIONS.merge(options)
+     
+       @default = @options[:default]
+       @reader_visibility = @options[:reader] || :public
+       @writer_visibility = @options[:writer] || :public
+     end
+   end
+   ```
+
+- Use Association classes to model the association:
+
+	```ruby
+	class MLS::Association
+	  class BelongsTo
+	    attr_reader :klass, :foreign_key, :foreign_type, :primary_key, :polymorphic
+	  
+	    def initialize(name, options={})
+	      @name                   = name
+	      @klass = options[:class_name] ? options[:class_name].constantize : name.camelize.constantize
+	    
+	      @polymorphic  = options[:polymorphic]  || false    
+	      @foreign_key  = options[:foreign_key]  || "#{name}_id".to_sym
+	      @foreign_type = options[:foreign_type] || "#{name}_type".to_sym
+	      @primary_key  = options[:primary_key]  || :id
+	    end
+	  end
+
+	end
+	```

data/lib/sunstone.rb

@@ -0,0 +1,361 @@
+require 'set'
+require 'uri'
+require 'net/https'
+
+require 'wankel'
+require 'cookie_store'
+require 'connection_pool'
+
+require 'active_support'
+require 'active_support/core_ext'
+
+require 'active_model'
+
+require 'sunstone/exception'
+require 'sunstone/schema'
+require 'sunstone/model'
+require 'sunstone/parser'
+
+# _Sunstone_ is a low-level API. It provides basic HTTP #get, #post, #put, and
+# #delete calls to the Sunstone Server. It can also provides basic error
+# checking of responses.
+module Sunstone
+  VERSION = 0.1
+  
+  extend self
+  
+  attr_reader :site
+  
+  # Set the User-Agent of the client. Will be joined with other User-Agent info
+  attr_writer :user_agent
+  attr_accessor :api_key, :host, :port, :use_ssl
+  
+  # Sets the Protocol, API Token, and Host and Port of the API Server
+  #
+  # #!ruby
+  # Sunstone.site = "https://API_KEY@host.com"
+  def site=(url)
+    @site = url
+    uri = URI.parse(url)
+    @api_key = uri.user ? CGI.unescape(uri.user) : nil
+    @host, @port = uri.host, uri.port
+    @use_ssl = (uri.scheme == 'https')
+  end
+  
+  # Returns the User-Agent of the client. Defaults to:
+  # "sunstone-ruby/SUNSTONE_VERSION RUBY_VERSION-pPATCH_LEVEL PLATFORM"
+  def user_agent
+    [
+      @user_agent,
+      "Sunstone/#{Sunstone::VERSION}",
+      "Ruby/#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}",
+      RUBY_PLATFORM
+    ].compact.join(' ')
+  end
+  
+  # Set a cookie jar to use during request sent during the 
+  def with_cookie_store(store, &block)
+    Thread.current[:sunstone_cookie_store] = store
+    yield
+  ensure
+    Thread.current[:sunstone_cookie_store] = nil
+  end
+
+  # Sends a Net::HTTPRequest to the server. The headers returned from
+  # Sunestone#headers are automatically added to the request. The appropriate
+  # error is raised if the response is not in the 200..299 range.
+  #
+  # Paramaters::
+  #
+  # * +request+ - A Net::HTTPRequest to send to the server
+  # * +body+ - Optional, a String, IO Object, or a Ruby object which is 
+  #            converted into JSON and sent as the body
+  # * +block+ - An optional block to call with the +Net::HTTPResponse+ object.
+  #
+  # Return Value::
+  #
+  #  Returns the return value of the <tt>&block</tt> if given, otherwise the
+  #  response object (a Net::HTTPResponse)
+  #
+  # Examples:
+  #
+  #  #!ruby
+  #  Sunstone.send_request(#<Net::HTTP::Get>) # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.send_request(#<Net::HTTP::Get @path="/404">) # => raises Sunstone::Exception::NotFound
+  #
+  #  # this will still raise an exception if the response_code is not valid
+  #  # and the block will not be called
+  #  Sunstone.send_request(#<Net::HTTP::Get>) do |response|
+  #    # ...
+  #  end
+  #
+  #  # The following example shows how to stream a response:
+  #  Sunstone.send_request(#<Net::HTTP::Get>) do |response|
+  #    response.read_body do |chunk|
+  #      io.write(chunk)
+  #    end
+  #  end
+  def send_request(request, body=nil, &block)
+    request_headers.each { |k, v| request[k] = v }
+    
+    if body.is_a?(IO)
+      request['Transfer-Encoding'] = 'chunked'
+      request.body_stream =  body
+    elsif body.is_a?(String)
+      request.body = body
+    elsif body
+      request.body = Wankel.encode(body)
+    end
+    
+    return_value = nil
+    with_connection do |connection|
+      connection.request(request) do |response|
+        
+        if response['X-42Floors-API-Version-Deprecated']
+          logger.warn("DEPRECATION WARNING: API v#{API_VERSION} is being phased out")
+        end
+        
+        validate_response_code(response)
+        
+        # Get the cookies
+        response.each_header do |key, value|
+          if key.downcase == 'set-cookie' && Thread.current[:sunstone_cookie_store]
+            Thread.current[:sunstone_cookie_store].set_cookie("#{site}#{request.path}", value)
+          end
+        end
+        
+        if block_given?
+          return_value =yield(response)
+        else
+          return_value =response
+        end
+      end
+    end
+    
+    return_value
+  end
+  
+  # Send a GET request to +path+ on the Sunstone Server via +Sunstone#send_request+.
+  # See +Sunstone#send_request+ for more details on how the response is handled.
+  #
+  # Paramaters::
+  #
+  # * +path+ - The +path+ on the server to GET to.
+  # * +params+ - Either a String, Hash, or Ruby Object that responds to
+  #              #to_param. Appended on the URL as query params
+  # * +block+ - An optional block to call with the +Net::HTTPResponse+ object.
+  #
+  # Return Value::
+  #
+  #  See +Sunstone#send_request+
+  #
+  # Examples:
+  #
+  #  #!ruby
+  #  Sunstone.get('/example') # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.get('/example', 'query=stuff') # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.get('/example', {:query => 'stuff'}) # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.get('/404') # => raises Sunstone::Exception::NotFound
+  #
+  #  Sunstone.get('/act') do |response|
+  #    # ...
+  #  end
+  def get(path, params='', &block)
+    params ||= ''
+    request = Net::HTTP::Get.new(path + '?' + params.to_param)
+    
+    send_request(request, nil, &block)
+  end
+
+  # Send a POST request to +path+ on the Sunstone Server via +Sunstone#send_request+.
+  # See +Sunstone#send_request+ for more details on how the response is handled.
+  #
+  # Paramaters::
+  #
+  # * +path+ - The +path+ on the server to POST to.
+  # * +body+ - Optional, See +Sunstone#send_request+.
+  # * +block+ - Optional, See +Sunstone#send_request+
+  #
+  # Return Value::
+  #
+  #  See +Sunstone#send_request+
+  #
+  # Examples:
+  #
+  #  #!ruby
+  #  Sunstone.post('/example') # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.post('/example', 'body') # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.post('/example', #<IO Object>) # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.post('/example', {:example => 'data'}) # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.post('/404') # => raises Sunstone::Exception::NotFound
+  #
+  #  Sunstone.post('/act') do |response|
+  #    # ...
+  #  end
+  def post(path, body=nil, &block)
+    request = Net::HTTP::Post.new(path)
+    
+    send_request(request, body, &block)
+  end
+  
+  # Send a PUT request to +path+ on the Sunstone Server via +Sunstone#send_request+.
+  # See +Sunstone#send_request+ for more details on how the response is handled.
+  #
+  # Paramaters::
+  #
+  # * +path+ - The +path+ on the server to POST to.
+  # * +body+ - Optional, See +Sunstone#send_request+.
+  # * +block+ - Optional, See +Sunstone#send_request+
+  #
+  # Return Value::
+  #
+  #  See +Sunstone#send_request+
+  #
+  # Examples:
+  #
+  #  #!ruby
+  #  Sunstone.put('/example') # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.put('/example', 'body') # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.put('/example', #<IO Object>) # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.put('/example', {:example => 'data'}) # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.put('/404') # => raises Sunstone::Exception::NotFound
+  #
+  #  Sunstone.put('/act') do |response|
+  #    # ...
+  #  end
+  def put(path, body=nil, *valid_response_codes, &block)
+    request = Net::HTTP::Put.new(path)
+    
+    send_request(request, body, &block)
+  end
+  
+  # Send a DELETE request to +path+ on the Sunstone Server via +Sunstone#send_request+.
+  # See +Sunstone#send_request+ for more details on how the response is handled
+  #
+  # Paramaters::
+  #
+  # * +path+ - The +path+ on the server to POST to.
+  # * +block+ - Optional, See +Sunstone#send_request+
+  #
+  # Return Value::
+  #
+  #  See +Sunstone#send_request+
+  #
+  # Examples:
+  #
+  #  #!ruby
+  #  Sunstone.delete('/example') # => #<Net::HTTP::Response>
+  #
+  #  Sunstone.delete('/404') # => raises Sunstone::Exception::NotFound
+  #
+  #  Sunstone.delete('/act') do |response|
+  #    # ...
+  #  end
+  def delete(path, &block)
+    request = Net::HTTP::Delete.new(path)
+    
+    send_request(request, nil, &block)
+  end
+  
+  # Get a connection from the connection pool and perform the block with
+  # the connection
+  def with_connection(&block)
+    connection_pool.with({}, &block)
+  end
+  
+  # Ping the Sunstone. If everything is configured and operating correctly
+  # <tt>"pong"</tt> will be returned. Otherwise and Sunstone::Exception should be
+  # thrown.
+  #
+  #  #!ruby
+  #  Sunstone.ping # => "pong"
+  #
+  #  Sunstone.ping # raises Sunstone::Exception::ServiceUnavailable if a 503 is returned
+  def ping
+    get('/ping').body
+  end
+  
+  def config
+    @config ||= Wankel.parse(get('/config').body, :symbolize_keys => true)
+  end
+  
+  private
+  
+  def request_headers
+    headers = {
+      'Content-Type'            => 'application/json',
+      'User-Agent'              => user_agent
+    }
+    
+    headers['Api-Key'] = api_key if api_key
+    
+    headers
+  end
+  
+  # Raise an Sunstone::Exception based on the response_code, unless the response_code
+  # is include in the valid_response_codes Array
+  #
+  # Paramaters::
+  #
+  # * +response+ - The Net::HTTP::Response object
+  #
+  # Return Value::
+  #
+  #  If an exception is not raised the +response+ is returned
+  #
+  # Examples:
+  #
+  #  #!ruby
+  #  Sunstone.validate_response_code(<Net::HTTP::Response @code=200>) # => <Net::HTTP::Response @code=200>
+  #
+  #  Sunstone.validate_response_code(<Net::HTTP::Response @code=404>) # => raises Sunstone::Exception::NotFound
+  #
+  #  Sunstone.validate_response_code(<Net::HTTP::Response @code=500>) # => raises Sunstone::Exception
+  def validate_response_code(response)
+    code = response.code.to_i
+    
+    if !(200..299).include?(code)
+      case code
+      when 400
+        raise Sunstone::Exception::BadRequest, response
+      when 401
+        raise Sunstone::Exception::Unauthorized, response
+      when 404
+        raise Sunstone::Exception::NotFound, response
+      when 410
+        raise Sunstone::Exception::Gone, response
+      when 422
+        raise Sunstone::Exception::ApiVersionUnsupported, response
+      when 503
+        raise Sunstone::Exception::ServiceUnavailable, response
+      when 301
+        raise Sunstone::Exception::MovedPermanently, response
+      when 300..599
+        raise Sunstone::Exception, response
+      else
+        raise Sunstone::Exception, response
+      end
+    end
+  end
+  
+  def connection_pool
+    @connection_pool ||= ConnectionPool.new(size: 5, timeout: 5) do
+      connection = Net::HTTP.new(@host, @port)
+      connection.use_ssl = @ssl
+      connection
+    end
+  end
+  
+end