diff --git a/src/kemal/helpers/helpers.cr b/src/kemal/helpers/helpers.cr index de06d9e..c2d2aa0 100644 --- a/src/kemal/helpers/helpers.cr +++ b/src/kemal/helpers/helpers.cr @@ -1,4 +1,13 @@ -# Adds given HTTP::Handler+ to handlers. +# Adds given Kemal::Handler to handlers chain. +# There are 5 handlers by default and all the custom handlers +# goes between the first 4 and the last `Kemal::RouteHandler`. +# +# - Kemal::InitHandler +# - Kemal::CommonLogHandler +# - Kemal::CommonExceptionHandler +# - Kemal::StaticFileHandler +# - Here goes custom handlers +# - Kemal::RouteHandler def add_handler(handler) Kemal.config.add_handler handler end @@ -9,28 +18,65 @@ def public_folder(path) Kemal.config.public_folder = path end -# Logs to output stream. STDOUT is the default stream. +# Logs the output via `logger`. +# This is the built-in `Kemal::CommonLogHandler` by default which uses STDOUT. def log(message) Kemal.config.logger.write "#{message}\n" end -# Enables / Disables logging +# Enables / Disables logging. +# This is enabled by default. +# +# logging false def logging(status) Kemal.config.logging = status end -# Replaces Kemal::CommonLogHandler with a custom logger. +# This is used to replace the built-in `Kemal::CommonLogHandler` with a custom logger. +# +# A custom logger must inherit from `Kemal::BaseLogHandler` and must implement +# `call(env)`, `write(message)` methods. +# +# class MyCustomLogger < Kemal::BaseLogHandler +# +# def call(env) +# puts "I'm logging some custom stuff here." +# call_next(env) # => This calls the next handler +# end +# +# # This is used from `log` method. +# def write(message) +# STDERR.puts message # => Logs the output to STDERR +# end +# end +# +# Now that we have a custom logger here's how we use it +# +# logger MyCustomLogger.new def logger(logger) Kemal.config.logger = logger Kemal.config.add_handler logger end # Enables / Disables static file serving. +# This is enabled by default. +# +# serve_static false +# +# Static server also have some advanced customization options like `dir_listing` and +# `gzip`. +# +# server_static {"gzip" => true, "dir_listing" => false} def serve_static(status : (Bool | Hash)) Kemal.config.serve_static = status end # Helper for easily modifying response headers. +# This can be used to modify a response header with the given hash. +# +# def call(env) +# headers(env, {"custom-header" => "This is a custom value"}) +# end def headers(env, additional_headers) env.response.headers.merge!(additional_headers) end