tarquinn 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40a2cd722ae376e627aba7f4d4e10b69df45b74593d89dbafd68b9f6e4cb635a
-  data.tar.gz: 7c29d8a9763a3f0ae3e71945ea16b690628b0a3fef4f3603d891dbe791a4a0ca
+  metadata.gz: 472e75e26a2d619f0284c9eb797c5e47f717a9f9a6e52757fc1c5ad7272a174f
+  data.tar.gz: efb31ef0021491a3b99c48cb8c3a34026493a10500636449195c1070d281dc91
 SHA512:
-  metadata.gz: 5b63bfd5ba62e690b145bc4394e1913f28e5756b325b8301fb1b467d1386b282950095d36638ee407c2404e30d098a79de7868285a390b643fb2e84b275f16c6
-  data.tar.gz: '0286cd856bbaa74643cf9174952aff220ed75e3b81ff22f07c451b95bf226a78919ac8e306bbde78b9ab2f0577cd7b707bf4b0f4d25da69830b5340d58bfc5d9'
+  metadata.gz: 9391c038495ea739fee48b43a9c104bcb0dfb887aa87ecb75be3d1378ee2c11649cc68725fd8beea215036065b5deb1aeca08babea956d77b42628b887ead261
+  data.tar.gz: 59ccde1cade0e2b76b82f89073409cf9ced274d7346214ae08f2d4e6f06e11269feb9b768c219064bcec0e748205c1ce6a5eb45515e21dbe404a53459cb6643b

data/.circleci/config.yml

@@ -18,7 +18,7 @@ workflows:
               only: /\d+\.\d+\.\d+/
             branches:
               only:
-                - master
+                - main
 jobs:
   test:
     docker:
@@ -27,18 +27,12 @@ jobs:
           PROJECT: tarquinn
     steps:
       - checkout
-      - run:
-          name: Prepare Coverage Test Report
-          command: cc-test-reporter before-build
       - run:
           name: Bundle Install
           command: bundle install
       - run:
           name: RSpec
           command: bundle exec rspec
-      - run:
-          name: Coverage Test Report
-          command: cc-test-reporter after-build --exit-code $?
   checks:
     docker:
       - image: darthjee/circleci_ruby_331:1.0.1

data/.github/copilot-instructions.md

