fmrest-core 0.15.0 → 0.17.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffafc2aecdab7b90059a7cc7a9a3687fbb557178d1cba164ca98feccf675cad1
-  data.tar.gz: df5a41ca5a2601a0bf4f9635ba42b14240aaeea10ced1b035a376fff12c0327e
+  metadata.gz: 312c477604d1cd806fd0e403222baf2485409ee15774b9b0a94da22dee585435
+  data.tar.gz: 2d229e1b3ad0ef228868c6298964a43e0a22ada7e23c8e00aa7d6b8b9be75e98
 SHA512:
-  metadata.gz: effc1532b7060e3167c726771bf057fa9154fd61e77517628e2d4ae9da716555e6bf0aa0a3fac29a1d5a7bbd6c6f53b9db138472af64b19b685e00d3a49ff52b
-  data.tar.gz: 3dc285d1ed51eb1a12203f90ad27655e8c24810391c0dbcb9223cbff80c0ed694c32ff86f6dd9f41f4170e399ec4aeabd79b7b4119b578fa3e1f9ef7e24ad500
+  metadata.gz: aad3c75eb9841885c78f9f0ed583ffc321eb66b1c2437181d84760cb44e52f4d27a3e4ce7d1c30c1697f77b36506075d98e3c925962ba90669198961497567a9
+  data.tar.gz: '0826d82c0a298a5a6ab0aec9f8fc582f73279d19e770080614f4faef368b21d646df33ac6065cf373ccd9e13e9ee6e2feefc66a3367e587883cfbd631dc52698'

data/.yardopts

@@ -1,4 +1,5 @@
 --markup markdown
 --plugin activesupport-concern
