lennarb 1.5.0 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b091cfa5731b3dc0b46ecfa6712b9e3ceeae0eedcce9bc97133683162e12ce28
-  data.tar.gz: 49a8957ed5b951e9e9b7d728fb72c9675e1c6d5eb22a897f2d305e106f02dd98
+  metadata.gz: 0b33c13f9c42ddb2d9593374c25fd6efca486c37b8cba0699031e01c61b2f408
+  data.tar.gz: 9e995281d4c034b933d62fc24e480ea160ee485b566f3bde0c648272d25ece5d
 SHA512:
-  metadata.gz: f494fd50eefbe648c73be463054f14995af8d771d593571ca3908aaa8341502433e925d6df74e99c8427a1cad5473a28495d10e45fe4e54e18a10efd1b22edd9
-  data.tar.gz: 4e858da099b1bdb88ad3593aa8354da285a4e33b4c59545dfb394ea84c6623f4d163c5500143fb86accb76356a1c35b67e9972d0a2667fd925dd79b6852e963c
+  metadata.gz: 95b23a6fa14cf0f55ccd91f75c2c094b97c9929652c099cb347a8996ba30b90cbc9da0d074707af14f7bec57d9c1420f8ed0256e3dcbaa1fee7984ed8ea2f268
+  data.tar.gz: ebb7666065e53c69dee117bb9167f22bf0de2e79ea06a4018240ca991edf1c38ff582921c09d523df48c790e75e543aa3d62e64bcaac8225a1660f24d58dd467

data/.gitignore

@@ -18,4 +18,4 @@ coverage/
 tmp/
 !tmp/.keep
 .yardo/
-minitestfailures
+.minitestfailures

data/README.pt-BR.md

@@ -33,14 +33,14 @@ Um framework web leve, rápido e modular para Ruby baseado em Rack. **Lennarb**
 - Opções de configuração flexíveis
 - Duas opções de implementação:
   - `Lennarb::App`: Abordagem minimalista para controle completo
-  - `Lennarb::Application`: Versão estendida com componentes comuns
+  - `Lennarb::Base`: Versão estendida, para montar várias aplicações
 
 ## Opções de Implementação
 
 Lennarb oferece duas abordagens de implementação para atender diferentes necessidades:
 
 - **Lennarb::App**: Abordagem minimalista para controle completo
