fmrest-spyke 0.13.0

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    module Model
+      module Auth
+        extend ::ActiveSupport::Concern
+
+        class_methods do
+          # Logs out the database session for this model (and other models
+          # using the same credentials).
+          #
+          # @raise [FmRest::V1::TokenSession::NoSessionTokenSet] if no session
+          #   token was set (and no request is sent).
+          def logout!
+            connection.delete(FmRest::V1.session_path("dummy-token"))
+          end
+
+          # Logs out the database session for this model (and other models
+          # using the same credentials). Unlike `logout!`, no exception is
+          # raised in case of missing session token.
+          #
+          # @return [Boolean] Whether the logout request was sent (it's only
+          #   sent if a session token was previously set)
+          def logout
+            logout!
+            true
+          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
+  end
+end

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    module Model
+      # This module provides methods for configuring the Farday connection for
+      # the model, as well as setting up the connection itself.
+      #
+      module Connection
+        extend ActiveSupport::Concern
+
+        included do
+          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 uses PUT by default)
+          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
+
+          # Sets the FileMaker connection settings for the model.
+          #
+          # Behaves similar to ActiveSupport's `class_attribute`, so it can be
+          # inherited and safely overwritten in subclasses.
+          #
+          # @param settings [Hash] The settings hash
+          #
+          def fmrest_config=(settings)
+            settings = ConnectionSettings.new(settings, skip_validation: true)
+
+            singleton_class.redefine_method(:fmrest_config) do
+              overlay = fmrest_config_overlay
+              return settings.merge(overlay, skip_validation: true) if overlay
+              settings
+            end
+          end
+
+          # Allows overriding 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).
+          #
+          # @param (see #fmrest_config=)
+          #
+          def fmrest_config_overlay=(settings)
+            Thread.current[fmrest_config_overlay_key] = settings
+          end
+
+          # @return [FmRest::ConnectionSettings] the connection settings
+          #   overlay if any is in use
+          #
+          def fmrest_config_overlay
+            Thread.current[fmrest_config_overlay_key] || begin
+              superclass.fmrest_config_overlay
+            rescue NoMethodError
+              nil
+            end
+          end
+
+          # Clears the connection settings overlay.
+          #
+          def clear_fmrest_config_overlay
+            Thread.current[fmrest_config_overlay_key] = nil
+          end
+
+          # Runs a block of code in the context of the given connection
+          # settings without affecting the connection settings outside said
+          # block.
+          #
+          # @param (see #fmrest_config=)
+          #
+          # @example
+          #   Honeybee.with_overlay(username: "...", password: "...") do
+          #     Honeybee.query(...)
+          #   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
+
+          # Spyke override -- Defaults to `fmrest_connection`
+          #
+          def connection
+            super || fmrest_connection
+          end
+
+          # Sets a block for injecting custom middleware into the Faraday
+          # connection.
+          #
+          # @example
+          #   class MyModel < FmRest::Spyke::Base
+          #     faraday do |conn|
+          #       # Set up a custom logger for the model
+          #       conn.response :logger, MyApp.logger, bodies: true
+          #     end
+          #   end
+          #
+          def faraday(&block)
+            self.faraday_block = block
+          end
+
+          private
+
+          def fmrest_connection
+            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
+
+            config = ConnectionSettings.wrap(fmrest_config)
+
+            connection =
+              FmRest::V1.build_connection(config) do |conn|
+                faraday_block.call(conn) if faraday_block
+
+                # 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
+
+                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
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "fmrest/spyke/container_field"
+
+module FmRest
+  module Spyke
+    module Model
+      # This module adds support for container fields.
+      #
+      module ContainerFields
+        extend ::ActiveSupport::Concern
+
+        class_methods do
+          # Defines a container field on the model.
+          #
+          # @param name [Symbol] the name of the container field
+          #
+          # @option options [String] :field_name (nil) the name of the container
+          #   field in the FileMaker layout (only needed if it doesn't match
+          #   the name given)
+          #
+          # @example
+          #   class Honeybee < FmRest::Spyke::Base
+          #     container :photo, field_name: "Beehive Photo ID"
+          #   end
+          #
+          def container(name, options = {})
+            field_name = options[:field_name] || name
+
+            define_method(name) do
+              @container_fields ||= {}
+              @container_fields[name.to_sym] ||= ContainerField.new(self, field_name)
+            end
+          end
+        end
+      end
+    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/http.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    module Model
+      module Http
+        extend ::ActiveSupport::Concern
+
+        class_methods do
+
+          # Override Spyke's request method to keep a thread-local copy of the
+          # last request's metadata, so that we can access things like script
+          # execution results after a save, etc.
+
+
+          # Spyke override -- Keeps metadata in thread-local class variable.
+          #
+          def request(*args)
+            super.tap do |r|
+              Thread.current[last_request_metadata_key] = r.metadata
+            end
+          end
+
+          def last_request_metadata(key: last_request_metadata_key)
+            Thread.current[key]
+          end
+
+          private
+
+          def last_request_metadata_key
+            "#{to_s}.last_request_metadata"
+          end
+        end
+      end
+
+      # Spyke override -- Uses `__record_id` for building the record URI.
+      #
+      def uri
+        ::Spyke::Path.new(@uri_template, fmrest_uri_attributes) if @uri_template
+      end
+
+      private
+
+      # Spyke override (private) -- Use `__record_id` instead of `id`
+      #
+      def resolve_path_from_action(action)
+        case action
+        when Symbol then uri.join(action)
+        when String then ::Spyke::Path.new(action, fmrest_uri_attributes)
+        else uri
+        end
+      end
+
+      def fmrest_uri_attributes
+        if persisted?
+          { __record_id: __record_id }
+        else
+          # NOTE: it seems silly to be calling attributes.slice(:__record_id)
+          # when the record is supposed to not have a record_id set (since
+          # persisted? is false here), but it makes sense in the context of how
+          # Spyke works:
+          #
+          # When calling Model.find(id), Spyke will internally create a scope
+          # with .where(primary_key => id) and call .find_one on it. Then,
+          # somewhere down the line Spyke creates a new empty instance of the
+          # current model class to get its .uri property (the one we're
+          # partially building through this method and which contains these URI
+          # attributes). When initializing a record Spyke first forcefully
+          # assigns the .where()-set attributes from the current scope onto
+          # that instance's attributes hash, which then leads us right here,
+          # where we might have __record_id assigned as a scope attribute:
+          attributes.slice(:__record_id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "fmrest/spyke/relation"
+require "fmrest/spyke/validation_error"
+
+module FmRest
+  module Spyke
+    module Model
+      # This module adds and extends various ORM features in Spyke models,
+      # including custom query methods, remote script execution and
+      # exception-raising persistence methods.
+      #
+      module Orm
+        extend ::ActiveSupport::Concern
+
+        included do
+          # Allow overriding FM's default limit (by default it's 100)
+          class_attribute :default_limit, instance_accessor: false, instance_predicate: false
+
+          class_attribute :default_sort, instance_accessor: false, instance_predicate: false
+
+          # Whether to raise an FmRest::APIError::NoMatchingRecordsError when a
+          # _find request has no results
+          class_attribute :raise_on_no_matching_records, instance_accessor: false, instance_predicate: false
+        end
+
+        class_methods do
+          # Methods delegated to `FmRest::Spyke::Relation`
+          delegate :limit, :offset, :sort, :order, :query, :omit, :portal,
+                   :portals, :includes, :with_all_portals, :without_portals,
+                   :script, :find_one, :first, :any, :find_some,
+                   :find_in_batches, :find_each, to: :all
+
+          # Spyke override -- Use FmRest's Relation instead of Spyke's vanilla
+          # one
+          #
+          def all
+            current_scope || Relation.new(self, uri: uri)
+          end
+
+          # Spyke override -- allows properly setting limit, offset and other
+          # options, as well as using the appropriate HTTP method/URL depending
+          # on whether there's a query present in the current scope.
+          #
+          # @example
+          #   Person.query(first_name: "Stefan").fetch # -> POST .../_find
+          #
+          def fetch
+            if current_scope.has_query?
+              scope = extend_scope_with_fm_params(current_scope, prefixed: false)
+              scope = scope.where(query: scope.query_params)
+              scope = scope.with(FmRest::V1::find_path(layout))
+            else
+              scope = extend_scope_with_fm_params(current_scope, prefixed: true)
+            end
+
+            previous, self.current_scope = current_scope, scope
+
+            # The DAPI returns a 401 "No records match the request" error when
+            # nothing matches a _find request, so we need to catch it in order
+            # to provide sane behavior (i.e. return an empty resultset)
+            begin
+              current_scope.has_query? ? scoped_request(:post) : super
+            rescue FmRest::APIError::NoMatchingRecordsError => e
+              raise e if raise_on_no_matching_records
+              ::Spyke::Result.new({})
+            end
+          ensure
+            self.current_scope = previous
+          end
+
+          # Exception-raising version of `#create`
+          #
+          # @param attributes [Hash] the attributes to initialize the
+          #   record with
+          #
+          def create!(attributes = {})
+            new(attributes).tap(&:save!)
+          end
+
+          # Requests execution of a FileMaker script.
+          #
+          # @param script_name [String] the name of the FileMaker script to
+          #   execute
+          # @param param [String] an optional paramater for the script
+          #
+          def execute_script(script_name, param: nil)
+            params = {}
+            params = {"script.param" => param} unless param.nil?
+            request(:get, FmRest::V1::script_path(layout, script_name), params)
+          end
+
+          private
+
+          def extend_scope_with_fm_params(scope, prefixed: false)
+            prefix = prefixed ? "_" : nil
+
+            where_options = {}
+
+            where_options["#{prefix}limit"] = scope.limit_value if scope.limit_value
+            where_options["#{prefix}offset"] = scope.offset_value if scope.offset_value
+
+            if scope.sort_params.present?
+              where_options["#{prefix}sort"] =
+                prefixed ? scope.sort_params.to_json : scope.sort_params
+            end
+
+            unless scope.included_portals.nil?
+              where_options["portal"] =
+                prefixed ? scope.included_portals.to_json : scope.included_portals
+            end
+
+            if scope.portal_params.present?
+              scope.portal_params.each do |portal_param, value|
+                where_options["#{prefix}#{portal_param}"] = value
+              end
+            end
+
+            if scope.script_params.present?
+              where_options.merge!(scope.script_params)
+            end
+
+            scope.where(where_options)
+          end
+        end
+
+        # Spyke override -- Adds a number of features to original `#save`:
+        #
+        # * Validations
+        # * Data API scripts execution
+        # * Refresh of dirty attributes
+        #
+        # @option options [String] :script the name of a FileMaker script to execute
+        #   upon saving
+        # @option options [Boolean] :raise_validation_errors whether to raise an
+        #   exception if validations fail
+        #
+        # @return [true] if saved successfully
+        # @return [false] if validations or persistence failed
+        #
+        def save(options = {})
+          callback = persisted? ? :update : :create
+
+          return false unless perform_save_validations(callback, options)
+          return false unless perform_save_persistence(callback, options)
+
+          true
+        end
+
+        # Exception-raising version of `#save`.
+        #
+        # @option (see #save)
+        #
+        # @return [true] if saved successfully
+        #
+        # @raise if validations or presistence failed
+        #
+        def save!(options = {})
+          save(options.merge(raise_validation_errors: true))
+        end
+
+        # Exception-raising version of `#update`.
+        #
+        # @param new_attributes [Hash] a hash of record attributes to update
+        #   the record with
+        #
+        # @option (see #save)
+        #
+        def update!(new_attributes, options = {})
+          self.attributes = new_attributes
+          save!(options)
+        end
+
+        # Spyke override -- Adds support for Data API script execution.
+        #
+        # @option options [String] :script the name of a FileMaker script to execute
+        #   upon deletion
+        #
+        def destroy(options = {})
+          # For whatever reason the Data API wants the script params as query
+          # string params for DELETE requests, making this more complicated
+          # than it should be
+          script_query_string = if options.has_key?(:script)
+                                  "?" + Faraday::Utils.build_query(FmRest::V1.convert_script_params(options[:script]))
+                                else
+                                  ""
+                                end
+
+          self.attributes = delete(uri.to_s + script_query_string)
+        end
+
+        # (see #destroy)
+        #
+        # @option (see #destroy)
+        #
+        def reload(options = {})
+          scope = self.class
+          scope = scope.script(options[:script]) if options.has_key?(:script)
+          reloaded = scope.find(__record_id)
+          self.attributes = reloaded.attributes
+          self.__mod_id = reloaded.mod_id
+        end
+
+        # ActiveModel 5+ implements this method, so we only need it if we're in
+        # the older AM4
+        if ActiveModel::VERSION::MAJOR == 4
+          def validate!(context = nil)
+            valid?(context) || raise_validation_error
+          end
+        end
+
+        private
+
+        def perform_save_validations(context, options)
+          return true if options[:validate] == false
+          options[:raise_validation_errors] ? validate!(context) : validate(context)
+        end
+
+        def perform_save_persistence(callback, options)
+          run_callbacks :save do
+            run_callbacks(callback) do
+
+              begin
+                send self.class.method_for(callback), build_params_for_save(options)
+
+              rescue APIError::ValidationError => e
+                if options[:raise_validation_errors]
+                  raise e
+                else
+                  return false
+                end
+              end
+
+            end
+          end
+
+          true
+        end
+
+        def build_params_for_save(options)
+          to_params.tap do |params|
+            if options.has_key?(:script)
+              params.merge!(FmRest::V1.convert_script_params(options[:script]))
+            end
+          end
+        end
+
+        # Overwrite ActiveModel's raise_validation_error to use our own class
+        #
+        def raise_validation_error # :doc:
+          raise(ValidationError.new(self))
+        end
+      end
+    end
+  end
+end