rotulus 0.2.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15fae43a1fc07b2c268c1604c065a12f0d2288d733219aa563348019a872d7a0
-  data.tar.gz: ca8548477eee36f6bed018d8ec20d5dd5217f74d36954f13b4e243fbaee6755e
+  metadata.gz: 149f276bc80e599488039c9858f817000766d74d6a494c1447ec58167a83c424
+  data.tar.gz: dad1c9cad5c214e88ede97573c18fbff1b65ed4a21e46b045a388910b325b5a7
 SHA512:
-  metadata.gz: f9d0e4611e800688f8c10ad7347043a07e7358f79a4254ecac6359a1f5f4101d323cfe0b21d45b363984cdc681e3ffc8b8b9587311e96553ab952eb76016792b
-  data.tar.gz: a3240e33d45cd4360c4235e94860558c584a9f1f373c9ad7451ad9d819c2616f5a2e2146bef0449b716b846144ee87c19e92596c2b39c13e34bef254f49c50af
+  metadata.gz: aab89cbb1f43d71ceddfe8cb1bb60d2d343f3d114109cb3d97d8650bca138d31893a1d803d7563b01ec51cca5eb3d227878f1fe2569d521edf6b9fc12ac2d364
+  data.tar.gz: 73e0d95ca8771ca86517f6fcf3def575b5536b269f3d6cdb65c7be887f633fa872bb0d8bc479c7932a592ba0bd204f29d5ba7ba2a43acb54546981c65c62c102

data/CHANGELOG.md

@@ -8,4 +8,11 @@
 - Raise error when there is no non-nullable and distinct column in the configured order definition.
 
 ## 0.2.3
-- Replace any existing order defined on the given ar_relation
+- Replace any existing order defined on the given ar_relation
+
+## 0.2.4
+- Allow changing limit param.
+
+## 1.0.0
+- Allow changing of ar_relation and order by default.
+- Make error class names consistent.

data/README.md

@@ -19,7 +19,7 @@ Some advantages of this approach are:
 * `NULLS FIRST`/`NULLS LAST` handling
 * Allows custom cursor format
 * Built-in cursor token expiration
-* Built-in cursor integrity check
+* Built-in cursor integrity checking
 * Supports **MySQL**, **PostgreSQL**, and **SQLite**
 * Supports **Rails 4.2** and above
 
@@ -45,8 +45,7 @@ gem install rotulus
 ```
 
 ## Configuration
-At the very least you only need to set the environment variable `ROTULUS_SECRET` to a random string(e.g. generate via `rails secret`).
-For more configuration options:
+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:
 
 #### Create an initializer `config/initializers/rotulus.rb`:
 
@@ -57,6 +56,8 @@ Rotulus.configure do |config|
   config.secret = ENV["MY_ENV_VAR"]
   config.token_expires_in = 10800
   config.cursor_class = MyCursor
+  config.restrict_order_change = false
+  config.restrict_query_change = false
 end
 ```
 
@@ -64,8 +65,10 @@ end
 | ----------- | ----------- |
 | `page_default_limit` | **Default: 5** <br/> Default record limit per page in case the `:limit` is not given when initializing a page `Rotulus::Page.new(...)` |
 | `page_max_limit` | **Default: 50** <br/> Maximum `:limit` value allowed when initializing a page.|
-| `secret` | **Default: ENV['ROTULUS_SECRET']** <br/> Key needed to generate the cursor state. |
+| `secret` | **Default: ENV['ROTULUS_SECRET']** <br/> Key needed to generate the cursor state needed for cursor integrity checking. |
 | `token_expires_in` | **Default: 259200**(3 days) <br/> Validity period of a cursor token (in seconds). Set to `nil` to disable token expiration. |
