1.10.0 (03-03-2026)

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 🙏

1.9.0 (28-01-2026)

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 🙏

1.8.0 (07-11-2025)

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 🙏

1.7.3 (02-10-2025)

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

1.7.2 (04-08-2025)

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

1.7.1 (14-04-2025)

Improve StaticFileHandler to align with latest Crystal implementation #711. Thanks @sdogruyol 🙏

1.7.0 (14-04-2025)

(SECURITY) Fix a Path Traversal Security issue in StaticFileHandler. See for more details. Thanks a lot @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 🙏

1.6.0 (12-10-2024)

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 🙏

1.5.0 (10-04-2024)

Crystal 1.12.0 support 🎉
Allow HTTP::Server::Context#redirect to take an URL #659. Thanks @xendk 🙏
Bump exception_page dependency #669. Thanks @Sija 🙏
Add message support to Kemal::Exceptions::CustomException #671. Thanks @sdogruyol 🙏
Add Date header to HTTP responses #676. Thanks @Sija 🙏

1.4.0 (15-04-2023)

Crystal 1.8.0 support 🎉
Fix multiple logger handlers when custom logger is used #653. Thanks @aravindavk 🙏
Add Kemal::OverrideMethodHandler #651. Thanks @sdogruyol 🙏
HeadRequestHandler: run GET handler and don't return the body #655. Thanks @compumike 🙏

1.3.0 (09-10-2022)

Crystal 1.6.0 support 🎉
Disable signal trap for usage Kemal with other tools #642. Thanks @le0pard 🙏
Bump exception_page shard to v0.3.0 #645. Thanks @Sija 🙏
(Security) Omitting filters fix for lowercase methods requests #647. Thanks @sdogruyol @SlayerShadow 🙏

1.2.0 (07-07-2022)

Crystal 1.5.0 support 🎉
Eliminated several seconds of delay when loading big mp4 file. Thanks @Athlon64 🙏
Fix content_for failing to capture the correct block input #639. Thanks @sdogruyol 🙏
Closes response by default in HTTP::Server::Context#redirect #641. Thanks @cyangle 🙏
Enable option for index.html to be a directories default #640. Thanks @ukd1 🙏

You can enable it via:
```
serve_static({"dir_index" => true})
```

1.1.2 (24-02-2022)

Fix content rendering #631. Thanks @matthewmcgarvey 🙏

1.1.1 (22-02-2022)

Remove Kilt #618. Thanks @sdogruyol 🙏
Ignore HTTP::Server::Response patching for crystal >= 1.3.0 #628. Thanks @SamantazFox 🙏

1.1.0 (02-09-2021)

You can now set your own application name for startup message #606. Thanks @aravindavk 🙏
Add array of paths support for before/after filters #605. Thanks @sdogruyol 🙏
Fixed executing filters when before and after is defined at the same time #612. Thanks @mamantoha 🙏
Set content type to text/html for 500 exceptions #616. Thanks @sdogruyol 🙏

1.0.0 (22-03-2021)

Crystal 1.0.0 support 🎉
Update Radix to use latest 0.4.0 #596. Thanks @luislavena 🙏
Use latest version of Ameba dependency (dev) #597. Thanks @luislavena 🙏
Fix StaticFileHandler failing spec #599. Thanks @jinn999 🙏

0.27.0 (28-11-2020)

Crystal 0.35.x support 🎉 Thanks @bcardiff 🙏
Fix issues with responding with long strings #576. Thanks @mamantoha 🙏
Fix broken WebSocket support in 0.35.0 #577. Thanks @mamantoha 🙏
Allow to set optional response body on redirects #561. Thanks @mamantoha 🙏

0.26.1 (01-12-2019)

Fix process request when a response already closed #550. Thanks @mamantoha 🙏
Switch to new Ameba repository #549. Thanks @mamantoha 🙏
Check for KEMAL_ENV variable already in Config#initialize#552. Thanks @Sija 🙏
Cleanup Ameba warnings #551. Thanks @Sija 🙏
Flush io buffer after each write to log #554. Thanks @mang 🙏

0.26.0 (05-08-2019)

Crystal 0.30.0 support 🎉 #548 and #544. Thanks @bcardiff and @straight-shoota 🙏
Add support for serving files greater than 2^31 bytes #546. Thanks @omarroth 🙏
Properly measure request time using Time.monotonic #527. Thanks @spinscale 🙏

0.25.2 (08-02-2019)

Add option to config to parse or not command line parameters #483. Thanks @diegogub 🙏
Allow to set filename for send_file #512. Thanks @mamantoha 🙏
```
send_file env, "./asset/image.jpeg", filename: "image.jpg"
```
Set status_code before response #513. Thanks @mamantohoa 🙏
Use Crystal MIME registry. #516 Thanks @Sija 🙏

0.25.1 (06-10-2018)

Fix params.files memoization #503. Thanks @mamantoha 🙏

0.25.0 (05-10-2018)

Crystal 0.27.0 support.
[breaking change] Added back env.params.files.

Here's a fully working sample for reading a image file upload image1 and saving it under public/uploads.

