eluvia-base 3.41.0 → 3.43.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +25 -0
- data/README.md +39 -85
- data/lib/eluvia/active_record/file_attribute.rb +2 -5
- data/lib/eluvia/base/config.rb +5 -7
- data/lib/eluvia/handlers/pagination_handler.rb +11 -6
- data/lib/eluvia/integrations/eluvia_integration.rb +2 -0
- data/lib/eluvia/uploads.rb +2 -2
- metadata +11 -5
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 1bd277a4bfc22a7850be8ce3fc18eb1bb1ee5f1d005c808b557bff4354550453
|
|
4
|
+
data.tar.gz: 0df8311f31b95334aa6c5ba7513d116d7fa19c1e300aa1754dfa50eafa27835c
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: da6282229d0a1199cb29b6448aa368e9573834183ce2d3bf1d91e0bbcfad1cb1e3a917b2d68c58d491fc45528f1e8756e0e629e2f27a86a97bb59208f07d3b72
|
|
7
|
+
data.tar.gz: 79bfdea954fc7078ee98c58208bc512e5f0e41519a6b614890dab6c0079db3cd4cf44f9614c5059a758be8637546ded3a87e91fcbc739f09584928533a9033b6
|
data/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,31 @@ All notable changes to this project are documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [3.43.0] — 2026-11-09
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- Support for Rails 8.0 and 8.1: the `rails` dependency is widened from `~> 7.0` to
|
|
12
|
+
`>= 7.0, < 9`. Tested on Ruby 3.2, 3.4 and 4.0. (HAB-1045)
|
|
13
|
+
|
|
14
|
+
### Changed
|
|
15
|
+
- The gemspec declares `required_ruby_version >= 3.2`; Bundler no longer resolves new versions of
|
|
16
|
+
the gem on Ruby 3.1 and older. (HAB-1045)
|
|
17
|
+
|
|
18
|
+
### Fixed
|
|
19
|
+
- `Eluvia::EluviaIntegration` loads `rest-client` itself; the HTTP helpers no longer raise
|
|
20
|
+
`NameError: uninitialized constant RestClient` in an app that does not list `rest-client` in its
|
|
21
|
+
own `Gemfile`. (HAB-1045)
|
|
22
|
+
|
|
23
|
+
## [3.42.0] — 2026-10-28
|
|
24
|
+
|
|
25
|
+
### Fixed
|
|
26
|
+
- `Eluvia::PaginationHandler#set_pagination`: `fallback_order_by` no longer overrides the
|
|
27
|
+
direction of a field that the client's `order_by` (or `default_order_by`) already orders by; it
|
|
28
|
+
only appends the fields not ordered by yet. This changes behavior: with the default
|
|
29
|
+
`fallback_order_by: 'created_at:asc'`, `?order_by=created_at:desc` now really sorts descending
|
|
30
|
+
(before it was silently turned into ascending), and `?order_by=id:desc` with
|
|
31
|
+
`fallback_order_by: 'id:asc'` keeps `id` descending (HAB-1064).
|
|
32
|
+
|
|
8
33
|
## [3.41.0] — 2026-10-27
|
|
9
34
|
|
|
10
35
|
### Added
|
data/README.md
CHANGED
|
@@ -1,10 +1,9 @@
|
|
|
1
1
|
# Eluvia Base
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Ruby on Rails customizations and helpers implementing the Eluvia
|
|
4
|
+
[API communication standard](https://sparktech.myjetbrains.com/youtrack/articles/BASE-A-4/Communication-interface-FE-BE)
|
|
5
|
+
and common backend behavior:
|
|
6
6
|
|
|
7
|
-
It applies to both client and server sides:
|
|
8
7
|
- Pagination and ordering is handled for the API requests (server side).
|
|
9
8
|
- Extended params parsing is implemented for the API requests (server side).
|
|
10
9
|
- Extended filtering is handled for the API requests (server side).
|
|
@@ -15,6 +14,8 @@ It applies to both client and server sides:
|
|
|
15
14
|
|
|
16
15
|
### 1.1. Gem
|
|
17
16
|
|
|
17
|
+
Requires Ruby 3.2+ and Rails 7.0–8.x.
|
|
18
|
+
|
|
18
19
|
To install the library to your project, just add this to your `Gemfile`:
|
|
19
20
|
|
|
20
21
|
```ruby
|
|
@@ -45,8 +46,7 @@ For full list of configuration options, see `lib/eluvia/base/config.rb` file.
|
|
|
45
46
|
|
|
46
47
|
### 2.1. Application controller setup
|
|
47
48
|
|
|
48
|
-
|
|
49
|
-
main `ApplicationController`:
|
|
49
|
+
Include the handlers in your `ApplicationController`:
|
|
50
50
|
|
|
51
51
|
```ruby
|
|
52
52
|
|
|
@@ -61,78 +61,39 @@ end
|
|
|
61
61
|
|
|
62
62
|
### 2.2. Pagination
|
|
63
63
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
easily used in Active Record and Kaminari interfaces.
|
|
64
|
+
`set_pagination` reads the `limit`, `offset` and `order_by` query params and sets `@limit`, `@page`, `@padding` and
|
|
65
|
+
`@order_by` for Active Record and Kaminari:
|
|
67
66
|
|
|
68
67
|
```ruby
|
|
69
|
-
|
|
70
68
|
class TestRecordsController < ApplicationController
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
before_action -> { set_pagination(20, 0, 'created_at:desc') }, only: [:index]
|
|
74
|
-
|
|
75
|
-
# ...
|
|
69
|
+
before_action -> { set_pagination(default_order_by: 'created_at:desc', fallback_order_by: 'id:asc') }, only: [:index]
|
|
76
70
|
|
|
77
71
|
def index
|
|
78
72
|
@test_records = TestRecord.all.order(@order_by).page(@page).per(@limit).padding(@padding)
|
|
79
73
|
end
|
|
80
|
-
|
|
81
|
-
# ...
|
|
82
74
|
end
|
|
83
75
|
```
|
|
84
76
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
end
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
```ruby
|
|
109
|
-
before_action -> { set_pagination(default_limit: 20, default_offset: 0, max_limit: 50) }, only: [:index]
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
To restore the pre-validation behavior (invalid or above-ceiling `limit` silently falls back to `default_limit`
|
|
113
|
-
instead of raising `422`), enable `disable_errors` — globally via `Eluvia::Base::Config.disable_pagination_errors =
|
|
114
|
-
true` (default: `false`), or per call via the `disable_errors:` keyword, which takes precedence over the global
|
|
115
|
-
setting:
|
|
116
|
-
|
|
117
|
-
```ruby
|
|
118
|
-
before_action -> { set_pagination(default_limit: 20, default_offset: 0, disable_errors: true) }, only: [:index]
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
`limit=0` is accepted by default as a way to request only pagination metadata without fetching any records — check
|
|
122
|
-
`@limit.zero?` in the action and skip the query:
|
|
123
|
-
|
|
124
|
-
```ruby
|
|
125
|
-
def index
|
|
126
|
-
@test_records = @limit.zero? ? TestRecord.none : TestRecord.all.order(@order_by).page(@page).per(@limit).padding(@padding)
|
|
127
|
-
end
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
Pass `allow_meta_only_limit: false` (e.g. for a search-backed resource, mirroring
|
|
131
|
-
`AnySearchCursorBasedPagination` in eluvia-base-django) to reject `limit=0` like any other invalid value instead:
|
|
132
|
-
|
|
133
|
-
```ruby
|
|
134
|
-
before_action -> { set_pagination(default_limit: 20, default_offset: 0, allow_meta_only_limit: false) }, only: [:index]
|
|
135
|
-
```
|
|
77
|
+
| Keyword | Default | Meaning |
|
|
78
|
+
|-------------------------|------------------------------------|---------------------------------------------------------------|
|
|
79
|
+
| `default_limit` | `20` | `limit` when the param is missing or blank |
|
|
80
|
+
| `default_offset` | `0` | `offset` when the param is missing |
|
|
81
|
+
| `max_limit` | `pagination_max_limit` | upper bound for `limit`, `nil` for none |
|
|
82
|
+
| `allow_meta_only_limit` | `true` | accept `limit=0` |
|
|
83
|
+
| `disable_errors` | `Config.disable_pagination_errors` | use `default_limit` instead of raising 422 on invalid `limit` |
|
|
84
|
+
| `default_order_by` | `'created_at:asc'` | ordering when `order_by` is missing or blank |
|
|
85
|
+
| `force_order_by` | `false` | ignore the `order_by` param, always use `default_order_by` |
|
|
86
|
+
| `fallback_order_by` | `'created_at:asc'` | tiebreaker appended to the ordering |
|
|
87
|
+
|
|
88
|
+
**Limit.** `limit` must be a non-negative integer not above the ceiling, otherwise the request fails with
|
|
89
|
+
`422 Unprocessable Entity` on `limit`. The ceiling is `Eluvia::Base::Config.max_page_limit` (default `1000`, `nil`
|
|
90
|
+
for none); a controller can override the `pagination_max_limit` method to set its own. `limit=0` returns only the
|
|
91
|
+
pagination metadata, so skip the query when `@limit.zero?`.
|
|
92
|
+
|
|
93
|
+
**Ordering.** `order_by` is a comma-separated list of `field:asc` or `field:desc` entries; anything else fails with
|
|
94
|
+
`422`. `fallback_order_by` only appends fields the ordering does not contain yet, so it never changes the requested
|
|
95
|
+
direction; set it to the primary key to keep pages stable when ordered values are equal. For example,
|
|
96
|
+
`?order_by=name:asc,id:desc` with `fallback_order_by: 'id:asc'` yields `{ 'name' => :asc, 'id' => :desc }`.
|
|
136
97
|
|
|
137
98
|
### 2.3. Params parser
|
|
138
99
|
|
|
@@ -195,8 +156,7 @@ For the full list of features, see `Eluvia::EluviaIntegration` interface.
|
|
|
195
156
|
|
|
196
157
|
### 2.5. Raising error
|
|
197
158
|
|
|
198
|
-
|
|
199
|
-
formatted as standardized error response.
|
|
159
|
+
An `Eluvia::Errors::XXX` exception raised anywhere in the code is rendered as a standardized error response.
|
|
200
160
|
|
|
201
161
|
For example, this exception:
|
|
202
162
|
|
|
@@ -256,12 +216,10 @@ For the full list of available exceptions, see content of `lib/eluvia/errors` fo
|
|
|
256
216
|
|
|
257
217
|
### 2.6. Chunked/direct upload finalization
|
|
258
218
|
|
|
259
|
-
`Eluvia::File`
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
ActiveStorage attachment. This lets a separate library (e.g. a chunked upload provider) implement the
|
|
264
|
-
actual storage logic (S3 `copy_object`, tus, ...) without eluvia-base depending on it.
|
|
219
|
+
An `Eluvia::File` assigned to a `file_attr` field may carry an `upload_key` instead of base64 `content`. The key
|
|
220
|
+
identifies an already uploaded (chunked/direct) temp object, and the setter passes it to `Eluvia::Uploads.finalizer`,
|
|
221
|
+
which attaches it to the ActiveStorage record. The storage logic (S3 `copy_object`, tus, ...) thus lives in the
|
|
222
|
+
application or another library, not in this gem. `file_array_attr` fields reject `upload_key` with `400 Bad Request`.
|
|
265
223
|
|
|
266
224
|
Register a finalizer, typically from an initializer:
|
|
267
225
|
|
|
@@ -273,8 +231,7 @@ Eluvia::Uploads.finalizer = ->(attachment_record, upload_key, filename) do
|
|
|
273
231
|
end
|
|
274
232
|
```
|
|
275
233
|
|
|
276
|
-
|
|
277
|
-
`Eluvia::Errors::StandardError` is raised.
|
|
234
|
+
Assigning a file with `upload_key` while no finalizer is registered raises `Eluvia::Errors::StandardError`.
|
|
278
235
|
|
|
279
236
|
### 2.7. ENV-driven scope restriction
|
|
280
237
|
|
|
@@ -324,13 +281,10 @@ are NULL-safe: a row whose value is `NULL` is kept.
|
|
|
324
281
|
|
|
325
282
|
### 2.8. Translations
|
|
326
283
|
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
`
|
|
330
|
-
|
|
331
|
-
`sk`, `uk`. These are appended to `I18n.load_path` automatically when the gem loads; a host application only
|
|
332
|
-
needs to add the relevant locale to its own `I18n.available_locales` and set `I18n.locale` as usual. A host app's
|
|
333
|
-
own `config/locales/*.yml` takes precedence over these if it defines the same key.
|
|
284
|
+
Validation error messages of this gem go through `I18n.t` with an English default, so no locale setup is needed.
|
|
285
|
+
Translations for `cs`, `de`, `en`, `es`, `fr`, `it`, `ja`, `nl`, `pl`, `pt`, `ro`, `sk` and `uk` (under
|
|
286
|
+
`eluvia.errors.*`) are added to `I18n.load_path` when the gem loads. The application's own `config/locales/*.yml`
|
|
287
|
+
takes precedence for the same key.
|
|
334
288
|
|
|
335
289
|
## 3. Development
|
|
336
290
|
|
|
@@ -75,11 +75,8 @@ module Eluvia
|
|
|
75
75
|
value = Eluvia::File.map(value) if value.is_a?(::Hash)
|
|
76
76
|
raise Eluvia::Errors::BadRequest.new("Invalid value for file attribute `#{attr_name}`, expecting Eluvia::File.") unless value.is_a?(Eluvia::File)
|
|
77
77
|
|
|
78
|
-
# Retrieve and check filename -
|
|
79
|
-
#
|
|
80
|
-
# itself already encodes the original filename as its last path segment (providers
|
|
81
|
-
# build it as `<tmp_prefix><uuid>/<filename>`), so fall back to that instead of
|
|
82
|
-
# requiring it to be sent twice.
|
|
78
|
+
# Retrieve and check filename - a chunked/direct upload may send only `upload_key`,
|
|
79
|
+
# whose last path segment is the original filename (`<tmp_prefix><uuid>/<filename>`)
|
|
83
80
|
filename = value.filename
|
|
84
81
|
filename = ::File.basename(value.upload_key) if filename.blank? && value.upload_key.present?
|
|
85
82
|
raise Eluvia::Errors::BadRequest.new("Expected `filename` in the attribute `#{attr_name}`.") if filename.blank?
|
data/lib/eluvia/base/config.rb
CHANGED
|
@@ -40,16 +40,14 @@ module Eluvia
|
|
|
40
40
|
mattr_accessor :search_use_unaccent
|
|
41
41
|
@@search_use_unaccent = true
|
|
42
42
|
|
|
43
|
-
# Upper bound for the `limit`
|
|
44
|
-
#
|
|
45
|
-
# disables the check. Mirrors `MAX_PAGE_LIMIT` in eluvia-base-django. (default: 1000)
|
|
43
|
+
# Upper bound for the `limit` param of `set_pagination`; a higher `limit` is rejected with 422.
|
|
44
|
+
# `nil` disables the check. (default: 1000)
|
|
46
45
|
mattr_accessor :max_page_limit
|
|
47
46
|
@@max_page_limit = 1000
|
|
48
47
|
|
|
49
|
-
# Whether an invalid `limit` param (non-numeric,
|
|
50
|
-
# without `allow_meta_only_limit:`)
|
|
51
|
-
#
|
|
52
|
-
# `LimitResolutionMixin` in eluvia-base-django. (default: false)
|
|
48
|
+
# Whether `set_pagination` uses `default_limit` for an invalid `limit` param (non-numeric,
|
|
49
|
+
# negative, above `max_page_limit`, or zero without `allow_meta_only_limit:`) instead of
|
|
50
|
+
# rejecting it with 422. (default: false)
|
|
53
51
|
mattr_accessor :disable_pagination_errors
|
|
54
52
|
@@disable_pagination_errors = false
|
|
55
53
|
|
|
@@ -44,10 +44,18 @@ module Eluvia
|
|
|
44
44
|
# A blank `order_by` is treated as "not supplied" (falls through to defaults/fallback)
|
|
45
45
|
# rather than as a literal empty ordering, since a Kaminari scope always needs some order.
|
|
46
46
|
order_by = !force_order_by && user_order_by.present? ? user_order_by : default_order_by
|
|
47
|
-
order_by = "#{order_by},#{fallback_order_by}"
|
|
48
47
|
|
|
48
|
+
# Within `order_by` a repeated field takes its last direction; `fallback_order_by` only
|
|
49
|
+
# appends fields not already ordered by, so it never overrides the requested direction.
|
|
49
50
|
@order_by = {}
|
|
50
|
-
order_by
|
|
51
|
+
parse_order_by(order_by) { |field_name, direction| @order_by[field_name] = direction }
|
|
52
|
+
parse_order_by(fallback_order_by) { |field_name, direction| @order_by[field_name] ||= direction }
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
private
|
|
56
|
+
|
|
57
|
+
def parse_order_by(order_by)
|
|
58
|
+
order_by.to_s.split(',').each do |entry|
|
|
51
59
|
entry = entry.strip
|
|
52
60
|
# `-1` keeps a trailing empty segment (e.g. `name:`) instead of Ruby's default of
|
|
53
61
|
# dropping it, so it is caught below as an invalid direction rather than as a bare field.
|
|
@@ -68,13 +76,10 @@ module Eluvia
|
|
|
68
76
|
})
|
|
69
77
|
end
|
|
70
78
|
|
|
71
|
-
|
|
79
|
+
yield field_name, direction.to_sym
|
|
72
80
|
end
|
|
73
|
-
|
|
74
81
|
end
|
|
75
82
|
|
|
76
|
-
private
|
|
77
|
-
|
|
78
83
|
def resolve_pagination_limit(default_limit:, max_limit:, disable_errors:, allow_meta_only_limit:)
|
|
79
84
|
return default_limit unless params[:limit].present?
|
|
80
85
|
|
data/lib/eluvia/uploads.rb
CHANGED
|
@@ -2,8 +2,8 @@ module Eluvia
|
|
|
2
2
|
module Uploads
|
|
3
3
|
|
|
4
4
|
# Extension point for finalizing chunked/direct uploads (identified by `Eluvia::File#upload_key`)
|
|
5
|
-
# into the underlying ActiveStorage attachment.
|
|
6
|
-
#
|
|
5
|
+
# into the underlying ActiveStorage attachment. Unset by default, so the gem does not depend on
|
|
6
|
+
# any storage provider (e.g. aws-sdk-s3).
|
|
7
7
|
#
|
|
8
8
|
# Consumers register a callable of the form:
|
|
9
9
|
# ->(attachment_record, upload_key, filename) { ... }
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: eluvia-base
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 3.
|
|
4
|
+
version: 3.43.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Matěj Outlý
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2026-
|
|
11
|
+
date: 2026-11-09 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: rest-client
|
|
@@ -28,16 +28,22 @@ dependencies:
|
|
|
28
28
|
name: rails
|
|
29
29
|
requirement: !ruby/object:Gem::Requirement
|
|
30
30
|
requirements:
|
|
31
|
-
- - "
|
|
31
|
+
- - ">="
|
|
32
32
|
- !ruby/object:Gem::Version
|
|
33
33
|
version: '7.0'
|
|
34
|
+
- - "<"
|
|
35
|
+
- !ruby/object:Gem::Version
|
|
36
|
+
version: '9'
|
|
34
37
|
type: :runtime
|
|
35
38
|
prerelease: false
|
|
36
39
|
version_requirements: !ruby/object:Gem::Requirement
|
|
37
40
|
requirements:
|
|
38
|
-
- - "
|
|
41
|
+
- - ">="
|
|
39
42
|
- !ruby/object:Gem::Version
|
|
40
43
|
version: '7.0'
|
|
44
|
+
- - "<"
|
|
45
|
+
- !ruby/object:Gem::Version
|
|
46
|
+
version: '9'
|
|
41
47
|
- !ruby/object:Gem::Dependency
|
|
42
48
|
name: jwt
|
|
43
49
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -201,7 +207,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
|
201
207
|
requirements:
|
|
202
208
|
- - ">="
|
|
203
209
|
- !ruby/object:Gem::Version
|
|
204
|
-
version: '
|
|
210
|
+
version: '3.2'
|
|
205
211
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
206
212
|
requirements:
|
|
207
213
|
- - ">="
|