+| `restrict_order_change` | **Default: false** <br/> When `true`, raise an `OrderChanged` error when paginating with a token that was generated from a page instance with a different `:order`. <br/> When `false`, no error is raised and pagination is based on the new `:order` definition. |
+| `restrict_query_change` | **Default: false** <br/> When `true`, raise a `QueryChanged` error when paginating with a token that was generated from a page instance with a different `:ar_relation` filter/query. <br/> When `false`, no error is raised and pagination will query based on the new `:ar_relation`. |
 | `cursor_class` | **Default: Rotulus::Cursor** <br/> Cursor class responsible for encoding/decoding cursor data. Default uses Base64 encoding. see [Custom Token Format](#custom-token-format). |
 <br/>
 
@@ -79,20 +82,19 @@ end
 ```ruby
 users = User.where('age > ?', 16)
 
-page = Rotulus::Page.new(users, order: { first_name: :asc, last_name: :desc }, limit: 3)
+page = Rotulus::Page.new(users, order: { id: :asc })
+# OR just
+page = Rotulus::Page.new(users)
 ```
-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.
-
 
-###### Example with `ORDER BY users.id asc` only:
+###### Example when sorting with multiple columns and `:limit`:
 
 ```ruby
-page = Rotulus::Page.new(users, order: { id: :asc } limit: 3)
-
-# OR
 
-page = Rotulus::Page.new(users, limit: 3)
+page = Rotulus::Page.new(users, order: { first_name: :asc, last_name: :desc }, limit: 3)
 ```
+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.
+
 
 #### Access the page records
 
@@ -295,13 +297,15 @@ page = Rotulus::Page.new(items, order: order_by, limit: 2)
 
 | Class | Description |
 | ----------- | ----------- |
-| `Rotulus::InvalidCursor` | Cursor token received is invalid e.g., unrecognized token, token data has been tampered/updated, base ActiveRecord relation filter/sorting/limit is no longer consistent to the token. |
+| `Rotulus::InvalidCursor` | Cursor token received is invalid e.g., unrecognized token, token data has been tampered/updated. |
 | `Rotulus::Expired` | Cursor token received has expired based on the configured `token_expires_in` |
 | `Rotulus::InvalidLimit` | Limit set to Rotulus::Page is not valid. e.g., exceeds the configured limit. see `config.page_max_limit` |
 | `Rotulus::CursorError` | Generic error for cursor related validations |
-| `Rotulus::InvalidColumnError` | Column provided in the :order param can't be found. |
-| `Rotulus::MissingTiebreakerError` | There is no non-nullable and distinct column in the configured order definition. |
+| `Rotulus::InvalidColumn` | Column provided in the :order param can't be found. |
+| `Rotulus::MissingTiebreaker` | There is no non-nullable and distinct column in the configured order definition. |
 | `Rotulus::ConfigurationError` | Generic error for missing/invalid configurations. |
+| `Rotulus::OrderChanged` | Error raised paginating with a token(i.e. calling `Page#at` or `Page#at!`) that was generated from a previous page instance with a different `:order` definition. Can be enabled by setting the `restrict_order_change` to true. |
+| `Rotulus::QueryChanged` | Error raised paginating with a token(i.e. calling `Page#at` or `Page#at!`) that was generated from a previous page instance with a different `:ar_relation` filter/query. Can be enabled by setting the `restrict_query_change` to true. |
 
 ## How it works
 Cursor-based pagination uses a reference point/record to fetch the previous or next set of records. This gem takes care of the SQL query and cursor generation needed for the pagination. To ensure that the pagination results are stable, it requires that:
@@ -380,8 +384,10 @@ To navigate between pages, a cursor is used. The cursor token is a Base64 encode
 ```
 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.
 2. `d` - the pagination direction. `next` or `prev` set of records from the reference values in "f".
-3. `s` - the cursor state needed for integrity check so we can detect whether the base ActiveRecord relation filter/sorting is no longer consistent(e.g. API request params changed) with the cursor token. Additionally, to restrict clients/third-parties from generating their own (unsafe)tokens or to tamper 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.
-4. `c` -  the time when this cursor was generated.
+3. `cs` - the cursor state needed for integrity checking, restrict clients/third-parties from generating their own (unsafe)tokens, or from tampering the data of an existing token. 
+4. `os` - the order state needed to detect whether the order definition changed.
+5. `qs` - the base AR relation state neede to detect whether the ar_relation has changed (e.g. filter/query changed due to API params). 
+4. `c` -  cursor token issuance time.
 
 A condition generated from the cursor above would look like:
 
@@ -461,7 +467,7 @@ end
   | Environment Variable | Values | Example |
   | ----------- | ----------- |----------- |
   | `DB_ADAPTER` | **Default: :sqlite**. `sqlite`,`mysql2`, or `postgresql` | ```DB_ADAPTER=postgresql bundle exec rspec```<br/><br/> ```DB_ADAPTER=postgresql ./bin/console``` |
-  | `RAILS_VERSION` | **Default: 7-0-stable** <br/><br/> `4-2-stable`,`5-0-stable`,`5-1-stable`,<br/>`5-2-stable`,`6-0-stable`,`6-1-stable`,<br/>`7-0-stable` |```RAILS_VERSION=5-2-stable ./bin/setup```<br/><br/>```RAILS_VERSION=5-2-stable  bundle exec rspec```<br/><br/> ```RAILS_VERSION=5-2-stable ./bin/console```|
+  | `RAILS_VERSION` | **Default: 7-0** <br/><br/> `4-2`,`5-0`,`5-1`,`5-2`,`6-0`,`6-1`,`7-0` |```RAILS_VERSION=5-2 ./bin/setup```<br/><br/>```RAILS_VERSION=5-2 bundle exec rspec```<br/><br/> ```RAILS_VERSION=5-2 ./bin/console```|
 
 
 <br/><br/>

data/lib/rotulus/column.rb

@@ -27,7 +27,7 @@ module Rotulus
       @model = model
       @name = name.to_s
       unless name_valid?
-        raise Rotulus::InvalidColumnError.new("Column/table name must contain letters, digits (0-9), or \
+        raise Rotulus::InvalidColumn.new("Column/table name must contain letters, digits (0-9), or \
           underscores and must begin with a letter or underscore.".squish)
       end
 

data/lib/rotulus/configuration.rb

@@ -6,8 +6,10 @@ module Rotulus
       @page_default_limit = default_limit
       @page_max_limit = default_max_limit
       @secret = ENV['ROTULUS_SECRET']
-      @token_expires_in = 259200
+      @token_expires_in = 259_200
       @cursor_class = default_cursor_class
+      @restrict_order_change = false
+      @restrict_query_change = false
     end
 
     def page_default_limit=(limit)
@@ -49,6 +51,22 @@ module Rotulus
       @cursor_class || default_cursor_class
     end
 
+    def restrict_order_change=(restrict)
+      @restrict_order_change = !!restrict
+    end
+
+    def restrict_order_change?
+      @restrict_order_change
+    end
+
+    def restrict_query_change=(restrict)
+      @restrict_query_change = !!restrict
+    end
+
+    def restrict_query_change?
+      @restrict_query_change
+    end
+
     private
 
     def default_cursor_class

data/lib/rotulus/cursor.rb

@@ -9,19 +9,32 @@ module Rotulus
       #  @param token [String] Base64-encoded string data
       #  @return [Cursor] Cursor
       #
-      #  @raise [InvalidCursor] if the cursor is no longer consistent to the page's ActiveRecord
-      #    relation filters, sorting, limit, or if the encoded cursor data was tampered.
+      #  @raise [InvalidCursor] if the token can't be decoded or if the cursor data was tampered.
+      #  @raise [OrderChanged] if token generated from a page with a different `:order` definition.
+      #  @raise [QueryChanged] if token generated from a page with a different `:ar_relation`.
       def for_page_and_token!(page, token)
         data = decode(token)
         reference_record = Record.new(page, data[:f])
         direction = data[:d]
         created_at = Time.at(data[:c]).utc
-        state = data[:s].presence
+        cursor_state = data[:cs].presence
+        order_state = data[:os].presence
+        query_state = data[:qs].presence
 
         cursor = new(reference_record, direction, created_at: created_at)
 
-        if cursor.state != state
-          raise InvalidCursor.new('Invalid cursor possibly due to filter, order, or limit changed')
+        raise InvalidCursor if cursor.state != cursor_state
+
+        if page.order_state != order_state
+          raise OrderChanged if Rotulus.configuration.restrict_order_change?
+
+          return nil
+        end
+
+        if page.query_state != query_state
+          raise QueryChanged if Rotulus.configuration.restrict_query_change?
+
+          return nil
         end
 
         cursor
@@ -36,7 +49,7 @@ module Rotulus
       #    page if page direction is `:prev`.
       def decode(token)
         Oj.load(Base64.urlsafe_decode64(token))
-      rescue ArgumentError => e
+      rescue ArgumentError, Oj::ParseError => e
         raise InvalidCursor.new("Invalid Cursor: #{e.message}")
       end
 
@@ -93,19 +106,19 @@ module Rotulus
     def to_token
       @token ||= self.class.encode(f: record.values,
                                    d: direction,
-                                   s: state,
-                                   c: created_at.to_i)
+                                   c: created_at.to_i,
+                                   cs: state,
+                                   os: page.order_state,
+                                   qs: page.query_state)
     end
     alias to_s to_token
 
-    # Generate a 'state' string so we can detect whether the cursor data is no longer consistent to
-    # the AR filter, limit, or order definition. This also provides a mechanism to detect if
-    # any token data was tampered.
+    # Generate a 'state' string for integrity checking of the reference record, direction,
+    # and created_at data from a decoded Cursor token.
     #
     # @return [String] the hashed state
     def state
-      state_data = "#{page.state}#{record.state}"
-      state_data << "#{direction}#{created_at.to_i}#{secret}"
+      state_data = "#{record.state}#{direction}#{created_at.to_i}#{secret}"
 
       Digest::MD5.hexdigest(state_data)
     end

data/lib/rotulus/order.rb

@@ -13,7 +13,8 @@ module Rotulus
       build_column_definitions
 
       return if has_tiebreaker?
-      raise Rotulus::MissingTiebreakerError.new('A non-nullable and distinct column is required.')
+
+      raise Rotulus::MissingTiebreaker.new('A non-nullable and distinct column is required.')
     end
 
     # Returns an array of the ordered columns
@@ -79,7 +80,9 @@ module Rotulus
     #
     # @return [String] the hashed state
     def state
-      Digest::MD5.hexdigest(Oj.dump(to_h, mode: :rails))
+      data = Oj.dump(to_h, mode: :rails)
+
+      Digest::MD5.hexdigest("#{data}#{Rotulus.configuration.secret}")
     end
 
     # Returns a hash containing the hash representation of the ordered columns.
@@ -123,7 +126,7 @@ module Rotulus
       unless model_override.nil?
         return model_override unless model_override.columns_hash[unprefixed_name].nil?
 
-        raise Rotulus::InvalidColumnError.new(
+        raise Rotulus::InvalidColumn.new(
           "Model '#{model_override}' doesnt have a '#{name}' column. \
           Tip: check the :model option value in the column's order configuration.".squish
         )
@@ -134,7 +137,7 @@ module Rotulus
         return ar_model
       end
 
-      raise Rotulus::InvalidColumnError.new(
+      raise Rotulus::InvalidColumn.new(
         "Unable determine which model the column '#{name}' belongs to. \
         Tip: set/check the :model option value in the column's order configuration.".squish
       )

data/lib/rotulus/page.rb

@@ -2,7 +2,7 @@ module Rotulus
   class Page
     attr_reader :ar_relation, :order, :limit, :cursor
 
-    delegate :columns, to: :order, prefix: true
+    delegate :columns, :state, to: :order, prefix: true
 
     # Creates a new Page instance representing a subset of the given ActiveRecord::Relation
     # records sorted using the given 'order' definition param.
@@ -176,12 +176,14 @@ module Rotulus
       }.delete_if { |_, token| token.nil? }
     end
 
-    # Return Hashed value of this page's state so we can check whether the ar_relation's filter,
-    # order definition, and limit are still consistent to the cursor. see Cursor.state_valid?.
+    # Return Hashed value of this page's state so we can check whether the base ar_relation has
+    # changed(e.g. SQL/filters from API params). see Cursor.for_page_and_token!
     #
     # @return [String] the hashed state
-    def state
-      Digest::MD5.hexdigest("#{ar_relation.to_sql}~#{order.state}~#{limit}")
+    def query_state
+      data = ar_relation.to_sql
+
+      Digest::MD5.hexdigest("#{data}#{Rotulus.configuration.secret}")
     end
 
     # Returns a string showing the page's records in table form with the ordered columns

data/lib/rotulus/version.rb

@@ -1,3 +1,3 @@
 module Rotulus
-  VERSION = '0.2.3'
+  VERSION = '1.0.0'.freeze
 end

data/lib/rotulus.rb

@@ -15,14 +15,16 @@ require 'rotulus/page'
 
 module Rotulus
   class BaseError < StandardError; end
+  class InvalidLimit < BaseError; end
   class CursorError < BaseError; end
   class InvalidCursor < CursorError; end
   class ExpiredCursor < CursorError; end
   class InvalidCursorDirection < CursorError; end
-  class InvalidLimit < BaseError; end
+  class OrderChanged < CursorError; end
+  class QueryChanged < CursorError; end
   class ConfigurationError < BaseError; end
-  class MissingTiebreakerError < ConfigurationError; end
-  class InvalidColumnError < ConfigurationError; end
+  class MissingTiebreaker < ConfigurationError; end
+  class InvalidColumn < ConfigurationError; end
 
   def self.db
     @db ||= case ActiveRecord::Base.connection.adapter_name.downcase

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rotulus
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Uy Jayson B
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-05-23 00:00:00.000000000 Z
+date: 2023-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -19,7 +19,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 7.0.5
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 7.0.5
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -39,7 +39,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 7.0.5
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -49,7 +49,7 @@ dependencies:
         version: '4.2'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 7.0.5
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: oj
   requirement: !ruby/object:Gem::Requirement