securial 1.0.2 → 1.0.3

data/lib/securial/middleware/transform_request_keys.rb

@@ -1,35 +1,158 @@
+# @title Securial Transform Request Keys Middleware
+#
+# Rack middleware for transforming JSON request body keys to Ruby conventions.
+#
+# This middleware automatically converts incoming JSON request body keys from
+# camelCase or PascalCase to snake_case, allowing Rails applications to receive
+# JavaScript-style APIs while maintaining Ruby naming conventions internally.
+# It only processes JSON requests and gracefully handles malformed JSON.
+#
+# @example Adding middleware to Rails application
+#   # config/application.rb
+#   config.middleware.use Securial::Middleware::TransformRequestKeys
+#
+# @example Request transformation
+#   # Incoming JSON request body:
+#   { "userName": "john", "emailAddress": "john@example.com" }
+#
+#   # Transformed for Rails application:
+#   { "user_name": "john", "email_address": "john@example.com" }
+#
+require "json"
+require "stringio"
+
 module Securial
   module Middleware
-    # This middleware transforms request keys to a specified format.
-    # It uses the KeyTransformer helper to apply the transformation.
+    # Rack middleware that transforms JSON request body keys to snake_case.
+    #
+    # This middleware enables Rails applications to accept camelCase JSON
+    # from frontend applications while automatically converting keys to
+    # Ruby's snake_case convention before they reach the application.
     #
-    # It reads the request body if the content type is JSON and transforms
-    # the keys to underscore format. If the body is not valid JSON, it does nothing.
     class TransformRequestKeys
+      # Initializes the middleware with the Rack application.
+      #
+      # @param [#call] app The Rack application to wrap
+      #
+      # @example
+      #   middleware = TransformRequestKeys.new(app)
+      #
       def initialize(app)
         @app = app
       end
 
+      # Processes the request and transforms JSON body keys if applicable.
+      #
+      # Intercepts JSON requests, parses the body, transforms all keys to
+      # snake_case using the KeyTransformer helper, and replaces the request
+      # body with the transformed JSON. Non-JSON requests pass through unchanged.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [Array] The Rack response array [status, headers, body]
+      #
+      # @example JSON transformation
+      #   # Original request body: { "firstName": "John", "lastName": "Doe" }
+      #   # Transformed body: { "first_name": "John", "last_name": "Doe" }
+      #
+      # @example Non-JSON requests
+      #   # Form data, XML, and other content types pass through unchanged
+      #
+      # @example Malformed JSON handling
+      #   # Invalid JSON is left unchanged and passed to the application
+      #   # The application can handle the JSON parsing error appropriately
+      #
       def call(env)
-        if env["CONTENT_TYPE"]&.include?("application/json")
-          req = Rack::Request.new(env)
-          if (req.body&.size || 0) > 0
-            raw = req.body.read
-            req.body.rewind
-            begin
-              parsed = JSON.parse(raw)
-              transformed = Securial::Helpers::KeyTransformer.deep_transform_keys(parsed) do |key|
-                Securial::Helpers::KeyTransformer.underscore(key)
-              end
-              env["rack.input"] = StringIO.new(JSON.dump(transformed))
-              env["rack.input"].rewind
-            rescue JSON::ParserError
-              # no-op
-            end
-          end
+        if json_request?(env)
+          transform_json_body(env)
         end
+
         @app.call(env)
       end
+
+      private
+
+      # Checks if the request contains JSON content.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [Boolean] true if the request has JSON content type
+      # @api private
+      #
+      def json_request?(env)
+        env["CONTENT_TYPE"]&.include?("application/json")
+      end
+
+      # Transforms JSON request body keys to snake_case.
+      #
+      # Reads the request body, parses it as JSON, transforms all keys
+      # to snake_case, and replaces the original body with the transformed
+      # JSON. Gracefully handles empty bodies and malformed JSON.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [void]
+      # @api private
+      #
+      def transform_json_body(env)
+        req = Rack::Request.new(env)
+
+        return unless request_has_body?(req)
+
+        raw_body = read_request_body(req)
+
+        begin
+          parsed_json = JSON.parse(raw_body)
+          transformed_json = transform_keys_to_snake_case(parsed_json)
+          replace_request_body(env, transformed_json)
+        rescue JSON::ParserError
+          # Malformed JSON - leave unchanged for application to handle
+        end
+      end
+
+      # Checks if the request has a body to process.
+      #
+      # @param [Rack::Request] req The Rack request object
+      # @return [Boolean] true if the request has a non-empty body
+      # @api private
+      #
+      def request_has_body?(req)
+        (req.body&.size || 0) > 0
+      end
+
+      # Reads and rewinds the request body.
+      #
+      # @param [Rack::Request] req The Rack request object
+      # @return [String] The raw request body content
+      # @api private
+      #
+      def read_request_body(req)
+        raw = req.body.read
+        req.body.rewind
+        raw
+      end
+
+      # Transforms all keys in the JSON structure to snake_case.
+      #
+      # @param [Object] json_data The parsed JSON data structure
+      # @return [Object] The data structure with transformed keys
+      # @api private
+      #
+      def transform_keys_to_snake_case(json_data)
+        Securial::Helpers::KeyTransformer.deep_transform_keys(json_data) do |key|
+          Securial::Helpers::KeyTransformer.underscore(key)
+        end
+      end
+
+      # Replaces the request body with transformed JSON.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @param [Object] transformed_data The transformed JSON data
+      # @return [void]
+      # @api private
+      #
+      def replace_request_body(env, transformed_data)
+        new_body = JSON.dump(transformed_data)
+        env["rack.input"] = StringIO.new(new_body)
+        env["rack.input"].rewind
+      end
     end
   end
 end

