fmrest-spyke 0.15.2 → 0.17.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a23ace303897e8ce4f81635a6b800aae8f4cba61f79bc9594ba43669ad900fd8
-  data.tar.gz: 117e2ec52a4fdbfec79ec846160b8bda7a5a4a43ea0059de6a1557913efe7182
+  metadata.gz: 19e4983cff9d5959b2e9263687daaf18d779fcf6d284cbb6ec8844c1623beabf
+  data.tar.gz: 0e558a94cf0b26f5ffe1258f33385f0e016a73ae55aa200ea6768160c746ebd1
 SHA512:
-  metadata.gz: 9b77e8a541883d8f0744653f69443c94eaf6e8fe40637107329b579791605c20086b09d79dd62e807b1bd4e9a941e998ddcac11fcac7b864908b7bfd613f88ae
-  data.tar.gz: fb90f1df6a5287bebe5ac77c9e88c6548c6101bdd29cbb4f2b0c9382a0d4e1781dbd717b504bc88bdc14b07770568cdc42871a9a65c90fbfeed545485a7480ca
+  metadata.gz: 1af0c0918fe48374fd2dbe5f20bbeb8f0f7e9f73537233f9b530ea53ec37c3ceffba5612c244ce0c9553c66a2090dcd1d8330581940f6713660cbc6b1a362dd0
+  data.tar.gz: 75abe05bdbfec9e21d0bc3e6dcc5c10d3bbdb66213382c494e3b7511f4c00c628b5ad054ca81e486c4c614a3c9832f60787000a5d990399488ce7027c59a45e1

data/CHANGELOG.md

@@ -1,8 +1,23 @@
 ## Changelog
 
+### 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
+
+* 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
 
@@ -18,13 +33,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
@@ -39,7 +54,7 @@
 
 ### 0.11.1
 
-* Fix a couple crashes due to missing constants
+* Fixed a couple crashes due to missing constants
 
 ### 0.11.0
 
@@ -54,7 +69,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))
 
@@ -128,20 +143,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,9 +153,11 @@ 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`
+`:log_level`        | Which log level to log into                | Values accepted by `Logger#level=` | `:debug`
 `:coerce_dates`     | See section on [date fields](#date-fields-and-timezones) | Boolean \| `:hybrid` \| `:full` | `false`
 `:date_format`      | Date parsing format                        | String (FM date format)     | `"MM/dd/yyyy"`
 `:timestamp_format` | Timestmap parsing format                   | String (FM date format)     | `"MM/dd/yyyy HH:mm:ss"`
@@ -282,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
@@ -322,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
 
@@ -451,13 +459,48 @@ 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
 you automatically by Spyke (see [their
 README](https://github.com/balvig/spyke#log-output)).
 
-You can also enable simple Faraday STDOUT logging of raw requests (useful for
+You can also enable simple Faraday logging of raw requests (useful for
 debugging) by passing `log: true` in the options hash for either
 `FmRest.default_connection_settings=` or your models' `fmrest_config=`, e.g.:
 
@@ -478,7 +521,17 @@ class LoggyBee < FmRest::Layout
 end
 ```
 
-If you need to set up more complex logging for your models can use the
+You can also pass `log_level` to connection settings to change the severity of
+log output (defaults to `:debug`).
+
+By default fmrest-ruby logs to STDOUT or to Rails' logger object if available.
+You can change this by providing your own logger object to `FmRest.logger=`:
+
+```ruby
+FmRest.logger = Logger.new("fmrest.log")
+```
+
+If you need to set up more complex logging for your models you can use the
 `faraday` block inside your class to inject your own logger middleware into the
 Faraday connection, e.g.:
 
@@ -499,7 +552,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/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

@@ -73,6 +73,10 @@ module FmRest
         # Modifies the given hash in-place encoding non-string values (e.g.
         # dates) to their string representation when appropriate.
         #
+        # nil gets converted to empty string as the Data API doesn't accept
+        # nulls in JSON. Likewise, true and false get converted to 1 and 0
+        # respectively.
+        #
         def serialize_values!(params)
           params.transform_values! do |value|
             case value
@@ -80,6 +84,10 @@ module FmRest
               FmRest::V1.convert_datetime_timezone(value.to_datetime, fmrest_config.timezone).strftime(FmRest::V1::Dates::FM_DATETIME_FORMAT)
             when *FmRest::V1.date_classes
               value.strftime(FmRest::V1::Dates::FM_DATE_FORMAT)
+            when nil
+              ""
+            when true, false
+              value ? 1 : 0
             else
               value
             end

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fmrest-spyke
 version: !ruby/object:Gem::Version
-  version: 0.15.2
+  version: 0.17.1
 platform: ruby
 authors:
 - Pedro Carbajal
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-06 00:00:00.000000000 Z
+date: 2021-08-29 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.15.2
+        version: 0.17.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.15.2
+        version: 0.17.1
 - !ruby/object:Gem::Dependency
   name: spyke
   requirement: !ruby/object:Gem::Requirement
@@ -64,6 +64,7 @@ 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
@@ -89,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
+rubygems_version: 3.2.3
 signing_key:
 specification_version: 4
 summary: FileMaker Data API ORM client library