fmrest 0.7.1 → 0.11.0

data/lib/fmrest/errors.rb

@@ -21,6 +21,8 @@ module FmRest
   class APIError::NoMatchingRecordsError < APIError::ParameterError; end
   class APIError::ValidationError < APIError; end      # error codes 500..599
   class APIError::SystemError < APIError; end          # error codes 800..899
+  class APIError::InvalidToken < APIError; end         # error code 952
+  class APIError::MaximumDataAPICallsExceeded < APIError; end # error code 953
   class APIError::ScriptError < APIError; end          # error codes 1200..1299
   class APIError::ODBCError < APIError; end            # error codes 1400..1499
 

data/lib/fmrest/spyke/base.rb

@@ -8,6 +8,8 @@ module FmRest
 
     class << self
       def Base(config = nil)
+        warn "[DEPRECATION] Inheriting from `FmRest::Spyke::Base(config)` is deprecated and will be removed, inherit from `FmRest::Spyke::Base` (without arguments) and use `fmrest_config=` instead"
+
         if config
           return Class.new(::FmRest::Spyke::Base) do
                    self.fmrest_config = config

data/lib/fmrest/spyke/model.rb

@@ -7,6 +7,7 @@ require "fmrest/spyke/model/serialization"
 require "fmrest/spyke/model/associations"
 require "fmrest/spyke/model/orm"
 require "fmrest/spyke/model/container_fields"
+require "fmrest/spyke/model/global_fields"
 require "fmrest/spyke/model/http"
 require "fmrest/spyke/model/auth"
 
@@ -22,6 +23,7 @@ module FmRest
       include Associations
       include Orm
       include ContainerFields
+      include GlobalFields
       include Http
       include Auth
 

data/lib/fmrest/spyke/model/auth.rb

@@ -28,6 +28,14 @@ module FmRest
           rescue FmRest::V1::TokenSession::NoSessionTokenSet
             false
           end
+
+          def request_auth_token
+            FmRest::V1.request_auth_token(FmRest::V1.auth_connection(fmrest_config))
+          end
+
+          def request_auth_token!
+            FmRest::V1.request_auth_token!(FmRest::V1.auth_connection(fmrest_config))
+          end
         end
       end
     end

data/lib/fmrest/spyke/model/connection.rb

@@ -4,19 +4,70 @@ module FmRest
   module Spyke
     module Model
       module Connection
-        extend ::ActiveSupport::Concern
+        extend ActiveSupport::Concern
 
         included do
-          class_attribute :fmrest_config, instance_accessor: false, instance_predicate: false
-
           class_attribute :faraday_block, instance_accessor: false, instance_predicate: false
           class << self; private :faraday_block, :faraday_block=; end
 
-          # FM Data API expects PATCH for updates (Spyke's default was PUT)
+          # FM Data API expects PATCH for updates (Spyke's default is PUT)
           self.callback_methods = { create: :post, update: :patch }.freeze
         end
 
         class_methods do
+          def fmrest_config
+            if fmrest_config_overlay
+              return FmRest.default_connection_settings.merge(fmrest_config_overlay, skip_validation: true)
+            end
+
+            FmRest.default_connection_settings
+          end
+
+          # Behaves similar to ActiveSupport's class_attribute, redefining the
+          # reader method so it can be inherited and overwritten in subclasses
+          #
+          def fmrest_config=(settings)
+            settings = ConnectionSettings.new(settings, skip_validation: true)
+
+            redefine_singleton_method(:fmrest_config) do
+              overlay = fmrest_config_overlay
+              return settings.merge(overlay, skip_validation: true) if overlay
+              settings
+            end
+          end
+
+          # Allows overwriting some connection settings in a thread-local
+          # manner. Useful in the use case where you want to connect to the
+          # same database using different accounts (e.g. credentials provided
+          # by users in a web app context)
+          #
+          def fmrest_config_overlay=(settings)
+            Thread.current[fmrest_config_overlay_key] = settings
+          end
+
+          def fmrest_config_overlay
+            Thread.current[fmrest_config_overlay_key] || begin
+              superclass.fmrest_config_overlay
+            rescue NoMethodError
+              nil
+            end
+          end
+
+          def clear_fmrest_config_overlay
+            Thread.current[fmrest_config_overlay_key] = nil
+          end
+
+          def with_overlay(settings, &block)
+            Fiber.new do
+              begin
+                self.fmrest_config_overlay = settings
+                yield
+              ensure
+                self.clear_fmrest_config_overlay
+              end
+            end.resume
+          end
+
           def connection
             super || fmrest_connection
           end
@@ -38,26 +89,45 @@ module FmRest
           private
 
           def fmrest_connection
-            @fmrest_connection ||=
-              begin
-                config = fmrest_config || FmRest.default_connection_settings
+            memoize = false
+
+            # Don't memoize the connection if there's an overlay, since
+            # overlays are thread-local and so should be the connection
+            unless fmrest_config_overlay
+              return @fmrest_connection if @fmrest_connection
+              memoize = true
+            end
 
