farscape 1.2.0

data/lib/farscape/representor.rb

@@ -0,0 +1,110 @@
+require 'representors'
+require 'farscape/transition'
+require 'ostruct'
+
+module Farscape
+  class SafeRepresentorAgent
+
+    include BaseAgent
+
+    attr_reader :agent
+    attr_reader :representor
+    attr_reader :response
+
+    EMPTY_BODIES = { hale: "{}" } #TODO: Fix Representor to allow nil resources
+
+    def initialize(requested_media_type, response, agent)
+      @agent = agent
+      @response = response
+      @requested_media_type = requested_media_type
+      @representor = deserialize(requested_media_type, response.body)
+      handle_extensions
+    end
+
+    %w(using omitting).each do |meth|
+      define_method(meth) { |name_or_type| self.class.new(@requested_media_type, @response, @agent.send(meth, name_or_type)) }
+    end
+
+    def attributes
+      representor.properties
+    end
+
+    #TODO: Handling list of transitions
+    def transitions
+      Hash[representor.transitions.map{ |trans| [trans.rel, Farscape::TransitionAgent.new(trans, agent)] }]
+    end
+
+    def embedded
+      Hash[representor.embedded.map{ |k, reps| [k, _embedded(reps, response)] }]
+    end
+
+    def to_hash
+      @representor.to_hash
+    end
+
+    def safe
+      reframe_representor(safe=true)
+    end
+
+    def unsafe
+      reframe_representor(safe=false)
+    end
+
+    private
+
+    def reframe_representor(safety)
+      agent = safety ? @agent.safe : @agent.unsafe
+      agent.representor.new(@requested_media_type, @response, agent)
+    end
+
+    def deserialize(requested_media_type, response_body)
+      return response_body unless requested_media_type
+      response_body = response_body || EMPTY_BODIES[@agent.media_type]
+      Representors::DeserializerFactory.build(requested_media_type, response_body).to_representor
+    end
+
+    def _embedded(reprs, response)
+      reprs = [reprs] unless reprs.respond_to?(:map)
+      reprs.map { |repr| @agent.representor.new(false, OpenStruct.new(status: response.status, headers: response.headers, body: repr), @agent) }
+    end
+
+  end
+
+  class RepresentorAgent < SafeRepresentorAgent
+    def method_missing(method, *args, &block)
+      super
+    rescue NoMethodError => e
+      parameters = args.first || {}
+      get_embedded(method) || get_transition(method, parameters, &block) || get_attribute(method) || raise
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      super || [embedded.include?(method_name), method_transitions.include?(method), attributes.include?(method)].any?
+    end
+
+    # HACK! - Requires for method_missing; apparently an undocumented feature of Ruby
+    def to_ary
+    end
+
+    private
+
+    def get_embedded(meth)
+      embedded[meth.to_s]
+    end
+
+    def get_attribute(meth)
+      attributes[meth.to_s]
+    end
+
+    def get_transition(meth, request_params = {}, &block)
+      return false unless method_transitions.include?(meth = meth.to_s)
+      block = ->(*args) { args } unless block_given?
+      method_transitions[meth].invoke(request_params) { |x| block.call(x) }
+    end
+
+    def method_transitions
+      transitions.map { |k,v| @agent.client.safe_method?( v.interface_method ) ? {k => v}  : {k+'!' => v} }.reduce({}, :merge)
+    end
+
+  end
+end

data/lib/farscape/transition.rb