-- **Lennarb::Application**: Versão estendida com componentes comuns
+- **Lennarb::Base**: Versão estendida, para montar várias aplicações
 
 Consulte a [documentação](https://aristotelesbr.github.io/lennarb/guides/getting-started/index) para detalhes sobre cada implementação.
 
@@ -63,26 +63,17 @@ gem install lennarb
 ```ruby
 require "lennarb"
 
-app = Lennarb::App.new do
-  configure do
-    mandary :database_url, string
-    optional :port, integer, 9292
-    optional :env, string, "development"
+class App < Lennarb::App
+  config do
+    mandatory :database_url, string
+    optional :port, int, 9292
   end
 
-  routes do
-    get("/") do |req, res|
-      res.html("<h1>Bem-vindo ao Lennarb!</h1>")
-    end
-
-    get("/hello/:name") do |req, res|
-      name = req.params[:name]
-      res.html("Olá, #{name}!")
-    end
-  end
+  get("/")            { |req, res| res.html("<h1>Bem-vindo ao Lennarb!</h1>") }
+  get("/hello/:name") { |req, res| res.html("Olá, #{req.params[:name]}!") }
 end
 
-app.initialize!
+run App.new.initialize!
 run app  # Em config.ru
 ```
 

data/benchmark/hot_path.rb

@@ -0,0 +1,62 @@
+# Measures the per-request cost of the Lennarb request path.
+#
+# Run with:  bundle exec ruby benchmark/hot_path.rb
+#
+# Reports requests per second and objects allocated per request for a static
+# and a dynamic route, plus the isolated cost of route matching and context
+# creation, so a regression can be attributed rather than guessed at.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "lennarb"
+require "benchmark"
+require "stringio"
+
+class BenchApp < Lennarb::App
+  get("/") { |req, res| res.text("ok") }
+  get("/users/:id/posts/:post_id") { |req, res| res.text(req.params[:id]) }
+end
+
+def rack_env(path)
+  {
+    "REQUEST_METHOD" => "GET",
+    "PATH_INFO" => path,
+    "QUERY_STRING" => "",
+    "SERVER_NAME" => "example.org",
+    "SERVER_PORT" => "80",
+    "rack.url_scheme" => "http",
+    "rack.input" => StringIO.new
+  }
+end
+
+def measure(label, iterations)
+  elapsed = Benchmark.realtime { iterations.times { yield } }
+  puts format("%-22s %9d req/s  %6.2f us/req", label, iterations / elapsed, elapsed / iterations * 1e6)
+end
+
+def allocations(iterations)
+  GC.start
+  before = GC.stat(:total_allocated_objects)
+  iterations.times { yield }
+  (GC.stat(:total_allocated_objects) - before) / iterations.to_f
+end
+
+app = BenchApp.new.initialize!
+handler = Lennarb::RequestHandler.new(app)
+
+ITERATIONS = 100_000
+static = rack_env("/")
+dynamic = rack_env("/users/42/posts/7")
+
+2_000.times { handler.call(static.dup) }
+
+puts "ruby #{RUBY_VERSION} (#{RUBY_PLATFORM}), lennarb #{Lennarb::VERSION}"
+puts
+
+measure("static route", ITERATIONS) { handler.call(static.dup) }
+measure("dynamic route", ITERATIONS) { handler.call(dynamic.dup) }
+measure("match_route only", ITERATIONS) { app.routes.match_route(["users", "42", "posts", "7"], :GET) }
+measure("create_context only", ITERATIONS) { handler.send(:create_context) }
+
+puts
+puts format("objects per request     %6.1f", allocations(10_000) { handler.call(dynamic.dup) })

data/changelog.md

@@ -7,11 +7,146 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.1] - 2026-09-09
+
+A patch release. No public API was added; everything here is a defect fix.
+
+### Fixed
+
+- `Lennarb::Request#content_type` and `#content_length` now read the Rack
+  `CONTENT_TYPE` and `CONTENT_LENGTH` headers instead of the `HTTP_`-prefixed
+  names. `Request#json?` was never true and `#json_body` never parsed on a real
+  HTTP request.
+- Exceptions raised inside a route handler no longer escape to Rack. They are
+  logged and answered with a 500, except in development, where they are
+  re-raised so `Rack::ShowExceptions` can render the backtrace.
+- `app` inside a route handler no longer raises `SystemStackError`. The context
+  object defined `app` with a block whose `self` was rebound to the context, so
+  the call recursed into itself. Nothing had exercised it.
+- `App#initialize!` no longer freezes the class-level routes. Each booted
+  instance holds its own deep, frozen snapshot, so registering a route after the
+  first boot works again -- it previously raised `RoutesFrozenError` and broke
+  test suites and development reload.
+- `Routes#freeze` now freezes the whole route tree rather than only its root.
+- Environment-scoped configuration at the class level -- `config(:production) do
+  ... end` inside a `Lennarb::App` subclass -- no longer raises `NameError`. The
+  class-level `config` referenced an `env` that only exists on instances, so only
+  the unscoped form worked. The instance and `Lennarb::Base` forms were
+  unaffected.
+- The test suite runs green again. minitest 6 extracted `Minitest::Mock` and
+  `Object#stub` into the separate `minitest-mock` gem, which is now a
+  development dependency. Both are pinned to their major, so a future major
+  bump has to be a deliberate change rather than the result of a fresh resolve.
+- Tests no longer leak `LENNA_ENV`/`APP_ENV`/`RACK_ENV` between each other,
+  which made results depend on minitest's random seed.
+- `Request#host` no longer shadows `Rack::Request#host` with a worse version. It
+  returned the raw `Host` header, so it kept the port (`example.com:3000`) and
+  returned `nil` when there was no `Host` header instead of falling back to
+  `SERVER_NAME`. The override is removed and Rack's implementation applies.
+- `Lennarb::Environment` equality is fixed in three ways. Two environments with
+  the same name were not `==` to each other; `equal?` was aliased to `==`, which
+  broke Ruby's object-identity contract in both directions (`env.equal?(env)` was
+  false and `env.equal?(:test)` was true); and `eql?` was inconsistent with
+  `hash`, so an environment did not work as a Hash key. `equal?` is no longer
+  overridden, and `eql?`/`hash` are now consistent.
+- 22 YARD `@retrn` typos corrected to `@return` in `route_node.rb`,
+  `middleware_stack.rb`, `environment.rb` and `response.rb`. The tag was not
+  recognised, so those return types were missing from the published
+  documentation.
+- The comments on `DuplicateRouteError`, `MissingEnvironmentVariable`,
+  `MissingCallable` and `RoutesFrozenError` all claimed the error was raised
+  when the app is initialized more than once. Each now describes what it is.
+- **Route parameters are now URL-decoded.** `/u/John%20Doe` used to yield
+  `"John%20Doe"`; it now yields `"John Doe"`, and a percent-encoded slash stays
+  inside its segment instead of splitting the path. **If your application worked
+  around this by decoding route parameters itself, remove that workaround or you
+  will decode twice.** Segments are decoded with `Rack::Utils.unescape_path`, so
+  `+` is left alone, as it should be in a path.
+- `.gitignore` now matches `.minitestfailures`.
+
+### Security
+
+- **`ParameterFilter` matching is now case-insensitive.** It was built with a
+  case-sensitive `Regexp.union`, and `RequestLogger` is in the default
+  middleware stack in every environment and logs `request.params` at `info`. A
+  form field named `Password`, `Token` or `API_KEY` was written to the log in
+  cleartext, and from there to journald, CloudWatch or Datadog.
+- **`Regexp` filters passed to `ParameterFilter` now work.** The docstring
+  documented them, but `filters.map(&:to_s)` stringified them and
+  `Regexp.union` escaped the result, so the filter matched only the literal text
+  `(?i-mx:password)`. Passing a Regexp to harden filtering disabled it entirely,
+  including for keys that had previously been filtered.
+- **The default filter list now covers** `auth`, `credit`, `card_number`, `cvn`,
+  `iban`, `api`, `pin` and `session_id`. Previously `cvv` was filtered while
+  `card_number` was not, protecting the CVV and not the card number it guards.
+- **`ParameterFilter#filter` no longer modifies the parameters it is given.**
+  `params.dup` is shallow and nested values were assigned in place, so an app
+  calling `filter(req.params)` for an error report found its own params replaced
+  by `"[FILTERED]"`.
+- **`RequestLogger` now uses the logger configured on the app handling the
+  request**, resolved from the Rack env. It read `Lennarb::App.app.config.logger`,
+  and `App.app` is never assigned anywhere, so a configured logger was
+  unreachable and request lines always went to the process's stderr. Configuring
+  a redacting or file-scoped logger was therefore not an available mitigation.
+- **The request path is escaped before being logged.** Control characters from
+  the client could otherwise forge log lines. Parameter values were already safe
+  because they go through `inspect`.
+- **Booting without `LENNA_ENV`, `APP_ENV` or `RACK_ENV` now logs a warning.**
+  The environment defaults to `development`, which enables
+  `Rack::ShowExceptions`; a deployment that forgot to export the variable served
+  the entire Rack environment, `Authorization` and `Cookie` included, to anyone
+  who could trigger a 500. Changing the default itself is a breaking change and
+  is deferred to 1.6.0.
+- **`Response#json` no longer echoes the exception message to the client**, which
+  could carry `inspect` output of the object being serialized, and now rescues
+  `JSON::JSONError` rather than `JSON::GeneratorError`: a circular or over-deep
+  object graph raises `JSON::NestingError`, which descends from `ParserError` and
+  escaped the rescue entirely.
+
+### Changed
+
+- `RequestHandler` compiles the route execution context once per application
+  class instead of building an object with a fresh singleton class on every
+  request. On ruby 3.4.1 (arm64-darwin23): static route 424,302 to 753,914
+  req/s, dynamic route 175,364 to 221,795 req/s, `create_context` 1.37us to
+  0.15us (24% to 3.3% of a request), 48 to 40 objects allocated per request.
+  The extra object over the 39 measured mid-release is the cost of decoding
+  route parameters, below.
+- `App#routes` returns the instance's frozen snapshot after `initialize!`, so
+  `app.routes.equal?(App.routes)` is no longer true once the app is booted.
+- Documentation now teaches subclassing `Lennarb::App` as the canonical form.
+  The previous quick start raised `NoMethodError`, and subclassing is the only
+  form isolated per application. The pt-BR quick start also called `configure`
+  (the method is `config`) and `mandary` (a typo for `mandatory`).
+- Changelog no longer references `Lennarb::Application` or
+  `Lennarb::Routes::Mixin`, neither of which exists. The real APIs are
+  `Lennarb::Base` and `Lennarb::Base.mount`.
+
 ### Added
 
