fmrest-spyke 0.17.1 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19e4983cff9d5959b2e9263687daaf18d779fcf6d284cbb6ec8844c1623beabf
-  data.tar.gz: 0e558a94cf0b26f5ffe1258f33385f0e016a73ae55aa200ea6768160c746ebd1
+  metadata.gz: 19357358bdb618c8e8f600c7a427bd7b779d17a192145e040f455403fe53e000
+  data.tar.gz: da2227cf47f7c920e367fdfda08bb9e0ac19e696b73930beacf98d975dac8fee
 SHA512:
-  metadata.gz: 1af0c0918fe48374fd2dbe5f20bbeb8f0f7e9f73537233f9b530ea53ec37c3ceffba5612c244ce0c9553c66a2090dcd1d8330581940f6713660cbc6b1a362dd0
-  data.tar.gz: 75abe05bdbfec9e21d0bc3e6dcc5c10d3bbdb66213382c494e3b7511f4c00c628b5ad054ca81e486c4c614a3c9832f60787000a5d990399488ce7027c59a45e1
+  metadata.gz: b00414dc29c9ec01317b47210fd4808f766fcaaa2744ed56ffd943180dd80e994c67b7749c3a619b5d1176e7c5bb3bf0b884f82517617e3e39b963e4094d84e7
+  data.tar.gz: 45ba0c02eede56150923029863a6a6301271967b8c6cde342b0ab1baf6c6089f7452f763e463138e4095a6b2b9de1178e8135b0e1d045ed00913b774780a531f

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## Changelog
 
+### 0.18.0
+
+* Better support for portals with mismatching field qualifiers
+* Better ergonomics for script execution, improved documentation
+* Defining an attribute on a model that would collide with an existing method
+  now raises an error
+* Cleared Faraday deprecation messages on authentication methods
+* Handle FileMaker Cloud case where HTTP 401 Unauthorized with content-type
+  text/html is returned after token expiry
+* Add retry option to Rescuable mixin
+* Added fmrest-ruby/VERSION to User-Agent headers
+
 ### 0.17.1
 
 * Fixed crash when `fmid_token` is set but `username` isn't

data/README.md

@@ -543,6 +543,10 @@ class LoggyBee < FmRest::Layout
 end
 ```
 
+## Gotchas
+
+Read about unexpected scenarios in the [gotchas doc](docs/Gotchas.md).
+
 ## API implementation completeness table
 
 FM Data API reference: https://fmhelp.filemaker.com/docs/18/en/dataapi/

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "fmrest/spyke/portal_builder"
 require "fmrest/spyke/portal"
 
 module FmRest
@@ -13,6 +14,8 @@ module FmRest
         included do
           # Keep track of portal options by their FM keys as we could need it
           # to parse the portalData JSON in SpykeFormatter
+          #
+          # TODO: Replace this with options in PortalBuilder
           class_attribute :portal_options, instance_accessor: false, instance_predicate: false
 
           # class_attribute supports a :default option since ActiveSupport 5.2,
@@ -40,11 +43,13 @@ module FmRest
           #   end
           #
           def has_portal(name, options = {})
-            create_association(name, Portal, options)
+            # This is analogous to Spyke's create_association method, but using
+            # our custom builder instead
+            self.associations = associations.merge(name => PortalBuilder.new(self, name, Portal, options))
 
             # Store options for SpykeFormatter to use if needed
             portal_key = options[:portal_key] || name
-            self.portal_options = portal_options.merge(portal_key.to_s => options.dup.merge(name: name.to_s)).freeze
+            self.portal_options = portal_options.merge(portal_key.to_s => options.dup.merge(name: name.to_s).freeze).freeze
 
             define_method "#{name.to_s.singularize}_ids" do
               association(name).map(&:id)

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

@@ -94,11 +94,17 @@ module FmRest
           end
 
           def _fmrest_define_attribute(from, to)
+            if existing_method = ((method_defined?(from) || private_method_defined?(from)) && from) ||
+                                 ((method_defined?("#{from}=") || private_method_defined?("#{from}=")) && "#{from}=")
+
+              raise ArgumentError, "You tried to define an attribute named `#{from}' on `#{name}', but this will generate a instance method `#{existing_method}', which is already defined by FmRest::Layout."
+            end
+
             # We use a setter here instead of injecting the hash key/value pair
             # directly with #[]= so that we don't change the mapped_attributes
             # hash on the parent class. The resulting hash is frozen for the
             # same reason.
-            self.mapped_attributes = mapped_attributes.merge(from => to).freeze
+            self.mapped_attributes = mapped_attributes.merge(from => to.to_s).freeze
 
             _fmrest_attribute_methods_container.module_eval do
               define_method(from) do

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

@@ -140,8 +140,8 @@ module FmRest
 
                 conn.use FmRest::V1::TypeCoercer, config
 
-                # FmRest::Spyke::JsonParse expects symbol keys
-                conn.response :json, parser_options: { symbolize_names: true }
+                # FmRest::Spyke::SpykeFormatter expects symbol keys
+                conn.response :json, parser_options: { symbolize_names: true }, content_type: /\bjson$/
               end
 
             @fmrest_connection = connection if memoize

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

