frodo 0.10.0

data/lib/frodo/concerns/api.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'uri'
+require 'frodo/concerns/verbs'
+
+module Frodo
+  module Concerns
+    module API
+      extend Frodo::Concerns::Verbs
+
+      # Public: Helper methods for performing arbitrary actions against the API using
+      # various HTTP verbs.
+      #
+      # Examples
+      #
+      #   # Perform a get request
+      #   client.get '/api/data/v9.1/leads'
+      #   client.api_get 'leads'
+      #
+      #   # Perform a post request
+      #   client.post '/api/data/v9.1/leads', { ... }
+      #   client.api_post 'leads', { ... }
+      #
+      #   # Perform a put request
+      #   client.put '/api/data/v9.1/leads(073ca9c8-2a41-e911-a81d-000d3a1d5a0b)', { ... }
+      #   client.api_put 'leads(073ca9c8-2a41-e911-a81d-000d3a1d5a0b)', { ... }
+      #
+      #   # Perform a delete request
+      #   client.delete '/api/data/v9.1/leads(073ca9c8-2a41-e911-a81d-000d3a1d5a0b)'
+      #   client.api_delete 'leads(073ca9c8-2a41-e911-a81d-000d3a1d5a0b)'
+      #
+      # Returns the Faraday::Response.
+      define_verbs :get, :post, :put, :delete, :patch, :head
+
+      # Public: Return the metadata XML schema for the service
+      #
+      # Returns [String]
+      def metadata
+        api_get("$metadata").body
+      end
+
+      # Public: Execute a query and returns the result.
+      #
+      # Query can be the url_chunk per the OData V4 spec or
+      # a Frodo::Query. The latter being preferred
+      #
+      # Examples
+      #
+      #   # Find the names of all Accounts
+      #   client.query("leads?$filter=firstname eq 'yo'")
+      #
+      # or
+      #
+      #   query = client.service['leads'].query
+      #   query.where("firstname eq 'yo'")
+      #   client.query(query)
+      #
+      # Returns a list of Frodo::Entity
+      def query(query)
+        url_chunk, entity_set = if query.is_a?(Frodo::Query)
+                      [query.to_s, query.entity_set.name]
+                    else
+                      [query]
+                    end
+
+        body = api_get(url_chunk).body
+
+        # if manual query as a string we detect the set on the response
+        entity_set = body['@odata.context'].split('#')[-1] if entity_set.nil?
+        build_entity(entity_set, body)
+      end
+
+      # Public: Insert a new record.
+      #
+      # entity_set - The set the entity belongs to
+      # attrs   - Hash of attributes to set on the new record.
+      #
+      # Examples
+      #
+      #   # Add a new lead
+      #   client.create('leads', {"firstname" =>'Bob'})
+      #   # => '073ca9c8-2a41-e911-a81d-000d3a1d5a0b'
+      #
+      # Returns the primary key value of the newly created entity.
+      # Returns false if something bad happens.
+      def create(*args)
+        create!(*args)
+      rescue *exceptions
+        false
+      end
+      alias insert create
+
+      # Public: Insert a new record.
+      #
+      # entity_set - The set the entity belongs to
+      # attrs   - Hash of attributes to set on the new record.
+      #
+      # Examples
+      #
+      #   # Add a new lead
+      #   client.create!('leads', {"firstname" =>'Bob'})
+      #   # => '073ca9c8-2a41-e911-a81d-000d3a1d5a0b'
+      #
+      # Returns the primary key value of the newly created entity.
+      # Raises exceptions if an error is returned from Dynamics.
+      def create!(entity_set, attrs)
+        entity = service[entity_set].new_entity(attrs)
+        url_chunk = to_url_chunk(entity)
+        url = api_post(url_chunk, attrs).headers['odata-entityid']
+        id = url.match(/\(.+\)/)[0]
+      end
+      alias insert! create!
+
+      # Public: Update a record.
+      #
+      # entity_set - The set the entity belongs to
+      # attrs   - Hash of attributes to set on the record.
+      #
+      # Examples
+      #
+      #   # Update the lead with id '073ca9c8-2a41-e911-a81d-000d3a1d5a0b'
+      #   client.update('leads', "leadid": '073ca9c8-2a41-e911-a81d-000d3a1d5a0b', Name: 'Whizbang Corp')
+      #
+      # Returns true if the entity was successfully updated.
+      # Returns false if there was an error.
+      def update(*args)
+        update!(*args)
+      rescue *exceptions
+        false
+      end
+
+      # Public: Update a record.
+      #
+      # entity_set - The set the entity belongs to
+      # attrs   - Hash of attributes to set on the record.
+      #
+      # Examples
+      #
+      #   # Update the leads with id '073ca9c8-2a41-e911-a81d-000d3a1d5a0b'
+      #   client.update!('leads', 'leadid' => '073ca9c8-2a41-e911-a81d-000d3a1d5a0b', "firstname" => 'Whizbang Corp')
+      #
+      # Returns true if the entity was successfully updated.
+      # Raises an exception if an error is returned from Dynamics.
+      def update!(entity_set, attrs)
+        entity = service[entity_set].new_entity(attrs)
+        url_chunk = to_url_chunk(entity)
+
+        raise ArgumentError, 'ID field missing from provided attributes' if entity.is_new?
+
+        api_patch url_chunk, attrs
+        true
+      end
+
+      # Public: Delete a record.
+      #
+      # entity_set - The set the entity belongs to
+      # id      - The Dynamics primary key ID of the record.
+      #
+      # Examples
+      #
+      #   # Delete the lead with id  "073ca9c8-2a41-e911-a81d-000d3a1d5a0b"
+      #   client.destroy('leads',  "073ca9c8-2a41-e911-a81d-000d3a1d5a0b")
+      #
+      # Returns true if the entity was successfully deleted.
+      # Returns false if an error is returned from Dynamics.
+      def destroy(*args)
+        destroy!(*args)
+      rescue *exceptions
+        false
+      end
+
+      # Public: Delete a record.
+      #
+      # entity_set - The set the entity belongs to
+      # id      - The Dynamics primary key ID of the record.
+      #
+      # Examples
+      #
+      #   # Delete the lead with id  "073ca9c8-2a41-e911-a81d-000d3a1d5a0b"
+      #   client.destroy!('leads',  "073ca9c8-2a41-e911-a81d-000d3a1d5a0b")
+      #
+      # Returns true of the entity was successfully deleted.
+      # Raises an exception if an error is returned from Dynamics.
+      def destroy!(entity_set, id)
+        query = service[entity_set].query
+        url_chunk = query.find(id).to_s
+        api_delete url_chunk
+        true
+      end
+
+      # Public: Finds a single record and returns all fields.
+      #
+      # entity_set - The set the entity belongs to
+      # id      - The id of the record. If field is specified, id should be the id
+      #           of the external field.
+      #
+      # Returns the Entity record.
+      def find(entity_set, id)
+        query = service[entity_set].query
+        url_chunk = query.find(id)
+
+        body = api_get(url_chunk).body
+        build_entity(entity_set, body)
+      end
+
+      # Public: Finds a single record and returns select fields.
+      #
+      # entity_set - The set the entity belongs to
+      # id      - The id of the record. If field is specified, id should be the id
+      #           of the external field.
+      # fields  - A String array denoting the fields to select.  If nil or empty array
+      #           is passed, all fields are selected.
+      def select(entity_set, id, fields)
+        query = service[entity_set].query
+
+        fields.each{|field| query.select(field)}
+        url_chunk = query.find(id)
+
+        body = api_get(url_chunk).body
+        build_entity(entity_set, body)
+      end
+
+      # Public: Count the entity set or for the query passed
+      #
+      # entity_set or query  - A  String or a Frodo::Query. If String is passed,
+      #                         all entities for the set are counted.
+      def count(query)
+        url_chunk = if query.is_a?(Frodo::Query)
+                      query.include_count
+                      query.to_s
+                    else
+                      service[query].query.count
+                    end
+
+        body = api_get(url_chunk).body
+
+        if query.is_a?(Frodo::Query)
+          body['@odata.count']
+        else
+          # Some servers (*cough* Microsoft *cough*) seem to return
+          # extraneous characters in the response.
+          # I found out that the _\xef\xbb\xbf  contains probably invisible junk characters
+          # called the Unicode BOM (short name for: byte order mark).
+          body.scan(/\d+/).first.to_i
+        end
+      end
+
+      private
+
+      # Internal: Returns a path to an api endpoint based on configured client
+      #
+      # Examples
+      #
+      #   api_path('leads')
+      #   # => '/leads'
+      def api_path(path)
+        "#{options[:base_path]}/#{path}" || "/#{path}"
+      end
+
+      def build_entity(entity_set, data)
+        entity_options = service[entity_set].entity_options
+        single_entity?(data) ? parse_entity(data, entity_options) : parse_entities(data, entity_options)
+      end
+
+      def single_entity?(body)
+        body['@odata.context'] =~ /\$entity$/
+      end
+
+      def parse_entity(entity_json, entity_options)
+        Frodo::Entity.from_json(entity_json, entity_options)
+      end
+
+      def parse_entities(body, entity_options)
+        body['value'].map  do |entity_data|
+          Frodo::Entity.from_json(entity_data, entity_options)
+        end
+      end
+
+      def to_url_chunk(entity)
+        primary_key = entity.get_property(entity.primary_key).url_value
+        set = entity.entity_set.name
+        entity.is_new? ? set : "#{set}(#{primary_key})"
+      end
+
+      # Internal: Errors that should be rescued from in non-bang methods
+      def exceptions
+        [Faraday::Error::ClientError]
+      end
+    end
+  end
+end

