lennarb 1.4.0 → 1.5.0

data/lib/lennarb/base.rb

@@ -0,0 +1,314 @@
+module Lennarb
+  # Base class for mounting applications with middleware support.
+  # This class serves as a proxy for mounting Lennarb::App instances,
+  # providing a lightweight router to dispatch requests to the appropriate app.
+  #
+  # @example Creating a mounting application
+  #   class Application < Lennarb::Base
+  #     # Define base-level middleware
+  #     middleware do
+  #       use Rack::Session::Cookie, secret: "your_secret"
+  #       use Rack::Protection
+  #     end
+  #
+  #     # Mount other applications
+  #     mount(Blog, at: "/blog")
+  #     mount(Admin, at: "/admin")
+  #   end
+  #
+  #   # Start the server
+  #   run Application.new
+  #
+  # @since 1.4.0
+  class Base
+    # This error is raised whenever the app is initialized more than once.
+    # @since 1.0.0
+    AlreadyInitializedError = Class.new(StandardError)
+
+    class << self
+      # Store for mounted applications at class level
+      # @return [Hash] mounted applications by path
+      # @since 1.4.0
+      def mounted_apps
+        @mounted_apps ||= {}
+      end
+
+      # Define the app's middleware stack at class level.
+      # This allows defining middleware that will be applied before
+      # routing to any mounted applications.
+      #
+      # @yield [middleware] Block to configure middleware
+      # @return [Lennarb::MiddlewareStack] the middleware stack
+      # @since 1.4.0
+      #
+      # @example
+      #   middleware do
+      #     use Rack::Session::Cookie, secret: "your_secret"
+      #     use Rack::Protection
+      #   end
+      def middleware(&block)
+        @middleware ||= MiddlewareStack.new
+        @middleware.instance_eval(&block) if block_given?
+        @middleware
+      end
+
+      # Define the app's configuration at class level
+      # @param [Array<Symbol>] envs Environments to apply the configuration to
+      # @yield [config] Block to configure the application
+      # @return [Lennarb::Config] the configuration
+      # @since 1.4.0
+      #
+      # @example Configure for all environments
+      #   config do
+      #     set :title, "My Application"
+      #   end
+      #
+      # @example Configure for specific environments
+      #   config :development, :test do
+      #     set :debug, true
+      #   end
+      def config(*envs, &block)
+        @config ||= Config.new
+        @config.instance_eval(&block) if block_given?
+        @config
+      end
+
+      # Mount a component at the given path.
+      # @param [Class] component The component to mount (must be a Lennarb::App subclass)
+      # @param [Hash] options The mounting options
+      # @option options [String] :at The path to mount the component at (defaults to "/")
+      # @raise [ArgumentError] If the component is not a Lennarb::App subclass
+      # @return [void]
+      # @since 1.4.0
+      #
+      # @example
+      #   mount(Blog, at: "/blog")
+      #   mount(Admin, at: "/admin")
+      def mount(component, at: nil)
+        if component.is_a?(Class) && component < Lennarb::App
+          path = normalize_mount_path(at || "/")
+          mounted_apps[path] = component
+        else
+          raise ArgumentError, "Component must be a Lennarb::App subclass"
+        end
+      end
+
+      # Normalize the mount path.
+      # @param [String] path The path to normalize
+      # @return [String] The normalized path
+      # @since 1.4.0
+      # @api private
+      private def normalize_mount_path(path)
+        path = "/#{path}" unless path.start_with?("/")
+        path = path[0..-2] if path.end_with?("/") && path != "/"
+        path
+      end
+    end
+
+    # The current environment.
+    # @return [Lennarb::Environment] The environment
+    # @since 1.0.0
+    attr_reader :env
+
+    # The root directory of the application.
+    # @return [Pathname] The root directory
+    # @since 1.0.0
+    attr_accessor :root
+
+    # Get the mounted applications.
+    # @return [Hash] The mounted applications by path
+    # @since 1.4.0
+    attr_reader :mounted_apps
+
+    # Initialize a new Base instance.
+    # @yield [self] Block to configure the application
+    # @return [Base] The initialized application
+    # @since 1.0.0
+    def initialize(&block)
+      @initialized = false
+      @mounted_apps = {}
+      @middleware = nil
+      self.root = Pathname.pwd
+      @env = Environment.new(compute_env)
+
+      # Initialize mounted applications from class definition
+      self.class.mounted_apps.each do |path, app_class|
+        @mounted_apps[path] = app_class
+      end
+
+      instance_eval(&block) if block_given?
+    end
+
+    # Define the app's middleware stack.
+    # Middleware defined here will be applied to all requests before
+    # they are routed to mounted applications.
+    #
+    # @yield [middleware] Block to configure middleware
+    # @return [Lennarb::MiddlewareStack] the middleware stack
+    # @since 1.4.0
+    #
+    # @example
+    #   middleware do
+    #     use Rack::Session::Cookie, secret: "your_secret"
+    #     use Rack::Protection
+    #   end
+    def middleware(&block)
+      @middleware ||= MiddlewareStack.new
+      @middleware.instance_eval(&block) if block_given?
+      @middleware
+    end
+
+    # Define the app's configuration.
+    # @param [Array<Symbol>] envs Environments to apply the configuration to
+    # @yield [config] Block to configure the application
+    # @return [Lennarb::Config] the configuration
+    # @since 1.4.0
+    def config(*envs, &block)
+      @config ||= Config.new
+
+      write = block_given? &&
+        (envs.map(&:to_sym).include?(env.to_sym) || envs.empty?)
+
+      @config.instance_eval(&block) if write
+
+      @config
+    end
+
+    # Check if the app is initialized.
+    # @return [Boolean] true if initialized, false otherwise
+    # @since 1.4.0
+    def initialized?
+      @initialized
+    end
+
+    # Initialize the app.
+    # @return [self] The initialized app
+    # @raise [AlreadyInitializedError] If the app is already initialized
+    # @since 1.4.0
+    def initialize!
+      raise AlreadyInitializedError if initialized?
+      @initialized = true
+      self
+    end
+
+    # Set the environment for the application.
+    # @param [String, Symbol] value The environment name
+    # @raise [AlreadyInitializedError] If the app is already initialized
+    # @return [Lennarb::Environment] The new environment
+    # @since 1.4.0
+    def env=(value)
+      raise AlreadyInitializedError if initialized?
+      @env = Environment.new(value)
+    end
+
+    # Freeze the app.
+    # @return [void]
+    # @since 1.0.0
+    def freeze!
+      app.freeze
+    end
+
+    # The Rack app with all middlewares and mounted applications.
+    # This builds a middleware stack around the URL map of mounted applications.
+    #
+    # @return [#call] The Rack application
+    # @since 1.0.0
+    def app
+      @app ||= begin
+        url_map = build_url_map
+
+        stack = middleware.to_a
+
+        Rack::Builder.app do
+          stack.each { |middleware, args, block| use(middleware, *args, &block) }
+          run url_map
+        end
+      end
+    end
+
+    # Call the app - main Rack entry point.
+    # This method is called by Rack when a request is received.
+    #
+    # @param [Hash] env The Rack environment
+    # @return [Array(Integer, Hash, #each)] The Rack response
+    # @since 1.0.0
+    def call(env)
+      # Store reference to the current app in the env
+      env[RACK_LENNA_APP] = self
+
+      # Call the app with middlewares
+      app.call(env)
+    end
+
+    # Mount a component at the given path (instance method)
+    # @param [Class] component The component to mount (must be a Lennarb::App subclass)
+    # @param [Hash] options The mounting options
+    # @option options [String] :at The path to mount the component at (defaults to "/")
+    # @raise [ArgumentError] If the component is not a Lennarb::App subclass
+    # @return [void]
+    # @since 1.4.0
+    #
+    # @example
+    #   mount(Blog, at: "/blog")
+    def mount(component, at: nil)
+      if component.is_a?(Class) && component < Lennarb::App
+        path = normalize_mount_path(at || "/")
+        @mounted_apps[path] = component
+      else
+        raise ArgumentError, "Component must be a Lennarb::App subclass"
+      end
+    end
+
+    private
+
+    # Build the URL map with all mounted applications.
+    # @return [Rack::URLMap] The URL map
+    # @since 1.4.0
+    # @api private
+    def build_url_map
+      url_map = {}
+
+      if mounted_apps.any?
+        mounted_apps.each do |path, app_class|
+          app_instance = app_class.new
+          app_instance.initialize!
+          url_map[path] = app_instance
+        end
+      end
+
+      # If no app is mounted at root path, provide a default handler
+      url_map["/"] = default_app_handler unless url_map.key?("/")
+
+      Rack::URLMap.new(url_map)
+    end
+
+    # Default handler for when no app is mounted at root path.
+    # @return [#call] A simple not found handler
+    # @since 1.4.0
+    # @api private
+    def default_app_handler
+      # config.logger.warn("No application mounted at root path. Default handler will be used.")
+      ->(env) { [404, {"content-type" => "text/plain"}, ["Not Found"]] }
+    end
+
+    # Normalize the mount path.
+    # @param [String] path The path to normalize
+    # @return [String] The normalized path
+    # @since 1.4.0
+    # @api private
+    def normalize_mount_path(path)
+      path = "/#{path}" unless path.start_with?("/")
+      path = path[0..-2] if path.end_with?("/") && path != "/"
+      path
+    end
+
+    # Compute the current environment from environment variables.
+    # @return [String] The environment name
+    # @since 1.4.0
+    # @api private
+    def compute_env
+      env = ENV_NAMES.map { |name| ENV[name] }.compact.first.to_s
+      env.empty? ? "development" : env
+    end
+  end
+end

