rotulus 0.2.3 → 0.2.4
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +4 -1
- data/README.md +12 -14
- data/lib/rotulus/cursor.rb +3 -3
- data/lib/rotulus/page.rb +3 -3
- data/lib/rotulus/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: dabab916c4cd609c84cf4dea85172a337df2501f846d3747e072ddc4c2ea5995
|
4
|
+
data.tar.gz: acd18440bd31048eec4cc7aa7afefb4609265a6bbe6002d6e3bea65ebc331eec
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: c951e3a06482187d8d340d1f66f67b71b8aadf955a48fa4f190fb1edeb921615c7ec47977faf57019c645ca27c3eb66dc31e9b5b4e57aac61323e0a356fdc875
|
7
|
+
data.tar.gz: fc5ba3d91f64aff2aa0a9594beffe646c99955ef369f590de1f538cc31e31ef6903a3321f4e7adaa1ad62f3e47db3c8a6e7450f97a7a5209d2784d5286ad5f3b
|
data/CHANGELOG.md
CHANGED
@@ -8,4 +8,7 @@
|
|
8
8
|
- Raise error when there is no non-nullable and distinct column in the configured order definition.
|
9
9
|
|
10
10
|
## 0.2.3
|
11
|
-
- Replace any existing order defined on the given ar_relation
|
11
|
+
- Replace any existing order defined on the given ar_relation
|
12
|
+
|
13
|
+
## 0.2.4
|
14
|
+
- Allow changing limit param
|
data/README.md
CHANGED
@@ -19,7 +19,7 @@ Some advantages of this approach are:
|
|
19
19
|
* `NULLS FIRST`/`NULLS LAST` handling
|
20
20
|
* Allows custom cursor format
|
21
21
|
* Built-in cursor token expiration
|
22
|
-
* Built-in cursor integrity
|
22
|
+
* Built-in cursor integrity checking
|
23
23
|
* Supports **MySQL**, **PostgreSQL**, and **SQLite**
|
24
24
|
* Supports **Rails 4.2** and above
|
25
25
|
|
@@ -45,8 +45,7 @@ gem install rotulus
|
|
45
45
|
```
|
46
46
|
|
47
47
|
## Configuration
|
48
|
-
|
49
|
-
For more configuration options:
|
48
|
+
Setting the environment variable `ROTULUS_SECRET` to a random string value(e.g. generate via `rails secret`) is the minimum required setup needed. But for more configuration options:
|
50
49
|
|
51
50
|
#### Create an initializer `config/initializers/rotulus.rb`:
|
52
51
|
|
@@ -79,20 +78,19 @@ end
|
|
79
78
|
```ruby
|
80
79
|
users = User.where('age > ?', 16)
|
81
80
|
|
82
|
-
page = Rotulus::Page.new(users, order: {
|
81
|
+
page = Rotulus::Page.new(users, order: { id: :asc })
|
82
|
+
# OR just
|
83
|
+
page = Rotulus::Page.new(users)
|
83
84
|
```
|
84
|
-
Example above will automatically add the table's PK(`users.id`) in the generated SQL query as tie-breaker if the PK isn't included in the `:order` column config yet.
|
85
|
-
|
86
85
|
|
87
|
-
###### Example with
|
86
|
+
###### Example when sorting with multiple columns and `:limit`:
|
88
87
|
|
89
88
|
```ruby
|
90
|
-
page = Rotulus::Page.new(users, order: { id: :asc } limit: 3)
|
91
|
-
|
92
|
-
# OR
|
93
89
|
|
94
|
-
page = Rotulus::Page.new(users, limit: 3)
|
90
|
+
page = Rotulus::Page.new(users, order: { first_name: :asc, last_name: :desc }, limit: 3)
|
95
91
|
```
|
92
|
+
With the example above, the gem will automatically add the table's PK(`users.id`) in the generated SQL query as the tie-breaker column to ensure stable sorting and pagination.
|
93
|
+
|
96
94
|
|
97
95
|
#### Access the page records
|
98
96
|
|
@@ -295,7 +293,7 @@ page = Rotulus::Page.new(items, order: order_by, limit: 2)
|
|
295
293
|
|
296
294
|
| Class | Description |
|
297
295
|
| ----------- | ----------- |
|
298
|
-
| `Rotulus::InvalidCursor` | Cursor token received is invalid e.g., unrecognized token, token data has been tampered/updated, base ActiveRecord relation filter/sorting
|
296
|
+
| `Rotulus::InvalidCursor` | Cursor token received is invalid e.g., unrecognized token, token data has been tampered/updated, base ActiveRecord relation filter/sorting is no longer consistent to the token. |
|
299
297
|
| `Rotulus::Expired` | Cursor token received has expired based on the configured `token_expires_in` |
|
300
298
|
| `Rotulus::InvalidLimit` | Limit set to Rotulus::Page is not valid. e.g., exceeds the configured limit. see `config.page_max_limit` |
|
301
299
|
| `Rotulus::CursorError` | Generic error for cursor related validations |
|
@@ -380,8 +378,8 @@ To navigate between pages, a cursor is used. The cursor token is a Base64 encode
|
|
380
378
|
```
|
381
379
|
1. `f` - contains the record values from the last record of the current page. Only the columns included in the `ORDER BY` are included. Note also that the unique column `users.id` is included as a tie-breaker.
|
382
380
|
2. `d` - the pagination direction. `next` or `prev` set of records from the reference values in "f".
|
383
|
-
3. `s` - the cursor state needed for integrity
|
384
|
-
4. `c` -
|
381
|
+
3. `s` - the cursor state needed for integrity checking so we can detect whether the base ActiveRecord relation filter(initial `WHERE` conditions) are no longer consistent with the cursor (e.g., API parameters have changed). Additionally, to restrict clients/third-parties from generating their own (unsafe)tokens or from tampering the data of an existing token. The gem requires a secret key configured for this through the `ROTULUS_SECRET` environment variable or the `config.secret` configuration. see [Configuration](#configuration) section.
|
382
|
+
4. `c` - cursor token issuance time.
|
385
383
|
|
386
384
|
A condition generated from the cursor above would look like:
|
387
385
|
|
data/lib/rotulus/cursor.rb
CHANGED
@@ -10,7 +10,7 @@ module Rotulus
|
|
10
10
|
# @return [Cursor] Cursor
|
11
11
|
#
|
12
12
|
# @raise [InvalidCursor] if the cursor is no longer consistent to the page's ActiveRecord
|
13
|
-
# relation filters, sorting,
|
13
|
+
# relation filters, sorting, or if the encoded cursor data was tampered.
|
14
14
|
def for_page_and_token!(page, token)
|
15
15
|
data = decode(token)
|
16
16
|
reference_record = Record.new(page, data[:f])
|
@@ -21,7 +21,7 @@ module Rotulus
|
|
21
21
|
cursor = new(reference_record, direction, created_at: created_at)
|
22
22
|
|
23
23
|
if cursor.state != state
|
24
|
-
raise InvalidCursor.new('Invalid cursor possibly due to filter
|
24
|
+
raise InvalidCursor.new('Invalid cursor possibly due to filter or sorting changed')
|
25
25
|
end
|
26
26
|
|
27
27
|
cursor
|
@@ -99,7 +99,7 @@ module Rotulus
|
|
99
99
|
alias to_s to_token
|
100
100
|
|
101
101
|
# Generate a 'state' string so we can detect whether the cursor data is no longer consistent to
|
102
|
-
# the AR filter
|
102
|
+
# the AR filter or order definition. This also provides a mechanism to detect if
|
103
103
|
# any token data was tampered.
|
104
104
|
#
|
105
105
|
# @return [String] the hashed state
|
data/lib/rotulus/page.rb
CHANGED
@@ -176,12 +176,12 @@ module Rotulus
|
|
176
176
|
}.delete_if { |_, token| token.nil? }
|
177
177
|
end
|
178
178
|
|
179
|
-
# Return Hashed value of this page's state so we can check whether the ar_relation's filter
|
180
|
-
# order definition
|
179
|
+
# Return Hashed value of this page's state so we can check whether the ar_relation's filter and
|
180
|
+
# order definition are still consistent to the cursor. see Cursor.state_valid?.
|
181
181
|
#
|
182
182
|
# @return [String] the hashed state
|
183
183
|
def state
|
184
|
-
Digest::MD5.hexdigest("#{ar_relation.to_sql}~#{order.state}
|
184
|
+
Digest::MD5.hexdigest("#{ar_relation.to_sql}~#{order.state}")
|
185
185
|
end
|
186
186
|
|
187
187
|
# Returns a string showing the page's records in table form with the ordered columns
|
data/lib/rotulus/version.rb
CHANGED
metadata
CHANGED
@@ -1,14 +1,14 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: rotulus
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.2.
|
4
|
+
version: 0.2.4
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Uy Jayson B
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2023-05-
|
11
|
+
date: 2023-05-24 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: activerecord
|