⚠️ IMPORTANT: This release fixes two critical security vulnerabilities in previous versions of Kemal. All users are strongly advised to update immediately.

• (SECURITY) Fix chunked multipart body limits #748. Thanks @canermastan 🙏

This PR adds a new config option:

Kemal.config.max_multipart_form_field_size = 8 * 1024 * 1024

• (SECURITY) Add Websocket origin validation and configuration support #749. Thanks @past3l 🙏

This PR adds a new config option:

Kemal.config.websocket_allowed_origins = ["https://myapp.com", "http://localhost:3000"]

Contributors

• @canermastan
• @azqzazq1

• Add shutdown_timeout configuration for graceful shutdown: after Kemal.stop, Kemal can wait before exit so in-flight work can finish #745. Thanks @sdogruyol 🙏

Kemal.config.shutdown_timeout = 10.seconds

Contributors

• @sdogruyol

This is the biggest Kemal release ever with new features and a lot of improvements 🎉

• Add modular Kemal::Router with namespaced routing, scoped filters, WebSocket support and flexible mounting while keeping the existing DSL fully compatible #731. Thanks @sdogruyol 🙏

require "kemal"
api = Kemal::Router.new
api.namespace "/users" do
 get "/" do |env|
 env.json({users: ["alice", "bob"]})
 end
 get "/:id" do |env|
 env.text "user #{env.params.url["id"]}"
 end
end
mount "/api/v1", api
Kemal.run

• Add use keyword for registering global and path-specific middleware, including support for arrays and insertion at a specific position in the handler chain #734. Thanks @sdogruyol 🙏

require "kemal"
# Path-specific middlewares for /api routes
use "/api", [CORSHandler.new, AuthHandler.new]
get "/" do
 "Public home"
end
get "/api/users" do |env|
 env.json({users: ["alice", "bob"]})
end
Kemal.run

• Enhance response helpers to provide chainable JSON/HTML/text/XML helpers, HTTP::Status support and the ability to halt execution from a chained response for concise API error handling #733, #735, #736. Thanks @sdogruyol and @mamantoha 🙏

require "kemal"
get "/users" do |env|
 # Default JSON response
 env.json({users: ["alice", "bob"]})
end
post "/users" do |env|
 # Symbol-based HTTP::Status and chained JSON
 env.status(:created).json({id: 1, created: true})
end
get "/admin" do |env|
 # Halt immediately with HTML response
 halt env.status(403).html("<h1>Forbidden</h1>")
end
get "/api/users" do |env|
 # Custom content type (JSON:API)
 env.json({data: ["alice", "bob"]}, content_type: "application/vnd.api+json")
end
Kemal.run

• Ensure global wildcard filters always execute while keeping namespace filters isolated to their routes #737. Thanks @mamantoha 🙏
• Fix CLI SSL validation and expand CLI option parsing specs #738. Thanks @sdogruyol 🙏
• Make route LRU cache concurrency-safe with Mutex #739. Thanks @sdogruyol 🙏
• Add raw_body to ParamParser for multi-handler body access (e.g. kemal-session) #740. Thanks @sdogruyol 🙏

post "/" do |env|
 raw = env.params.raw_body # raw body, multiple handlers can call it
 env.params.body["name"] # parsed body
end

• Fix OverrideMethodHandler route cache bug when using _method override #741, #742. Thanks @skojin and @sdogruyol 🙏

Contributors

• @skojin
• @mamantoha
• @sdogruyol

• Crystal 1.19.0 support 🎉
• (SECURITY) Limit maximum request body size to avoid DoS attacks #730. Thanks @sdogruyol 🙏
• Optimize JSON parameter parsing by directly using the request body IO. Thanks @sdogruyol 🙏

Contributors

• @sdogruyol

This release brings a lot of performance improvements 🚀

• Enhance HEAD request handling by caching GET route lookups and optimize path construction using string interpolation for improved performance #728. Thanks @sdogruyol 🙏
• Improve error messages #726. Thanks @sdogruyol 🙏
• Optimize route and websocket lookups by caching results to reduce redundant processing in the HTTP server context #725. Thanks @sdogruyol 🙏
• Replace full-flush Route cache with LRU and add a configurable max cache size #724. Thanks @sdogruyol 🙏

Contributors

• @sdogruyol

• Refactor #719. Thanks @sdogruyol 🙏
• Improve Kemal test suite. Thanks @sdogruyol 🙏

Contributors

• @sdogruyol

• Move Kemal::Handler logic into separate module #717. Thanks @syeopite 🙏
• Refactor server binding logic to avoid binding in test environment #719. Thanks @sdogruyol 🙏

Contributors

• @sdogruyol
• @syeopite

• Improve StaticFileHandler to align with latest Crystal implementation #711. Thanks @sdogruyol @straight-shoota 🙏

Contributors

• @straight-shoota
• @sdogruyol

⚠️ IMPORTANT: This release fixes a critical path traversal security vulnerability in previous versions of Kemal.
All users are strongly advised to update immediately.

• (SECURITY) Fix a Path Traversal Security issue in StaticFileHandler. See for more details. Huge THANKS to @ahmetumitbayram 🙏
• Crystal 1.16.0 support 🎉
• Add ability to add handlers for raised exceptions #688. Thanks @syeopite 🙏

require "kemal"
class NewException < Exception
end
get "/" do | env |
 raise NewException.new()
end
error NewException do | env |
 "An error occured!"
end
Kemal.run

• Add all_files method to params to support multiple file uploads in names ending with [] #701. Thanks @sdogruyol 🙏

images = env.params.all_files["images[]"]?

• Embrace Crystal standard Log for logging #705. Thanks @hugopl 🙏
• Cleanup temporary files for file uploads #707. Thanks @sdogruyol 🙏
• Implement multiple partial ranges #708. Thanks @sdogruyol 🙏

Contributors

• @hugopl
• @sdogruyol
• @syeopite

• Crystal 1.14.0 support 🎉
• Windows support #690. Thanks @sdogruyol 🙏
• Directory Listing: Add UTF-8 Charset to the response Content type #679. Thanks @alexkutsan @Sija 🙏
• Use context instead of response in static_headers helper #681. Thanks @sdogruyol 🙏

Contributors

• @Sija
• @alexkutsan
• @sdogruyol