data/lib/lennarb/config.rb

@@ -0,0 +1,52 @@
+module Lennarb
+  # The configuration for the application.
+  # It uses {https://rubygems.org/gems/superconfig SuperConfig} to define the
+  # configuration.
+  class Config < SuperConfig::Base
+    undef_method :credential
+
+    attr_reader :app
+    attr_accessor :stderr_output
+
+    def initialize(app = nil, silent: !ENV["LENNARB_SILENT_LOGS"].nil?, **options)
+      self.stderr_output = if silent
+        nil
+      else
+        $stderr
+      end
+
+      @app = app
+      block = proc { true }
+      super(**options, &block)
+      apply_defaults_settings
+    end
+
+    # @private
+    def to_s = "#<Lennarb::Config>"
+
+    # @private
+    def mandatory(*, **)
+      super
+    rescue SuperConfig::MissingEnvironmentVariable => error
+      raise MissingEnvironmentVariable, error.message
+    end
+
+    # @private
+    def property(*, **, &)
+      super
+    rescue SuperConfig::MissingCallable
+      raise MissingCallable,
+        "arg[1] must respond to #call or a block must be provided"
+    end
+
+    private def apply_defaults_settings
+      set :logger,
+        Lennarb::Logger.new(
+          ::Logger.new(stderr_output),
+          colorize: true,
+          tag: :lennarb
+        )
+      set :enable_reloading, false
+    end
+  end
+end

