fmrest 0.9.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f96cf4500b2417bde1c853954dee03a362088adac933fc7d803d8e37e91cc8a
-  data.tar.gz: e6cd271dbfef1c87c04a515b8a22e7ead87ec88ab915b37245d4dcecc7c9a237
+  metadata.gz: 725c8356fc5933f0484f7d04a4458ecc85c638838c8d9869d039a6e09b0b15f6
+  data.tar.gz: 2a8047594d93d13b0f6d9981159c16b1afdcaa19713c054391fc08ca1fa68633
 SHA512:
-  metadata.gz: 68c4083e32e942fd609b050c2001d32b97c18d88ab70301f10ff0ce31527af2c5faff6e210afceaf152280dc2e0924a8edf2e2994e28ad331d2f015860f172f3
-  data.tar.gz: 9af1f38e2a59bda96639d6b6f1d3756b007a8c327392159f6288f2365161a94a211ff483744499771716e8e1d61cd8a57876fbfffcf7646e61db52d1794ab1a3
+  metadata.gz: 7a41a3e747bf6ccfe0de7e5541b0db35d30d9723b7a0eeb895fbe9e21f4c2c7e6f08ccd3012c1e6f4edaa5403966e2a7563b74490327c721990fbdd4ab79608a
+  data.tar.gz: 16fb2868c102905a58632b1183581dcf4617d4e6c9f7529abad12916b78b3c692d21a469eaf7b23101d53ff55e8c9ccbfc1167556cc09855516647ce00565ea8

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 ## Changelog
 
+### 0.12.0
+
+* Rename `FmRest::Spyke::Base#id=` to `FmRest::Spyke::Base#__record_id=` to
+  prevent clobbering of FileMaker layout-defined fields
+* Better yard documentation
+
+### 0.11.1
+
+* Fix a couple crashes due to missing constants
+
+### 0.11.0
+
+* Added custom class for connection settings, providing indifferent access
+  (i.e. keys can be strings or symbols), and centralized default values and
+  validations
+* Added `:autologin`, `:token` and `:token_store` connection settings
+* Added `FmRest::Base.fmrest_config_overlay=` and related methods
+* Added `FmRest::V1.request_auth_token` and
+  `FmRest::Spyke::Base.request_auth_token` (as well as `!`-suffixed versions
+  which raise exceptions on failure)
+
+### 0.10.1
+
+* Fix `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))
+
+### 0.10.0
+
+* Added `FmRest::StringDateAwareness` module to correct some issues when using
+  `FmRest::StringDate`
+* Added basic timezones support
+* Deprecated `class < FmRest::Spyke::Base(config_hash)` syntax in favor of
+  using `self.fmrest_config=`
+
 ### 0.9.0
 
 * Added `FmRest::Spyke::Base.set_globals`

data/README.md

@@ -1,9 +1,10 @@
 # fmrest-ruby
 
-<a href="https://rubygems.org/gems/fmrest"><img src="https://badge.fury.io/rb/fmrest.svg?style=flat" alt="Gem Version"></a>
+[![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)
 
 A Ruby client for
-[FileMaker 18's Data API](https://fmhelp.filemaker.com/docs/18/en/dataapi/)
+[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
 [Spyke](https://github.com/balvig/spyke) support (ActiveRecord-ish models).
@@ -120,6 +121,9 @@ Option              | Description                                | Format
 `: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"`
 `:time_format`      | Time parsing format                        | String (FM date format)     | `"HH:mm:ss"`
+`: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
 
 ### Default connection settings
 
@@ -270,9 +274,9 @@ a DSL in model classes).
 ### Hybrid string/date objects
 
 `FmRest::StringDate` and `FmRest::StringDateTime` are special classes that
-inherit from `String`, but internally parse and store a `Date`/`DateTime`
-(respectively), and delegate any methods not provided by `String` to those
-objects. In other words, they quack like a duck *and* bark like a dog.
+inherit from `String`, but internally parse and store a `Date` or `DateTime`,
+and delegate any methods not provided by `String` to those objects. In other
+words, they quack like a duck *and* bark like a dog.
 
 You can use these when you want fmrest-ruby to provide you with date objects,
 but you don't want to worry about date coercion of false positives (i.e. a
@@ -280,7 +284,29 @@ string field that gets converted to `Date` because it just so matched the given
 date format).
 
 Be warned however that these classes come with a fair share of known gotchas
-(see GitHub wiki for more info).
+(see GitHub wiki for more info). Some of those gothas can be removed by calling
+
+```ruby
+FmRest::StringDateAwareness.enable
+```
+
+Which will extend the core `Date` and `DateTime` classes to be aware of
+`FmRest::StringDate`, especially when calling `Date.===`, `Date.parse` or
+`Date._parse`.
+
+If you're working with ActiveRecord models this will also make them accept
+`FmRest::StringDate` values for date fields.
+
+### Timezones
+
+fmrest-ruby has basic timezone support. You can set the `:timezone` option in
+your connection settings to one of the following values:
+
+* `:local` - dates will be converted to your system local time offset (as
+  defined by `ENV["TZ"]`), or the timezone set by `Time.zone` if you're using
+  ActiveSupport
+* `:utc` - dates will be converted to UTC offset
+* `nil` - (default) ignore timezones altogether
 
 
 ## Spyke support (ActiveRecord-like ORM)
@@ -322,17 +348,6 @@ class Honeybee < FmRest::Spyke::Base
 end
 ```
 
