iry 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 21ffff3b3300f8b100bbe0af995b5d0736260f8c17ca93c9f6e66b44b9fd3088
+  data.tar.gz: 5df2033893b5f5d8e8bdf7c97061f8bacc185620daa9a42b87167e945cf534ae
+SHA512:
+  metadata.gz: dbc9d0e8a465a34834007308bce3955ed5248c8a93699f81a346c6472cf153dc3df982217868a0392b510f32a0d3fc7ead3c6e9474bc55a508fd976a03e64be4
+  data.tar.gz: 3810fa311f0c09b51dd681eeaa31d6e36eb6a9ee3c131042e43cc525a0231a8df8cbe6f4ae2a55588de95ca3c7e950bf4ef36bc56410214c9adc71f1ceea1ab7

data/.envrc.example

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+export PGDATABASE=iry_development
+export PGHOST=localhost
+export PGPORT=5432
+export PGUSER=postgres

data/.yardopts

@@ -0,0 +1 @@
+--no-private 'lib/**/*.rb' - 'README.md' 'CHANGELOG.md' VERSION LICENSE '.envrc.example' Gemfile 'Gemfile.lock' 'db/schema.pgsql' 'iry.gemspec'

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2023-07-04
+
+- Initial release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Francesco Belladonna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,119 @@
+# Iry
+
+Convert constraint errors into Rails model validation errors.
+
+## Usage
+
+Given the following database schema:
+
+```sql
+create extension if not exists "pgcrypto";
+create extension if not exists "btree_gist";
+
+create table if not exists users (
+    id uuid primary key default gen_random_uuid(),
+    unique_text text unique not null default gen_random_uuid()::text
+    created_at timestamp(6) not null,
+    updated_at timestamp(6) not null
+);
+```
+
+The following constraint can be used on the `User` class:
+
+```ruby
+class User < ActiveRecord::Base
+  include Iry
+
+  belongs_to :user, optional: true
+
+  unique_constraint :unique_text
+end
+```
+
+When saving a new `User` record or updating it, in case constraint exceptions are raised, these will be rescued and
+validation errors will be applied to the record, like in the following example:
+
+```ruby
+user = User.create!(unique_text: "some unique text")
+
+fail_user = User.create(unique_text: "some unique text")
+
+fail_user.errors.details.fetch(:unique_text) #=> [{error: :taken}]
+```
+
+Multiple constraints of the same or different types can be present on the model, as long as the `:name` is different.
+
+The following constraint types are available:
+- [`check_constraint`](#check_constraint)
+- [`exclusion_constraint`](#exclusion_constraint)
+- [`foreign_key_constraint`](#foreign_key_constraint)
+- [`unique_constraint`](#unique_constraint)
+
+The class method `.constraints` is also available, that returns all the constraints applied to a model.
+
+## Constraints
+
+### `check_constraint`
+
+Catches a specific check constraint violation.
+
+- **key** (`Symbol`) which key will have validation errors added to
+- **name** (optional `String`) constraint name in the database, to detect constraint errors. Infferred if omitted
+- **message** (optional `String` or `Symbol`) error message, defaults to `:invalid`
+
+### `exclusion_constraint`
+
+Catches a specific exclusion constraint violation.
+
+- **key** (`Symbol`) which key will have validation errors added to
+- **name** (optional `String`) constraint name in the database, to detect constraint errors. Infferred if omitted
+- **message** (optional `String` or `Symbol`) error message, defaults to `:taken`
+
+### `foreign_key_constraint`
+
+Catches a specific foreign key constraint violation.
+
+- **key_or_keys** (`Symbol` or array of `Symbol`) key or keys used to make the foreign key constraint
+- **name** (optional `String`) constraint name in the database, to detect constraint errors. Infferred if omitted
+- **message** (optional `String` or `Symbol`) error message, defaults to `:required`
+- **error_key** (optional `Symbol`) which key will have validation errors added to
+
+### `unique_constraint`
+
+Catches a specific foreign key constraint violation.
+
+- **key_or_keys** (`Symbol` or array of `Symbol`) key or keys used to make the unique constraint
+- **name** (optional `String`) constraint name in the database, to detect constraint errors. Infferred if omitted
+- **message** (optional `String` or `Symbol`) error message, defaults to `:taken`
+- **error_key** (optional `Symbol`) which key will have validation errors added to
+
+## Limitations
+
+- `valid?` will not check for constraints. If calling `valid?` right after a `save` operation, keep in mind `errors`
+    are cleared
+- `create!` and `update!` will raise `ActiveRecord::RecordNotSaved` for constraints that are caught by `iry`, instead
+    of `ActiveModel::ValidationError`
+- Currently only PostgreSQL is supported, with the `pg` gem, but it's easy to add support for other databases.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add iry
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install iry
+
+## Development
+
+**Requirements:**
+- PostgreSQL with `psql`, `createdb`, `dropdb`
+
+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/Fire-Dragon-DoL/iry.

data/Rakefile

@@ -0,0 +1,14 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_prelude = "require \"test/test_helper\""
+  t.warning = false
+  t.test_globs = ["test/**/*_test.rb"]
+end
+
+task(default: :test)

data/Steepfile

@@ -0,0 +1,28 @@
+D = Steep::Diagnostic
+
+target(:lib) do
+  signature("sig")
+
+  # Directory name
+  check("lib")
+  # check "Gemfile"                   # File name
+  # check "app/models/**/*.rb"        # Glob
+  # ignore "lib/templates/*.rb"
+
+  # library "pathname", "set"       # Standard libraries
+  # library "strong_json"           # Gems
+
+  # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+  # configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+  # configure_code_diagnostics do |hash|             # You can setup everything yourself
+  #   hash[D::Ruby::NoMethod] = :information
+  # end
+end
+
+# target :test do
+#   signature "sig", "sig-private"
+#
+#   check "test"
+#
+#   # library "pathname", "set"       # Standard libraries
+# end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/db/schema.pgsql

@@ -0,0 +1,14 @@
+create extension if not exists "pgcrypto";
+create extension if not exists "btree_gist";
+
+create table if not exists users (
+	id uuid primary key default gen_random_uuid(),
+  unique_text text unique not null default gen_random_uuid()::text check (unique_text != 'invalid'),
+  exclude_text text not null default gen_random_uuid()::text,
+	user_id uuid references users (id),
+	friend_user_id uuid references users (id),
+	created_at timestamp(6) not null,
+	updated_at timestamp(6) not null,
+	-- acts similar to unique constraint
+	exclude using gist (exclude_text with =)
+);

data/lib/iry/callbacks.rb

@@ -0,0 +1,27 @@
+module Iry
+  # Main function to kick-off **Iry** constraint-checking mechanism
+  # If interested in adding support for other databases beside Postgres, modify this file.
+  # @private
+  module Callbacks
+    extend self
+
+    # @param model [Handlers::Model]
+    # @yield
+    # @return [void]
+    def around_save(model)
+      yield
+    rescue ActiveRecord::StatementInvalid => err
+      handler = Handlers::Null
+      case
+      when Handlers::PG.handle?(err)
+        handler = Handlers::PG
+      end
+
+      is_handled = handler.handle(err, model)
+
+      if !is_handled
+        raise
+      end
+    end
+  end
+end

data/lib/iry/constraint/check.rb

@@ -0,0 +1,39 @@
+module Iry
+  module Constraint
+    class Check
+      # Infers the check constraint name based on key and table name
+      # @param key [Symbol]
+      # @param table_name [String]
+      # @return [String]
+      def self.infer_name(key, table_name)
+        "#{table_name}_#{key}_check"
+      end
+
+      # @return [Symbol]
+      attr_accessor :key
+      # @return [Symbol, String]
+      attr_accessor :message
+      # @return [String]
+      attr_accessor :name
+
+      # @param key [Symbol] key to apply error message for check constraint to
+      # @param message [Symbol, String] the validation error message
+      # @param name [String] constraint name
+      def initialize(
+        key,
+        name:,
+        message: :invalid
+      )
+        @key = key
+        @message = message
+        @name = name
+      end
+
+      # @param model [Handlers::Model]
+      # @return [void]
+      def apply(model)
+        model.errors.add(key, message)
+      end
+    end
+  end
+end

data/lib/iry/constraint/exclusion.rb

@@ -0,0 +1,39 @@
+module Iry
+  module Constraint
+    class Exclusion
+      # Infers the exclusion constraint name based on key and table name
+      # @param key [Symbol]
+      # @param table_name [String]
+      # @return [String]
+      def self.infer_name(key, table_name)
+        "#{table_name}_#{key}_excl"
+      end
+
+      # @return [Symbol]
+      attr_accessor :key
+      # @return [Symbol, String]
+      attr_accessor :message
+      # @return [String]
+      attr_accessor :name
+
+      # @param key [Symbol] key to apply error message for exclusion constraint to
+      # @param message [Symbol, String] the validation error message
+      # @param name [String] constraint name
+      def initialize(
+        key,
+        name:,
+        message: :taken
+      )
+        @key = key
+        @message = message
+        @name = name
+      end
+
+      # @param model [Handlers::Model]
+      # @return [void]
+      def apply(model)
+        model.errors.add(key, message)
+      end
+    end
+  end
+end

data/lib/iry/constraint/foreign_key.rb

@@ -0,0 +1,44 @@
+module Iry
+  module Constraint
+    class ForeignKey
+      # Infers the unique constraint name based on keys and table name
+      # @param keys [<Symbol>]
+      # @param table_name [String]
+      # @return [String]
+      def self.infer_name(keys, table_name)
+        "#{table_name}_#{keys.join("_")}_fkey"
+      end
+
+      # @return [<Symbol>]
+      attr_accessor :keys
+      # @return [Symbol, String]
+      attr_accessor :message
+      # @return [String]
+      attr_accessor :name
+      # @return [Symbol]
+      attr_accessor :error_key
+
+      # @param keys [<Symbol>] array of keys to track the uniqueness constraint of
+      # @param message [Symbol, String] the validation error message
+      # @param name [String] constraint name
+      # @param error_key [Symbol] key to which the validation error will be applied to
+      def initialize(
+        keys,
+        name:,
+        error_key:,
+        message: :required
+      )
+        @keys = keys
+        @message = message
+        @name = name
+        @error_key = error_key
+      end
+
+      # @param model [Handlers::Model]
+      # @return [void]
+      def apply(model)
+        model.errors.add(error_key, message)
+      end
+    end
+  end
+end

data/lib/iry/constraint/unique.rb

@@ -0,0 +1,44 @@
+module Iry
+  module Constraint
+    class Unique
+      # Infers the unique constraint name based on keys and table name
+      # @param keys [<Symbol>]
+      # @param table_name [String]
+      # @return [String]
+      def self.infer_name(keys, table_name)
+        "#{table_name}_#{keys.join("_")}_key"
+      end
+
+      # @return [<Symbol>]
+      attr_accessor :keys
+      # @return [Symbol, String]
+      attr_accessor :message
+      # @return [String]
+      attr_accessor :name
+      # @return [Symbol]
+      attr_accessor :error_key
+
+      # @param keys [<Symbol>] array of keys to track the uniqueness constraint of
+      # @param message [Symbol, String] the validation error message
+      # @param name [String] constraint name
+      # @param error_key [Symbol] key to which the validation error will be applied to
+      def initialize(
+        keys,
+        name:,
+        error_key:,
+        message: :taken
+      )
+        @keys = keys
+        @message = message
+        @name = name
+        @error_key = error_key
+      end
+
+      # @param model [Handlers::Model]
+      # @return [void]
+      def apply(model)
+        model.errors.add(error_key, message)
+      end
+    end
+  end
+end

data/lib/iry/constraint.rb

@@ -0,0 +1,26 @@
+module Iry
+  # Interface representing a constraint.
+  # A constraint has a name and can apply errors to an object inheriting from {ActiveRecord::Base}
+  # @abstract
+  module Constraint
+    # Sets validation errors on the model
+    # @abstract
+    # @param model [Handlers::Model]
+    # @return [void]
+    def apply(model)
+    end
+
+    # Name of the constraint to be caught from the database
+    # @abstract
+    # @return [String]
+    def name
+    end
+
+    # Message to be attached as validation error to the model
+    # (see Handlers::Model)
+    # @abstract
+    # @return [Symbol, String]
+    def message
+    end
+  end
+end

data/lib/iry/handlers/null.rb

@@ -0,0 +1,24 @@
+module Iry
+  module Handlers
+    # Catch-all handler for unrecognized database adapters
+    # @private
+    module Null
+      extend self
+
+      # Returns always true, catching any unhandled database exception
+      # @param err [StandardError, ActiveRecord::StatementInvalid]
+      # @return [Boolean]
+      def handle?(err)
+        return true
+      end
+
+      # Return always false, failing to handle any constraint
+      # @param err [ActiveRecord::StatementInvalid]
+      # @param model [Model] should inherit {ActiveRecord::Base} and`include Iry` to match the interface
+      # @return [Boolean]
+      def handle(err, model)
+        return false
+      end
+    end
+  end
+end

data/lib/iry/handlers/pg.rb

@@ -0,0 +1,56 @@
+module Iry
+  module Handlers
+    # PostgreSQL handler through `pg` gem
+    # @private
+    module PG
+      extend self
+
+      # @return [Regexp]
+      REGEX = %r{
+        (?:
+          unique\sconstraint|
+          check\sconstraint|
+          exclusion\sconstraint|
+          foreign\skey\sconstraint
+        )
+        \s"(.+)"
+      }x
+
+      # When true, the handler is able to handle this exception, representing a constraint error in PostgreSQL.
+      # This method must ensure not to raise exception in case the postgresql adapter is missing and as such, the
+      # postgres constant is undefined
+      # @param err [ActiveRecord::StatementInvalid]
+      # @return [Boolean]
+      def handle?(err)
+        return false if !Object.const_defined?("::PG::Error")
+        return false if !err.cause.is_a?(::PG::Error)
+
+        return true if err.cause.is_a?(::PG::UniqueViolation)
+        return true if err.cause.is_a?(::PG::CheckViolation)
+        return true if err.cause.is_a?(::PG::ExclusionViolation)
+        return true if err.cause.is_a?(::PG::ForeignKeyViolation)
+
+        return false
+      end
+
+      # Appends constraint errors as model errors
+      # @param err [ActiveRecord::StatementInvalid]
+      # @param model [Model] should inherit {ActiveRecord::Base} and`include Iry` to match the interface
+      # @return [void]
+      def handle(err, model)
+        pgerr = err.cause
+        constraint_name_msg = pgerr.result.error_field(::PG::Constants::PG_DIAG_MESSAGE_PRIMARY)
+        match = REGEX.match(constraint_name_msg)
+        constraint_name = match[1]
+        constraint = model.class.constraints[constraint_name]
+        if constraint.nil?
+          return false
+        end
+
+        constraint.apply(model)
+
+        return true
+      end
+    end
+  end
+end

data/lib/iry/handlers.rb

@@ -0,0 +1,48 @@
+module Iry
+  module Handlers
+    # Interface for handlers of different database types
+    # @abstract
+    module Handler
+      # @abstract
+      # @param err [ActiveRecord::StatementInvalid] possible constraint error to handle
+      # @return [Boolean] true if this database handler is the correct one for this exception
+      def handle?(err)
+      end
+
+      # @abstract
+      # @param err [ActiveRecord::StatementInvalid] possible constraint error to handle
+      # @param model [Model]
+      # @return [Boolean] true if this database handler handled the constraint error
+      def handle(err, model)
+      end
+    end
+
+    # Interface of the model class. This class is usually inherits from {ActiveRecord::Base}
+    # @abstract
+    module ModelClass
+      # @abstract
+      # @return [String]
+      def table_name
+      end
+
+      # @abstract
+      # @return [{String => Constraint}]
+      def constraints
+      end
+    end
+
+    # Interface of the model that should be used to handle constraints.
+    # This object is an instance of {ActiveRecord::Base}
+    # @abstract
+    module Model
+      # @abstract
+      # @return [ActiveModel::Errors]
+      def errors
+      end
+
+      # @!method class
+      #   @abstract
+      #   @return [ModelClass]
+    end
+  end
+end