data/lib/lennarb/constants.rb

@@ -0,0 +1,12 @@
+module Lennarb
+  # The root app directory of the app.
+  RACK_LENNA_APP = "lennarb.app"
+  # The current environment. Defaults to "development".
+  ENV_NAMES = %w[LENNA_ENV APP_ENV RACK_ENV]
+  # The HTTP methods.
+  HTTP_METHODS = %i[GET POST PUT PATCH DELETE HEAD OPTIONS]
+  # The HTTP status codes.
+  CONTENT_TYPE = {HTML: "text/html", TEXT: "text/plain", JSON: "application/json"}
+  # The current environment. Defaults to "development".
+  NAMES = %i[development test production local]
+end

data/lib/lennarb/environment.rb

@@ -0,0 +1,80 @@
+module Lennarb
+  # Manage the environment of the application.
+  #
+  # @example
+  #  app.env.development? # => true
+  #  app.env.test? # => false
+  #
+  class Environment
+    # Returns the name of the environment.
+    # @param name [Symbol]
+    #
+    attr_reader :name
+
+    # Initialize the environment.
+    #  @param name [String, Symbol] The name of the environment.
+    #
+    def initialize(name)
+      @name = name.to_sym
+
+      return if NAMES.include?(@name)
+
+      raise ArgumentError, "Invalid environment: #{@name.inspect}"
+    end
+
+    # Returns true if the environment is development.
+    #
+    def development? = name == :development
+
+    # Returns true if the environment is test.
+    #
+    def test? = name == :test
+
+    # Returns true if the environment is production.
+    #
+    def production? = name == :production
+
+    # Returns true if the environment is local (either `test` or `development`).
+    #
+    def local? = test? || development?
+
+    # Implements equality for the environment.
+    #
+    def ==(other) = name == other || name.to_s == other
+    alias_method :eql?, :==
+    alias_method :equal?, :==
+    alias_method :===, :==
+
+    # Returns the name of the environment as a symbol.
+    # @retrn [Symbol]
+    #
+    def to_sym = name
+
+    # Returns the name of the environment as a string.
+    # @retrn [String]
+    #
+    def to_s = name.to_s
+
+    # Returns the name of the environment as a string.
+    # @retrn [String]
+    def inspect = to_s.inspect
+
+    # Yields a block if the environment is the same as the given environment.
+    # - To match all environments use `:any` or `:all`.
+    # - To match local environments use `:local`.
+    # @param envs [Array<Symbol>] The environment(s) to check.
+    #
+    # @example
+    #   app.env.on(:development) do
+    #     # Code to run in development
+    #   end
+    def on(*envs)
+      matched = envs.include?(:any) ||
+        envs.include?(:all) ||
+        envs.include?(name) ||
+        (envs.include?(:local) && local?)
+
+      yield if matched
+    end
+  end
+end