@@ -0,0 +1,81 @@
+require 'representors'
+require 'ostruct'
+require 'active_support/core_ext/object/blank'
+
+module Farscape
+
+  class TransitionAgent
+
+    include BaseAgent
+
+    def initialize(transition, agent)
+      @agent = agent
+      @transition = transition
+      handle_extensions
+    end
+
+    def invoke(args = {})
+      opts = OpenStruct.new
+      yield opts if block_given?
+      options = match_params(args, opts)
+      params = args.merge(options.parameters || {})
+
+      call_options = {}
+      call_options[:method] = @transition.interface_method
+      call_options[:headers] = @agent.get_accept_header(@agent.media_type).merge(options.headers || {})
+      call_options[:body] = options.attributes if options.attributes.present?
+
+      if call_options[:method].downcase == 'get'
+        # delegate the URL building to representors so we can use templated URIs
+        call_options[:url] = @transition.uri(params)
+        # still need to use this for extra params... (e.g. "conditions=can_do_anything")
+        if params.present?
+          if @transition.templated?
+            # exclude the parameters that have been consumed by Addressable (e.g. path segments) so
+            # we don't repeat those in the final URL (ex: /api{/uuid} => /api/123456, not /api/123456?uuid=123456)
+            # TODO: make some "variables" method in representors/transition.rb so we don't deal with this here
+            Addressable::Template.new(@transition.templated_uri).variables.each do |param|
+              params.delete(param.to_sym)
+            end
+          end
+          call_options[:params] = params
+        end
+      else
+        # Farscape handles "parameters" as query string, and "attributes" as request body.
+        # However, in many API documents, only "parameters" is used regardless of methods.
+        # Since changing API documents must have a huge impact on existing systems,
+        # we use parameters as the request body if the method is not GET.
+        # This makes it impossible to use URIs with parameters.
+        call_options[:url] = @transition.uri
+        call_options[:body] = (call_options[:body] || {}).merge(params) if params.present?
+      end
+
+      response = @agent.client.invoke(call_options)
+
+      @agent.find_exception(response)
+    end
+
+    %w(using omitting).each do |meth|
+      define_method(meth) { |name_or_type| self.class.new(@transition, @agent.send(meth, name_or_type)) }
+    end
+
+    def method_missing(meth, *args, &block)
+      @transition.send(meth, *args, &block)
+    end
+
+    private
+
+    def match_params(args, options)
+      [:parameters, :attributes].each do |key_type|
+        field_list = @transition.public_send(key_type)
+        field_names = field_list.map { |field| field.name.to_sym }
+        filtered_values = args.select { |k,_| field_names.include?(k) }
+        values = filtered_values.merge(options.public_send(key_type) || {})
+        options.public_send(:"#{key_type}=", values)
+      end
+      options
+    end
+
+
+  end
+end

data/lib/farscape/version.rb

@@ -0,0 +1,6 @@
+# Used to prevent the class/module from being loaded more than once
+unless defined?(::Farscape::VERSION)
+  module Farscape
+    VERSION = '1.2.0'.freeze
+  end
+end

data/lib/farscape.rb

@@ -0,0 +1,4 @@
+require 'plugins/plugins'
+require 'farscape/base_agent'
+require 'farscape/agent'
+require 'farscape/cache'

data/lib/plugins/plugins.rb

