securial 1.0.1 → 1.0.3

data/lib/securial/logger/builder.rb

@@ -1,3 +1,19 @@
+# @title Securial Logger Builder
+#
+# Logger construction utilities for the Securial framework.
+#
+# This file defines a builder class that constructs and configures loggers for the Securial
+# framework based on application configuration. It supports multiple logging destinations
+# (stdout and file) with appropriate formatters for each, and combines them using a
+# broadcaster pattern for unified logging.
+#
+# @example Building a logger with defaults from configuration
+#   # Securial.configuration has been set up elsewhere
+#   logger = Securial::Logger::Builder.build
+#
+#   # Log messages go to both configured destinations
+#   logger.info("User authentication successful")
+#
 require "logger"
 require "active_support/logger"
 require "active_support/tagged_logging"
@@ -7,7 +23,22 @@ require "securial/logger/formatter"
 
 module Securial
   module Logger
+    # Builder for constructing Securial's logging system.
+    #
+    # This class provides factory methods to create properly configured logger instances
+    # based on the application's configuration settings. It supports multiple logging
+    # destinations and handles the setup of formatters, log levels, and tagging.
+    #
     class Builder
+      # Builds a complete logger system based on configuration settings.
+      #
+      # Creates file and/or stdout loggers as specified in configuration and
+      # combines them using a Broadcaster to provide unified logging to multiple
+      # destinations with appropriate formatting for each.
+      #
+      # @return [Securial::Logger::Broadcaster] A broadcaster containing all configured loggers
+      # @see Securial::Logger::Broadcaster
+      #
       def self.build
         loggers = []
         progname = "Securial"
@@ -23,6 +54,17 @@ module Securial
         Broadcaster.new(loggers)
       end
 
+      # Creates and configures a file logger.
+      #
+      # Sets up a logger that writes to a Rails environment-specific log file
+      # with plain text formatting and adds it to the provided loggers array.
+      #
+      # @param progname [String] The program name to include in log entries
+      # @param level [Integer, Symbol] The log level (e.g., :info, :debug)
+      # @param loggers [Array<Logger>] Array to which the new logger will be added
+      # @return [ActiveSupport::TaggedLogging] The configured file logger
+      # @see Securial::Logger::Formatter::PlainFormatter
+      #
       def self.create_file_logger(progname, level, loggers)
         file_logger = ::Logger.new(Rails.root.join("log", "securial-#{Rails.env}.log"))
         file_logger.level = level
@@ -32,12 +74,23 @@ module Securial
         loggers << tagged_file_logger
       end
 
+      # Creates and configures a stdout logger.
+      #
+      # Sets up a logger that writes to standard output with colorful formatting
+      # and adds it to the provided loggers array.
+      #
+      # @param progname [String] The program name to include in log entries
+      # @param level [Integer, Symbol] The log level (e.g., :info, :debug)
+      # @param loggers [Array<Logger>] Array to which the new logger will be added
+      # @return [ActiveSupport::TaggedLogging] The configured stdout logger
+      # @see Securial::Logger::Formatter::ColorfulFormatter
+      #
       def self.create_stdout_logger(progname, level, loggers)
         stdout_logger = ::Logger.new($stdout)
         stdout_logger.level = level
         stdout_logger.progname = progname
         stdout_logger.formatter = Formatter::ColorfulFormatter.new
-        tagged_stdout_logger =  ActiveSupport::TaggedLogging.new(stdout_logger)
+        tagged_stdout_logger = ActiveSupport::TaggedLogging.new(stdout_logger)
         loggers << tagged_stdout_logger
       end
     end

data/lib/securial/logger/formatter.rb

@@ -1,6 +1,33 @@
+# @title Securial Logger Formatters
+#
+# Log formatting utilities for the Securial framework's logging system.
+#
+# This file defines formatter classes that determine how log messages are displayed,
+# providing both colorful terminal-friendly output and plain text output options.
+# These formatters are used by the Securial::Logger system to ensure consistent
+# and readable log formats across different environments.
+#
+# @example Using a formatter with a standard Ruby logger
+#   require 'logger'
+#   logger = Logger.new(STDOUT)
+#   logger.formatter = Securial::Logger::Formatter::ColorfulFormatter.new
+#
+#   logger.info("Application started")
+#   # Output: [2023-11-15 14:30:22] INFO  -- Application started (in green color)
+#
 module Securial
   module Logger
+    # Formatting utilities for Securial's logging system.
+    #
+    # This module contains formatter classes and constants that determine
+    # how log messages are presented. It provides both colored output for
+    # terminal environments and plain text output for file logging.
+    #
     module Formatter
+      # Terminal color codes for different log severity levels.
+      #
+      # @return [Hash{String => String}] Mapping of severity names to ANSI color codes
+      #
       COLORS = {
         "DEBUG" => "\e[36m",   # cyan
         "INFO" => "\e[32m",    # green
@@ -9,10 +36,38 @@ module Securial
         "FATAL" => "\e[35m",   # magenta
         "UNKNOWN" => "\e[37m", # white
       }.freeze
