royal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1ae44a417ca2d8441ecd326e7d93fb50df992802a3857bff8b1e71e487b43600
+  data.tar.gz: 352ce9d947cfbe551e93dbce55d6491d75d7948b409d6d4f340866c2f41e4513
+SHA512:
+  metadata.gz: ae6451b26677cea399826b945967c251b2440a7bf9231050bff5d26869d86b4a604e5cf39c63cc59a23378ae148d018a7c0e56ed0ba07ec3d8110a4437ff4dac
+  data.tar.gz: 5578bcba479a0ab03cb11831dbdc18b28e1253c020224a382e293e6e31adba2c98a8f52b530d51f857c18c6a04d521f9512e642b48f1353754da8358fd591af3

data/.github/workflows/main.yml

@@ -0,0 +1,70 @@
+name: Ruby
+
+on: [push,pull_request]
+
+jobs:
+  rubocop:
+    name: Rubocop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.0
+          bundler-cache: true
+      - name: Run Rubocop
+        run: bin/rubocop
+
+  rspec-sqlite:
+    name: RSpec (SQLite3)
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: [2.6, 2.7, 3.0, 3.1]
+        locking-mode: [optimistic, pessimistic]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+      - name: Run RSpec (${{ matrix.locking-mode }} locking)
+        env:
+          TEST_LOCKING_MODE: ${{ matrix.locking-mode }}
+          TEST_DATABASE_ADAPTER: sqlite3
+        run: bin/rspec
+
+  rspec-postgresql:
+    name: RSpec (PostgreSQL)
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: [2.6, 2.7, 3.0, 3.1]
+        locking-mode: [optimistic, pessimistic, advisory]
+    services:
+      postgres:
+        image: postgres:13
+        ports:
+          - 5432:5432
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: royal_test
+        options: --health-cmd pg_isready --health-interval 5s --health-timeout 5s --health-retries 10
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+      - name: Run RSpec (${{ matrix.locking-mode }} locking)
+        env:
+          PGHOST: localhost
+          PGUSER: postgres
+          PGPASSWORD: postgres
+          TEST_LOCKING_MODE: ${{ matrix.locking-mode }}
+          TEST_DATABASE_ADAPTER: postgresql
+        run: bin/rspec

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.rspec_status

data/.rubocop.yml

@@ -0,0 +1,53 @@
+require:
+  - rubocop-performance
+  - rubocop-rails
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+  TargetRubyVersion: 2.6
+  Exclude:
+    - bin/*
+    - vendor/**/*
+
+Layout/AccessModifierIndentation:
+  EnforcedStyle: outdent
+
+Layout/LineLength:
+  Max: 120
+
+Lint/AmbiguousBlockAssociation:
+  Exclude:
+    - spec/**/*.rb
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*.rb
+
+Naming/RescuedExceptionsVariableName:
+  PreferredName: error
+
+Rails/ApplicationRecord:
+  Enabled: false
+
+RSpec/ExpectChange:
+  EnforcedStyle: block
+
+RSpec/HookArgument:
+  EnforcedStyle: each
+
+Style/Documentation:
+  Enabled: false
+
+Style/RescueModifier:
+  Exclude:
+    - spec/**/*.rb
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: single_quotes

data/.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+    "[ruby]": {
+        "editor.tabSize": 2
+    },
+    "ruby.rubocop.useBundler": true,
+    "cSpell.words": [
+        "hashtext",
+        "pointable",
+        "rubygems",
+        "xact"
+    ]
+}

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in royal.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+gem 'rspec', '~> 3.0'
+gem 'rubocop', '~> 1.25'
+gem 'rubocop-performance', '~> 1.12'
+gem 'rubocop-rails', '~> 2.13'
+gem 'rubocop-rspec', '~> 2.8'
+
+gem 'pg', '~> 1.3'
+gem 'sqlite3', '~> 1.4'

data/Gemfile.lock