+lib/**/*.rb
 -
 docs/*

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## Changelog
 
+### 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
+
+* Fixed autoloading of `FmRest::Layout`
+
 ### 0.15.0
 
 * Much improved querying API (see documentation on querying), adding new
@@ -14,13 +29,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
@@ -35,7 +50,7 @@
 
 ### 0.11.1
 
-* Fix a couple crashes due to missing constants
+* Fixed a couple crashes due to missing constants
 
 ### 0.11.0
 
@@ -50,7 +65,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))
 
@@ -124,20 +139,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

@@ -2,6 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/fmrest.svg?style=flat)](https://rubygems.org/gems/fmrest)
 ![CI](https://github.com/beezwax/fmrest-ruby/workflows/CI/badge.svg)
+[![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)
@@ -9,7 +10,7 @@ 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 18's Data API.
+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.
 
@@ -124,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:
@@ -148,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"`
@@ -281,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
@@ -321,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
 
@@ -450,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.:
 
@@ -477,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.:
 
@@ -498,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                          |
@@ -552,6 +606,6 @@ See [LICENSE.txt](LICENSE.txt).
 
 ## Disclaimer
 
-This project is not sponsored by or otherwise affiliated with FileMaker, Inc,
-an Apple subsidiary. FileMaker is a trademark of FileMaker, Inc., registered in
-the U.S. and other countries.
+This project is not sponsored by or otherwise affiliated with Claris
+International Inc., an Apple Inc. subsidiary. FileMaker is a trademark of
+Claris International Inc., registered in the U.S. and other countries.

data/lib/fmrest.rb

@@ -11,12 +11,17 @@ module FmRest
   autoload :V1,         "fmrest/v1"
   autoload :TokenStore, "fmrest/token_store"
   autoload :Spyke,      "fmrest/spyke"
+  autoload :Layout,     "fmrest/spyke"
 
   class << self
     attr_accessor :token_store
+    attr_writer :logger
 
     def default_connection_settings=(settings)
-      @default_connection_settings = ConnectionSettings.wrap(settings, skip_validation: true)
+      # Skip validation since we may use the defaults for half-complete
+      # settings
+      @default_connection_settings =
+        ConnectionSettings.wrap(settings, skip_validation: true)
     end
 
     def default_connection_settings
@@ -33,6 +38,15 @@ module FmRest
       default_connection_settings
     end
 
+    def logger
+      @logger ||= if defined?(Rails)
+                    Rails.logger
+                  else
+                    require "logger"
+                    Logger.new($stdout)
+                  end
+    end
+
     # Shortcut for FmRest::V1.escape_find_operators
     #
     # @param (see FmRest::V1.escape_find_operators
@@ -40,5 +54,10 @@ module FmRest
     def e(s)
       V1.escape_find_operators(s)
     end
+
+    def Layout(*_)
+      require "fmrest/spyke"
+      self.Layout(*_)
+    end
   end
 end

data/lib/fmrest/connection_settings.rb

@@ -18,12 +18,14 @@ module FmRest
       database
       username
       password
+      fmid_token
       token
       token_store
       autologin
       ssl
       proxy
       log
+      log_level
       coerce_dates
       date_format
       timestamp_format
@@ -45,6 +47,7 @@ module FmRest
     DEFAULTS = {
       autologin:        true,
       log:              false,
+      log_level:        :debug,
       date_format:      DEFAULT_DATE_FORMAT,
       time_format:      DEFAULT_TIME_FORMAT,
       timestamp_format: DEFAULT_TIMESTAMP_FORMAT,
@@ -67,13 +70,12 @@ module FmRest
 
     PROPERTIES.each do |p|
       define_method(p) do
-        get(p)
+        get_eval(p)
       end
 
       define_method("#{p}!") do
-        r = get(p)
-        raise MissingSetting, "Missing required setting: `#{p}'" if r.nil?
-        r
+        raise MissingSetting, "Missing required setting: `#{p}'" if get(p).nil?
+        get_eval(p)
       end
 
       define_method("#{p}?") do
@@ -83,7 +85,7 @@ module FmRest
 
     def [](key)
       raise ArgumentError, "Unknown setting `#{key}'" unless PROPERTIES.include?(key.to_sym)
-      get(key)
+      get_eval(key)
     end
 
     def to_h
@@ -102,13 +104,18 @@ module FmRest
       missing = REQUIRED.select { |r| get(r).nil? }.map { |m| "`#{m}'" }
       raise MissingSetting, "Missing required setting(s): #{missing.join(', ')}" unless missing.empty?
 
-      unless username? || token?
-        raise MissingSetting, "A minimum of `username' or `token' are required to be able to establish a connection"
+      unless username? || fmid_token? || token?
+        raise MissingSetting, "A minimum of `username', `fmid_token' or `token' are required to be able to establish a connection"
       end
     end
 
     private
 
+    def get_eval(key)
+      c = get(key)
+      c.kind_of?(Proc) ? c.call : c
+    end
+
     def get(key)
       return @settings[key.to_sym] if @settings.has_key?(key.to_sym)
       return @settings[key.to_s] if @settings.has_key?(key.to_s)

data/lib/fmrest/v1/auth.rb

@@ -3,6 +3,8 @@
 module FmRest
   module V1
     module Auth
+      ACCESS_TOKEN_HEADER = "X-FM-Data-Access-Token"
+
       # Requests a token through basic auth
       #
       # @param connection [Faraday] the auth connection to use for
@@ -23,7 +25,7 @@ module FmRest
       # @raise [FmRest::APIError::AccountError] if authentication failed
       def request_auth_token!(connection = FmRest.V1.auth_connection)
         resp = connection.post(V1.session_path)
-        resp.body["response"]["token"]
+        resp.headers[ACCESS_TOKEN_HEADER] || resp.body["response"]["token"]
       end
     end
   end

data/lib/fmrest/v1/connection.rb

@@ -9,6 +9,7 @@ module FmRest
       DATABASES_PATH = "#{BASE_PATH}/databases"
 
       AUTH_HEADERS = { "Content-Type" => "application/json" }.freeze
+      CLARIS_ID_HTTP_AUTH_TYPE = "FMID"
 
       # Builds a complete DAPI Faraday connection with middleware already
       # configured to handle authentication, JSON parsing, logging and DAPI
@@ -41,7 +42,7 @@ module FmRest
           end
 
           if settings.log
-            conn.response :logger, nil, bodies: true, headers: true
+            conn.response :logger, FmRest.logger, bodies: true, headers: true, log_level: settings.log_level
           end
 
           conn.adapter Faraday.default_adapter
@@ -58,10 +59,14 @@ module FmRest
         base_connection(settings, { headers: AUTH_HEADERS }) do |conn|
           conn.use RaiseErrors
 
-          conn.basic_auth settings.username!, settings.password!
+          if settings.fmid_token?
+            conn.authorization CLARIS_ID_HTTP_AUTH_TYPE, settings.fmid_token
+          else
+            conn.basic_auth settings.username!, settings.password!
+          end
 
           if settings.log
-            conn.response :logger, nil, bodies: true, headers: true
+            conn.response :logger, FmRest.logger, bodies: true, headers: true, log_level: settings.log_level
           end
 
           conn.response :json

data/lib/fmrest/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FmRest
-  VERSION = "0.15.0"
+  VERSION = "0.17.0.rc1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fmrest-core
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.17.0.rc1
 platform: ruby
 authors:
 - Pedro Carbajal
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-04-01 00:00:00.000000000 Z
+date: 2021-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -104,11 +104,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 client using Faraday, core library