+
+      # ANSI code to reset terminal colors.
+      #
+      # @return [String] Terminal color reset sequence
+      #
       CLEAR = "\e[0m"
+
+      # Width used for severity level padding in log output.
+      #
+      # @return [Integer] Number of characters to use for severity field
+      #
       SEVERITY_WIDTH = 5
 
+      # Formatter that adds color to log output for terminal display.
+      #
+      # This formatter colorizes log messages based on their severity level,
+      # making them easier to distinguish in terminal output. It follows the
+      # standard Ruby Logger formatter interface.
+      #
+      # @example
+      #   logger = Logger.new(STDOUT)
+      #   logger.formatter = Securial::Logger::Formatter::ColorfulFormatter.new
+      #
       class ColorfulFormatter
+        # Formats a log message with color based on severity.
+        #
+        # @param severity [String] Log severity level (DEBUG, INFO, etc.)
+        # @param timestamp [Time] Time when the log event occurred
+        # @param progname [String] Program name or context for the log message
+        # @param msg [String] The log message itself
+        # @return [String] Formatted log message with appropriate ANSI color codes
+        #
         def call(severity, timestamp, progname, msg)
           color = COLORS[severity] || CLEAR
           padded_severity = severity.ljust(SEVERITY_WIDTH)
@@ -22,7 +77,25 @@ module Securial
         end
       end
 
+      # Formatter that produces plain text log output without colors.
+      #
+      # This formatter is suitable for file logging or environments where
+      # terminal colors are not supported. It follows the standard Ruby
+      # Logger formatter interface.
+      #
+      # @example
+      #   logger = Logger.new('application.log')
+      #   logger.formatter = Securial::Logger::Formatter::PlainFormatter.new
+      #
       class PlainFormatter
+        # Formats a log message in plain text without color codes.
+        #
+        # @param severity [String] Log severity level (DEBUG, INFO, etc.)
+        # @param timestamp [Time] Time when the log event occurred
+        # @param progname [String] Program name or context for the log message
+        # @param msg [String] The log message itself
+        # @return [String] Formatted log message as plain text
+        #
         def call(severity, timestamp, progname, msg)
           padded_severity = severity.ljust(SEVERITY_WIDTH)
           formatted = "[#{timestamp.strftime("%Y-%m-%d %H:%M:%S")}] #{padded_severity} -- #{msg}\n"

data/lib/securial/logger.rb

@@ -1,13 +1,54 @@
+# @title Securial Logger Configuration
+#
+# Defines the logging interface for the Securial framework.
+#
+# This file establishes the logging system for Securial, providing methods
+# to access and configure the application's logger instance. By default,
+# it initializes a logger using the Securial::Logger::Builder class, which
+# configures appropriate log levels and formatters based on the current environment.
+#
+# @example Basic logging usage
+#   # Log messages at different levels
+#   Securial.logger.debug("Detailed debugging information")
+#   Securial.logger.info("General information about system operation")
+#   Securial.logger.warn("Warning about potential issue")
+#   Securial.logger.error("Error condition")
+#
+# @example Setting a custom logger
+#   # Configure a custom logger
+#   custom_logger = Logger.new(STDOUT)
+#   custom_logger.level = :info
+#   Securial.logger = custom_logger
+#
 require_relative "logger/builder"
 
 module Securial
   extend self
   attr_accessor :logger
 
+  # Returns the logger instance used by Securial.
+  #
+  # If no logger has been set, initializes a new logger instance using
+  # the Securial::Logger::Builder class, which configures the logger
+  # based on the current environment settings.
+  #
+  # @return [Securial::Logger::Builder] the configured logger instance
+  # @see Securial::Logger::Builder
   def logger
-    @logger ||= Logger::Builder.build
+    @logger ||= Securial::Logger::Builder.build
   end
 
+  # Sets the logger instance for Securial.
+  #
+  # This allows applications to provide their own custom logger
+  # implementation that may have specialized formatting or output
+  # destinations.
+  #
+  # @param logger [Logger] a Logger-compatible object that responds to standard
+  #   logging methods (debug, info, warn, error, fatal)
+  # @return [Logger] the newly set logger instance
+  # @example
+  #   Securial.logger = Rails.logger
   def logger=(logger)
     @logger = logger
   end

data/lib/securial/middleware/request_tag_logger.rb

@@ -1,11 +1,62 @@
+# @title Securial Request Tag Logger Middleware
+#
+# Rack middleware for adding request context to log messages.
+#
+# This middleware automatically tags all log messages within a request with
+# contextual information like request ID, IP address, and user agent. This
+# enables better tracking and debugging of requests across the application
+# by providing consistent context in all log entries.
+#
+# @example Adding middleware to Rails application
+#   # config/application.rb
+#   config.middleware.use Securial::Middleware::RequestTagLogger
+#
+# @example Log output with request tags
+#   # Without middleware:
+#   [2024-06-27 10:30:15] INFO  -- User authentication successful
+#
+#   # With middleware:
+#   [2024-06-27 10:30:15] INFO  -- [abc123-def456] [IP:192.168.1.100] [UA:Mozilla/5.0...] User authentication successful
+#
 module Securial
   module Middleware
