Core Modules

This document provides a comprehensive reference for Azu's core modules, including endpoints, requests, responses, and routing.

Endpoint Module

`Azu::Endpoint`

The core endpoint module that provides type-safe HTTP request handling.

module Azu::Endpoint
  # Include this module to create type-safe endpoints
  include Endpoint(RequestType, ResponseType)
end

Methods

get(path : String, **options)

Registers a GET route for the endpoint.

struct UserEndpoint
  include Endpoint(UserRequest, UserResponse)

  get "/users/:id"
  get "/users", constraints: {id: /\d+/}
  get "/users", middleware: [AuthMiddleware]
end

Parameters:

path - The route path pattern
constraints - Route parameter constraints (optional)
middleware - Route-specific middleware (optional)
only - HTTP methods to allow (optional)

post(path : String, **options)

Registers a POST route for the endpoint.

post "/users"
post "/users", middleware: [ValidationMiddleware]

put(path : String, **options)

Registers a PUT route for the endpoint.

put "/users/:id"

patch(path : String, **options)

Registers a PATCH route for the endpoint.

patch "/users/:id"

delete(path : String, **options)

Registers a DELETE route for the endpoint.

delete "/users/:id"

head(path : String, **options)

Registers a HEAD route for the endpoint.

head "/users"

options(path : String, **options)

Registers an OPTIONS route for the endpoint.

options "/users"

call : ResponseType

The main endpoint method that must be implemented.

def call : UserResponse
  # Implementation here
  UserResponse.new(user: find_user(request.id))
end

Request Module

`Azu::Request`

Base module for type-safe request objects.

module Azu::Request
  # Include this module to create request contracts
end

Methods

self.from_params(params : Params) : self

Factory method to create request objects from parameters.

def self.from_params(params : Params) : self
  new(
    id: params.get_int("id"),
    name: params.get_string("name"),
    email: params.get_string("email")
  )
end

self.schema : Schema

Define validation schema for the request.

def self.schema : Schema
  Schema.new(
    id: Int32,
    name: String,
    email: String
  )
end

Response Module

`Azu::Response`

Base module for type-safe response objects.

module Azu::Response
  # Include this module to create response objects
end

Methods

render : String

Convert the response object to a string representation.

def render : String
  {
    "id" => user.id,
    "name" => user.name,
    "email" => user.email
  }.to_json
end

headers : HTTP::Headers

Return custom HTTP headers for the response.

def headers : HTTP::Headers
  headers = HTTP::Headers.new
  headers["Content-Type"] = "application/json"
  headers["Cache-Control"] = "no-cache"
  headers
end

status : Int32

Return the HTTP status code for the response.

def status : Int32
  200
end

Params Module

`Azu::Params`

Type-safe parameter extraction from HTTP requests.

class Azu::Params
  # Provides type-safe access to request parameters
end

Methods

get_string(key : String) : String

Extract a string parameter.

name = params.get_string("name")

get_string?(key : String) : String?

Extract an optional string parameter.

description = params.get_string?("description")

get_int(key : String) : Int32

Extract an integer parameter.

id = params.get_int("id")

get_int?(key : String) : Int32?

Extract an optional integer parameter.

age = params.get_int?("age")

get_float(key : String) : Float64

Extract a float parameter.

price = params.get_float("price")

get_float?(key : String) : Float64?

Extract an optional float parameter.

rating = params.get_float?("rating")

get_bool(key : String) : Bool

Extract a boolean parameter.

active = params.get_bool("active")

get_bool?(key : String) : Bool?

Extract an optional boolean parameter.

featured = params.get_bool?("featured")

get_file(key : String) : Azu::FileUpload

Extract a file upload.

file = params.get_file("upload")

get_files(key : String) : Array(Azu::FileUpload)

Extract multiple file uploads.

files = params.get_files("uploads")

get_array(key : String) : Array(String)

Extract an array parameter.

tags = params.get_array("tags")

get_hash(key : String) : Hash(String, String)

Extract a hash parameter.

metadata = params.get_hash("metadata")

to_h : Hash(String, String)

Convert all parameters to a hash.

all_params = params.to_h

Router Module

`Azu::Router`

High-performance routing using Radix trees.

class Azu::Router
  # Handles route matching and parameter extraction
end

Methods

add(method : String, path : String, handler : Handler)

Add a route to the router.

router.add("GET", "/users/:id", user_handler)

find(method : String, path : String) : RouteMatch?

Find a matching route for the given method and path.

if match = router.find("GET", "/users/123")
  params = match.params
  handler = match.handler
end

routes : Array(Route)

Get all registered routes.

all_routes = router.routes

Channel Module

`Azu::Channel`

WebSocket channel handling for real-time features.

class Azu::Channel < Azu::Base
  # Base class for WebSocket channels
end

Methods

ws(path : String)

class ChatChannel < Azu::Channel
  ws "/ws/chat/:room_id"
end

on_connect

Called when a client connects to the channel.

def on_connect
  Log.info { "Client connected to chat room" }
end

on_message(message : String)

Called when a message is received from a client.

def on_message(message : String)
  broadcast(message)
end

on_disconnect

Called when a client disconnects from the channel.

def on_disconnect
  Log.info { "Client disconnected from chat room" }
end

broadcast(message : String)

Send a message to all connected clients.

def broadcast(message : String)
  # Implementation
end

send_to(client_id : String, message : String)

Send a message to a specific client.

def send_to(client_id : String, message : String)
  # Implementation
end

Component Module

`Azu::Component`

Live components for real-time UI updates.