post "/upload" do |env|
  file = env.params.files["image1"].tempfile
  file_path = ::File.join [Kemal.config.public_folder, "uploads/", File.basename(file.path)]
  File.open(file_path, "w") do |f|
    IO.copy(file, f)
  end
  "Upload ok"
end

To test

curl -F "image1=@/Users/serdar/Downloads/kemal.png" http://localhost:3000/upload

Cache HTTP routes to increase performance 🚀 #493

0.24.0 (14-08-2018)

[breaking change] Removed env.params.files. You can use Crystal's built-in HTTP::FormData.parse instead:

post "/upload" do |env|
  HTTP::FormData.parse(env.request) do |upload|
    filename = file.filename

    if !filename.is_a?(String)
      "No filename included in upload"
    else
      file_path = ::File.join [Kemal.config.public_folder, "uploads/", filename]
      File.open(file_path, "w") do |f|
      IO.copy(file.tmpfile, f)
    end
    "Upload OK"
  end
end

[breaking change] From now on to access dynamic url params in a WebSocket route you have to use:
```
ws "/:id" do |socket, context|
  id = context.ws_route_lookup.params["id"]
end
```
[breaking change] Removed _method magic param.
Added new exception page #466. Thanks @mamantoha 🙏

Support custom port binding. Thanks @straight-shoota 🙏

Kemal.run do |config|
  server = config.server.not_nil!
  server.bind_tcp "127.0.0.1", 3000, reuse_port: true
  server.bind_tcp "0.0.0.0", 3001, reuse_port: true
end

0.23.0 (17-06-2018)

Crystal 0.25.0 support 🎉
Add Kemal::Context.get? to safely access context storage 😎
[Security] Don't serve 404 image dynamically 👍
Disable X-Powered-By header #449. Thanks @Blacksmoke16 🙏

0.22.0 (29-12-2017)

Crystal 0.24.1 support 🎉
Only return string from route.#408 thanks @crisward 🙏
Don't crash on empty path when compiled in --release. #407 thanks @crisward 🙏
Rename Kemal::CommonLogHandler to Kemal::LogHandler and Kemal::CommonExceptionHandler to Kemal::ExceptionHandler.
Allow videos to be opened with correct mime type. #406 thanks @crisward 🙏
Add webm mime type.#413 thanks @reindeer-cafe 🙏

0.21.0 (05-09-2017)

Dynamically insert handlers 💪 Fixes #376.
Add context to WebSocket. This allows one to use HTTP::Server::Context in ws declarations 😍 Fixes #349.
```
ws "/:room_name" do |socket, env|
  env.params.url["room_name"]
end
```

Add support for customizing the headers of built-in Kemal::StaticFileHandler 🔨 Useful for supporting CORS for single page applications 👏

static_headers do |response, filepath, filestat|
  if filepath =~ /\.html$/
    response.headers.add("Access-Control-Allow-Origin", "*")
  end
  response.headers.add("Content-Size", filestat.size.to_s)
end

Allow %w in Handler macros #385. Thanks @will 🙏
Security: X-Content-Type-Options: nosniff for static files. Fixes #379. Thanks @crisward 🙏
Performance: Remove tempfile management to OS. This brings 10-15% performance boost to Kemal 🚀

0.20.0 (01-07-2017)

Crystal 0.23.0 support! As always, Kemal is compatible with the latest major release of Crystal 💎

Great news everyone 🎉 All handlers are now completely customizable!. Use the default Kemal handlers or go wild, it's all up to you ⛏

# Don't forget to add `Kemal::RouteHandler::INSTANCE` or your routes won't work!
Kemal.config.handlers = [Kemal::InitHandler.new, YourHandler.new, Kemal::RouteHandler::INSTANCE]

You can also insert a handler into a specific position.

# This adds MyCustomHandler instance to 1 position.
# Be aware that the index starts from 0.
add_handler MyCustomHandler.new, 1

Updated Kilt to v0.4.0.
Make Route a Struct. This improves the performance of route declarations.

0.19.0 (09-05-2017)

Return no body for head route fixes #323. (thanks @crisward)
Update Radix to v0.3.8. (thanks @waghanza)
User defined context store types. (thanks @neovitange)

class User
  property name
end

add_context_storage_type(User)

Prevent send_file returning filesize. (thanks @crisward)
Don't call setup in config#add_filter_handler fixes #338.

0.18.3 (07-03-2017)

Remove Gzip::Header monkey patch since it's fixed in Crystal 0.21.1.

0.18.2 (24-02-2017)

Fix Gzip in Kemal Seems broken for static files #316. This was caused by Gzip::Writer in Crystal 0.21.0 and currently mitigated by monkey patching Gzip::Header.

0.18.1 (21-02-2017)

Crystal 0.21.0 support
Drop multipart.cr dependency. multipart support is now built-into Crystal <3
Since Crystal 0.21.0 comes built-in with multipart there are some improvements and deprecations.
meta has been removed from FileUpload and it has the following properties:
- tmpfile: This is temporary file for file upload. Useful for saving the upload file.
- filename: File name of the file upload. (logo.png, images.zip e.g)
- headers: Headers for the file upload.
- creation_time: Creation time of the file upload.
- modification_time: Last Modification time of the file upload.
- read_time: Read time of the file upload.
- size: Size of the file upload.