@@ -0,0 +1,104 @@
+module Farscape
+  module Plugins
+
+    def self.enabled_plugins(plugins)
+      plugins.select { |plugin| plugins[plugin][:enabled] }
+    end
+
+    def self.disabled_plugins(plugins)
+      plugins.reject { |plugin| plugins[plugin][:enabled] }
+    end
+
+    # If the middleware has been disabled by name, return the name
+    # Else if by type, return the type.
+    # Else if :default_state was passed in return :default_state
+    def self.why_disabled(plugins, disabling_rules, options)
+      maybe = disabling_rules.map { |hash| hash.select { |k,v| k if v == options[k] } }
+      maybe |= [disabled_plugins(plugins)[options[:name]]]
+      maybe |= [:default_state] if options[:default_state] == :disabled
+      maybe.compact
+    end
+    
+    def self.disabled?(plugins, disabling_rules, options)
+      options = normalize_selector(options)
+      return plugins[options[:name]][:enabled] if options.include?([:name])
+      why_disabled(plugins, disabling_rules, options).any?
+    end
+    
+    def self.enabled?(plugins, disabling_rules, options)
+      !self.disabled?(plugins, disabling_rules, options)
+    end
+
+    def self.disable(name_or_type, disabling_rules, plugins)
+      name_or_type = self.normalize_selector(name_or_type)
+      plugins = set_plugin_states(name_or_type, false, plugins)
+      [disabling_rules << name_or_type, plugins]      
+    end
+
+    def self.enable(name_or_type, disabling_rules, plugins)
+      name_or_type = normalize_selector(name_or_type)
+      plugins = set_plugin_states(name_or_type, true, plugins)
+      [disabling_rules.reject {|k| k == name_or_type}, plugins]      
+    end
+
+    def self.set_plugin_states(name_or_type, condition, plugins)
+      plugins = Marshal.load( Marshal.dump(plugins) ) # TODO: This is super inefficient, figure out a good deep_dup
+      selected_plugins = find_attr_intersect(plugins, name_or_type)
+      selected_plugins.each { |plugin| plugins[plugin][:enabled] = condition }
+      plugins
+    end
+
+    def self.construct_stack(plugins)
+      stack = PartiallyOrderedList.new { |m,n| order_middleware(m,n) }
+      plugins.each do |_, plugin|
+        [*plugin[:middleware]].each do |middleware|
+          middleware = {class: middleware} unless middleware.is_a?(Hash)
+          middleware[:type] = plugin[:type]
+          middleware[:plugin] = plugin[:name]
+          stack.add(middleware)
+        end
+      end
+      stack
+    end
+
+    def self.normalize_selector(name_or_type)
+      name_or_type.is_a?(Hash) ? name_or_type : { name: name_or_type, type: name_or_type}
+    end
+
+    # Used by PartiallyOrderedList to implement the before: and after: options
+    def self.order_middleware(mw_1, mw_2)
+      case
+      when includes_middleware?(mw_1[:before],mw_2)
+        -1
+      when includes_middleware?(mw_1[:after],mw_2)
+        1
+      when includes_middleware?(mw_2[:before],mw_1)
+        1
+      when includes_middleware?(mw_2[:after],mw_1)
+        -1
+      end
+    end
+
+    def self.find_attr_intersect(master_hash, selector_hash)
+      master_hash.map do |mkey, mval|
+        selector_hash.map { |skey, sval| mkey if mval[skey] == sval }
+      end.flatten.compact
+    end
+
+    # Search a list for a given middleware by either its class or the type of its originating plugin
+    def self.includes_middleware?(list, middleware)
+      list = [*list]
+      list.map(&:to_s).include?(middleware[:class].to_s) || list.include?(middleware[:type])
+    end
+
+    def self.extensions(plugins)
+      plugs = plugins.map { |_, hash| hash[:extensions] }.compact
+      collect_values(plugs)
+    end
+
+    def self.collect_values(hashes)
+      hashes.reduce({}) { |h1, h2| h1.merge(h2) { |k, l1, l2| l1+l2 } }
+    end
+
+  end
+end

data/spec/lib/farscape/cache_spec.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+require 'farscape/cache'
+
+describe(Farscape) do
+
+  describe 'cache' do
+
+    after(:each) { Farscape.cache = nil }
+
+    it 'defaults to a memory store' do
+      expect(Farscape.cache).to be_a(ActiveSupport::Cache::MemoryStore)
+    end
+
+    it 'can be set to any store' do
+      custom_cache = Object.new
+      Farscape.cache = custom_cache
+      expect(Farscape.cache).to eq(custom_cache)
+    end
+
+  end
+
+end

