fmrest 0.8.0 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5873c0192a2b166cfef71b33c521665dd6953660bd9d23d3ef728b89c55e886f
-  data.tar.gz: 7615faa115cc7506d3a472d2fac70ea293bd3dbec1e03bb3c19f0faca51b7c9d
+  metadata.gz: d087824f401c6c36c5f0ac00acf9e3ee12fced43d002000533ba0b97e579d89d
+  data.tar.gz: 2c3f0018686f48f02c6e177cc10ba0cbdecd584523776c9269023bb7192eb271
 SHA512:
-  metadata.gz: b627994fa66842be8200692895077649837a7b343c337aaf5762926c633de02baf14ba6428cc33b8b3cc0d0314d7d62a4f6cf16173edb09d32ba8218c533d7d6
-  data.tar.gz: 2cd9e7f7003f9ec05120587f50ee892076d8e02045a6b18e9311276792bf831dee6c4434969990b17f4f5898f95040da0614aabbdb5940fa8906f3c507f7f0e8
+  metadata.gz: 9746926229c22793428d1c0d76c7d0b373cee751c15d83389e3a426ca434773524e1f8133d65914b0301d47c7e6c22f893f14850377bb8b665f065ce377f972f
+  data.tar.gz: a8d32edd04361bb9a4f8add3cc8ecd9e89cf1bcbcf0437cfcc3d30cba652c67b935d58091246f1657041dc0678ce0b01c3685d300b6a699fea3bb73dfb131846

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,11 +1,45 @@
 ## Changelog
 
+### 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`
+
 ### 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]`
-* Implemented `.find_in_batches` and `.find_each` for `FmRest::Spyke::Model`
+* Added batch-finders `.find_in_batches` and `.find_each` for
+* `FmRest::Spyke::Base`
 
 ### 0.7.1
 

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
@@ -943,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
@@ -1011,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,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