lennarb 1.2.0 → 1.4.0

data/guides/getting-started/readme.md

@@ -0,0 +1,201 @@
+# 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'
+
+app = Lennarb.new do |app|
+  app.get '/' do |req, res|
+    res.status = 200
+    res.html('<h1>Welcome to Lennarb!</h1>')
+  end
+end
+
+app.initializer!
+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
+app = Lennarb.new do |l|
+  # Basic route
+  l.get '/' do |req, res|
+    res.html('Home page')
+  end
+
+  # Route with parameters
+  l.get '/users/:id' do |req, res|
+    user_id = req.params[:id]
+    res.json("{\"id\": #{user_id}}")
+  end
+end
+```
+
+### Route Parameters
+
+Parameters from dynamic route segments are available in `req.params`:
+
+```ruby
+app.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 Lifecycle
+
+### Initialization
+
+```ruby
+app = Lennarb.new do |l|
+  # Define routes and configuration
+end
+
+# Initialize and freeze the application
+app.initializer!
+```
+
+The `initializer!` method:
+
+- Loads environment-specific dependencies
+- Freezes the route tree
+- Freezes the Rack application
+
+### Environment
+
+Lennarb uses the `LENNA_ENV` environment variable (defaults to "development"):
+
+```bash
+LENNA_ENV=production rackup
+```
+
+## Error Handling
+
+Lennarb provides basic error handling:
+
+```ruby
+app.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 initializer!**
+
+   ```ruby
+   app = Lennarb.new { |l| ... }
+   app.initializer!
+   run app
+   ```
+
+2. **Set response status**
+
+   ```ruby
+   app.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
+
+app.get '/' do |req, res|
+ res.html 'Hello World'
+end
+```
+
+## Content Types
+
+Lenna supports the following content types:
+
+```ruby
+# app.rb
+
+app.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
+
+app.get '/' do |req, res|
+ res.write 'Hello World'
+end
+```
+
+JSON example:
+
+```ruby
+# app.rb
+
+app.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
+
+app.get '/' do |req, res|
+  # Stuff code here...
+ res.redirect '/hello'
+end
+```

data/lennarb.gemspec

@@ -0,0 +1,44 @@
+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_development_dependency "bundler"
+  spec.add_development_dependency "covered"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "minitest"
+  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"
+end

data/lib/lennarb/constansts.rb

@@ -0,0 +1 @@
+HTTP_METHODS = %i[GET POST PUT PATCH DELETE HEAD OPTIONS].freeze

data/lib/lennarb/request.rb

@@ -1,44 +1,86 @@
-# frozen_string_literal: true
+class Lennarb
+  class Request < Rack::Request
+    # The environment variables of the request
+    #
+    # @returns [Hash]
+    #
+    attr_reader :env
 
-# Released under the MIT License.
-# Copyright, 2023-2024, by Aristóteles Coutinho.
+    # Initialize the request object
+    #
+    # @parameter [Hash] env
+    # @parameter [Hash] route_params
+    #
+    # @returns [Request]
+    #
+    def initialize(env, route_params = {})
+      super(env)
+      @route_params = route_params
+    end
 
-class Lennarb
-	class Request < Rack::Request
-		# Initialize the request object
-		#
-		# @parameter [Hash] env
-		# @parameter [Hash] route_params
-		#
-		# @returns [Request]
-		#
-		def initialize(env, route_params = {})
-			super(env)
-			@route_params = route_params
-		end
-
-		# Get the request body
-		#
-		# @returns [String]
-    #
-		def params
-			@params ||= super.merge(@route_params)
-		end
-
-		# Read the body of the request
-		#
-		# @returns [String]
-		#
-		def body = @body ||= super.read
-
-		private
-
-		# Get the query string parameters
-		#
-		# @returns [String]
-		#
-		def query_params
-			@query_params ||= Rack::Utils.parse_nested_query(query_string)
-		end
-	end
+    # Get the request body
+    #
+    # @returns [String]
+    #
+    def params = @params ||= super.merge(@route_params)&.transform_keys(&:to_sym)
+
+    # Get the request path
+    #
+    # @returns [String]
+    #
+    def path = @path ||= super.split("?").first
+
+    # Read the body of the request
+    #
+    # @returns [String]
+    #
+    def body = @body ||= super.read
+
+    # Get the query parameters
+    #
+    # @returns [Hash]
+    #
+    def query_params
+      @query_params ||= Rack::Utils.parse_nested_query(query_string).transform_keys(&:to_sym)
+    end
+
+    # Get the headers of the request
+    #
+    def headers
+      @headers ||= env.select { |key, _| key.start_with?("HTTP_") }
+    end
+
+    def ip = ip_address
+
+    def secure? = scheme == "https"
+
+    def user_agent = headers["HTTP_USER_AGENT"]
+
+    def accept = headers["HTTP_ACCEPT"]
+
+    def referer = headers["HTTP_REFERER"]
+
+    def host = headers["HTTP_HOST"]
+
+    def content_length = headers["HTTP_CONTENT_LENGTH"]
+
+    def content_type = headers["HTTP_CONTENT_TYPE"]
+
+    def xhr? = headers["HTTP_X_REQUESTED_WITH"]&.casecmp("XMLHttpRequest")&.zero?
+
+    def []=(key, value)
+      env[key] = value
+    end
+
+    def [](key)
+      env[key]
+    end
+
+    private
+
+    def ip_address
+      forwarded_for = headers["HTTP_X_FORWARDED_FOR"]
+      forwarded_for ? forwarded_for.split(",").first.strip : env["REMOTE_ADDR"]
+    end
+  end
 end