@@ -0,0 +1,92 @@
+PATH
+  remote: .
+  specs:
+    royal (0.1.0)
+      activerecord (>= 5, < 8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (6.1.4.1)
+      activesupport (= 6.1.4.1)
+    activerecord (6.1.4.1)
+      activemodel (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+    activesupport (6.1.4.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
+    ast (2.4.2)
+    concurrent-ruby (1.1.9)
+    diff-lcs (1.4.4)
+    i18n (1.8.11)
+      concurrent-ruby (~> 1.0)
+    minitest (5.15.0)
+    parallel (1.21.0)
+    parser (3.1.0.0)
+      ast (~> 2.4.1)
+    pg (1.3.1)
+    rack (2.2.3)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.2.0)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.3)
+    rubocop (1.25.0)
+      parallel (~> 1.10)
+      parser (>= 3.1.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.15.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.15.1)
+      parser (>= 3.0.1.1)
+    rubocop-performance (1.12.0)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rails (2.13.2)
+      activesupport (>= 4.2.0)
+      rack (>= 1.1)
+      rubocop (>= 1.7.0, < 2.0)
+    rubocop-rspec (2.8.0)
+      rubocop (~> 1.19)
+    ruby-progressbar (1.11.0)
+    sqlite3 (1.4.2)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.1.0)
+    zeitwerk (2.5.3)
+
+PLATFORMS
+  x86_64-darwin-19
+  x86_64-linux
+
+DEPENDENCIES
+  pg (~> 1.3)
+  rake (~> 13.0)
+  royal!
+  rspec (~> 3.0)
+  rubocop (~> 1.25)
+  rubocop-performance (~> 1.12)
+  rubocop-rails (~> 2.13)
+  rubocop-rspec (~> 2.8)
+  sqlite3 (~> 1.4)
+
+BUNDLED WITH
+   2.2.22

data/README.md

