abstract struct Kemal::Controller

• Kemal::Controller
• Struct
• Value
• Object

Overview

Abstract controller class that provides a structured way to define HTTP endpoints.

Controllers are structs, so the overhead is minimal and you can still use all Kemal features. Method parameters automatically map to GET/POST/URL parameters with type-safe conversion.

Example

struct UsersController < Kemal::Controller
  @[Get("/users")]
  def index
    "Listing all users"
  end

  @[Get("/users/:id")]
  def show(id : Int32)
    "Showing user with ID: #{id}"
  end

  @[Post("/users")]
  def create(name : String, age : Int32, description : String?)
    "Creating user with name: #{name}, age: #{age}, description: #{description}"
  end
end

Supported Parameter Types

• String
• Int32, Int64
• Bool
• Array (with nested support)
• NamedTuple (with nested support)
• Nilable versions of the above

Parameter Mapping

• name=John becomes name : String
• item[foo]=bar becomes item : NamedTuple(foo: String)
• items[]=1&items[]=2 becomes items : Array(Int32)
• items[][id]=1&items[][quantity]=2 becomes items : Array(NamedTuple(id: Int32, quantity: Int32))

Route annotation parameters

• path : String - The URL path for the route (can include path parameters like :id)
• auth : Bool - If true, requires authentication via authenticate! method (default: false)
• strip : Bool | Array(Symbol) - If true, strips all parameters; if array, strips only specified parameters (default: false)

Example

@[Get("/users/:id")]
def show(id : Int32)
  "User #{id}"
end

Example with Authentication

@[Get("/admin/dashboard", auth: true)]
def dashboard
  "Admin Dashboard"
end

private def authenticate! : Bool
  # Return false to halt with 401 status
  request.headers["Authorization"]? == "SecretToken"
end

Example with Parameter Stripping

@[Post("/users", strip: true)]
def create(name : String, description : String?)
  # name and description will have leading/trailing whitespace removed
end

@[Post("/login", strip: [:email])]
def login(email : String, password : String)
  # Only email will be stripped, password remains unchanged
end

Defined in:

Constructors

• .new(context : HTTP::Server::Context)

  Initializes a new controller instance.

Instance Method Summary

• #context : HTTP::Server::Context

  The HTTP server context for the current request.

• #error(field, message, status : HTTP::Status | Nil = nil)

  Adds a field-specific error message.

• #error(message : String)

  Adds a general error message to the base error field.

• #error_for?(field : String) : String | Nil

  Returns the error message for a specific field.

• #error_for_base : String | Nil

  Returns the error message for the "base" field.

• #errors : Errors | Nil

  Hash of validation errors that occurred during request processing.

• #has_error? : Bool

  Checks if any errors have been recorded.

• #redirect(*args, **options)

  Delegates to the redirect method from the context.

• #redirect(*args, **options, &)

  Delegates to the redirect method from the context.

• #request(*args, **options)

  Delegates to the request object from the context.

• #request(*args, **options, &)

  Delegates to the request object from the context.

• #response(*args, **options)

  Delegates to the response object from the context.

• #response(*args, **options, &)

  Delegates to the response object from the context.

• #session(*args, **options)

  Delegates to the session object from the context.

• #session(*args, **options, &)

  Delegates to the session object from the context.

Constructor Detail

Instance Method Detail

def create(email : String, password : String)
  if !email.includes?("@")
    error("email", "Invalid email format")
    render("src/views/users/new.ecr")
    return
  end
  if password.size < 8
    error("password", "Password must be at least 8 characters", HTTP::Status::BAD_REQUEST)
    render("src/views/users/new.ecr")
    return
  end
end

def create(name : String)
  if name.empty?
    error("Name cannot be empty")
    render("src/views/users/new.ecr")
    return
  end
end

def create(email : String)
  error("email", "Invalid email") unless email.includes?("@")

  if msg = error_for?("email")
    render("src/views/users/new.ecr")
    return
  end
end

def update
  error("Something went wrong")
  if msg = error_for_base
    render("src/views/error.ecr")
    return
  end
end

def create(name : String, email : String)
  error("name", "Name is required") if name.empty?
  error("email", "Email is required") if email.empty?

  if has_error?
    render("src/views/users/new.ecr")
    return
  end

  # Process the valid data
end

redirect("/login")

redirect("/login")