fmrest 0.7.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 94745e25176074d96540a4a7659dce7ee15d6ea88867a58c35c3f38af8cd466f
-  data.tar.gz: 512669f188c9abe0c403318d50da19ac5376b6cc6bed74880eff9aebb5d642af
+  metadata.gz: e6433cf32d6d0111377f6080967e96fd5ff4cd54c5e223551c777a24c58e8662
+  data.tar.gz: 1a0fcd5951ab9b5bee88d822a429f16b02dcb01d5c95f74de9d529bb1ed00278
 SHA512:
-  metadata.gz: 620ee792b4b585d80358857d5464870c3384211d4311385a034ff6b941c40672d48bfa9f42b48935885131c2fe579d8a51b7e84544dbe08483d467d27966ba0c
-  data.tar.gz: e422690817ba000c9bbecd828a0c58118e223238ba44b76e86a6160cd87cb854cad0a584efd7932237cb58f125a5e567f292c0849022b897dc3f4c89ab66d96d
+  metadata.gz: a0130f8b3598b3723d3c9e2514448a44a10381045176894cfed21244547c7ed41d0bc83fd18ab40981e9a2fc9ac7bd5c7290a5026b301878ea2c1d9ec440bb76
+  data.tar.gz: 0fc6a827bb57dea0b261bb812b58322dad8a01eecf78a4344bef877732f4f0b016636750833c048c5831e63e5015c707264a0697282cc7fba9a6879a0cd7e8b1

data/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: CI
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+    # uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@ec106b438a1ff6ff109590de34ddc62c540232e0
+      with:
+        ruby-version: 2.6
+    - name: Install dependencies
+      run: bundle install
+    - name: Run specs
+      run: bundle exec rspec spec

data/CHANGELOG.md

@@ -1,5 +1,42 @@
 ## Changelog
 
+### 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`
+
+### 0.8.0
+
+* Improved metadata when using `FmRest::Spyke::Model`. Metadata now uses
+  Struct/OpenStruct, so properties are accessible through `.property`, as well
+  as `[:property]`
+* Added batch-finders `.find_in_batches` and `.find_each` for
+* `FmRest::Spyke::Base`
+
 ### 0.7.1
 
 * Made sure `Model.find_one` and `Model.find_some` work without needing to call

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
 