data/lib/frodo/concerns/authentication.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Frodo
+  module Concerns
+    module Authentication
+      # Public: Force an authentication
+      def authenticate!
+        unless authentication_middleware
+          raise AuthenticationError, 'No authentication middleware present'
+        end
+
+        middleware = authentication_middleware.new nil, self, options
+        middleware.authenticate!
+      end
+
+      # Internal: Determines what middleware will be used based on the options provided
+      def authentication_middleware
+        if oauth_refresh?
+          Frodo::Middleware::Authentication::Token
+        end
+      end
+
+      # Internal: Returns true if oauth token refresh flow should be used for
+      # authentication.
+      def oauth_refresh?
+        options[:refresh_token] &&
+          options[:client_id] &&
+          options[:client_secret]
+      end
+    end
+  end
+end

data/lib/frodo/concerns/base.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Frodo
+  module Concerns
+    module Base
+      attr_reader :options
+
+      MIME_TYPES = {
+        json:  'application/json'
+      }
+
+      # Public: Creates a new client instance
+      #
+      # opts - A hash of options to be passed in (default: {}).
+      #
+      #        :oauth_token             - The String oauth access token to authenticate
+      #                                   API calls (required unless password
+      #                                   authentication is used).
+      #        :refresh_token           - The String refresh token to obtain fresh
+      #                                   OAuth access tokens (required if oauth
+      #                                   authentication is used).
+      #        :instance_url            - The String base url for all api requests
+      #                                   (required if oauth authentication is used).
+      #
+      #        :client_id               - The oauth client id to use. Needed for both
+      #                                   password and oauth authentication
+      #        :client_secret           - The oauth client secret to use.
+      #
+      #        :host                    - The String hostname to use during
+      #                                   authentication requests
+      #                                   (default: 'login.microsoftonline.com').
+      #
+      #        :base_path              - The base path for the REST api. (default: '/')
+      #
+      #        :authentication_retries  - The number of times that client
+      #                                   should attempt to reauthenticate
+      #                                   before raising an exception (default: 3).
+      #
+      #        :compress                - Set to true to have Dynamics compress the
+      #                                   response (default: false).
+      #        :raw_json                 - Set to true to skip the conversion of
+      #                                   Entities responses (default: false).
+      #        :timeout                 - Faraday connection request read/open timeout.
+      #                                   (default: nil).
+      #
+      #        :proxy_uri               - Proxy URI: 'http://proxy.example.com:port' or
+      #                                   'http://user@pass:proxy.example.com:port'
+      #
+      #        :authentication_callback - A Proc that is called with the response body
+      #                                   after a successful authentication.
+      #
+      #        :request_headers         - A hash containing custom headers that will be
+      #                                   appended to each request
+
+      def initialize(opts = {})
+        raise ArgumentError, 'Please specify a hash of options' unless opts.is_a?(Hash)
+
+        # allow injecting the service for performance purpose such as
+        # when you have already a local schema
+        @service = opts.delete(:service)
+
+        @options = Hash[Frodo.configuration.options.map do |option|
+          [option, Frodo.configuration.send(option)]
+        end]
+
+        @options.merge! opts
+        yield builder if block_given?
+      end
+
+      def instance_url
+        authenticate! unless options[:instance_url]
+        options[:instance_url]
+      end
+
+      def service
+        @service ||= Frodo::Service.new(instance_url, strict: false, metadata_document: metadata)
+      end
+
+      def inspect
+        "#<#{self.class} @options=#{@options.inspect}>"
+      end
+    end
+  end
+end