@@ -6,8 +6,6 @@ module FmRest
       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, {
@@ -26,7 +24,7 @@ module FmRest
                 next
               end
 
-              unless FULLY_QUALIFIED_FIELD_NAME_MATCHER === k.to_s
+              unless V1.is_fully_qualified?(k.to_s)
                 raise ArgumentError, "global fields must be given in fully qualified format (table name::field name)"
               end
 

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

@@ -78,18 +78,6 @@ module FmRest
             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)

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

@@ -3,9 +3,46 @@
 module FmRest
   module Spyke
     module Model
+      # This mixin allows rescuing from errors raised during HTTP requests,
+      # with optional retry (useful for solving expired auth). This is based
+      # off ActiveSupport::Rescuable, with minimal added functionality. Its
+      # usage is analogous to `rescue_from` in Rails' controllers.
+      #
+      # Example usage:
+      #
+      #   MyLayout < FmRest::Layout
+      #     # Mix-in module
+      #     include FmRest::Spyke::Model::Rescuable
+      #
+      #     # Define an error handler
+      #     rescue_from FmRest::APIError::SomeError, with: :report_error
+      #
+      #     # Define block-based error handler
+      #     rescue_from FmRest::APIError::SomeOtherError, with: -> { ... }
+      #
+      #     private
+      #
+      #     def report_error(exception)
+      #       ErrorNotifier.notify(exception)
+      #     ene
+      #   end
+      #
+      # This module also extends upon ActiveSupport's implementation by
+      # allowing to request a retry of the failed request, which can be useful
+      # in situations where an auth token has expired and credentials need to
+      # be manually reset.
+      #
+      # To request a retry use `throw :retry` within the handler method.
+      #
+      # Finally, since it's the most common use case, there's a shorthand
+      # method for handling Data API authentication errors:
+      #
+      #   rescue_account_error with: -> { CredentialsManager.refresh_credentials }
+      #
+      # This method will always issue a retry.
+      #
       module Rescuable
         extend ::ActiveSupport::Concern
-
         include ::ActiveSupport::Rescuable
 
         class_methods do
@@ -13,12 +50,19 @@ module FmRest
             begin
               super
             rescue => e
-              rescue_with_handler(e) || raise
+              catch :retry do
+                rescue_with_handler(e) || raise
+                return
+              end
+              super
             end
           end
 
-          def rescue_account_error(with: nil, &block)
-            rescue_from APIError::AccountError, with: with, &block
+          def rescue_account_error(with: nil)
+            rescue_from(APIError::AccountError, with: with) do
+              yield
+              throw :retry
+            end
           end
         end
       end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+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 ScriptExecution
+        extend ::ActiveSupport::Concern
+
+        class_methods do
+          # Requests execution of a FileMaker script, returning its result
+          # object.
+          #
+          # @example
+          #   response = MyLayout.execute("Uppercasing Script", "hello")
+          #
+          #   response.result   # => "HELLO"
+          #   response.error    # => "0"
+          #   response.success? # => true
+          #
+          # @param script_name [String] the name of the FileMaker script to
+          #   execute
+          # @param param [String] an optional paramater for the script
+          # @return [FmRest::Spyke::ScriptResult] the script result object
+          #   containing the return value and error code
+          #
+          def execute(script_name, param = nil)
+            # Allow keyword argument format for compatibility with execute_script
+            if param.respond_to?(:has_key?) && param.has_key?(:param)
+              param = param[:param]
+            end
+
+            response = execute_script(script_name, param: param)
+            response.metadata.script.after
+          end
+
+          # Requests execution of a FileMaker script, returning the entire
+          # response object.
+          #
+          # The execution results will be in `response.metadata.script.after`
+          #
+          # In general you'd want to use the simpler `.execute` instead of this
+          # method, as it provides more direct access to the script results.
+          #
+          # @example
+          #   response = MyLayout.execute_script("My Script", param: "hello")
+          #
+          # @param script_name [String] the name of the FileMaker script to
+          #   execute
+          # @param param [String] an optional paramater for the script
+          # @return the complete response object
+          #
+          def execute_script(script_name, param: nil)
+            params = param.nil? ? {} : {"script.param" => param}
+            request(:get, FmRest::V1::script_path(layout, script_name), params)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -26,7 +26,7 @@ module FmRest
         def serialize_for_portal(portal)
           params =
             changed_params.except(:__record_id).transform_keys do |key|
-              "#{portal.attribute_prefix}::#{key}"
+              V1.is_fully_qualified?(key) ? key : "#{portal.attribute_prefix}::#{key}"
             end
 
           params[:recordId] = __record_id.to_s if __record_id

data/lib/fmrest/spyke/model.rb

@@ -11,6 +11,7 @@ require "fmrest/spyke/model/container_fields"
 require "fmrest/spyke/model/global_fields"
 require "fmrest/spyke/model/http"
 require "fmrest/spyke/model/auth"
+require "fmrest/spyke/model/script_execution"
 
 module FmRest
   module Spyke