-In this case you can pass the [`fmrest_config`](#modelfmrest_config) hash as an
-argument to `Base()`:
-
-```ruby
-class Honeybee < FmRest::Spyke::Base(host: "...", database: "...", username: "...", password: "...")
-end
-
-Honeybee.fmrest_config
-# => { host: "...", database: "...", username: "...", password: "..." }
-```
-
 All of Spyke's basic ORM operations work:
 
 ```ruby
@@ -406,6 +421,59 @@ class Honeybee < BeeBase
 end
 ```
 
+### Model.fmrest_config_overlay=
+
+There may be cases where you want to use different connection settings
+depending on context, for example if you want to use username and password
+provided by the user in a web application. Since `Model.fmrest_config` is
+global, changing the username/password for one context would also change it for
+all other contexts, leading to security issues.
+
+`Model.fmrest_config_overlay=` solves that issue by allowing you to override
+some settings in a thread-local and reversible manner. That way, using the same
+example as above, you could connect to the Data API with user-provided
+credentials without having them leak into other users of your web application.
+
+E.g.:
+
+```ruby
+class BeeBase < Spyke::Base
+  include FmRest::Spyke
+
+  # Host and database provided as base settings
+  self.fmrest_config = {
+    host:     "example.com",
+    database: "My Database"
+  }
+end
+
+# E.g. in a controller-action of a Rails application:
+
+# User-provided credentials
+BeeBase.fmrest_config_overlay = {
+  username: params[:username],
+  password: params[:password]
+}
+
+# Perform some Data API requests ...
+```
+
+### Model.clear_fmrest_config_overlay
+
+Clears the thread-local settings provided to `fmrest_config_overaly=`.
+
+### Model.with_overlay
+
+Runs a block with the given settings overlay, resetting them after the block
+finishes running. It wraps execution in its own fiber, so it doesn't affect the
+overlay of the currently-running thread.
+
+```ruby
+Honeybee.with_overlay(username: "...", password: "...") do
+  Honeybee.query(...)
+end
+```
+
 ### Model.layout
 
 Use `layout` to set the `:layout` part of API URLs, e.g.:
@@ -422,6 +490,15 @@ Data API models.
 Note that you only need to set this if the name of the model and the name of
 the layout differ, otherwise the default will just work.
 
+### Model.request_auth_token
+
+Requests a Data API session token using the connection settings in
+`fmrest_config` and returns it if successful, otherwise returns `false`.
+
+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`).
+
 ### Model.logout
 
 Use `logout` to log out from the database session (you may call it on any model

data/UPGRADING

@@ -0,0 +1,15 @@
+=======================================
+ Notes on upgrading from fmrest < 0.12
+=======================================
+
+There's a small breaking change in fmrest 0.12 that will most likely not affect
+you, but you may want to be aware of:
+
+Previous to this version the record ID on an FmRest::Spyke::Base instance could
+be set with `id=`. This caused problems in cases where a FileMaker layout had a
+field named `id`, so `id=` got renamed to `__record_id=`. Setting the record ID
+by hand however isn't something useful or that should be done at all, so it's
+very unlikely that this change will affect your existing code at all.
+
+Thanks for using fmrest-ruby!
+

data/fmrest.gemspec

@@ -14,23 +14,34 @@ Gem::Specification.new do |spec|
   spec.license       = "MIT"
 
   spec.files         = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features|bin)/})
+    f.match(%r{^(\.github|test|spec|features|bin)/})
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  if File.exist?('UPGRADING')
+    spec.post_install_message = File.read("UPGRADING")
+  end
+
   spec.add_dependency 'faraday', '>= 0.9.0', '< 2.0'
   spec.add_dependency 'faraday_middleware', '>= 0.9.1', '< 2.0'
 
-  spec.add_development_dependency "bundler", "~> 1.16"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "spyke"
+  spec.add_development_dependency "spyke", ">= 5.3.3"
   spec.add_development_dependency "webmock"
   spec.add_development_dependency "pry-byebug"
   spec.add_development_dependency "activerecord", ENV["ACTIVE_RECORD_VERSION"]
-  spec.add_development_dependency "sqlite3", ENV["SQLITE3_VERSION"]
+
+  sqlite3_version = if (4.2..5.2).include?(ENV["ACTIVE_RECORD_VERSION"].to_s.gsub(/[^\d.]/, "").to_f)
+                      "~> 1.3.0"
+                    else
+                      "~> 1.4.0"
+                    end
+
+  spec.add_development_dependency "sqlite3", sqlite3_version
   spec.add_development_dependency "mock_redis"
   spec.add_development_dependency "moneta"
   spec.add_development_dependency "yard"

data/lib/fmrest.rb

@@ -4,16 +4,23 @@ require "faraday"
 require "faraday_middleware"
 
 require "fmrest/version"
-require "fmrest/v1"
+require "fmrest/connection_settings"
+
+require "fmrest/errors"
 
 module FmRest
+  autoload :V1,         "fmrest/v1"
+  autoload :TokenStore, "fmrest/token_store"
+
   class << self
     attr_accessor :token_store
 
-    attr_writer :default_connection_settings
+    def default_connection_settings=(settings)
+      @default_connection_settings = ConnectionSettings.wrap(settings, skip_validation: true)
+    end
 
     def default_connection_settings
-      @default_connection_settings || {}
+      @default_connection_settings || ConnectionSettings.new({}, skip_validation: true)
     end
 
     def config=(connection_hash)

data/lib/fmrest/connection_settings.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module FmRest
+  # Wrapper class for connection settings hash, with a number of purposes:
+  #
+  # * Provide indifferent access (base hash can have either string or symbol
+  #   keys)
+  # * Method access
+  # * Default values
+  # * Basic validation
+  # * Normalization (e.g. aliased settings)
+  # * Useful error messages
+  class ConnectionSettings
+    class MissingSetting < ArgumentError; end
+
+    PROPERTIES = %i(
+      host
+      database
+      username
+      password
+      token
+      token_store
+      autologin
+      ssl
+      proxy
+      log
+      coerce_dates
+      date_format
+      timestamp_format
+      time_format
+      timezone
+    ).freeze
+
+    # NOTE: password intentionally left non-required since it's only really
+    # needed when no token exists, and should only be required when logging in
+    REQUIRED = %i(
+      host
+      database
+    ).freeze
+
+    DEFAULT_DATE_FORMAT = "MM/dd/yyyy"
+    DEFAULT_TIME_FORMAT = "HH:mm:ss"
+    DEFAULT_TIMESTAMP_FORMAT = "#{DEFAULT_DATE_FORMAT} #{DEFAULT_TIME_FORMAT}"
+
+    DEFAULTS = {
+      autologin:        true,
+      log:              false,
+      date_format:      DEFAULT_DATE_FORMAT,
+      time_format:      DEFAULT_TIME_FORMAT,
+      timestamp_format: DEFAULT_TIMESTAMP_FORMAT,
+      coerce_dates:     false
+    }.freeze
+
+    def self.wrap(settings, skip_validation: false)
+      if settings.kind_of?(self)
+        settings.validate unless skip_validation
+        return settings
+      end
+      new(settings, skip_validation: skip_validation)
+    end
+
+    def initialize(settings, skip_validation: false)
+      @settings = settings.to_h.dup
+      normalize
+      validate unless skip_validation
+    end
+
+    PROPERTIES.each do |p|
+      define_method(p) do
+        get(p)
+      end
+
+      define_method("#{p}!") do
+        r = get(p)
+        raise MissingSetting, "Missing required setting: `#{p}'" if r.nil?
+        r
+      end
+
+      define_method("#{p}?") do
+        !!get(p)
+      end
+    end
+
+    def [](key)
+      raise ArgumentError, "Unknown setting `#{key}'" unless PROPERTIES.include?(key.to_sym)
+      get(key)
+    end
+
+    def to_h
+      PROPERTIES.each_with_object({}) do |p, h|
+        v = get(p)
+        h[p] = v unless v == DEFAULTS[p]
+      end
+    end
+
+    def merge(other, **keyword_args)
+      other = self.class.wrap(other, skip_validation: true)
+      self.class.new(to_h.merge(other.to_h), **keyword_args)
+    end
+
+    def validate
+      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"
+      end
+    end
+
+    private
+
+    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)
+      DEFAULTS[key.to_sym]
+    end
+
+    def normalize
+      if !get(:username) && account_name = get(:account_name)
+        @settings[:username] = account_name
+      end
+    end
+  end
+end

data/lib/fmrest/errors.rb

@@ -21,6 +21,8 @@ module FmRest
   class APIError::NoMatchingRecordsError < APIError::ParameterError; end
   class APIError::ValidationError < APIError; end      # error codes 500..599
   class APIError::SystemError < APIError; end          # error codes 800..899
+  class APIError::InvalidToken < APIError; end         # error code 952
+  class APIError::MaximumDataAPICallsExceeded < APIError; end # error code 953
   class APIError::ScriptError < APIError; end          # error codes 1200..1299
   class APIError::ODBCError < APIError; end            # error codes 1400..1499
 

data/lib/fmrest/spyke/base.rb

@@ -5,17 +5,5 @@ module FmRest
     class Base < ::Spyke::Base
       include FmRest::Spyke::Model
     end
-
-    class << self
-      def Base(config = nil)
-        if config
-          return Class.new(::FmRest::Spyke::Base) do
-                   self.fmrest_config = config
-                 end
-        end
-
-        ::FmRest::Spyke::Base
-      end
-    end
   end
 end