fmrest-spyke 0.16.0 → 0.18.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a91619fdca8717119b8b299648d3388948551e653bececb0a90a422850be0a2
-  data.tar.gz: 9e666b8f8162522b1269a3b4d18cda8724ad7439d0398672c02d228149cb636d
+  metadata.gz: 38cc05be48b9ba5737e7a2c1d89504bab617a2f1d6d7261fde1b5a919aa793e7
+  data.tar.gz: 0b1780c8ce2f7d8d8f4c300909b2bafb7f41e18e2ce648f929be9e2d3569ddbe
 SHA512:
-  metadata.gz: 6fee0ccdc7bb75ae47f620c0cbf3da137806394225a565f5227d9a63e4ea4612b78200997dfc84594ba4eb2db84a156a28d3b05109d9dfb95f6851434bd94f6b
-  data.tar.gz: bab901d8024b1331358325f149ebc297c206e549aba81b73187748b2f168c7eecac2409170722e7a062901317084348c4ac3811bddffa07613bf944aa0f61f00
+  metadata.gz: 123d5611c9c862605c30643b8034665c67c24fc283d21311f6124baff2271c459bcae0d4834f2480f4aa2e521105a6df58ecb011f46fc4f50a656df4a91108f5
+  data.tar.gz: 91a6d0bdf49792a76b0bf817543a89e7b92bcf0c55eaa128d9bee3219f250e47a14bd064f862383f11f66dac70f1830cc6f1017b56d912f4d8be344e7ac86bed

data/CHANGELOG.md

@@ -1,13 +1,29 @@
 ## Changelog
 
+### 0.18.0
+
+* Better support for portals with mismatching field qualifiers
+* Defining an attribute on a model that would collide with an existing method
+  now raises an error
+
+### 0.17.1
+
+* Fixed crash when `fmid_token` is set but `username` isn't
+
+### 0.17.0
+
+* Added support for Claris ID token login
+* Added ability to use procs in settings
+* Added `Rescuable` mixin
+
 ### 0.16.0
 
-* Add `FmRest.logger=`
+* Added `FmRest.logger=`
 * Handle serialization of `nil`, `true` and `false` values
 
 ### 0.15.2
 
-* Fix autoloading of `FmRest::Layout`
+* Fixed autoloading of `FmRest::Layout`
 
 ### 0.15.0
 
@@ -23,13 +39,13 @@
 
 ### 0.13.1
 
-* Fix downloading of container field data from FMS19+
+* Fixed downloading of container field data from FMS19+
 
 ### 0.13.0
 
 * Split `fmrest` gem into `fmrest-core` and `fmrest-spyke`. `fmrest` becomes a
   wrapper for the two new gems.
-* Fix bug preventing connection databases with spaces in their names.
+* Fixed bug preventing connection databases with spaces in their names.
 * Improved portal support with ability to delete portal records, and better
   refreshing of portal records after saving the parent.
 * `FmRest::Spyke::Base#__record_id` and `FmRest::Spyke::Base#__mod_id` now
@@ -44,7 +60,7 @@
 
 ### 0.11.1
 
-* Fix a couple crashes due to missing constants
+* Fixed a couple crashes due to missing constants
 
 ### 0.11.0
 
@@ -59,7 +75,7 @@
 
 ### 0.10.1
 