-                FmRest::V1.build_connection(config) do |conn|
-                  faraday_block.call(conn) if faraday_block
+            config = ConnectionSettings.wrap(fmrest_config)
 
-                  # Pass the class to SpykeFormatter's initializer so it can have
-                  # access to extra context defined in the model, e.g. a portal
-                  # where name of the portal and the attributes prefix don't match
-                  # and need to be specified as options to `portal`
-                  conn.use FmRest::Spyke::SpykeFormatter, self
+            connection =
+              FmRest::V1.build_connection(config) do |conn|
+                faraday_block.call(conn) if faraday_block
 
-                  conn.use FmRest::V1::TypeCoercer, config
+                # Pass the class to SpykeFormatter's initializer so it can have
+                # access to extra context defined in the model, e.g. a portal
+                # where name of the portal and the attributes prefix don't match
+                # and need to be specified as options to `portal`
+                conn.use FmRest::Spyke::SpykeFormatter, self
 
-                  # FmRest::Spyke::JsonParse expects symbol keys
-                  conn.response :json, parser_options: { symbolize_names: true }
-                end
+                conn.use FmRest::V1::TypeCoercer, config
+
+                # FmRest::Spyke::JsonParse expects symbol keys
+                conn.response :json, parser_options: { symbolize_names: true }
               end
+
+            @fmrest_connection = connection if memoize
+
+            connection
           end
+
+          def fmrest_config_overlay_key
+            :"#{object_id}.fmrest_config_overlay"
+          end
+        end
+
+        def fmrest_config
+          self.class.fmrest_config
         end
       end
     end

data/lib/fmrest/spyke/model/global_fields.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    module Model
+      module GlobalFields
+        extend ::ActiveSupport::Concern
+
+        FULLY_QUALIFIED_FIELD_NAME_MATCHER = /\A[^:]+::[^:]+\Z/.freeze
+
+        class_methods do
+          def set_globals(values_hash)
+            connection.patch(FmRest::V1.globals_path, {
+              globalFields: normalize_globals_hash(values_hash)
+            })
+          end
+
+          private
+
+          def normalize_globals_hash(hash)
+            hash.each_with_object({}) do |(k, v), normalized|
+              if v.kind_of?(Hash)
+                v.each do |k2, v2|
+                  normalized["#{k}::#{k2}"] = v2
+                end
+                next
+              end
+
+              unless FULLY_QUALIFIED_FIELD_NAME_MATCHER === k.to_s
+                raise ArgumentError, "global fields must be given in fully qualified format (table name::field name)"
+              end
+
+              normalized[k] = v
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fmrest/spyke/model/orm.rb

@@ -24,7 +24,8 @@ module FmRest
           # Methods delegated to FmRest::Spyke::Relation
           delegate :limit, :offset, :sort, :order, :query, :omit, :portal,
                    :portals, :includes, :with_all_portals, :without_portals,
-                   :script, :find_one, :find_some, to: :all
+                   :script, :find_one, :first, :any, :find_some,
+                   :find_in_batches, :find_each, to: :all
 
           def all
             # Use FmRest's Relation instead of Spyke's vanilla one

data/lib/fmrest/spyke/model/serialization.rb

@@ -4,8 +4,8 @@ module FmRest
   module Spyke
     module Model
       module Serialization
-        FM_DATE_FORMAT = "%m/%d/%Y".freeze
-        FM_DATETIME_FORMAT = "#{FM_DATE_FORMAT} %H:%M:%S".freeze
+        FM_DATE_FORMAT = "%m/%d/%Y"
+        FM_DATETIME_FORMAT = "#{FM_DATE_FORMAT} %H:%M:%S"
 
         # Override Spyke's to_params to return FM Data API's expected JSON
         # format, and including only modified fields
@@ -63,9 +63,9 @@ module FmRest
         def serialize_values!(params)
           params.transform_values! do |value|
             case value
-            when DateTime, Time
-              value.strftime(FM_DATETIME_FORMAT)
-            when Date
+            when DateTime, Time, FmRest::StringDateTime
+              convert_datetime_timezone(value.to_datetime).strftime(FM_DATETIME_FORMAT)
+            when Date, FmRest::StringDate
               value.strftime(FM_DATE_FORMAT)
             else
               value
@@ -74,6 +74,17 @@ module FmRest
 
           params
         end
+
+        def convert_datetime_timezone(dt)
+          case fmrest_config.timezone
+          when :utc, "utc"
+            dt.new_offset(0)
+          when :local, "local"
+            dt.new_offset(FmRest::V1.local_offset_for_datetime(dt))
+          when nil
+            dt
+          end
+        end
       end
     end
   end

data/lib/fmrest/spyke/relation.rb

@@ -190,6 +190,79 @@ module FmRest
       rescue ::Spyke::ConnectionError => error
         fallback_or_reraise(error, default: nil)
       end
