fmrest-spyke 0.18.0.rc1 → 0.19.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38cc05be48b9ba5737e7a2c1d89504bab617a2f1d6d7261fde1b5a919aa793e7
-  data.tar.gz: 0b1780c8ce2f7d8d8f4c300909b2bafb7f41e18e2ce648f929be9e2d3569ddbe
+  metadata.gz: eb879437821941e732a5e52b01c7f0feace73cd3faf1d1e584e0a1a5b3224876
+  data.tar.gz: 02b666bdba2e9a29fcfdea4c34bb6ea26eccaead15b3294de57fc5a000cfc13d
 SHA512:
-  metadata.gz: 123d5611c9c862605c30643b8034665c67c24fc283d21311f6124baff2271c459bcae0d4834f2480f4aa2e521105a6df58ecb011f46fc4f50a656df4a91108f5
-  data.tar.gz: 91a6d0bdf49792a76b0bf817543a89e7b92bcf0c55eaa128d9bee3219f250e47a14bd064f862383f11f66dac70f1830cc6f1017b56d912f4d8be344e7ac86bed
+  metadata.gz: bc1506322c774bd2d1bee6a072644df4f37f9116940f710adc6f0fdb9dd4982e9ba570e4f21ee95543d0f52d3e3532ea133dc9a5689621945179eaba33052c28
+  data.tar.gz: d7370baeaf5a4b92ac6b3800ea8fe0ade0525f196cabd2a41615e9cf358251b1cfef2e7263e688545b727f619f6de1802c9f23cde012627e81f1ca5852a6b3e8

data/CHANGELOG.md

@@ -1,10 +1,20 @@
 ## Changelog
 
+### 0.19.0
+
+* Add native support for FileMaker cloud through the `fmrest-cloud` gem
+
 ### 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
 

data/README.md