-* Fix `URI.escape` obsolete warning messages in Ruby 2.7 by replacing it with
+* Fixed `URI.escape` obsolete warning messages in Ruby 2.7 by replacing it with
   `URI.encode_www_form_component`
   ([PR#40](https://github.com/beezwax/fmrest-ruby/pull/40))
 
@@ -133,20 +149,20 @@
 
 ### 0.3.2
 
-* Fix support for ActiveSupport < 5.2
+* Fixed support for ActiveSupport < 5.2
   ([#27](https://github.com/beezwax/fmrest-ruby/issues/27))
 
 ### 0.3.0
 
-* Add Moneta token store
+* Added Moneta token store
 
 ### 0.2.5
 
-* Fix crash in `fetch_container_data` when no proxy options were set
+* Fixed crash in `fetch_container_data` when no proxy options were set
 
 ### 0.2.4
 
 * Use `String#=~` instead of `String#match?` for Ruby <2.4 compatibility (Fixes
   [#26](https://github.com/beezwax/fmrest-ruby/issues/26))
-* Deprecate `FmRest.config` in favor of `FmRest.default_connection_settings`
+* Deprecated `FmRest.config` in favor of `FmRest.default_connection_settings`
 * Honor Faraday SSL and proxy settings when fetching container files

data/README.md

@@ -125,6 +125,10 @@ The minimum required connection settings are `:host`, `:database`, `:username`
 and `:password`, but fmrest-ruby has many other options you can pass when
 setting up a connection (see [full list](#full-list-of-available-options) below).
 
+If you're using FileMaker Cloud you may need to pass `:fmid_token` instead
+of the regular `:username` and `:password`. See the [main document on
+connecting to FileMaker Cloud](docs/FileMakerCloud.md) for more info.
+
 `:ssl` and `:proxy` are forwarded to the underlying
 [Faraday](https://github.com/lostisland/faraday) connection. You can use this
 to, for instance, disable SSL verification:
@@ -149,6 +153,7 @@ Option              | Description                                | Format
 `:username`         | A Data API-ready account                   | String                      | None
 `:password`         | Your password                              | String                      | None
 `:account_name`     | Alias of `:username`                       | String                      | None
+`:fmid_token`       | Claris ID token (only needed for FileMaker Cloud) | String               | None
 `:ssl`              | SSL options to be forwarded to Faraday     | Faraday SSL options         | None
 `:proxy`            | Proxy options to be forwarded to Faraday   | Faraday proxy options       | None
 `:log`              | Log JSON responses to STDOUT               | Boolean                     | `false`
@@ -283,10 +288,12 @@ Also, if not set, your model will try to use
 #### Connection settings overlays
 
 There may be cases where you want to use a different set of connection settings
-depending on context. For example, if you want to use username and password
-provided by the user in a web application. Since `.fmrest_config`
-is set at the class level, changing the username/password for the model in one
-context would also change it in all other contexts, leading to security issues.
+depending on context, or simply change the connection settings over time. For
+example, if you want to use username and password provided by the user in a web
+application, or if you're connecting using an expiring Claris ID token. Since
+`.fmrest_config` is set at the class level, changing the username/password for
+the model in one context would also change it in all other contexts, leading to
+security issues.
 
 To solve this scenario, fmrest-ruby provides a way of defining thread-local and
 reversible connection settings overlays through
@@ -323,7 +330,7 @@ Requests a Data API session token using the connection settings in
 
 You normally don't need to use this method as fmrest-ruby will automatically
 request and store session tokens for you (provided that `:autologin` is
-`true`).
+`true` in the connection settings, which it is by default).
 
 ### FmRest::Layout.logout
 
@@ -452,6 +459,41 @@ field values on the database that model is configured for.
 See the [main document on setting global field values](docs/GlobalFields.md)
 for details.
 
+### Rescuable mixin
+
+Sometimes you may want to handle Data API errors at the model level. For
+instance, if you're logging in to a file hosted by FileMaker Cloud using a
+Claris ID token, and you want to be able to renew said token when it fails to
+log you in. For such cases fmrest-ruby provides an off-by-default mixin called
+`Rescuable` that provides convenience macros for that. If you've used Ruby on
+Rails you may be familiar with its syntax from controllers. E.g.
+
+```ruby
+class BeeBase < FmRest::Layout
+  include FmRest::Spyke::Model::Rescuable
+
+  rescue_from FmRest::APIError::SystemError, with: :notify_admin_of_system_error
+
+  # Shorthand for rescue_with FmRest::APIError::AccountError, ...
+  rescue_account_error { ClarisIDTokenManager.expire_token }
+
+  def self.notify_admin_of_system_error(e)
+    # Shoot an email to the FM admin...
+  end
+end
+```
+
+Since `Rescuable` uses `ActiveSupport::Rescuable` internally, you may want to
+check [Rails'
+documentation](https://api.rubyonrails.org/classes/ActiveSupport/Rescuable/ClassMethods.html)
+too for details on how it works.
+
+One caveat of using `rescue_from` is that it always catches exceptions at the
+class level, so if you pass a method name to `with:` that method has to be a
+class method. Also note that this will only catch exceptions raised during an
+API call to the Data API server (in other words, only on actions that perform
+an HTTP request).
+
 ## Logging
 
 If using `fmrest-spyke` with Rails then pretty log output will be set up for
@@ -501,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/
@@ -510,7 +556,7 @@ FM Data API reference: https://fmhelp.filemaker.com/docs/18/en/dataapi/
 | Log in using HTTP Basic Auth        | Yes                           | Yes                         |
 | Log in using OAuth                  | No                            | No                          |
 | Log in to an external data source   | No                            | No                          |
-| Log in using a FileMaker ID account | No                            | No                          |
+| Log in using Claris ID account      | Yes                           | Yes                         |
 | Log out                             | Yes                           | Yes                         |
 | Get product information             | Manual*                       | No                          |
 | Get database names                  | Manual*                       | No                          |

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/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/rescuable.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module FmRest
+  module Spyke
+    module Model
+      module Rescuable
+        extend ::ActiveSupport::Concern
+
+        include ::ActiveSupport::Rescuable
+
+        class_methods do
+          def request(*args)
+            begin
+              super
+            rescue => e
+              rescue_with_handler(e) || raise
+            end
+          end
+
+          def rescue_account_error(with: nil, &block)
+            rescue_from APIError::AccountError, with: with, &block
+          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

@@ -28,6 +28,8 @@ module FmRest
       include GlobalFields
       include Http
       include Auth
+
+      autoload :Rescuable, "fmrest/spyke/model/rescuable"
     end
   end
 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

@@ -195,8 +195,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 +210,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 = @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.16.0
+  version: 0.18.0.rc1
 platform: ruby
 authors:
 - Pedro Carbajal
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-14 00:00:00.000000000 Z
+date: 2021-09-01 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.16.0
+        version: 0.18.0.rc1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.16.0
+        version: 0.18.0.rc1
 - !ruby/object:Gem::Dependency
   name: spyke
   requirement: !ruby/object:Gem::Requirement
@@ -64,9 +64,11 @@ files:
 - lib/fmrest/spyke/model/http.rb
 - lib/fmrest/spyke/model/orm.rb
 - lib/fmrest/spyke/model/record_id.rb
+- lib/fmrest/spyke/model/rescuable.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
@@ -85,11 +87,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.0.6
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: FileMaker Data API ORM client library