@@ -0,0 +1,188 @@
+# GitHub Copilot Instructions for Tarquinn
+
+## Project Overview
+
+Tarquinn is a Ruby gem that provides generic redirection control for Rails controllers.
+It is implemented as an `ActiveSupport::Concern` that adds `before_action` hooks and
+class-level DSL methods (`redirection_rule`, `skip_redirection`, `skip_redirection_rule`)
+to any Rails controller.
+
+Key components:
+
+- **`Tarquinn`** – The main concern included in controllers; sets up `before_action :perform_redirection`.
+- **`Tarquinn::ClassMethods`** – DSL methods added to controller classes.
+- **`Tarquinn::RequestHandlerBuilder`** – Accumulates redirection configurations for a controller class.
+- **`Tarquinn::RequestHandler`** – Processes a single request, iterating over configs to find the first matching redirect.
+- **`Tarquinn::RedirectionHandler`** – Evaluates one redirection config (conditions + skip rules) for a request.
+- **`Tarquinn::RedirectionConfig`** – Holds the data for a single redirection rule (blocks, skip blocks, redirect target).
+- **`Tarquinn::Condition`** – Wraps a single condition (method name or block) used in redirection/skip evaluation.
+- **`Tarquinn::Controller`** – Thin wrapper around the Rails controller instance, used by handlers.
+
+## Redirection Rules Data Flow
+
+### How It Works
+
+1. A controller includes `Tarquinn` (an `ActiveSupport::Concern`), which:
+   - Extends the controller with `Tarquinn::ClassMethods`, making the DSL methods available.
+   - Registers a `before_action :perform_redirection` that runs on every request.
+
+2. During a request, `perform_redirection` delegates to `Tarquinn::RequestHandler`, which
+   iterates over all registered `Tarquinn::RedirectionConfig` objects (in definition order)
+   and applies the **first** rule whose conditions are satisfied.
+
+3. Each rule is evaluated by `Tarquinn::RedirectionHandler`:
+   - All condition methods and/or the optional block are evaluated against the current
+     controller instance.
+   - If **any** condition returns a truthy value the rule fires and the controller redirects
+     to the path returned by the rule's target method.
+   - Skip conditions (registered via `skip_redirection` or `skip_redirection_rule`) are
+     checked first; if any skip condition is truthy the rule is bypassed entirely.
+
+### Defining a Redirection Rule — `redirection_rule`
+
+```ruby
+redirection_rule <rule_name>, *<condition_methods>, &<block>
+```
+
+| Argument            | Description                                                                                  |
+|---------------------|----------------------------------------------------------------------------------------------|
+| `rule_name`         | Symbol. Also the name of the controller method that returns the redirect path.               |
+| `condition_methods` | Zero or more symbol method names. Each is called on the controller; truthy → rule fires.     |
+| `block`             | Optional. Evaluated in the context of the controller; truthy → rule fires.                   |
+
+**Evaluation**: the rule fires when **any** condition method **or** the block returns truthy.
+
+#### Example 1 — block-based rule
+
+```ruby
+redirection_rule :redirect_home { params[:secret_key] != '12345' }
+
+def redirect_home
+  home_path
+end
+```
+
+Redirects to `home_path` if `secret_key` is absent or different from `'12345'`.
+
+#### Example 2 — method-based rule
+
+```ruby
+redirection_rule :redirect_home, :misses_secret_key
+
+def redirect_home
+  home_path
+end
+
+def misses_secret_key
+  params[:secret_key] != '12345'
+end
+```
+
+Same behaviour as Example 1, but the condition is extracted into a dedicated method.
+
+### Skipping a Rule for Specific Actions — `skip_redirection`
+
+```ruby
+skip_redirection <rule_name>, *<actions>
+```
+
+Prevents the named rule from running for the listed controller actions.
+
+```ruby
+skip_redirection :redirect_home, :index
+```
+
+The `index` action is not affected by the `redirect_home` rule; all other actions still are.
+
+### Skipping a Rule Under a Condition — `skip_redirection_rule`
+
+```ruby
+skip_redirection_rule <rule_name>, *<condition_methods>, &<block>
+```
+
+Registers a skip condition for a rule. When the condition is truthy the rule is bypassed,
+regardless of the action.
+
+```ruby
+skip_redirection_rule :redirect_home { params[:admin_key] == '9999' }
+```
+
+The `redirect_home` rule does not fire when the correct admin key is provided.
+
+### Passing Options to Redirection Rules
+
+You can pass options to `redirection_rule` to control advanced behavior. Currently, the main supported option is `domain`, which enables cross-domain redirection.
+
+| Option   | Description                                                                                 |
+|----------|---------------------------------------------------------------------------------------------|
+| `domain` | String. If set, allows redirection to the specified domain (cross-domain). If not set, only same-host redirection is allowed. |
+
+#### Example — domain-based rule
+
+```ruby
+redirection_rule :redirect_external, domain: 'example.com' do
+  params[:should_redirect]
+end
+
+def redirect_external
+  '/external_path'
+end
+```
+
+This will only allow redirection to `https://example.com/external_path` because the domain option is set to `'example.com'`.
+
+## Language
+
+All code, comments, documentation, commit messages, and PR descriptions must be written in **English**.
+
+## Coding Standards
+
+### General Style
+
+- Follow the existing RuboCop configuration (`.rubocop.yml` / `.rubocop_todo.yml`).
+- Use `# frozen_string_literal: true` at the top of every Ruby file.
+- Keep methods small and focused (Sandi Metz style): aim for methods under 5 lines.
+- Keep classes small with clear, single responsibilities and explicit object boundaries.
+- Avoid deeply nested conditionals; extract guard clauses or helper methods.
+- Use `private` / `attr_reader` to hide implementation details.
+- Use `delegate` (ActiveSupport) instead of manual forwarding where it improves readability.
+
+### Documentation
+
+- Add **YARD** documentation to all public classes, modules, and methods.
+- Non-obvious private methods should also have short YARD comments.
+- Always include `@param`, `@return`, and `@api public` / `@api private` tags where applicable.
+- Ensure documentation coverage stays at or above the threshold in `config/yardstick.yml`.
+
+### Tests
+
+- Write **RSpec** tests using the patterns established in `spec/`.
+- Keep tests small and focused — one behaviour per example.
+- Use `let` definitions that are **reusable** and **avoid duplication** across contexts.
+- Prefer `context` blocks to describe different input/state scenarios.
+- Avoid `before` blocks that do more than one thing; split them if needed.
+- Use `shared_examples` or `shared_context` when the same setup appears in multiple groups.
+
+## CI Checks
+
+The CI pipeline (`.circleci/config.yml`) runs the following checks on every push.
+Reproduce them locally before opening a PR:
+
+| CI Step                        | Local Command                                    |
+|-------------------------------|--------------------------------------------------|
+| Run tests                     | `bundle exec rspec`                              |
+| RuboCop lint                  | `bundle exec rubocop`                            |
+| YARD documentation coverage   | `bundle exec rake verify_measurements`           |
+| RubyCritic quality check      | `rubycritic.sh` (or `bundle exec rubycritic`)    |
+
+All checks must pass before a PR can be merged.
+
+## Docker / Local Development
+
+To run the project locally, use the Makefile targets:
+
+- Build Docker image:  `make build`
+- Start development environment:  `make dev`
+- Run tests:  `make tests`
+
+See the [Developer Guide](../README.md#developer-guide) in the README for further instructions.

data/Dockerfile

@@ -1,4 +1,4 @@
-FROM darthjee/scripts:0.4.2 as scripts
+FROM darthjee/scripts:0.6.0 as scripts
 
 FROM darthjee/ruby_331:1.0.1 as base
 

data/Gemfile

@@ -5,14 +5,14 @@ source 'https://rubygems.org'
 gem 'bundler',     '~> 2.5.13'
 gem 'pry',         '~> 0.14.2'
 gem 'pry-nav',     '~> 1.0.0'
-gem 'rails',       '7.0.4.3'
+gem 'rails',       '7.2.3'
 gem 'rake',        '~> 13.1.0'
 gem 'rspec',       '~> 3.12.0'
-gem 'rspec-rails', '6.0.2'
-gem 'rubycritic', '4.9.1'
-gem 'simplecov', '~> 0.22.0'
-gem 'sqlite3', '1.4.2'
-gem 'yard', '0.9.36'
-gem 'yardstick', '0.9.9'
+gem 'rspec-rails', '6.1.1'
+gem 'rubycritic',  '4.9.1'
+gem 'simplecov',   '~> 0.22.0'
+gem 'sqlite3',     '1.4.2'
+gem 'yard',        '0.9.38'
+gem 'yardstick',   '0.9.9'
 
 gemspec

data/Makefile

@@ -0,0 +1,21 @@
+.PHONY: build dev tests
+
+PROJECT?=tarquinn
+IMAGE?=$(PROJECT)
+BASE_IMAGE?=$(DOCKER_ID_USER)/$(PROJECT)-base
+DOCKER_FILE_BASE=Dockerfile.$(PROJECT)-base
+
+all:
+	@echo "Usage:"
+	@echo "  make build\n    Build docker image for $(PROJECT)"
+	@echo "  make dev\n    Run development environment for $(PROJECT)"
+	@echo "  make tests\n    Run tests for $(PROJECT)"
+
+build:
+	docker build -f Dockerfile.$(PROJECT) . -t $(IMAGE) -t $(PUSH_IMAGE):latest
+
+tests:
+	docker-compose run $(PROJECT)_tests /bin/bash
+
+dev:
+	docker-compose run $(PROJECT) /bin/bash

data/README.md

@@ -2,8 +2,6 @@ Tarquinn
 ========
 [![Build Status](https://circleci.com/gh/darthjee/tarquinn.svg?style=shield)](https://circleci.com/gh/darthjee/tarquinn)
 [![Code Climate](https://codeclimate.com/github/darthjee/tarquinn/badges/gpa.svg)](https://codeclimate.com/github/darthjee/tarquinn)
-[![Test Coverage](https://codeclimate.com/github/darthjee/tarquinn/badges/coverage.svg)](https://codeclimate.com/github/darthjee/tarquinn/coverage)
-[![Issue Count](https://codeclimate.com/github/darthjee/tarquinn/badges/issue_count.svg)](https://codeclimate.com/github/darthjee/tarquinn)
 [![Gem Version](https://badge.fury.io/rb/tarquinn.svg)](https://badge.fury.io/rb/tarquinn)
 [![Inline docs](http://inch-ci.org/github/darthjee/tarquinn.svg)](http://inch-ci.org/github/darthjee/tarquinn)
 
@@ -11,13 +9,13 @@ Tarquinn
 
 Yard Documentation
 -------------------
-[https://www.rubydoc.info/gems/tarquinn/0.3.0](https://www.rubydoc.info/gems/tarquinn/0.3.0)
+[https://www.rubydoc.info/gems/tarquinn/0.4.0](https://www.rubydoc.info/gems/tarquinn/0.4.0)
 
 This gem makes easier to controll generic redirection
 
-Current Release: [0.3.0](https://github.com/darthjee/tarquinn/tree/0.3.0)
+Current Release: [0.4.0](https://github.com/darthjee/tarquinn/tree/0.4.0)
 
-[Next release](https://github.com/darthjee/tarquinn/compare/0.3.0...master)
+Next Version [0.4.1](https://github.com/darthjee/tarquinn/compare/0.4.0...main)
 
 Getting started
 ---------------
@@ -60,3 +58,108 @@ Getting started
       end
     end
   ```
+
+---
+
+## Developer Guide
+
+### How It Works
+
+Tarquinn is a Rails concern that adds a `before_action` to any controller it is included in.
+On each request the action chain works as follows:
+
+1. `before_action :perform_redirection` is triggered automatically.
+2. A `RequestHandlerBuilder` (stored per controller class) holds all registered redirection
+   configs (`redirection_rule` / `skip_redirection` / `skip_redirection_rule` calls).
+3. At request time, `RequestHandlerBuilder` creates a `RequestHandler` for the current request.
+4. `RequestHandler` iterates over every `RedirectionConfig` and checks whether a redirect
+   should fire via `RedirectionHandler`.
+5. `RedirectionHandler` evaluates skip conditions first; if none match, it evaluates redirect
+   conditions. The first config that requires a redirect triggers `redirect_to`.
+
+### Running Locally with Docker Compose
+
+> Prerequisites: Docker and Docker Compose installed.
+
+**Build the image**
+
+```bash
+docker compose build base_build
+# or
+### Running Locally with Docker Compose and Makefile
+
+| `make build`    | Build the Docker image                               |
+
+| `make dev`      | Open an interactive bash shell inside the container  |
+
+| `make test`     | Run RSpec tests inside the container                 |
+make build
+```
+
+**Run the test suite**
+
+```bash
+make tests
+```
+
+**Open an interactive shell inside the container**
+
+```bash
+make dev
+```
+
+### Makefile Targets
+
+| Target        | Description                                 |
+|--------------|---------------------------------------------|
+| `make build` | Build Docker image for the project          |
+| `make dev`   | Run development environment (bash shell)    |
+| `make tests` | Run tests (RSpec) in the container          |
+
+### CI Checks
+
+The CircleCI pipeline (`.circleci/config.yml`) runs three jobs:
+
+| Job                   | What it does                                                                             |
+|-----------------------|------------------------------------------------------------------------------------------|
+| `test`                | `bundle exec rspec` + uploads coverage report                                            |
+| `checks`              | RuboCop, Yardstick coverage, README version check, RubyCritic, unit-test structure check |
+| `build-and-release`   | Builds and pushes the gem (tags only, on `master`)                                       |
+
+Run the same checks locally before opening a PR:
+
+```bash
+# Tests
+bundle exec rspec
+
+# RuboCop
+bundle exec rubocop
+
+# YARD documentation coverage
+bundle exec rake verify_measurements
+```
+
+### Domain Option for Cross-Domain Redirection
+
+You can specify a `domain` option in your `redirection_rule` to allow cross-domain redirection. When set, the redirection will be allowed to external hosts and the specified domain will be used for validation.
+
+**Example:**
+
+```ruby
+class ExternalRedirectController < ApplicationController
+  include Tarquinn
+
+  redirection_rule :redirect_external, domain: 'example.com' do
+    params[:should_redirect]
+  end
+
+  private
+
+  def redirect_external
+    '/external_path'
+  end
+end
+```
+
+- If `domain` is not set, redirection is only allowed for the same host.
+- If `domain` is set, redirection to the specified domain is allowed.

data/config/check_specs.yml

@@ -1,3 +1,4 @@
 ignore:
   - lib/tarquinn/class_methods.rb
   - lib/tarquinn/version.rb
+  - lib/tarquinn/exception.rb

data/config/yardstick.yml

@@ -1,4 +1,4 @@
-threshold: 88.1
+threshold: 100.0
 require_exact_threshold: false
 rules:
   ApiTag::Presence:
@@ -15,13 +15,35 @@ rules:
     exclude: []
   ExampleTag:
     enabled: true
-    exclude: []
+    exclude:
+      - Tarquinn.redirection_rule
+      - Tarquinn.skip_redirection
+      - Tarquinn.skip_redirection_rule
   ReturnTag:
     enabled: true
-    exclude: []
+    exclude:
+      - Tarquinn.redirection_rule
+      - Tarquinn.skip_redirection
+      - Tarquinn.skip_redirection_rule
+      - Tarquinn.redirector_builder
+      - Tarquinn#perform_redirection
+      - Tarquinn::RedirectionHandler#initialize
+      - Tarquinn::RequestHandler#initialize
+      - Tarquinn::RedirectionConfigBuilder#initialize
+      - Tarquinn::Condition::ProcRunner#initialize
+      - Tarquinn::Condition::MethodCaller#initialize
+      - Tarquinn::Condition::ActionChecker#initialize
+      - Tarquinn::Exception::RedirectionAlreadyDefined#initialize
   Summary::Presence:
     enabled: true
-    exclude: []
+    exclude:
+      - Tarquinn::RedirectionHandler#initialize
+      - Tarquinn::RequestHandler#initialize
+      - Tarquinn::RedirectionConfigBuilder#initialize
+      - Tarquinn::Condition::ProcRunner#initialize
+      - Tarquinn::Condition::MethodCaller#initialize
+      - Tarquinn::Condition::ActionChecker#initialize
+      - Tarquinn::Exception::RedirectionAlreadyDefined#initialize
   Summary::Length:
     enabled: true
     exclude: []

data/docker-compose.yml

@@ -17,7 +17,7 @@ services:
     depends_on: [base_build]
     command: /bin/bash -c 'rspec'
 
-  test_all:
+  tarquinn_tests:
     <<: *base
     depends_on: [base_build]
     command: /bin/bash -c 'rspec && yard && rake yardstick_measure && rake verify_measurements'

data/lib/tarquinn/class_methods.rb

@@ -3,16 +3,64 @@
 module Tarquinn
   # @api public
   #
-  # Methods added by Tarquinn
+  # Methods added by {Tarquinn}
   module ClassMethods
     # Creates a redirection rule
     #
     # The rule name defines which method will be called when checking the path of redirection
     #
     # @param (see Tarquinn::RequestHandlerBuilder#add_redirection_config)
+    # @option (see Tarquinn::RequestHandlerBuilder#add_redirection_config)
     # @return (see Tarquinn::RequestHandlerBuilder#add_redirection_config)
-    def redirection_rule(redirection, *methods, &)
-      redirector_builder.add_redirection_config(redirection, *methods, &)
+    #
+    # @see Tarquinn::RequestHandlerBuilder
+    # @see Tarquinn::RedirectionConfig::Options
+    #
+    # @example A redirection with block style condition
+    #   class ApplicationController < ActionController::Base
+    #     include Tarquinn
+    #
+    #     redirection_rule :redirect_old_path do |redirection|
+    #       redirection.path == '/old_path'
+    #     end
+    #
+    #     private
+    #
+    #     def redirect_old_path
+    #       '/new_path'
+    #     end
+    #   end
+    #
+    # @example A redirection with method style condition
+    #   class ApplicationController < ActionController::Base
+    #     include Tarquinn
+    #
+    #     redirection_rule :redirect_old_path, :perform_redirection_for_old_path?
+    #
+    #     private
+    #
+    #     def perform_redirection_for_old_path?
+    #       request.path == '/old_path'
+    #     end
+    #
+    #     def redirect_old_path
+    #       '/new_path'
+    #     end
+    #   end
+    #
+    # @example A redirection with domain options
+    #   class ApplicationController < ActionController::Base
+    #     include Tarquinn
+    #     redirection_rule :redirect_external_path, domain: 'example.com' do |redirection|
+    #       redirection.path == '/new_path'
+    #     end
+    #     private
+    #     def redirect_external_path
+    #       '/new_path'
+    #     end
+    #   end
+    def redirection_rule(redirection, *methods, **options, &block)
+      redirector_builder.add_redirection_config(redirection, *methods, **options, &block)
     end
 
     # Attaches a condition to skip a redirection based on route (controller action)
@@ -21,23 +69,64 @@ module Tarquinn
     #
     # @param (see Tarquinn::RequestHandlerBuilder#add_skip_action)
     # @return (see Tarquinn::RequestHandlerBuilder#add_skip_action)
+    #
+    # @example Skip a redirection for a specific group of controller actions
+    #   class ApplicationController < ActionController::Base
+    #     include Tarquinn
+    #     redirection_rule :redirect_old_path
+    #     skip_redirection :redirect_old_path, :new, :create, :update
+    #   end
     def skip_redirection(redirection, *actions)
       redirector_builder.add_skip_action(redirection, *actions)
     end
 
     # Attaches conditions to skip a redirection
     #
-    # Methods and blocks are ran and if any returns true, the redirec is skipped
+    # Methods and blocks are ran and if any returns true, the redirect is skipped
     #
     # @param (see Tarquinn::RequestHandlerBuilder#add_skip_config)
     # @return (see Tarquinn::RequestHandlerBuilder#add_skip_config)
+    #
+    # @example A redirection with method style condition
+    #   class ApplicationController < ActionController::Base
+    #     include Tarquinn
+    #
+    #     redirection_rule :redirect_old_path
+    #     skip_redirection_rule :redirect_old_path, :skip_redirection_for_old_path?
+    #
+    #     private
+    #
+    #     def skip_redirection_for_old_path?
+    #       request.path != '/old_path'
+    #     end
+    #
+    #     def redirect_old_path
+    #       '/new_path'
+    #     end
+    #   end
+    #
+    # @example A redirection with block style condition
+    #   class ApplicationController < ActionController::Base
+    #     include Tarquinn
+    #
+    #     redirection_rule :redirect_old_path do |redirection|
+    #       redirection.path == '/old_path'
+    #     end
+    #
+    #     private
+    #
+    #     def redirect_old_path
+    #       '/new_path'
+    #     end
+    #   end
     def skip_redirection_rule(redirection, *methods, &block)
-      redirector_builder.add_skip_config(redirection, *methods, block)
+      redirector_builder.add_skip_config(redirection, *methods, &block)
     end
 
-    # Retruns the RequestHandlerBuilder
+    # @api private
+    # Returns the RequestHandlerBuilder
     #
-    # RequestHandlerBuilder will Carry all the configurations and will create
+    # RequestHandlerBuilder will carry all the configurations and will create
     # one {RequestHandler} for each request
     #
     # @return [RequestHandlerBuilder]

data/lib/tarquinn/condition/action_checker.rb

@@ -6,14 +6,29 @@ module Tarquinn
     #
     # Checks condition based on route action
     class ActionChecker < Tarquinn::Condition
+      # @param routes [Array<Symbol>] controller actions that trigger the condition
+      #
+      # @return [Tarquinn::Condition::ActionChecker]
       def initialize(routes)
         @routes = [routes].flatten.map(&:to_s)
       end
 
+      # Checks if the current request action matches any of the configured routes
+      #
+      # @param controller [Tarquinn::Controller] the controller with the request params
+      #
+      # @return [TrueClass] when the current action is in the routes list
+      # @return [FalseClass] when the current action is not in the routes list
       def check?(controller)
         routes.include? controller.params[:action]
       end
 
+      # Checks equality with another object
+      #
+      # @param other [Object] the object to compare with
+      #
+      # @return [TrueClass] when the other object is of the same class and has the same routes
+      # @return [FalseClass] otherwise
       def ==(other)
         return false unless other.class == self.class
 
@@ -22,6 +37,12 @@ module Tarquinn
 
       protected
 
+      # @api private
+      # @private
+      #
+      # Controller actions that trigger the condition
+      #
+      # @return [Array<String>]
       attr_reader :routes
     end
   end