data/lib/lennarb/errors.rb

@@ -0,0 +1,17 @@
+module Lennarb
+  # Lite implementation of app.
+  #
+  Error = Class.new(StandardError)
+  # This error is raised whenever the app is initialized more than once.
+  #
+  DuplicateRouteError = Class.new(StandardError)
+  # This error is raised whenever the app is initialized more than once.
+  #
+  MissingEnvironmentVariable = Class.new(StandardError)
+  # This error is raised whenever the app is initialized more than once.
+  #
+  MissingCallable = Class.new(StandardError)
+  # This error is raised whenever the app is initialized more than once.
+  #
+  RoutesFrozenError = Class.new(RuntimeError)
+end

data/lib/lennarb/helpers.rb

@@ -0,0 +1,40 @@
+module Lennarb
+  # Simple helpers module for Lennarb applications.
+  # Provides helper methods to be used in routes and hooks.
+  module Helpers
+    # Store helpers for app classes
+    @app_helpers = {}
+
+    class << self
+      # Get the app helpers map
+      attr_reader :app_helpers
+
+      # Get helpers module for an app class
+      #
+      # @param [Class] app_class The application class
+      # @return [Module] The helpers module
+      def for(app_class)
+        app_helpers[app_class] ||= Module.new
+      end
+
+      # Define helpers for an app class
+      #
+      # @param [Class] app_class The application class
+      # @param [Module, Proc] mod_or_block The module to include or block with helper definitions
+      # @return [Module] The helpers module
+      def define(app_class, mod_or_block = nil, &block)
+        mod = self.for(app_class)
+
+        case mod_or_block
+        when Module
+          mod.include(mod_or_block)
+        when Proc
+          mod.module_eval(&mod_or_block)
+        end
+
+        mod.module_eval(&block) if block_given?
+        mod
+      end
+    end
+  end
+end

data/lib/lennarb/hooks.rb

@@ -0,0 +1,71 @@
+module Lennarb
+  # Provides hook functionality for Lennarb applications.
+  # Hooks execute code before and after route handlers.
+  #
+  # @example
+  #   Hooks.add(MyApp, :before) do |req, res|
+  #     res.headers["X-My-Header"] = "MyValue"
+  #   end
+  #   Hooks.add(MyApp, :after) do |req, res|
+  #     res.body << "Goodbye!"
+  #   end
+  #
+  # @note
+  #   - Hooks are executed in the order they are added.
+  #   - The context of the hook is the object that calls the route handler.
+  #   - Hooks can modify the request and response objects.
+  #   - Hooks can be used to implement middleware-like functionality.
+  #   - Hooks are not thread-safe. Use with caution in multi-threaded environments.
+  module Hooks
+    # Valid hook types
+    TYPES = [:before, :after].freeze
+
+    # Store hooks for each app class
+    @app_hooks = {}
+
+    class << self
+      # Get the hooks hash
+      #
+      # @return [Hash] The hooks hash with app classes as keys
+      attr_reader :app_hooks
+
+      # Get the hooks for an app class
+      #
+      # @param [Class] app_class The application class
+      # @return [Hash] The hooks hash with :before and :after keys
+      def for(app_class)
+        app_hooks[app_class] ||= {before: [], after: []}
+      end
+
+      # Add a hook for an app class
+      #
+      # @param [Class] app_class The application class
+      # @param [Symbol] type The hook type (:before or :after)
+      # @param [Proc] block The hook block
+      # @return [Array] The hooks array for the given type
+      def add(app_class, type, &block)
+        raise ArgumentError, "Invalid hook type: #{type}" unless TYPES.include?(type)
+
+        hooks = self.for(app_class)
+        hooks[type] << block if block_given?
+        hooks[type]
+      end
+
+      # Execute hooks of a given type
+      #
+      # @param [Object] context The execution context
+      # @param [Class] app_class The application class
+      # @param [Symbol] type The hook type to execute
+      # @param [Request] req The request object
+      # @param [Response] res The response object
+      # @return [void]
+      def execute(context, app_class, type, req, res)
+        hooks = self.for(app_class)[type]
+
+        hooks.each do |hook|
+          context.instance_exec(req, res, &hook)
+        end
+      end
+    end
+  end
+end