-- Add `Lennarb::Application` class to be the base class of the "standard" implementation of the Lennarb framework.
+- `benchmark/hot_path.rb`, so the performance claims can be reproduced.
+- `required_ruby_version = ">= 3.4"` in the gemspec. The code uses `it`, the
+  implicit block parameter introduced in Ruby 3.4, and the README has always
+  promised 3.4+, but no version constraint was declared. RubyGems would install
+  the gem on an older Ruby and the first `require` failed with a `SyntaxError`
+  rather than a clear resolution error. This has been missing since 0.1.0.
+
+### Known limitations
+
+- Two applications created with `Lennarb::App.new` without subclassing still
+  share the class's route definitions. Subclass to isolate them.
+- Hooks and helpers are still stored per app class and are shared the same way.
+  Tracked in [#87](https://github.com/aristotelesbr/lennarb/issues/87); they are
+  meant to become an opt-in mechanism rather than machinery every application
+  carries.
+
+## [1.5.0] - 2025-04-19
+
+### Added
+
+- Add `Lennarb::Base` class to be the base class of the "standard" implementation of the Lennarb framework, for mounting several applications behind one middleware stack.
 - Add middleware support to Lennarb::App class.
-- Add `middleware` support to the `Lennarb::Application` with default middlewares.
+- Add `middleware` support to `Lennarb::Base` with default middlewares.
 - Add files to centralize the errors of the project.
 - Add CODE_OF_CONDUCT.md in English and Portuguese
 - Add CONTRIBUTING.md in English and Portuguese
@@ -52,20 +187,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add support to mount routes. Now, you can centralize the routes in a single file and mount them in the main application. Ex.
 
 ```rb
-class PostsController
-  extend Lennarb::Routes::Mixin
-
+class Posts < Lennarb::App
   get '/posts' do |req, res|
     res.html('Posts')
   end
 end
 
-SampleApp = Lennarb.new do |router|
-  mount PostsController
+class Application < Lennarb::Base
+  mount Posts, at: '/'
 end
 ```
 
-The `mount` method will add the routes from the `PostsController` class to the main application. You can use the `mount` method with multiple classes, ex. `mount PostsController, CommentsController`.
+`Lennarb::Base.mount` registers a `Lennarb::App` subclass at a path, behind the
+base application's middleware stack. Call it once per application you want to
+mount.
 
 - Add `Lennarb::Environment` module to manage the environment variables in the project. Now, the `Lennarb` class is the main class of the project.
 - Add `Lennarb::Config` module to manage the configuration in the project. Now, the `Lennarb` class is the main class of the project.

data/guides/getting-started/readme.md

@@ -27,17 +27,14 @@ Create a new file named `config.ru`:
 ```ruby
 require 'lennarb'
 
-MyApp = Lennarb::App.new do
-  routes do
-    get '/' do |req, res|
-      res.status = 200
-      res.html('<h1>Welcome to Lennarb!</h1>')
-    end
+class MyApp < Lennarb::App
+  get '/' do |req, res|
+    res.status = 200
+    res.html('<h1>Welcome to Lennarb!</h1>')
   end
 end
 
-MyApp.initialize!
-run MyApp
+run MyApp.new.initialize!
 ```
 
 Start the server:
@@ -86,16 +83,13 @@ 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
+class MyApp < Lennarb::App
+  get '/' do |req, res|
+    res.html('Home page')
+  end
+
+  get '/users/:id' do |req, res|
+    res.json({id: req.params[:id]})
   end
 end
 ```
@@ -124,18 +118,19 @@ Lennarb is thread-safe by design:
 ### Initialization
 
 ```ruby
-MyApp = Lennarb::App.new do
-  # Define routes
-  routes do
+class MyApp < Lennarb::App
+  # Define configuration
+  config do
   end
 
-  # Define Configurations
-  config do
+  # Define routes
+  get '/' do |req, res|
+    res.text('ok')
   end
 end
 
-# Initialize and freeze the application
-MyApp.initialize!
+# Boot the application: it snapshots and freezes its routes
+MyApp.new.initialize!
 ```
 
 The `initialize!` method:

data/guides/performance/readme.md

@@ -1,5 +1,9 @@
 # Performance
 
+> The comparison tables below were produced in 2024 on a 2013 MacBook Pro with
+> Ruby 3.3.0. They are kept for historical reference. To measure the current
+> request path on your own machine, run `bundle exec ruby benchmark/hot_path.rb`.
+
 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

data/lennarb.gemspec

@@ -24,6 +24,11 @@ Gem::Specification.new do |spec|
       .reject { |f| f.match(%r{^(test|features)/}) }
   end
 
+  # lib/lennarb/routes.rb uses `it`, the implicit block parameter, which is
+  # Ruby 3.4+. Without this, RubyGems installs happily on an older Ruby and the
+  # first require fails with a SyntaxError instead of a clear resolution error.
+  spec.required_ruby_version = ">= 3.4"
+
   spec.bindir = "exe"
   spec.executables = ["lenna"]
   spec.require_paths = ["lib"]
@@ -36,7 +41,12 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "simplecov"
   spec.add_development_dependency "simplecov-json"
-  spec.add_development_dependency "minitest"
+  # Pinned to the major: minitest 6 removed Minitest::Mock and Object#stub, which
+  # silently broke CI for five months because nothing pins and gems.locked is
+  # gitignored. A major bump must be a deliberate change, not a fresh resolve.
+  spec.add_development_dependency "minitest", "~> 6.0"
+  # minitest 6 extracted Minitest::Mock and Object#stub into their own gem.
+  spec.add_development_dependency "minitest-mock", "~> 5.27"
   spec.add_development_dependency "minitest-utils"
   spec.add_development_dependency "rack-test"
   spec.add_development_dependency "rake"

data/lib/lennarb/app.rb

@@ -75,12 +75,24 @@ module Lennarb
         @config ||= Config.new(self)
 
         if block_given?
-          write = envs.empty? || envs.map(&:to_sym).include?(env.name)
+          write = envs.empty? || envs.map(&:to_sym).include?(compute_env_name)
           @config.instance_eval(&) if write
         end
 
         @config
       end
+
+      # The environment name computed from ENV.
+      #
+      # A class has no env of its own, so environment-scoped config blocks
+      # resolve it here.
+      #
+      # @return [Symbol] Environment name
+      # @api private
+      private def compute_env_name
+        name = ENV_NAMES.map { |var| ENV[var] }.compact.first.to_s
+        (name.empty? ? "development" : name).to_sym
+      end
     end
 
     # Instance methods
@@ -179,7 +191,9 @@ module Lennarb
         self.class.instance_exec(&block)
       end
 
-      self.class.routes
+      # Before boot, route definitions go to the class. After boot, this
+      # instance serves from its own frozen snapshot.
+      @routes || self.class.routes
     end
 
     # Get/define configuration
@@ -205,8 +219,15 @@ module Lennarb
     def initialize!
       raise AlreadyInitializedError if @initialized
 
+      warn_about_defaulted_env
+
+      # Snapshot the class routes into this instance and freeze only the copy,
+      # so booting an app never freezes process-global class state.
+      @routes = Routes.new
+      @routes.merge!(self.class.routes)
+      @routes.freeze
+
       @initialized = true
-      routes.freeze
       self
     end
 
@@ -242,6 +263,26 @@ module Lennarb
       stack
     end
 
+    # Warn when the environment was defaulted rather than chosen.
+    #
+    # Defaulting to development is a fail-open: development enables
+    # Rack::ShowExceptions, which renders the whole Rack environment -- the
+    # Authorization and Cookie headers included -- on any unhandled error. A
+    # deployment that simply forgot to export the variable would serve that to
+    # anyone able to trigger a 500.
+    #
+    # @return [void]
+    private def warn_about_defaulted_env
+      return if ENV_NAMES.any? { |name| ENV[name] }
+
+      config.logger.warn do
+        "No #{ENV_NAMES.join(", ")} is set, so the environment defaults to " \
+          "development. Rack::ShowExceptions is enabled and will render the " \
+          "full Rack environment, including Authorization and Cookie headers, " \
+          "on any unhandled error. Set one of these variables in production."
+      end
+    end
+
     # Compute environment from ENV variables
     #
     # @return [String] Environment name

data/lib/lennarb/environment.rb

@@ -40,23 +40,39 @@ module Lennarb
 
     # Implements equality for the environment.
     #
-    def ==(other) = name == other || name.to_s == other
-    alias_method :eql?, :==
-    alias_method :equal?, :==
+    # Compares by name, so an environment equals its name as a Symbol or a
+    # String, and equals another environment with the same name.
+    #
+    # `equal?` is deliberately not aliased here: in Ruby it means object
+    # identity and overriding it broke that contract in both directions.
+    #
+    def ==(other) = name == other || name.to_s == other.to_s
     alias_method :===, :==
 
+    # Value equality, kept consistent with {#hash} so an environment behaves as
+    # a Hash key.
+    #
+    # @param other [Object]
+    # @return [Boolean]
+    #
+    def eql?(other) = other.is_a?(Environment) && name == other.name
+
+    # @return [Integer]
+    #
+    def hash = name.hash
+
     # Returns the name of the environment as a symbol.
-    # @retrn [Symbol]
+    # @return [Symbol]
     #
     def to_sym = name
 
     # Returns the name of the environment as a string.
-    # @retrn [String]
+    # @return [String]
     #
     def to_s = name.to_s
 
     # Returns the name of the environment as a string.
-    # @retrn [String]
+    # @return [String]
     def inspect = to_s.inspect
 
     # Yields a block if the environment is the same as the given environment.

data/lib/lennarb/errors.rb

@@ -1,17 +1,19 @@
 module Lennarb
-  # Lite implementation of app.
+  # Base class for errors raised by Lennarb.
   #
   Error = Class.new(StandardError)
-  # This error is raised whenever the app is initialized more than once.
+  # Raised when merging routes would define the same HTTP method twice for the
+  # same path.
   #
   DuplicateRouteError = Class.new(StandardError)
-  # This error is raised whenever the app is initialized more than once.
+  # Raised when a mandatory configuration value has no environment variable set.
   #
   MissingEnvironmentVariable = Class.new(StandardError)
-  # This error is raised whenever the app is initialized more than once.
+  # Raised when a configuration property is declared without something callable
+  # to compute it.
   #
   MissingCallable = Class.new(StandardError)
-  # This error is raised whenever the app is initialized more than once.
+  # Raised when a route is registered after the routes have been frozen.
   #
   RoutesFrozenError = Class.new(RuntimeError)
 end

data/lib/lennarb/middleware/request_logger.rb

@@ -13,8 +13,17 @@ module Lennarb
         @app = app
       end
 
-      # Get logger from application configuration
-      def logger = Lennarb::App.app.config.logger
+      # Get the logger for this request.
+      #
+      # Resolved from the app handling the request, which App#call publishes in
+      # the Rack env, so an app's configured logger is actually used. Falls back
+      # to the class-level default when there is no app in the env.
+      #
+      # @param [Hash, nil] env Rack environment
+      # @return [Object] The logger
+      def logger(env = nil)
+        env&.[](RACK_LENNA_APP)&.config&.logger || Lennarb::App.app.config.logger
+      end
 
       # Process the request and log information
       #
@@ -28,7 +37,7 @@ module Lennarb
 
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
 
-        log_request(request, status, headers, duration)
+        log_request(request, status, headers, duration, env)
 
         [status, headers, body]
       end
@@ -52,18 +61,20 @@ module Lennarb
       end
 
       # Log the complete request
-      def log_request(request, status, headers, duration)
-        logger.info { request_line(request, duration, status) }
+      def log_request(request, status, headers, duration, env = nil)
+        log = logger(env)
+
+        log.info { request_line(request, duration, status) }
 
-        logger.info { status_line(status) }
+        log.info { status_line(status) }
 
         if request.params.any?
-          logger.info { params_line(request.params) }
+          log.info { params_line(request.params) }
         end
 
-        if headers["Location"]
-          logger.info { redirect_line(headers["Location"]) }
-        end
+        # Rack 3 header names are lowercase; Response#redirect writes "location".
+        location = headers["location"]
+        log.info { redirect_line(location) } if location
       end
 
       # Format the request line
@@ -92,9 +103,16 @@ module Lennarb
         "Redirect: #{location}".colorize(:yellow)
       end
 
-      # Filter the request path
+      # Escape control characters in the request path.
+      #
+      # The path comes from the client, and an unescaped newline or ANSI escape
+      # would let it forge log lines. Parameter values are already safe because
+      # they go through #inspect.
+      #
+      # @param [String] path Request path
+      # @return [String] Path safe to write to a log
       def filter_path(path)
-        path
+        path.to_s.gsub(/[[:cntrl:]]/) { |char| format("\\x%02X", char.ord) }
       end
 
       # Filter request parameters

data/lib/lennarb/middleware_stack.rb

@@ -19,7 +19,7 @@ module Lennarb
     # @param [Array] args
     # @param [Proc] block
     #
-    # @retrn [void]
+    # @return [void]
     #
     def use(middleware, *args, &block)
       @store << [middleware, args, block]
@@ -31,7 +31,7 @@ module Lennarb
     # @param [Array] args
     # @param [Proc] block
     #
-    # @retrn [void]
+    # @return [void]
     #
     def unshift(middleware, *args, &block)
       @store.unshift([middleware, args, block])
@@ -39,7 +39,7 @@ module Lennarb
 
     # Clear the middleware stack.
     #
-    # @retrn [void]
+    # @return [void]
     #
     def clear
       @store.clear
@@ -47,7 +47,7 @@ module Lennarb
 
     # Convert the middleware stack to an array.
     #
-    # @retrn [Array]
+    # @return [Array]
     #
     def to_a
       @store

data/lib/lennarb/parameter_filter.rb

@@ -1,8 +1,8 @@
 module Lennarb
-  # Filtra parâmetros sensíveis de logs e exceções.
-  # Útil para evitar o vazamento de informações confidenciais.
+  # Filters sensitive parameters from logs and exceptions.
+  # Useful for preventing the leakage of confidential information.
   #
-  # Por padrão, as seguintes chaves de parâmetros são filtradas:
+  # By default, the following parameter keys are filtered:
   #
   # - `passw`
   # - `email`
@@ -17,6 +17,16 @@ module Lennarb
   # - `cvv`
   # - `cvc`
   # - `signature`
+  # - `auth`
+  # - `credit`
+  # - `card_number`
+  # - `cvn`
+  # - `iban`
+  # - `api`
+  # - `pin`
+  # - `session_id`
+  #
+  # Matching is case-insensitive, so `Password` and `API_KEY` are filtered too.
   #
   # @example
   #   filter = Lennarb::ParameterFilter.new
@@ -30,47 +40,50 @@ module Lennarb
     # @api private
     DEFAULT_FILTERS = %w[
       passw email secret token _key crypt salt certificate otp ssn cvv cvc
-      signature
+      signature auth credit card_number cvn iban api pin session_id
     ].freeze
 
-    # Inicializa um novo filtro de parâmetros
+    # Initialize a new parameter filter
+    #
+    # Regexp filters are used as given. Anything else is matched as a literal
+    # substring of the key, case-insensitively.
     #
-    # @param [Array<String, Regexp>] filters Lista de padrões para filtrar
+    # @param [Array<String, Symbol, Regexp>] filters List of patterns to filter
     def initialize(filters = DEFAULT_FILTERS)
-      @filter = Regexp.union(filters.map(&:to_s))
+      union = Regexp.union(filters.map { |pattern| pattern.is_a?(Regexp) ? pattern : pattern.to_s })
+      @filter = Regexp.new(union.source, Regexp::IGNORECASE)
     end
 
-    # Filtra os parâmetros conforme o filtro configurado
+    # Filter parameters according to the configured filter
     #
-    # @param [Hash, Array] params Parâmetros a serem filtrados
-    # @param [String] mask Valor que substituirá os parâmetros filtrados
-    # @return [Hash, Array] Parâmetros filtrados
+    # @param [Hash, Array] params Parameters to be filtered
+    # @param [String] mask Value that will replace filtered parameters
+    # @return [Hash, Array] Filtered parameters
     def filter(params, mask: DEFAULT_MASK)
-      filter_object(params.dup, mask)
+      filter_object(params, mask)
     end
 
     private
 
-    # Filtra recursivamente um objeto (hash ou array)
+    # Recursively filter an object (hash or array).
     #
-    # @param [Object] object Objeto a ser filtrado
-    # @param [String] mask Valor que substituirá os parâmetros filtrados
-    # @return [Object] Objeto filtrado
+    # Builds new containers rather than writing into the ones it was given, so
+    # the caller's parameters are never modified.
+    #
+    # @param [Object] object Object to be filtered
+    # @param [String] mask Value that will replace filtered parameters
+    # @return [Object] Filtered object
     def filter_object(object, mask)
       case object
       when Hash
-        object.each do |key, value|
-          object[key] = if key.to_s.match?(@filter)
-            mask
-          else
-            filter_object(value, mask)
-          end
+        object.each_with_object({}) do |(key, value), result|
+          result[key] = key.to_s.match?(@filter) ? mask : filter_object(value, mask)
         end
       when Array
-        object = object.map { filter_object(it, mask) }
+        object.map { filter_object(it, mask) }
+      else
+        object
       end
-
-      object
     end
   end
 end

data/lib/lennarb/request.rb

@@ -125,20 +125,12 @@ module Lennarb
       env["HTTP_REFERER"]
     end
 
-    # Get the host header
-    #
-    # @return [String, nil]
-    #
-    def host
-      env["HTTP_HOST"]
-    end
-
     # Get the content length header
     #
     # @return [String, nil]
     #
     def content_length
-      env["HTTP_CONTENT_LENGTH"]
+      env["CONTENT_LENGTH"]
     end
 
     # Get the content type header
@@ -146,7 +138,7 @@ module Lennarb
     # @return [String, nil]
     #
     def content_type
-      env["HTTP_CONTENT_TYPE"]
+      env["CONTENT_TYPE"]
     end
 
     # Check if the request is an XHR request

data/lib/lennarb/request_handler.rb

@@ -17,7 +17,7 @@ module Lennarb
     # @return [Array] Rack response [status, headers, body]
     def call(env)
       http_method = env[Rack::REQUEST_METHOD].to_sym
-      parts = env[Rack::PATH_INFO].split("/").reject(&:empty?)
+      parts = split_path(env[Rack::PATH_INFO])
       block, params = app.routes.match_route(parts, http_method)
 
       return [404, {"content-type" => CONTENT_TYPE[:TEXT]}, ["Not Found"]] unless block
@@ -35,27 +35,62 @@ module Lennarb
         Hooks.execute(context, app.class, :after, req, res)
 
         res.finish
-      rescue Lennarb::Error => e
+      rescue => e
+        # In development, let the exception through so Rack::ShowExceptions --
+        # already in App#default_middleware_stack -- can render the backtrace.
+        raise if app.env.development?
+
         app.class.config.logger.error("Error: #{e.message}")
         app.class.config.logger.error(e.backtrace.first)
-        [500, {"content-type" => "text/plain"}, ["Internal Server Error"]]
+        [500, {"content-type" => CONTENT_TYPE[:TEXT]}, ["Internal Server Error"]]
       end
     end
 
     private
 
-    # Create a context object with app's helper methods
+    # Split a request path into decoded segments.
     #
-    # @return [Object] A context object with helper methods
-    def create_context
-      context = Object.new
+    # Segments are decoded after splitting, so a percent-encoded slash stays
+    # inside its segment instead of splitting the path. The escape check keeps
+    # the common path free of the decoding cost.
+    #
+    # @param [String] path The raw PATH_INFO
+    # @return [Array<String>] The decoded segments
+    def split_path(path)
+      parts = path.split("/").reject(&:empty?)
+      return parts unless path.include?("%")
 
-      context.define_singleton_method(:app) { app }
+      parts.map! { |part| Rack::Utils.unescape_path(part) }
+    end
+
+    # The context class for this app, compiled once.
+    #
+    # Safe to memoize: Helpers.for always returns the same Module object for a
+    # given app class, and Ruby's include is live, so helpers defined after the
+    # first request still resolve through it.
+    #
+    # @return [Class] The context class
+    def context_class
+      @context_class ||= begin
+        helpers_module = Helpers.for(app.class)
 
-      helpers_module = Helpers.for(app.class)
-      context.extend(helpers_module) if helpers_module
+        Class.new do
+          def initialize(app)
+            @app = app
+          end
 
-      context
+          attr_reader :app
+
+          include helpers_module
+        end
+      end
+    end
+
+    # Create a context object with app's helper methods
+    #
+    # @return [Object] A context object with helper methods
+    def create_context
+      context_class.new(app)
     end
   end
 end

data/lib/lennarb/response.rb

@@ -8,17 +8,17 @@ module Lennarb
     attr_accessor :status
 
     # @!attribute [r] body
-    # @retrn [Array]
+    # @return [Array]
     #
     attr_reader :body
 
     # @!attribute [r] headers
-    # @retrn [Hash]
+    # @return [Hash]
     #
     attr_reader :headers
 
     # @!attribute [r] length
-    # @retrn [Integer]
+    # @return [Integer]
     #
     attr_reader :length
 
@@ -35,7 +35,7 @@ module Lennarb
 
     # Initialize the response object
     #
-    # @retrn [Response]
+    # @return [Response]
     #
     def initialize
       @status = 200
@@ -48,7 +48,7 @@ module Lennarb
     #
     # @param [String] key
     #
-    # @retrn [String] value
+    # @return [String] value
     #
     def [](key)
       @headers[key]
@@ -59,7 +59,7 @@ module Lennarb
     # @param [String] key
     # @param [String] value
     #
-    # @retrn [String] value
+    # @return [String] value
     #
     def []=(key, value)
       @headers[key] = value
@@ -69,7 +69,7 @@ module Lennarb
     #
     # @param [String] str
     #
-    # @retrn [String] str
+    # @return [String] str
     #
     def write(str)
       str = str.to_s
@@ -82,7 +82,7 @@ module Lennarb
     #
     # @param [String] str
     #
-    # @retrn [String] str
+    # @return [String] str
     #
     def text(str)
       @headers[CONTENT_TYPE] = Lennarb::CONTENT_TYPE[:TEXT]
@@ -93,7 +93,7 @@ module Lennarb
     #
     # @param [String] str
     #
-    # @retrn [String] str
+    # @return [String] str
     #
     def html(str)
       @headers[CONTENT_TYPE] = Lennarb::CONTENT_TYPE[:HTML]
@@ -104,16 +104,22 @@ module Lennarb
     #
     # @param [String] str
     #
-    # @retrn [String] str
+    # @return [String] str
     #
     def json(str)
       json_str = JSON.generate(str)
       @headers[CONTENT_TYPE] = Lennarb::CONTENT_TYPE[:JSON]
       write(json_str)
-    rescue JSON::GeneratorError => e
+    # Rescues JSON::JSONError rather than JSON::GeneratorError: a circular or
+    # over-deep object graph raises JSON::NestingError, which descends from
+    # ParserError, not GeneratorError, and so escaped this rescue entirely.
+    #
+    # The body is static because the exception message can carry `inspect`
+    # output of the object being serialized, which may hold credentials.
+    rescue JSON::JSONError
       @status = 500
       @headers[CONTENT_TYPE] = Lennarb::CONTENT_TYPE[:TEXT]
-      write("JSON generation error: #{e.message}")
+      write("JSON generation error")
     end
 
     # Redirect the response
@@ -130,7 +136,7 @@ module Lennarb
 
     # Finish the response
     #
-    # @retrn [Array] response
+    # @return [Array] response
     #
     def finish
       [@status, @headers, @body]

data/lib/lennarb/route_node.rb

@@ -13,7 +13,7 @@ module Lennarb
 
     # Initialize the route node.
     #
-    # @retrn [RouteNode]
+    # @return [RouteNode]
     #
     def initialize
       @blocks = {}
@@ -28,7 +28,7 @@ module Lennarb
     # @param http_method [String] The HTTP method.
     # @param block [Proc] The block to be executed when the route is matched.
     #
-    # @retrn [void]
+    # @return [void]
     #
     def add_route(parts, http_method, block)
       current_node = self
@@ -55,7 +55,7 @@ module Lennarb
     # @param http_method [String] The HTTP method.
     # @param params [Hash] The parameters of the route.
     #
-    # @retrn [Array<Proc, Hash>]
+    # @return [Array<Proc, Hash>]
     #
     def match_route(parts, http_method, params: {})
       if parts.empty?
@@ -85,7 +85,7 @@ module Lennarb
     #
     # @param other [RouteNode] The other route node.
     #
-    # @retrn [void|DuplicateRouteError]
+    # @return [void|DuplicateRouteError]
     #
     def merge!(other)
       other.blocks.each do |http_method, block|

data/lib/lennarb/routes.rb

@@ -35,12 +35,28 @@ module Lennarb
       @store.match_route(parts, http_method)
     end
 
-    # Freeze the routes to prevent further modification
+    # Copy the routes from another Routes instance into this one.
+    #
+    # The copy is deep: node objects are rebuilt rather than shared, so routes
+    # registered on the source afterwards cannot leak into this instance.
+    #
+    # @param other [Routes] The routes to copy from
+    # @return [self]
+    # @api private
+    def merge!(other)
+      @store.merge!(deep_copy(other.store))
+      self
+    end
+
+    # Freeze the routes to prevent further modification.
+    #
+    # Freezes the whole tree, not only the root, so a frozen copy really is
+    # immutable.
     #
     # @return [self] The frozen routes
     def freeze
       @frozen = true
-      @store.freeze
+      deep_freeze(@store)
       self
     end
 
@@ -63,5 +79,39 @@ module Lennarb
       parts = path.split("/").reject(&:empty?)
       @store.add_route(parts, http_method, block)
     end
+
+    # The underlying route tree.
+    #
+    # Protected so that merge! can reach a sibling instance's store without
+    # exposing the tree publicly.
+    #
+    # @return [RouteNode]
+    # @api private
+    protected attr_reader :store
+
+    # Rebuild a route tree, sharing no node objects with the original.
+    #
+    # @param node [RouteNode] The node to copy
+    # @return [RouteNode] The copy
+    def deep_copy(node)
+      copy = RouteNode.new
+      copy.param_key = node.param_key
+      copy.blocks = node.blocks.dup
+
+      node.static_children.each { |part, child| copy.static_children[part] = deep_copy(child) }
+      node.dynamic_children.each { |param, child| copy.dynamic_children[param] = deep_copy(child) }
+
+      copy
+    end
+
+    # Freeze a route tree from the leaves up.
+    #
+    # @param node [RouteNode] The node to freeze
+    # @return [RouteNode] The frozen node
+    def deep_freeze(node)
+      node.static_children.each_value { deep_freeze(it) }
+      node.dynamic_children.each_value { deep_freeze(it) }
+      node.freeze
+    end
   end
 end

data/lib/lennarb/version.rb

@@ -1,3 +1,3 @@
 module Lennarb # :nodoc:
-  VERSION = "1.5.0" # :nodoc:
+  VERSION = "1.5.1" # :nodoc:
 end

data/readme.md

@@ -63,23 +63,18 @@ Create a simple application with routes:
 ```ruby
 require "lennarb"
 
-app = Lennarb::App.new do
-  routes do
-    get("/") do |req, res|
-      res.html("<h1>Welcome to Lennarb!</h1>")
-    end
-
-    get("/hello/:name") do |req, res|
-      name = req.params[:name]
-      res.html("Hello, #{name}!")
-    end
-  end
+class App < Lennarb::App
+  get("/")            { |req, res| res.html("<h1>Welcome to Lennarb!</h1>") }
+  get("/hello/:name") { |req, res| res.html("Hello, #{req.params[:name]}!") }
+  post("/users")      { |req, res| res.json(id: 1, **req.json_body) }
 end
 
-app.initialize!
-run app  # In config.ru
+run App.new.initialize!   # In config.ru
 ```
 
+Subclassing is the canonical form: each subclass gets its own routes, so
+several applications can coexist in one process.
+
 Start with: `rackup`
 
 ## Basic Usage
@@ -98,15 +93,13 @@ class MyApp < Lennarb::App
     optional :port, int, 9292
   end
 
-  # Define routes
-  routes do
-    get("/") do |req, res|
-      res.html("<h1>Welcome!</h1>")
-    end
+  get("/") do |req, res|
+    res.html("<h1>Welcome!</h1>")
+  end
 
-    post("/users") do |req, res|
-      # Access request data
-      data = req.body
+  post("/users") do |req, res|
+    # Access request data
+    data = req.body
       res.json({status: "created", data: data})
     end
   end
@@ -160,18 +153,14 @@ For larger applications, use `Lennarb::Base` to mount multiple apps:
 
 ```ruby
 class API < Lennarb::App
-  routes do
-    get("/users") do |req, res|
-      res.json([{id: 1, name: "Alice"}, {id: 2, name: "Bob"}])
-    end
+  get("/users") do |req, res|
+    res.json([{id: 1, name: "Alice"}, {id: 2, name: "Bob"}])
   end
 end
 
-class Admin < Lennarb::App
-  routes do
-    get("/dashboard") do |req, res|
-      res.html("<h1>Admin Dashboard</h1>")
-    end
+class Admin < Lennarb::App  
+  get("/dashboard") do |req, res|
+    res.html("<h1>Admin Dashboard</h1>")
   end
 end
 
@@ -193,11 +182,10 @@ run Application.new.initialize!
 
 For more detailed information, please see:
 
-- [Getting Started](https://aristotelesbr.github.io/lennarb/guides/getting-started/index) - Setup and first steps
-- [Response](https://aristotelesbr.github.io/lennarb/guides/response/index.html) - Response handling
-- [Request](https://aristotelesbr.github.io/lennarb/guides/request/index.html) - Request handling
-- [Mounting Applications](https://aristotelesbr.github.io/lennarb/guides/mounting-applications/index.html) - Working with multiple apps
-- [Performance](https://aristotelesbr.github.io/lennarb/guides/performance/index.html) - Benchmarks showing Lennarb's routing algorithm efficiency
+- [Getting Started](https://github.com/aristotelesbr/lennarb/tree/main/guides/getting-started) - Setup and first steps
+- [Response](https://github.com/aristotelesbr/lennarb/tree/main/guides/response) - Response handling
+- [Mounting Applications](https://github.com/aristotelesbr/lennarb/tree/main/guides/mounting-applications) - Working with multiple apps
+- [Performance](https://github.com/aristotelesbr/lennarb/tree/main/guides/performance) - Benchmarks showing Lennarb's routing algorithm efficiency
 
 ## Contributing
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: lennarb
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.5.1
 platform: ruby
 authors:
 - Aristóteles Coutinho
 bindir: exe
 cert_chain: []
-date: 2025-04-19 00:00:00.000000000 Z
+date: 2026-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -125,16 +125,30 @@ dependencies:
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-mock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.27'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.27'
 - !ruby/object:Gem::Dependency
   name: minitest-utils
   requirement: !ruby/object:Gem::Requirement
@@ -254,6 +268,7 @@ files:
 - LICENCE
 - README.pt-BR.md
 - Rakefile
+- benchmark/hot_path.rb
 - benchmark/memory.png
 - benchmark/rps.png
 - benchmark/runtime_with_startup.png
@@ -307,7 +322,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="