lennarb 1.3.0 → 1.4.1

data/guides/getting-started/readme.md

@@ -0,0 +1,215 @@
+# Getting Started with Lennarb
+
+## Overview
+
+Lennarb is a minimalist, thread-safe Rack-based web framework for Ruby that focuses on simplicity and performance. It provides a clean routing DSL and straightforward request/response handling.
+
+## Installation
+
+Add Lennarb to your project's Gemfile:
+
+```ruby
+gem 'lennarb'
+```
+
+Or install it directly via RubyGems:
+
+```bash
+gem install lennarb
+```
+
+## Quick Start
+
+### Basic Application
+
+Create a new file named `config.ru`:
+
+```ruby
+require 'lennarb'
+
+MyApp = Lennarb::App.new do
+  routes
+    get '/' do |req, res|
+      res.status = 200
+      res.html('<h1>Welcome to Lennarb!</h1>')
+    end
+  end
+end
+
+MyApp.initialize!
+run App
+```
+
+Start the server:
+
+```bash
+rackup
+```
+
+Your application will be available at `http://localhost:9292`.
+
+## Core Concepts
+
+### Request Handling
+
+Each route handler receives two arguments:
+
+- `req`: A Request object wrapping the Rack environment
+- `res`: A Response object for building the HTTP response
+
+### Response Types
+
+Lennarb provides three main response helpers:
+
+```rb
+app.get '/text' do |req, res|
+  res.text('Plain text response')
+end
+
+app.get '/html' do |req, res|
+  res.html('<h1>HTML response</h1>')
+end
+
+app.get '/json' do |req, res|
+  res.json('{"message": "JSON response"}')
+end
+```
+
+### Redirects
+
+```ruby
+app.get '/redirect' do |req, res|
+  res.redirect('/new-location', 302) # 302
+end
+```
+
+Routes are defined using HTTP method helpers:
+
+```ruby
+Lennarb::App.new do
+  routes do
+    get '/' do |req, res|
+      res.html('Home page')
+    end
+
+    get '/users/:id' do |req, res|
+      user_id = req.params[:id]
+      res.json("{\"id\": #{user_id}}")
+    end
+  end
+end
+```
+
+### Route Parameters
+
+Parameters from dynamic route segments are available in `req.params`:
+
+```ruby
+get '/hello/:name' do |req, res|
+  name = req.params[:name]
+  res.text("Hello, #{name}!")
+end
+```
+
+## Thread Safety
+
+Lennarb is thread-safe by design:
+
+- All request processing is synchronized using a mutex
+- The router tree is frozen after initialization
+- Response objects are created per-request
+
+## Application Life-cycle
+
+### Initialization
+
+```ruby
+Myapp = Lennarb::App.new do
+  # Define routes
+  routes do
+  end
+
+  # Define Configurations
+  config do
+  end
+end
+
+# Initialize and freeze the application
+MyApp.initialize!
+```
+
+The `initialize!` method:
+
+- Loads environment-specific dependencies
+- Freezes the route tree
+- Freezes the Rack application
+
+### Environment
+
+Lennarb uses the `LENNA_ENV` environment variable (defaults to "development"):
+
+It can be set using the following environment variables:
+
+- `LENNA_ENV`
+- `APP_ENV`
+- `RACK_ENV`
+
+```bash
+LENNA_ENV=production rackup
+```
+
+## Error Handling
+
+Lennarb provides basic error handling:
+
+```ruby
+get '/api' do |req, res|
+  # Errors are caught and return 500 with error message
+  raise "Something went wrong"
+end
+```
+
+Default error responses:
+
+- 404 for unmatched routes
+- 500 for application errors
+
+## Best Practices
+
+1. **Always call initialize!**
+
+   ```ruby
+   app = Lennarb::App.new
+   app.initialize!
+   run app
+   ```
+
+2. **Set response status**
+
+   ```ruby
+   get '/api' do |req, res|
+     res.status = 200
+     res.json('{"status": "ok"}')
+   end
+   ```
+
+3. **Use appropriate response types**
+
+   ```ruby
+   # HTML for web pages
+   res.html('<h1>Web Page</h1>')
+
+   # JSON for APIs
+   res.json('{"data": "value"}')
+
+   # Text for simple responses
+   res.text('Hello')
+   ```
+
+## Support
+
+For help and bug reports, please visit:
+
+- GitHub Issues: [lennarb/issues](https://github.com/aristotelesbr/lennarb/issues)
+
+Now you can run your app!

data/guides/links.yaml

@@ -0,0 +1,6 @@
+getting-started:
+  order: 1
+performance:
+  order: 2
+response:
+  order: 3

data/guides/performance/readme.md

@@ -0,0 +1,120 @@
+# Performance
+
+The **Lennarb** is very fast. The following benchmarks were performed on a MacBook Pro (Retina, 13-inch, Early 2013) with 2,7 GHz Intel Core i7 and 8 GB 1867 MHz DDR3. Based on [jeremyevans/r10k](https://github.com/jeremyevans/r10k) using the following. All tests are performed using the **Ruby 3.3.0**
+
+## Benchmark results
+
+This document contains the benchmarks comparing **Lennarb** with other routers based on Rack. Metrics evaluated include Requests per Second, Initial memory usage and Startup time.
+
+### 1. Requests per Second (RPS)
+
+![RPS](https://raw.githubusercontent.com/aristotelesbr/lennarb/main/benchmark/rps.png)
+
+| Position | Application | 10 RPS     | 100 RPS    | 1.000 RPS | 10.000 RPS |
+| -------- | ----------- | ---------- | ---------- | --------- | ---------- |
+| 1        | Lenna       | 126.252,36 | 108.086,55 | 87.111,91 | 68.460,64  |
+| 2        | Roda        | 123.360,37 | 88.380,56  | 66.990,77 | 48.108,29  |
+| 3        | Syro        | 114.105,38 | 80.909,39  | 61.415,86 | 46.639,81  |
+| 4        | Hanami-API  | 68.089,18  | 52.851,88  | 40.801,78 | 27.996,00  |
+
+This table ranks the routers by the number of requests they can process per second. Higher numbers indicate better performance.
+
+### 2. Initial memory usage (in KB)
+
+![Memory](https://raw.githubusercontent.com/aristotelesbr/lennarb/main/benchmark/memory.png)
+
+| Position | Application | 10 KB  | 100 KB | 1.000 KB | 10.000 KB |
+| -------- | ----------- | ------ | ------ | -------- | --------- |
+| 1        | Syro        | 12,160 | 12,544 | 16,460   | 49,692    |
+| 2        | Lenna       | 14,464 | 14,720 | 18,232   | 56,812    |
+| 3        | Roda        | 15,104 | 15,104 | 18,220   | 49,900    |
+| 4        | Hanami-API  | 15,744 | 16,128 | 20,888   | 64,824    |
+
+This table shows the initial memory usage in KB. Lower values indicate lower memory consumption.
+
+### 3. Startup time (in seconds)
+
+![Startup](https://raw.githubusercontent.com/aristotelesbr/lennarb/main/benchmark/runtime_with_startup.png)
+
+| Position | Application | 10 seg | 100 seg | 1.000 seg | 10.000 seg |
+| -------- | ----------- | ------ | ------- | --------- | ---------- |
+| 1        | Syro        | 0.274  | 0.347   | 0.455     | 0.997      |
+| 2        | Lenna       | 0.289  | 0.312   | 0.393     | 0.914      |
+| 3        | Roda        | 0.294  | 0.378   | 0.467     | 0.918      |
+| 4        | Hanami-API  | 0.445  | 0.550   | 0.808     | 3.074      |
+
+This table shows the startup time in seconds. Lower values indicate faster startup times.
+
+## Graphs
+
+See the graphs in the `benchmarks` directory of the lennarb project.
+
+## Steps to run the benchmarks
+
+### 1. Install the router gem you want to test
+
+```bash
+gem install lennarb
+gem install syro
+gem install roda
+```
+
+### 2. Clone the jeremyevans/r10k repository
+
+```bash
+git clone https://github.com/jeremyevans/r10k
+```
+
+### 3. Create a new file in the `r10k` directory
+
+In the `r10k` directory, create a new file called `lennarb.rb` into `builders` directory with the code below:
+
+```bash
+touch r10k/builders/lennarb.rb
+```
+
+Put the code below into `lennarb.rb` file:
+
+```rb
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2024, by Aristóteles Coutinho.
+
+lennarb_routes =
+  lambda do |f, level, prefix, calc_path, lvars|
+    base = BASE_ROUTE.dup
+    ROUTES_PER_LEVEL.times do
+      route = "#{prefix}#{base}"
+      if level == 1
+        params = lvars.map { |lvar| "\#{req.params[:#{lvar}]}" }
+.join('-')
+        f.puts "  app.get '#{route}/:#{lvars.last}' do |req, res|"
+        f.puts "    body = \"#{calc_path[1..]}#{base}-#{params}\""
+        f.puts '    res.html body'
+        f.puts '  end'
+      else
+       lennarb_routes.call(f, level - 1, "#{route}/:#{lvars.last}/", "#{calc_path}#{base}/", lvars + [lvars.last.succ])
+      end
+      base.succ!
+    end
+  end
+
+File.open("#{File.dirname(__FILE__)}/../apps/lennarb_#{LEVELS}_#{ROUTES_PER_LEVEL}.rb", 'wb') do |f|
+  f.puts '# frozen_string_literal: true'
+  f.puts "require 'lennarb'"
+  f.puts 'app = Lennarb.new'
+  lennarb_routes.call(f, LEVELS, '/', '/', ['a'])
+  f.puts 'App = app'
+end
+```
+
+### 4. Run the benchmarks
+
+```bash
+bundle exec rake bench graphs R10K_APPS="lennarb syro roda"
+```
+
+## Conclusion
+
+These numbers are just a small reference, **Lennarb** is not a framework, it is a router. In my opinion, **Roda** is the best router for Ruby because it has many interesting features, such as a middleware manager, and very good development performance.

data/guides/response/readme.md

@@ -0,0 +1,83 @@
+# Response
+
+This is the response guide.
+The `res` object is used to send a response to the client. The Lennarb use a custom response object to send responses to the client. The `res` object is an instance of {Lennarb::Response}.
+
+## Usage
+
+You can use the `res` object to send a response to the client.
+
+```ruby
+# app.rb
+
+get '/' do |req, res|
+ res.html 'Hello World'
+end
+```
+
+## Content Types
+
+Lennarb supports the following content types:
+
+```ruby
+# app.rb
+
+get '/' do |req, res|
+ res.html 'Hello World'
+ res.json '{"message": "Hello World"}'
+ res.text 'Hello World'
+end
+```
+
+But you can also set your own content type:
+
+```ruby
+res['content-type'] = 'text/markdown'
+res.write '# Hello World'
+```
+
+## The write method
+
+You can use the `res.write` method to write to the response body:
+
+```ruby
+# app.rb
+
+get '/' do |req, res|
+ res.write 'Hello World'
+end
+```
+
+JSON example:
+
+```ruby
+# app.rb
+
+post '/posts' do |req, res|
+ req.params # => { name: 'Lenna' }
+ name = req.params[:name]
+
+ res.write({ data: { name: } }.to_json) # This will write to the response body
+end
+```
+
+## Status Codes
+
+You can set the status code using the `res.status` method:
+
+```ruby
+res.status 200
+```
+
+## Redirects
+
+You can redirect the client using the `res.redirect` method:
+
+```ruby
+# app.ruby
+
+get '/' do |req, res|
+  # Stuff code here...
+ res.redirect '/hello'
+end
+```

data/lennarb.gemspec

@@ -0,0 +1,47 @@
+require_relative "lib/lennarb/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "lennarb"
+  spec.version = Lennarb::VERSION
+
+  spec.summary = <<~DESC
+    Lennarb provides a lightweight yet robust solution for web routing in Ruby, focusing on performance and simplicity.
+  DESC
+  spec.authors = ["Aristóteles Coutinho"]
+  spec.license = "MIT"
+  spec.homepage = "https://aristotelesbr.github.io/lennarb"
+  spec.metadata = {
+    "allowed_push_host" => "https://rubygems.org",
+    "changelog_uri" => "https://github.com/aristotelesbr/lennarb/blob/master/changelog.md",
+    "homepage_uri" => "https://aristotelesbr.github.io/lennarb",
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => "https://github.com/aristotelesbr/lennarb"
+  }
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`
+      .split("\x0")
+      .reject { |f| f.match(%r{^(test|features)/}) }
+  end
+
+  spec.bindir = "exe"
+  spec.executables = ["lenna"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "bigdecimal"
+  spec.add_dependency "colorize", "~> 1.1"
+  spec.add_dependency "rack", "~> 3.1"
+  spec.add_dependency "superconfig"
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "covered"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "minitest-utils"
+  spec.add_development_dependency "rack-test"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "standard"
+  spec.add_development_dependency "standard-custom"
+  spec.add_development_dependency "standard-performance"
+  spec.add_development_dependency "m"
+  spec.add_development_dependency "debug"
+end

data/lib/lennarb/app.rb

@@ -0,0 +1,172 @@
+module Lennarb
+  class App
+    # This error is raised whenever the app is initialized more than once.
+    AlreadyInitializedError = Class.new(StandardError)
+
+    # The root app directory of the app.
+    #
+    # @returns [Pathname]
+    #
+    attr_accessor :root
+
+    # The current environment. Defaults to "development".
+    # It can be set using the following environment variables:
+    #
+    # - `LENNA_ENV`
+    # - `APP_ENV`
+    # - `RACK_ENV`
+    #
+    # @returns [Lennarb::Environment]
+    #
+    attr_reader :env
+
+    def initialize(&)
+      @initialized = false
+      self.root = Pathname.pwd
+      self.env = compute_env
+      instance_eval(&) if block_given?
+    end
+
+    # Set the current environment. See {Lennarb::Environment} for more details.
+    #
+    # @parameter [Hash] env
+    #
+    def env=(env)
+      raise AlreadyInitializedError if initialized?
+
+      @env = Environment.new(env)
+    end
+
+    # Mount an app at a specific path.
+    #
+    # @parameter [Object] The controller|app to mount.
+    #
+    # @returns [void]
+    #
+    # @example
+    #
+    #   class PostController
+    #     extend Lennarb::Routes::Mixin
+    #
+    #     get "/post/:id" do |req, res|
+    #       res.text("Post ##{req.params[:id]}")
+    #     end
+    #   end
+    #
+    #  MyApp = Lennarb::App.new do
+    #    routes do
+    #      mount PostController
+    #    end
+    #
+    def mount(*controllers)
+      controllers.each do |controller|
+        raise ArgumentError, "Controller must respond to :routes" unless controller.respond_to?(:routes)
+
+        self.controllers << controller
+      end
+    end
+
+    # Define the app's configuration. See {Lennarb::Config}.
+    #
+    # @returns [Lennarb::Config]
+    #
+    # @example Run config on every environment
+    #   app.config do
+    #     mandatory :database_url, string
+    #   end
+    #
+    # @example Run config on every a specific environment
+    #   app.config :development do
+    #     set :domain, "example.dev"
+    #   end
+    #
+    # @example Run config on every a specific environment
+    #   app.config :development, :test do
+    #     set :domain, "example.dev"
+    #   end
+    #
+    def config(*envs, &)
+      @config ||= Config.new
+
+      write = block_given? &&
+        (envs.map(&:to_sym).include?(env.to_sym) || envs.empty?)
+
+      @config.instance_eval(&) if write
+
+      @config
+    end
+
+    # Define the app's route. See {Lennarb::RouteNode} for more details.
+    #
+    # @returns [Lennarb::RouteNode]
+    #
+    def routes(&)
+      @routes ||= Routes.new
+      @routes.instance_eval(&) if block_given?
+      @routes
+    end
+
+    # The Rack app.
+    #
+    def app
+      @app ||= begin
+        request_handler = RequestHandler.new(self)
+
+        Rack::Builder.app do
+          run request_handler
+        end
+      end
+    end
+
+    # Store mounted app's
+    #
+    def controllers
+      @controllers ||= []
+    end
+    alias_method :mounted_apps, :controllers
+
+    # Check if the app is initialized.
+    #
+    # @returns [Boolean]
+    #
+    def initialized? = @initialized
+
+    # Initialize the app.
+    #
+    # @returns [void]
+    #
+    def initialize!
+      raise AlreadyInitializedError if initialized?
+
+      controllers.each do
+        routes.store.merge!(it.routes.store)
+      end
+
+      @initialized = true
+
+      app.freeze
+      routes.freeze
+    end
+
+    # Call the app.
+    #
+    # @parameter [Hash] env
+    #
+    def call(env)
+      env[RACK_LENNA_APP] = self
+      Dir.chdir(root) { return app.call(env) }
+    end
+
+    # Compute the current environment.
+    #
+    # @returns [String]
+    #
+    # @private
+    #
+    private def compute_env
+      env = ENV_NAMES.map { ENV[_1] }.compact.first.to_s
+
+      env.empty? ? "development" : env
+    end
+  end
+end

data/lib/lennarb/config.rb

@@ -0,0 +1,34 @@
+module Lennarb
+  # The configuration for the application.
+  # It uses {https://rubygems.org/gems/superconfig SuperConfig} to define the
+  # configuration.
+  class Config < SuperConfig::Base
+    MissingEnvironmentVariable = Class.new(StandardError)
+    MissingCallable = Class.new(StandardError)
+
+    undef_method :credential
+
+    def initialize(**)
+      block = proc { true }
+      super(**, &block)
+    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
+  end
+end

data/lib/lennarb/constansts.rb

@@ -0,0 +1,6 @@
+module Lennarb
+  RACK_LENNA_APP = "lennarb.app"
+  ENV_NAMES = %w[LENNA_ENV APP_ENV RACK_ENV]
+  HTTP_METHODS = %i[GET POST PUT PATCH DELETE HEAD OPTIONS]
+  CONTENT_TYPE = {HTML: "text/html", TEXT: "text/plain", JSON: "application/json"}
+end