@@ -5,14 +5,27 @@
 [![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/github/beezwax/fmrest-ruby)
 
 A Ruby client for
-[FileMaker 18 and 19's Data API](https://help.claris.com/en/data-api-guide)
-using
-[Faraday](https://github.com/lostisland/faraday) and with optional
-ActiveRecord-ish ORM features through [Spyke](https://github.com/balvig/spyke).
-
-fmrest-ruby only partially implements FileMaker 19's Data API.
-See the [implementation completeness table](#api-implementation-completeness-table)
-to see if a feature you need is natively supported by the gem.
+[FileMaker's Data API](https://help.claris.com/en/data-api-guide)
+with ActiveRecord-ish ORM features.
+
+While pretty feature-rich, fmrest-ruby doesn't yet support 100% of FileMaker
+19's Data API features. See the [implementation completeness
+table](#api-implementation-completeness-table) to check if a feature you need
+is natively supported by the gem.
+
+## Contents
+
+* [Gems](#gems)
+* [Installation](#installation)
+* [Simple example](#simple-example)
+* [Connection settings](#connection-settings)
+* [Session token store](#session-token-store)
+* [Date fields and timezones](#date-fields-and-timezones)
+* [ActiveRecord-like ORM (fmrest-spyke)](#activerecord-like-orm--fmrest-spyke-)
+* [Logging](#logging)
+* [Gotchas](#gotchas)
+* [API implementation completeness table](#api-implementation-completeness-table)
+* [Supported Ruby versions](#supported-ruby-versions)
 
 ## Gems
 
@@ -20,28 +33,26 @@ The `fmrest` gem is a wrapper for two other gems:
 
 * `fmrest-spyke`, providing an ActiveRecord-like ORM library built on top
   of `fmrest-core` and [Spyke](https://github.com/balvig/spyke).
-* `fmrest-core`, providing the core Faraday connection builder, session
+* `fmrest-core`, providing the core
+  [Faraday](https://github.com/lostisland/faraday) connection builder, session
   management, and other core utilities.
 
+In addition, the optional `fmrest-cloud` gem adds support for FileMaker Cloud.
+See the [main document on connecting to FileMaker
+Cloud](docs/FileMakerCloud.md).
+
 ## Installation
 
-Add this to your Gemfile:
+In your Gemfile:
 
 ```ruby
 gem 'fmrest'
-```
-
-Or if you just want to use the Faraday connection without the ORM features:
 
-```ruby
-gem 'fmrest-core'
+# Optional: if your files are hosted on FileMaker Cloud
+gem 'fmrest-cloud'
 ```
 
-## Simple examples
-
-### ORM example
-
-Most people would want to use the ORM features:
+## Simple example
 
 ```ruby
 # A Layout model connecting to the "Honeybees Web" FileMaker layout
@@ -90,32 +101,9 @@ bee.tasks.build(urgency: "Today")
 bee.save
 ```
 
-### Barebones connection example (without ORM)
-
-In case you don't need the advanced ORM features (e.g. if you only need minimal
-Data API interaction and just want a lightweight solution) you can simply use
-the Faraday connection provided by `fmrest-core`:
-
-```ruby
-connection = FmRest::V1.build_connection(
-  host:     "…",
-  database: "…",
-  username: "…",
-  password: "…"
-)
-
-# Get all records (as parsed JSON)
-connection.get("layouts/FancyLayout/records")
-
-# Create new record
-connection.post do |req|
-  req.url "layouts/FancyLayout/records"
-
-  # You can just pass a hash for the JSON body
-  req.body = { … }
-end
-```
-
+In case you don't want the ORM features (i.e. you only need authentication and
+JSON parsing, and are comfortable writing the API requests manually without the
+ORM overhead) you can use the Faraday connection provided by `fmrest-core`.
 See the [main document on using the base
 connection](docs/BaseConnectionUsage.md) for more.
 
@@ -125,10 +113,6 @@ 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:
@@ -153,7 +137,6 @@ 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`
@@ -165,6 +148,11 @@ Option              | Description                                | Format
 `:timezone`         | The timezone for the FM server             | `:local` \| `:utc` \| `nil` | `nil`
 `:autologin`        | Whether to automatically start Data API sessions | Boolean               | `true`
 `:token`            | Used to manually provide a session token (e.g. if `:autologin` is `false`) | String | None
+`:fmid_token`       | Claris ID token (only needed if manually obtaining the token) | String   | None
+`:cloud`            | Specifies whether the host is using FileMaker Cloud | `:auto` \| Boolean | `:auto`
+`:cognito_client_id`| Overwrites the hardcoded FileMaker Cloud Cognito Client ID | String      | None
+`:cognito_pool_id`  | Overwrites the hardcoded FileMaker Cloud Cognito Pool ID | String        | None
+`:aws_region`       | Overwrites the hardcoded FileMaker Cloud AWS Region | String             | None
 
 ### Default connection settings
 
@@ -207,7 +195,7 @@ See the [main document on date fields](docs/DateFields.md) for more info.
 ## ActiveRecord-like ORM (fmrest-spyke)
 
 [Spyke](https://github.com/balvig/spyke) is an ActiveRecord-like gem for
-building REST ORM models. fmrest-ruby builds its ORM features atop Spyke,
+building REST ORM models. fmrest-ruby uses it to build its ORM features,
 bundled in the `fmrest-spyke` gem (already included if you're using the
 `fmrest` gem).
 
@@ -265,39 +253,33 @@ class Honeybee < FmRest::Layout
 end
 ```
 
-This will automatically create a proper Faraday connection using those
-connection settings, so you don't have to worry about setting that up.
-
-Note that these settings are inheritable, so you could create a base class that
+These settings are class-inheritable, so you could create a base class that
 does the initial connection setup and then inherit from it in models using that
 same connection. E.g.:
 
 ```ruby
-class BeeBase < FmRest::Layout
+class ApplicationFmLayout < FmRest::Layout
   self.fmrest_config = { host: "…", database: "…", … }
 end
 
-class Honeybee < BeeBase
-  # This model will use the same connection as BeeBase
+class Honeybee < ApplicationFmLayout
+  # This model will use the same connection as ApplicationFmLayout
 end
 ```
 
-Also, if not set, your model will try to use
+If `fmrest_config` is not set, your model will try to use
 `FmRest.default_connection_settings` instead.
 
 #### Connection settings overlays
 
 There may be cases where you want to use a different set of connection settings
-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.
+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.
 
-To solve this scenario, fmrest-ruby provides a way of defining thread-local and
-reversible connection settings overlays through
-`.fmrest_config_overlay=`.
+To solve this scenario, fmrest-ruby provides a way of defining thread-local,
+reversible connection settings overlays through `.fmrest_config_overlay=`.
 
 See the [main document on connection setting overlays](docs/ConfigOverlays.md)
 for details on how it works.
@@ -461,12 +443,10 @@ 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.
+Sometimes you may want to handle Data API errors at the model level. 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
@@ -474,9 +454,6 @@ class BeeBase < FmRest::Layout
 
   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
@@ -549,14 +526,14 @@ 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/
+FM Data API reference: https://help.claris.com/en/data-api-guide/
 
-| FM 18 Data API feature              | Supported by basic connection | Supported by FmRest::Layout |
+| FM 19 Data API feature              | Supported by basic connection | Supported by FmRest::Layout |
 |-------------------------------------|-------------------------------|-----------------------------|
 | 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 Claris ID account      | Yes                           | Yes                         |
+| Log in using Claris ID account (FileMaker Cloud) | Yes              | Yes                         |
 | Log out                             | Yes                           | Yes                         |
 | Get product information             | Manual*                       | No                          |
 | Get database names                  | Manual*                       | No                          |
@@ -592,9 +569,9 @@ the following Ruby implementations:
 ## Gem development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
-`rake spec` to run the tests. You can also run `bin/console` for an interactive
-prompt that will allow you to experiment (it will auto-load all fixtures in
-spec/fixtures).
+`bundle exec rspec` to run the specs. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment (it will auto-load all
+fixtures in spec/fixtures).
 
 To install all gems onto your local machine, run
 `bundle exec rake all:install`. To release a new version, update the version
@@ -602,12 +579,6 @@ number in `lib/fmrest/version.rb`, and then run `bundle exec rake all:release`,
 which will create a git tag for the version, push git commits and tags, and
 push the `.gem` files to [rubygems.org](https://rubygems.org).
 
-## License
-
-The gem is available as open source under the terms of the
-[MIT License](https://opensource.org/licenses/MIT).
-See [LICENSE.txt](LICENSE.txt).
-
 ## Disclaimer
 
 This project is not sponsored by or otherwise affiliated with Claris

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/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.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/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
 
@@ -212,7 +217,7 @@ module FmRest
         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_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) || []
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fmrest-spyke
 version: !ruby/object:Gem::Version
-  version: 0.18.0.rc1
+  version: 0.19.0.rc1
 platform: ruby
 authors:
 - Pedro Carbajal
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-09-01 00:00:00.000000000 Z
+date: 2021-10-06 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.18.0.rc1
+        version: 0.19.0.rc1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.18.0.rc1
+        version: 0.19.0.rc1
 - !ruby/object:Gem::Dependency
   name: spyke
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +65,7 @@ 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