data/lib/frodo/concerns/caching.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Frodo
+  module Concerns
+    module Caching
+      # Public: Runs the block with caching disabled.
+      #
+      # block - A query/describe/etc.
+      #
+      # Returns the result of the block
+      def without_caching
+        options[:use_cache] = false
+        yield
+      ensure
+        options.delete(:use_cache)
+      end
+
+      private
+
+      # Internal: Cache to use for the caching middleware
+      def cache
+        options[:cache]
+      end
+    end
+  end
+end

data/lib/frodo/concerns/connection.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Frodo
+  module Concerns
+    module Connection
+      # Public: The Faraday::Builder instance used for the middleware stack. This
+      # can be used to insert an custom middleware.
+      #
+      # Examples
+      #
+      #   # Add the instrumentation middleware for Rails.
+      #   client.middleware.use FaradayMiddleware::Instrumentation
+      #
+      # Returns the Faraday::Builder for the Faraday connection.
+      def middleware
+        connection.builder
+      end
+      alias builder middleware
+
+      private
+
+      # Internal: Internal faraday connection where all requests go through
+      def connection
+        @connection ||= Faraday.new(options[:instance_url],
+                                    connection_options) do |builder|
+
+          # Converts the request into JSON.
+          builder.request :json
+          # Handles reauthentication for 403 responses.
+          if authentication_middleware
+            builder.use authentication_middleware, self, options
+          end
+          # Sets the oauth token in the headers.
+          builder.use Frodo::Middleware::Authorization, self, options
+          # Ensures the instance url is set.
+          builder.use Frodo::Middleware::InstanceURL, self, options
+          # Caches GET requests.
+          builder.use Frodo::Middleware::Caching, cache, options if cache
+          # Follows 30x redirects.
+          builder.use FaradayMiddleware::FollowRedirects
+          # Raises errors for 40x responses.
+          builder.use Frodo::Middleware::RaiseError
+          # Parses returned JSON response into a hash.
+          builder.response :json, content_type: /\bjson$/
+          # Compress/Decompress the request/response
+          unless adapter == :httpclient
+            builder.use Frodo::Middleware::Gzip, self, options
+          end
+          # Inject OData headers into requests
+          builder.use Frodo::Middleware::OdataHeaders, self, options
+          # Inject custom headers into requests
+          builder.use Frodo::Middleware::CustomHeaders, self, options
+          # Log request/responses
+          if Frodo.log?
+            builder.use Frodo::Middleware::Logger,
+                        Frodo.configuration.logger,
+                        options
+          end
+
+          builder.adapter adapter
+        end
+      end
+
+      def adapter
+        options[:adapter]
+      end
+
+      # Internal: Faraday Connection options
+      def connection_options
+        { request: {
+            timeout: options[:timeout],
+            open_timeout: options[:timeout]
+          },
+          proxy: options[:proxy_uri],
+          ssl: options[:ssl] }
+      end
+    end
+  end
+end

