route_schemer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4dd45bbb9e2f0add1fece5dcd0ba7a6ecc66c245655d65e0f329527e07c05506
+  data.tar.gz: fd8fa2f8f99f2e2c7b3fb56933610fa2f73483d47b8df226c8055dbd8cd54818
+SHA512:
+  metadata.gz: 634b3f5be853503903704a688bc2e1d5bad7dcd74940aaaecb2a68a51dd02623d3b16a4d1f8ab0e43ca78c927f20a50a8122a0c965230c149e184aeda3ff2853
+  data.tar.gz: d93d85055fa6e6763788dc6d8655e33811d7f6fe2ca930f6f373a7c17e4c4b287db81131feac2ea3f43c8c9c46f8346f31801d3167ce97210da9b1fb9d68ad01

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sarvesh Kumar Dwivedi
+
+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,197 @@
+# RouteSchemer
+ 
+[![Gem Version](https://badge.fury.io/rb/route_schemer.svg)](https://badge.fury.io/rb/route_schemer) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+**RouteSchemer** is a Ruby gem designed for Rails applications to streamline schema validation of requests and responses for API endpoints. It leverages `JSONSchemer` for validation against OpenAPI-style JSON schemas. This gem makes it easy to ensure that API payloads conform to predefined structures and simplifies error handling for mismatched data.
+
+---
+
+## 🌟 Why RouteSchemer?
+
+As a developer with a background in Python's FastAPI, I noticed a gap in the Rails ecosystem for robust schema validation. FastAPI provides clear, built-in tools for validating and documenting API contracts, and I wanted to bring a similar experience to Rails. RouteSchemer fills this gap by making JSON schema validation seamless and Rails-friendly.
+
+---
+
+## 🚀 Features
+
+- Automatically validate requests and responses against JSON schemas.
+- Supports nested controllers and complex schema structures.
+- Generates schema files for controllers using a Rails-like generator.
+- Provides a simple API to access validated and filtered parameters.
+- Custom error handling for schema mismatches.
+
+---
+
+## 📦 Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add route_schemer
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install route_schemer
+```
+
+---
+
+## 🛠️ Getting Started
+
+### Step 1: Generate a Controller and a RouteSchemer
+
+Create a new controller and corresponding RouteSchemer with:
+
+```bash
+rails g controller Foo demo
+rails g route_schemer Foo demo
+```
+
+This will generate:
+
+- A `FooController` with an action `demo`
+- A schema file in `app/route_schemers/foo_route_schemer.rb`
+
+### Step 2: Define a Schema
+
+Edit the generated `FooRouteSchemer` file to define a schema:
+
+```ruby
+class FooRouteSchemer < ApplicationRouteSchemer
+    def self.demo_request_schema
+        JSONSchemer.schema({
+            type: "object",
+            properties: {
+                name: { type: "string" },
+                age: { type: "integer" }
+            },
+            required: ["name", "age"]
+        })
+    end
+
+    def self.demo_response_schema
+        JSONSchemer.schema({
+            type: "object",
+            properties: {
+                success: { type: "boolean" },
+                message: { type: "string" }
+            },
+            required: ["success"]
+        })
+    end
+end
+```
+
+### Step 3: Use in the Controller
+
+In `FooController`, use the validation helpers provided by the gem:
+Make Sure to include `RouteSchemer` in `ApplicationController`
+
+```ruby
+class FooController < ApplicationController
+
+    def demo
+        @filtered_params = validated_params # auto fetches requests schema 
+
+        # Your controller logic
+        response = validated_params(request: false, permit: false) # auto fetches response schema
+        render json: response, status: :ok
+    end
+end
+```
+
+The `validated_params` method automatically applies the request schema for the current action (`demo_request_schema` in this case).
+
+The `validated_params(request: false, permit: false)` validates response and do not permits as we do not need to permit in case of response.
+
+---
+
+## 🔧 Advanced Usage
+
+### Custom Schemas in Methods
+
+You can override the default behavior of using `validated_params` with a custom schema:
+
+```ruby
+class FooController < ApplicationController
+    def custom_action
+        schema = CustomRouteSchemer.some_other_schema
+        @filtered_params = validated_params(schema: schema)
+        render json: { success: true }
+    end
+end
+```
+
+### Error Handling
+
+RouteSchemer raises `RouteSchemer::RequestSchemerError` when validation fails. You can handle this error in your Rails application by rescuing it globally:
+
+```ruby
+class ApplicationController < ActionController::API
+    rescue_from RouteSchemer::RequestSchemerError do |e|
+        Rails.logger.debug e.details # has all errors
+        render json: { error: e.message }, status: :unprocessable_entity
+    end
+end
+```
+
+---
+
+## 🧪 Testing
+
+To test a controller action with RouteSchemer, make a request with a valid or invalid payload and ensure that:
+
+- A valid payload is processed successfully.
+- An invalid payload triggers the appropriate error response.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! To contribute:
+
+1. Fork the repository.
+2. Create a new branch for your feature/bugfix.
+3. Submit a pull request with a detailed description of your changes.
+
+If you would like to streamline and standardize commit messages, please give a try to [pygitmate](https://github.com/sarvesh4396/pygitmate) also created by me.
+---
+
+## ⭐ Star the Repository
+
+If you find this project helpful, consider starring the repository on GitHub to show your support!
+
+[![Star this repo](https://img.shields.io/github/stars/yourusername/route_schemer.svg?style=social)](https://github.com/sarvesh4396/route_schemer)
+
+---
+
+## 📜 License
+
+RouteSchemer is open-source software licensed under the [MIT License](./LICENSE).
+
+---
+
+## Code of Conduct
+
+Everyone interacting in the RouteSchemer project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/sarvesh4396/route_schemer/blob/master/CODE_OF_CONDUCT.md).
+
+---
+
+## 🙏 Acknowledgments
+
+- Thanks to the creators of `JSONSchemer` for powering the schema validation.
+- Inspired by Rails' generators and extensible architecture.
+
+## TODO
+- [ ] Parsing of date strings to objects after validating in request.
+- [ ] Add more comprehensive documentation with examples.
+- [ ] Provide detailed guides for common use cases and best practices.
+- [ ] Make controller existence optional, allowing generation even if the controller doesn't exist.
+- [ ] Explore support for `ActiveModel` to enhance schema validation using the Rails ecosystem.
+- [ ] Add support for custom error messages in schema validations.
+- [ ] Set up continuous integration and deployment pipelines.
+- [ ] Enhance test coverage and add more unit and integration tests.
+- [ ] Add auto integration to support swagger generation of present schemers.
+- [ ] Implement strict option as optional for schema validation so that schema validation passes but no errors.

data/lib/generators/route_schemer/route_schemer_generator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+# A Rails generator that creates route schema files for controllers.
+# This generator validates the existence of controllers and their methods,
+# then generates both application-wide and controller-specific route schema files.
+#
+# @example Generate schema for UserController with index and show actions
+#   rails generate route_schemer User index show
+#
+# @param controller_name [String] The name of the controller to generate schema for (e.g., 'Users' or 'Api::Users')
+# @param methods [Array<String>] List of controller methods/actions to include in the schema
+#
+# @raise [ArgumentError] If the controller doesn't exist or specified methods are not defined
+class RouteSchemerGenerator < Rails::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+
+  argument :controller_name, type: :string
+  argument :methods, type: :array, default: []
+
+  def validate_controller
+    # Ensure controller_name is properly formatted (e.g., Foo or Foo::Bar)
+    controller_path = File.join("app", "controllers", "#{controller_name.underscore}_controller.rb")
+    unless File.exist?(controller_path)
+      raise ArgumentError, "Controller #{controller_name} does not exist at #{controller_path}"
+    end
+
+    # Attempt to constantize the controller name
+    begin
+      @controller_class = "#{controller_name}Controller".constantize
+    rescue NameError
+      raise ArgumentError, "Controller class #{controller_name} could not be found. Ensure it is defined correctly."
+    end
+
+    # Validate each method in the controller class
+    methods.each do |method|
+      unless @controller_class.instance_methods.include?(method.to_sym)
+        raise ArgumentError, "Method #{method} is not defined in #{controller_name}"
+      end
+    end
+  end
+
+  def create_route_schemer_file
+    # Define the path based on the nested structure of `controller_name`
+    schemer_directory = File.join("app", "route_schemers")
+
+    # Create nested directories if they don't exist
+    FileUtils.mkdir_p(schemer_directory) unless Dir.exist?(schemer_directory)
+
+    # Generate the application route schemer file
+    application_schemer_file = File.join("app", "route_schemers", "application_route_schemer.rb")
+    unless File.exist?(application_schemer_file)
+      template "application_route_schemer_template.rb.tt",
+               application_schemer_file
+    end
+
+    # Generate the schemer file always override
+    schemer_file = File.join(schemer_directory, "#{controller_name.demodulize.underscore}_route_schemer.rb")
+    template "route_schemer_template.rb.tt", schemer_file
+  end
+end

data/lib/generators/route_schemer/templates/application_route_schemer_template.rb.tt

@@ -0,0 +1,6 @@
+class ApplicationRouteSchemer
+    # write your own custom configuration and formats for schema generation
+    # def fetch_schema_object(schema)
+    #     JSONSchemer.schema(schema)
+    # end
+end

data/lib/generators/route_schemer/templates/route_schemer_template.rb.tt

@@ -0,0 +1,22 @@
+class <%= controller_name %>RouteSchemer < ApplicationRouteSchemer
+<% methods.each do |method| %>
+  def self.<%= method %>_request_schema
+    {
+      # Example Request JSON schema for <%= method %>
+      type: "object",
+      required: [],
+      properties: {}
+    }
+  end
+
+  def self.<%= method %>_response_schema
+    {
+      # Example Response JSON schema for <%= method %>
+      type: "object",
+      required: [],
+      properties: {}
+    }
+  end
+
+<% end %>
+end

data/lib/route_schemer/errors/request_schemer_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module RouteSchemer
+  # Custom error class for schema validation failures in RouteSchemer.
+  # This error is raised when request or response parameters fail JSON schema validation.
+  class RequestSchemerError < StandardError
+    # @return [Array<Hash>] Details of the validation failures
+    attr_reader :details
+
+    # Initialize a new RequestSchemerError
+    # @param message [String] The error message
+    # @param details [Array<Hash>, nil] Detailed validation errors from JSONSchemer
+    def initialize(message, details = nil)
+      @details = details
+      super(process_error(message))
+    end
+
+    def process_error(message)
+      # TODO: format error message
+      message
+    end
+  end
+end

data/lib/route_schemer/route_schemer.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# A module for JSON schema validation in Rails controllers.
+# Provides methods for validating request and response parameters against JSON schemas.
+# This module is automatically included in Rails controllers through the RouteSchemer::Engine.
+#
+# @example Validating request parameters in a controller
+#   def create
+#     params = validated_params(schema: MyRouteSchemer.create_request_schema)
+#     # ...
+#   end
+module RouteSchemer
+  extend ActiveSupport::Concern
+
+  def validated_params(schema: nil, params: nil, request: true, permit: true)
+    # Default to dynamically determined schema and params if not provided
+    schema ||= schema_for_current_action(request)
+    raise ArgumentError, "No schema defined for validation" unless schema
+
+    params ||= self.params
+
+    data = request ? validate_request(schema, params) : validate_response(schema, params)
+    permit ? @permitted_params || permitted_params(schema, data) : data
+  end
+
+  def schema_for_current_action(request)
+    # Derive the associated RouteSchemer class (e.g., FooController -> FooRouteSchemer)
+    route_schemer_class = "#{controller_path.camelize}RouteSchemer".constantize
+    schema_method_name = request ? "#{action_name}_request_schema" : "#{action_name}_response_schema"
+    # Look up the schema method on the RouteSchemer class
+    return route_schemer_class.public_send(schema_method_name) if route_schemer_class.respond_to?(schema_method_name)
+
+    nil
+  end
+
+  # Get a JSONSchemer object for the provided schema
+  # @param schema [Hash] the JSON schema to validate against
+  # @return [JSONSchemer::Schema] the JSONSchemer object
+  def fetch_schema_object(schema)
+    JSONSchemer.schema(
+      schema,
+      before_property_validation: proc do |data, property, property_schema, _|
+        value = data[property]
+        case property_schema["type"]
+        when "integer"
+          data[property] = value.to_i if value.is_a?(String) && value.match?(/^\d+$/)
+        when "number"
+          data[property] = value.to_f if value.is_a?(String) && value.match?(/^[-+]?[0-9]*\.?[0-9]+$/)
+        end
+      end
+    )
+  end
+
+  private
+
+  # Validate the request parameters against the provided schema
+  # @param schema [Hash] the JSON schema to validate against
+  # @param data [Hash, ActionController::Parameters] the incoming request parameters
+  # @return [Hash] the validated and permitted parameters
+  def validate_request(schema, data)
+    schemer = fetch_schema_object(schema)
+    data = permitted_params(schema, data)
+    check_for_error(schemer, data)
+    @permitted_params = data
+
+    data # Return validated and permitted params
+  end
+
+  def check_for_error(schemer, data)
+    return if schemer.valid?(data)
+
+    errors = schemer.validate(data)
+    error_message = errors.first["error"]
+    raise RequestSchemerError.new(error_message, errors)
+  end
+
+  def validate_response(schema, data)
+    schemer = fetch_schema_object(schema)
+    check_for_error(schemer, data)
+    data
+  end
+
+  # Filters and permits parameters based on a given schema.
+  # @param schema [Hash] The schema defining the permitted fields.
+  # @param params [ActionController::Parameters, Hash] The parameters to be filtered.
+  # @return [Hash] The filtered parameters.
+  def permitted_params(schema, params)
+    data = {}
+    if params.is_a?(ActionController::Parameters)
+      data = params.permit(*get_permitted_fields(schema)).to_h
+    elsif params.is_a?(Hash)
+      data = params.select { |key, _| schema[:properties].key?(key.to_sym) }
+    end
+    data
+  end
+
+  # Get the permitted fields from the schema
+  # @param schema [Hash] the JSON schema to extract permitted fields from
+  # @return [Array] the list of permitted fields for rails
+  def get_permitted_fields(schema)
+    properties = schema[:properties] || {}
+    properties.map do |key, value|
+      case value[:type]
+      when "object"
+        { key.to_sym => get_permitted_fields(value) }
+      when "array"
+        value[:items][:type] == "object" ? { key.to_sym => get_permitted_fields(value[:items]) } : { key.to_sym => [] }
+      else
+        key.to_sym
+      end
+    end
+  end
+end

data/lib/route_schemer/version.rb

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

data/lib/route_schemer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "json_schemer"
+require "active_support/concern"
+require "route_schemer/route_schemer"
+require "route_schemer/errors/request_schemer_error"
+
+# A module for JSON schema validation in Rails controllers.
+# Provides methods for validating request/response parameters against JSON schemas.
+# This module is automatically included in Rails controllers through the Engine.
+module RouteSchemer
+  # Rails engine that automatically includes RouteSchemer functionality in Rails controllers.
+  # Hooks into the Rails initialization process to include the RouteSchemer module
+  # in all ActionController::Base descendants.
+  class Engine < ::Rails::Engine
+    initializer "route_schemer.include_module" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include RouteSchemer
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: route_schemer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sarvesh Kumar Dwivedi
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2025-01-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: stringio
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+description: Validate your controller routes request and response schemas.
+email:
+- heysarvesh@pm.me
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+- LICENSE
+files:
+- LICENSE
+- README.md
+- lib/generators/route_schemer/route_schemer_generator.rb
+- lib/generators/route_schemer/templates/application_route_schemer_template.rb.tt
+- lib/generators/route_schemer/templates/route_schemer_template.rb.tt
+- lib/route_schemer.rb
+- lib/route_schemer/errors/request_schemer_error.rb
+- lib/route_schemer/route_schemer.rb
+- lib/route_schemer/version.rb
+homepage: https://www.github.com/sarvesh4396/route_schemer
+licenses: []
+metadata:
+  homepage_uri: https://www.github.com/sarvesh4396/route_schemer
+  source_code_uri: https://www.github.com/sarvesh4396/route_schemer
+  changelog_uri: https://www.github.com/sarvesh4396/route_schemer/blob/master/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key: 
+specification_version: 4
+summary: Validate request and response schemas for Rails routes using RouteSchemer
+test_files: []