data/spec/lib/farscape/integration/entry_point_spec.rb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+describe Farscape::Agent do
+  let(:entry_point) { "http://localhost:#{RAILS_PORT}"}
+
+  describe '#enter' do
+    it 'returns a Farscape::Representor' do
+      expect(Farscape::Agent.new(entry_point).enter).to be_a Farscape::RepresentorAgent
+    end
+
+    it 'can be provided an entry point after initialization' do
+      expect(Farscape::Agent.new.enter(entry_point)).to be_a Farscape::RepresentorAgent
+    end
+
+    #TODO decide on the appropriate error
+    it 'raises an appropriate error if no entry point is specified' do
+      expect{ Farscape::Agent.new.enter }.to raise_error(RuntimeError)
+    end
+
+    it 'raises an appropriate error when giving invalid requests' do
+      expect{ Farscape::Agent.new.enter("http://localhost:#{RAILS_PORT}/drds/ninja_boot")}.to raise_error(Farscape::Exceptions::UnprocessableEntity)
+      expect{ Farscape::Agent.new.enter("http://localhost:#{RAILS_PORT}/ninja_boot")}.to raise_error(Farscape::Exceptions::ProtocolException)
+
+      # Original test was expect{ Farscape::Agent.new.enter("http://localhost:#{RAILS_PORT}/ninja_boot")}.to raise_error(Farscape::Exceptions::NotFound)
+      # However, Moya is getting an internal server error when hitting a routing error instead of a 404
+
+    end
+  end
+end

data/spec/lib/farscape/integration/interface_spec.rb