@@ -195,7 +199,7 @@ FmRest.token_store = FmRest::TokenStore::Redis.new(redis: Redis.new, prefix: "my
 FmRest.token_store = FmRest::TokenStore::Redis.new(prefix: "my-fancy-prefix:", host: "10.0.1.1", port: 6380, db: 15)
 ```
 
-**NOTE:** redis-rb is not included as a gem dependency of fmrest-ruby, so you'll
+NOTE: redis-rb is not included as a gem dependency of fmrest-ruby, so you'll
 have to add it to your Gemfile.
 
 ### Moneta
@@ -232,7 +236,7 @@ FmRest.token_store = FmRest::TokenStore::Moneta.new(
 )
 ```
 
-**NOTE:** the moneta gem is not included as a dependency of fmrest-ruby, so
+NOTE: the moneta gem is not included as a dependency of fmrest-ruby, so
 you'll have to add it to your Gemfile.
 
 
@@ -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
@@ -555,7 +632,7 @@ Honeybee.limit(10)
 ```
 
 NOTE: You can also set a default limit value for a model class, see
-[Other notes on querying](#other-notes-on-querying).
+[other notes on querying](#other-notes-on-querying).
 
 You can also use `.limit` to set limits on portals:
 
@@ -727,15 +804,15 @@ the scope object:
 Honeybee.limit(10).sort(:name).find_some # => [<Honeybee...>, ...]
 ```
 
-If you want just a single result you can use `.find_one` instead (this will
+If you want just a single result you can use `.first` instead (this will
 force `.limit(1)`):
 
 ```ruby
-Honeybee.query(name: "Hutch").find_one # => <Honeybee...>
+Honeybee.query(name: "Hutch").first # => <Honeybee...>
 ```
 
 If you know the id of the record you should use `.find(id)` instead of
-`.query(id: id).find_one` (so that the sent request is
+`.query(id: id).first` (so that the sent request is
 `GET ../:layout/records/:id` instead of `POST ../:layout/_find`).
 
 ```ruby
@@ -746,6 +823,52 @@ Note also that if you use `.find(id)` your `.query()` parameters (as well as
 limit, offset and sort parameters) will be discarded as they're not supported
 by the single record endpoint.
 
+
+### Finding records in batches
+
+Sometimes you want to iterate over a very large number of records to do some
+processing, but requesting them all at once would result in one huge request to
+the Data API, and loading too many records in memory all at once.
+
+To mitigate this problem you can use `.find_in_batches` and `.find_each`. If
+you've used ActiveRecord you're probably familiar with how they operate:
+
+```ruby
+# Find records in batches of 100 each
+Honeybee.query(hive: "Queensville").find_in_batches(batch_size: 100) do |batch|
+  dispatch_bees(batch)
+end
+
+# Iterate over all records using batches
+Honeybee.query(hive: "Queensville").find_each(batch_size: 100) do |bee|
+  bee.dispatch
+end
+```
+
+`.find_in_batches` yields collections of records (batches), while `.find_each`
+yields individual records, but using batches behind the scenes.
+
+Both methods accept a block-less form in which case they return an
+`Enumerator`:
+
+```ruby
+batch_enum = Honeybee.find_in_batches
+
+batch = batch_enum.next # => Spyke::Collection
+
+batch_enum.each do |batch|
+  process_batch(batch)
+end
+
+record_enum = Honeybee.find_each
+
+record_enum.next # => Honeybee
+```
+
+NOTE: By its nature, batch processing is subject to race conditions if other
+processes are modifying the database.
+
+
 ### Container fields
 
 You can define container fields on your model class with `container`:
@@ -783,6 +906,7 @@ bee.photo.upload(filename_or_io) # Upload a file to the container
 * `:content_type` - The MIME content type to use (defaults to
   `application/octet-stream`)
 
+
 ### Script execution
 
 The Data API allows running scripts as part of many types of requests.
@@ -870,7 +994,7 @@ separately, under their matching key.
 ```ruby
 bee.save(script: { presort: "My Presort Script", after: "My Script" })
 
-Honeybee.last_request_metadata[:script]
+Honeybee.last_request_metadata.script
 # => { after: { result: "oh hi", error: "0" }, presort: { result: "lo", error: "0" } }
 ```
 
@@ -884,7 +1008,7 @@ is performed on that scope.
 
 ```ruby
 # Find one Honeybee record executing a presort and after script
-Honeybee.script(presort: ["My Presort Script", "parameter"], after: "My Script").find_one
+Honeybee.script(presort: ["My Presort Script", "parameter"], after: "My Script").first
 ```
 
 The model class' `.last_request_metadata` will be set in case you need to get the result.
@@ -896,6 +1020,32 @@ to retrieving single records, in that case you'll have to use
 `.last_request_metadata`.
 
 
+### Setting global field values
+
+You can call `.set_globals` on any `FmRest::Spyke::Base` model to set glabal
+field values on the database that model is configured for.
+
+You can pass it either a hash of fully qualified field names
+(table_name::field_name), or 1-level-deep nested hashes, with the outer being a
+table name and the inner keys being the field names:
+
+```ruby
+Honeybee.set_globals(
+  "beeTable::myVar"      => "value",
+  "beeTable::myOtherVar" => "also a value"
+)
+
+# Equivalent to the above example
+Honeybee.set_globals(beeTable: { myVar: "value", myOtherVar: "also a value" })
+
+# Combined
+Honeybee.set_globals(
+  "beeTable::myVar" => "value",
+  beeTable: { myOtherVar: "also a value" }
+)
+```
+
+
 ## Logging
 
 If using fmrest-ruby + Spyke in a Rails app pretty log output will be set up
@@ -964,7 +1114,7 @@ FM Data API reference: https://fmhelp.filemaker.com/docs/18/en/dataapi/
 | Get container data                  | Manual*                       | Yes                              |
 | Upload container data               | Manual*                       | Yes                              |
 | Perform a find request              | Manual*                       | Yes                              |
-| Set global field values             | Manual*                       | No                               |
+| Set global field values             | Manual*                       | Yes
 | Run a script                        | Manual*                       | Yes                              |
 | Run a script with another request   | Manual*                       | Yes                              |
 

data/fmrest.gemspec

@@ -23,8 +23,8 @@ Gem::Specification.new do |spec|
   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 "webmock"

data/lib/fmrest.rb

@@ -4,16 +4,21 @@ require "faraday"
 require "faraday_middleware"
 
 require "fmrest/version"
-require "fmrest/v1"
+require "fmrest/connection_settings"
 
 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