@@ -0,0 +1,252 @@
+# Royal
+
+Royal adds loyalty (and other types of) points to your ActiveRecord models.
+It's backed by an internal ledger for balance tracking, provides a simple programmer interface, and is designed to handle concurrency and locking for you.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'royal'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install royal
+
+### Generating Configuration
+
+Generate the configuration file with:
+
+    $ bin/rails g royal:install
+
+This will place a configuration file at `config/initializers/royal.rb` in your Rails application directory.
+
+### Generating Migrations
+
+Generate the migration file with:
+
+    $ bin/rails g royal:migration
+
+And then run the migration:
+
+    $ bin/rails db:migrate
+
+## Usage
+
+To add a points balance to any of your ActiveRecord models, include the `Royal::Points` module.
+For the purposes of the examples below, we'll be using a hypothetical `User` model:
+
+```ruby
+class User < ApplicationRecord
+  include Royal::Points
+
+  # ...
+end
+```
+
+Royal uses a separate ledger table to track points for your models, so it's not necessary to add any columns to existing tables.
+
+### Viewing the Point Balance
+
+To view the current balance of a record, use the `current_points` method:
+
+```ruby
+user = User.first
+
+user.current_points # => 0
+```
+
+**NOTE:** The `current_points` method accesses the database each time it's called.
+
+### Adding Loyalty Points
+
+```ruby
+user.add_points(100) # => 100
+```
+
+This method returns the new points balance after the operation.
+
+### Spending Loyalty Points
+
+```ruby
+user.subtract_points(75) # => 25
+```
+
+This method returns the new points balance after the operation.
+
+If the current balance is less than the specified amount of points to subtract, a `Royal::InsufficientPointsError` is raised:
+
+```ruby
+user.subtract_points(200) # => raises #<Royal::InsufficientPointsError ...>
+```
+
+### Including a Reason or Note
+
+It's possible to include a String of text when adding or subtracting points, which will be stored with the change:
+
+```ruby
+user.add_points(50, reason: 'Birthday points!')
+```
+
+**NOTE:** By default, the reason can be at most 1000 characters long.
+
+### Linking to Another Record
+
+It's possible to link an additional record when adding or subtracting points.
+Below is an example using a hypothetical `Reward` model:
+
+```ruby
+reward = Reward.find_by(name: 'Gift Card')
+
+user.subtract_points(50, pointable: reward)
+```
+
+### Loyalty Point Balance History
+
+Since points are stored in a ledger, it's possible to view and display the complete history of a points balance:
+
+```erb
+<table>
+  <tr>
+    <th>Operation</th>
+    <th>Balance</th>
+    <th>Reason</th>
+  </tr>
+  <% user.point_balances.order(:sequence).each do |point_balance| %>
+    <tr>
+      <td><%= point_balance.amount.positive? ? 'Added' : 'Spent' %> <%= point_balance.amount %></td>
+      <td><%= point_balance.balance %></td>
+      <td><%= point_balance.reason %></td>
+    </tr>
+  <% end %>
+</table>
+```
+
+**NOTE:** For data integrity purposes, the `owner`, `amount`, `balance`, and `sequence` attributes on `Royal::PointBalance` records are as marked readonly once persisted to the database. Modifying the fields or removing existing balance records is not supported.
+
+## Concurrency and Locking
+
+Royal comes with built-in automatic locking around point balance changes.
+Since each applicable behaves differently, it also includes a few alternative locking strategies.
+
+Royal supports three possible locking modes:
+* Optimistic locking (default)
+* Pessimistic locking
+* Advisory locking (PosgreSQL only)
+
+Each mode has its own advantages and disadvantages, which are outlined in detail below.
+Optimistic locking is used by default and should work well in most use cases and even in high-load applications.
+In general, you shouldn't need to change this unless you start to experience `SequenceError`s.
+
+### Optimistic Locking (Default)
+
+This locking mode relies on a unique index specific to `owner` record such that: `(owner_id, owner_type, sequence)`.
+A `sequence` column is increased by 1 for every write to the points balance ledger, so any conflicting writes to the table would produce a duplicate value for the `sequence` column and be rejected by the uniqueness constraint.
+
+Whenever an update is rejected by this constraint, the operation is re-attempted with a new sequence value and updated balance calculation.
+By default, an update can be re-attempted up to 10 times before a `Royal::SequenceError` is raised.
+
+For most applications, updates should only be very rarely retried and generally resolve it an most one or two attempts.
+However, if your application needs to perform frequent, parallel balance updates for a single record, this may become a concern.
+(For example, an organization that receives points from all of its employees, or some other group that receives points from all of its members.)
+
+**NOTE:** You shouldn't usually need to change locking strategies unless you see frequent `SequenceError`s or otherwise experience poor performance.
+Even in cases where your application does perform a large number of parallel balance updates for the same record, you may see better results changing how your application applies these updates. (e.g. Using a queue to asynchronously apply updates in sequence from a separate task instead of in parallel.)
+
+### Pessimistic Locking
+
+This locking mode relies on row-level exclusive locks acquired on the `owner` record for the points balance.
+
+In general, this strategy is the slowest as it will be blocked by any other locks on the record, and will block all other operations on the record for the duration of the update.
+Unless you are experiencing issues with the optimistic locking strategy and are unable to leverage advisory locks for your applicable, use of the strategy is not advised.
+
+### Advisory Locking (PostgreSQL Only)
+
+This locking mode uses an exclusive advisory lock on a key that's unique to each `owner` record via `pg_advisory_xact_lock`.
+See more here: https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS
+
+Using advisory locking provides similar advantages to pessimistic locking without having to acquire a row-level lock on the owner record.
+Locking is done using the 2-argument version of `pg_advisory_xact_lock` using values computed based from their `owner` record's ID and polymorphic name.
+
+e.g. A lock for a `User` record with ID 1 would acquire a lock as so:
+```sql
+SELECT pg_advisory_xact_lock(hashtext('User'), 1)
+```
+
+When using advisory locks, there are situations where lock-keys could potentially experience collisions.
+Since advisory lock keys are 64-bits wide, it is unlikely to happen for most applications, but is still worth considering.
+
+Two possible situations where these keys would collide are:
+1. Your applicable already heavily relies on advisory locks. Note that the single 64-bit argument advisory lock uses a separate key space and does not overlap with the 2-argument key space.
+2. Your models have 64-bit (or greater) IDs and the bottom 32-bits are the same. Since the 2 key segments are restricted to 32-bits, this locking system only uses the bottom 32-bits of the `owner` record's ID as part of the lock key.
+
+In most cases, lock-keys colliding would just result in two or more unrelated records waiting before applying a point balance update.
+Unless your applicable has a very large number of `owner` records with overlapping keys that are frequently updated together, this shouldn't create any cause for concern.
+
+However, if your application falls into situation #1 described above and also holds advisory locks for extended periods of time, balance updates may stall for much longer than expected as they'll be blocked until the lock is released.
+
+### Transactions and Deadlock Prevention
+
+When adding or subtracting points from a single record, Royal automatically handles locking and usually poses no risk of deadlock (as locks are only acquired for a single record).
+However, when changing the points balances of multiple records together, care must be taken to avoid conditions that would result in a stall or deadlock.
+
+To make this easier, Royal providers a `Transaction` object which can be used to define and safely execute a sequence on points balance changes on a number of objects all at once.
+In the example below, we transfer 100 points from one user to another:
+
+```ruby
+transaction = Royal::Transaction.new
+
+user1 = User.find(1)
+user2 = User.find(2)
+
+transaction.add_points(user1, 100)
+transaction.subtract_points(user2, 100)
+
+transaction.call
+```
+
+Transactions have no limit on how many records can be involved or how many operations can be performed on each record. For example, it's possible to have a single transaction both add and subtract points from the same `User` record.
+
+Royal will re-order the addition/subtraction operations in such a way that:
+* Records will be modified in a deterministic order, to avoid deadlocks
+* If a single record has both addition and subtraction operations, addition will be performed first
+
+Just like when adding or subtracting points from a single record, the transaction interface allows you to specify a `reason` or associated `pointable` record.
+
+```ruby
+trade = Trade.find(...) # Some hypothetical trade record.
+
+transaction.add_points(user1, 100, reason: 'Trade from User 2', pointable: trade)
+transaction.subtract_points(user2, 100, reason: 'Trade to User 1', pointable: trade)
+```
+
+The transaction `add_points` and `subtract_points` methods also return the transaction object, so it's also possible to chain these method calls together if desired:
+
+```ruby
+transaction
+  .add_points(user1, 100)
+  .subtract_points(user2, 100)
+  .call
+```
+
+## Future Functionality and Wishlist
+
+ * [ ] Support multiple types of points per model
+ * [ ] Add RSpec matchers to assist in testing
+ * [ ] Improve documentation and examples
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mintyfresh/royal.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: :rubocop

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'royal'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/rubocop

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile',
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path('../bundle', __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rubocop', 'rubocop')

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/generators/royal/install_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module Royal
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      def create_initializer
+        template 'royal.rb', 'config/initializers/royal.rb'
+      end
+    end
+  end
+end

data/lib/generators/royal/migration_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Royal
+  module Generators
+    class MigrationGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      def self.next_migration_number(dir)
+        ::ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_point_balances_migration
+        migration_template 'create_point_balances.rb.erb', 'db/migrate/create_point_balances.rb'
+      end
+
+    private
+
+      def migration_version
+        "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]" if Rails.version >= '5.0.0'
+      end
+    end
+  end
+end

data/lib/generators/royal/templates/create_point_balances.rb.erb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class CreatePointBalances < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :point_balances do |t|
+      t.belongs_to :owner, polymorphic: true, null: false
+      t.belongs_to :pointable, polymorphic: true, null: true
+      t.string     :reason, null: true
+      t.integer    :amount, null: false
+      t.integer    :balance, null: false
+      t.integer    :sequence, null: false
+      t.timestamps
+
+      t.index %i[owner_id owner_type sequence], unique: true
+    end
+  end
+end

data/lib/generators/royal/templates/royal.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+Royal.configure do |config|
+  # Sets the locking for the points balance ledger.
+  #
+  # Available modes are:
+  #   - :optimistic (default)
+  #   - :pessimistic
+  #   - :advisory (PostgreSQL only)
+  #
+  # Most applications should use the default locking mode.
+  # For further information about each of the supported modes, see the README file:
+  # https://github.com/mintyfresh/royal#concurrency-and-locking
+  #
+  # config.locking = :optimistic
+
+  # Sets the maximum number of retries when using the optimistic locking mode. (default 10)
+  # config.max_retries = 10
+end

data/lib/royal/config.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Royal
+  class Config
+    DEFAULT_LOCKING     = :optimistic
+    DEFAULT_MAX_RETRIES = 10
+
+    # The configured locking mechanism for the points balance ledger.
+    #
+    # @return [#call]
+    attr_reader :locking
+    # @return [Integer]
+    attr_reader :max_retries
+
+    def initialize
+      self.locking     = DEFAULT_LOCKING
+      self.max_retries = DEFAULT_MAX_RETRIES
+    end
+
+    # @param locator [Symbol]
+    # @return [void]
+    def locking=(locator)
+      @locking = Royal::Locking.resolve(locator)
+    end
+
+    # @param max_retries [Integer]
+    # @return [void]
+    def max_retries=(max_retries)
+      raise ArgumentError, 'Max retries must be an Integer' unless max_retries.is_a?(Integer)
+      raise ArgumentError, 'Max retries must be positive' unless max_retries.positive?
+
+      @max_retries = max_retries
+    end
+  end
+end

data/lib/royal/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Royal
+  Error = Class.new(StandardError)
+end

data/lib/royal/insufficient_points_error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Royal
+  class InsufficientPointsError < Error
+    # @return [ActiveRecord::Base]
+    attr_reader :owner
+    # @return [Integer]
+    attr_reader :amount
+    # @return [Integer]
+    attr_reader :balance
+    # @return [String, nil]
+    attr_reader :reason
+    # @return [ActiveRecord::Base, nil]
+    attr_reader :pointable
+
+    # @param owner [ActiveRecord::Base]
+    # @param amount [Integer]
+    # @param balance [Integer]
+    # @param reason [String, nil]
+    # @param pointable [ActiveRecord::Base, nil]
+    def initialize(owner, amount, balance, reason, pointable)
+      @owner     = owner
+      @amount    = amount
+      @balance   = balance
+      @reason    = reason
+      @pointable = pointable
+
+      super("Insufficient points: #{amount} (balance: #{balance})")
+    end
+  end
+end

data/lib/royal/locking/advisory.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Royal
+  module Locking
+    class Advisory
+      # Used to extract the lower 32-bits of owner IDs.
+      # The 2-argument version of `pg_advisory_xact_lock` accepts 32 bit integers,
+      # and this ensures we do not overflow that constraint.
+      ID_LOBITS_MASK = 0xFFFFFFFF
+
+      # @param owner [ActiveRecord::Base]
+      def call(owner)
+        PointBalance.transaction(requires_new: true) do
+          acquire_advisory_lock_on_owner(owner)
+          yield
+        end
+      end
+
+    private
+
+      # @param owner [ActiveRecord::Base]
+      # @return [void]
+      def acquire_advisory_lock_on_owner(owner)
+        sql = PointBalance.sanitize_sql_array([<<-SQL.squish, owner.class.polymorphic_name, owner.id & ID_LOBITS_MASK])
+          SELECT pg_advisory_xact_lock(hashtext(?), ?)
+        SQL
+
+        PointBalance.connection.query(sql)
+      end
+    end
+  end
+end

data/lib/royal/locking/optimistic.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Royal
+  module Locking
+    class Optimistic
+      # @param owner [Royal::PointBalance]
+      def call(_owner, &block)
+        result = nil
+
+        up_to_max_retries do
+          success, result = try_create_record(&block)
+          return result if success
+        end
+
+        # NOTE: Failed to insert record after maximum number of attempts.
+        # This could be caused by too much write contention for the same owner.
+        # One possible solution is to acquire a row-level lock on the owner record and retry.
+        # Other solutions like advisory locks or sequential processing queues may work better in some situations.
+        raise Royal::SequenceError, "Failed to update points: #{result.message}"
+      end
+
+    private
+
+      def up_to_max_retries(&block)
+        Royal.config.max_retries.times(&block)
+      end
+
+      # @return [[Boolean, Object]]
+      def try_create_record
+        success = true
+        result  = nil
+
+        PointBalance.transaction(requires_new: true) do
+          result = yield
+        rescue ActiveRecord::RecordNotUnique => error
+          success = false
+          result  = error
+          raise ActiveRecord::Rollback
+        end
+
+        [success, result]
+      end
+    end
+  end
+end

data/lib/royal/locking/pessimistic.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Royal
+  module Locking
+    class Pessimistic
+      # @param owner [ActiveRecord::Base]
+      def call(owner)
+        owner.transaction(requires_new: true) do
+          # NOTE: Avoid using `lock!` to prevent reloading the record from DB.
+          # We don't need any updated state, just exclusive use of the record.
+          owner.class.where(id: owner).lock(true).take!
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/royal/locking.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Royal
+  module Locking
+    autoload :Advisory, 'royal/locking/advisory'
+    autoload :Optimistic, 'royal/locking/optimistic'
+    autoload :Pessimistic, 'royal/locking/pessimistic'
+
+    # @param locator [Symbol]
+    # @return [#call]
+    def self.resolve(locator)
+      case locator
+      when :advisory then Advisory.new
+      when :optimistic then Optimistic.new
+      when :pessimistic then Pessimistic.new
+      else raise ArgumentError, "Unsupported locking type: #{locator.inspect}"
+      end
+    end
+  end
+end

data/lib/royal/point_balance.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'active_record'
+
+module Royal
+  class PointBalance < ActiveRecord::Base
+    attr_readonly :owner_id, :owner_type, :amount, :balance, :sequence
+
+    belongs_to :owner, polymorphic: true, optional: false
+    belongs_to :pointable, polymorphic: true, optional: true
+
+    validates :amount, numericality: { other_than: 0 }
+    validates :reason, length: { maximum: 1000 }
+
+    before_create do
+      previous_balance = self.class.latest_for_owner(owner)
+
+      self.sequence = (previous_balance&.sequence || 0) + 1
+      self.balance  = (previous_balance&.balance  || 0) + amount
+    end
+
+    after_create if: -> { balance.negative? } do
+      # Rollback the transaction _after_ the operation to ensure amount
+      # was applied against the most recent points balance.
+      raise InsufficientPointsError.new(owner, amount, original_balance, reason, pointable)
+    end
+
+    # @param owner [ActiveRecord::Base]
+    # @return [PointBalance, nil]
+    def self.latest_for_owner(owner)
+      PointBalance.where(owner: owner).order(:sequence).last
+    end
+
+    # @param owner [ActiveRecord::Base]
+    def self.with_lock_on_owner(owner, &block)
+      Royal.config.locking.call(owner, &block)
+    end
+
+    # @param owner [ActiveRecord::Base]
+    # @param amount [Integer]
+    # @param attributes [Hash] Additional attributes to set on the new record.
+    # @return [Integer] Returns the new points balance.
+    def self.apply_change_to_points(owner, amount, **attributes)
+      with_lock_on_owner(owner) do
+        create!(owner: owner, amount: amount, **attributes).balance
+      end
+    end
+
+    # Returns the balance before this operation.
+    #
+    # @return [Integer]
+    def original_balance
+      balance - amount
+    end
+  end
+end

data/lib/royal/points.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module Royal
+  module Points
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :point_balances, as: :owner, inverse_of: :owner,
+                                class_name: 'Royal::PointBalance', dependent: :delete_all
+    end
+
+    # Returns the current number of points in the record's balance.
+    #
+    # @return [Integer]
+    def current_points
+      point_balances.order(sequence: :desc).limit(1).pluck(:balance).first || 0
+    end
+
+    # Adds a number of points to the record's current points balance.
+    #
+    # @param amount [Integer] The number of points to add to the blance.
+    # @param reason [String, nil] An optional reason to store with the balance change.
+    # @param pointable [ActiveRecord::Base, nil] An optional record to associate to the balance change.
+    # @return [Integer] Returns the new points balance.
+    def add_points(amount, reason: nil, pointable: nil)
+      point_balances.apply_change_to_points(self, amount, reason: reason, pointable: pointable)
+    end
+
+    # Subtracts a number of points to the record's current points balance.
+    #
+    # @param amount [Integer] The number of points to subtract from the balance.
+    # @param reason [String, nil] An optional reason to store with the balance change.
+    # @param pointable [ActiveRecord::Base, nil] An optional record to associate to the balance change.
+    # @return [Integer] Returns the new points balance.
+    def subtract_points(amount, reason: nil, pointable: nil)
+      point_balances.apply_change_to_points(self, -amount, reason: reason, pointable: pointable)
+    end
+  end
+end

data/lib/royal/sequence_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Royal
+  SequenceError = Class.new(Error)
+end

data/lib/royal/transaction.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Royal
+  class Transaction
+    Operation = Struct.new(:owner, :amount, :reason, :pointable) do
+      # @return [void]
+      def perform
+        owner.add_points(amount, reason: reason, pointable: pointable)
+      end
+
+      # Used to ensure a deterministic order of operations in a transaction to avoid deadlocks.
+      #
+      # @return [Array]
+      def sorting_key
+        [owner.class.polymorphic_name, owner.id, -amount]
+      end
+    end
+
+    def initialize
+      @operations = []
+    end
+
+    # @param owner [ActiveRecord::Base]
+    # @param amount [Integer]
+    # @param reason [String, nil]
+    # @param pointable [ActiveRecord::Base, nil]
+    # @return [self]
+    def add_points(owner, amount, reason: nil, pointable: nil)
+      @operations << Operation.new(owner, amount, reason, pointable).freeze
+
+      self
+    end
+
+    # @param owner [ActiveRecord::Base]
+    # @param amount [Integer]
+    # @param reason [String, nil]
+    # @param pointable [ActiveRecord::Base, nil]
+    # @return [self]
+    def subtract_points(owner, amount, reason: nil, pointable: nil)
+      add_points(owner, -amount, reason: reason, pointable: pointable)
+    end
+
+    # @return [self]
+    def call
+      PointBalance.transaction(requires_new: true) do
+        @operations.sort_by(&:sorting_key).each(&:perform)
+      end
+
+      self
+    end
+  end
+end

data/lib/royal/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Royal
+  VERSION = '0.1.0'
+end

data/lib/royal.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'royal/version'
+
+require_relative 'royal/error'
+require_relative 'royal/insufficient_points_error'
+require_relative 'royal/sequence_error'
+
+require_relative 'royal/config'
+require_relative 'royal/points'
+require_relative 'royal/point_balance'
+require_relative 'royal/locking'
+require_relative 'royal/transaction'
+
+module Royal
+  # @return [Royal::Config]
+  def self.config
+    @config ||= Royal::Config.new.freeze
+  end
+
+  # @return [void]
+  def self.configure
+    config = Royal::Config.new
+    yield(config)
+
+    @config = config.freeze
+  end
+end

data/royal.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/royal/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'royal'
+  spec.version       = Royal::VERSION
+  spec.authors       = ['Minty Fresh']
+  spec.email         = ['7896757+mintyfresh@users.noreply.github.com']
+
+  spec.summary       = 'Loyalty Points for ActiveRecord'
+  spec.description   = 'Ledger backed loyalty points for your ActiveRecord models'
+  spec.homepage      = 'https://github.com/mintyfresh/royal'
+
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org/'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activerecord', '>= 5', '< 8'
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: royal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Minty Fresh
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2022-02-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+description: Ledger backed loyalty points for your ActiveRecord models
+email:
+- 7896757+mintyfresh@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/main.yml"
+- ".gitignore"
+- ".rubocop.yml"
+- ".vscode/settings.json"
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/console
+- bin/rspec
+- bin/rubocop
+- bin/setup
+- lib/generators/royal/install_generator.rb
+- lib/generators/royal/migration_generator.rb
+- lib/generators/royal/templates/create_point_balances.rb.erb
+- lib/generators/royal/templates/royal.rb
+- lib/royal.rb
+- lib/royal/config.rb
+- lib/royal/error.rb
+- lib/royal/insufficient_points_error.rb
+- lib/royal/locking.rb
+- lib/royal/locking/advisory.rb
+- lib/royal/locking/optimistic.rb
+- lib/royal/locking/pessimistic.rb
+- lib/royal/point_balance.rb
+- lib/royal/points.rb
+- lib/royal/sequence_error.rb
+- lib/royal/transaction.rb
+- lib/royal/version.rb
+- royal.gemspec
+homepage: https://github.com/mintyfresh/royal
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org/
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/mintyfresh/royal
+  source_code_uri: https://github.com/mintyfresh/royal
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key: 
+specification_version: 4
+summary: Loyalty Points for ActiveRecord
+test_files: []