data/lib/securial/middleware/transform_response_keys.rb

@@ -1,15 +1,76 @@
+# @title Securial Transform Response Keys Middleware
+#
+# Rack middleware for transforming JSON response keys to client-preferred formats.
+#
+# This middleware automatically converts outgoing JSON response keys from Ruby's
+# snake_case convention to the configured format (camelCase, PascalCase, etc.) to
+# match client application expectations. It only processes JSON responses and
+# preserves the original response structure and content.
+#
+# @example Adding middleware to Rails application
+#   # config/application.rb
+#   config.middleware.use Securial::Middleware::TransformResponseKeys
+#
+# @example Response transformation with lowerCamelCase
+#   # Original Rails response:
+#   { "user_name": "john", "email_address": "john@example.com" }
+#
+#   # Transformed for client:
+#   { "userName": "john", "emailAddress": "john@example.com" }
+#
+# @example Response transformation with UpperCamelCase
+#   # Configuration: config.response_keys_format = :UpperCamelCase
+#   # Original: { "user_profile": { "first_name": "John" } }
+#   # Transformed: { "UserProfile": { "FirstName": "John" } }
+#
+require "json"
+
 module Securial
   module Middleware
-    # This middleware transforms response keys to a specified format.
-    # It uses the KeyTransformer helper to apply the transformation.
+    # Rack middleware that transforms JSON response keys to configured format.
+    #
+    # This middleware enables Rails applications to output responses in
+    # the naming convention expected by client applications (JavaScript,
+    # mobile apps, etc.) while maintaining Ruby's snake_case internally.
     #
-    # It reads the response body if the content type is JSON and transforms
-    # the keys to the specified format (default is lowerCamelCase).
     class TransformResponseKeys
+      # Initializes the middleware with the Rack application and optional format.
+      #
+      # The format parameter is deprecated in favor of the global configuration
+      # setting `Securial.configuration.response_keys_format`.
+      #
+      # @param [#call] app The Rack application to wrap
+      # @param [Symbol] format Deprecated: The key format to use (defaults to :lowerCamelCase)
+      #
+      # @example
+      #   middleware = TransformResponseKeys.new(app)
+      #
+      # @deprecated Use `Securial.configuration.response_keys_format` instead of format parameter
+      #
       def initialize(app, format: :lowerCamelCase)
         @app = app
       end
 
+      # Processes the response and transforms JSON keys if applicable.
+      #
+      # Intercepts JSON responses, parses the body, transforms all keys to
+      # the configured format using the KeyTransformer helper, and replaces
+      # the response body with the transformed JSON. Non-JSON responses
+      # pass through unchanged.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [Array] The Rack response array [status, headers, body] with transformed keys
+      #
+      # @example JSON transformation
+      #   # Original response: { "first_name": "John", "last_name": "Doe" }
+      #   # Transformed response: { "firstName": "John", "lastName": "Doe" }
+      #
+      # @example Non-JSON responses
+      #   # HTML, XML, and other content types pass through unchanged
+      #
+      # @example Empty or malformed JSON handling
+      #   # Empty responses and invalid JSON are left unchanged
+      #
       def call(env)
         status, headers, response = @app.call(env)
 
@@ -33,10 +94,29 @@ module Securial
 
       private
 
+      # Checks if the response contains JSON content.
+      #
+      # @param [Hash] headers The response headers hash
+      # @return [Boolean] true if the response has JSON content type
+      # @api private
+      #
       def json_response?(headers)
         headers["Content-Type"]&.include?("application/json")
       end
 
