resource_set 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 79aa7ef9a5449e0663ad6ec7d0bd3b038d46beda
+  data.tar.gz: 5a54cdfa3b831b445bbcfd422deec1547a34bc8c
+SHA512:
+  metadata.gz: 38309396161c178f16b9c45c0720d2d65f928cd0aeb719e71d4491cecbda381b4bc92afe5be60a85be1abf1ddd093b8d9f7e57ff87028c75421cfea9fcb69290
+  data.tar.gz: a39ce7e9f13d7e1de224aad0eee5b9824c14866c22c706ac4a5957f1183c16f78ff16c43debde781a5c7dd9a19c02b217cf9868cd08a9388384e2bae4811974f

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,12 @@
+language: ruby
+sudo: false
+
+rvm:
+  - 2.0.0
+  - 2.1.8
+  - 2.2.4
+  - 2.3.3
+  - 2.4.1
+
+cache:
+  bundler: true

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+Resource Set Changelog
+======================
+
+### master
+
+### [v1.0.0][v1.0.0] (September 8, 2017)
+
+* Fixed Fixnum deprecation warnings
+  ([#4](https://github.com/kyrylo/resource_set/pull/4))
+
+[v1.0.0]: https://github.com/kyrylo/resource_set/releases/tag/v1.0.0

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Robert Ross
+
+MIT License
+
+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,165 @@
+# Resource Set
+
+Resource Set provides tools to aid in making API Clients. Such as URL resolving, Request / Response layer, and more.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'resource_set'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install resource_set
+
+## Usage
+
+This library recommends using [Cartograph](http://github.com/kyrylo/cartograph) for representing and deserializing response bodies.
+You'll see it in the examples provided below.
+
+### Resource classes
+
+Resource Set provides a comprehensive but intuitive DSL where you describe the remote resources capabilities.
+For example, where can I get a list of users? Where do I get a single user? How do I create a user?
+
+When you're able to answer these questions, you can describe them in your resource class like this:
+
+```ruby
+class DropletResource < ResourceSet::Resource
+  resources do
+    default_handler(422) { |response| ErrorMapping.extract_single(response.body, :read) }
+    default_handler(:ok, :created) { |response| DropletMapping.extract_single(response.body, :read) }
+    default_handler { |response| raise "Unexpected response status #{response.status}... #{response.body}" }
+
+    # Defining actions will create instance methods on the resource class to call them.
+    action :find do
+      verb :get # get is assumed if this is omitted
+      path '/droplets/:id'
+      handler(200) { |response| DropletMapping.extract_single(response.body, :read) }
+    end
+
+    action :all do
+      path '/droplets'
+      handler(200) { |body| DropletMapping.extract_collection(body, :read) }
+    end
+
+    action :create do
+      path '/droplets'
+      verb :post
+      body { |object| DropletMapping.representation_for(:create, object) } # Generate a response body from a passed object
+      handler(202) { |response| DropletMapping.extract_single(response.body, :read) }
+    end
+  end
+end
+```
+
+You also have the option to use a shorter version to describe actions like this:
+
+```ruby
+class DropletResource < ResourceSet::Resource
+  resources do
+    action :all, 'GET /v2/droplets' do
+      handler(:ok) { |response| DropletMapping.extract_collection(response.body, :read) }
+    end
+  end
+end
+```
+
+Instead of using `#action`, you can use any of the supported HTTP verb methods including `#get`, `#post`, `#put`, `#delete`, `#head`, `#patch`, and `#options`. Thus, the above example can be also written as:
+
+```ruby
+class DropletResource < ResourceSet::Resource
+  resources do
+    get :all, '/v2/droplets' do
+      handler(:ok) { |response| DropletMapping.extract_collection(response.body, :read) }
+    end
+  end
+end
+```
+
+Now that we've described our resources. We can instantiate our class with a connection object. ResourceSet relies on the interface that Faraday provides. For example:
+
+```ruby
+conn = Faraday.new(url: 'http://api.digitalocean.com') do |req|
+  req.adapter :net_http
+end
+
+resource = DropletResource.new(connection: conn)
+```
+
+Now that we've instantiated a resource with our class, we can call the actions we've defined on it.
+
+```
+all_droplets = resource.all
+single_droplet = resource.find(id: 123)
+create = resource.create(Droplet.new)
+```
+
+## Scope
+
+ResourceSet classes give you the option to pass in an optional scope object, so that you may interact with the resource with it that way.
+
+For example, you may want to use this for nested resources:
+
+```ruby
+class CommentResource < ResourceSet::Resource
+  resources do
+    action :all do
+      path { "/users/#{user_id}/comments" }
+      handler(200) { |resp| CommentMapping.extract_collection(resp.body, :read) }
+    end
+  end
+
+  def user_id
+    scope.user_id
+  end
+end
+
+user = User.find(123)
+resource = CommentResource.new(connection: conn, scope: user)
+comments = resource.all #=> Will fetch from /users/123/comments
+```
+
+## Test Helpers
+
+ResourceSet supplys test helpers that assist in certain things you'd want your resource classes to do.
+
+Make sure you:
+
+    require 'resource_set/testing'
+
+Testing a certain action:
+
+```ruby
+# Tag the spec with resource_set to bring in the helpers
+RSpec.describe MyResourceClass, resource_set: true do
+  it 'has an all action' do
+    expect(MyResourceClass).to have_action(:all).that_handles(:ok, :no_content).at_path('/users')
+  end
+
+  it 'handles a 201 with response body' do
+    expect(MyResourceClass).to handle_response(:create).with(status: 201, body: '{"users":[]}') do |handled|
+      expect(handled).to all(be_kind_of(User))
+    end
+  end
+end
+```
+
+### Nice to have's
+
+Things we've thought about but just haven't implemented are:
+
+* Pagination capabilities
+
+
+## Contributing
+
+1. Fork it ( https://github.com/kyrylo/resource_set/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,5 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/digitalocean_droplets.rb

@@ -0,0 +1,60 @@
+require 'kartograph'
+
+class Droplet
+  attr_accessor :id, :name, :region, :size, :image
+end
+
+class DropletMapping
+  include Kartograph::DSL
+
+  kartograph do
+    mapping Droplet
+    root_key plural: 'droplets', singular: 'droplet', scopes: [:read]
+
+    property :id, scopes: [:read]
+    property :name, scopes: [:read, :create]
+    property :size, scopes: [:read, :create]
+    property :image, scopes: [:read, :create]
+    property :region, scopes: [:read, :create]
+  end
+end
+
+class DropletResource < ResourceSet::Resource
+  resources do
+    action :all do
+      verb :get
+      path '/v2/droplets'
+      handler(200) { |response| DropletMapping.extract_collection(response.body, :read) }
+    end
+
+    action :find do
+      verb :get
+      path '/v2/droplets/:id'
+      handler(200) { |response| DropletMapping.extract_single(response.body, :read) }
+    end
+
+    action :create do
+      verb :post
+      path '/v2/droplets'
+      body { |object| DropletMapping.representation_for(:create, object) }
+      handler(202) { |response| DropletMapping.extract_single(response.body, :read) }
+    end
+
+    action :update do
+      verb :put
+      path '/v2/droplets/123'
+      body { |object| DropletMapping.representation_for(:create, object) }
+      handler(200) { |response, object| DropletMapping.extract_into_object(object, response.body, :read) }
+    end
+  end
+end
+
+token = 'YOUR_ACCESS_TOKEN'
+conn = Faraday.new(url: 'https://api.digitalocean.com', headers: { content_type: 'application/json', authorization: "Bearer #{token}" }) do |req|
+  req.adapter :net_http
+end
+
+resource = DropletResource.new(connection: conn)
+
+# Retrieve all droplets
+puts resource.all

data/examples/httpbin_client.rb

@@ -0,0 +1,15 @@
+require 'resource_set'
+
+class HTTPBinResource < ResourceSet::Resource
+  resources do
+    get '/ip' => :ip
+    get '/status/:code' => :status
+  end
+end
+
+conn = Faraday.new(url: 'http://httpbin.org')
+resource = HTTPBinResource.new(connection: conn)
+
+puts resource.ip
+puts
+puts resource.status(code: 418)

data/lib/resource_set/action.rb

@@ -0,0 +1,66 @@
+module ResourceSet
+  class Action
+    attr_reader :name
+
+    def initialize(name, verb = nil, path = nil)
+      @name = name
+      @verb = (verb && verb.downcase.to_sym) || :get
+      @path = path
+      @query_keys = []
+    end
+
+    def verb(v = nil)
+      @verb = v if v
+      @verb
+    end
+
+    def path(path = nil, &block)
+      raise "You must pass either a block or a string for paths" if path and block_given?
+      @path = path if path
+      @path = block if block_given?
+      @path
+    end
+
+    def query_keys(*keys)
+      return @query_keys if keys.empty?
+      @query_keys += keys
+    end
+
+    def handlers
+      @handlers ||= {}
+    end
+
+    def handler(*response_codes, &block)
+      if response_codes.empty?
+        handlers[:any] = block
+      else
+        response_codes.each do |code|
+          code = StatusCodeMapper.code_for(code) unless code.is_a?(Integer)
+          handlers[code] = block
+        end
+      end
+    end
+
+    def body(&block)
+      @body_handler = block if block_given?
+      @body_handler
+    end
+
+    def hooks
+      @hooks ||= {}
+    end
+
+    def before_request(method_name = nil, &block)
+      hooks[:before] ||= []
+
+      if block_given?
+        hooks[:before] << block
+      else
+        raise "Must include a method name" unless method_name
+        hooks[:before] << method_name
+      end
+
+      nil
+    end
+  end
+end

data/lib/resource_set/action_invoker.rb

@@ -0,0 +1,58 @@
+module ResourceSet
+  class ActionInvoker
+    attr_reader :action, :connection, :args, :options, :resource
+
+    def initialize(action, resource, *args)
+      @action = action
+      @resource = resource
+      @connection = resource.connection
+      @args = args
+      @options = args.last.kind_of?(Hash) ? args.last : {}
+    end
+
+    def self.call(action, resource, *args)
+      new(action, resource, *args).handle_response
+    end
+
+    def handle_response
+      if handler = action.handlers[response.status] || action.handlers[:any]
+        resource.instance_exec(response, *args, &handler) # Since the handler is a block, it does not enforce parameter length checking
+      else
+        response.body
+      end
+    end
+
+    def construct_body
+      action.body.call(*args[0..(action.body.arity - 1)])
+    end
+
+    def response
+      return @response if @response
+
+      raise ArgumentError, "Verb '#{action.verb}' is not allowed" unless ALLOWED_VERBS.include?(action.verb)
+
+      @response = connection.send(action.verb, resolver.resolve(options)) do |request|
+        request.body = construct_body if action.body and [:post, :put, :patch, :delete].include?(action.verb)
+        append_hooks(:before, request)
+      end
+    end
+
+    def resolver
+      path = action.path.kind_of?(Proc) ? resource.instance_eval(&action.path) : action.path
+      EndpointResolver.new(path: path, query_param_keys: action.query_keys)
+    end
+
+    private
+
+    def append_hooks(hook_type, request)
+      (action.hooks[hook_type] || []).each do |hook|
+        case hook
+        when Proc
+          resource.instance_exec(*args, request, &hook)
+        when Symbol
+          resource.send(hook, *args, request)
+        end
+      end
+    end
+  end
+end