fmrest-core 0.15.0 → 0.17.0.rc1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.yardopts +1 -0
- data/CHANGELOG.md +23 -8
- data/README.md +66 -12
- data/lib/fmrest.rb +20 -1
- data/lib/fmrest/connection_settings.rb +14 -7
- data/lib/fmrest/v1/auth.rb +3 -1
- data/lib/fmrest/v1/connection.rb +8 -3
- data/lib/fmrest/version.rb +1 -1
- metadata +5 -5
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 312c477604d1cd806fd0e403222baf2485409ee15774b9b0a94da22dee585435
|
4
|
+
data.tar.gz: 2d229e1b3ad0ef228868c6298964a43e0a22ada7e23c8e00aa7d6b8b9be75e98
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: aad3c75eb9841885c78f9f0ed583ffc321eb66b1c2437181d84760cb44e52f4d27a3e4ce7d1c30c1697f77b36506075d98e3c925962ba90669198961497567a9
|
7
|
+
data.tar.gz: '0826d82c0a298a5a6ab0aec9f8fc582f73279d19e770080614f4faef368b21d646df33ac6065cf373ccd9e13e9ee6e2feefc66a3367e587883cfbd631dc52698'
|
data/.yardopts
CHANGED
data/CHANGELOG.md
CHANGED
@@ -1,5 +1,20 @@
|
|
1
1
|
## Changelog
|
2
2
|
|
3
|
+
### 0.17.0
|
4
|
+
|
5
|
+
* Added support for Claris ID token login
|
6
|
+
* Added ability to use procs in settings
|
7
|
+
* Added `Rescuable` mixin
|
8
|
+
|
9
|
+
### 0.16.0
|
10
|
+
|
11
|
+
* Added `FmRest.logger=`
|
12
|
+
* Handle serialization of `nil`, `true` and `false` values
|
13
|
+
|
14
|
+
### 0.15.2
|
15
|
+
|
16
|
+
* Fixed autoloading of `FmRest::Layout`
|
17
|
+
|
3
18
|
### 0.15.0
|
4
19
|
|
5
20
|
* Much improved querying API (see documentation on querying), adding new
|
@@ -14,13 +29,13 @@
|
|
14
29
|
|
15
30
|
### 0.13.1
|
16
31
|
|
17
|
-
*
|
32
|
+
* Fixed downloading of container field data from FMS19+
|
18
33
|
|
19
34
|
### 0.13.0
|
20
35
|
|
21
36
|
* Split `fmrest` gem into `fmrest-core` and `fmrest-spyke`. `fmrest` becomes a
|
22
37
|
wrapper for the two new gems.
|
23
|
-
*
|
38
|
+
* Fixed bug preventing connection databases with spaces in their names.
|
24
39
|
* Improved portal support with ability to delete portal records, and better
|
25
40
|
refreshing of portal records after saving the parent.
|
26
41
|
* `FmRest::Spyke::Base#__record_id` and `FmRest::Spyke::Base#__mod_id` now
|
@@ -35,7 +50,7 @@
|
|
35
50
|
|
36
51
|
### 0.11.1
|
37
52
|
|
38
|
-
*
|
53
|
+
* Fixed a couple crashes due to missing constants
|
39
54
|
|
40
55
|
### 0.11.0
|
41
56
|
|
@@ -50,7 +65,7 @@
|
|
50
65
|
|
51
66
|
### 0.10.1
|
52
67
|
|
53
|
-
*
|
68
|
+
* Fixed `URI.escape` obsolete warning messages in Ruby 2.7 by replacing it with
|
54
69
|
`URI.encode_www_form_component`
|
55
70
|
([PR#40](https://github.com/beezwax/fmrest-ruby/pull/40))
|
56
71
|
|
@@ -124,20 +139,20 @@
|
|
124
139
|
|
125
140
|
### 0.3.2
|
126
141
|
|
127
|
-
*
|
142
|
+
* Fixed support for ActiveSupport < 5.2
|
128
143
|
([#27](https://github.com/beezwax/fmrest-ruby/issues/27))
|
129
144
|
|
130
145
|
### 0.3.0
|
131
146
|
|
132
|
-
*
|
147
|
+
* Added Moneta token store
|
133
148
|
|
134
149
|
### 0.2.5
|
135
150
|
|
136
|
-
*
|
151
|
+
* Fixed crash in `fetch_container_data` when no proxy options were set
|
137
152
|
|
138
153
|
### 0.2.4
|
139
154
|
|
140
155
|
* Use `String#=~` instead of `String#match?` for Ruby <2.4 compatibility (Fixes
|
141
156
|
[#26](https://github.com/beezwax/fmrest-ruby/issues/26))
|
142
|
-
*
|
157
|
+
* Deprecated `FmRest.config` in favor of `FmRest.default_connection_settings`
|
143
158
|
* Honor Faraday SSL and proxy settings when fetching container files
|
data/README.md
CHANGED
@@ -2,6 +2,7 @@
|
|
2
2
|
|
3
3
|
[![Gem Version](https://badge.fury.io/rb/fmrest.svg?style=flat)](https://rubygems.org/gems/fmrest)
|
4
4
|
![CI](https://github.com/beezwax/fmrest-ruby/workflows/CI/badge.svg)
|
5
|
+
[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/github/beezwax/fmrest-ruby)
|
5
6
|
|
6
7
|
A Ruby client for
|
7
8
|
[FileMaker 18 and 19's Data API](https://help.claris.com/en/data-api-guide)
|
@@ -9,7 +10,7 @@ using
|
|
9
10
|
[Faraday](https://github.com/lostisland/faraday) and with optional
|
10
11
|
ActiveRecord-ish ORM features through [Spyke](https://github.com/balvig/spyke).
|
11
12
|
|
12
|
-
fmrest-ruby only partially implements FileMaker
|
13
|
+
fmrest-ruby only partially implements FileMaker 19's Data API.
|
13
14
|
See the [implementation completeness table](#api-implementation-completeness-table)
|
14
15
|
to see if a feature you need is natively supported by the gem.
|
15
16
|
|
@@ -124,6 +125,10 @@ The minimum required connection settings are `:host`, `:database`, `:username`
|
|
124
125
|
and `:password`, but fmrest-ruby has many other options you can pass when
|
125
126
|
setting up a connection (see [full list](#full-list-of-available-options) below).
|
126
127
|
|
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
|
+
|
127
132
|
`:ssl` and `:proxy` are forwarded to the underlying
|
128
133
|
[Faraday](https://github.com/lostisland/faraday) connection. You can use this
|
129
134
|
to, for instance, disable SSL verification:
|
@@ -148,9 +153,11 @@ Option | Description | Format
|
|
148
153
|
`:username` | A Data API-ready account | String | None
|
149
154
|
`:password` | Your password | String | None
|
150
155
|
`:account_name` | Alias of `:username` | String | None
|
156
|
+
`:fmid_token` | Claris ID token (only needed for FileMaker Cloud) | String | None
|
151
157
|
`:ssl` | SSL options to be forwarded to Faraday | Faraday SSL options | None
|
152
158
|
`:proxy` | Proxy options to be forwarded to Faraday | Faraday proxy options | None
|
153
159
|
`:log` | Log JSON responses to STDOUT | Boolean | `false`
|
160
|
+
`:log_level` | Which log level to log into | Values accepted by `Logger#level=` | `:debug`
|
154
161
|
`:coerce_dates` | See section on [date fields](#date-fields-and-timezones) | Boolean \| `:hybrid` \| `:full` | `false`
|
155
162
|
`:date_format` | Date parsing format | String (FM date format) | `"MM/dd/yyyy"`
|
156
163
|
`:timestamp_format` | Timestmap parsing format | String (FM date format) | `"MM/dd/yyyy HH:mm:ss"`
|
@@ -281,10 +288,12 @@ Also, if not set, your model will try to use
|
|
281
288
|
#### Connection settings overlays
|
282
289
|
|
283
290
|
There may be cases where you want to use a different set of connection settings
|
284
|
-
depending on context
|
285
|
-
provided by the user in a web
|
286
|
-
|
287
|
-
|
291
|
+
depending on context, or simply change the connection settings over time. For
|
292
|
+
example, if you want to use username and password provided by the user in a web
|
293
|
+
application, or if you're connecting using an expiring Claris ID token. Since
|
294
|
+
`.fmrest_config` is set at the class level, changing the username/password for
|
295
|
+
the model in one context would also change it in all other contexts, leading to
|
296
|
+
security issues.
|
288
297
|
|
289
298
|
To solve this scenario, fmrest-ruby provides a way of defining thread-local and
|
290
299
|
reversible connection settings overlays through
|
@@ -321,7 +330,7 @@ Requests a Data API session token using the connection settings in
|
|
321
330
|
|
322
331
|
You normally don't need to use this method as fmrest-ruby will automatically
|
323
332
|
request and store session tokens for you (provided that `:autologin` is
|
324
|
-
`true`).
|
333
|
+
`true` in the connection settings, which it is by default).
|
325
334
|
|
326
335
|
### FmRest::Layout.logout
|
327
336
|
|
@@ -450,13 +459,48 @@ field values on the database that model is configured for.
|
|
450
459
|
See the [main document on setting global field values](docs/GlobalFields.md)
|
451
460
|
for details.
|
452
461
|
|
462
|
+
### Rescuable mixin
|
463
|
+
|
464
|
+
Sometimes you may want to handle Data API errors at the model level. For
|
465
|
+
instance, if you're logging in to a file hosted by FileMaker Cloud using a
|
466
|
+
Claris ID token, and you want to be able to renew said token when it fails to
|
467
|
+
log you in. For such cases fmrest-ruby provides an off-by-default mixin called
|
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.
|
470
|
+
|
471
|
+
```ruby
|
472
|
+
class BeeBase < FmRest::Layout
|
473
|
+
include FmRest::Spyke::Model::Rescuable
|
474
|
+
|
475
|
+
rescue_from FmRest::APIError::SystemError, with: :notify_admin_of_system_error
|
476
|
+
|
477
|
+
# Shorthand for rescue_with FmRest::APIError::AccountError, ...
|
478
|
+
rescue_account_error { ClarisIDTokenManager.expire_token }
|
479
|
+
|
480
|
+
def self.notify_admin_of_system_error(e)
|
481
|
+
# Shoot an email to the FM admin...
|
482
|
+
end
|
483
|
+
end
|
484
|
+
```
|
485
|
+
|
486
|
+
Since `Rescuable` uses `ActiveSupport::Rescuable` internally, you may want to
|
487
|
+
check [Rails'
|
488
|
+
documentation](https://api.rubyonrails.org/classes/ActiveSupport/Rescuable/ClassMethods.html)
|
489
|
+
too for details on how it works.
|
490
|
+
|
491
|
+
One caveat of using `rescue_from` is that it always catches exceptions at the
|
492
|
+
class level, so if you pass a method name to `with:` that method has to be a
|
493
|
+
class method. Also note that this will only catch exceptions raised during an
|
494
|
+
API call to the Data API server (in other words, only on actions that perform
|
495
|
+
an HTTP request).
|
496
|
+
|
453
497
|
## Logging
|
454
498
|
|
455
499
|
If using `fmrest-spyke` with Rails then pretty log output will be set up for
|
456
500
|
you automatically by Spyke (see [their
|
457
501
|
README](https://github.com/balvig/spyke#log-output)).
|
458
502
|
|
459
|
-
You can also enable simple Faraday
|
503
|
+
You can also enable simple Faraday logging of raw requests (useful for
|
460
504
|
debugging) by passing `log: true` in the options hash for either
|
461
505
|
`FmRest.default_connection_settings=` or your models' `fmrest_config=`, e.g.:
|
462
506
|
|
@@ -477,7 +521,17 @@ class LoggyBee < FmRest::Layout
|
|
477
521
|
end
|
478
522
|
```
|
479
523
|
|
480
|
-
|
524
|
+
You can also pass `log_level` to connection settings to change the severity of
|
525
|
+
log output (defaults to `:debug`).
|
526
|
+
|
527
|
+
By default fmrest-ruby logs to STDOUT or to Rails' logger object if available.
|
528
|
+
You can change this by providing your own logger object to `FmRest.logger=`:
|
529
|
+
|
530
|
+
```ruby
|
531
|
+
FmRest.logger = Logger.new("fmrest.log")
|
532
|
+
```
|
533
|
+
|
534
|
+
If you need to set up more complex logging for your models you can use the
|
481
535
|
`faraday` block inside your class to inject your own logger middleware into the
|
482
536
|
Faraday connection, e.g.:
|
483
537
|
|
@@ -498,7 +552,7 @@ FM Data API reference: https://fmhelp.filemaker.com/docs/18/en/dataapi/
|
|
498
552
|
| Log in using HTTP Basic Auth | Yes | Yes |
|
499
553
|
| Log in using OAuth | No | No |
|
500
554
|
| Log in to an external data source | No | No |
|
501
|
-
| Log in using
|
555
|
+
| Log in using Claris ID account | Yes | Yes |
|
502
556
|
| Log out | Yes | Yes |
|
503
557
|
| Get product information | Manual* | No |
|
504
558
|
| Get database names | Manual* | No |
|
@@ -552,6 +606,6 @@ See [LICENSE.txt](LICENSE.txt).
|
|
552
606
|
|
553
607
|
## Disclaimer
|
554
608
|
|
555
|
-
This project is not sponsored by or otherwise affiliated with
|
556
|
-
an Apple subsidiary. FileMaker is a trademark of
|
557
|
-
the U.S. and other countries.
|
609
|
+
This project is not sponsored by or otherwise affiliated with Claris
|
610
|
+
International Inc., an Apple Inc. subsidiary. FileMaker is a trademark of
|
611
|
+
Claris International Inc., registered in the U.S. and other countries.
|
data/lib/fmrest.rb
CHANGED
@@ -11,12 +11,17 @@ module FmRest
|
|
11
11
|
autoload :V1, "fmrest/v1"
|
12
12
|
autoload :TokenStore, "fmrest/token_store"
|
13
13
|
autoload :Spyke, "fmrest/spyke"
|
14
|
+
autoload :Layout, "fmrest/spyke"
|
14
15
|
|
15
16
|
class << self
|
16
17
|
attr_accessor :token_store
|
18
|
+
attr_writer :logger
|
17
19
|
|
18
20
|
def default_connection_settings=(settings)
|
19
|
-
|
21
|
+
# Skip validation since we may use the defaults for half-complete
|
22
|
+
# settings
|
23
|
+
@default_connection_settings =
|
24
|
+
ConnectionSettings.wrap(settings, skip_validation: true)
|
20
25
|
end
|
21
26
|
|
22
27
|
def default_connection_settings
|
@@ -33,6 +38,15 @@ module FmRest
|
|
33
38
|
default_connection_settings
|
34
39
|
end
|
35
40
|
|
41
|
+
def logger
|
42
|
+
@logger ||= if defined?(Rails)
|
43
|
+
Rails.logger
|
44
|
+
else
|
45
|
+
require "logger"
|
46
|
+
Logger.new($stdout)
|
47
|
+
end
|
48
|
+
end
|
49
|
+
|
36
50
|
# Shortcut for FmRest::V1.escape_find_operators
|
37
51
|
#
|
38
52
|
# @param (see FmRest::V1.escape_find_operators
|
@@ -40,5 +54,10 @@ module FmRest
|
|
40
54
|
def e(s)
|
41
55
|
V1.escape_find_operators(s)
|
42
56
|
end
|
57
|
+
|
58
|
+
def Layout(*_)
|
59
|
+
require "fmrest/spyke"
|
60
|
+
self.Layout(*_)
|
61
|
+
end
|
43
62
|
end
|
44
63
|
end
|
@@ -18,12 +18,14 @@ module FmRest
|
|
18
18
|
database
|
19
19
|
username
|
20
20
|
password
|
21
|
+
fmid_token
|
21
22
|
token
|
22
23
|
token_store
|
23
24
|
autologin
|
24
25
|
ssl
|
25
26
|
proxy
|
26
27
|
log
|
28
|
+
log_level
|
27
29
|
coerce_dates
|
28
30
|
date_format
|
29
31
|
timestamp_format
|
@@ -45,6 +47,7 @@ module FmRest
|
|
45
47
|
DEFAULTS = {
|
46
48
|
autologin: true,
|
47
49
|
log: false,
|
50
|
+
log_level: :debug,
|
48
51
|
date_format: DEFAULT_DATE_FORMAT,
|
49
52
|
time_format: DEFAULT_TIME_FORMAT,
|
50
53
|
timestamp_format: DEFAULT_TIMESTAMP_FORMAT,
|
@@ -67,13 +70,12 @@ module FmRest
|
|
67
70
|
|
68
71
|
PROPERTIES.each do |p|
|
69
72
|
define_method(p) do
|
70
|
-
|
73
|
+
get_eval(p)
|
71
74
|
end
|
72
75
|
|
73
76
|
define_method("#{p}!") do
|
74
|
-
|
75
|
-
|
76
|
-
r
|
77
|
+
raise MissingSetting, "Missing required setting: `#{p}'" if get(p).nil?
|
78
|
+
get_eval(p)
|
77
79
|
end
|
78
80
|
|
79
81
|
define_method("#{p}?") do
|
@@ -83,7 +85,7 @@ module FmRest
|
|
83
85
|
|
84
86
|
def [](key)
|
85
87
|
raise ArgumentError, "Unknown setting `#{key}'" unless PROPERTIES.include?(key.to_sym)
|
86
|
-
|
88
|
+
get_eval(key)
|
87
89
|
end
|
88
90
|
|
89
91
|
def to_h
|
@@ -102,13 +104,18 @@ module FmRest
|
|
102
104
|
missing = REQUIRED.select { |r| get(r).nil? }.map { |m| "`#{m}'" }
|
103
105
|
raise MissingSetting, "Missing required setting(s): #{missing.join(', ')}" unless missing.empty?
|
104
106
|
|
105
|
-
unless username? || token?
|
106
|
-
raise MissingSetting, "A minimum of `username' or `token' are required to be able to establish a connection"
|
107
|
+
unless username? || fmid_token? || token?
|
108
|
+
raise MissingSetting, "A minimum of `username', `fmid_token' or `token' are required to be able to establish a connection"
|
107
109
|
end
|
108
110
|
end
|
109
111
|
|
110
112
|
private
|
111
113
|
|
114
|
+
def get_eval(key)
|
115
|
+
c = get(key)
|
116
|
+
c.kind_of?(Proc) ? c.call : c
|
117
|
+
end
|
118
|
+
|
112
119
|
def get(key)
|
113
120
|
return @settings[key.to_sym] if @settings.has_key?(key.to_sym)
|
114
121
|
return @settings[key.to_s] if @settings.has_key?(key.to_s)
|
data/lib/fmrest/v1/auth.rb
CHANGED
@@ -3,6 +3,8 @@
|
|
3
3
|
module FmRest
|
4
4
|
module V1
|
5
5
|
module Auth
|
6
|
+
ACCESS_TOKEN_HEADER = "X-FM-Data-Access-Token"
|
7
|
+
|
6
8
|
# Requests a token through basic auth
|
7
9
|
#
|
8
10
|
# @param connection [Faraday] the auth connection to use for
|
@@ -23,7 +25,7 @@ module FmRest
|
|
23
25
|
# @raise [FmRest::APIError::AccountError] if authentication failed
|
24
26
|
def request_auth_token!(connection = FmRest.V1.auth_connection)
|
25
27
|
resp = connection.post(V1.session_path)
|
26
|
-
resp.body["response"]["token"]
|
28
|
+
resp.headers[ACCESS_TOKEN_HEADER] || resp.body["response"]["token"]
|
27
29
|
end
|
28
30
|
end
|
29
31
|
end
|
data/lib/fmrest/v1/connection.rb
CHANGED
@@ -9,6 +9,7 @@ module FmRest
|
|
9
9
|
DATABASES_PATH = "#{BASE_PATH}/databases"
|
10
10
|
|
11
11
|
AUTH_HEADERS = { "Content-Type" => "application/json" }.freeze
|
12
|
+
CLARIS_ID_HTTP_AUTH_TYPE = "FMID"
|
12
13
|
|
13
14
|
# Builds a complete DAPI Faraday connection with middleware already
|
14
15
|
# configured to handle authentication, JSON parsing, logging and DAPI
|
@@ -41,7 +42,7 @@ module FmRest
|
|
41
42
|
end
|
42
43
|
|
43
44
|
if settings.log
|
44
|
-
conn.response :logger,
|
45
|
+
conn.response :logger, FmRest.logger, bodies: true, headers: true, log_level: settings.log_level
|
45
46
|
end
|
46
47
|
|
47
48
|
conn.adapter Faraday.default_adapter
|
@@ -58,10 +59,14 @@ module FmRest
|
|
58
59
|
base_connection(settings, { headers: AUTH_HEADERS }) do |conn|
|
59
60
|
conn.use RaiseErrors
|
60
61
|
|
61
|
-
|
62
|
+
if settings.fmid_token?
|
63
|
+
conn.authorization CLARIS_ID_HTTP_AUTH_TYPE, settings.fmid_token
|
64
|
+
else
|
65
|
+
conn.basic_auth settings.username!, settings.password!
|
66
|
+
end
|
62
67
|
|
63
68
|
if settings.log
|
64
|
-
conn.response :logger,
|
69
|
+
conn.response :logger, FmRest.logger, bodies: true, headers: true, log_level: settings.log_level
|
65
70
|
end
|
66
71
|
|
67
72
|
conn.response :json
|
data/lib/fmrest/version.rb
CHANGED
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: fmrest-core
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.17.0.rc1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Pedro Carbajal
|
8
8
|
autorequire:
|
9
9
|
bindir: exe
|
10
10
|
cert_chain: []
|
11
|
-
date: 2021-
|
11
|
+
date: 2021-07-26 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: faraday
|
@@ -104,11 +104,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
104
104
|
version: '0'
|
105
105
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
106
106
|
requirements:
|
107
|
-
- - "
|
107
|
+
- - ">"
|
108
108
|
- !ruby/object:Gem::Version
|
109
|
-
version:
|
109
|
+
version: 1.3.1
|
110
110
|
requirements: []
|
111
|
-
rubygems_version: 3.
|
111
|
+
rubygems_version: 3.2.3
|
112
112
|
signing_key:
|
113
113
|
specification_version: 4
|
114
114
|
summary: FileMaker Data API client using Faraday, core library
|