data/lib/lennarb/logger.rb

@@ -0,0 +1,100 @@
+module Lennarb
+  class Logger
+    # @api private
+    LEVELS = {
+      debug: ::Logger::DEBUG,
+      info: ::Logger::INFO,
+      warn: ::Logger::WARN,
+      error: ::Logger::ERROR,
+      fatal: ::Logger::FATAL
+    }.freeze
+
+    # @api private
+    DEFAULT_FORMATTER = proc do |options|
+      line = [options[:tag], options[:message]].compact.join(" ")
+      "#{line}\n"
+    end
+
+    # Initialize a new logger
+    #
+    # @param [::Logger] logger Logger instance to use
+    # @param [Proc] formatter Custom formatter for messages
+    # @param [Array, String, Symbol, nil] tag Tag to identify log messages
+    # @param [Symbol, nil] tag_color Color for the tag
+    # @param [Symbol, nil] message_color Color for the message
+    # @param [Boolean] colorize Force colorization even when not TTY
+    def initialize(
+      logger = ::Logger.new($stdout, level: ::Logger::INFO),
+      formatter: DEFAULT_FORMATTER,
+      tag: nil,
+      tag_color: nil,
+      message_color: nil,
+      colorize: false
+    )
+      @logger = logger.dup
+      @logger.formatter = proc { |*args| format_log(*args) }
+      @tag = Array(tag)
+      @formatter = formatter
+      @tag_color = tag_color
+      @message_color = message_color
+      @colorize = colorize || $stdout.tty?
+    end
+
+    # Create a new logger with additional tags
+    #
+    # @param [Array<Symbol, String>] tags Additional tags
+    # @yield [logger] Block to execute with the new logger
+    # @return [Logger] New instance with added tags
+    #
+    # @example With block
+    #   logger.tagged(:api) { |l| l.info("message") }
+    #
+    # @example Without block
+    #   api_logger = logger.tagged(:api)
+    #   api_logger.info("message")
+    def tagged(*tags)
+      new_logger = Logger.new(
+        @logger,
+        formatter: @formatter,
+        tag: @tag.dup.concat(tags),
+        tag_color: @tag_color,
+        message_color: @message_color,
+        colorize: @colorize
+      )
+
+      yield new_logger if block_given?
+
+      new_logger
+    end
+
+    # Define methods for each log level
+    # debug, info, warn, error, fatal
+    LEVELS.each_key do |level|
+      define_method(level) do |message = nil, &block|
+        return self if @logger.level > LEVELS[level]
+
+        message = block.call if block && !message
+        @logger.add(LEVELS[level], message)
+
+        self
+      end
+    end
+
+    private
+
+    # Format the log message
+    def format_log(_severity, _time, _progname, message)
+      tag = @tag.map { |t| "[#{t}]" }.join(" ")
+      tag = colorize_text(tag, @tag_color)
+      message = colorize_text(message, @message_color)
+
+      @formatter.call(message: message, tag: tag.empty? ? nil : tag)
+    end
+
+    def colorize_text(text, color)
+      return text.to_s unless @colorize
+      return text.to_s if color.nil?
+      text.to_s.colorize(color)
+    end
+  end
+end