@@ -0,0 +1,222 @@
+require 'spec_helper'
+require 'json'
+
+describe Farscape::SafeRepresentorAgent do
+
+  # TODO: Make Representor::Field behave like a string
+
+  let(:entry_point) { "http://localhost:#{RAILS_PORT}"}
+
+  let(:drds_link) { Farscape::Agent.new(entry_point).enter.transitions["drds"] }
+  let(:can_do_hash) { {conditions: 'can_do_anything'} }
+
+  describe "A Hypermedia API" do
+    it 'returns a Farscape::Representor instance
+    with a simple state-machine interface of attributes (data)
+    and transitions (link/form affordances) for interacting with the resource representations.' do
+      agent = Farscape::Agent.new(entry_point)
+      resources = agent.enter
+
+      expect(resources.attributes).to eq({})  # TODO: Make Crichton more flexible with Entry Points
+      expect(resources.transitions.keys).to eq(["drds"]) # => TODO: Add leviathans to Moya
+    end
+  end
+
+  describe "A Hypermedia Discovery Service" do
+    # TODO: Fix Documentation to reflect this
+
+    it 'follow your nose entry to select a registered resource' do
+      agent = Farscape::Agent.new(entry_point)
+      resources = agent.enter
+
+      expect(resources.transitions['drds'].invoke).to be_a Farscape::RepresentorAgent
+    end
+
+    it 'immediately loading a discoverable resource if known to be registered in the service a priori.' do
+      agent = Farscape::Agent.new
+      resources = agent.enter(entry_point)
+
+      expect(resources.transitions['drds'].invoke).to be_a Farscape::RepresentorAgent
+    end
+
+    it 'throws an error on an unknown resource' do
+      agent = Farscape::Agent.new
+
+      expect{ agent.enter }.to raise_error(RuntimeError) # TODO: Create Exact Error Interface for Farscape
+    end
+
+  end
+
+  context "API Interaction" do
+
+    let(:agent) { Farscape::Agent.new(entry_point) }
+    let(:drds) { agent.enter.transitions['drds'].invoke { |req| req.parameters = can_do_hash } }
+
+    describe "Load a Resource" do
+      it 'can load a resource' do
+        resources = agent.enter
+        drds_transition = resources.transitions['drds']
+        drds_resource = drds_transition.invoke { |req| req.parameters = can_do_hash }
+
+        expect(drds_resource.transitions['self'].uri).to eq(drds.transitions['self'].uri)
+      end
+    end
+
+    describe "A Representor Agent" do
+      it "Allows retrieving Response Header Information" do
+        resources = agent.enter
+        drds = resources.drds
+        expect(drds.response.status).to eq(200)
+      end
+    end
+
+    describe "Reload A Resource" do
+      it "can reload a resource" do
+        self_transition = drds.transitions['self']
+        reloaded_drds = self_transition.invoke
+
+        expect(reloaded_drds.to_hash).to eq(drds.to_hash)
+      end
+    end
+
+    describe "When using classmethods to refence API elements" do
+      context "When following unsafe transitions" do
+        it "can follow safe transitions" do
+          agent = Farscape::Agent.new
+          resources = agent.enter(entry_point)
+          expect(resources.drds).to be_a Farscape::RepresentorAgent
+        end
+        it "requires an ! on unsafe transitions" do
+          agent = Farscape::Agent.new
+          resources = agent.enter(entry_point)
+          expect { resources.drds { |req| req.parameters = can_do_hash }.create }.to raise_error(NoMethodError) # TODO: Create Exact Error Interface for Farscape
+
+          drones = resources.drds { |req| req.parameters = can_do_hash }
+          begin
+            drones.create!
+            raise StandardError
+          rescue Farscape::Exceptions::UnprocessableEntity => e
+            expect(e.representor.transitions.keys).to include('help')
+          end
+        end
+
+        it "can be called with arguments" do
+          agent = Farscape::Agent.new
+          resources = agent.enter(entry_point)
+          expect(resources.drds.search(status: 'active').items.all? { |h| h.status }).to be true
+        end
+
+        it "can take a block" do
+          agent = Farscape::Agent.new
+          resources = agent.enter(entry_point)
+          resources.drds { |req| req.parameters = can_do_hash }
+          resources.drds.search { |req| req.parameters = can_do_hash }
+
+          expect(resources.drds.search(status: 'activated') { |req| req.parameters = can_do_hash }.transitions.keys).to include('create')
+          expect(resources.drds.search(status: 'activated') { |req| req.parameters = can_do_hash }.items.all? { |h| h.status == 'activated' }).to be true
+        end
+      end
+      context "When Referencing Attributes" do
+        it "can reference attributes" do
+          resource = agent.enter(entry_point).drds(can_do_hash).items.first
+          expect(resource.status).to eq(drds.embedded['items'].first.attributes['status'])
+        end
+        it "is read only" do
+          resource = agent.enter(entry_point).drds(can_do_hash).items.first
+          expect {resource.status = 'ninja food'}.to raise_error(NoMethodError)
+        end
+        it "throws on unknown" do
+          resource = agent.enter(entry_point).drds(can_do_hash).items.find { |drd| drd.status == 'deactivated' }
+          expect {resource.ninja}.to raise_error(NoMethodError)
+          expect {resource.self {|r| r.parameters = {'conditions' => 'can_do_anything'}}.activate!.activate!}.to raise_error(NoMethodError, /undefined method `activate!' for/)
+        end
+      end
+      context "When handling namespace collisions" do
+        it "can be converted to a safe representor and back" do
+          resource = agent.safe.enter.transitions['drds'].invoke { |req| req.parameters = can_do_hash }.embedded['items'].first
+          expect {resource.status}.to raise_error(NoMethodError)
+
+          resource = resource.unsafe
+          expect(resource.status).to eq(drds.embedded['items'].first.attributes['status'])
+
+          resource = resource.safe
+          expect {resource.status}.to raise_error(NoMethodError)
+        end
+      end
+
+      context "When using Alternate Interface" do
+        it "can change to and from a safe representor" do
+           drds = agent.enter(entry_point).drds(can_do_hash)
+           safely = drds.safe
+           unsafely = safely.unsafe
+           expect(safely.attributes.keys).to eq(unsafely.attributes.keys) # TODO: Representor should support descriptor equality
+           expect(safely.transitions.keys).to eq(unsafely.transitions.keys) # TODO: Representor should support descriptor equality
+           expect(safely.embedded.keys).to eq(unsafely.embedded.keys) # TODO: Representor should support descriptor equality
+        end
+      end
+
+    end
+
+    context "Explore" do
+      describe "Apply Query Parameters" do
+        it 'allows Application of Query Parameters' do
+          search_transition = drds.transitions['search']
+
+          # TODO: Diverges from Doc due to doc not considering Field objects
+          expect(search_transition.parameters.map { |p| p.name } ).to eq(['status'])
+
+          filtered_drds = search_transition.invoke do |builder|
+            builder.parameters = { status: 'activated' }
+          end
+
+          expect(filtered_drds.transitions['items']).to_not be(nil)
+        end
+      end
+
+      describe "Transform Resource State" do
+        it 'allows Transformation of Resource State' do
+          embedded_drd_items = drds.embedded # TODO: Orig "drds.items" Looks like New Interface
+          drd = embedded_drd_items['items'].first
+
+          expect(drd.attributes.keys).to eq(["id", "name", "status", "old_status", "kind", "size", "leviathan_uuid", "created_at", "location", "location_detail", "destroyed_status"])
+          expect(drd.transitions.keys).to include("self", "update", "delete", "leviathan", "profile", "type", "help")
+
+          status = drd.attributes['status']
+          action = status == 'activated' ? 'deactivate' : 'activate'
+          deactivate_transition = drd.transitions[action]
+
+          # TODO: Not sure what to do about empty response bodies
+          # deactivated_drd = deactivate_transition.invoke
+          deactivate_transition.invoke { |req| req.parameters = can_do_hash }
+          deactivated_drd = drd.transitions['self'].invoke { |req| req.parameters = can_do_hash }
+
+          expect(deactivated_drd.attributes['status']).to_not eq(status)
+          expect(deactivated_drd.attributes.keys).to eq(drd.attributes.keys)
+          expect(deactivated_drd.transitions.keys).to_not eq(drd.transitions.keys)
+        end
+      end
+
+      describe "Transform Application State" do
+        xit 'allows Transformation of Application State' do
+# TODO: Make Moya serve Leviathan as a separate service
+#           leviathan_transition = deactivated_drd.transitions['leviathan']
+#
+#           leviathan = leviathan_transition.invoke
+#           leviathan.attributes # => { name: 'Elack' }
+#           leviathan.transitions # => ['self', 'drds']
+#
+#           # Use Attributes
+#           create_transition = drds.transitions['create']
+#           create_transition.attributes # => ['name']
+#
+#           new_drd = create_transition.invoke do |builder|
+#             builder.attributes = { name: 'Pike' }
+#           end
+#
+#           new_drd.attributes # => { name: 'Pike' }
+#           new_drd.transitions # => ['self', 'edit', 'delete', 'deactivate', 'leviathan']
+        end
+      end
+    end
+  end
+end

data/spec/lib/farscape/integration/representor_spec.rb

@@ -0,0 +1,36 @@
+require 'spec_helper'
+
+describe Farscape::RepresentorAgent do
+  let(:entry_point) { "http://localhost:#{RAILS_PORT}"}
+
+  describe '#transitions' do
+    it 'returns a hash of tranistions' do
+      representor = Farscape::Agent.new(entry_point).enter
+      expect(representor.transitions["drds"].uri).to eq("http://localhost:1234/drds")
+    end
+
+    it 'responds to keys appropriately' do
+      representor = Farscape::Agent.new(entry_point).enter
+      expect(representor.transitions["drds"].invoke.transitions.keys).to eq(["self", "search", "items", "profile", "type", "help"])
+    end
+   end
+
+   describe "#invoke" do
+      it 'returns a representor' do
+        representor = Farscape::Agent.new(entry_point).enter
+         expect(representor.transitions["drds"].invoke).to be_a Farscape::RepresentorAgent
+      end
+
+      it 'can reload a resource' do
+        representor = Farscape::Agent.new(entry_point).enter.transitions["drds"].invoke
+        expect(representor.transitions["self"].invoke.to_hash).to eq(representor.to_hash)
+      end
+   end
+
+  describe '#attributes' do
+    it 'has readable attributes' do
+      representor = Farscape::Agent.new(entry_point).enter
+      expect(representor.transitions["drds"].invoke.attributes["total_count"]).to be > 4
+    end
+  end
+end