+      alias_method :first, :find_one
+      alias_method :any, :find_one
+
+      # Yields each batch of records that was found by the find options.
+      #
+      # NOTE: By its nature, batch processing is subject to race conditions if
+      # other processes are modifying the database
+      #
+      # @param batch_size [Integer] Specifies the size of the batch.
+      # @return [Enumerator] if called without a block.
+      def find_in_batches(batch_size: 1000)
+        unless block_given?
+          return to_enum(:find_in_batches, batch_size: batch_size) do
+            total = limit(1).find_some.metadata.data_info.found_count
+            (total - 1).div(batch_size) + 1
+          end
+        end
+
+        offset = 1 # DAPI offset is 1-based
+
+        loop do
+          relation = offset(offset).limit(batch_size)
+
+          records = relation.find_some
+
+          yield records if records.length > 0
+
+          break if records.length < batch_size
+
+          # Save one iteration if the total is a multiple of batch_size
+          if found_count = records.metadata.data_info && records.metadata.data_info.found_count
+            break if found_count == (offset - 1) + batch_size
+          end
+
+          offset += batch_size
+        end
+      end
+
+      # Looping through a collection of records from the database (using the
+      # #all method, for example) is very inefficient since it will fetch and
+      # instantiate all the objects at once.
+      #
+      # In that case, batch processing methods allow you to work with the
+      # records in batches, thereby greatly reducing memory consumption and be
+      # lighter on the Data API server.
+      #
+      # The find_each method uses #find_in_batches with a batch size of 1000
+      # (or as specified by the :batch_size option).
+      #
+      # NOTE: By its nature, batch processing is subject to race conditions if
+      # other processes are modifying the database
+      #
+      # @param (see #find_in_batches)
+      # @example
+      #   Person.find_each do |person|
+      #     person.greet
+      #   end
+      #
+      #   Person.query(name: "==Mitch").find_each do |person|
+      #     person.say_hi
+      #   end
+      # @return (see #find_in_batches)
+      def find_each(batch_size: 1000)
+        unless block_given?
+          return to_enum(:find_each, batch_size: batch_size) do
+            limit(1).find_some.metadata.data_info.found_count
+          end
+        end
+
+        find_in_batches(batch_size: batch_size) do |records|
+          records.each { |r| yield r }
+        end
+      end
 
       protected
 

data/lib/fmrest/spyke/spyke_formatter.rb

@@ -1,9 +1,21 @@
 # frozen_string_literal: true
 
 require "json"
+require "ostruct"
 
 module FmRest
   module Spyke
+    # Metadata class to be passed to Spyke::Collection#metadata
+    class Metadata < Struct.new(:messages, :script, :data_info)
+      alias_method :scripts, :script
+    end
+
+    class DataInfo < OpenStruct
+      def total_record_count; totalRecordCount; end
+      def found_count; foundCount; end
+      def returned_count; returnedCount; end
+    end
+
     # Response Faraday middleware for converting FM API's response JSON into
     # Spyke's expected format
     class SpykeFormatter < ::Faraday::Response::Middleware
@@ -77,36 +89,61 @@ module FmRest
 
       # @param json [Hash]
       # @param include_errors [Boolean]
-      # @return [Hash] the skeleton structure for a Spyke-formatted response
+      # @return [FmRest::Spyke::Metadata] the skeleton structure for a
+      #   Spyke-formatted response
       def build_base_hash(json, include_errors = false)
         {
-          metadata: { messages: json[:messages] }.merge(script: prepare_script_results(json).presence),
-          errors:   include_errors ? prepare_errors(json) : {}
+          metadata: Metadata.new(
+            prepare_messages(json),
+            prepare_script_results(json),
+            prepare_data_info(json)
+          ).freeze,
+          errors: include_errors ? prepare_errors(json) : {}
         }
       end
 
       # @param json [Hash]
-      # @return [Hash] the script(s) execution results for Spyke metadata format
+      # @return [Array<OpenStruct>] the skeleton structure for a
+      #   Spyke-formatted response
+      def prepare_messages(json)
+        return [] unless json[:messages]
+        json[:messages].map { |m| OpenStruct.new(m).freeze }.freeze
+      end
+
+      # @param json [Hash]
+      # @return [OpenStruct] the script(s) execution results for Spyke metadata
+      #   format
       def prepare_script_results(json)
         results = {}
 
         [:prerequest, :presort].each do |s|
           if json[:response][:"scriptError.#{s}"]
-            results[s] = {
+            results[s] = OpenStruct.new(
               result: json[:response][:"scriptResult.#{s}"],
               error:  json[:response][:"scriptError.#{s}"]
-            }
+            ).freeze
           end
         end
 
         if json[:response][:scriptError]
-          results[:after] = {
+          results[:after] = OpenStruct.new(
             result: json[:response][:scriptResult],
             error:  json[:response][:scriptError]
-          }
+          ).freeze
         end
 
-        results
+        results.present? ? OpenStruct.new(results).freeze : nil
+      end
+
+      # @param json [Hash]
+      # @return [OpenStruct] the script(s) execution results for
+      #   Spyke metadata format
+      def prepare_data_info(json)
+        data_info = json[:response] && json[:response][:dataInfo]
+
+        return nil unless data_info.present?
+
+        DataInfo.new(data_info).freeze
       end
 
       # @param json [Hash]