fmrest-spyke 0.18.0.rc3 → 0.20.0.rc1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +11 -0
- data/README.md +62 -91
- data/lib/fmrest/spyke/model/connection.rb +2 -2
- data/lib/fmrest/spyke/model/rescuable.rb +48 -4
- data/lib/fmrest/spyke/spyke_formatter.rb +0 -1
- metadata +4 -4
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 60161315c910b54afb5dc86f5d4549436afbb3244e734f36c8019bea386d3074
|
4
|
+
data.tar.gz: '0118d433eac27c95addb1175f333fb44e7040da79459f698642c36e8d86fa3b7'
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 98638f63c0d575224f14834b811ad9fdc43e64897b9d8223c7848e2ef9fe644b323f7d41649c7342da364d90bfaf4be1956ca50cbc825413dbb24ecf194c09c8
|
7
|
+
data.tar.gz: c9d7716570a34599656945d1731d582c17009b34d5fd20a8397227e8b387977b54577508601e7c38510e8be780d442b0134c01dd882764c22c256631a97716f2
|
data/CHANGELOG.md
CHANGED
@@ -1,5 +1,13 @@
|
|
1
1
|
## Changelog
|
2
2
|
|
3
|
+
### 0.20.0
|
4
|
+
|
5
|
+
* Forward proxy options to AWS Client when using `fmrest-cloud` gem
|
6
|
+
|
7
|
+
### 0.19.0
|
8
|
+
|
9
|
+
* Added native support for FileMaker Cloud through the `fmrest-cloud` gem
|
10
|
+
|
3
11
|
### 0.18.0
|
4
12
|
|
5
13
|
* Better support for portals with mismatching field qualifiers
|
@@ -7,6 +15,9 @@
|
|
7
15
|
* Defining an attribute on a model that would collide with an existing method
|
8
16
|
now raises an error
|
9
17
|
* Cleared Faraday deprecation messages on authentication methods
|
18
|
+
* Handle FileMaker Cloud case where HTTP 401 Unauthorized with content-type
|
19
|
+
text/html is returned after token expiry
|
20
|
+
* Add retry option to Rescuable mixin
|
10
21
|
* Added fmrest-ruby/VERSION to User-Agent headers
|
11
22
|
|
12
23
|
### 0.17.1
|
data/README.md
CHANGED
@@ -5,14 +5,27 @@
|
|
5
5
|
[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/github/beezwax/fmrest-ruby)
|
6
6
|
|
7
7
|
A Ruby client for
|
8
|
-
[FileMaker
|
9
|
-
|
10
|
-
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
|
15
|
-
|
8
|
+
[FileMaker's Data API](https://help.claris.com/en/data-api-guide)
|
9
|
+
with ActiveRecord-ish ORM features.
|
10
|
+
|
11
|
+
While pretty feature-rich, fmrest-ruby doesn't yet support 100% of FileMaker
|
12
|
+
19's Data API features. See the [implementation completeness
|
13
|
+
table](#api-implementation-completeness-table) to check if a feature you need
|
14
|
+
is natively supported by the gem.
|
15
|
+
|
16
|
+
## Contents
|
17
|
+
|
18
|
+
* [Gems](#gems)
|
19
|
+
* [Installation](#installation)
|
20
|
+
* [Simple example](#simple-example)
|
21
|
+
* [Connection settings](#connection-settings)
|
22
|
+
* [Session token store](#session-token-store)
|
23
|
+
* [Date fields and timezones](#date-fields-and-timezones)
|
24
|
+
* [ActiveRecord-like ORM (fmrest-spyke)](#activerecord-like-orm-fmrest-spyke)
|
25
|
+
* [Logging](#logging)
|
26
|
+
* [Gotchas](#gotchas)
|
27
|
+
* [API implementation completeness table](#api-implementation-completeness-table)
|
28
|
+
* [Supported Ruby versions](#supported-ruby-versions)
|
16
29
|
|
17
30
|
## Gems
|
18
31
|
|
@@ -20,28 +33,26 @@ The `fmrest` gem is a wrapper for two other gems:
|
|
20
33
|
|
21
34
|
* `fmrest-spyke`, providing an ActiveRecord-like ORM library built on top
|
22
35
|
of `fmrest-core` and [Spyke](https://github.com/balvig/spyke).
|
23
|
-
* `fmrest-core`, providing the core
|
36
|
+
* `fmrest-core`, providing the core
|
37
|
+
[Faraday](https://github.com/lostisland/faraday) connection builder, session
|
24
38
|
management, and other core utilities.
|
25
39
|
|
40
|
+
In addition, the optional `fmrest-cloud` gem adds support for FileMaker Cloud.
|
41
|
+
See the [main document on connecting to FileMaker
|
42
|
+
Cloud](docs/FileMakerCloud.md).
|
43
|
+
|
26
44
|
## Installation
|
27
45
|
|
28
|
-
|
46
|
+
In your Gemfile:
|
29
47
|
|
30
48
|
```ruby
|
31
49
|
gem 'fmrest'
|
32
|
-
```
|
33
|
-
|
34
|
-
Or if you just want to use the Faraday connection without the ORM features:
|
35
50
|
|
36
|
-
|
37
|
-
gem 'fmrest-
|
51
|
+
# Optional: if your files are hosted on FileMaker Cloud
|
52
|
+
gem 'fmrest-cloud'
|
38
53
|
```
|
39
54
|
|
40
|
-
## Simple
|
41
|
-
|
42
|
-
### ORM example
|
43
|
-
|
44
|
-
Most people would want to use the ORM features:
|
55
|
+
## Simple example
|
45
56
|
|
46
57
|
```ruby
|
47
58
|
# A Layout model connecting to the "Honeybees Web" FileMaker layout
|
@@ -90,32 +101,9 @@ bee.tasks.build(urgency: "Today")
|
|
90
101
|
bee.save
|
91
102
|
```
|
92
103
|
|
93
|
-
|
94
|
-
|
95
|
-
|
96
|
-
Data API interaction and just want a lightweight solution) you can simply use
|
97
|
-
the Faraday connection provided by `fmrest-core`:
|
98
|
-
|
99
|
-
```ruby
|
100
|
-
connection = FmRest::V1.build_connection(
|
101
|
-
host: "…",
|
102
|
-
database: "…",
|
103
|
-
username: "…",
|
104
|
-
password: "…"
|
105
|
-
)
|
106
|
-
|
107
|
-
# Get all records (as parsed JSON)
|
108
|
-
connection.get("layouts/FancyLayout/records")
|
109
|
-
|
110
|
-
# Create new record
|
111
|
-
connection.post do |req|
|
112
|
-
req.url "layouts/FancyLayout/records"
|
113
|
-
|
114
|
-
# You can just pass a hash for the JSON body
|
115
|
-
req.body = { … }
|
116
|
-
end
|
117
|
-
```
|
118
|
-
|
104
|
+
In case you don't want the ORM features (i.e. you only need authentication and
|
105
|
+
JSON parsing, and are comfortable writing the API requests manually without the
|
106
|
+
ORM overhead) you can use the Faraday connection provided by `fmrest-core`.
|
119
107
|
See the [main document on using the base
|
120
108
|
connection](docs/BaseConnectionUsage.md) for more.
|
121
109
|
|
@@ -125,10 +113,6 @@ The minimum required connection settings are `:host`, `:database`, `:username`
|
|
125
113
|
and `:password`, but fmrest-ruby has many other options you can pass when
|
126
114
|
setting up a connection (see [full list](#full-list-of-available-options) below).
|
127
115
|
|
128
|
-
If you're using FileMaker Cloud you may need to pass `:fmid_token` instead
|
129
|
-
of the regular `:username` and `:password`. See the [main document on
|
130
|
-
connecting to FileMaker Cloud](docs/FileMakerCloud.md) for more info.
|
131
|
-
|
132
116
|
`:ssl` and `:proxy` are forwarded to the underlying
|
133
117
|
[Faraday](https://github.com/lostisland/faraday) connection. You can use this
|
134
118
|
to, for instance, disable SSL verification:
|
@@ -153,9 +137,8 @@ Option | Description | Format
|
|
153
137
|
`:username` | A Data API-ready account | String | None
|
154
138
|
`:password` | Your password | String | None
|
155
139
|
`:account_name` | Alias of `:username` | String | None
|
156
|
-
`:fmid_token` | Claris ID token (only needed for FileMaker Cloud) | String | None
|
157
140
|
`:ssl` | SSL options to be forwarded to Faraday | Faraday SSL options | None
|
158
|
-
`:proxy` | Proxy
|
141
|
+
`:proxy` | Proxy URI e.g. `http://username:password@proxy.host:5000` | String / URI | None
|
159
142
|
`:log` | Log JSON responses to STDOUT | Boolean | `false`
|
160
143
|
`:log_level` | Which log level to log into | Values accepted by `Logger#level=` | `:debug`
|
161
144
|
`:coerce_dates` | See section on [date fields](#date-fields-and-timezones) | Boolean \| `:hybrid` \| `:full` | `false`
|
@@ -165,6 +148,11 @@ Option | Description | Format
|
|
165
148
|
`:timezone` | The timezone for the FM server | `:local` \| `:utc` \| `nil` | `nil`
|
166
149
|
`:autologin` | Whether to automatically start Data API sessions | Boolean | `true`
|
167
150
|
`:token` | Used to manually provide a session token (e.g. if `:autologin` is `false`) | String | None
|
151
|
+
`:fmid_token` | Claris ID token (only needed if manually obtaining the token) | String | None
|
152
|
+
`:cloud` | Specifies whether the host is using FileMaker Cloud | `:auto` \| Boolean | `:auto`
|
153
|
+
`:cognito_client_id`| Overwrites the hardcoded FileMaker Cloud Cognito Client ID | String | None
|
154
|
+
`:cognito_pool_id` | Overwrites the hardcoded FileMaker Cloud Cognito Pool ID | String | None
|
155
|
+
`:aws_region` | Overwrites the hardcoded FileMaker Cloud AWS Region | String | None
|
168
156
|
|
169
157
|
### Default connection settings
|
170
158
|
|
@@ -207,7 +195,7 @@ See the [main document on date fields](docs/DateFields.md) for more info.
|
|
207
195
|
## ActiveRecord-like ORM (fmrest-spyke)
|
208
196
|
|
209
197
|
[Spyke](https://github.com/balvig/spyke) is an ActiveRecord-like gem for
|
210
|
-
building REST ORM models. fmrest-ruby
|
198
|
+
building REST ORM models. fmrest-ruby uses it to build its ORM features,
|
211
199
|
bundled in the `fmrest-spyke` gem (already included if you're using the
|
212
200
|
`fmrest` gem).
|
213
201
|
|
@@ -265,39 +253,33 @@ class Honeybee < FmRest::Layout
|
|
265
253
|
end
|
266
254
|
```
|
267
255
|
|
268
|
-
|
269
|
-
connection settings, so you don't have to worry about setting that up.
|
270
|
-
|
271
|
-
Note that these settings are inheritable, so you could create a base class that
|
256
|
+
These settings are class-inheritable, so you could create a base class that
|
272
257
|
does the initial connection setup and then inherit from it in models using that
|
273
258
|
same connection. E.g.:
|
274
259
|
|
275
260
|
```ruby
|
276
|
-
class
|
261
|
+
class ApplicationFmLayout < FmRest::Layout
|
277
262
|
self.fmrest_config = { host: "…", database: "…", … }
|
278
263
|
end
|
279
264
|
|
280
|
-
class Honeybee <
|
281
|
-
# This model will use the same connection as
|
265
|
+
class Honeybee < ApplicationFmLayout
|
266
|
+
# This model will use the same connection as ApplicationFmLayout
|
282
267
|
end
|
283
268
|
```
|
284
269
|
|
285
|
-
|
270
|
+
If `fmrest_config` is not set, your model will try to use
|
286
271
|
`FmRest.default_connection_settings` instead.
|
287
272
|
|
288
273
|
#### Connection settings overlays
|
289
274
|
|
290
275
|
There may be cases where you want to use a different set of connection settings
|
291
|
-
depending on context,
|
292
|
-
|
293
|
-
|
294
|
-
|
295
|
-
the model in one context would also change it in all other contexts, leading to
|
296
|
-
security issues.
|
276
|
+
depending on context. For example, if you want to use username and password
|
277
|
+
provided by the user in a web application. Since `.fmrest_config` is set at the
|
278
|
+
class level, changing the username/password for the model in one context would
|
279
|
+
also change it in all other contexts, leading to security issues.
|
297
280
|
|
298
|
-
To solve this scenario, fmrest-ruby provides a way of defining thread-local
|
299
|
-
reversible connection settings overlays through
|
300
|
-
`.fmrest_config_overlay=`.
|
281
|
+
To solve this scenario, fmrest-ruby provides a way of defining thread-local,
|
282
|
+
reversible connection settings overlays through `.fmrest_config_overlay=`.
|
301
283
|
|
302
284
|
See the [main document on connection setting overlays](docs/ConfigOverlays.md)
|
303
285
|
for details on how it works.
|
@@ -461,12 +443,10 @@ for details.
|
|
461
443
|
|
462
444
|
### Rescuable mixin
|
463
445
|
|
464
|
-
Sometimes you may want to handle Data API errors at the model level. For
|
465
|
-
|
466
|
-
|
467
|
-
|
468
|
-
`Rescuable` that provides convenience macros for that. If you've used Ruby on
|
469
|
-
Rails you may be familiar with its syntax from controllers. E.g.
|
446
|
+
Sometimes you may want to handle Data API errors at the model level. For such
|
447
|
+
cases fmrest-ruby provides an off-by-default mixin called `Rescuable` that
|
448
|
+
provides convenience macros for that. If you've used Ruby on Rails you may be
|
449
|
+
familiar with its syntax from controllers. E.g.
|
470
450
|
|
471
451
|
```ruby
|
472
452
|
class BeeBase < FmRest::Layout
|
@@ -474,9 +454,6 @@ class BeeBase < FmRest::Layout
|
|
474
454
|
|
475
455
|
rescue_from FmRest::APIError::SystemError, with: :notify_admin_of_system_error
|
476
456
|
|
477
|
-
# Shorthand for rescue_with FmRest::APIError::AccountError, ...
|
478
|
-
rescue_account_error { ClarisIDTokenManager.expire_token }
|
479
|
-
|
480
457
|
def self.notify_admin_of_system_error(e)
|
481
458
|
# Shoot an email to the FM admin...
|
482
459
|
end
|
@@ -549,14 +526,14 @@ Read about unexpected scenarios in the [gotchas doc](docs/Gotchas.md).
|
|
549
526
|
|
550
527
|
## API implementation completeness table
|
551
528
|
|
552
|
-
FM Data API reference: https://
|
529
|
+
FM Data API reference: https://help.claris.com/en/data-api-guide/
|
553
530
|
|
554
|
-
| FM
|
531
|
+
| FM 19 Data API feature | Supported by basic connection | Supported by FmRest::Layout |
|
555
532
|
|-------------------------------------|-------------------------------|-----------------------------|
|
556
533
|
| Log in using HTTP Basic Auth | Yes | Yes |
|
557
534
|
| Log in using OAuth | No | No |
|
558
535
|
| Log in to an external data source | No | No |
|
559
|
-
| Log in using Claris ID account
|
536
|
+
| Log in using Claris ID account (FileMaker Cloud) | Yes | Yes |
|
560
537
|
| Log out | Yes | Yes |
|
561
538
|
| Get product information | Manual* | No |
|
562
539
|
| Get database names | Manual* | No |
|
@@ -592,9 +569,9 @@ the following Ruby implementations:
|
|
592
569
|
## Gem development
|
593
570
|
|
594
571
|
After checking out the repo, run `bin/setup` to install dependencies. Then, run
|
595
|
-
`
|
596
|
-
prompt that will allow you to experiment (it will auto-load all
|
597
|
-
spec/fixtures).
|
572
|
+
`bundle exec rspec` to run the specs. You can also run `bin/console` for an
|
573
|
+
interactive prompt that will allow you to experiment (it will auto-load all
|
574
|
+
fixtures in spec/fixtures).
|
598
575
|
|
599
576
|
To install all gems onto your local machine, run
|
600
577
|
`bundle exec rake all:install`. To release a new version, update the version
|
@@ -602,12 +579,6 @@ number in `lib/fmrest/version.rb`, and then run `bundle exec rake all:release`,
|
|
602
579
|
which will create a git tag for the version, push git commits and tags, and
|
603
580
|
push the `.gem` files to [rubygems.org](https://rubygems.org).
|
604
581
|
|
605
|
-
## License
|
606
|
-
|
607
|
-
The gem is available as open source under the terms of the
|
608
|
-
[MIT License](https://opensource.org/licenses/MIT).
|
609
|
-
See [LICENSE.txt](LICENSE.txt).
|
610
|
-
|
611
582
|
## Disclaimer
|
612
583
|
|
613
584
|
This project is not sponsored by or otherwise affiliated with Claris
|
@@ -140,8 +140,8 @@ module FmRest
|
|
140
140
|
|
141
141
|
conn.use FmRest::V1::TypeCoercer, config
|
142
142
|
|
143
|
-
# FmRest::Spyke::
|
144
|
-
conn.response :json, parser_options: { symbolize_names: true }
|
143
|
+
# FmRest::Spyke::SpykeFormatter expects symbol keys
|
144
|
+
conn.response :json, parser_options: { symbolize_names: true }, content_type: /\bjson$/
|
145
145
|
end
|
146
146
|
|
147
147
|
@fmrest_connection = connection if memoize
|
@@ -3,9 +3,46 @@
|
|
3
3
|
module FmRest
|
4
4
|
module Spyke
|
5
5
|
module Model
|
6
|
+
# This mixin allows rescuing from errors raised during HTTP requests,
|
7
|
+
# with optional retry (useful for solving expired auth). This is based
|
8
|
+
# off ActiveSupport::Rescuable, with minimal added functionality. Its
|
9
|
+
# usage is analogous to `rescue_from` in Rails' controllers.
|
10
|
+
#
|
11
|
+
# Example usage:
|
12
|
+
#
|
13
|
+
# MyLayout < FmRest::Layout
|
14
|
+
# # Mix-in module
|
15
|
+
# include FmRest::Spyke::Model::Rescuable
|
16
|
+
#
|
17
|
+
# # Define an error handler
|
18
|
+
# rescue_from FmRest::APIError::SomeError, with: :report_error
|
19
|
+
#
|
20
|
+
# # Define block-based error handler
|
21
|
+
# rescue_from FmRest::APIError::SomeOtherError, with: -> { ... }
|
22
|
+
#
|
23
|
+
# private
|
24
|
+
#
|
25
|
+
# def report_error(exception)
|
26
|
+
# ErrorNotifier.notify(exception)
|
27
|
+
# ene
|
28
|
+
# end
|
29
|
+
#
|
30
|
+
# This module also extends upon ActiveSupport's implementation by
|
31
|
+
# allowing to request a retry of the failed request, which can be useful
|
32
|
+
# in situations where an auth token has expired and credentials need to
|
33
|
+
# be manually reset.
|
34
|
+
#
|
35
|
+
# To request a retry use `throw :retry` within the handler method.
|
36
|
+
#
|
37
|
+
# Finally, since it's the most common use case, there's a shorthand
|
38
|
+
# method for handling Data API authentication errors:
|
39
|
+
#
|
40
|
+
# rescue_account_error with: -> { CredentialsManager.refresh_credentials }
|
41
|
+
#
|
42
|
+
# This method will always issue a retry.
|
43
|
+
#
|
6
44
|
module Rescuable
|
7
45
|
extend ::ActiveSupport::Concern
|
8
|
-
|
9
46
|
include ::ActiveSupport::Rescuable
|
10
47
|
|
11
48
|
class_methods do
|
@@ -13,12 +50,19 @@ module FmRest
|
|
13
50
|
begin
|
14
51
|
super
|
15
52
|
rescue => e
|
16
|
-
|
53
|
+
catch :retry do
|
54
|
+
rescue_with_handler(e) || raise
|
55
|
+
return
|
56
|
+
end
|
57
|
+
super
|
17
58
|
end
|
18
59
|
end
|
19
60
|
|
20
|
-
def rescue_account_error(with: nil
|
21
|
-
rescue_from
|
61
|
+
def rescue_account_error(with: nil)
|
62
|
+
rescue_from(APIError::AccountError, with: with) do
|
63
|
+
yield
|
64
|
+
throw :retry
|
65
|
+
end
|
22
66
|
end
|
23
67
|
end
|
24
68
|
end
|
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: fmrest-spyke
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.20.0.rc1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Pedro Carbajal
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2021-
|
11
|
+
date: 2021-10-19 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: fmrest-core
|
@@ -16,14 +16,14 @@ dependencies:
|
|
16
16
|
requirements:
|
17
17
|
- - '='
|
18
18
|
- !ruby/object:Gem::Version
|
19
|
-
version: 0.
|
19
|
+
version: 0.20.0.rc1
|
20
20
|
type: :runtime
|
21
21
|
prerelease: false
|
22
22
|
version_requirements: !ruby/object:Gem::Requirement
|
23
23
|
requirements:
|
24
24
|
- - '='
|
25
25
|
- !ruby/object:Gem::Version
|
26
|
-
version: 0.
|
26
|
+
version: 0.20.0.rc1
|
27
27
|
- !ruby/object:Gem::Dependency
|
28
28
|
name: spyke
|
29
29
|
requirement: !ruby/object:Gem::Requirement
|