ronflex 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 109826546b5ad30bac8df1832887023a7c8bda79df3f240b2aac4f9b9af816b5
+  data.tar.gz: 2764d13b18441bd16a695848174dc14010f663afcdecc78c1fb7f7fc2422e5f0
+SHA512:
+  metadata.gz: 28820603b4ed03da0c23247e42096d069b9571f8623e494a8443ab7515c714c888a08b072931949ad76f45fba3866f6d6527be66fa7614d5b6276cdb690cfd94
+  data.tar.gz: 9b65bc8ed111da7adcb65d310ae5184ca3c67d2f02d81365b6035b175449984f6ca18d4ffd082559624fb72e78a47804a9d71df713cab009e497466e3f746b63

data/README.md

@@ -0,0 +1,154 @@
+# Ronflex Gem
+
+[![Gem Version](https://badge.fury.io/rb/ronflex.svg)](http://badge.fury.io/rb/ronflex)
+
+`Ronflex` is a Ruby gem that provides a middleware for managing requests and displaying a custom maintenance page during downtime or maintenance. It also offers configuration options to handle user access and authorization rules, making it easy to implement a custom maintenance mode in your application.
+
+## Installation
+
+Run:
+
+    bundle add zarby
+
+Or install it yourself as:
+
+    $ gem install zarby
+
+## Configuration
+
+```ruby
+Ronflex.configure do |config|
+  # The list of paths that are always accessible (no restrictions)
+  config.excluded_path = ["/health_check", "/status"]
+
+  # Define a provider for user model (can be a Proc or Lambda)
+  config.provider = ->(env) { User.find_by(api_key: env['HTTP_API_KEY']) }
+
+  # Define rules for which routes users are authorized to access
+  config.add_rule :admin do |user, request|
+    request.path.start_with?("/admin") && user.admin?
+  end
+
+  # Enable or disable the maintenance mode
+  config.enable = true
+
+  # Optional: Set a custom maintenance page (HTML or ERB template)
+  config.maintenance_page = "/path/to/maintenance_page.html"  # Or "/path/to/maintenance_page.erb"
+end
+```
+
+## Enable or disable ronflex
+```ruby
+# Playing the pokeflute, Ronflex wakes up and no longer blocks the road
+Ronflex.play_pokeflute
+
+# Stop the pokeflute, Ronflex falls asleep and blocks the road again
+Ronflex.stop_pokeflute
+```
+
+## Configuration Options
+
+- excluded_path (Array): A list of paths that are always accessible, even when the application is in maintenance mode.
+
+Default: ["/health_check"]
+
+- provider (Proc/Lambda): A function that returns the user model based on the request environment. This is used to determine which user is making the request.
+
+exemple:
+```ruby
+config.provider = ->(env) { User.find_by(api_key: env['HTTP_API_KEY']) }
+```
+
+- rules (Array): A collection of rules for user access authorization. You can add rules to control access based on the user type and request path.
+
+Example:
+```ruby
+config.add_rule :admin do |user, request|
+  user.admin? && request.path.start_with?("/admin")
+end
+```
+
+- enable (Boolean): Enable or disable maintenance mode.
+Default: false
+
+- maintenance_page (String): A path to a custom maintenance page (HTML or ERB). If not set, a default maintenance page will be used.
+
+Example:
+```ruby
+config.maintenance_page = "/path/to/maintenance_page.html"
+```
+
+## Middleware
+Ronflex includes a Rack middleware (Ronflex::Rest) that intercepts incoming requests and checks whether the application should be in maintenance mode.
+
+- If the enable flag is set to true and the user is not authorized or the system is under maintenance, the middleware will return a 503 response with the maintenance page.
+- If the request path is in the excluded_path list, it will always be allowed through.
+
+Example usage in config/application.rb:
+```ruby
+# Add Ronflex middleware to the stack
+config.middleware.use Ronflex::Rest
+```
+
+Example of Request Handling with Middleware
+The middleware checks the following conditions before allowing a request to proceed:
+
+1. Always Accessible Paths: If the request path is in excluded_path, it is immediately allowed.
+2. Maintenance Mode: If enable is true and the user is not authorized, the request will return the maintenance page.
+3. Authorization: If a user is authenticated and authorized to access the requested route, the request proceeds as normal.
+
+## Custom Maintenance Page
+If you configure a custom maintenance_page path in your Ronflex.configure block, the middleware will load the file and return it as the response when the application is in maintenance mode.
+
+- The custom maintenance page can be either a static HTML file or an ERB template. If it's an ERB file, it will be rendered.
+- If the custom page is not found or if no maintenance_page is configured, a default maintenance page will be returned.
+
+```ruby
+Ronflex.configure do |config|
+  config.maintenance_page = "/path/to/custom/maintenance_page.html"
+end
+```
+
+## Customization and Extensibility
+
+Adding Custom Authorization Rules
+You can add custom rules to control which users are allowed to access specific parts of your application. For example:
+```ruby
+Ronflex.configure do |config|
+  # Only admin users can access /admin routes
+  config.add_rule :admin do |user, request|
+    user.admin? && request.path.start_with?("/admin")
+  end
+end
+```
+
+## Handling User Model
+Ronflex uses a provider (a lambda or Proc) to determine which user is making the request based on the request environment. This allows you to integrate with your own user authentication system.
+```ruby
+Ronflex.configure do |config|
+  config.provider = ->(env) { User.find_by(api_key: env['HTTP_API_KEY']) }
+end
+```
+
+## Example Flow
+1. Request Access: When a request is made, the middleware checks if the request path is in the list of excluded_path.
+2. Maintenance Mode: If enable is true and the user is not authorized, the request will return the maintenance page.
+3. Authorization: If the request is for an authorized route, the request proceeds as normal.
+
+## Example Output of Maintenance Page
+When the application is in maintenance mode, the user will see a page like the following:
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Maintenance</title>
+  </head>
+  <body>
+    <h1>The site is currently under maintenance</h1>
+    <p>Please try again later</p>
+  </body>
+</html>
+```
+
+## Error Handling
+In case of issues loading the custom maintenance page (e.g., if the file does not exist), Ronflex will fallback to a default maintenance page.

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/gem_info.txt

@@ -0,0 +1,5 @@
+## TEST ##
+
+## PUSH GEM ##
+
+gem build ronflex.gemspec

data/lib/ronflex/configuration.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "ronflex/rule"
+require "ronflex/errors"
+
+# Module Ronflex
+# 
+# This module provides configuration to manage access rules based on templates and queries,
+# with options to exclude certain paths or customize logic via a provider.
+#
+# @example Basic setup
+#   Ronflex.configure do |config|
+#     # add path to exclude all rule
+#     config.excluded_path << "/public"
+
+#     # add a provider to identify the model user
+#     config.provider = ->(env) { env[:current_user] }
+
+#     # add rule for administrator
+#     config.add_rule(:admin) do |user, request|
+#       # admins can access to all routes, expected "/restricted"
+#       !request.path.start_with?("/restricted")
+#     end
+
+#     # add rule for guest
+#     config.add_rule(:guest) do |user, request|
+#       # guests can only acces public path
+#       request.path.start_with?("/public")
+#     end
+#     
+#     # add custom page maintenance
+#     config.maintenance_page = "/path/to/your/custom/maintenance/page.html"
+# end
+module Ronflex
+  class Configuration
+    # List of paths excluded by default.
+    # These paths are ignored by the defined rules.
+    #
+    # @return [Array<String>]
+    DEFAULT_EXCLUDED_PATHS = ["/health_check"]
+    # Default provider.
+    # by default, it is a lambda which returns `nil`.
+    #
+    # @return [Proc]
+    DEFAULT_PROVIDER = -> (env) { nil }
+
+    # Attribute for desable or enable th feature
+    #
+    # @return [Boolean]
+    attr_accessor :enable
+
+    # List of paths excluded from rule evaluation.
+    #
+    # @return [Array<String>]
+    attr_accessor :excluded_path
+
+    # Custom provider to retrieve a model based on the environment.
+    #
+    # @return [Proc]
+    attr_accessor :provider
+
+    # List of defined access rules.
+    #
+    # @return [Array<Rule>]
+    attr_accessor :rules
+
+    # Path to a custom maintenance page (either an HTML or ERB file).
+    #
+    # @return [String]
+    attr_accessor :maintenance_page
+
+    # Initializes a new configuration with default values.
+    def initialize
+      @excluded_path = DEFAULT_EXCLUDED_PATHS.dup
+      @provider = DEFAULT_PROVIDER
+      @enable = false
+      @maintenance_page = nil
+      @rules = []
+    end
+  
+    # Adds an access rule for a specific type.
+    #
+    # A rule is a block of code that determines whether a model is allowed to access a given query.
+    #
+    # @param type [Symbol, String] The type or role of the model (e.g. `:admin`, `:user`).
+    # @yield [model, request] The rule block, which takes a model and a request as parameters.
+    # @yieldparam model [Object] The evaluated model.
+    # @yieldparam request [Object] The evaluated request.
+    # @return [void]
+    #
+    # @example Add a rule for administrators
+    # config.add_rule(:admin) do |model, request|
+    # request.path.start_with?("/admin")
+    # end
+    def add_rule(type, &block)
+      raise RonflexArgumentError, "Rule type must be provided" if type.nil?
+      raise RonflexArgumentError, "Block must be provided for the rule" unless block_given?
+      @rules << Rule.new(type, &block)
+    end
+  
+    # Checks if a model is allowed to access a given query.
+    #
+    # This method iterates through the defined rules and applies those matching the pattern.
+    #
+    # @param model [Object] The model to check (e.g. a user or a symbolic role).
+    # @param request [Object] The request to check, which should respond to methods like `path`.
+    # @return [Boolean] `true` if at least one rule authorizes access, `false` otherwise.
+    #
+    # @example Check an authorization
+    # model = :admin
+    # request = OpenStruct.new(path: "/admin/dashboard")
+    # config.allowed?(model, request) # => true or false
+    def allowed?(model, request)
+      rules.any? { |rule| rule.matches?(model, request) }
+    end
+
+
+    # Checks if a model is valid (present).
+    #
+    # @param model [Object] The model to check.
+    # @return [Boolean] `true` if the model is valid, `false` otherwise.
+    #
+    # @note This method uses the `present?` method, which is typically available in Rails.
+    # If you are not using Rails, you may need to override this method.
+    def model_present?(model)
+      !model.nil? && !(model.respond_to?(:empty?) && model.empty?)
+    end
+  end
+end

data/lib/ronflex/errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Ronflex
+  class Error < StandardError; end
+  class RonflexArgumentError < ArgumentError end
+end

data/lib/ronflex/railties.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "ronflex/rest"
+
+module Ronflex
+  class Railtie < Rails::Railtie
+    initializer "ronflex.configure_rails_initialization" do |app|
+      app.middleware.insert_before 0, Ronflex::Rest
+    end
+  end
+end

data/lib/ronflex/rest.rb

@@ -0,0 +1,123 @@
+module Ronflex
+  class Rest
+    # Initializes the middleware with the given app
+    #
+    # @param app [Object] The application instance that this middleware wraps
+    #   It will call the next middleware or application in the stack.
+    def initialize(app)
+      @app = app
+    end
+
+    # Rack middleware call method that processes the incoming request.
+    #
+    # It checks if the request should be granted access, and if not, it returns
+    # the maintenance page or proceeds with the normal request handling.
+    #
+    # @param env [Hash] Rack environment hash which contains information about
+    #   the incoming request, such as headers, parameters, etc.
+    #
+    # @return [Array] Rack response in the form of [status, headers, body]
+    #   If access is allowed, the request is passed to the next middleware/application.
+    #   Otherwise, a 503 status with the maintenance page is returned.
+    def call(env)
+      request = Rack::Request.new(env)
+      model = Ronflex.configuration.provider.call(env)
+
+      # If the request is always accessible (excluded path), pass the request to the next app
+      return @app.call(env) if always_access?(request)
+
+      # If the system is enabled and the model is present and authorized, proceed with the request
+      if Ronflex.configuration.enable
+        if model_present?(model) && routes_authorized?(model, request)
+          return @app.call(env)
+        else
+          # If conditions are not met, return maintenance page
+          return [503, { "Content-Type" => "text/html" }, [maintenance_page]]
+        end
+      end
+
+      # Default pass-through for the request
+      @app.call(env)
+    end
+
+    private
+
+    # Checks if the request path is always accessible, i.e., excluded from any restrictions.
+    #
+    # @param request [Rack::Request] The current HTTP request object
+    #
+    # @return [Boolean] Returns `true` if the request path is in the list of excluded paths.
+    def always_access?(request)
+      Ronflex.configuration.excluded_path.include?(request.path)
+    end
+
+    # Checks if the model (user or entity) is present and valid.
+    #
+    # @param model [Object] The model (typically a user) retrieved from the provider.
+    #
+    # @return [Boolean] Returns `true` if the model is present and valid as per the configuration.
+    def model_present?(model)
+      Ronflex.configuration.model_present?(model)
+    end
+
+    # Checks if the current route is authorized for the given model.
+    #
+    # @param model [Object] The model (user or entity) for which access needs to be authorized.
+    # @param request [Rack::Request] The current HTTP request object containing the route.
+    #
+    # @return [Boolean] Returns `true` if the model is allowed to access the requested route.
+    def routes_authorized?(model, request)
+      Ronflex.configuration.allowed?(model, request)
+    end
+
+    # Returns the content of the maintenance page, either custom or default.
+    #
+    # @return [String] The HTML content to be displayed on the maintenance page.
+    def maintenance_page
+      if Ronflex.configuration.maintenance_page
+        load_custom_maintenance_page(Ronflex.configuration.maintenance_page)
+      else
+        default_maintenance_page
+      end
+    end
+
+    # Loads a custom maintenance page if a path is provided.
+    #
+    # If the path is an ERB file, it renders the template. Otherwise, it reads and returns the HTML file.
+    #
+    # @param path [String] The file path to the custom maintenance page (could be HTML or ERB).
+    #
+    # @return [String] The rendered HTML content of the custom maintenance page.
+    def load_custom_maintenance_page(path)
+      if path.end_with?(".erb")
+        template = ERB.new(File.read(path))
+        template.result
+      else
+        File.read(path)
+      end
+    rescue Errno::ENOENT
+      default_maintenance_page
+    end
+
+    # Provides the default maintenance page content.
+    #
+    # This is a basic HTML page shown when no custom page is configured or when
+    # there is an issue loading the custom maintenance page.
+    #
+    # @return [String] The default HTML content for the maintenance page.
+    def default_maintenance_page
+      <<~HTML
+        <!DOCTYPE html>
+        <html>
+          <head>
+            <title>Maintenance</title>
+          </head>
+          <body>
+            <h1>The site is currently under maintenance</h1>
+            <p>Please try again later</p>
+          </body>
+        </html>
+      HTML
+    end
+  end
+end

data/lib/ronflex/rule.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Module Ronflex
+#
+# This module encapsulates functionality related to rule-based access control.
+# The `Rule` class within this module represents a single rule that determines
+# whether a specific model (e.g., a user or role) is allowed access to a given request.
+module Ronflex
+  # Class Rule
+  #
+  # Represents a rule that associates a specific type (e.g., `:admin`, `:guest`) with 
+  # a custom condition defined by a block of logic. The rule can then evaluate whether 
+  # a model matches the type and satisfies the condition for a particular request.
+  class Rule
+    # @return [Symbol, String] the type of the model this rule applies to (e.g., `:admin` or `:guest`).
+    attr_reader :type
+
+    # @return [Proc] the block of logic that determines if the rule matches a given model and request.
+    attr_reader :rule
+
+    # Initializes a new rule.
+    #
+    # @param type [Symbol, String] The type of model this rule applies to.
+    #   Typically a symbol representing a role (e.g., `:admin` or `:guest`).
+    # @yield [model, request] The block defining the rule's logic. It is executed to determine
+    #   if the rule matches for a given model and request.
+    # @yieldparam model [Object] The model being evaluated (e.g., a user or role).
+    # @yieldparam request [Object] The request being evaluated (e.g., an HTTP request object).
+    def initialize(type, &block)
+      @type = type
+      @rule = block
+    end
+
+    # Checks if the rule matches a given model and request.
+    #
+    # This method evaluates whether the provided model matches the rule's type
+    # and if the rule's block returns `true` for the given model and request.
+    #
+    # @param model [Object] The model to check (e.g., a user or role).
+    # @param request [Object] The request to check (e.g., an HTTP request object).
+    # @return [Boolean] `true` if the model matches the rule's type and satisfies the block's logic, `false` otherwise.
+    def matches?(model, request)
+      model == type && rule.call(model, request)
+    end
+  end
+end
+

data/lib/ronflex/version.rb

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

data/lib/ronflex.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "ronflex/version"
+require "ronflex/configuration"
+
+module Ronflex  
+  class << self
+    # Method to configure `Snorlax` with a block
+    #
+    # @yield [config] The block receives an instance of `Snorlax::Configuration`
+    # @yieldparam config [Snorlax::Configuration] The configuration object to modify.
+    def configure
+      @configuration ||= Configuration.new
+      yield @configuration if block_given?
+    end
+
+    # Accesses global configuration
+    #
+    # @return [Snorlax::Configuration] The global instance of the configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Simulates playing the Pokéflute, disabling a feature.
+    #
+    # This method modifies the global configuration to enable a specific feature.
+    #
+    # @return [void]
+    def play_pokeflute
+      configuration.enable = false
+    end
+
+    # Simulates stopping the Pokéflute, enabling a feature.
+    #
+    # This method modifies the global configuration to disable a specific feature.
+    #
+    # @return [void]
+    def stop_pokeflute
+      configuration.enable = true
+    end
+  end
+end

data/sig/ronflex.rbs

@@ -0,0 +1,4 @@
+module Ronflex
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: ronflex
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- vianney.sonneville
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-11-29 00:00:00.000000000 Z
+dependencies: []
+description: Ronflex is a Ruby gem that provides a middleware for managing requests
+  and displaying a custom maintenance page during downtime or maintenance. It also
+  offers configuration options to handle user access and authorization rules, making
+  it easy to implement a custom maintenance mode in your application.
+email:
+- vianneysonneville4@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- gem_info.txt
+- lib/ronflex.rb
+- lib/ronflex/configuration.rb
+- lib/ronflex/errors.rb
+- lib/ronflex/railties.rb
+- lib/ronflex/rest.rb
+- lib/ronflex/rule.rb
+- lib/ronflex/version.rb
+- sig/ronflex.rbs
+homepage: https://rubygems.org/gems/ronflex.
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/VianneySonneville/ronflex
+  changelog_uri: https://github.com/VianneySonneville/ronflex/blob/main/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.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key:
+specification_version: 4
+summary: Gem that provides a middleware for managing requests and displaying a custom
+  maintenance page during downtime or maintenance.
+test_files: []