class Azu::Component
  # Base class for live components
end

Methods

content

Generate the component's HTML content.

def content
  div class: "user-card" do
    h3 user.name
    p user.email
  end
end

on_event(event : String, data : Hash(String, JSON::Any))

Handle client-side events.

def on_event(event : String, data : Hash(String, JSON::Any))
  case event
  when "click"
    handle_click(data)
  when "update"
    handle_update(data)
  end
end

update_content

Update the component's content and notify clients.

def update_content
  # Update internal state
  @show_details = !@show_details

  # Notify clients of the change
  broadcast_update
end

Templates Module

`Azu::Templates`

Template rendering and hot reloading support.

module Azu::Templates
  # Template engine integration
end

Methods

render(template : String, data : Hash) : String

Render a template with data.

html = Templates.render("user.html", {"user" => user})

renderable

Include this module to make a response renderable.

struct UserPage
  include Response
  include Templates::Renderable

  def render
    view "user.html", {"user" => user}
  end
end

Configuration Module

`Azu::Configuration`

Application configuration management.

class Azu::Configuration
  # Centralized configuration management
end

Properties

host : String

The host to bind the server to.

Configuration.host = "0.0.0.0"

port : Int32

The port to bind the server to.

Configuration.port = 3000

workers : Int32

The number of worker processes.

Configuration.workers = 4

ssl_enabled : Bool

Whether SSL/TLS is enabled.

Configuration.ssl_enabled = true

ssl_cert_path : String?

Path to the SSL certificate file.

Configuration.ssl_cert_path = "/path/to/cert.pem"

ssl_key_path : String?

Path to the SSL private key file.

Configuration.ssl_key_path = "/path/to/key.pem"

Error Module

`Azu::Error`

Error handling and custom exceptions.

class Azu::Error < Exception
  # Base error class for Azu applications
end

Subclasses

Azu::Error::NotFound

Raised when a resource is not found.

raise Azu::Error::NotFound.new("User not found")

Azu::Error::BadRequest

Raised when the request is malformed.

raise Azu::Error::BadRequest.new("Invalid parameters")

Azu::Error::Unauthorized

Raised when authentication is required.

raise Azu::Error::Unauthorized.new("Authentication required")

Azu::Error::Forbidden

Raised when access is denied.

raise Azu::Error::Forbidden.new("Access denied")

Azu::Error::InternalServerError

Raised when an internal error occurs.

raise Azu::Error::InternalServerError.new("Database connection failed")

Logging Module

`Azu::Log`

Structured logging for Azu applications.

module Azu::Log
  # Logging utilities and configuration
end

Methods

info(message : String)

Log an info message.

Log.info { "User #{user.id} logged in" }

debug(message : String)

Log a debug message.

Log.debug { "Processing request: #{request.path}" }

warn(message : String)

Log a warning message.

Log.warn { "Rate limit exceeded for IP: #{ip}" }

error(message : String)

Log an error message.

Log.error { "Database connection failed: #{ex.message}" }

fatal(message : String)

Log a fatal message.

Log.fatal { "Application startup failed: #{ex.message}" }

Utility Modules

`Azu::Utils`

Common utility functions and helpers.

module Azu::Utils
  # Utility functions for common tasks
end

Methods

generate_id : String

Generate a unique identifier.

id = Utils.generate_id

slugify(text : String) : String

Convert text to a URL-friendly slug.

slug = Utils.slugify("Hello World!") # => "hello-world"

encrypt(data : String, key : String) : String

Encrypt sensitive data.

encrypted = Utils.encrypt("sensitive data", secret_key)

decrypt(data : String, key : String) : String

Decrypt encrypted data.

decrypted = Utils.decrypt(encrypted_data, secret_key)

hash_password(password : String) : String

Hash a password for storage.

hashed = Utils.hash_password("user_password")

verify_password(password : String, hash : String) : Bool

Verify a password against its hash.

valid = Utils.verify_password("user_password", stored_hash)

Constants

HTTP Methods

GET     = "GET"
POST    = "POST"
PUT     = "PUT"
PATCH   = "PATCH"
DELETE  = "DELETE"
HEAD    = "HEAD"
OPTIONS = "OPTIONS"

HTTP Status Codes

OK                  = 200
CREATED             = 201
NO_CONTENT          = 204
BAD_REQUEST         = 400
UNAUTHORIZED        = 401
FORBIDDEN           = 403
NOT_FOUND           = 404
METHOD_NOT_ALLOWED  = 405
CONFLICT            = 409
UNPROCESSABLE_ENTITY = 422
INTERNAL_SERVER_ERROR = 500

Content Types

JSON = "application/json"
XML  = "application/xml"
HTML = "text/html"
TEXT = "text/plain"

Type Definitions

`Azu::FileUpload`

Represents an uploaded file.

struct Azu::FileUpload
  getter filename : String
  getter content_type : String
  getter content : IO
  getter size : Int64
end

`Azu::RouteMatch`

Represents a matched route.

struct Azu::RouteMatch
  getter params : Hash(String, String)
  getter handler : Handler
  getter route : Route
end

`Azu::Route`

Represents a registered route.

struct Azu::Route
  getter method : String
  getter path : String
  getter handler : Handler
  getter constraints : Hash(String, Regex)?
  getter middleware : Array(Middleware)?
end

Next Steps

Handler Classes - Built-in middleware handlers
Configuration Options - Configuration reference
Core Concepts - Understanding the core concepts
Advanced Usage - Advanced usage patterns

PreviousAPI Reference NextHandler Classes

Last updated 1 month ago

Was this helpful?