@@ -28,6 +29,7 @@ module FmRest
       include GlobalFields
       include Http
       include Auth
+      include ScriptExecution
 
       autoload :Rescuable, "fmrest/spyke/model/rescuable"
     end

data/lib/fmrest/spyke/portal_builder.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    class PortalBuilder < ::Spyke::Associations::Builder
+      attr_reader :options
+
+      def klass
+        begin
+          super
+        rescue NameError => e
+          ::FmRest::Layout
+        end
+      end
+    end
+  end
+end

data/lib/fmrest/spyke/spyke_formatter.rb

@@ -1,12 +1,11 @@
 # 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)
+    Metadata = Struct.new(:messages, :script, :data_info) do
       alias_method :scripts, :script
     end
 
@@ -16,6 +15,11 @@ module FmRest
       def returned_count; returnedCount; end
     end
 
+    ScriptResult = Struct.new(:result, :error) do
+      def success?; error == "0"; end
+      def error?; !success?; end
+    end
+
     # Response Faraday middleware for converting FM API's response JSON into
     # Spyke's expected format
     class SpykeFormatter < ::Faraday::Response::Middleware
@@ -119,17 +123,18 @@ module FmRest
 
         [:prerequest, :presort].each do |s|
           if json[:response][:"scriptError.#{s}"]
-            results[s] = OpenStruct.new(
-              result: json[:response][:"scriptResult.#{s}"],
-              error:  json[:response][:"scriptError.#{s}"]
+            results[s] = ScriptResult.new(
+              json[:response][:"scriptResult.#{s}"],
+              json[:response][:"scriptError.#{s}"]
             ).freeze
           end
         end
 
+        # after/default script
         if json[:response][:scriptError]
-          results[:after] = OpenStruct.new(
-            result: json[:response][:scriptResult],
-            error:  json[:response][:scriptError]
+          results[:after] = ScriptResult.new(
+            json[:response][:scriptResult],
+            json[:response][:scriptError]
           ).freeze
         end
 
@@ -195,8 +200,8 @@ module FmRest
         out
       end
 
-      # Extracts `recordId` and strips the `"PortalName::"` field prefix for each
-      # portal
+      # Extracts `recordId` and strips the `"tableName::"` field qualifier for
+      # each portal
       #
       # Sample `json_portal_data`:
       #
@@ -210,19 +215,33 @@ module FmRest
       # @return [Hash] the portal data in Spyke format
       def prepare_portal_data(json_portal_data)
         json_portal_data.each_with_object({}) do |(portal_name, portal_records), out|
+
           portal_options = @model.portal_options[portal_name.to_s] || {}
+          portal_builder = portal_options[:name] && @model.associations[portal_options[:name].to_sym]
+          portal_class = portal_builder && portal_builder.klass
+          portal_attributes = (portal_class && portal_class.mapped_attributes.values) || []
 
           out[portal_name] =
             portal_records.map do |portal_fields|
               attributes = { __record_id: portal_fields[:recordId] }
               attributes[:__mod_id] = portal_fields[:modId] if portal_fields[:modId]
 
-              prefix = portal_options[:attribute_prefix] || portal_name
-              prefix_matcher = /\A#{prefix}::/
+              qualifier = portal_options[:attribute_prefix] || portal_name
+              qualifier_matcher = /\A#{qualifier}::/
 
               portal_fields.each do |k, v|
                 next if :recordId == k || :modId == k
-                attributes[k.to_s.gsub(prefix_matcher, "").to_sym] = v
+
+                stripped_field_name = k.to_s.gsub(qualifier_matcher, "")
+
+                # Only use the non-qualified attribute name if it was defined
+                # that way on the portal model, otherwise default to the fully
+                # qualified name
+                if portal_attributes.include?(stripped_field_name)
+                  attributes[stripped_field_name.to_sym] = v
+                else
+                  attributes[k.to_sym] = v
+                end
               end
 
               attributes

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fmrest-spyke
 version: !ruby/object:Gem::Version
-  version: 0.17.1
+  version: 0.18.0
 platform: ruby
 authors:
 - Pedro Carbajal
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-08-29 00:00:00.000000000 Z
+date: 2021-09-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fmrest-core
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.17.1
+        version: 0.18.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.17.1
+        version: 0.18.0
 - !ruby/object:Gem::Dependency
   name: spyke
   requirement: !ruby/object:Gem::Requirement
@@ -65,9 +65,11 @@ files:
 - lib/fmrest/spyke/model/orm.rb
 - lib/fmrest/spyke/model/record_id.rb
 - lib/fmrest/spyke/model/rescuable.rb
+- lib/fmrest/spyke/model/script_execution.rb
 - lib/fmrest/spyke/model/serialization.rb
 - lib/fmrest/spyke/model/uri.rb
 - lib/fmrest/spyke/portal.rb
+- lib/fmrest/spyke/portal_builder.rb
 - lib/fmrest/spyke/relation.rb
 - lib/fmrest/spyke/spyke_formatter.rb
 - lib/fmrest/spyke/validation_error.rb