fmrest-core 0.13.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f3df4def4688541f93d0c0ab3cdf2ec4aa61424cf5304d668190e270b5d8a98e
+  data.tar.gz: e1e7935827cb2720ea008b6f563ee24881c12d9d437f81163101796a7bc4d781
+SHA512:
+  metadata.gz: 3cf8c4fb66bb25d6a78e794572b243b2afaad2fabed94f73fb499776d4227b0a90b0fa9bf7068dce0f8cdac9d13c70302aed142e73d62c818ae6ad4c28f23600
+  data.tar.gz: c58374f6976087b957c6dd1689b1db447e99490c6f141effc2a2f14540f81bac1c7bf79dc4beec62d437dce4385d704f53bffc919a26d5ad38a660bb763f6fe2

data/.yardopts

@@ -0,0 +1,4 @@
+--markup markdown
+--plugin activesupport-concern
+-
+docs/*

data/CHANGELOG.md

@@ -0,0 +1,127 @@
+## Changelog
+
+### 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.
+* 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
+  always return integers if set.
+
+### 0.12.0
+
+* Rename `FmRest::Spyke::Base#id=` to `FmRest::Spyke::Base#__record_id=` to
+  prevent clobbering of FileMaker layout-defined fields
+* Removed previously deprecated `FmRest::Spyke::Base(config)` syntax
+* 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`
+
+### 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
+  `Model.all` in between
+
+### 0.7.0
+
+* Added date coercion feature
+
+### 0.6.0
+
+* Implemented session logout
+  ([#16](https://github.com/beezwax/fmrest-ruby/issues/16))
+
+### 0.5.2
+
+* Improved support for legacy ActiveModel 4.x
+
+### 0.5.1
+
+* Alias `:username` option as `:account_name` for ginjo-rfm gem
+  cross-compatibility
+
+### 0.5.0
+
+* Much improved script execution support
+  ([#20](https://github.com/beezwax/fmrest-ruby/issues/20))
+* Fixed bug when setting `default_limi` and trying to find a record
+  ([35](https://github.com/beezwax/fmrest-ruby/issues/35))
+
+### 0.4.1
+
+* Prevent raising an exception when a /\_find request yields no results
+  ([#33](https://github.com/beezwax/fmrest-ruby/issues/33) and
+  [#34](https://github.com/beezwax/fmrest-ruby/issues/34))
+
+### 0.4.0
+
+* Implement ability to set limit and offset for portals
+* Implement disabling and requesting all portals
+
+### 0.3.3
+
+* Fix encoding of paths for layouts with brackets in them (e.g. `"\[Very Ugly\]
+  Layout"`)
+* Raise an error if `"id"` is assigned as an attribute on a model, as it's
+  currently a reserved method name by Spyke
+
+### 0.3.2
+
+* Fix support for ActiveSupport < 5.2
+  ([#27](https://github.com/beezwax/fmrest-ruby/issues/27))
+
+### 0.3.0
+
+* Add Moneta token store
+
+### 0.2.5
+
+* Fix 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`
+* Honor Faraday SSL and proxy settings when fetching container files

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Pedro Carbajal and Beezwax Datatools, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,523 @@
+# fmrest-ruby
+
+[![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 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 18'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.
+
+## Gems
+
+The `fmrest` gem is a wrapper for two other gems:
+
+* `fmrest-core`, which provides the core Faraday connection builder, session
+  management, and other core utilities.
+* `fmrest-spyke`, which provides an ActiveRecord-like ORM library built on top
+  of `fmrest-core` and Spyke.
+
+## Installation
+
+Add this to your Gemfile:
+
+```ruby
+gem 'fmrest'
+```
+
+Or if you just want to use the Faraday connection without the ORM features, do:
+
+```ruby
+gem 'fmrest-core'
+```
+
+## Simple examples
+
+### ORM example
+
+Most people would want to use the ORM features provided by `fmrest-spyke`:
+
+```ruby
+class Honeybee < FmRest::Spyke::Base
+  # Connection settings
+  self.fmrest_config = {
+    host:     "…",
+    database: "…",
+    username: "…",
+    password: "…"
+  }
+
+  # Mapped attributes
+  attributes name: "Bee Name", age: "Bee Age"
+
+  # Portals
+  has_portal :flowers
+
+  # File container
+  container :photo, field_name: "Bee Photo"
+end
+
+# Find a record by id
+bee = Honeybee.find(9)
+
+bee.name = "Hutch"
+
+# Add a new record to portal
+bee.flowers.build(name: "Daisy")
+
+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/MyFancyLayout/records")
+
+# Create new record
+connection.post do |req|
+  req.url "layouts/MyFancyLayout/records"
+
+  # You can just pass a hash for the JSON body
+  req.body = { … }
+end
+```
+
+See the [main document on using the base
+connection](docs/BaseConnectionUsage.md) for more.
+
+## Connection settings
+
+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).
+
+`: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:
+
+```ruby
+{
+  host: "…",
+  …
+  ssl:  { verify: false }
+}
+```
+
+You can also pass a `:log` option for basic request logging, see the section on
+[Logging](#Logging) below.
+
+### Full list of available options
+
+Option              | Description                                | Format                      | Default
+--------------------|--------------------------------------------|-----------------------------|--------
+`:host`             | Hostname with optional port, e.g. `"example.com:9000"` | String          | None
+`:database`         |                                            | String                      | None
+`:username`         |                                            | String                      | None
+`:password`         |                                            | String                      | None
+`:account_name`     | Alias of `:username`                       | 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`
+`: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"`
+`: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
+
+If you're only connecting to a single FM database you can configure it globally
+through `FmRest.default_connection_settings=`. E.g.:
+
+```ruby
+FmRest.default_connection_settings = {
+  host:     "…",
+  database: "…",
+  username: "…",
+  password: "…"
+}
+```
+
+These settings will be used by default by `FmRest::Spyke::Base` models whenever
+you don't set `fmrest_config=` explicitly, as well as by
+`FmRest::V1.build_connection` in case you're setting up your Faraday connection
+manually.
+
+## Session token store
+
+fmrest-ruby includes a number of options for storing session tokens:
+
+* Memory
+* ActiveRecord
+* Redis
+* Moneta
+
+See the [main document on token stores](docs/TokenStore.md) for detailed info
+on how to set up each store.
+
+## Date fields and timezones
+
+fmrest-ruby has automatic detection and coercion of date fields to and from
+Ruby date/time objects. Basic timezone support is also provided.
+
+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,
+bundled in the `fmrest-spyke` gem (already included if you're using the
+`fmrest` gem).
+
+To create a model you can inherit directly from `FmRest::Spyke::Base`, which is
+itself a subclass of `Spyke::Base`.
+
+```ruby
+class Honeybee < FmRest::Spyke::Base
+end
+```
+
+All of Spyke's basic ORM operations work as expected:
+
+```ruby
+bee = Honeybee.new
+
+bee.name = "Hutch"
+bee.save # POST request (creates new record)
+
+bee.name = "ハッチ"
+bee.save # PATCH request (updates existing record)
+
+bee.reload # GET request
+
+bee.destroy # DELETE request
+
+bee = Honeybee.find(9) # GET request
+```
+
+It's recommended that you read Spyke's documentation for more information on
+these basic features. If you've used ActiveRecord or similar ORM libraries
+however you'll find it quite familiar.
+
+In addition, `FmRest::Spyke::Base` extends `Spyke::Base` with the following
+features:
+
+### Model.fmrest_config=
+
+This allows you to set your Data API connection settings on your model:
+
+```ruby
+class Honeybee < FmRest::Spyke::Base
+  self.fmrest_config = {
+    host:     "…",
+    database: "…",
+    username: "…",
+    password: "…"
+  }
+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
+does the initial connection setup and then inherit from it in models using that
+same connection. E.g.:
+
+```ruby
+class BeeBase < FmRest::Spyke::Base
+  self.fmrest_config = { host: "…", … }
+  }
+end
+
+class Honeybee < BeeBase
+  # This model will use the same connection as BeeBase
+end
+```
+
+#### 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 `Model.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 `Model.fmrest_config_overlay=`.
+
+See the [main document on connection setting overlays](docs/ConfigOverlays.md)
+for details on how it works.
+
+### Model.layout
+
+Use `Model.layout` to define the layout for your model.
+
+```ruby
+class Honeybee < FmRest::Spyke::Base
+  layout "Honeybees Web"
+end
+```
+
+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 `Model.logout` to log out from the database session (you may call it on any
+model that uses the database session you want to log out from).
+
+```ruby
+Honeybee.logout
+```
+
+### Mapped Model.attributes
+
+Spyke allows you to define your model's attributes using `attributes`, however
+sometimes FileMaker's field names aren't very Ruby-ORM-friendly, especially
+since they may sometimes contain spaces and other special characters, so
+fmrest-ruby extends `attributes`' functionality to allow you to map
+Ruby-friendly attribute names to FileMaker field names. E.g.:
+
+```ruby
+class Honeybee < FmRest::Spyke::Base
+  attributes first_name: "First Name", last_name: "Last Name"
+end
+```
+
+You can then simply use the pretty attribute names whenever working with your
+model and they will get mapped to their FileMaker fields:
+
+```ruby
+bee = Honeybee.find(1)
+
+bee.first_name # => "Princess"
+bee.last_name  # => "Buzz"
+
+bee.first_name = "Queen"
+
+bee.attributes # => { "First Name": "Queen", "Last Name": "Buzz" }
+```
+
+### Model.has_portal
+
+You can define portal associations on your model wth `has_portal`, as such:
+
+```ruby
+class Honeybee < FmRest::Spyke::Base
+  has_portal :flowers
+end
+
+class Flower < FmRest::Spyke::Base
+  attributes :color, :species
+end
+```
+
+See the [main document on portal associations](docs/Portals.md) for details.
+
+### Dirty attributes
+
+fmrest-ruby includes support for ActiveModel's Dirty mixin out of the box,
+providing methods like:
+
+```ruby
+bee = Honeybee.new
+
+bee.changed? # => false
+
+bee.name = "Maya"
+
+bee.changed? # => true
+
+bee.name_changed? # => true
+```
+
+fmrest-ruby uses the Dirty functionality to only send changed attributes back
+to the server on save.
+
+You can read more about [ActiveModel's Dirty in Rails
+Guides](https://guides.rubyonrails.org/active_model_basics.html#dirty).
+
+### Query API
+
+Since Spyke is API-agnostic it only provides a wide-purpose `.where` method for
+passing arbitrary parameters to the REST backend. fmrest-ruby however is well
+aware of its backend API, so it extends Spkye models with a bunch of useful
+querying methods: `.query`, `.limit`, `.offset`, `.sort`, `.portal`, `.script`,
+etc.
+
+See the [main document on querying](docs/Querying.md) for detailed information
+on the query API methods.
+
+### 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`.
+
+See the [main document on finding in batches](docs/FindInBatches.md) for
+detailed information on how those work.
+
+### Container fields
+
+You can define container fields on your model class with `container`:
+
+```ruby
+class Honeybee < FmRest::Spyke::Base
+  container :photo, field_name: "Beehive Photo ID"
+end
+```
+
+See the [main document on container fields](docs/ContainerFields.md) for
+details on how to use it.
+
+### Script execution
+
+The FM Data API allows running scripts as part of many types of requests, and
+`fmrest-spyke` provides mechanisms for all of them.
+
+See the [main document on script execution](docs/ScriptExecution.md) for
+details.
+
+### Setting global field values
+
+You can call `.set_globals` on any `FmRest::Spyke::Base` model to set global
+field values on the database that model is configured for.
+
+See the [main document on setting global field values](docs/GlobalFields.md)
+for details.
+
+## 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
+debugging) by passing `log: true` in the options hash for either
+`FmRest.default_connection_settings=` or your models' `fmrest_config=`, e.g.:
+
+```ruby
+FmRest.default_connection_settings = {
+  host: "…",
+  …
+  log:  true
+}
+
+# Or in your model
+class LoggyBee < FmRest::Spyke::Base
+  self.fmrest_config = {
+    host: "…",
+    …
+    log:  true
+  }
+end
+```
+
+If you need to set up more complex logging for your models can use the
+`faraday` block inside your class to inject your own logger middleware into the
+Faraday connection, e.g.:
+
+```ruby
+class LoggyBee < FmRest::Spyke::Base
+  faraday do |conn|
+    conn.response :logger, MyApp.logger, bodies: true
+  end
+end
+```
+
+## API implementation completeness table
+
+FM Data API reference: https://fmhelp.filemaker.com/docs/18/en/dataapi/
+
+| FM 18 Data API feature              | Supported by basic connection | Supported by FmRest::Spyke::Base |
+|-------------------------------------|-------------------------------|----------------------------------|
+| 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 out                             | Yes                           | Yes                              |
+| Get product information             | Manual*                       | No                               |
+| Get database names                  | Manual*                       | No                               |
+| Get script names                    | Manual*                       | No                               |
+| Get layout names                    | Manual*                       | No                               |
+| Get layout metadata                 | Manual*                       | No                               |
+| Create a record                     | Manual*                       | Yes                              |
+| Edit a record                       | Manual*                       | Yes                              |
+| Duplicate a record                  | Manual*                       | No                               |
+| Delete a record                     | Manual*                       | Yes                              |
+| Edit portal records                 | Manual*                       | Yes                              |
+| Get a single record                 | Manual*                       | Yes                              |
+| Get a range of records              | Manual*                       | Yes                              |
+| Get container data                  | Manual*                       | Yes                              |
+| Upload container data               | Manual*                       | Yes                              |
+| Perform a find request              | Manual*                       | Yes                              |
+| Set global field values             | Manual*                       | Yes                              |
+| Run a script                        | Manual*                       | Yes                              |
+| Run a script with another request   | Manual*                       | Yes                              |
+
+\* You can manually supply the URL and JSON to a `FmRest` connection.
+
+## Supported Ruby versions
+
+fmrest-ruby aims to support and is [tested against](https://github.com/beezwax/fmrest-ruby/actions?query=workflow%3ACI)
+the following Ruby implementations:
+
+* Ruby 2.5
+* Ruby 2.6
+* Ruby 2.7
+
+## 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).
+
+To install all gems onto your local machine, run
+`bundle exec rake all:install`. To release a new version, update the version
+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 FileMaker, Inc,
+an Apple subsidiary. FileMaker is a trademark of FileMaker, Inc., registered in
+the U.S. and other countries.