restme 0.0.37

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1b1c3586a14caa25fa15e0d7bcaf12547738e779d43e498c9241dbb198990cbb
+  data.tar.gz: 5ded53d0db89650ebab2580d512912a5939998347367fb7414dbdd07ace50c3e
+SHA512:
+  metadata.gz: 982f4ca537611174ec4a2ef7a768c26e33869b5491fab6ad58ea09189fe21fa9d35875f580982ccbb392ebd13c3d0fa3c8b8d4c5777e4fa4245e80b2585e8520
+  data.tar.gz: 179e7b1f1f7d6604498ac40265c9f0e187781f0432f559997959af21934ef92b46e72fdffb8cfb52ce072af91c7a36695c830a8ddf8822e9453e860fbaed7aa9

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,8 @@
+AllCops:
+  TargetRubyVersion: 3.0
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-04-26
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/Dockerfile

@@ -0,0 +1,28 @@
+FROM ruby:3.4.3
+
+RUN apt-get update -y ; apt-get upgrade -y openssl 
+RUN apt-get install -y unrar-free build-essential libpq-dev cmake vim poppler-utils postgresql-client
+
+RUN useradd -c 'restme' -m -d /home/restme -s /bin/bash restme
+
+ENV DISPLAY=:99
+ENV RUBY_GC_MALLOC_LIMIT=90000000
+ENV RUBY_GC_HEAP_FREE_SLOTS=200000
+ENV APP_HOME=/var/www/restme
+
+RUN mkdir -p $APP_HOME
+
+WORKDIR $APP_HOME
+
+ADD Gemfile* $APP_HOME/
+
+RUN chown -R $(whoami):$(whoami) $APP_HOME
+
+RUN gem install bundler \
+    && bundle install --jobs 3
+
+ADD . $APP_HOME
+
+EXPOSE 3000
+
+CMD ["./bin/rails", "server"]

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 TODO: Write your name
+
+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,350 @@
+# Restme
+
+## ⚠️ Do not use this gem yet. In progress
+
+[![Gem Version](https://badge.fury.io/rb/restme.svg)](https://badge.fury.io/rb/restme)
+
+Adds support for new **Rails** controller actions such as pagination, filtering, sorting, and selecting specific model fields. Easily implement full CRUD functionality by importing Restme into your controller.
+
+This gem manages your controller's responsibilities for:
+- Read Actions: Provide complete pagination, filtering, sorting, and field selection for records, all handled through query parameters (e.g., `http://127.0.0.1/products?name_equal=foo`).
+- Create/Update Actions: Enabling automatic creation and updating of records.
+
+## Installation
+
+
+
+```bash
+gem install restme
+```
+
+OR
+
+```bash
+gem 'restme', '~> 0.0.33'
+```
+
+## Usage
+
+#### ℹ️ Current Version of gem require the following pré configs
+
+ - If your controller defines an instance variable named `current_user`, Restme will automatically assign it to `model.current_user` during create and update actions—provided your model responds to the `current_user` method.
+ - Your user model must have a role attribute (user.role).
+ - Your controllers must be named using the plural form of the model (e.g., Product → ProductsController). Alternatively, you can manually set the model name by defining the MODEL_NAME constant (e.g., MODEL_NAME = "Shopping").
+ - You must create a folder inside app named restfy to define controller rules for authorization, scoping, creation, updating, and field selection (see example below).
+
+
+### Usage examples
+
+
+#### First of all
+
+Include the Restme module in your controller (or, optionally, in your ApplicationController if you want it available globally):
+```ruby
+include Restme::Restme
+
+before_action :initialize_restme  # This will authorize or deny the current action based on `ProductsController::Authorize::Rules` (see example below)
+```
+
+<br>
+<br>
+
+ProductsController example with restme
+```ruby
+module Api::V1::Products
+  class ProductsController < ApplicationController
+    include Restme::Restme
+
+    before_action :initialize_restme
+
+    def index
+      render json: pagination_response, status: restme_scope_status
+    end
+
+    def show
+      render json: model_scope_object, status: restme_scope_status
+    end
+
+    def create
+      render json: creatable_record, status: restme_create_status
+    end
+
+    def update
+      render json: updateable_record, status: restme_update_status
+    end
+  end
+end
+```
+- `restme_scope_status`, `restme_create_status`, and `restme_update_status` are dynamic status codes generated by Restme.
+- `model_scope_object` returns a single record or nil base on scope users.
+- `pagination_response` returns the dynamic collection response generated by Restme.
+
+<be><br>
+
+Each Restme controller works together with its corresponding rules defined inside app/restfy. Restme dynamically loads the rules for each controller.
+
+For example, ProductsController has the following rules:
+
+### app/restfy/products_controller/authorize/rules.rb
+- Used to verify if a user is authorized to access the current action based on their role.
+```ruby
+module ProductsController::Authorize
+  class Rules
+    ALLOWED_ROLES_ACTIONS = {
+      create: %i[manager],
+      index: %i[client manager],
+      show: %i[client manager],
+      update: %i[manager]
+    }.freeze
+  end
+end
+```
+
+### app/restfy/products_controller/create/rules.rb
+- Used to check if the current create action is within the user's scope. The example below checks if a manager is authorized to create a product for a specific establishment_id.
+- `CREATABLE_ACTIONS_RULES` defines which controller actions are considered POST actions.
+```ruby
+module ProductsController::Create
+  class Rules
+    CREATABLE_ACTIONS_RULES = %i[create].freeze
+
+    # The initialization of the create rules must receive the following three parameters: current_record (the record in memory), current_user, and the controller's params.
+    def initialize(temp_record, current_user, controller_params = {})
+      @temp_record = temp_record
+      @current_user = current_user
+      @controller_params = controller_params
+    end
+
+    def create_manager_scope?
+      @current_user.manager.establishments.exists?(id: @temp_record.establishment_id)
+    end
+  end
+end
+
+```
+
+
+### app/restfy/products_controller/update/rules.rb
+- Used to check if the current update action is within the user's scope. The example below checks if a manager is authorized to update a product for a specific establishment_id.
+- `UPDATABLE_ACTIONS_RULES` defines which controller actions are considered PUT actions.
+```ruby
+module ProductsController::Update
+  class Rules
+    UPDATABLE_ACTIONS_RULES = %i[update].freeze
+
+    # The initialization of the create rules must receive the following three parameters: current_record (the record in memory), current_user, and the controller's params.
+    def initialize(temp_record, current_user, controller_params = {})
+      @temp_record = temp_record
+      @current_user = current_user
+      @controller_params = controller_params
+    end
+
+    def update_manager_scope?
+      @current_user.manager.establishments.select(:id).ids.include?(@temp_record.establishment_id)
+    end
+  end
+end
+
+```
+
+
+### app/restfy/products_controller/scope/rules.rb
+This rule defines which records are part of the current user's scope (i.e., visible to them).
+```ruby
+module ProductsController::Scope
+  class Rules
+
+    # The initialization of the scope rules must receive the following three parameters: current_record (the record in memory), current_user, and the controller's params.
+    def initialize(klass, current_user, controller_params = {})
+      @klass = klass
+      @current_user = current_user
+      @controller_params = controller_params
+    end
+
+    def client_scope
+      @klass.all
+    end
+
+    def deliveryman_scope
+      @klass.all
+    end
+
+    def manager_scope
+      @klass.where(establishment_id: @current_user.manager.establishments.ids)
+    end
+  end
+end
+```
+
+
+### app/restfy/products_controller/field/rules.rb
+This rule defines which nested_fields are selectable (nested fields are model relationships).
+```ruby
+module ProductsController::Field
+  class Rules
+    NESTED_SELECTABLE_FIELDS = {
+      unit: {
+        table_name: :units
+      },
+      establishment: {
+        table_name: :establishments
+      },
+      category: {
+        table_name: :categories
+      }
+    }.freeze
+  end
+end
+```
+
+### And now how to use that?
+
+<br><br>
+
+#### Filtering
+
+To enable data filtering, specify the filterable fields in your model using the `FILTERABLE_FIELDS` constant (e.g., `FILTERABLE_FIELDS = %[name]`).
+
+You can filter data using the following query parameters:
+
+- **in**: Filters by matching any of the specified values.
+  - Example: `id_in=1,2,3`
+  
+- **equal**: Filters by exact match.
+  - Example: `name_equal=foo`
+  
+- **like**: Filters by partial match (using `LIKE` SQL operator).
+  - Example: `name_like=foo`
+  
+- **bigger_than**: Filters by records where the field is greater than the specified value.
+  - Example: `created_at_bigger_than=2025-01-01`
+  
+- **less_than**: Filters by records where the field is less than the specified value.
+  - Example: `created_at_less_than=2025-01-01`
+  
+- **bigger_than_or_equal_to**: Filters by records where the field is greater than or equal to the specified value.
+  - Example: `created_at_bigger_than_or_equal_to=2025-01-01`
+  
+- **less_than_or_equal_to**: Filters by records where the field is less than or equal to the specified value.
+  - Example: `created_at_less_than_or_equal_to=2025-01-01`
+
+Example request:
+
+```
+http://127.0.0.1/api/v1/products?name_equal=foo,establishment_id_in=1,2,3
+```
+
+<br><br>
+
+
+#### Sorting
+
+To enable data sorting, specify the sortable fields in your model using the `SORTABLE_FIELDS` constant (e.g., `SORTABLE_FIELDS = %[id]`).
+
+You can sort records using the following query parameters:
+
+Examples
+
+- **Descending (DESC)**: Sort records in descending order.
+  ```bash
+   http://localhost:3000/api/v1/products?id_sort=desc
+  ```
+
+- Ascending (ASC): Sort records in ascending order.
+  ```bash
+   http://localhost:3000/api/v1/products?id_sort=asc
+  ```
+
+<br><br>
+
+
+#### Pagination
+
+Pagination functionality is available for any `index` endpoint that uses the `pagination_response` variable in the controller.
+
+There are two query parameters available to control pagination:
+- `per_page`: Defines the number of items per page.
+- `page`: Sets the current page number.
+
+ℹ️ **Note:** The maximum number of items per page is currently limited to 100.
+
+Example usage:
+
+```bash
+http://localhost:3000/api/v1/products?per_page=12&page=1
+```
+
+<br><br>
+
+
+#### Field Selection (`fields_select`)
+
+You can select specific fields from your model, such as `id`, `name`, or `created_at`.  
+The resulting query will retrieve **only** the selected fields directly from the database, improving performance.
+
+Example:
+
+```bash
+http://localhost:3000/api/v1/products?fields_select=id,name
+```
+
+<br><br>
+
+
+#### Nested Field Selection (`nested_fields_select`)
+
+You can also select specific relationships of your records, such as `product.client` or `product.establishment`.  
+The resulting query will automatically include the related data, optimizing the response for your needs.
+
+ℹ️ **Note:**  
+If you select a nested field, you must also ensure that the related foreign key (e.g., `establishment_id`, `client_id`) is included via `fields_select`.  
+If the `fields_select` parameter is not provided, Restme will automatically handle the necessary field selections.
+
+Example:
+
+```bash
+http://localhost:3000/api/v1/products?nested_fields_select=client
+```
+
+```json
+{
+  "products": [
+    {
+      "id": 1,
+      "name": "foo",
+      "client": {
+        "id": 5,
+        "name": "bar"
+      }
+    }
+  ]
+}
+```
+
+<br><br>
+
+
+#### Attachment Field Selection (`attachment_fields_select`)
+
+If your model uses Active Storage and has attachments, you can retrieve the URL of an attached file by using the `attachment_fields_select` parameter.  
+When specified, Restme will include the URL of the attachment in the response.
+
+ℹ️ **Note:**  
+If the specified attachment field does not exist in the model, Restme will return an HTTP 422 Unprocessable Entity error.
+
+Example:
+
+```bash
+http://localhost:3000/api/v1/products?attachment_fields_select=image
+```
+
+<br><br>
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Restme project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/restme/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docker-compose.yml

@@ -0,0 +1,13 @@
+services:
+  restme_app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: restme
+    command: /bin/bash
+    tty: true
+    volumes:
+      - .:/var/www/restme
+    mem_limit: 1024mb
+volumes:
+  app:

data/lib/restme/authorize/rules.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../shared/user_role"
+require_relative "../shared/current_model"
+
+module Restme
+  module Authorize
+    # Defines the rules used to authotize user
+    module Rules
+      include ::Restme::Shared::CurrentModel
+      include ::Restme::Shared::UserRole
+
+      def user_authorize
+        return true unless restme_current_user
+        return if super_authorize? || allowed_roles_actions[action_name.to_sym]&.include?(user_role.to_sym)
+
+        render json: { message: "Action not allowed" }, status: :forbidden
+      end
+
+      def allowed_roles_actions
+        return {} unless authorize_rules_class.const_defined?(:ALLOWED_ROLES_ACTIONS)
+
+        authorize_rules_class::ALLOWED_ROLES_ACTIONS
+      end
+
+      def super_authorize?
+        restme_current_user&.super_admin?
+      end
+
+      def authorize_rules_class
+        "#{controller_class.to_s.split("::").last}::Authorize::Rules".constantize
+      end
+    end
+  end
+end