+    # Rack middleware that adds request context tags to log messages.
+    #
+    # This middleware intercepts requests and wraps the application call
+    # with tagged logging, ensuring all log messages generated during
+    # request processing include relevant request metadata for better
+    # traceability and debugging.
+    #
     class RequestTagLogger
+      # Initializes the middleware with the Rack application and logger.
+      #
+      # @param [#call] app The Rack application to wrap
+      # @param [Logger] logger The logger instance to use for tagging (defaults to Securial.logger)
+      #
+      # @example
+      #   middleware = RequestTagLogger.new(app, Rails.logger)
+      #
       def initialize(app, logger = Securial.logger)
         @app = app
         @logger = logger
       end
 
+      # Processes the request with tagged logging context.
+      #
+      # Extracts request metadata from the Rack environment and applies
+      # them as tags to all log messages generated during the request
+      # processing. Tags are automatically removed after the request completes.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [Array] The Rack response array [status, headers, body]
+      #
+      # @example Request processing with tags
+      #   # All log messages during this request will include:
+      #   # - Request ID (if available)
+      #   # - IP address (if available)
+      #   # - User agent (if available)
+      #   response = middleware.call(env)
+      #
       def call(env)
         request_id = request_id_from_env(env)
         ip_address = ip_from_env(env)
@@ -23,14 +74,43 @@ module Securial
 
       private
 
+      # Extracts the request ID from the Rack environment.
+      #
+      # Looks for request ID in ActionDispatch's request_id or the
+      # X-Request-ID header, providing request traceability across
+      # multiple services and log aggregation systems.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [String, nil] The request ID if found, nil otherwise
+      # @api private
+      #
       def request_id_from_env(env)
         env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"]
       end
 
+      # Extracts the client IP address from the Rack environment.
+      #
+      # Prioritizes ActionDispatch's processed remote IP (which handles
+      # proxy headers) over the raw REMOTE_ADDR to ensure accurate
+      # client identification behind load balancers and proxies.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [String, nil] The client IP address if found, nil otherwise
+      # @api private
+      #
       def ip_from_env(env)
         env["action_dispatch.remote_ip"]&.to_s || env["REMOTE_ADDR"]
       end
 
+      # Extracts the user agent string from the Rack environment.
+      #
+      # Retrieves the HTTP User-Agent header to provide context about
+      # the client application or browser making the request.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [String, nil] The user agent string if found, nil otherwise
+      # @api private
+      #
       def user_agent_from_env(env)
         env["HTTP_USER_AGENT"]
       end

data/lib/securial/middleware/response_headers.rb

@@ -1,17 +1,65 @@
+# @title Securial Response Headers Middleware
+#
+# Rack middleware for adding Securial-specific headers to HTTP responses.
+#
+# This middleware automatically adds identification headers to all HTTP responses
+# to indicate that the application is using Securial for authentication and to
+# provide developer attribution. These headers can be useful for debugging,
+# monitoring, and identifying Securial-powered applications.
+#
+# @example Adding middleware to Rails application
+#   # config/application.rb
+#   config.middleware.use Securial::Middleware::ResponseHeaders
+#
+# @example Response headers added by middleware
+#   # HTTP Response Headers:
+#   X-Securial-Mounted: true
+#   X-Securial-Developer: Aly Badawy - https://alybadawy.com | @alybadawy
+#
 module Securial
   module Middleware
-    # This middleware removes sensitive headers from the request environment.
-    # It is designed to enhance security by ensuring that sensitive information
-    # is not inadvertently logged or processed.
+    # Rack middleware that adds Securial identification headers to responses.
+    #
+    # This middleware enhances security transparency by clearly identifying
+    # when Securial is mounted in an application and provides developer
+    # attribution information in response headers.
+    #
     class ResponseHeaders
+      # Initializes the middleware with the Rack application.
+      #
+      # @param [#call] app The Rack application to wrap
+      #
+      # @example
+      #   middleware = ResponseHeaders.new(app)
+      #
       def initialize(app)
         @app = app
       end
 
+      # Processes the request and adds Securial headers to the response.
+      #
+      # Calls the wrapped application and then adds identification headers
+      # to the response before returning it to the client. The headers
+      # provide clear indication of Securial usage and developer attribution.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [Array] The Rack response array [status, headers, body] with added headers
+      #
+      # @example Headers added to response
+      #   # Original response headers remain unchanged
+      #   # Additional headers added:
+      #   # X-Securial-Mounted: "true"
+      #   # X-Securial-Developer: "Aly Badawy - https://alybadawy.com | @alybadawy"
+      #
       def call(env)
         status, headers, response = @app.call(env)
+
+        # Indicate that Securial is mounted and active
         headers["X-Securial-Mounted"] = "true"
+
+        # Provide developer attribution
         headers["X-Securial-Developer"] = "Aly Badawy - https://alybadawy.com | @alybadawy"
+
         [status, headers, response]
       end
     end

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