0.18.0 (11-02-2017)

Simpler file upload. File uploads can now be access from HTTP::Server::Context like env.params.files["filename"], which exposes following properties.
- tmpfile: This is temporary file for file upload. Useful for saving the upload file.
- tmpfile_path: File path of tmpfile.
- filename: File name of the file upload. (logo.png, images.zip e.g)
- meta: Meta information for the file upload.
- headers: Headers for the file upload.
Here's a fully working sample for reading a image file upload image1 and saving it under public/uploads.
```
post "/upload" do |env|
  file = env.params.files["image1"].tmpfile
  file_path = ::File.join [Kemal.config.public_folder, "uploads/", file.filename]
  File.open(file_path, "w") do |f|
    IO.copy(file, f)
  end
  "Upload ok"
end
```
To test

curl -F "image1=@/Users/serdar/Downloads/kemal.png" http://localhost:3000/upload
RF7233 support a.k.a file streaming. #299 (thanks @denysvitali)
Update Radix to 0.3.7. Fixes #293
Configurable startup / shutdown logging. #291 and #292 (thanks @twisterghost).

0.17.5 (09-01-2017)

Update multipart.cr to 0.1.2. Fixes #285 related to multipart.cr

0.17.4 (24-12-2016)

Support for Crystal 0.20.3
Add Kemal.stop. Fixes #269.
HTTP::Handler is not a class anymore, it's a module. See https://github.com/crystal-lang/crystal/releases/tag/0.20.3

0.17.3 (03-12-2016)

Handle missing 404 image. Fixes #263
Remove basic auth middleware from core and move to kemalcr/kemal-basic-auth.

0.17.2 (25-11-2016)

Use body.gets_to_end for parse_json. Fixes #260.
Update Radix to 0.3.5 and lock pessimistically. (thanks @luislavena)

0.17.1 (24-11-2016)

Treat HTTP::Request body as an IO. Fixes #257

0.17.0 (23-11-2016)

Reimplemented Request middleware / filter routing.

Now all requests will first go through the Middleware stack then Filters (before_*) and will finally reach the matching route.

Which is illustrated as: Request -> Middleware -> Filter -> Route
Rename return_with as halt.
Route declaration must start with /. Fixes #242
Set default exception Content-Type to text/html. Fixes #202

Add only and exclude paths for Kemal::Handler. This change requires that all handlers must inherit from Kemal::Handler.

For example this handler will only work on / path. By default the HTTP method is GET.

class OnlyHandler < Kemal::Handler
  only ["/"]

  def call(env)
    return call_next(env) unless only_match?(env)
    puts "If the path is / i will be doing some processing here."
  end
end

The handlers using exclude will work on the paths that isn't specified. For example this handler will work on any routes other than /.

class ExcludeHandler < Kemal::Handler
  exclude ["/"]

  def call(env)
    return call_next(env) unless only_match?(env)
    puts "If the path is NOT / i will be doing some processing here."
  end
end

Close response on halt. (thanks @samueleaton).
Update Radix to v0.3.4.
error handler now also yields error. For example you can get the error mesasage like:
```
error 500 do |env, err|
  err.message
end
```
Update multipart.cr to v0.1.1

0.16.1 (12-10-2016)

Improved Multipart support with more info on parsed files. parse_multipart(env) now yields an UploadFile object which has the following properties: field, data, meta and headers.

post "/upload" do |env|
  parse_multipart(env) do |f|
    image1 = f.data if f.field == "image1"
    image2 = f.data if f.field == "image2"
    puts f.meta
    puts f.headers
    "Upload complete"
  end
end

0.16.0

Multipart support <3 (thanks @RX14). Now you can handle file uploads.

post "/upload" do |env|
  parse_multipart(env) do |field, data|
    image1 = data if field == "image1"
    image2 = data if field == "image2"
    "Upload complete"
  end
end

Make session configurable. Now you can specify session name and expire time with:

Kemal.config.session["name"] = "your_app"
Kemal.config.session["expire_time"] = 48.hours

Session now supports more types. (String, Int32, Float64, Bool)
Add gzip helper to enable / disable gzip compression on responses.
Static file caching with etag and gzip (thanks @crisward)
Kemal.run now accepts port to listen.

0.15.1 (05-09-2016)

Don't forget to call_next on NullLogHandler

0.15.0 (03-09-2016)

Add context store.
KEMAL_ENV respects to Kemal.config.env and needs to be explicitly set.
Kemal::InitHandler is introduced. Adds initial configuration, headers like X-Powered-By.
Add send_file to helpers.
Add mime types.
Fix parsing JSON params when "charset" is present in Content-Type header.
Use http-only cookie for session.
Inject STDOUT by default in CommonLogHandler.

Uh oh!

FilesExpand file tree

CHANGELOG.md

Latest commit

History