+      # Extracts the complete response body from the response object.
+      #
+      # Iterates through the response body parts and concatenates them
+      # into a single string for JSON parsing and transformation.
+      #
+      # @param [#each] response The response body object (responds to #each)
+      # @return [String] The complete response body as a string
+      # @api private
+      #
+      # @example
+      #   body = extract_body(response)
+      #   # => '{"user_name":"john","email":"john@example.com"}'
+      #
       def extract_body(response)
         response_body = ""
         response.each { |part| response_body << part }

data/lib/securial/version.rb

@@ -6,5 +6,5 @@ module Securial
   #
   # @see https://semver.org/ Semantic Versioning 2.0.0
   # @return [String] the current version in the format "major.minor.patch"
-  VERSION = "1.0.2".freeze
+  VERSION = "1.0.3".freeze
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: securial
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Aly Badawy
 bindir: bin
 cert_chain: []
-date: 2025-06-25 00:00:00.000000000 Z
+date: 2025-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -206,22 +206,27 @@ homepage: https://github.com/AlyBadawy/Securial/wiki
 licenses:
 - MIT
 metadata:
-  release_date: '2025-06-25'
-  allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/AlyBadawy/Securial/wiki
+  release_date: '2025-06-27'
+  allowed_push_host: https://rubygems.org
   source_code_uri: https://github.com/AlyBadawy/Securial
+  documentation_uri: https://alybadawy.github.io/Securial/_index.html
   changelog_uri: https://github.com/AlyBadawy/Securial/blob/main/CHANGELOG.md
-post_install_message: "\n    ---\n    [SECURIAL] Thank you for installing Securial!\n\n
-  \   Securial is a mountable Rails engine that provides robust, extensible\n    authentication
-  and access control for Rails applications. It supports JWT,\n    API tokens, session-based
-  auth, and is designed for easy integration with\n    modern web and mobile apps.\n\n
-  \   Usage:\n      securial new APP_NAME [rails_options...]    # Create a new Rails
-  app with Securial pre-installed\n      securial -v, --version                      #
-  Show the Securial gem version\n      securial -h, --help                         #
-  Show this help message\n\n    Example:\n      securial new myapp --api --database=postgresql
-  -T\n\n    More Info:\n      review the [changelog] and [WIKI] for more info on the
-  latest\n      changes and how to use this gem/engine:\n        [Changelog]:  https://github.com/AlyBadawy/Securial/blob/main/CHANGELOG.md\n
-  \       [WIKI]:       https://github.com/AlyBadawy/Securial/wiki\n    ---\n  "
+  wiki_uri: https://github.com/AlyBadawy/Securial/wiki
+post_install_message: "\e[36m\n ▗▄▄▖▗▄▄▄▖ ▗▄▄▖▗▖ ▗▖▗▄▄▖ ▗▄▄▄▖ ▗▄▖ ▗▖\n▐▌   ▐▌   ▐▌
+  \  ▐▌ ▐▌▐▌ ▐▌  █  ▐▌ ▐▌▐▌\n ▝▀▚▖▐▛▀▀▘▐▌   ▐▌ ▐▌▐▛▀▚▖  █  ▐▛▀▜▌▐▌\n▗▄▄▞▘▐▙▄▄▖▝▚▄▄▖▝▚▄▞▘▐▌
+  ▐▌▗▄█▄▖▐▌ ▐▌▐▙▄▄▖\n\e[0m\n\n\e[32mThank you for installing Securial!\e[0m\n\n\e[37mSecurial
+  is a mountable Rails engine that provides robust, extensible\nauthentication and
+  access control for Rails applications. It supports JWT,\nAPI tokens, session-based
+  auth, and is designed for easy integration with\nmodern web and mobile apps.\e[0m\n\n\e[33mUsage:\e[0m\n
+  \ \e[36msecurial new APP_NAME [rails_options...]\e[0m    # Create a new Rails app
+  with Securial pre-installed\n  \e[36msecurial -v, --version\e[0m                      #
+  Show the Securial gem version\n  \e[36msecurial -h, --help\e[0m                         #
+  Show this help message\n\n\e[33mExample:\e[0m\n  \e[32msecurial new myapp --api
+  --database=postgresql -T\e[0m\n\n\e[33mMore Info:\e[0m\n  \e[37mreview the [changelog]
+  and [WIKI] for more info on the latest\n  changes and how to use this gem/engine:\e[0m\n
+  \   \e[34m[Changelog]:  https://github.com/AlyBadawy/Securial/blob/main/CHANGELOG.md\e[0m\n
+  \   \e[34m[WIKI]:       https://github.com/AlyBadawy/Securial/wiki\e[0m\n\e[90m---\e[0m\n"
 rdoc_options: []
 require_paths:
 - lib