data/lib/frodo/concerns/verbs.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Frodo
+  module Concerns
+    module Verbs
+      # Internal: Define methods to handle a verb.
+      #
+      # verbs - A list of verbs to define methods for.
+      #
+      # Examples
+      #
+      #   define_verbs :get, :post
+      #
+      # Returns nil.
+      def define_verbs(*verbs)
+        verbs.each do |verb|
+          define_verb(verb)
+          define_api_verb(verb)
+        end
+      end
+
+      # Internal: Defines a method to handle HTTP requests with the passed in
+      # verb.
+      #
+      # verb - Symbol name of the verb (e.g. :get).
+      #
+      # Examples
+      #
+      #   define_verb :get
+      #   # => get '/path/to/entity'
+      #
+      # Returns nil.
+      def define_verb(verb)
+        define_method verb do |*args, &block|
+          retries = options[:authentication_retries]
+          begin
+            connection.send(verb, *args, &block)
+          rescue Frodo::UnauthorizedError
+            if retries.positive?
+              retries -= 1
+              connection.url_prefix = options[:instance_url]
+              retry
+            end
+            raise
+          end
+        end
+      end
+
+      # Internal: Defines a method to handle HTTP requests with the passed in
+      # verb to a Dynamics api endpoint.
+      #
+      # verb - Symbol name of the verb (e.g. :get).
+      #
+      # Examples
+      #
+      #   define_api_verb :get
+      #   # => api_get 'entity_set'
+      #
+      # Returns nil.
+      def define_api_verb(verb)
+        define_method :"api_#{verb}" do |*args, &block|
+          args[0] = api_path(args[0])
+          send(verb, *args, &block)
+        end
+      end
+    end
+  end
+end