1 of 95

Azu

Tutorials

Building a User API

This tutorial walks you through building a complete RESTful API for user management with type-safe endpoints, validation, and proper error handling.

What You'll Build

By the end of this tutorial, you'll have:

Working with Databases

This tutorial teaches you how to connect Azu to a database using CQL, Crystal's type-safe ORM.

What You'll Build

By the end of this tutorial, you'll have:

CQL connected to PostgreSQL (or SQLite for development)

Building Live Components

This tutorial teaches you how to create real-time, interactive UI components using Azu's live component system.

What You'll Build

By the end of this tutorial, you'll have:

A reactive counter component
A live chat component
Understanding of component lifecycle
Real-time DOM updates without page refreshes

Prerequisites

Completed tutorial
Understanding of WebSocket basics

Step 1: Understanding Live Components

Live components in Azu provide:

Real-time DOM updates - UI changes without page refreshes
Server-side state - State managed on the server
Event-driven interactions - Respond to user actions immediately

Step 2: Create a Counter Component

Create src/components/counter_component.cr:

Step 3: Create a Counter Endpoint

Create src/endpoints/counter_endpoint.cr:

Step 4: Create a Chat Component

Create src/components/chat_component.cr:

Step 5: Component Lifecycle

Components have lifecycle methods you can override:

Step 6: State Management

Manage complex state in components:

Step 7: Form Components

Handle forms with validation:

Step 8: Composing Components

Build complex UIs by composing components:

Key Concepts Learned

Component Structure

DOM Updates

Event Handling

Best Practices

Keep components focused - One responsibility per component
Use composition - Build complex UIs from simple components
Handle cleanup - Implement on_unmount for resource cleanup

Next Steps

You've learned to build interactive components. Continue with:

- Test your components
- Deploy your application

Interactive components ready! Your application now has real-time, reactive UI elements.

Testing Your App

This tutorial teaches you how to write comprehensive tests for your Azu application, including endpoints, models, and WebSocket channels.

What You'll Learn

By the end of this tutorial, you'll be able to:

Endpoints

Create an Endpoint

This guide shows you how to create type-safe HTTP endpoints in Azu.

Basic Endpoint

Create an endpoint by including Azu::Endpoint with request and response types:

Handle Parameters

This guide shows you how to extract and work with request parameters.

Route Parameters

Define route parameters with a colon prefix:

Validation

Real-Time

Database

Caching

File Handling

Middleware

Templates

Testing

Deployment

Error Handling

Performance

API Reference

Handlers

Configuration

Errors

Database

Templates

Migration

Architecture

Concepts

Design Decisions

Resources

class CounterComponent < Azu::Component
  def initialize(@initial_count : Int32 = 0)
    @count = @initial_count
  end

  def content
    div class: "counter", id: "counter-#{object_id}" do
      h3 "Counter"

      div class: "display" do
        span id: "count", class: "count-value" do
          text @count.to_s
        end
      end

      div class: "controls" do
        button onclick: "increment()", class: "btn btn-primary" do
          text "+"
        end
        button onclick: "decrement()", class: "btn btn-secondary" do
          text "-"
        end
        button onclick: "reset()", class: "btn btn-danger" do
          text "Reset"
        end
      end
    end
  end

  def on_event("increment", data)
    @count += 1
    update_element "count", @count.to_s
  end

  def on_event("decrement", data)
    @count -= 1
    update_element "count", @count.to_s
  end

  def on_event("reset", data)
    @count = @initial_count
    update_element "count", @count.to_s
  end
end

struct CounterEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Html)
  include Azu::Templates::Renderable

  get "/counter"

  def call
    component = CounterComponent.new(0)

    html <<-HTML
      <!DOCTYPE html>
      <html>
      <head>
        <title>Live Counter</title>
        <style>
          .counter { text-align: center; padding: 20px; }
          .count-value { font-size: 48px; font-weight: bold; }
          .controls { margin-top: 20px; }
          .btn { padding: 10px 20px; margin: 5px; cursor: pointer; }
          .btn-primary { background: #007bff; color: white; border: none; }
          .btn-secondary { background: #6c757d; color: white; border: none; }
          .btn-danger { background: #dc3545; color: white; border: none; }
        </style>
      </head>
      <body>
        #{component.render}

        <script>
          const ws = new WebSocket('ws://localhost:4000/spark');

          function increment() {
            ws.send(JSON.stringify({type: 'event', event: 'increment'}));
          }

          function decrement() {
            ws.send(JSON.stringify({type: 'event', event: 'decrement'}));
          }

          function reset() {
            ws.send(JSON.stringify({type: 'event', event: 'reset'}));
          }

          ws.onmessage = function(event) {
            const data = JSON.parse(event.data);
            if (data.type === 'update') {
              document.getElementById(data.id).innerHTML = data.content;
            }
          };
        </script>
      </body>
      </html>
    HTML
  end
end

class ChatComponent < Azu::Component
  def initialize(@room_id : String)
    @messages = [] of NamedTuple(user: String, text: String, time: Time)
    @users = Set(String).new
  end

  def content
    div class: "chat-room", id: "chat-#{object_id}" do
      div class: "chat-header" do
        h3 "Room: #{@room_id}"
        span id: "user-count" do
          text "#{@users.size} users"
        end
      end

      div id: "messages", class: "messages" do
        @messages.each do |msg|
          render_message(msg)
        end
      end

      form onsubmit: "sendMessage(event)", class: "message-form" do
        input type: "text", id: "message-input", placeholder: "Type a message..."
        button type: "submit" do
          text "Send"
        end
      end
    end
  end

  def on_event("send_message", data)
    message = data["text"]?.try(&.as_s)
    user = data["user"]?.try(&.as_s) || "Anonymous"
    return unless message && !message.strip.empty?

    msg = {user: user, text: message, time: Time.utc}
    @messages << msg

    # Append new message to DOM
    append_element "messages", render_message_html(msg)
  end

  def on_event("user_joined", data)
    user = data["user"]?.try(&.as_s)
    return unless user

    @users << user
    update_element "user-count", "#{@users.size} users"

    # Add system message
    append_element "messages", <<-HTML
      <div class="system-message">#{user} joined the room</div>
    HTML
  end

  def on_event("user_left", data)
    user = data["user"]?.try(&.as_s)
    return unless user

    @users.delete(user)
    update_element "user-count", "#{@users.size} users"

    append_element "messages", <<-HTML
      <div class="system-message">#{user} left the room</div>
    HTML
  end

  private def render_message(msg)
    div class: "message" do
      span class: "user" do
        text msg[:user]
      end
      span class: "text" do
        text msg[:text]
      end
      time class: "timestamp" do
        text msg[:time].to_s("%H:%M")
      end
    end
  end

  private def render_message_html(msg)
    <<-HTML
      <div class="message">
        <span class="user">#{msg[:user]}</span>
        <span class="text">#{msg[:text]}</span>
        <time class="timestamp">#{msg[:time].to_s("%H:%M")}</time>
      </div>
    HTML
  end
end

class LifecycleComponent < Azu::Component
  def on_mount
    # Called when component is first mounted
    # Load initial data, set up subscriptions
    Log.info { "Component mounted" }
  end

  def on_unmount
    # Called when component is removed
    # Clean up resources, unsubscribe
    Log.info { "Component unmounted" }
  end

  def on_connect
    # Called when WebSocket connects
    Log.info { "WebSocket connected" }
  end

  def on_disconnect
    # Called when WebSocket disconnects
    Log.info { "WebSocket disconnected" }
  end
end

class StatefulComponent < Azu::Component
  def initialize
    @state = {} of String => JSON::Any
    @listeners = [] of Proc(Nil)
  end

  # Get state value
  def get(key : String)
    @state[key]?
  end

  # Set state and notify listeners
  def set(key : String, value)
    @state[key] = JSON::Any.new(value)
    notify_listeners
    render_state
  end

  # Subscribe to state changes
  def subscribe(&block : -> Nil)
    @listeners << block
  end

  def on_event("update_state", data)
    key = data["key"]?.try(&.as_s)
    value = data["value"]?
    return unless key && value

    set(key, value)
  end

  private def notify_listeners
    @listeners.each(&.call)
  end

  private def render_state
    content = @state.map do |k, v|
      "<div><strong>#{k}:</strong> #{v}</div>"
    end.join

    update_element "state-display", content
  end
end

class FormComponent < Azu::Component
  def initialize
    @errors = {} of String => String
    @values = {} of String => String
  end

  def content
    form onsubmit: "submitForm(event)", id: "user-form" do
      div class: "form-group" do
        label "Name", for: "name"
        input type: "text", id: "name", name: "name", value: @values["name"]?

        if error = @errors["name"]?
          span class: "error" do
            text error
          end
        end
      end

      div class: "form-group" do
        label "Email", for: "email"
        input type: "email", id: "email", name: "email", value: @values["email"]?

        if error = @errors["email"]?
          span class: "error" do
            text error
          end
        end
      end

      button type: "submit" do
        text "Submit"
      end
    end
  end

  def on_event("submit_form", data)
    @values = data.as_h.transform_values(&.as_s)
    @errors.clear

    validate_form

    if @errors.empty?
      process_form
    else
      render_errors
    end
  end

  private def validate_form
    name = @values["name"]?
    email = @values["email"]?

    @errors["name"] = "Name is required" if name.nil? || name.strip.empty?
    @errors["email"] = "Email is required" if email.nil? || email.strip.empty?
    @errors["email"] = "Invalid email" if email && !email.includes?("@")
  end

  private def render_errors
    @errors.each do |field, message|
      # Show error next to field
      update_element "#{field}-error", message
    end
  end

  private def process_form
    # Handle successful submission
    update_element "user-form", <<-HTML
      <div class="success">Form submitted successfully!</div>
    HTML
  end
end

class ButtonComponent < Azu::Component
  def initialize(@text : String, @variant : String = "primary")
  end

  def content
    button class: "btn btn-#{@variant}" do
      text @text
    end
  end
end

class CardComponent < Azu::Component
  def initialize(@title : String, &@block : -> Nil)
  end

  def content
    div class: "card" do
      div class: "card-header" do
        h4 @title
      end
      div class: "card-body" do
        @block.call
      end
    end
  end
end

class UserCardComponent < Azu::Component
  def initialize(@user : User)
  end

  def content
    CardComponent.new(@user.name) do
      p @user.email
      p "Joined: #{@user.created_at.to_s("%B %Y")}"

      div class: "actions" do
        ButtonComponent.new("Edit", "primary").render
        ButtonComponent.new("Delete", "danger").render
      end
    end.render
  end
end

class MyComponent < Azu::Component
  def content       # Define the HTML structure
  def on_event(...)  # Handle events from client
  def on_mount       # Called when mounted
  def on_unmount     # Called when removed
end

class User
  property id : Int64
  property name : String
  property email : String
  property age : Int32?
  property created_at : Time
  property updated_at : Time

  @@next_id = 1_i64
  @@users = [] of User

  def initialize(@name : String, @email : String, @age : Int32? = nil)
    @id = @@next_id
    @@next_id += 1
    @created_at = Time.utc
    @updated_at = Time.utc
    @@users << self
  end

  def self.all : Array(User)
    @@users.dup
  end

  def self.find(id : Int64) : User?
    @@users.find { |u| u.id == id }
  end

  def self.find_by_email(email : String) : User?
    @@users.find { |u| u.email == email }
  end

  def update(name : String? = nil, email : String? = nil, age : Int32? = nil)
    @name = name if name
    @email = email if email
    @age = age if age
    @updated_at = Time.utc
  end

  def delete
    @@users.delete(self)
  end

  def to_json(json : JSON::Builder)
    json.object do
      json.field "id", @id
      json.field "name", @name
      json.field "email", @email
      json.field "age", @age
      json.field "created_at", @created_at.to_rfc3339
      json.field "updated_at", @updated_at.to_rfc3339
    end
  end
end

struct CreateUserRequest
  include Azu::Request

  getter name : String
  getter email : String
  getter age : Int32?

  def initialize(@name = "", @email = "", @age = nil)
  end

  validate name, presence: true, length: {min: 2, max: 50},
    message: "Name must be between 2 and 50 characters"

  validate email, presence: true, format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i,
    message: "Email must be a valid email address"

  validate age, numericality: {greater_than: 0, less_than: 150}, allow_nil: true,
    message: "Age must be between 1 and 150"
end

struct UpdateUserRequest
  include Azu::Request

  getter name : String?
  getter email : String?
  getter age : Int32?

  def initialize(@name = nil, @email = nil, @age = nil)
  end

  validate name, length: {min: 2, max: 50}, allow_nil: true,
    message: "Name must be between 2 and 50 characters"

  validate email, format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i, allow_nil: true,
    message: "Email must be a valid email address"

  validate age, numericality: {greater_than: 0, less_than: 150}, allow_nil: true,
    message: "Age must be between 1 and 150"
end

struct UserResponse
  include Azu::Response

  def initialize(@user : User)
  end

  def render
    {
      id: @user.id,
      name: @user.name,
      email: @user.email,
      age: @user.age,
      created_at: @user.created_at.to_rfc3339,
      updated_at: @user.updated_at.to_rfc3339
    }.to_json
  end
end

struct UsersListResponse
  include Azu::Response

  def initialize(@users : Array(User))
  end

  def render
    {
      users: @users.map { |user| user_json(user) },
      count: @users.size,
      timestamp: Time.utc.to_rfc3339
    }.to_json
  end

  private def user_json(user : User)
    {
      id: user.id,
      name: user.name,
      email: user.email,
      age: user.age,
      created_at: user.created_at.to_rfc3339
    }
  end
end

struct CreateUserEndpoint
  include Azu::Endpoint(CreateUserRequest, UserResponse)

  post "/users"

  def call : UserResponse
    # Validate request
    unless create_user_request.valid?
      raise Azu::Response::ValidationError.new(
        create_user_request.errors.group_by(&.field).transform_values(&.map(&.message))
      )
    end

    # Check for duplicate email
    if User.find_by_email(create_user_request.email)
      raise Azu::Response::ValidationError.new(
        {"email" => ["Email is already taken"]}
      )
    end

    # Create user
    user = User.new(
      name: create_user_request.name,
      email: create_user_request.email,
      age: create_user_request.age
    )

    status 201
    UserResponse.new(user)
  end
end

struct ShowUserEndpoint
  include Azu::Endpoint(EmptyRequest, UserResponse)

  get "/users/:id"

  def call : UserResponse
    user_id = params["id"].to_i64

    if user = User.find(user_id)
      UserResponse.new(user)
    else
      raise Azu::Response::NotFound.new("/users/#{user_id}")
    end
  end
end

struct UpdateUserEndpoint
  include Azu::Endpoint(UpdateUserRequest, UserResponse)

  put "/users/:id"

  def call : UserResponse
    user_id = params["id"].to_i64

    unless user = User.find(user_id)
      raise Azu::Response::NotFound.new("/users/#{user_id}")
    end

    # Validate request
    unless update_user_request.valid?
      raise Azu::Response::ValidationError.new(
        update_user_request.errors.group_by(&.field).transform_values(&.map(&.message))
      )
    end

    # Check for duplicate email if updating
    if email = update_user_request.email
      if existing = User.find_by_email(email)
        unless existing.id == user_id
          raise Azu::Response::ValidationError.new(
            {"email" => ["Email is already taken"]}
          )
        end
      end
    end

    # Update user
    user.update(
      name: update_user_request.name,
      email: update_user_request.email,
      age: update_user_request.age
    )

    UserResponse.new(user)
  end
end

struct DeleteUserEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Empty)

  delete "/users/:id"

  def call : Azu::Response::Empty
    user_id = params["id"].to_i64

    unless user = User.find(user_id)
      raise Azu::Response::NotFound.new("/users/#{user_id}")
    end

    user.delete
    status 204
    Azu::Response::Empty.new
  end
end

require "azu"

# Load application files
require "./models/*"
require "./requests/*"
require "./responses/*"
require "./endpoints/*"

module UserAPI
  include Azu

  configure do
    port = ENV.fetch("PORT", "4000").to_i
    host = ENV.fetch("HOST", "0.0.0.0")
    log.level = Log::Severity::DEBUG
  end
end

# Start the application
UserAPI.start [
  Azu::Handler::RequestId.new,
  Azu::Handler::Rescuer.new,
  Azu::Handler::Logger.new,
  Azu::Handler::CORS.new,
  ListUsersEndpoint.new,
  ShowUserEndpoint.new,
  CreateUserEndpoint.new,
  UpdateUserEndpoint.new,
  DeleteUserEndpoint.new,
]

{
  "Status": "Unprocessable Entity",
  "Title": "Validation Error",
  "FieldErrors": {
    "name": ["Name must be between 2 and 50 characters"],
    "email": ["Email must be a valid email address"]
  }
}

user_api/
├── shard.yml
├── src/
│   ├── user_api.cr           # Main application
│   ├── models/
│   │   └── user.cr           # User model
│   ├── requests/
│   │   ├── create_user_request.cr
│   │   └── update_user_request.cr
│   ├── responses/
│   │   ├── user_response.cr
│   │   └── users_list_response.cr
│   └── endpoints/
│       ├── create_user_endpoint.cr
│       ├── list_users_endpoint.cr
│       ├── show_user_endpoint.cr
│       ├── update_user_endpoint.cr
│       └── delete_user_endpoint.cr
└── spec/

name: user_api
version: 0.1.0

dependencies:
  azu:
    github: azutoolkit/azu
    version: ~> 0.5.28
  cql:
    github: azutoolkit/cql
    version: ~> 0.1.0
  # Choose your database driver:
  pg:                           # PostgreSQL
    github: will/crystal-pg
  # OR
  # sqlite3:                    # SQLite (development)
  #   github: crystal-lang/crystal-sqlite3

crystal: >= 0.35.0
license: MIT

require "cql"

AppDB = CQL::Schema.define(
  :app_database,
  adapter: CQL::Adapter::Postgres,
  uri: ENV.fetch("DATABASE_URL", "postgres://localhost:5432/user_api_dev")
) do
  table :users do
    primary :id, Int64
    text :name
    text :email
    integer :age, null: true
    boolean :active, default: "true"
    timestamps

    index :email, unique: true
  end
end

struct User
  include CQL::ActiveRecord::Model(Int64)
  db_context AppDB, :users

  getter id : Int64?
  getter name : String
  getter email : String
  getter age : Int32?
  getter active : Bool
  getter created_at : Time
  getter updated_at : Time

  # Validations
  validates :name, presence: true, size: 2..50
  validates :email, presence: true

  # Scopes for common queries
  scope :active, -> { where(active: true) }
  scope :recent, -> { order(created_at: :desc) }

  # Instance methods
  def activate!
    @active = true
    save!
  end

  def deactivate!
    @active = false
    save!
  end
end

struct CreateUserEndpoint
  include Azu::Endpoint(CreateUserRequest, UserResponse)

  post "/users"

  def call : UserResponse
    # Validate request
    unless create_user_request.valid?
      raise Azu::Response::ValidationError.new(
        create_user_request.errors.group_by(&.field).transform_values(&.map(&.message))
      )
    end

    # Check for duplicate email
    if User.find_by(email: create_user_request.email)
      raise Azu::Response::ValidationError.new(
        {"email" => ["Email is already taken"]}
      )
    end

    # Create user in database
    user = User.create!(
      name: create_user_request.name,
      email: create_user_request.email,
      age: create_user_request.age
    )

    status 201
    UserResponse.new(user)
  rescue CQL::RecordInvalid => e
    raise Azu::Response::ValidationError.new(e.errors)
  end
end

struct ListUsersEndpoint
  include Azu::Endpoint(EmptyRequest, UsersListResponse)

  get "/users"

  def call : UsersListResponse
    # Use scopes for filtering
    users = User.active.recent.limit(100).all
    UsersListResponse.new(users)
  end
end

struct ShowUserEndpoint
  include Azu::Endpoint(EmptyRequest, UserResponse)

  get "/users/:id"

  def call : UserResponse
    user_id = params["id"].to_i64

    if user = User.find?(user_id)
      UserResponse.new(user)
    else
      raise Azu::Response::NotFound.new("/users/#{user_id}")
    end
  end
end

struct UpdateUserEndpoint
  include Azu::Endpoint(UpdateUserRequest, UserResponse)

  put "/users/:id"

  def call : UserResponse
    user_id = params["id"].to_i64

    unless user = User.find?(user_id)
      raise Azu::Response::NotFound.new("/users/#{user_id}")
    end

    unless update_user_request.valid?
      raise Azu::Response::ValidationError.new(
        update_user_request.errors.group_by(&.field).transform_values(&.map(&.message))
      )
    end

    # Check duplicate email
    if email = update_user_request.email
      if existing = User.find_by(email: email)
        unless existing.id == user_id
          raise Azu::Response::ValidationError.new(
            {"email" => ["Email is already taken"]}
          )
        end
      end
    end

    # Update the user
    user.update!(
      name: update_user_request.name,
      email: update_user_request.email,
      age: update_user_request.age
    )

    UserResponse.new(user)
  rescue CQL::RecordInvalid => e
    raise Azu::Response::ValidationError.new(e.errors)
  end
end

struct DeleteUserEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Empty)

  delete "/users/:id"

  def call : Azu::Response::Empty
    user_id = params["id"].to_i64

    unless user = User.find?(user_id)
      raise Azu::Response::NotFound.new("/users/#{user_id}")
    end

    user.destroy!
    status 204
    Azu::Response::Empty.new
  end
end

require "azu"

# Load database configuration first
require "./config/database"

# Load application files
require "./models/*"
require "./requests/*"
require "./responses/*"
require "./endpoints/*"

module UserAPI
  include Azu

  configure do
    port = ENV.fetch("PORT", "4000").to_i
    host = ENV.fetch("HOST", "0.0.0.0")
  end
end

# Create tables if they don't exist
AppDB.create_tables

# Start the application
UserAPI.start [
  Azu::Handler::RequestId.new,
  Azu::Handler::Rescuer.new,
  Azu::Handler::Logger.new,
  Azu::Handler::CORS.new,
  ListUsersEndpoint.new,
  ShowUserEndpoint.new,
  CreateUserEndpoint.new,
  UpdateUserEndpoint.new,
  DeleteUserEndpoint.new,
]

AppDB = CQL::Schema.define(
  :app_database,
  adapter: CQL::Adapter::Postgres,
  uri: ENV["DATABASE_URL"]
) do
  table :users do
    primary :id, Int64
    text :name
    text :email
    integer :age, null: true
    boolean :active, default: "true"
    timestamps
    index :email, unique: true
  end

  table :posts do
    primary :id, Int64
    text :title
    text :content
    bigint :user_id
    boolean :published, default: "false"
    timestamps
    index :user_id
  end
end

struct Post
  include CQL::ActiveRecord::Model(Int64)
  db_context AppDB, :posts

  getter id : Int64?
  getter title : String
  getter content : String
  getter user_id : Int64
  getter published : Bool
  getter created_at : Time
  getter updated_at : Time

  belongs_to :user, User, foreign_key: :user_id

  validates :title, presence: true, size: 5..200
  validates :content, presence: true
  validates :user_id, presence: true

  scope :published, -> { where(published: true) }
  scope :drafts, -> { where(published: false) }
  scope :by_user, ->(id : Int64) { where(user_id: id) }

  def publish!
    @published = true
    save!
  end
end

# Find by ID
user = User.find(1)           # Raises if not found
user = User.find?(1)          # Returns nil if not found

# Find by attributes
user = User.find_by(email: "alice@example.com")

# Queries with conditions
active_users = User.where(active: true).all
recent_users = User.order(created_at: :desc).limit(10).all

# Using scopes
User.active.recent.limit(20).all

# Relationships
user = User.find(1)
user_posts = user.posts.all
published_posts = user.posts.published.all

# Create with relationship
post = Post.create!(
  title: "My First Post",
  content: "Hello, world!",
  user_id: user.id
)

# Count records
User.count
User.where(active: true).count

struct Model
  include CQL::ActiveRecord::Model(Int64)
  db_context Schema, :table

  getter field : Type
  validates :field, presence: true
  scope :name, -> { where(...) }
  has_many :relation, OtherModel
end

struct CreateUserRequest
  include Azu::Request

  getter name : String
  getter email : String
  getter age : Int32?

  def initialize(@name = "", @email = "", @age = nil)
  end
end

struct CreateUserEndpoint
  include Azu::Endpoint(CreateUserRequest, UserResponse)

  post "/users"

  def call
    name = create_user_request.name
    email = create_user_request.email
    age = create_user_request.age
  end
end

struct FormEndpoint
  include Azu::Endpoint(FormRequest, FormResponse)

  post "/submit"

  def call
    # Access form fields from request contract
    name = form_request.name
    email = form_request.email
  end
end

struct UploadRequest
  include Azu::Request

  getter file : HTTP::FormData::File
  getter description : String?

  def initialize(@file, @description = nil)
  end
end

struct UploadEndpoint
  include Azu::Endpoint(UploadRequest, UploadResponse)

  post "/upload"

  def call
    file = upload_request.file
    filename = file.filename
    content = file.content
    content_type = file.content_type
  end
end

def call
  # String to integer
  id = params["id"].to_i64

  # String to boolean
  active = params["active"]? == "true"

  # String to enum
  status = Status.parse(params["status"]? || "pending")
end

struct UserEndpoint
  include Azu::Endpoint(EmptyRequest, UserResponse)

  get "/users/:id"

  def call : UserResponse
    user_id = params["id"].to_i64
    user = User.find(user_id)

    if user
      UserResponse.new(user)
    else
      raise Azu::Response::NotFound.new("/users/#{user_id}")
    end
  end
end

struct UserResponse
  include Azu::Response

  def initialize(@user : User)
  end

  def render
    {id: @user.id, name: @user.name, email: @user.email}.to_json
  end
end

require "spec"
require "../src/user_api"

# Test configuration
module TestConfig
  def self.setup
    # Use test database
    ENV["DATABASE_URL"] = "sqlite3://./test.db"
    ENV["AZU_ENV"] = "test"
  end
end

# Helper module for creating test contexts
module TestHelpers
  def create_context(
    method : String = "GET",
    path : String = "/",
    body : String? = nil,
    headers : HTTP::Headers = HTTP::Headers.new
  ) : HTTP::Server::Context
    io = IO::Memory.new
    request = HTTP::Request.new(method, path, headers, body)
    response = HTTP::Server::Response.new(io)
    HTTP::Server::Context.new(request, response)
  end

  def json_headers : HTTP::Headers
    headers = HTTP::Headers.new
    headers["Content-Type"] = "application/json"
    headers
  end

  def parse_response(context : HTTP::Server::Context) : JSON::Any
    context.response.close
    body = context.response.@io.as(IO::Memory).to_s
    JSON.parse(body.split("\r\n\r\n").last)
  end
end

# Setup before all tests
TestConfig.setup

Spec.before_each do
  # Clean database before each test
  User.delete_all if defined?(User)
end

require "../spec_helper"

describe CreateUserEndpoint do
  include TestHelpers

  describe "#call" do
    it "creates a user with valid data" do
      body = {
        name: "Alice Smith",
        email: "alice@example.com",
        age: 30
      }.to_json

      context = create_context("POST", "/users", body, json_headers)
      endpoint = CreateUserEndpoint.new

      # Simulate the request
      endpoint.context = context
      response = endpoint.call

      response.should be_a(UserResponse)
      context.response.status_code.should eq(201)
    end

    it "returns validation error for missing name" do
      body = {email: "alice@example.com"}.to_json
      context = create_context("POST", "/users", body, json_headers)
      endpoint = CreateUserEndpoint.new
      endpoint.context = context

      expect_raises(Azu::Response::ValidationError) do
        endpoint.call
      end
    end

    it "returns validation error for invalid email" do
      body = {name: "Alice", email: "invalid-email"}.to_json
      context = create_context("POST", "/users", body, json_headers)
      endpoint = CreateUserEndpoint.new
      endpoint.context = context

      expect_raises(Azu::Response::ValidationError) do
        endpoint.call
      end
    end

    it "returns validation error for duplicate email" do
      # Create first user
      User.create!(name: "First", email: "alice@example.com")

      body = {name: "Second", email: "alice@example.com"}.to_json
      context = create_context("POST", "/users", body, json_headers)
      endpoint = CreateUserEndpoint.new
      endpoint.context = context

      expect_raises(Azu::Response::ValidationError) do
        endpoint.call
      end
    end
  end
end

require "../spec_helper"

describe ShowUserEndpoint do
  include TestHelpers

  describe "#call" do
    it "returns user when found" do
      user = User.create!(name: "Alice", email: "alice@example.com")

      context = create_context("GET", "/users/#{user.id}")
      endpoint = ShowUserEndpoint.new
      endpoint.context = context
      endpoint.params = {"id" => user.id.to_s}

      response = endpoint.call

      response.should be_a(UserResponse)
    end

    it "raises NotFound for non-existent user" do
      context = create_context("GET", "/users/999")
      endpoint = ShowUserEndpoint.new
      endpoint.context = context
      endpoint.params = {"id" => "999"}

      expect_raises(Azu::Response::NotFound) do
        endpoint.call
      end
    end
  end
end

require "../spec_helper"

describe CreateUserRequest do
  describe "validation" do
    it "validates with correct data" do
      request = CreateUserRequest.new(
        name: "Alice Smith",
        email: "alice@example.com",
        age: 30
      )

      request.valid?.should be_true
      request.errors.should be_empty
    end

    it "requires name" do
      request = CreateUserRequest.new(
        name: "",
        email: "alice@example.com"
      )

      request.valid?.should be_false
      request.errors.map(&.field).should contain("name")
    end

    it "validates name length" do
      request = CreateUserRequest.new(
        name: "A",  # Too short
        email: "alice@example.com"
      )

      request.valid?.should be_false
    end

    it "requires email" do
      request = CreateUserRequest.new(
        name: "Alice Smith",
        email: ""
      )

      request.valid?.should be_false
      request.errors.map(&.field).should contain("email")
    end

    it "validates email format" do
      request = CreateUserRequest.new(
        name: "Alice Smith",
        email: "invalid-email"
      )

      request.valid?.should be_false
    end

    it "allows nil age" do
      request = CreateUserRequest.new(
        name: "Alice Smith",
        email: "alice@example.com",
        age: nil
      )

      request.valid?.should be_true
    end

    it "validates age range" do
      request = CreateUserRequest.new(
        name: "Alice Smith",
        email: "alice@example.com",
        age: 200  # Too old
      )

      request.valid?.should be_false
    end
  end
end

require "../spec_helper"

describe User do
  describe "validations" do
    it "requires name" do
      user = User.new(email: "test@example.com")
      user.valid?.should be_false
      user.errors.should contain("name")
    end

    it "validates name length" do
      user = User.new(name: "A", email: "test@example.com")
      user.valid?.should be_false
    end

    it "requires email" do
      user = User.new(name: "Test User")
      user.valid?.should be_false
    end
  end

  describe "CRUD operations" do
    it "creates a user" do
      user = User.create!(name: "Test", email: "test@example.com")

      user.id.should_not be_nil
      user.name.should eq("Test")
      user.created_at.should_not be_nil
    end

    it "finds a user by ID" do
      created = User.create!(name: "Test", email: "test@example.com")
      found = User.find?(created.id.not_nil!)

      found.should_not be_nil
      found.try(&.name).should eq("Test")
    end

    it "updates a user" do
      user = User.create!(name: "Test", email: "test@example.com")
      user.update!(name: "Updated")

      User.find?(user.id.not_nil!).try(&.name).should eq("Updated")
    end

    it "deletes a user" do
      user = User.create!(name: "Test", email: "test@example.com")
      user.destroy!

      User.find?(user.id.not_nil!).should be_nil
    end
  end

  describe "scopes" do
    it "filters active users" do
      User.create!(name: "Active", email: "active@example.com", active: true)
      User.create!(name: "Inactive", email: "inactive@example.com", active: false)

      active_users = User.active.all
      active_users.size.should eq(1)
      active_users.first.name.should eq("Active")
    end

    it "orders by recent" do
      first = User.create!(name: "First", email: "first@example.com")
      sleep 0.1.seconds
      second = User.create!(name: "Second", email: "second@example.com")

      users = User.recent.all
      users.first.name.should eq("Second")
    end
  end
end

require "../spec_helper"

describe NotificationChannel do
  describe "#on_connect" do
    it "adds socket to connections" do
      channel = NotificationChannel.new
      socket = MockWebSocket.new

      initial_count = NotificationChannel::CONNECTIONS.size
      channel.socket = socket
      channel.on_connect

      NotificationChannel::CONNECTIONS.size.should eq(initial_count + 1)
    end

    it "sends welcome message" do
      channel = NotificationChannel.new
      socket = MockWebSocket.new
      channel.socket = socket
      channel.on_connect

      socket.sent_messages.size.should eq(1)
      message = JSON.parse(socket.sent_messages.first)
      message["type"].should eq("connected")
    end
  end

  describe "#on_message" do
    it "responds to ping with pong" do
      channel = NotificationChannel.new
      socket = MockWebSocket.new
      channel.socket = socket
      channel.on_connect

      channel.on_message(%({"type": "ping"}))

      messages = socket.sent_messages
      pong = messages.find { |m| JSON.parse(m)["type"] == "pong" }
      pong.should_not be_nil
    end

    it "handles invalid JSON" do
      channel = NotificationChannel.new
      socket = MockWebSocket.new
      channel.socket = socket
      channel.on_connect

      channel.on_message("invalid json")

      messages = socket.sent_messages
      error = messages.find { |m| JSON.parse(m)["type"] == "error" }
      error.should_not be_nil
    end
  end

  describe "#on_close" do
    it "removes socket from connections" do
      channel = NotificationChannel.new
      socket = MockWebSocket.new
      channel.socket = socket
      channel.on_connect

      count_before = NotificationChannel::CONNECTIONS.size
      channel.on_close(nil, nil)

      NotificationChannel::CONNECTIONS.size.should eq(count_before - 1)
    end
  end
end

# Mock WebSocket for testing
class MockWebSocket
  getter sent_messages = [] of String

  def send(message : String)
    @sent_messages << message
  end

  def object_id
    0_u64
  end
end

require "../spec_helper"
require "http/client"

describe "User API Integration" do
  # Start server before tests
  before_all do
    spawn do
      UserAPI.start
    end
    sleep 1.second  # Wait for server to start
  end

  it "creates and retrieves a user" do
    # Create user
    response = HTTP::Client.post(
      "http://localhost:4000/users",
      headers: HTTP::Headers{"Content-Type" => "application/json"},
      body: {name: "Integration Test", email: "integration@test.com"}.to_json
    )

    response.status_code.should eq(201)
    user = JSON.parse(response.body)
    user["name"].should eq("Integration Test")

    # Retrieve user
    get_response = HTTP::Client.get("http://localhost:4000/users/#{user["id"]}")
    get_response.status_code.should eq(200)
  end

  it "lists all users" do
    response = HTTP::Client.get("http://localhost:4000/users")

    response.status_code.should eq(200)
    data = JSON.parse(response.body)
    data["users"].as_a.should be_a(Array(JSON::Any))
  end

  it "returns 404 for non-existent user" do
    response = HTTP::Client.get("http://localhost:4000/users/999999")

    response.status_code.should eq(404)
  end

  it "validates request data" do
    response = HTTP::Client.post(
      "http://localhost:4000/users",
      headers: HTTP::Headers{"Content-Type" => "application/json"},
      body: {name: ""}.to_json
    )

    response.status_code.should eq(422)
  end
end

spec/
├── spec_helper.cr           # Test configuration
├── endpoints/               # Endpoint tests
│   ├── create_user_endpoint_spec.cr
│   ├── show_user_endpoint_spec.cr
│   └── ...
├── requests/                # Request validation tests
│   ├── create_user_request_spec.cr
│   └── ...
├── models/                  # Model tests
│   └── user_spec.cr
├── channels/                # WebSocket channel tests
│   └── notification_channel_spec.cr
└── integration/             # Integration tests
    └── api_spec.cr

struct CreateUserRequest
  include Azu::Request

  getter name : String
  getter email : String
  getter age : Int32?

  def initialize(@name = "", @email = "", @age = nil)
  end

  validate name, presence: true
  validate email, presence: true
end

struct CreateUserEndpoint
  include Azu::Endpoint(CreateUserRequest, UserResponse)

  post "/users"

  def call : UserResponse
    # If validation fails, Azu raises ValidationError automatically
    # The error handler converts it to a 422 response
    UserResponse.new(User.create!(create_user_request))
  end
end

struct JsonEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Json)

  get "/api/data"

  def call
    json({
      message: "Hello",
      timestamp: Time.utc.to_rfc3339
    })
  end
end

struct RegistrationRequest
  include Azu::Request

  getter username : String
  getter password : String
  getter email : String

  def initialize(@username = "", @password = "", @email = "")
  end

  validate username, presence: true, length: {min: 3, max: 20}
  validate password, presence: true, length: {min: 8}
  validate email, presence: true, format: /@/
end

struct OrderRequest
  include Azu::Request

  getter items : Array(OrderItem)
  getter coupon_code : String?

  def initialize(@items = [] of OrderItem, @coupon_code = nil)
  end

  def validate
    super  # Run standard validations first

    if items.empty?
      errors << Error.new(:items, "must have at least one item")
    end

    if coupon = coupon_code
      unless valid_coupon?(coupon)
        errors << Error.new(:coupon_code, "is invalid or expired")
      end
    end
  end

  private def valid_coupon?(code : String) : Bool
    Coupon.valid?(code)
  end
end

struct PaymentRequest
  include Azu::Request

  getter payment_type : String
  getter card_number : String?
  getter bank_account : String?

  def initialize(@payment_type = "", @card_number = nil, @bank_account = nil)
  end

  validate payment_type, presence: true

  def validate
    super

    case payment_type
    when "card"
      if card_number.nil? || card_number.try(&.empty?)
        errors << Error.new(:card_number, "is required for card payments")
      end
    when "bank"
      if bank_account.nil? || bank_account.try(&.empty?)
        errors << Error.new(:bank_account, "is required for bank payments")
      end
    end
  end
end

struct CreateUserEndpoint
  include Azu::Endpoint(CreateUserRequest, UserResponse)

  post "/users"

  def call : UserResponse
    # Request is automatically validated before call
    # Access validated data via the request object
    user = User.create!(
      name: create_user_request.name,
      email: create_user_request.email,
      age: create_user_request.age
    )

    status 201
    UserResponse.new(user)
  end
end

struct ValidationErrorResponse
  include Azu::Response

  def initialize(@errors : Array(Azu::Request::Error))
  end

  def render
    {
      success: false,
      error: {
        code: "VALIDATION_FAILED",
        details: @errors.map do |e|
          {field: e.field.to_s, message: e.message}
        end
      }
    }.to_json
  end
end

struct CreateUserEndpoint
  include Azu::Endpoint(CreateUserRequest, Azu::Response)

  post "/users"

  def call : Azu::Response
    request = create_user_request

    unless request.valid?
      status 422
      return ValidationErrorResponse.new(request.errors)
    end

    status 201
    UserResponse.new(User.create!(request))
  end
end

def call : Azu::Response
  user = User.new(
    name: create_user_request.name,
    email: create_user_request.email
  )

  if user.save
    status 201
    UserResponse.new(user)
  else
    status 422
    ModelErrorResponse.new(user.errors)
  end
end

class ValidationErrorHandler < Azu::Handler::Base
  def call(context)
    call_next(context)
  rescue error : Azu::Response::ValidationError
    context.response.status_code = 422
    context.response.content_type = "application/json"
    context.response.print({
      error: "Validation Failed",
      details: error.errors.map { |e| {field: e.field, message: e.message} }
    }.to_json)
  end
end

struct MultiFieldRequest
  include Azu::Request

  getter name : String
  getter email : String
  getter password : String

  def initialize(@name = "", @email = "", @password = "")
  end

  validate name, presence: true, length: {min: 2}
  validate email, presence: true, format: /@/
  validate password, presence: true, length: {min: 8}

  # All errors are collected, not just the first one
end

def call
  request = create_user_request

  unless request.valid?
    return view "users/new.html", {
      errors: request.errors,
      form_data: request
    }
  end

  redirect_to "/users"
end

struct CreateUserRequest
  include Azu::Request

  getter name : String

  def initialize(@name = "")
  end

  def validate
    if name.empty?
      errors << Error.new(:name, I18n.t("errors.name.blank"))
    elsif name.size < 2
      errors << Error.new(:name, I18n.t("errors.name.too_short", min: 2))
    end
  end
end

struct HtmlEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Html)

  get "/page"

  def call
    html <<-HTML
      <!DOCTYPE html>
      <html>
        <head><title>Page</title></head>
        <body><h1>Hello!</h1></body>
      </html>
    HTML
  end
end

struct TemplateEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Html)
  include Azu::Templates::Renderable

  get "/users"

  def call
    view "users/index.html", {
      users: User.all,
      title: "User List"
    }
  end
end

struct DeleteEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Empty)

  delete "/users/:id"

  def call
    user = User.find(params["id"].to_i64)
    user.try(&.delete)

    status 204
    Azu::Response::Empty.new
  end
end

struct NegotiatedEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response)

  get "/data"

  def call
    data = {message: "Hello", value: 42}

    case accept_type
    when "application/json"
      json data
    when "text/html"
      html "<p>#{data[:message]}: #{data[:value]}</p>"
    when "text/plain"
      text "#{data[:message]}: #{data[:value]}"
    else
      json data  # Default to JSON
    end
  end

  private def accept_type
    headers["Accept"]?.try(&.split(",").first) || "application/json"
  end
end

struct DownloadEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response)

  get "/download/:filename"

  def call
    filename = params["filename"]
    file_path = File.join("files", filename)

    if File.exists?(file_path)
      response.headers["Content-Type"] = "application/octet-stream"
      response.headers["Content-Disposition"] = "attachment; filename=\"#{filename}\""
      response.body = File.read(file_path)
    else
      raise Azu::Response::NotFound.new("/download/#{filename}")
    end
  end
end

module UserAPI
  include Azu

  configure do
    # Use environment variables for all settings
    port = ENV.fetch("PORT", "8080").to_i
    host = ENV.fetch("HOST", "0.0.0.0")

    # Production settings
    if ENV["AZU_ENV"]? == "production"
      log.level = Log::Severity::INFO

      # SSL configuration
      ssl_cert = ENV["SSL_CERT"]?
      ssl_key = ENV["SSL_KEY"]?
    else
      log.level = Log::Severity::DEBUG
    end
  end
end

# Build stage
FROM crystallang/crystal:1.17.1-alpine AS builder

WORKDIR /app

# Copy dependency files
COPY shard.yml shard.lock ./

# Install dependencies
RUN shards install --production

# Copy source code
COPY src/ src/

# Build release binary
RUN crystal build --release --static --no-debug src/user_api.cr -o bin/user_api

# Runtime stage
FROM alpine:latest

RUN apk add --no-cache ca-certificates tzdata

WORKDIR /app

# Copy binary from builder
COPY --from=builder /app/bin/user_api .

# Copy static files if any
COPY public/ public/

# Create non-root user
RUN adduser -D appuser
USER appuser

EXPOSE 8080

CMD ["./user_api"]

version: "3.8"

services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - AZU_ENV=production
      - PORT=8080
      - DATABASE_URL=postgres://user:password@db:5432/myapp_prod
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      - db
      - redis
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=myapp_prod
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:

[Unit]
Description=User API Application
After=network.target

[Service]
Type=simple
User=appuser
Group=appuser
WorkingDirectory=/opt/user-api
ExecStart=/opt/user-api/bin/user_api
Restart=always
RestartSec=5
Environment=AZU_ENV=production
Environment=PORT=8080
EnvironmentFile=/opt/user-api/.env

[Install]
WantedBy=multi-user.target

# /etc/nginx/sites-available/user-api
server {
    listen 80;
    server_name api.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

struct HealthEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Json)

  get "/health"

  def call
    json({
      status: "healthy",
      timestamp: Time.utc.to_rfc3339,
      version: "1.0.0"
    })
  end
end

#!/bin/bash
set -e

echo "Starting deployment..."

# Pull latest code
git pull origin main

# Install dependencies
shards install --production

# Build application
crystal build --release --no-debug src/user_api.cr -o bin/user_api

# Run database migrations
./bin/user_api --migrate

# Restart service
sudo systemctl restart user-api

# Verify health
sleep 5
curl -f http://localhost:8080/health || exit 1

echo "Deployment completed successfully!"

name: Deploy

on:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Crystal
        uses: crystal-lang/install-crystal@v1
        with:
          crystal: 1.17.1

      - name: Install dependencies
        run: shards install

      - name: Run tests
        run: crystal spec

  deploy:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to server
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          script: |
            cd /opt/user-api
            ./scripts/deploy.sh

struct MetricsEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Json)

  get "/metrics"

  def call
    json({
      uptime: Process.times.real.to_i,
      memory_mb: GC.stats.heap_size / (1024 * 1024),
      requests_total: RequestCounter.total
    })
  end
end

class SecurityHeaders < Azu::Handler::Base
  def call(context)
    response = context.response
    response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
    response.headers["X-Content-Type-Options"] = "nosniff"
    response.headers["X-Frame-Options"] = "DENY"
    response.headers["X-XSS-Protection"] = "1; mode=block"

    call_next(context)
  end
end

class User
  include CQL::Model(User, Int64)

  property id : Int64?
  property name : String
  property email : String
  property age : Int32?

  validate name, presence: true, length: {min: 2, max: 100}
  validate email, presence: true, format: /@/
  validate age, numericality: {greater_than: 0, less_than: 150}, allow_nil: true
end

class Order
  include CQL::Model(Order, Int64)

  property id : Int64?
  property user_id : Int64
  property total : Float64
  property items : Array(OrderItem)

  def validate
    super

    if items.empty?
      errors.add(:items, "must have at least one item")
    end

    if total <= 0
      errors.add(:total, "must be positive")
    end

    validate_inventory
  end

  private def validate_inventory
    items.each do |item|
      product = Product.find(item.product_id)
      if product && product.stock < item.quantity
        errors.add(:items, "insufficient stock for #{product.name}")
      end
    end
  end
end

class User
  include CQL::Model(User, Int64)

  property name : String
  property email : String
  property normalized_email : String?

  before_validation :normalize_email

  private def normalize_email
    @normalized_email = email.downcase.strip
  end
end

user = User.new(name: "", email: "invalid")

if user.valid?
  user.save!
else
  puts user.errors.full_messages
end

# Or use save with return value
if user.save
  puts "Saved!"
else
  puts user.errors.full_messages
end

class User
  include CQL::Model(User, Int64)

  property password : String?

  validate password, presence: true, on: :create
  validate password, length: {min: 8}, on: :create
end

# Validations run on create
user = User.new(name: "Alice", email: "alice@example.com")
user.save  # password validation runs

# Validations don't run on update for password
user.name = "Alice Smith"
user.save  # password validation skipped

class ChatChannel < Azu::Channel
  PATH = "/chat"

  def on_connect
    # Called when client connects
    send({type: "connected", message: "Welcome!"}.to_json)
  end

  def on_message(message : String)
    # Called when client sends a message
    data = JSON.parse(message)
    # Process message...
  end

  def on_close(code, reason)
    # Called when connection closes
  end
end

const socket = new WebSocket('ws://localhost:4000/chat');

socket.onopen = () => {
  console.log('Connected');
};

socket.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

socket.onclose = () => {
  console.log('Disconnected');
};

// Send a message
socket.send(JSON.stringify({
  type: 'message',
  content: 'Hello!'
}));

class ChatChannel < Azu::Channel
  PATH = "/chat"

  def on_message(message : String)
    data = JSON.parse(message)

    case data["type"]?.try(&.as_s)
    when "message"
      handle_chat_message(data)
    when "typing"
      handle_typing_indicator(data)
    when "ping"
      send({type: "pong"}.to_json)
    else
      send({type: "error", message: "Unknown message type"}.to_json)
    end
  rescue JSON::ParseException
    send({type: "error", message: "Invalid JSON"}.to_json)
  end

  private def handle_chat_message(data)
    content = data["content"]?.try(&.as_s) || ""
    # Process chat message...
  end

  private def handle_typing_indicator(data)
    # Handle typing indicator...
  end
end

class ChatChannel < Azu::Channel
  PATH = "/chat"

  CONNECTIONS = [] of HTTP::WebSocket

  def on_connect
    CONNECTIONS << socket
    broadcast_user_count
  end

  def on_close(code, reason)
    CONNECTIONS.delete(socket)
    broadcast_user_count
  end

  private def broadcast_user_count
    message = {type: "users", count: CONNECTIONS.size}.to_json
    CONNECTIONS.each(&.send(message))
  end
end

class AuthenticatedChannel < Azu::Channel
  PATH = "/secure"

  @user : User?

  def on_connect
    token = context.request.query_params["token"]?

    if token && (user = authenticate(token))
      @user = user
      send({type: "authenticated", user: user.name}.to_json)
    else
      send({type: "error", message: "Unauthorized"}.to_json)
      socket.close
    end
  end

  private def authenticate(token : String) : User?
    # Validate token and return user
    Token.validate(token)
  end
end

class RoomChannel < Azu::Channel
  PATH = "/rooms/:room_id"

  @@rooms = Hash(String, Array(HTTP::WebSocket)).new { |h, k| h[k] = [] of HTTP::WebSocket }

  def on_connect
    room_id = params["room_id"]
    @@rooms[room_id] << socket
    broadcast_to_room(room_id, {type: "joined", room: room_id}.to_json)
  end

  def on_message(message : String)
    room_id = params["room_id"]
    broadcast_to_room(room_id, message)
  end

  def on_close(code, reason)
    room_id = params["room_id"]
    @@rooms[room_id].delete(socket)
  end

  private def broadcast_to_room(room_id : String, message : String)
    @@rooms[room_id].each do |ws|
      ws.send(message) unless ws == socket
    end
  end
end

class ChatChannel < Azu::Channel
  PATH = "/chat"

  def on_message(message : String)
    process_message(message)
  rescue ex : JSON::ParseException
    send({type: "error", code: "INVALID_JSON"}.to_json)
  rescue ex : Exception
    Log.error { "WebSocket error: #{ex.message}" }
    send({type: "error", code: "INTERNAL_ERROR"}.to_json)
  end
end

class CounterComponent
  include Azu::Component

  @count = 0

  def mount(socket)
    # Called when component is mounted
    push_state
  end

  def content
    <<-HTML
    <div id="counter">
      <span>Count: #{@count}</span>
      <button azu-click="increment">+</button>
      <button azu-click="decrement">-</button>
    </div>
    HTML
  end

  on_event "increment" do
    @count += 1
    push_state
  end

  on_event "decrement" do
    @count -= 1
    push_state
  end
end

class UserCardComponent
  include Azu::Component

  property user_id : Int64
  @user : User?

  def mount(socket)
    @user = User.find(user_id)
    push_state
  end

  def content
    if user = @user
      <<-HTML
      <div class="user-card">
        <h3>#{user.name}</h3>
        <p>#{user.email}</p>
      </div>
      HTML
    else
      "<div>User not found</div>"
    end
  end
end

class TodoFormComponent
  include Azu::Component

  @todos = [] of String
  @input = ""

  def content
    <<-HTML
    <div id="todo-form">
      <input type="text"
             azu-model="input"
             value="#{@input}"
             placeholder="Add todo...">
      <button azu-click="add_todo">Add</button>

      <ul>
        #{@todos.map { |todo| "<li>#{todo}</li>" }.join}
      </ul>
    </div>
    HTML
  end

  on_event "input_change" do |value|
    @input = value.as_s
  end

  on_event "add_todo" do
    unless @input.empty?
      @todos << @input
      @input = ""
      push_state
    end
  end
end

class LifecycleComponent
  include Azu::Component

  def mount(socket)
    # Called when component first mounts
    load_initial_data
  end

  def unmount
    # Called when component is removed
    cleanup_resources
  end

  def before_update
    # Called before state update
  end

  def after_update
    # Called after state update
  end

  private def load_initial_data
    # Load data from database, etc.
  end

  private def cleanup_resources
    # Clean up subscriptions, etc.
  end
end

class NotificationComponent
  include Azu::Component

  @notifications = [] of Notification

  def mount(socket)
    # Subscribe to notification channel
    NotificationService.subscribe(current_user_id) do |notification|
      @notifications.unshift(notification)
      push_state
    end
  end

  def content
    <<-HTML
    <div class="notifications">
      #{@notifications.map { |n| render_notification(n) }.join}
    </div>
    HTML
  end

  private def render_notification(n : Notification)
    <<-HTML
    <div class="notification #{n.read? ? "" : "unread"}">
      <p>#{n.message}</p>
      <button azu-click="dismiss" azu-value="#{n.id}">Dismiss</button>
    </div>
    HTML
  end

  on_event "dismiss" do |id|
    @notifications.reject! { |n| n.id == id.as_i }
    push_state
  end
end

class ListComponent
  include Azu::Component

  @items = [] of Item

  def content
    <<-HTML
    <ul id="item-list">
      #{@items.map { |item| render_item(item) }.join}
    </ul>
    HTML
  end

  on_event "add_item" do |data|
    item = Item.new(data["name"].as_s)
    @items << item

    # Push only the new item instead of full re-render
    push_append("#item-list", render_item(item))
  end

  private def render_item(item : Item)
    %(<li id="item-#{item.id}">#{item.name}</li>)
  end
end

class ParentComponent
  include Azu::Component

  @selected_id : Int64?

  def content
    <<-HTML
    <div>
      <div azu-component="ListComponent" azu-on-select="handle_select"></div>
      <div azu-component="DetailComponent" azu-props='{"id": #{@selected_id}}'></div>
    </div>
    HTML
  end

  on_event "handle_select" do |id|
    @selected_id = id.as_i64
    push_state
  end
end

class SafeComponent
  include Azu::Component

  @error : String?

  def content
    if error = @error
      %(<div class="error">#{error}</div>)
    else
      render_content
    end
  end

  on_event "risky_action" do
    begin
      perform_risky_action
    rescue ex
      @error = "Something went wrong: #{ex.message}"
      push_state
    end
  end
end

# db/migrations/001_create_users.cr
class CreateUsers < CQL::Migration
  def up
    create_table :users do
      primary :id, Int64
      column :name, String
      column :email, String
      timestamps
    end

    create_index :users, :email, unique: true
  end

  def down
    drop_table :users
  end
end

def up
  create_table :posts do
    primary :id, Int64
    column :user_id, Int64
    column :title, String
    column :content, String
    column :published, Bool, default: false
    timestamps

    foreign_key :user_id, :users, :id
  end
end

# src/cli.cr
require "./db/schema"
require "./db/migrations/*"

case ARGV[0]?
when "db:migrate"
  CQL::Migrator.new(AcmeDB).migrate
  puts "Migrations complete"
when "db:rollback"
  CQL::Migrator.new(AcmeDB).rollback
  puts "Rollback complete"
when "db:reset"
  CQL::Migrator.new(AcmeDB).reset
  puts "Database reset"
else
  puts "Usage: crystal run src/cli.cr -- [db:migrate|db:rollback|db:reset]"
end

class BackfillUserSlugs < CQL::Migration
  def up
    add_column :users, :slug, String?

    # Backfill existing records
    AcmeDB.exec("UPDATE users SET slug = lower(replace(name, ' ', '-'))")

    # Make non-nullable after backfill
    change_column :users, :slug, String
  end

  def down
    remove_column :users, :slug
  end
end

def up
  add_column :posts, :word_count, Int32, default: 0

  # Update in batches
  offset = 0
  batch_size = 1000

  loop do
    result = AcmeDB.exec(<<-SQL, offset, batch_size)
      UPDATE posts
      SET word_count = length(content) - length(replace(content, ' ', '')) + 1
      WHERE id IN (SELECT id FROM posts LIMIT ? OFFSET ?)
    SQL

    break if result.rows_affected == 0
    offset += batch_size
  end
end

class TimingHandler < Azu::Handler::Base
  def call(context)
    start = Time.instant

    call_next(context)

    duration = Time.instant - start
    context.response.headers["X-Response-Time"] = "#{duration.total_milliseconds.round(2)}ms"
  end
end

# src/db/schema.cr
AcmeDB = CQL::Schema.define(
  :acme_db,
  adapter: CQL::Adapter::SQLite,
  uri: ENV.fetch("DATABASE_URL", "sqlite3://./db/development.db")
) do
  table :users do
    primary :id, Int64
    column :name, String
    column :email, String
    column :created_at, Time, default: -> { Time.utc }
    column :updated_at, Time, default: -> { Time.utc }
  end
end

# spec/spec_helper.cr
require "spec"
require "../src/app"

module TestHelpers
  def create_context(
    method : String = "GET",
    path : String = "/",
    body : String? = nil,
    headers : HTTP::Headers = HTTP::Headers.new
  ) : HTTP::Server::Context
    io = IO::Memory.new
    request = HTTP::Request.new(method, path, headers, body)
    response = HTTP::Server::Response.new(io)
    HTTP::Server::Context.new(request, response)
  end

  def json_headers : HTTP::Headers
    headers = HTTP::Headers.new
    headers["Content-Type"] = "application/json"
    headers
  end

  def with_auth(headers : HTTP::Headers, token : String) : HTTP::Headers
    headers["Authorization"] = "Bearer #{token}"
    headers
  end

  def parse_json_response(context) : JSON::Any
    context.response.close
    body = context.response.@io.as(IO::Memory).to_s
    JSON.parse(body.split("\r\n\r\n").last)
  end
end

module FileValidator
  ALLOWED_IMAGES = [".jpg", ".jpeg", ".png", ".gif", ".webp"]
  ALLOWED_DOCUMENTS = [".pdf", ".doc", ".docx", ".txt"]

  def self.valid_image?(filename : String) : Bool
    ext = File.extname(filename).downcase
    ALLOWED_IMAGES.includes?(ext)
  end

  def self.valid_document?(filename : String) : Bool
    ext = File.extname(filename).downcase
    ALLOWED_DOCUMENTS.includes?(ext)
  end
end

struct HomeEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Html)
  include Azu::Templates::Renderable

  get "/"

  def call
    view "home/index.html", {
      title: "Welcome",
      message: "Hello, World!"
    }
  end
end

class AuthHandler < Azu::Handler::Base
  EXCLUDED_PATHS = ["/", "/login", "/health"]

  def call(context)
    path = context.request.path

    if EXCLUDED_PATHS.includes?(path)
      return call_next(context)
    end

    token = extract_token(context)

    if token && valid_token?(token)
      # Store user in context for later use
      context.request.headers["X-User-ID"] = user_id_from_token(token).to_s
      call_next(context)
    else
      context.response.status_code = 401
      context.response.content_type = "application/json"
      context.response.print({error: "Unauthorized"}.to_json)
    end
  end

  private def extract_token(context) : String?
    auth = context.request.headers["Authorization"]?
    return nil unless auth

    if auth.starts_with?("Bearer ")
      auth[7..]
    else
      nil
    end
  end

  private def valid_token?(token : String) : Bool
    Token.valid?(token)
  end

  private def user_id_from_token(token : String) : Int64
    Token.decode(token)["user_id"].as_i64
  end
end

class CorsHandler < Azu::Handler::Base
  def initialize(
    @allowed_origins = ["*"],
    @allowed_methods = ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    @allowed_headers = ["Content-Type", "Authorization"],
    @max_age = 86400
  )
  end

  def call(context)
    origin = context.request.headers["Origin"]?

    if origin && allowed_origin?(origin)
      set_cors_headers(context, origin)
    end

    # Handle preflight
    if context.request.method == "OPTIONS"
      context.response.status_code = 204
      return
    end

    call_next(context)
  end

  private def allowed_origin?(origin : String) : Bool
    @allowed_origins.includes?("*") || @allowed_origins.includes?(origin)
  end

  private def set_cors_headers(context, origin)
    headers = context.response.headers
    headers["Access-Control-Allow-Origin"] = origin
    headers["Access-Control-Allow-Methods"] = @allowed_methods.join(", ")
    headers["Access-Control-Allow-Headers"] = @allowed_headers.join(", ")
    headers["Access-Control-Max-Age"] = @max_age.to_s
  end
end

class RateLimitHandler < Azu::Handler::Base
  def initialize(
    @limit = 100,
    @window = 1.minute
  )
  end

  def call(context)
    client_id = get_client_id(context)
    key = "ratelimit:#{client_id}"

    current = increment_counter(key)

    context.response.headers["X-RateLimit-Limit"] = @limit.to_s
    context.response.headers["X-RateLimit-Remaining"] = Math.max(0, @limit - current).to_s

    if current > @limit
      context.response.status_code = 429
      context.response.content_type = "application/json"
      context.response.print({error: "Too many requests"}.to_json)
      return
    end

    call_next(context)
  end

  private def get_client_id(context) : String
    context.request.headers["X-Forwarded-For"]? ||
      context.request.remote_address.to_s
  end

  private def increment_counter(key : String) : Int32
    count = Azu.cache.increment(key)
    Azu.cache.expire(key, @window) if count == 1
    count
  end
end

class RequestIdHandler < Azu::Handler::Base
  def call(context)
    request_id = context.request.headers["X-Request-ID"]? || generate_id

    # Set on request for logging
    context.request.headers["X-Request-ID"] = request_id

    # Include in response
    context.response.headers["X-Request-ID"] = request_id

    call_next(context)
  end

  private def generate_id : String
    UUID.random.to_s
  end
end

class CompressionHandler < Azu::Handler::Base
  MIN_SIZE = 1024  # Only compress responses > 1KB

  def call(context)
    call_next(context)

    return unless should_compress?(context)

    body = context.response.output.to_s
    return if body.bytesize < MIN_SIZE

    compressed = Compress::Gzip.compress(body)

    context.response.headers["Content-Encoding"] = "gzip"
    context.response.output = IO::Memory.new(compressed)
  end

  private def should_compress?(context) : Bool
    accept = context.request.headers["Accept-Encoding"]?
    return false unless accept

    accept.includes?("gzip")
  end
end

class ConditionalHandler < Azu::Handler::Base
  def initialize(&@condition : HTTP::Server::Context -> Bool)
  end

  def call(context)
    if @condition.call(context)
      # Do something
    end

    call_next(context)
  end
end

# Usage
ConditionalHandler.new { |ctx| ctx.request.path.starts_with?("/api") }

MyApp.start [
  RequestIdHandler.new,       # First: Add request ID
  TimingHandler.new,          # Track timing
  CorsHandler.new,            # Handle CORS
  RateLimitHandler.new,       # Enforce limits
  AuthHandler.new,            # Authenticate
  Azu::Handler::Logger.new,   # Log requests
  Azu::Handler::Rescuer.new,  # Handle errors
  # ... endpoints
]

Azu::Cache::RedisStore.new(
  url: "redis://localhost:6379/0",
  pool_size: 10,
  pool_timeout: 5.seconds,
  default_ttl: 1.hour,
  namespace: "myapp",
  ssl: false,
  password: ENV["REDIS_PASSWORD"]?
)

# Production namespace
config.cache = Azu::Cache::RedisStore.new(
  url: ENV["REDIS_URL"],
  namespace: "myapp:production"
)

# Test namespace
config.cache = Azu::Cache::RedisStore.new(
  url: ENV["REDIS_URL"],
  namespace: "myapp:test"
)

# Cache a user with associations
def cache_user(user : User)
  data = {
    id: user.id,
    name: user.name,
    email: user.email,
    posts: user.posts.map { |p| {id: p.id, title: p.title} }
  }
  Azu.cache.set("user:#{user.id}:full", data.to_json, expires_in: 15.minutes)
end

# Retrieve
def get_cached_user(id : Int64)
  json = Azu.cache.get("user:#{id}:full")
  JSON.parse(json) if json
end

struct ProductEndpoint
  include Azu::Endpoint(EmptyRequest, ProductResponse)

  get "/products/:id"

  def call : ProductResponse
    product_id = params["id"]

    # Try cache first
    cached = Azu.cache.get("product:#{product_id}")
    return ProductResponse.from_json(cached) if cached

    # Cache miss - load from database
    product = Product.find(product_id.to_i64)
    response = ProductResponse.new(product)

    # Store in cache
    Azu.cache.set("product:#{product_id}", response.to_json, expires_in: 1.hour)

    response
  end
end

class Product
  include CQL::Model(Product, Int64)

  after_save :update_cache
  after_destroy :remove_from_cache

  private def update_cache
    Azu.cache.set("product:#{id}", to_json, expires_in: 1.hour)
  end

  private def remove_from_cache
    Azu.cache.delete("product:#{id}")
  end
end

class RateLimiter
  def self.allowed?(key : String, limit : Int32, window : Time::Span) : Bool
    current = Azu.cache.increment("ratelimit:#{key}")

    if current == 1
      # Set expiration on first request
      Azu.cache.expire("ratelimit:#{key}", window)
    end

    current <= limit
  end
end

# Usage in endpoint
def call
  unless RateLimiter.allowed?(client_ip, limit: 100, window: 1.minute)
    raise Azu::Response::TooManyRequests.new
  end

  # Process request...
end

class SessionStore
  def self.create(user_id : Int64) : String
    session_id = Random::Secure.hex(32)
    Azu.cache.set(
      "session:#{session_id}",
      {user_id: user_id, created_at: Time.utc}.to_json,
      expires_in: 24.hours
    )
    session_id
  end

  def self.get(session_id : String) : Int64?
    data = Azu.cache.get("session:#{session_id}")
    return nil unless data

    JSON.parse(data)["user_id"].as_i64
  end

  def self.destroy(session_id : String)
    Azu.cache.delete("session:#{session_id}")
  end
end

struct HealthEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Json)

  get "/health"

  def call
    redis_ok = begin
      Azu.cache.set("health_check", "ok", expires_in: 1.second)
      true
    rescue
      false
    end

    json({
      status: redis_ok ? "healthy" : "degraded",
      redis: redis_ok
    })
  end
end

# Store a value
Azu.cache.set("user:1", user.to_json)

# Retrieve a value
json = Azu.cache.get("user:1")
if json
  user = User.from_json(json)
end

# With expiration (TTL)
Azu.cache.set("session:abc123", session_data, expires_in: 30.minutes)

struct UserEndpoint
  include Azu::Endpoint(EmptyRequest, UserResponse)

  get "/users/:id"

  def call : UserResponse
    user_id = params["id"]
    cache_key = "user:#{user_id}"

    cached = Azu.cache.get(cache_key)
    if cached
      return UserResponse.from_json(cached)
    end

    user = User.find(user_id.to_i64)
    response = UserResponse.new(user)

    Azu.cache.set(cache_key, response.to_json, expires_in: 10.minutes)

    response
  end
end

Azu.configure do |config|
  config.cache = Azu::Cache::MemoryStore.new(
    max_size: 10_000,           # Maximum number of entries
    default_ttl: 1.hour,        # Default expiration
    cleanup_interval: 5.minutes # How often to clean expired entries
  )
end

module CacheKeys
  def self.user(id)
    "users:#{id}"
  end

  def self.user_posts(user_id)
    "users:#{user_id}:posts"
  end

  def self.post(id)
    "posts:#{id}"
  end
end

# Usage
Azu.cache.set(CacheKeys.user(user.id), user.to_json)

class User
  include CQL::Model(User, Int64)

  after_save :invalidate_cache
  after_destroy :invalidate_cache

  private def invalidate_cache
    Azu.cache.delete("user:#{id}")
    Azu.cache.delete("user:#{id}:posts")
    Azu.cache.delete("users:list")
  end
end

table :products do
  primary :id, Int64
  column :name, String                    # VARCHAR/TEXT
  column :description, String?            # Nullable
  column :price, Float64                  # REAL/DOUBLE
  column :quantity, Int32                 # INTEGER
  column :active, Bool, default: true     # BOOLEAN
  column :metadata, JSON::Any?            # JSON
end

table :orders do
  primary :id, Int64
  column :status, String, default: "pending"
  column :order_number, String, default: -> { generate_order_number }
  column :created_at, Time, default: -> { Time.utc }
end

table :post_tags do
  primary :id, Int64
  column :post_id, Int64
  column :tag_id, Int64

  foreign_key :post_id, :posts, :id
  foreign_key :tag_id, :tags, :id

  index [:post_id, :tag_id], unique: true
end

table :users do
  primary :id, Int64
  column :email, String
  column :username, String
  column :organization_id, Int64

  index :email, unique: true
  index :username, unique: true
  index :organization_id  # Non-unique index
  index [:organization_id, :username], unique: true  # Composite
end

AcmeDB = CQL::Schema.define(:acme_db, adapter: CQL::Adapter::SQLite, uri: db_uri) do
  table :users do
    primary :id, Int64
    column :name, String
    column :email, String
    timestamps
  end

  table :posts do
    primary :id, Int64
    column :user_id, Int64
    column :title, String
    column :content, String
    column :published, Bool, default: false
    timestamps

    foreign_key :user_id, :users, :id
    index :user_id
  end

  table :comments do
    primary :id, Int64
    column :post_id, Int64
    column :user_id, Int64
    column :content, String
    timestamps

    foreign_key :post_id, :posts, :id
    foreign_key :user_id, :users, :id
  end
end

def database_uri
  case ENV.fetch("AZU_ENV", "development")
  when "production"
    ENV["DATABASE_URL"]
  when "test"
    "sqlite3://./db/test.db"
  else
    "sqlite3://./db/development.db"
  end
end

AcmeDB = CQL::Schema.define(:acme_db, adapter: CQL::Adapter::SQLite, uri: database_uri)

user = AcmeDB.transaction do
  user = User.create!(name: "Alice", email: "alice@example.com")
  Profile.create!(user_id: user.id)
  user  # Return the user
end

puts user.id  # Use the created user

begin
  AcmeDB.transaction do
    transfer_funds(from_account, to_account, amount)
  end
  puts "Transfer successful"
rescue ex : CQL::TransactionError
  puts "Transaction failed: #{ex.message}"
rescue ex : CQL::RecordInvalid
  puts "Validation failed: #{ex.message}"
end

AcmeDB.transaction do
  user = User.create!(name: "Alice", email: "alice@example.com")

  AcmeDB.transaction(savepoint: true) do
    # This is a savepoint, not a new transaction
    create_optional_resources(user)
  rescue
    # Only this inner block is rolled back
    Log.warn { "Optional resources failed" }
  end

  # User creation is preserved
  create_required_resources(user)
end

AcmeDB.transaction(isolation: :serializable) do
  # Highest isolation level
  process_financial_transaction
end

# Available levels:
# :read_uncommitted
# :read_committed
# :repeatable_read
# :serializable

def transfer(from_id : Int64, to_id : Int64, amount : Float64)
  raise "Invalid amount" if amount <= 0

  AcmeDB.transaction do
    # Lock both accounts to prevent race conditions
    from = Account.lock.find(from_id)
    to = Account.lock.find(to_id)

    raise "Insufficient funds" if from.balance < amount

    from.balance -= amount
    to.balance += amount

    from.save!
    to.save!

    # Record the transaction
    Transaction.create!(
      from_account_id: from_id,
      to_account_id: to_id,
      amount: amount,
      completed_at: Time.utc
    )
  end
end

def import_users(records : Array(Hash))
  # Process in batches of 100
  records.each_slice(100) do |batch|
    AcmeDB.transaction do
      batch.each do |data|
        User.create!(
          name: data["name"],
          email: data["email"]
        )
      end
    end
  end
end

class Order
  include CQL::Model(Order, Int64)

  after_commit :send_confirmation_email, on: :create
  after_rollback :log_failure

  private def send_confirmation_email
    # Only runs if transaction commits
    Mailer.order_confirmation(self).deliver
  end

  private def log_failure
    Log.error { "Order creation rolled back: #{id}" }
  end
end

# Good: Short, focused transaction
AcmeDB.transaction do
  order.status = "completed"
  order.save!
  inventory.reduce!(order.items)
end

# Then do external operations
send_notification(order)  # Outside transaction

Azu.configure do |config|
  case ENV.fetch("AZU_ENV", "development")
  when "production"
    config.log.level = Log::Severity::Info
  when "test"
    config.log.level = Log::Severity::Warn
  else
    config.log.level = Log::Severity::Debug
  end
end

class StructuredLogger < Azu::Handler::Base
  def call(context)
    start = Time.instant
    request_id = context.request.headers["X-Request-ID"]?

    begin
      call_next(context)
    ensure
      duration = Time.instant - start
      log_request(context, duration, request_id)
    end
  end

  private def log_request(context, duration, request_id)
    Log.info { {
      request_id: request_id,
      method: context.request.method,
      path: context.request.path,
      status: context.response.status_code,
      duration_ms: duration.total_milliseconds.round(2),
      remote_ip: client_ip(context),
      user_agent: context.request.headers["User-Agent"]?
    }.to_json }
  end

  private def client_ip(context) : String
    context.request.headers["X-Forwarded-For"]?.try(&.split(",").first.strip) ||
      context.request.remote_address.to_s
  end
end

struct CreateUserEndpoint
  include Azu::Endpoint(CreateUserRequest, UserResponse)

  post "/users"

  def call : UserResponse
    Log.debug { "Creating user with email: #{create_user_request.email}" }

    user = User.create!(create_user_request)

    Log.info { "User created: id=#{user.id}, email=#{user.email}" }

    UserResponse.new(user)
  rescue ex
    Log.error(exception: ex) { "Failed to create user" }
    raise ex
  end
end

class JsonLogBackend < Log::Backend
  def initialize(@io : IO = STDOUT)
  end

  def write(entry : Log::Entry)
    data = {
      timestamp: entry.timestamp.to_rfc3339,
      severity: entry.severity.to_s,
      source: entry.source,
      message: entry.message,
      data: entry.data.to_h,
    }

    if ex = entry.exception
      data = data.merge({
        exception: ex.class.name,
        exception_message: ex.message,
        backtrace: ex.backtrace?.try(&.first(10))
      })
    end

    @io.puts data.to_json
  end
end

Log.setup do |config|
  config.bind "*", :info, JsonLogBackend.new
end

Log.setup do |config|
  stdout = Log::IOBackend.new
  file = Log::IOBackend.new(File.new("log/app.log", "a"))

  # Development: stdout only
  if ENV["AZU_ENV"]? == "development"
    config.bind "*", :debug, stdout
  else
    # Production: file for all, stdout for errors
    config.bind "*", :info, file
    config.bind "*", :error, stdout
  end
end

class ContextLogger
  Log = ::Log.for(self)

  def self.with_context(request_id : String, user_id : Int64? = nil, &)
    Log.context.set(request_id: request_id)
    Log.context.set(user_id: user_id.to_s) if user_id

    yield
  ensure
    Log.context.clear
  end
end

# Usage in handler
class RequestContextHandler < Azu::Handler::Base
  def call(context)
    request_id = context.request.headers["X-Request-ID"]? || UUID.random.to_s
    user_id = context.request.headers["X-User-ID"]?.try(&.to_i64)

    ContextLogger.with_context(request_id, user_id) do
      call_next(context)
    end
  end
end

class ErrorLogger < Azu::Handler::Base
  Log = ::Log.for(self)

  def call(context)
    call_next(context)
  rescue ex
    log_error(context, ex)
    raise ex
  end

  private def log_error(context, ex : Exception)
    Log.error(exception: ex) { {
      error: ex.class.name,
      message: ex.message,
      path: context.request.path,
      method: context.request.method,
      request_id: context.request.headers["X-Request-ID"]?
    }.to_json }
  end
end

module LogFilter
  SENSITIVE_KEYS = ["password", "token", "secret", "api_key", "authorization"]

  def self.filter(data : Hash) : Hash
    data.transform_values do |value|
      case value
      when Hash
        filter(value)
      when String
        SENSITIVE_KEYS.any? { |k| data.keys.any?(&.downcase.includes?(k)) } ? "[FILTERED]" : value
      else
        value
      end
    end
  end
end

class SlowRequestLogger < Azu::Handler::Base
  THRESHOLD = 1.second

  def call(context)
    start = Time.instant
    call_next(context)
    duration = Time.instant - start

    if duration > THRESHOLD
      Log.warn { "Slow request: #{context.request.method} #{context.request.path} took #{duration.total_seconds.round(2)}s" }
    end
  end
end

# spec/endpoints/show_user_endpoint_spec.cr
require "../spec_helper"

describe ShowUserEndpoint do
  include TestHelpers

  before_each do
    User.delete_all
  end

  describe "#call" do
    it "returns user when found" do
      user = User.create!(name: "Alice", email: "alice@example.com")

      context = create_context("GET", "/users/#{user.id}")
      endpoint = ShowUserEndpoint.new
      endpoint.context = context
      endpoint.params = {"id" => user.id.to_s}

      response = endpoint.call

      response.should be_a(UserResponse)
      context.response.status_code.should eq(200)
    end

    it "returns 404 for non-existent user" do
      context = create_context("GET", "/users/999")
      endpoint = ShowUserEndpoint.new
      endpoint.context = context
      endpoint.params = {"id" => "999"}

      expect_raises(Azu::Response::NotFound) do
        endpoint.call
      end
    end
  end
end

# spec/endpoints/create_user_endpoint_spec.cr
require "../spec_helper"

describe CreateUserEndpoint do
  include TestHelpers

  before_each do
    User.delete_all
  end

  describe "#call" do
    it "creates user with valid data" do
      body = {name: "Alice", email: "alice@example.com", age: 30}.to_json

      context = create_context("POST", "/users", body, json_headers)
      endpoint = CreateUserEndpoint.new
      endpoint.context = context

      response = endpoint.call

      response.should be_a(UserResponse)
      context.response.status_code.should eq(201)

      User.count.should eq(1)
    end

    it "returns validation error for missing name" do
      body = {email: "alice@example.com"}.to_json

      context = create_context("POST", "/users", body, json_headers)
      endpoint = CreateUserEndpoint.new
      endpoint.context = context

      expect_raises(Azu::Response::ValidationError) do
        endpoint.call
      end
    end

    it "returns validation error for invalid email" do
      body = {name: "Alice", email: "invalid"}.to_json

      context = create_context("POST", "/users", body, json_headers)
      endpoint = CreateUserEndpoint.new
      endpoint.context = context

      expect_raises(Azu::Response::ValidationError) do
        endpoint.call
      end
    end
  end
end

describe UpdateUserEndpoint do
  include TestHelpers

  it "updates user attributes" do
    user = User.create!(name: "Alice", email: "alice@example.com")
    body = {name: "Alice Smith"}.to_json

    context = create_context("PUT", "/users/#{user.id}", body, json_headers)
    endpoint = UpdateUserEndpoint.new
    endpoint.context = context
    endpoint.params = {"id" => user.id.to_s}

    response = endpoint.call

    response.should be_a(UserResponse)
    User.find(user.id).name.should eq("Alice Smith")
  end
end

describe DeleteUserEndpoint do
  include TestHelpers

  it "deletes the user" do
    user = User.create!(name: "Alice", email: "alice@example.com")

    context = create_context("DELETE", "/users/#{user.id}")
    endpoint = DeleteUserEndpoint.new
    endpoint.context = context
    endpoint.params = {"id" => user.id.to_s}

    endpoint.call

    context.response.status_code.should eq(204)
    User.find?(user.id).should be_nil
  end
end

describe ProtectedEndpoint do
  include TestHelpers

  it "returns 401 without token" do
    context = create_context("GET", "/protected")
    endpoint = ProtectedEndpoint.new
    endpoint.context = context

    expect_raises(Azu::Response::Unauthorized) do
      endpoint.call
    end
  end

  it "succeeds with valid token" do
    user = User.create!(name: "Alice", email: "alice@example.com")
    token = Token.create(user_id: user.id)

    headers = with_auth(json_headers, token)
    context = create_context("GET", "/protected", nil, headers)
    endpoint = ProtectedEndpoint.new
    endpoint.context = context

    response = endpoint.call
    context.response.status_code.should eq(200)
  end
end

# spec/integration/users_api_spec.cr
require "../spec_helper"
require "http/client"

describe "Users API" do
  BASE_URL = "http://localhost:4000"

  before_all do
    # Start server in background
    spawn { MyApp.start }
    sleep 1.second
  end

  describe "POST /users" do
    it "creates a new user" do
      response = HTTP::Client.post(
        "#{BASE_URL}/users",
        headers: HTTP::Headers{"Content-Type" => "application/json"},
        body: {name: "Test User", email: "test@example.com"}.to_json
      )

      response.status_code.should eq(201)

      data = JSON.parse(response.body)
      data["name"].should eq("Test User")
      data["email"].should eq("test@example.com")
    end
  end

  describe "GET /users/:id" do
    it "returns the user" do
      # Create user first
      create_response = HTTP::Client.post(
        "#{BASE_URL}/users",
        headers: HTTP::Headers{"Content-Type" => "application/json"},
        body: {name: "Test", email: "test@example.com"}.to_json
      )
      user_id = JSON.parse(create_response.body)["id"]

      # Get user
      response = HTTP::Client.get("#{BASE_URL}/users/#{user_id}")

      response.status_code.should eq(200)
      JSON.parse(response.body)["id"].should eq(user_id)
    end
  end
end

it "returns correct JSON structure" do
  user = User.create!(name: "Alice", email: "alice@example.com")
  context = create_context("GET", "/users/#{user.id}")
  endpoint = ShowUserEndpoint.new
  endpoint.context = context
  endpoint.params = {"id" => user.id.to_s}

  endpoint.call

  json = parse_json_response(context)

  json["id"].should eq(user.id)
  json["name"].should eq("Alice")
  json["email"].should eq("alice@example.com")
  json.as_h.has_key?("password").should be_false
end

# Run all tests
crystal spec

# Run specific file
crystal spec spec/endpoints/create_user_endpoint_spec.cr

# Run with verbose output
crystal spec --verbose

# Run tagged tests
crystal spec --tag focus

Azu.configure do |config|
  case ENV.fetch("AZU_ENV", "development")
  when "development"
    config.template_hot_reload = true
    config.log.level = Log::Severity::Debug
  when "production"
    config.template_hot_reload = false
    config.log.level = Log::Severity::Info
  end
end

class LiveReloadChannel < Azu::Channel
  PATH = "/livereload"

  CONNECTIONS = [] of HTTP::WebSocket

  def on_connect
    CONNECTIONS << socket
  end

  def on_close(code, reason)
    CONNECTIONS.delete(socket)
  end

  def self.trigger_reload
    CONNECTIONS.each do |ws|
      ws.send({type: "reload"}.to_json)
    end
  end
end

<script>
  if (location.hostname === 'localhost') {
    const ws = new WebSocket('ws://localhost:4000/livereload');
    ws.onmessage = (e) => {
      const data = JSON.parse(e.data);
      if (data.type === 'reload') {
        location.reload();
      }
    };
  }
</script>

# scripts/dev.cr
require "file_utils"

WATCH_DIRS = ["src", "views"]
EXTENSIONS = [".cr", ".html", ".css", ".js"]

def run_server
  Process.new(
    "crystal",
    ["run", "src/app.cr"],
    output: STDOUT,
    error: STDERR
  )
end

def file_changed?(path : String) : Bool
  EXTENSIONS.any? { |ext| path.ends_with?(ext) }
end

server = run_server

loop do
  # Simple polling approach
  sleep 1.second

  changed = false
  WATCH_DIRS.each do |dir|
    Dir.glob("#{dir}/**/*").each do |file|
      if file_changed?(file) && File.info(file).modification_time > 1.second.ago
        changed = true
        break
      end
    end
  end

  if changed
    puts "Change detected, restarting..."
    server.signal(:term)
    server = run_server
  end
end

ALLOWED_CONTENT_TYPES = {
  "image/jpeg" => [".jpg", ".jpeg"],
  "image/png" => [".png"],
  "image/gif" => [".gif"],
  "application/pdf" => [".pdf"],
}

def valid_content_type?(file : HTTP::FormData::File) : Bool
  content_type = file.headers["Content-Type"]?
  return false unless content_type

  filename = file.filename || ""
  ext = File.extname(filename).downcase

  if allowed_exts = ALLOWED_CONTENT_TYPES[content_type]?
    allowed_exts.includes?(ext)
  else
    false
  end
end

module MagicNumber
  SIGNATURES = {
    jpeg: Bytes[0xFF, 0xD8, 0xFF],
    png: Bytes[0x89, 0x50, 0x4E, 0x47],
    gif: Bytes[0x47, 0x49, 0x46],
    pdf: Bytes[0x25, 0x50, 0x44, 0x46],
    zip: Bytes[0x50, 0x4B, 0x03, 0x04],
  }

  def self.detect(io : IO) : Symbol?
    buffer = Bytes.new(8)
    io.read(buffer)
    io.rewind  # Reset position

    SIGNATURES.each do |type, signature|
      if buffer[0, signature.size] == signature
        return type
      end
    end

    nil
  end

  def self.image?(io : IO) : Bool
    type = detect(io)
    [:jpeg, :png, :gif].includes?(type)
  end

  def self.pdf?(io : IO) : Bool
    detect(io) == :pdf
  end
end

class FileValidationError < Exception; end

module SecureFileValidator
  ALLOWED_TYPES = {
    image: {
      extensions: [".jpg", ".jpeg", ".png", ".gif"],
      content_types: ["image/jpeg", "image/png", "image/gif"],
      magic_check: ->(io : IO) { MagicNumber.image?(io) }
    },
    document: {
      extensions: [".pdf"],
      content_types: ["application/pdf"],
      magic_check: ->(io : IO) { MagicNumber.pdf?(io) }
    }
  }

  def self.validate!(file : HTTP::FormData::File, type : Symbol)
    config = ALLOWED_TYPES[type]?
    raise FileValidationError.new("Unknown file type category") unless config

    filename = file.filename || "unknown"
    ext = File.extname(filename).downcase
    content_type = file.headers["Content-Type"]?

    # Check extension
    unless config[:extensions].includes?(ext)
      raise FileValidationError.new("Invalid file extension: #{ext}")
    end

    # Check content type
    unless content_type && config[:content_types].includes?(content_type)
      raise FileValidationError.new("Invalid content type: #{content_type}")
    end

    # Check magic number
    unless config[:magic_check].call(file.body)
      raise FileValidationError.new("File content does not match declared type")
    end

    true
  end
end

struct ImageUploadRequest
  include Azu::Request

  ALLOWED_EXTENSIONS = [".jpg", ".jpeg", ".png", ".gif"]
  MAX_SIZE = 5 * 1024 * 1024  # 5 MB

  getter image : HTTP::FormData::File

  def initialize(@image)
  end

  def validate
    super

    validate_extension
    validate_size
    validate_content
  end

  private def validate_extension
    ext = File.extname(image.filename || "").downcase
    unless ALLOWED_EXTENSIONS.includes?(ext)
      errors << Error.new(:image, "must be JPG, PNG, or GIF")
    end
  end

  private def validate_size
    if image.body.size > MAX_SIZE
      errors << Error.new(:image, "must be smaller than 5 MB")
    end
  end

  private def validate_content
    unless MagicNumber.image?(image.body)
      errors << Error.new(:image, "is not a valid image file")
    end
  end
end

def safe_filename(original : String) : String
  # Remove path components
  name = File.basename(original)

  # Remove dangerous characters
  name = name.gsub(/[^a-zA-Z0-9._-]/, "_")

  # Ensure it doesn't start with a dot
  name = "_#{name}" if name.starts_with?(".")

  # Add unique prefix
  "#{UUID.random}_#{name}"
end

def validate_filename(name : String) : Bool
  # Reject double extensions like "file.php.jpg"
  parts = name.split(".")
  return false if parts.size > 2

  # Reject executable extensions anywhere
  dangerous = [".php", ".exe", ".sh", ".bat", ".cmd", ".js"]
  parts.none? { |p| dangerous.includes?(".#{p.downcase}") }
end

def validate_image_dimensions(file : HTTP::FormData::File, max_width = 4096, max_height = 4096)
  # Use ImageMagick identify
  result = Process.run("identify", ["-format", "%wx%h", "-"], input: file.body)

  dimensions = result.output.to_s.strip.split("x")
  width = dimensions[0].to_i
  height = dimensions[1].to_i

  file.body.rewind

  width <= max_width && height <= max_height
end

module VirusScanner
  def self.scan(file_path : String) : Bool
    result = Process.run("clamscan", ["--no-summary", file_path])
    result.exit_code == 0  # 0 means no virus found
  end

  def self.scan_io(io : IO) : Bool
    # Save to temp file for scanning
    temp_path = File.tempname("scan")
    File.write(temp_path, io.gets_to_end)
    io.rewind

    result = scan(temp_path)
    File.delete(temp_path)
    result
  end
end

views/
├── layouts/
│   └── application.html
├── home/
│   └── index.html
├── users/
│   ├── index.html
│   ├── show.html
│   └── edit.html
└── shared/
    ├── _header.html
    └── _footer.html

<!-- views/home/index.html -->
<!DOCTYPE html>
<html>
<head>
  <title>{{ title }}</title>
</head>
<body>
  <h1>{{ message }}</h1>

  {% if user %}
    <p>Welcome, {{ user.name }}!</p>
  {% else %}
    <p>Please log in.</p>
  {% endif %}
</body>
</html>

<h1>{{ user.name }}</h1>
<p>Email: {{ user.email }}</p>

{% if is_admin %}
  <a href="/admin">Admin Panel</a>
{% endif %}

<h2>Recent Posts</h2>
<ul>
{% for post in posts %}
  <li>{{ post.title }}</li>
{% endfor %}
</ul>

<!-- views/layouts/application.html -->
<!DOCTYPE html>
<html>
<head>
  <title>{% block title %}My App{% endblock %}</title>
  <link rel="stylesheet" href="/css/app.css">
</head>
<body>
  <header>
    {% include "shared/_header.html" %}
  </header>

  <main>
    {% block content %}{% endblock %}
  </main>

  <footer>
    {% include "shared/_footer.html" %}
  </footer>
</body>
</html>

<!-- views/users/index.html -->
{% extends "layouts/application.html" %}

{% block title %}Users - My App{% endblock %}

{% block content %}
<h1>Users</h1>
<ul>
{% for user in users %}
  <li>{{ user.name }}</li>
{% endfor %}
</ul>
{% endblock %}

{% macro input(name, value="", type="text") %}
<input type="{{ type }}" name="{{ name }}" value="{{ value }}" class="form-input">
{% endmacro %}

{{ input("email", user.email, "email") }}
{{ input("password", type="password") }}

# Build stage
FROM crystallang/crystal:1.17.1-alpine AS builder

WORKDIR /app

# Copy dependency files
COPY shard.yml shard.lock ./

# Install dependencies
RUN shards install --production

# Copy source code
COPY src/ src/

# Build release binary
RUN crystal build --release --static --no-debug src/app.cr -o bin/app

# Runtime stage
FROM alpine:3.19

RUN apk add --no-cache ca-certificates tzdata

WORKDIR /app

# Copy binary from builder
COPY --from=builder /app/bin/app .

# Copy static assets if any
COPY public/ public/
COPY views/ views/

# Create non-root user
RUN adduser -D -u 1000 appuser
USER appuser

EXPOSE 8080

ENV AZU_ENV=production
ENV PORT=8080

CMD ["./app"]

class NotFoundError < Azu::Response::Error
  def initialize(resource : String, id : String | Int64)
    super("#{resource} with id #{id} not found", 404)
  end
end

# Usage
raise NotFoundError.new("User", params["id"])

# spec/support/mock_websocket.cr
class MockWebSocket
  getter sent_messages = [] of String
  getter closed = false
  getter close_code : Int32?
  getter close_reason : String?

  def send(message : String)
    @sent_messages << message
  end

  def close(code : Int32? = nil, reason : String? = nil)
    @closed = true
    @close_code = code
    @close_reason = reason
  end

  def object_id
    0_u64
  end
end

module MyApp
  include Azu

  configure do
    port = ENV.fetch("PORT", "8080").to_i
    host = ENV.fetch("HOST", "0.0.0.0")

    case ENV.fetch("AZU_ENV", "development")
    when "production"
      log.level = Log::Severity::Info
      template_hot_reload = false
    when "test"
      log.level = Log::Severity::Warn
    else
      log.level = Log::Severity::Debug
      template_hot_reload = true
    end
  end
end

class MyChannel < Azu::Channel
  PATH = "/ws/path"

  def on_connect
    # Handle connection
  end

  def on_message(message : String)
    # Handle message
  end

  def on_close(code, reason)
    # Handle disconnection
  end
end

# Build the image
docker build -t myapp:latest .

# Run the container
docker run -p 8080:8080 \
  -e DATABASE_URL=postgres://... \
  -e REDIS_URL=redis://... \
  myapp:latest

# Run with env file
docker run -p 8080:8080 --env-file .env.production myapp:latest

version: "3.8"

services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - AZU_ENV=production
      - PORT=8080
      - DATABASE_URL=postgres://user:password@db:5432/myapp
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d myapp"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:

version: "3.8"

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - "4000:4000"
    volumes:
      - .:/app
      - /app/lib  # Exclude lib directory
    environment:
      - AZU_ENV=development
      - PORT=4000
      - DATABASE_URL=postgres://user:password@db:5432/myapp_dev
    depends_on:
      - db
      - redis

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=myapp_dev
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    ports:
      - "5432:5432"
    volumes:
      - postgres_dev_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_dev_data:

# Dockerfile.dev
FROM crystallang/crystal:1.17.1

WORKDIR /app

RUN apt-get update && apt-get install -y watchexec

COPY shard.yml shard.lock ./
RUN shards install

COPY . .

CMD ["watchexec", "-r", "-e", "cr", "crystal", "run", "src/app.cr"]

version: "3.8"

services:
  app:
    build: .
    expose:
      - "8080"
    environment:
      - AZU_ENV=production
      - DATABASE_URL=postgres://user:password@db:5432/myapp
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      - db
      - redis
    restart: unless-stopped
    deploy:
      replicas: 2

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - app
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:

# nginx.conf
events {
    worker_connections 1024;
}

http {
    upstream app {
        server app:8080;
    }

    server {
        listen 80;
        server_name example.com;
        return 301 https://$host$request_uri;
    }

    server {
        listen 443 ssl http2;
        server_name example.com;

        ssl_certificate /etc/nginx/certs/fullchain.pem;
        ssl_certificate_key /etc/nginx/certs/privkey.pem;

        location / {
            proxy_pass http://app;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
    }
}

# Docker Hub
docker tag myapp:latest username/myapp:latest
docker push username/myapp:latest

# GitHub Container Registry
docker tag myapp:latest ghcr.io/username/myapp:latest
docker push ghcr.io/username/myapp:latest

# AWS ECR
aws ecr get-login-password | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com
docker tag myapp:latest 123456789.dkr.ecr.us-east-1.amazonaws.com/myapp:latest
docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/myapp:latest

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build image
        run: docker build -t myapp:${{ github.sha }} .

      - name: Push to registry
        run: |
          echo ${{ secrets.DOCKER_PASSWORD }} | docker login -u ${{ secrets.DOCKER_USERNAME }} --password-stdin
          docker push myapp:${{ github.sha }}

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to server
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          script: |
            docker pull myapp:${{ github.sha }}
            docker-compose up -d

class ValidationError < Azu::Response::Error
  getter errors : Array(FieldError)

  def initialize(@errors : Array(FieldError))
    super("Validation failed", 422)
  end

  def to_json(io : IO)
    {
      error: message,
      details: errors.map { |e| {field: e.field, message: e.message} }
    }.to_json(io)
  end
end

record FieldError, field : String, message : String

# Payment errors
class PaymentError < Azu::Response::Error
  def initialize(message : String)
    super(message, 402)  # Payment Required
  end
end

class InsufficientFundsError < PaymentError
  def initialize(required : Float64, available : Float64)
    super("Insufficient funds: need $#{required}, have $#{available}")
  end
end

class PaymentDeclinedError < PaymentError
  getter decline_code : String

  def initialize(@decline_code : String)
    super("Payment declined: #{decline_code}")
  end
end

# Inventory errors
class InventoryError < Azu::Response::Error
  def initialize(message : String)
    super(message, 422)
  end
end

class OutOfStockError < InventoryError
  def initialize(product_name : String)
    super("#{product_name} is out of stock")
  end
end

module Errors
  # Base application error
  abstract class AppError < Azu::Response::Error
    getter code : String

    def initialize(message : String, status : Int32, @code : String)
      super(message, status)
    end

    def to_json(io : IO)
      {
        error: {
          code: code,
          message: message
        }
      }.to_json(io)
    end
  end

  # Client errors (4xx)
  class BadRequest < AppError
    def initialize(message : String, code = "BAD_REQUEST")
      super(message, 400, code)
    end
  end

  class Unauthorized < AppError
    def initialize(message = "Authentication required")
      super(message, 401, "UNAUTHORIZED")
    end
  end

  class Forbidden < AppError
    def initialize(message = "Access denied")
      super(message, 403, "FORBIDDEN")
    end
  end

  class NotFound < AppError
    def initialize(resource : String)
      super("#{resource} not found", 404, "NOT_FOUND")
    end
  end

  class Conflict < AppError
    def initialize(message : String)
      super(message, 409, "CONFLICT")
    end
  end

  class ValidationFailed < AppError
    getter details : Array(Hash(String, String))

    def initialize(@details : Array(Hash(String, String)))
      super("Validation failed", 422, "VALIDATION_FAILED")
    end

    def to_json(io : IO)
      {
        error: {
          code: code,
          message: message,
          details: details
        }
      }.to_json(io)
    end
  end

  # Server errors (5xx)
  class InternalError < AppError
    def initialize(message = "Internal server error")
      super(message, 500, "INTERNAL_ERROR")
    end
  end

  class ServiceUnavailable < AppError
    def initialize(service : String)
      super("#{service} is temporarily unavailable", 503, "SERVICE_UNAVAILABLE")
    end
  end
end

class ApiError < Azu::Response::Error
  getter code : String
  getter details : Hash(String, JSON::Any)?
  getter request_id : String?

  def initialize(
    message : String,
    status : Int32,
    @code : String,
    @details : Hash(String, JSON::Any)? = nil,
    @request_id : String? = nil
  )
    super(message, status)
  end

  def to_json(io : IO)
    response = {
      error: {
        code: code,
        message: message,
        timestamp: Time.utc.to_rfc3339
      }
    }

    response[:error][:details] = details if details
    response[:error][:request_id] = request_id if request_id

    response.to_json(io)
  end
end

class CustomErrorHandler < Azu::Handler::Base
  def call(context)
    call_next(context)
  rescue ex : Errors::AppError
    context.response.status_code = ex.status
    context.response.content_type = "application/json"
    ex.to_json(context.response)
  rescue ex : Azu::Response::Error
    context.response.status_code = ex.status
    context.response.content_type = "application/json"
    {error: ex.message}.to_json(context.response)
  end
end

struct TransferFundsEndpoint
  include Azu::Endpoint(TransferRequest, TransferResponse)

  post "/transfers"

  def call : TransferResponse
    from_account = Account.find?(transfer_request.from_account_id)
    raise Errors::NotFound.new("Source account") unless from_account

    to_account = Account.find?(transfer_request.to_account_id)
    raise Errors::NotFound.new("Destination account") unless to_account

    amount = transfer_request.amount
    raise Errors::BadRequest.new("Amount must be positive") if amount <= 0

    if from_account.balance < amount
      raise InsufficientFundsError.new(amount, from_account.balance)
    end

    transfer = Transfer.execute!(from_account, to_account, amount)
    TransferResponse.new(transfer)
  end
end

# Each error code has a specific meaning:
#
# Client Errors:
# - BAD_REQUEST (400): The request was malformed
# - UNAUTHORIZED (401): Authentication is required
# - FORBIDDEN (403): You don't have permission
# - NOT_FOUND (404): The resource doesn't exist
# - VALIDATION_FAILED (422): Input validation failed
#
# Server Errors:
# - INTERNAL_ERROR (500): Something went wrong on our end
# - SERVICE_UNAVAILABLE (503): A dependent service is down

class SessionStore
  def self.create(user_id : Int64) : String
    session_id = Random::Secure.hex(32)
    Azu.cache.set(
      "session:#{session_id}",
      {user_id: user_id, created_at: Time.utc}.to_json,
      expires_in: 24.hours
    )
    session_id
  end

  def self.get(session_id : String) : Int64?
    data = Azu.cache.get("session:#{session_id}")
    return nil unless data
    JSON.parse(data)["user_id"].as_i64
  end
end

upstream app_servers {
    least_conn;  # Use least connections algorithm
    server app1:8080;
    server app2:8080;
    server app3:8080;
}

server {
    listen 80;

    location / {
        proxy_pass http://app_servers;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /health {
        proxy_pass http://app_servers;
        proxy_connect_timeout 1s;
        proxy_read_timeout 1s;
    }
}

frontend http_front
    bind *:80
    default_backend app_servers

backend app_servers
    balance roundrobin
    option httpchk GET /health
    http-check expect status 200

    server app1 app1:8080 check inter 5s fall 3 rise 2
    server app2 app2:8080 check inter 5s fall 3 rise 2
    server app3 app3:8080 check inter 5s fall 3 rise 2

# docker-compose.swarm.yml
version: "3.8"

services:
  app:
    image: myapp:latest
    deploy:
      replicas: 3
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
      resources:
        limits:
          cpus: "0.5"
          memory: 512M
    environment:
      - AZU_ENV=production
      - DATABASE_URL=postgres://...
      - REDIS_URL=redis://redis:6379/0
    networks:
      - app_network

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    deploy:
      placement:
        constraints:
          - node.role == manager
    networks:
      - app_network

  redis:
    image: redis:7-alpine
    deploy:
      replicas: 1
    networks:
      - app_network

networks:
  app_network:
    driver: overlay

# kubernetes/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: app
          image: myapp:latest
          ports:
            - containerPort: 8080
          env:
            - name: AZU_ENV
              value: "production"
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: myapp-secrets
                  key: database-url
          resources:
            limits:
              cpu: "500m"
              memory: "512Mi"
            requests:
              cpu: "250m"
              memory: "256Mi"
          livenessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: myapp
spec:
  selector:
    app: myapp
  ports:
    - port: 80
      targetPort: 8080
  type: LoadBalancer
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: myapp-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: myapp
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70

class ScalableNotificationChannel < Azu::Channel
  PATH = "/notifications"

  @@redis = Redis.new(url: ENV["REDIS_URL"])
  @@local_connections = [] of HTTP::WebSocket

  def on_connect
    @@local_connections << socket

    # Subscribe to Redis channel
    spawn do
      @@redis.subscribe("notifications") do |on|
        on.message do |channel, message|
          @@local_connections.each(&.send(message))
        end
      end
    end
  end

  def self.broadcast(message : String)
    # Publish to Redis - all servers receive it
    @@redis.publish("notifications", message)
  end
end

module Database
  PRIMARY = CQL::Schema.define(:primary,
    adapter: CQL::Adapter::Postgres,
    uri: ENV["DATABASE_URL"]
  )

  REPLICA = CQL::Schema.define(:replica,
    adapter: CQL::Adapter::Postgres,
    uri: ENV["DATABASE_REPLICA_URL"]
  )

  def self.read
    REPLICA
  end

  def self.write
    PRIMARY
  end
end

# Usage
users = Database.read.query("SELECT * FROM users")
Database.write.exec("INSERT INTO users ...")

# pgbouncer.ini
[databases]
myapp = host=db port=5432 dbname=myapp

[pgbouncer]
listen_port = 6432
listen_addr = 0.0.0.0
auth_type = md5
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 20

struct HealthEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Json)

  get "/health"

  def call
    json({
      status: "healthy",
      instance: ENV.fetch("HOSTNAME", "unknown"),
      version: ENV.fetch("APP_VERSION", "unknown"),
      uptime: Process.times.real.to_i
    })
  end
end

# spec/channels/notification_channel_spec.cr
require "../spec_helper"
require "../support/mock_websocket"

describe NotificationChannel do
  describe "#on_connect" do
    it "adds socket to connections" do
      channel = NotificationChannel.new
      socket = MockWebSocket.new

      initial_count = NotificationChannel::CONNECTIONS.size
      channel.socket = socket
      channel.on_connect

      NotificationChannel::CONNECTIONS.size.should eq(initial_count + 1)
    end

    it "sends welcome message" do
      channel = NotificationChannel.new
      socket = MockWebSocket.new
      channel.socket = socket

      channel.on_connect

      socket.sent_messages.size.should eq(1)
      message = JSON.parse(socket.sent_messages.first)
      message["type"].should eq("connected")
    end
  end
end

describe NotificationChannel do
  describe "#on_message" do
    it "responds to ping with pong" do
      channel = NotificationChannel.new
      socket = MockWebSocket.new
      channel.socket = socket
      channel.on_connect

      channel.on_message(%({"type": "ping"}))

      pong = socket.sent_messages.find do |m|
        JSON.parse(m)["type"] == "pong"
      end
      pong.should_not be_nil
    end

    it "handles subscribe action" do
      channel = NotificationChannel.new
      socket = MockWebSocket.new
      channel.socket = socket
      channel.on_connect

      channel.on_message(%({"type": "subscribe", "topic": "news"}))

      response = socket.sent_messages.last
      JSON.parse(response)["type"].should eq("subscribed")
    end

    it "handles invalid JSON gracefully" do
      channel = NotificationChannel.new
      socket = MockWebSocket.new
      channel.socket = socket
      channel.on_connect

      channel.on_message("not valid json")

      error_msg = socket.sent_messages.find do |m|
        JSON.parse(m)["type"] == "error"
      end
      error_msg.should_not be_nil
    end
  end
end

describe NotificationChannel do
  describe "#on_close" do
    it "removes socket from connections" do
      channel = NotificationChannel.new
      socket = MockWebSocket.new
      channel.socket = socket
      channel.on_connect

      count_before = NotificationChannel::CONNECTIONS.size

      channel.on_close(nil, nil)

      NotificationChannel::CONNECTIONS.size.should eq(count_before - 1)
    end

    it "cleans up subscriptions" do
      channel = NotificationChannel.new
      socket = MockWebSocket.new
      channel.socket = socket
      channel.on_connect

      # Subscribe to topic
      channel.on_message(%({"type": "subscribe", "topic": "news"}))

      channel.on_close(nil, nil)

      # Verify subscription cleaned up
      channel.subscriptions.should be_empty
    end
  end
end

describe NotificationChannel do
  describe ".broadcast" do
    it "sends message to all connections" do
      sockets = 3.times.map { MockWebSocket.new }.to_a
      channels = sockets.map do |socket|
        channel = NotificationChannel.new
        channel.socket = socket
        channel.on_connect
        channel
      end

      NotificationChannel.broadcast("Hello everyone!")

      sockets.each do |socket|
        socket.sent_messages.should contain("Hello everyone!")
      end
    end

    it "excludes sender when specified" do
      sender_socket = MockWebSocket.new
      other_socket = MockWebSocket.new

      sender = NotificationChannel.new
      sender.socket = sender_socket
      sender.on_connect

      other = NotificationChannel.new
      other.socket = other_socket
      other.on_connect

      NotificationChannel.broadcast("Hello!", except: sender_socket)

      sender_socket.sent_messages.should_not contain("Hello!")
      other_socket.sent_messages.should contain("Hello!")
    end
  end
end

describe RoomChannel do
  describe "room management" do
    it "joins user to room" do
      channel = RoomChannel.new
      socket = MockWebSocket.new
      channel.socket = socket
      channel.params = {"room_id" => "room-1"}
      channel.on_connect

      RoomChannel.room_members("room-1").should contain(socket)
    end

    it "broadcasts only to room members" do
      room1_socket = MockWebSocket.new
      room2_socket = MockWebSocket.new

      channel1 = RoomChannel.new
      channel1.socket = room1_socket
      channel1.params = {"room_id" => "room-1"}
      channel1.on_connect

      channel2 = RoomChannel.new
      channel2.socket = room2_socket
      channel2.params = {"room_id" => "room-2"}
      channel2.on_connect

      RoomChannel.broadcast_to("room-1", "Room 1 only")

      room1_socket.sent_messages.should contain("Room 1 only")
      room2_socket.sent_messages.should_not contain("Room 1 only")
    end
  end
end

describe AuthenticatedChannel do
  describe "#on_connect" do
    it "rejects invalid tokens" do
      channel = AuthenticatedChannel.new
      socket = MockWebSocket.new
      context = create_ws_context(query: "token=invalid")
      channel.socket = socket
      channel.context = context

      channel.on_connect

      socket.closed.should be_true

      error_msg = socket.sent_messages.find do |m|
        JSON.parse(m)["type"] == "error"
      end
      error_msg.should_not be_nil
    end

    it "accepts valid tokens" do
      user = User.create!(name: "Alice", email: "alice@example.com")
      token = Token.create(user_id: user.id)

      channel = AuthenticatedChannel.new
      socket = MockWebSocket.new
      context = create_ws_context(query: "token=#{token}")
      channel.socket = socket
      channel.context = context

      channel.on_connect

      socket.closed.should be_false

      success_msg = socket.sent_messages.find do |m|
        JSON.parse(m)["type"] == "authenticated"
      end
      success_msg.should_not be_nil
    end
  end
end

def create_ws_context(query : String = "") : HTTP::Server::Context
  io = IO::Memory.new
  request = HTTP::Request.new("GET", "/ws?#{query}")
  response = HTTP::Server::Response.new(io)
  HTTP::Server::Context.new(request, response)
end

require "http/web_socket"

describe "WebSocket Integration" do
  before_all do
    spawn { MyApp.start }
    sleep 1.second
  end

  it "establishes connection and receives messages" do
    received = [] of String
    done = Channel(Nil).new

    ws = HTTP::WebSocket.new("ws://localhost:4000/notifications")

    ws.on_message do |message|
      received << message
      if received.size >= 2
        done.send(nil)
      end
    end

    spawn { ws.run }
    sleep 100.milliseconds

    # Send a message
    ws.send(%({"type": "ping"}))

    # Wait for response
    select
    when done.receive
    when timeout(5.seconds)
      fail "Timeout waiting for messages"
    end

    # Should have welcome + pong
    received.size.should be >= 2
    ws.close
  end
end

# Application
AZU_ENV=production
PORT=8080
HOST=0.0.0.0

# Database
DATABASE_URL=postgres://user:password@localhost:5432/myapp_prod

# Cache
REDIS_URL=redis://localhost:6379/0

# Security
SECRET_KEY=your-secret-key-here
JWT_SECRET=your-jwt-secret

# External Services
SMTP_HOST=smtp.example.com
SMTP_PORT=587

class SecurityHeaders < Azu::Handler::Base
  def call(context)
    headers = context.response.headers

    # HTTPS enforcement
    headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"

    # XSS protection
    headers["X-Content-Type-Options"] = "nosniff"
    headers["X-Frame-Options"] = "DENY"
    headers["X-XSS-Protection"] = "1; mode=block"

    # CSP (customize as needed)
    headers["Content-Security-Policy"] = "default-src 'self'"

    call_next(context)
  end
end

Log.setup do |config|
  if ENV["AZU_ENV"] == "production"
    # JSON logs for production
    backend = JsonLogBackend.new(STDOUT)
    config.bind "*", :info, backend
  else
    # Human-readable for development
    config.bind "*", :debug, Log::IOBackend.new
  end
end

struct HealthEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Json)

  get "/health"

  def call
    checks = {
      database: check_database,
      redis: check_redis,
    }

    all_healthy = checks.values.all?

    status(all_healthy ? 200 : 503)

    json({
      status: all_healthy ? "healthy" : "unhealthy",
      checks: checks,
      timestamp: Time.utc.to_rfc3339,
      version: ENV.fetch("APP_VERSION", "unknown")
    })
  end

  private def check_database : Bool
    AcmeDB.exec("SELECT 1")
    true
  rescue
    false
  end

  private def check_redis : Bool
    Azu.cache.set("health", "ok", expires_in: 1.second)
    true
  rescue
    false
  end
end

module MyApp
  @@running = true

  def self.start
    server = HTTP::Server.new(handlers)

    # Handle shutdown signals
    Signal::INT.trap { shutdown(server) }
    Signal::TERM.trap { shutdown(server) }

    Log.info { "Starting server on port #{port}" }
    server.listen(host, port)
  end

  private def self.shutdown(server)
    return unless @@running
    @@running = false

    Log.info { "Shutting down gracefully..." }

    # Stop accepting new connections
    server.close

    # Wait for in-flight requests
    sleep 5.seconds

    Log.info { "Shutdown complete" }
    exit 0
  end
end

class RateLimiter < Azu::Handler::Base
  LIMIT = 100
  WINDOW = 1.minute

  def call(context)
    key = "ratelimit:#{client_ip(context)}"

    current = Azu.cache.increment(key)
    Azu.cache.expire(key, WINDOW) if current == 1

    context.response.headers["X-RateLimit-Limit"] = LIMIT.to_s
    context.response.headers["X-RateLimit-Remaining"] = Math.max(0, LIMIT - current).to_s

    if current > LIMIT
      context.response.status_code = 429
      context.response.print({error: "Too many requests"}.to_json)
      return
    end

    call_next(context)
  end
end

<button azu-click="click_button">Click Me</button>
<button azu-click="delete" azu-value="123">Delete</button>
<input azu-change="input_changed" azu-model="name">
<form azu-submit="submit_form">...</form>

class CounterComponent
  include Azu::Component

  @count = 0
  @history = [] of Int32

  def content
    <<-HTML
    <div>
      <p>Count: #{@count}</p>
      <button azu-click="increment">+</button>
      <button azu-click="decrement">-</button>
      <button azu-click="reset">Reset</button>
    </div>
    HTML
  end

  on_event "increment" do
    @history << @count
    @count += 1
    push_state
  end

  on_event "decrement" do
    @history << @count
    @count -= 1
    push_state
  end

  on_event "reset" do
    @history.clear
    @count = 0
    push_state
  end
end

class TodoComponent
  include Azu::Component

  @todos = [] of Todo
  @new_todo = ""

  def mount(socket)
    @todos = Todo.all
    push_state
  end

  def content
    <<-HTML
    <div class="todo-app">
      <h1>Todos (#{@todos.size})</h1>

      <form azu-submit="add_todo">
        <input type="text"
               azu-model="new_todo"
               value="#{@new_todo}"
               placeholder="What needs to be done?">
        <button type="submit">Add</button>
      </form>

      <ul id="todo-list">
        #{@todos.map { |t| render_todo(t) }.join}
      </ul>
    </div>
    HTML
  end

  private def render_todo(todo : Todo)
    <<-HTML
    <li id="todo-#{todo.id}" class="#{todo.completed? ? "completed" : ""}">
      <input type="checkbox"
             azu-change="toggle"
             azu-value="#{todo.id}"
             #{todo.completed? ? "checked" : ""}>
      <span>#{todo.title}</span>
      <button azu-click="delete" azu-value="#{todo.id}">×</button>
    </li>
    HTML
  end

  on_event "new_todo_change" do |value|
    @new_todo = value.as_s
  end

  on_event "add_todo" do
    unless @new_todo.empty?
      todo = Todo.create!(title: @new_todo)
      @todos << todo
      @new_todo = ""
      push_state
    end
  end

  on_event "toggle" do |id|
    if todo = @todos.find { |t| t.id == id.as_i64 }
      todo.toggle!
      push_replace("#todo-#{todo.id}", render_todo(todo))
    end
  end

  on_event "delete" do |id|
    @todos.reject! { |t| t.id == id.as_i64 }
    push_remove("#todo-#{id}")
  end
end

class NotificationChannel < Azu::Channel
  CONNECTIONS = [] of HTTP::WebSocket

  def on_connect
    CONNECTIONS << socket
  end

  def on_close(code, reason)
    CONNECTIONS.delete(socket)
  end

  def self.broadcast(message : String)
    CONNECTIONS.each(&.send(message))
  end
end

class RoomChannel < Azu::Channel
  PATH = "/rooms/:room_id"

  @@rooms = Hash(String, Set(HTTP::WebSocket)).new { |h, k| h[k] = Set(HTTP::WebSocket).new }

  def on_connect
    room_id = params["room_id"]
    @@rooms[room_id] << socket
  end

  def on_close(code, reason)
    room_id = params["room_id"]
    @@rooms[room_id].delete(socket)
  end

  def self.broadcast_to(room_id : String, message : String)
    @@rooms[room_id].each(&.send(message))
  end

  def self.room_count(room_id : String) : Int32
    @@rooms[room_id].size
  end
end

class SecureChannel < Azu::Channel
  PATH = "/secure"

  @user : User?

  def on_connect
    token = context.request.query_params["token"]?

    unless token && (@user = authenticate(token))
      send({type: "error", message: "Unauthorized"}.to_json)
      close(code: 4001, reason: "Unauthorized")
      return
    end

    send({type: "authenticated", user: @user.not_nil!.name}.to_json)
  end

  private def authenticate(token : String) : User?
    Token.validate(token)
  end
end

def on_message(message : String)
  data = JSON.parse(message)

  case data["type"]?.try(&.as_s)
  when "ping"
    handle_ping
  when "subscribe"
    handle_subscribe(data)
  when "message"
    handle_message(data)
  else
    send({type: "error", message: "Unknown type"}.to_json)
  end
rescue JSON::ParseException
  send({type: "error", message: "Invalid JSON"}.to_json)
end

private def handle_ping
  send({type: "pong", timestamp: Time.utc.to_unix}.to_json)
end

class ChatChannel < Azu::Channel
  PATH = "/chat/:room"

  @@rooms = Hash(String, Array(HTTP::WebSocket)).new { |h, k| h[k] = [] of HTTP::WebSocket }

  def on_connect
    room = params["room"]
    @@rooms[room] << socket

    broadcast_to_room(room, {
      type: "system",
      message: "User joined",
      users: @@rooms[room].size
    }.to_json)
  end

  def on_message(message : String)
    room = params["room"]
    broadcast_to_room(room, message, except: socket)
  end

  def on_close(code, reason)
    room = params["room"]
    @@rooms[room].delete(socket)

    broadcast_to_room(room, {
      type: "system",
      message: "User left",
      users: @@rooms[room].size
    }.to_json)
  end

  private def broadcast_to_room(room : String, message : String, except : HTTP::WebSocket? = nil)
    @@rooms[room].each do |ws|
      ws.send(message) unless ws == except
    end
  end
end

validate name, length: {min: 2}           # At least 2 chars
validate name, length: {max: 100}         # At most 100 chars
validate name, length: {min: 2, max: 100} # Between 2 and 100
validate code, length: {is: 6}            # Exactly 6 chars

validate age, numericality: {greater_than: 0}
validate age, numericality: {greater_than_or_equal_to: 18}
validate age, numericality: {less_than: 150}
validate age, numericality: {less_than_or_equal_to: 120}
validate quantity, numericality: {equal_to: 1}

struct CreateUserRequest
  include Azu::Request

  getter name : String
  getter email : String
  getter password : String
  getter age : Int32?
  getter role : String

  def initialize(
    @name = "",
    @email = "",
    @password = "",
    @age = nil,
    @role = "user"
  )
  end

  validate name, presence: true, length: {min: 2, max: 100}
  validate email, presence: true, format: /@/
  validate password, presence: true, length: {min: 8}
  validate age, numericality: {greater_than: 0, less_than: 150}, allow_nil: true
  validate role, inclusion: {in: ["user", "admin", "moderator"]}

  def validate
    super

    if email_taken?(email)
      errors << Error.new(:email, "is already taken")
    end
  end

  private def email_taken?(email : String) : Bool
    User.exists?(email: email)
  end
end

# Define multiple endpoints with shared prefix
struct ApiV1::UsersIndex
  include Azu::Endpoint(EmptyRequest, UsersResponse)
  get "/api/v1/users"
end

struct ApiV1::UsersShow
  include Azu::Endpoint(EmptyRequest, UserResponse)
  get "/api/v1/users/:id"
end

# User CRUD endpoints
struct UsersIndex
  include Azu::Endpoint(EmptyRequest, UsersResponse)
  get "/users"
end

struct UsersShow
  include Azu::Endpoint(EmptyRequest, UserResponse)
  get "/users/:id"
end

struct UsersCreate
  include Azu::Endpoint(CreateUserRequest, UserResponse)
  post "/users"
end

struct UsersUpdate
  include Azu::Endpoint(UpdateUserRequest, UserResponse)
  put "/users/:id"
end

struct UsersDelete
  include Azu::Endpoint(EmptyRequest, Azu::Response::Empty)
  delete "/users/:id"
end

# Nested routes
struct UserPosts
  include Azu::Endpoint(EmptyRequest, PostsResponse)
  get "/users/:user_id/posts"
end

struct UserPostShow
  include Azu::Endpoint(EmptyRequest, PostResponse)
  get "/users/:user_id/posts/:id"
end

# PostgreSQL
AcmeDB.query("EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com'")

# Look for:
# - Sequential Scan (bad for large tables)
# - Index Scan (good)
# - Index Only Scan (best)

# Bad: Loads all columns
users = User.all

# Good: Loads only needed columns
users = User.select(:id, :name, :email).all

# For large text/blob columns especially
posts = Post.select(:id, :title, :created_at).all  # Skip body column

# Bad: Loads all records into memory
User.all.each do |user|
  process(user)
end

# Good: Process in batches
User.find_each(batch_size: 1000) do |user|
  process(user)
end

# Or with explicit batching
User.in_batches(of: 1000) do |batch|
  batch.each { |user| process(user) }
end

# Bad: Ruby iteration
users = User.all
total = users.sum(&.balance)

# Good: Database aggregation
total = User.sum(:balance)

# Other aggregations
average = User.average(:age)
max_price = Product.maximum(:price)
min_date = Order.minimum(:created_at)

def expensive_stats
  cache_key = "stats:#{Date.today}"

  Azu.cache.fetch(cache_key, expires_in: 1.hour) do
    {
      total_users: User.count,
      active_users: User.where(active: true).count,
      total_orders: Order.count,
      revenue: Order.sum(:total)
    }.to_json
  end
end

module DB
  PRIMARY = connect(ENV["DATABASE_URL"])
  REPLICA = connect(ENV["DATABASE_REPLICA_URL"])

  def self.read
    REPLICA
  end

  def self.write
    PRIMARY
  end
end

# Usage
users = DB.read { User.all }
DB.write { user.save! }

# Bad: OFFSET with large values
User.offset(10000).limit(20).all  # Scans 10,020 rows

# Good: Cursor-based pagination
last_id = params["after_id"]?.try(&.to_i64) || 0
User.where("id > ?", last_id).limit(20).order(id: :asc).all

# Bad: LIKE with leading wildcard
User.where("name LIKE ?", "%smith%")  # Can't use index

# Good: Full-text search or trigram
User.where("name ILIKE ?", "smith%")  # Can use index

# Better: Full-text search
User.where("to_tsvector('english', name) @@ plainto_tsquery('english', ?)", search_term)

# Bad: Function on indexed column
Order.where("DATE(created_at) = ?", date)  # Can't use index

# Good: Range query
Order.where("created_at >= ? AND created_at < ?", date.at_beginning_of_day, date.tomorrow.at_beginning_of_day)

class QueryLogger
  @@slow_threshold = 100.milliseconds

  def self.log(sql : String, duration : Time::Span)
    if duration > @@slow_threshold
      Log.warn { "Slow query (#{duration.total_milliseconds}ms): #{sql}" }
    end
  end
end

struct ProductsEndpoint
  include Azu::Endpoint(EmptyRequest, ProductsResponse)

  get "/products"

  CACHE_TTL = 5.minutes

  def call : ProductsResponse
    cache_key = "products:#{cache_params}"

    cached = Azu.cache.get(cache_key)
    return ProductsResponse.from_json(cached) if cached

    products = Product.all
    response = ProductsResponse.new(products)

    Azu.cache.set(cache_key, response.to_json, expires_in: CACHE_TTL)

    response
  end

  private def cache_params
    "page=#{params["page"]? || 1}&limit=#{params["limit"]? || 20}"
  end
end

def call
  product = Product.find(params["id"])

  # Set cache headers
  context.response.headers["Cache-Control"] = "public, max-age=3600"
  context.response.headers["ETag"] = generate_etag(product)

  # Check If-None-Match
  if_none_match = context.request.headers["If-None-Match"]?
  if if_none_match == context.response.headers["ETag"]
    status 304
    return EmptyResponse.new
  end

  ProductResponse.new(product)
end

private def generate_etag(product)
  %("#{product.updated_at.to_unix}")
end

struct UsersEndpoint
  include Azu::Endpoint(EmptyRequest, UsersResponse)

  get "/users"

  DEFAULT_LIMIT = 20
  MAX_LIMIT = 100

  def call : UsersResponse
    page = (params["page"]? || "1").to_i
    limit = [(params["limit"]? || DEFAULT_LIMIT.to_s).to_i, MAX_LIMIT].min
    offset = (page - 1) * limit

    users = User.limit(limit).offset(offset).all
    total = User.count

    UsersResponse.new(
      users: users,
      page: page,
      limit: limit,
      total: total,
      total_pages: (total / limit.to_f).ceil.to_i
    )
  end
end

# Bad: N+1 queries
def call
  posts = Post.all
  posts.each do |post|
    post.author  # Each access triggers a query
  end
end

# Good: Eager load
def call
  posts = Post.includes(:author).all
  posts.each do |post|
    post.author  # No additional query
  end
end

def call
  user_id = params["id"].to_i64

  # Run queries in parallel
  user_channel = Channel(User?).new
  posts_channel = Channel(Array(Post)).new
  stats_channel = Channel(UserStats).new

  spawn { user_channel.send(User.find?(user_id)) }
  spawn { posts_channel.send(Post.where(user_id: user_id).recent.limit(10).all) }
  spawn { stats_channel.send(UserStats.for(user_id)) }

  user = user_channel.receive
  raise Azu::Response::NotFound.new("/users/#{user_id}") unless user

  UserDetailResponse.new(
    user: user,
    posts: posts_channel.receive,
    stats: stats_channel.receive
  )
end

class CompressionHandler < Azu::Handler::Base
  MIN_SIZE = 1024  # Only compress > 1KB

  def call(context)
    call_next(context)

    return unless should_compress?(context)

    body = context.response.output.to_s
    return if body.bytesize < MIN_SIZE

    compressed = Compress::Gzip.compress(body)

    if compressed.bytesize < body.bytesize
      context.response.headers["Content-Encoding"] = "gzip"
      context.response.output = IO::Memory.new(compressed)
    end
  end

  private def should_compress?(context) : Bool
    accept = context.request.headers["Accept-Encoding"]?
    return false unless accept
    accept.includes?("gzip")
  end
end

def call
  context.response.content_type = "application/json"
  context.response.headers["Transfer-Encoding"] = "chunked"

  context.response.print "["

  User.find_each(batch_size: 100) do |user, index|
    context.response.print "," if index > 0
    context.response.print user.to_json
    context.response.flush
  end

  context.response.print "]"
end

def call
  # Fire and forget for non-critical operations
  spawn do
    Analytics.track(
      event: "page_view",
      user_id: current_user_id,
      path: context.request.path
    )
  end

  # Return immediately
  MainResponse.new(data)
end

def call
  result = with_timeout(5.seconds) do
    external_api.fetch_data
  end

  DataResponse.new(result)
rescue Timeout::Error
  raise Azu::Response::ServiceUnavailable.new("External service timeout")
end

private def with_timeout(duration : Time::Span, &)
  channel = Channel(typeof(yield)).new

  spawn do
    channel.send(yield)
  end

  select
  when result = channel.receive
    result
  when timeout(duration)
    raise Timeout::Error.new
  end
end

class BenchmarkHandler < Azu::Handler::Base
  def call(context)
    start = Time.instant
    start_gc = GC.stats

    call_next(context)

    duration = Time.instant - start
    end_gc = GC.stats
    allocated = end_gc.heap_size - start_gc.heap_size

    context.response.headers["X-Response-Time"] = "#{duration.total_milliseconds.round(2)}ms"
    context.response.headers["X-Memory-Allocated"] = "#{allocated / 1024}KB"
  end
end

# Hash conditions
User.where(active: true)
User.where(role: "admin", active: true)

# SQL conditions
User.where("age > ?", 18)
User.where("created_at > ?", 1.week.ago)
User.where("name LIKE ?", "%smith%")

# IN clause
User.where("id IN (?)", [1, 2, 3])

# NULL check
User.where("deleted_at IS NULL")

class User
  scope :active, -> { where(active: true) }
  scope :recent, -> { order(created_at: :desc) }
  scope :by_role, ->(role : String) { where(role: role) }
end

User.active.recent.all
User.by_role("admin").count

def get_user(id : Int64) : User?
  cache_key = "user:#{id}"

  cached = Azu.cache.get(cache_key)
  return User.from_json(cached) if cached

  user = User.find?(id)
  if user
    Azu.cache.set(cache_key, user.to_json, expires_in: 15.minutes)
  end

  user
end

class User
  after_save :update_cache
  after_destroy :remove_from_cache

  private def update_cache
    Azu.cache.set("user:#{id}", to_json, expires_in: 1.hour)
  end

  private def remove_from_cache
    Azu.cache.delete("user:#{id}")
  end
end

def fetch_with_lock(key : String, expires_in : Time::Span, &)
  # Try cache first
  cached = Azu.cache.get(key)
  return cached if cached

  # Try to acquire lock
  lock_key = "lock:#{key}"
  if Azu.cache.set(lock_key, "1", expires_in: 10.seconds, nx: true)
    begin
      value = yield
      Azu.cache.set(key, value, expires_in: expires_in)
      value
    ensure
      Azu.cache.delete(lock_key)
    end
  else
    # Wait and retry
    sleep 100.milliseconds
    Azu.cache.get(key) || yield
  end
end

Azu.configure do |config|
  if ENV["AZU_ENV"] == "production"
    config.cache = Azu::Cache::RedisStore.new(
      url: ENV["REDIS_URL"],
      pool_size: 10,
      namespace: "myapp:production",
      default_ttl: 1.hour
    )
  else
    config.cache = Azu::Cache::MemoryStore.new(
      max_size: 1000,
      default_ttl: 15.minutes
    )
  end
end

struct UploadRequest
  include Azu::Request

  getter file : HTTP::FormData::File
  getter description : String?

  def initialize(@file, @description = nil)
  end
end

struct UploadEndpoint
  include Azu::Endpoint(UploadRequest, UploadResponse)

  post "/upload"

  def call : UploadResponse
    file = upload_request.file

    # Access file properties
    filename = file.filename      # Original filename
    content = file.body           # File content as IO
    content_type = file.headers["Content-Type"]?

    # Save the file
    save_path = File.join("uploads", filename)
    File.write(save_path, content.gets_to_end)

    UploadResponse.new(filename, save_path)
  end
end

<form action="/upload" method="POST" enctype="multipart/form-data">
  <input type="file" name="file" required>
  <input type="text" name="description" placeholder="Description">
  <button type="submit">Upload</button>
</form>

struct MultiUploadRequest
  include Azu::Request

  getter files : Array(HTTP::FormData::File)

  def initialize(@files = [] of HTTP::FormData::File)
  end
end

struct MultiUploadEndpoint
  include Azu::Endpoint(MultiUploadRequest, MultiUploadResponse)

  post "/upload-multiple"

  def call : MultiUploadResponse
    saved_files = multi_upload_request.files.map do |file|
      save_path = save_file(file)
      {filename: file.filename, path: save_path}
    end

    MultiUploadResponse.new(saved_files)
  end

  private def save_file(file) : String
    filename = generate_unique_filename(file.filename)
    path = File.join("uploads", filename)
    File.write(path, file.body.gets_to_end)
    path
  end

  private def generate_unique_filename(original : String) : String
    ext = File.extname(original)
    "#{UUID.random}#{ext}"
  end
end

struct UploadRequest
  include Azu::Request

  MAX_SIZE = 10 * 1024 * 1024  # 10 MB

  getter file : HTTP::FormData::File

  def initialize(@file)
  end

  def validate
    super

    if file.body.size > MAX_SIZE
      errors << Error.new(:file, "must be smaller than 10 MB")
    end
  end
end

module FileUploader
  ALLOWED_EXTENSIONS = [".jpg", ".jpeg", ".png", ".gif", ".pdf"]
  UPLOAD_DIR = "uploads"

  def self.save(file : HTTP::FormData::File) : String
    # Sanitize filename
    original = file.filename || "unnamed"
    extension = File.extname(original).downcase
    safe_name = "#{UUID.random}#{extension}"

    # Validate extension
    unless ALLOWED_EXTENSIONS.includes?(extension)
      raise "Invalid file type"
    end

    # Ensure upload directory exists
    Dir.mkdir_p(UPLOAD_DIR)

    # Save file
    path = File.join(UPLOAD_DIR, safe_name)
    File.write(path, file.body.gets_to_end)

    path
  end
end

struct ImageUploadEndpoint
  include Azu::Endpoint(ImageUploadRequest, ImageResponse)

  post "/images"

  def call : ImageResponse
    file = image_upload_request.file

    # Validate it's an image
    unless image?(file)
      raise Azu::Response::BadRequest.new("File must be an image")
    end

    # Save original
    original_path = save_file(file, "originals")

    # Create thumbnail (using external tool)
    thumb_path = create_thumbnail(original_path)

    ImageResponse.new(
      original: original_path,
      thumbnail: thumb_path
    )
  end

  private def image?(file) : Bool
    content_type = file.headers["Content-Type"]?
    return false unless content_type

    content_type.starts_with?("image/")
  end

  private def create_thumbnail(path : String) : String
    thumb_path = path.gsub("originals", "thumbnails")
    Dir.mkdir_p(File.dirname(thumb_path))

    # Use ImageMagick or similar
    Process.run("convert", [path, "-resize", "200x200", thumb_path])

    thumb_path
  end
end

require "awscr-s3"

module S3Uploader
  CLIENT = Awscr::S3::Client.new(
    region: ENV["AWS_REGION"],
    aws_access_key: ENV["AWS_ACCESS_KEY_ID"],
    aws_secret_key: ENV["AWS_SECRET_ACCESS_KEY"]
  )
  BUCKET = ENV["S3_BUCKET"]

  def self.upload(file : HTTP::FormData::File) : String
    key = "uploads/#{UUID.random}/#{file.filename}"

    CLIENT.put_object(
      bucket: BUCKET,
      object: key,
      body: file.body.gets_to_end,
      headers: {"Content-Type" => file.headers["Content-Type"]? || "application/octet-stream"}
    )

    "https://#{BUCKET}.s3.amazonaws.com/#{key}"
  end
end

const form = document.getElementById('upload-form');
const progress = document.getElementById('progress');

form.addEventListener('submit', async (e) => {
  e.preventDefault();

  const formData = new FormData(form);
  const xhr = new XMLHttpRequest();

  xhr.upload.addEventListener('progress', (e) => {
    if (e.lengthComputable) {
      const percent = (e.loaded / e.total) * 100;
      progress.style.width = percent + '%';
    }
  });

  xhr.open('POST', '/upload');
  xhr.send(formData);
});

module FileCleanup
  def self.cleanup_old_files(max_age : Time::Span = 7.days)
    cutoff = Time.utc - max_age

    Dir.glob("uploads/**/*").each do |path|
      next if File.directory?(path)

      if File.info(path).modification_time < cutoff
        File.delete(path)
      end
    end
  end
end

{{ form_tag("/users", method="post") }}
  {{ csrf_field() }}
  
  {{ label_tag("user_name", "Name") }}
  {{ text_field("user", "name", required=true) }}
  
  {{ label_tag("user_email", "Email") }}
  {{ email_field("user", "email", required=true) }}
  
  {{ submit_button("Create User") }}
{{ end_form() }}

{{ form_tag("/upload", method="post", multipart=true) }}
  {{ csrf_field() }}
  
  {{ label_tag("file", "Choose file") }}
  <input type="file" name="file" id="file" accept="image/*">
  
  {{ submit_button("Upload") }}
{{ end_form() }}

{{ form_tag("/users", method="post") }}
  {{ csrf_field() }}
  
  <div class="form-group {% if errors['name'] %}has-error{% endif %}">
    {{ label_tag("user_name", "Name") }}
    {{ text_field("user", "name", value=form_data['name'], class="form-control") }}
    {% if errors['name'] %}
      <span class="error-message">{{ errors['name'] }}</span>
    {% endif %}
  </div>
  
  {{ submit_button("Submit") }}
{{ end_form() }}

{{ select_field("user", "role", options=[
  {"value": "user", "label": "Regular User"},
  {"value": "admin", "label": "Administrator"},
  {"value": "moderator", "label": "Moderator"}
], selected=user.role, include_blank="Select a role...") }}

{# Checkbox #}
{{ checkbox("user", "newsletter", label="Subscribe to newsletter") }}
{{ checkbox("user", "terms", required=true) }}
<label for="user_terms">I agree to the terms</label>

{# Radio buttons #}
{% for role in ["user", "admin", "moderator"] %}
  {{ radio_button("user", "role", value=role, checked=(user.role == role)) }}
  <label>{{ role | capitalize }}</label>
{% endfor %}

<nav>
  {{ link_to("Home", "/", class="nav-link " ~ ("/" | active_class("active"))) }}
  {{ link_to("About", "/about", class="nav-link " ~ ("/about" | active_class("active"))) }}
  {{ link_to("Contact", "/contact", class="nav-link " ~ ("/contact" | active_class("active"))) }}
</nav>

<nav>
  {% for item in [
    {"label": "Home", "path": "/"},
    {"label": "Blog", "path": "/blog"},
    {"label": "About", "path": "/about"}
  ] %}
    <a href="{{ item.path }}" 
       class="nav-link {% if item.path | is_current_page %}active{% endif %}">
      {{ item.label }}
    </a>
  {% endfor %}
</nav>

{# Simple delete #}
{{ button_to("Delete", "/posts/" ~ post.id, method="delete") }}

{# With confirmation #}
{{ button_to("Delete", "/posts/" ~ post.id,
   method="delete",
   confirm="Are you sure you want to delete this post?",
   class="btn btn-danger") }}

{# Link to collection (GET /users) #}
{{ link_to_get_users("View All Users", class="btn") }}

{# Link to member (GET /users/:id) #}
{{ link_to_get_user("View Profile", id=user.id) }}

{# Link to edit page #}
{{ link_to_get_edit_user("Edit", id=user.id, class="btn btn-secondary") }}

{# Create form (POST /users) - method is clear from the name #}
{{ form_for_post_create_user(class="user-form") }}
  {{ csrf_field() }}

  {{ label_tag("user_name", "Name") }}
  {{ text_field("user", "name", required=true) }}

  {{ label_tag("user_email", "Email") }}
  {{ email_field("user", "email", required=true) }}

  {{ submit_button("Create User") }}
{{ end_form() }}

{# Edit form (PUT /users/:id) - _method field added automatically #}
{{ form_for_put_update_user(id=user.id, class="edit-form") }}
  {{ csrf_field() }}

  {{ label_tag("user_name", "Name") }}
  {{ text_field("user", "name", value=user.name) }}

  {{ submit_button("Update User") }}
{{ end_form() }}

{# Simple delete button #}
{{ button_to_delete_delete_user(id=user.id) }}

{# With custom text and confirmation #}
{{ button_to_delete_delete_user(
   text="Remove User",
   id=user.id,
   confirm="Are you sure you want to delete this user?",
   class="btn btn-danger") }}

{# User listing with all actions #}
<table class="table">
  <thead>
    <tr>
      <th>Name</th>
      <th>Email</th>
      <th>Actions</th>
    </tr>
  </thead>
  <tbody>
    {% for user in users %}
    <tr>
      <td>{{ link_to_get_user(user.name, id=user.id) }}</td>
      <td>{{ user.email }}</td>
      <td>
        {{ link_to_get_edit_user("Edit", id=user.id, class="btn btn-sm") }}
        {{ button_to_delete_delete_user(id=user.id, class="btn btn-sm btn-danger", confirm="Delete this user?") }}
      </td>
    </tr>
    {% endfor %}
  </tbody>
</table>

{# Link to create new user #}
{{ link_to_get_new_user("Add New User", class="btn btn-primary") }}

<head>
  <meta charset="UTF-8">
  <title>{% block title %}My App{% endblock %}</title>
  
  {{ favicon_tag("favicon.ico") }}
  {{ stylesheet_tag("app.css") }}
  
  {# Preload critical fonts #}
  <link rel="preload" href="{{ 'fonts/inter.woff2' | asset_path }}" 
        as="font" type="font/woff2" crossorigin>
  
  {{ csrf_meta() }}
</head>

# locales/en.yml
en:
  app_name: "My App"
  welcome:
    title: "Welcome!"
    greeting: "Hello, %{name}!"
  users:
    count:
      zero: "No users yet"
      one: "1 user"
      other: "%{count} users"
  date:
    formats:
      short: "%b %d"
      long: "%B %d, %Y"

<div class="language-switcher">
  {% for locale in available_locales() %}
    <a href="?locale={{ locale }}" 
       class="{% if locale == current_locale() %}active{% endif %}">
      {{ locale | locale_name }}
    </a>
  {% endfor %}
</div>

<span class="price">{{ product.price | currency("$") }}</span>
<span class="views">{{ article.views | number_with_delimiter }} views</span>
<span class="rating">{{ product.rating | percentage }} positive</span>
<span class="size">{{ file.size | filesize }}</span>

<small>{{ post.created_at | time_ago }}</small>
{# Output: "5 minutes ago", "2 days ago", etc. #}

<small>{{ event.starts_at | relative_time }}</small>
{# Output: "in 3 hours", "in 2 days", etc. #}

{% extends "layouts/application.jinja" %}

{% block title %}{{ t("posts.show.title", title=post.title) }}{% endblock %}

{% block content %}
<article class="post">
  <header>
    <h1>{{ post.title }}</h1>
    <p class="meta">
      By {{ link_to(post.author.name, "/users/" ~ post.author.id) }}
      <time>{{ post.created_at | time_ago }}</time>
    </p>
  </header>
  
  <div class="content">
    {{ post.content | safe_html }}
  </div>
  
  <footer>
    {% if current_user and current_user.id == post.author.id %}
      {{ link_to(t("actions.edit"), "/posts/" ~ post.id ~ "/edit", class="btn") }}
      {{ button_to(t("actions.delete"), "/posts/" ~ post.id, 
         method="delete", 
         confirm=t("posts.confirm_delete"),
         class="btn btn-danger") }}
    {% endif %}
    
    {{ link_to(t("actions.back"), back_url(fallback="/posts"), class="btn btn-secondary") }}
  </footer>
</article>
{% endblock %}

class ErrorHandler < Azu::Handler::Base
  Log = ::Log.for(self)

  def call(context)
    call_next(context)
  rescue ex : Azu::Response::Error
    handle_known_error(context, ex)
  rescue ex : JSON::ParseException
    handle_json_error(context, ex)
  rescue ex : CQL::RecordNotFound
    handle_not_found(context, ex)
  rescue ex : CQL::RecordInvalid
    handle_validation_error(context, ex)
  rescue ex
    handle_unknown_error(context, ex)
  end

  private def handle_known_error(context, ex : Azu::Response::Error)
    respond_with_error(context, ex.status, ex.message)
  end

  private def handle_json_error(context, ex)
    respond_with_error(context, 400, "Invalid JSON: #{ex.message}")
  end

  private def handle_not_found(context, ex)
    respond_with_error(context, 404, "Resource not found")
  end

  private def handle_validation_error(context, ex)
    respond_with_error(context, 422, "Validation failed", ex.errors)
  end

  private def handle_unknown_error(context, ex)
    Log.error(exception: ex) { "Unhandled error" }

    if ENV["AZU_ENV"] == "production"
      respond_with_error(context, 500, "Internal server error")
    else
      respond_with_error(context, 500, ex.message, ex.backtrace)
    end
  end

  private def respond_with_error(context, status, message, details = nil)
    context.response.status_code = status
    context.response.content_type = "application/json"

    body = {error: message}
    body = body.merge({details: details}) if details

    context.response.print(body.to_json)
  end
end

struct CreateOrderEndpoint
  include Azu::Endpoint(CreateOrderRequest, OrderResponse)

  post "/orders"

  def call : Azu::Response
    validate_inventory
    order = create_order

    status 201
    OrderResponse.new(order)
  rescue ex : InsufficientInventoryError
    status 422
    ErrorResponse.new("Insufficient inventory: #{ex.message}")
  rescue ex : PaymentDeclinedError
    status 402
    ErrorResponse.new("Payment declined: #{ex.message}")
  end

  private def validate_inventory
    # Check inventory...
  end

  private def create_order
    # Create order...
  end
end

struct ErrorResponse
  include Azu::Response

  def initialize(
    @message : String,
    @code : String? = nil,
    @details : Hash(String, String)? = nil
  )
  end

  def render
    response = {
      error: {
        message: @message
      }
    }

    response[:error][:code] = @code if @code
    response[:error][:details] = @details if @details

    response.to_json
  end
end

class ErrorLogger < Azu::Handler::Base
  Log = ::Log.for(self)

  def call(context)
    call_next(context)
  rescue ex
    log_error(context, ex)
    raise ex
  end

  private def log_error(context, ex)
    Log.error(exception: ex) { {
      error_class: ex.class.name,
      message: ex.message,
      path: context.request.path,
      method: context.request.method,
      request_id: context.request.headers["X-Request-ID"]?,
      user_agent: context.request.headers["User-Agent"]?
    }.to_json }
  end
end

class ErrorReporter < Azu::Handler::Base
  def call(context)
    call_next(context)
  rescue ex
    report_error(context, ex)
    raise ex
  end

  private def report_error(context, ex)
    return if ENV["AZU_ENV"] != "production"

    # Send to Sentry, Honeybadger, etc.
    Sentry.capture_exception(ex, extra: {
      path: context.request.path,
      method: context.request.method
    })
  end
end

def with_retry(max_attempts = 3, &)
  attempts = 0

  loop do
    attempts += 1
    return yield
  rescue ex : Timeout::Error | IO::Error
    raise ex if attempts >= max_attempts

    Log.warn { "Attempt #{attempts} failed, retrying..." }
    sleep (2 ** attempts).seconds
  end
end

# Usage
def call
  with_retry do
    external_api.fetch_data
  end
end

class CircuitBreaker
  enum State
    Closed
    Open
    HalfOpen
  end

  def initialize(
    @failure_threshold = 5,
    @reset_timeout = 30.seconds
  )
    @state = State::Closed
    @failures = 0
    @last_failure_time = Time.utc
  end

  def call(&)
    case @state
    when .open?
      if Time.utc - @last_failure_time > @reset_timeout
        @state = State::HalfOpen
      else
        raise CircuitOpenError.new
      end
    end

    begin
      result = yield
      on_success
      result
    rescue ex
      on_failure
      raise ex
    end
  end

  private def on_success
    @failures = 0
    @state = State::Closed
  end

  private def on_failure
    @failures += 1
    @last_failure_time = Time.utc

    if @failures >= @failure_threshold
      @state = State::Open
    end
  end
end

def call
  data = fetch_from_primary
rescue ex : ServiceUnavailableError
  Log.warn { "Primary service unavailable, using cache" }
  data = fetch_from_cache

  if data.nil?
    Log.error { "No cached data available" }
    raise ex
  end

  data
end

Request Lifecycle

This document explains how HTTP requests flow through an Azu application from receipt to response.

Overview

When a request arrives, it passes through several stages:

Connection - TCP connection established
Parsing - HTTP request parsed
Handler Chain - Middleware processing
Routing - Match to endpoint
Request Binding - Parse and validate input
Execution - Call endpoint logic
Response - Serialize and send output

Stage 1: Connection

Crystal's HTTP server accepts the TCP connection:

Stage 2: Handler Chain

The request enters the handler pipeline:

Each handler:

Receives the context
Optionally processes the request
Calls call_next(context)

Stage 3: Routing

The router matches the path and method:

The radix tree provides O(k) lookup where k is path length.

Stage 4: Request Binding

The endpoint's request contract is populated:

Binding process:

Detect content type (JSON, form, multipart)
Parse body according to type
Map parsed data to request properties
Run validations

Stage 5: Endpoint Execution

The endpoint's call method runs:

The call method has full access to:

params - Route parameters
headers - Request headers
context - Full HTTP context

Stage 6: Response Serialization

The response object is rendered:

Response handling:

Call render method
Set Content-Type header
Write body to output

Stage 7: Handler Chain (Reverse)

The response travels back up the handler chain:

Each handler's code after call_next executes with the response available.

Error Handling

When an exception occurs:

The Rescuer handler converts exceptions to HTTP responses:

Exception

Status

Behavior

WebSocket Lifecycle

WebSocket connections follow a different path:

Performance Considerations

Hot Path Optimization

The request hot path is optimized:

Minimal allocations
Cached route lookups
Pre-compiled templates

Context Pooling

HTTP contexts may be pooled for reuse, avoiding allocation overhead.

Async I/O

Crystal's event loop handles I/O efficiently:

Non-blocking sockets
Fiber-based concurrency
No thread pool overhead

Timing Breakdown

Typical request timing:

Stage

Time

Performance Design

This document explains the performance-oriented design decisions in Azu and how they contribute to high throughput and low latency.

Design Principles

Azu's performance design follows these principles:

Zero-cost abstractions - High-level code compiles to efficient machine code
Minimal allocations - Reduce garbage collection pressure
Cache-friendly - Optimize for CPU cache hits
Async I/O - Never block on I/O operations

Crystal's Performance Foundation

Azu benefits from Crystal's performance characteristics:

LLVM Compilation

Crystal compiles to LLVM IR, benefiting from decades of optimization work.

Stack Allocation

Value types (structs) are stack-allocated:

UserResponse instances:

Allocated on stack when possible
No GC overhead for short-lived objects
Cache-friendly memory layout

No Runtime Reflection

Types are resolved at compile time:

No runtime type checking overhead
Method calls are direct, not looked up
Generics compile to specialized code

Router Performance

The router uses a radix tree for O(k) route matching:

Radix Tree Structure

Characteristics:

Path lookup is O(k) where k = path length
Shared prefixes stored once
No regex matching for static segments

Path Caching

Frequently accessed paths are cached:

Request Processing

Minimal Parsing

Request bodies are parsed lazily:

Streaming Bodies

Large bodies can be streamed:

Handler Pipeline

Direct Dispatch

Handlers use direct method calls, not dynamic dispatch:

No Middleware Allocation

Handler instances are created once at startup:

Response Generation

Pre-computed Headers

Common headers are pre-computed:

Efficient JSON Serialization

Crystal's JSON serialization is compile-time generated:

Template Caching

Templates are compiled and cached:

Component Pooling

Frequently used components are pooled:

Benefits:

Reduced allocation overhead
Faster component instantiation
Bounded memory usage

Fiber-Based Concurrency

Crystal uses fibers for lightweight concurrency:

Fiber characteristics:

~8KB stack (vs ~1MB for threads)
No OS thread overhead
Cooperative scheduling

I/O Optimization

Non-Blocking I/O

All I/O operations are non-blocking:

Connection Pooling

Database and HTTP connections are pooled:

Benchmarks

Typical performance characteristics:

Metric

Value

Profiling

Use Crystal's profiling tools:

Best Practices

Use structs for value objects
Avoid string concatenation in loops
Cache computed values

Template Helpers

Azu provides built-in template helpers for common web development tasks like building forms, generating links, formatting dates, and handling internationalization.

Quick Reference

Form Helpers

form_tag

Opens a form with CSRF protection:

Parameters:

Parameter

Type

Default

Description

Non-standard methods (put, patch, delete) automatically add a hidden _method field.

end_form

Closes a form tag:

csrf_field

Generates a hidden CSRF token input:

csrf_meta

Generates a CSRF meta tag for JavaScript use:

text_field

Generates a text input:

Parameters:

Parameter

Type

Default

Description

email_field

Generates an email input:

password_field

Generates a password input:

number_field

Generates a number input:

Additional parameters: min, max, step

textarea

Generates a textarea:

Additional parameters: rows, cols

hidden_field

Generates a hidden input:

checkbox

Generates a checkbox with hidden unchecked value:

Additional parameters: checked, label, unchecked_value (default "0")

radio_button

Generates a radio button:

Additional parameters: value, checked, label

select_field

Generates a select dropdown:

Parameters:

Parameter

Type

Default

Description

label_tag

Generates a label element:

submit_button

Generates a submit button:

URL Helpers

link_to

Generates an anchor tag:

Parameters:

Parameter

Type

Default

Description

Links with target="_blank" automatically add rel="noopener noreferrer".

button_to

Generates a form with a submit button (for non-GET actions):

Parameters:

Parameter

Type

Default

Description

mail_to

Generates a mailto link:

Parameters:

Parameter

Type

Default

Description

current_path

Returns the current request path:

current_url

Returns the full current URL:

is_current_page

Filter that checks if a path matches the current page:

active_class

Filter that returns a class name if the path is active:

Parameters:

Parameter

Type

Default

Description

back_url

Returns the referer URL or a fallback:

Type-Safe Endpoint Helpers

Azu automatically generates type-safe URL and form helpers from your endpoint definitions. The HTTP method is part of the helper name, making it impossible to confuse which action will be performed.

How They're Generated

When you define an endpoint with an HTTP method, Azu auto-generates helpers:

This generates the following helpers:

Endpoint

Generated Helpers

link_to_{method}_{resource}

Generates anchor tags for any endpoint:

Parameters:

Parameter

Type

Default

Description

With custom query parameters:

form_for_{method}_{resource}

Generates form opening tags for non-GET endpoints. PUT, PATCH, and DELETE methods automatically include a hidden _method field:

Parameters:

Parameter

Type

Default

Description

With custom hidden fields:

button_to_delete_{resource}

Generates a complete delete form with a submit button (only for DELETE endpoints):

Parameters:

Parameter

Type

Default

Description

With custom hidden fields:

Helper Naming Convention

The helper name is derived from the endpoint class name:

Class Name

Helper Resource Name

Benefits

Intuitive: link_to_get_users clearly indicates a GET request
Hard to confuse: The HTTP method is in the name, not a parameter
Type-safe: Helpers are generated at compile-time from your endpoints

Asset Helpers

asset_path

Filter that returns the asset URL:

image_tag

Generates an image element:

Parameters:

Parameter

Type

Default

Description

javascript_tag

Generates a script element:

Parameters:

Parameter

Type

Default

Description

stylesheet_tag

Generates a link stylesheet element:

Parameters:

Parameter

Type

Default

Description

favicon_tag

Generates a favicon link:

Date Helpers

time_ago

Filter that formats a time as relative past:

relative_time

Filter that formats time relative to now (past or future):

date_format

Filter that formats a date with a strftime pattern:

time_tag

Function that generates a time element:

distance_of_time

Filter that converts seconds to human-readable duration:

Number Helpers

currency

Filter that formats a number as currency:

Parameters:

Parameter

Type

Default

Description

number_with_delimiter

Filter that adds thousands separators:

percentage

Filter that formats a decimal as percentage:

filesize

Filter that formats bytes as human-readable:

number_to_human

Filter that formats large numbers with words:

HTML Helpers

safe_html

Filter that marks content as safe (no escaping):

Warning: Only use with trusted content to prevent XSS.

simple_format

Filter that converts newlines to <br> and wraps in paragraphs:

highlight

Filter that highlights occurrences of a phrase:

truncate_html

Filter that truncates HTML while preserving structure:

strip_tags

Filter that removes HTML tags:

word_wrap

Filter that wraps text at a specified width:

auto_link

Filter that converts URLs and emails to links:

content_tag

Function that generates an HTML tag:

i18n Helpers

t (Translate)

Function that translates a key:

Parameters:

Parameter

Type

Default

Description

Pluralization:

Define translations with zero, one, other keys:

l (Localize)

Filter that localizes dates using translation formats:

current_locale

Function that returns the current locale:

available_locales

Function that returns available locales:

locale_name

Filter that returns display name for a locale code:

pluralize

Function for simple pluralization:

Component Helpers

For use with Azu's Spark real-time component system.

spark_tag

Generates the Spark JavaScript bootstrap:

render_component

Renders a Spark live component:

Live Attribute Filters

Add Spark live attributes to elements:

Complete Example

Getting Started

Welcome to Azu! This tutorial will guide you through installing Crystal and Azu, then building your first working application.

What You'll Learn

By the end of this tutorial, you will have:

Crystal and Azu installed on your system
A working Azu application running locally
Understanding of the basic project structure

Prerequisites

Before starting, ensure you have:

A computer running macOS, Linux, or Windows
Internet connection for downloading dependencies
A terminal/command line application

Step 1: Install Crystal

Azu requires Crystal 0.35.0 or higher. Install Crystal for your operating system:

macOS

Linux (Ubuntu/Debian)

Linux (Fedora/CentOS/RHEL)

Windows

Step 2: Create Your Project

Create a new Crystal project and add Azu as a dependency:

Edit your shard.yml to add Azu:

Install dependencies:

Step 3: Create Your First Application

Replace the contents of src/my_first_azu_app.cr with:

Step 4: Run Your Application

Start the server:

You should see output like:

Step 5: Test Your Endpoints

Open a new terminal and test your endpoints:

You can also open http://localhost:4000/ in your browser.

Understanding the Code

Let's break down what you just created:

Application Module

This defines your application and configures the server settings.

Endpoints

Endpoints handle HTTP requests:

include Azu::Endpoint(RequestType, ResponseType) defines the contract
get "/" declares the HTTP method and route
def call contains your handler logic

Route Parameters

The :name in the route captures that segment and makes it available via params.

Project Structure

Your project should now look like this:

Troubleshooting

"command not found: crystal"

Add Crystal to your PATH:

"Error resolving dependencies"

Clear the cache and reinstall:

Port already in use

Change the port in your configuration or kill the existing process:

Next Steps

Congratulations! You've created your first Azu application. Continue learning with:

- Create a complete CRUD API
- Add real-time features
- Connect to PostgreSQL or MySQL

Your Azu journey begins! You now have a working development environment and understand the basics of creating endpoints.

MyApp.start [
  Azu::Handler::Rescuer.new,   # 1. Outermost
  Azu::Handler::Logger.new,    # 2.
  AuthHandler.new,              # 3.
  RateLimitHandler.new,         # 4.
  MyEndpoint.new,               # 5. Innermost
]

class RequestIdHandler < Azu::Handler::Base
  def call(context)
    request_id = context.request.headers["X-Request-ID"]?
    request_id ||= UUID.random.to_s

    context.request.headers["X-Request-ID"] = request_id
    call_next(context)
  end
end

class SecurityHeadersHandler < Azu::Handler::Base
  def call(context)
    call_next(context)

    context.response.headers["X-Frame-Options"] = "DENY"
    context.response.headers["X-Content-Type-Options"] = "nosniff"
  end
end

class AuthHandler < Azu::Handler::Base
  def call(context)
    unless authenticated?(context)
      context.response.status_code = 401
      context.response.print({error: "Unauthorized"}.to_json)
      return  # Don't call_next - stop here
    end

    call_next(context)
  end
end

class AdminOnlyHandler < Azu::Handler::Base
  def call(context)
    if admin_route?(context.request.path)
      verify_admin!(context)
    end

    call_next(context)
  end

  private def admin_route?(path)
    path.starts_with?("/admin")
  end
end

class MetricsHandler < Azu::Handler::Base
  @request_count = Atomic(Int64).new(0)

  def call(context)
    @request_count.add(1)
    call_next(context)
  end

  def request_count
    @request_count.get
  end
end

class RateLimitHandler < Azu::Handler::Base
  def initialize(@limit : Int32 = 100, @window : Time::Span = 1.minute)
  end

  def call(context)
    if rate_limited?(context)
      context.response.status_code = 429
      return
    end

    call_next(context)
  end
end

# Usage
RateLimitHandler.new(limit: 200, window: 30.seconds)

MyApp.start [
  # 1. Error handling (catches everything)
  Azu::Handler::Rescuer.new,

  # 2. Request ID (for tracing)
  RequestIdHandler.new,

  # 3. CORS (early for preflight)
  CorsHandler.new,

  # 4. Logging (after IDs, before auth)
  LoggingHandler.new,

  # 5. Rate limiting (before expensive ops)
  RateLimitHandler.new,

  # 6. Authentication
  AuthHandler.new,

  # 7. Static files (can skip auth)
  StaticHandler.new,

  # 8. Endpoints
  UsersEndpoint.new,
  PostsEndpoint.new,
]

class Azu::Handler::Rescuer < Base
  def call(context)
    call_next(context)
  rescue ex : Response::Error
    render_error(context, ex)
  rescue ex
    render_internal_error(context, ex)
  end
end

describe AuthHandler do
  it "allows authenticated requests" do
    context = create_context(headers: {"Authorization" => "Bearer valid"})
    handler = AuthHandler.new

    handler.call(context)

    context.response.status_code.should_not eq(401)
  end

  it "rejects unauthenticated requests" do
    context = create_context
    handler = AuthHandler.new

    handler.call(context)

    context.response.status_code.should eq(401)
  end
end

require "azu"

module MyApp
  include Azu

  configure do
    port = 3000
  end
end

struct HelloRequest
  include Azu::Request
  getter name : String = "World"
end

struct HelloResponse
  include Azu::Response
  def initialize(@name : String); end
  def render
    "Hello, #{@name}!"
  end
end

struct HelloEndpoint
  include Azu::Endpoint(HelloRequest, HelloResponse)
  get "/"
  def call : HelloResponse
    HelloResponse.new(hello_request.name)
  end
end

MyApp.start [
  Azu::Handler::Logger.new,
  Azu::Handler::Rescuer.new
]

# Before
class User
  def full_name
    "#{first_name} #{last_name}"
  end
end

# After - rename to display_name
class User
  def display_name
    "#{first_name} #{last_name}"
  end
end

# Compiler shows every call site that needs updating
# Error: undefined method 'full_name' for User

struct CreateUserRequest
  include Azu::Request

  getter name : String       # Required, must be string
  getter email : String      # Required, must be string
  getter age : Int32?        # Optional, must be integer if present
end

struct UserEndpoint
  include Azu::Endpoint(Request, UserResponse)

  def call : UserResponse  # Must return UserResponse
    if condition
      UserResponse.new(user)
    else
      "error"  # Compile error: expected UserResponse
    end
  end
end

class User
  include CQL::Model(User, Int64)
  db_context AcmeDB, :users

  property id : Int64?
  property name : String
  property email : String
  property created_at : Time?
  property updated_at : Time?

  def initialize(@name = "", @email = "")
  end
end

# Rails controller
def create
  @user = User.new(user_params)
  # What is user_params?
  # What fields are allowed?
  # What validations apply?
end

private

def user_params
  params.require(:user).permit(:name, :email, :age)
  # Scattered across the file
  # Not type-safe
  # Validation elsewhere
end

class NotificationChannel < Azu::Channel
  PATH = "/notifications"

  CONNECTIONS = [] of HTTP::WebSocket

  def on_connect
    CONNECTIONS << socket
  end

  def on_close(code, reason)
    CONNECTIONS.delete(socket)
  end

  def self.broadcast(message : String)
    CONNECTIONS.each do |ws|
      ws.send(message)
    end
  end
end

# In an endpoint
def call
  user = User.create!(create_user_request)

  NotificationChannel.broadcast({
    type: "user_created",
    user: {id: user.id, name: user.name}
  }.to_json)

  UserResponse.new(user)
end

# Add Crystal repository
curl -fsSL https://crystal-lang.org/install.sh | sudo bash

# Fedora
sudo dnf install crystal

# CentOS/RHEL
sudo yum install crystal

# Verify installation
crystal version

require "azu"

# Define your application module
module MyFirstAzuApp
  include Azu

  configure do
    port = 4000
    host = "0.0.0.0"
  end
end

# Create a simple endpoint
struct HelloEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Text)

  get "/"

  def call
    text "Hello from Azu!"
  end
end

# Create a JSON endpoint
struct GreetEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Json)

  get "/greet/:name"

  def call
    json({
      message: "Hello, #{params["name"]}!",
      timestamp: Time.utc.to_rfc3339
    })
  end
end

# Start the server
MyFirstAzuApp.start [
  HelloEndpoint.new,
  GreetEndpoint.new,
]

# Test the hello endpoint
curl http://localhost:4000/
# Output: Hello from Azu!

# Test the greet endpoint
curl http://localhost:4000/greet/World
# Output: {"message":"Hello, World!","timestamp":"2026-01-24T10:30:45Z"}

my_first_azu_app/
├── shard.yml           # Dependencies
├── shard.lock          # Locked versions
├── src/
│   └── my_first_azu_app.cr  # Main application
├── lib/                # Installed dependencies
└── spec/               # Test files

class User
  include CQL::Model(User, Int64)
  db_context AcmeDB, :users

  property id : Int64?
  property name : String
  property email : String
  property age : Int32?

  def initialize(@name = "", @email = "", @age = nil)
  end

  validate name, presence: true, length: {min: 2, max: 100}
  validate email, presence: true, format: /@/, uniqueness: true
  validate age, numericality: {greater_than: 0}, allow_nil: true
end

class Post
  include CQL::Model(Post, Int64)
  db_context AcmeDB, :posts

  property id : Int64?
  property user_id : Int64
  property title : String
  property content : String

  belongs_to :user, User, foreign_key: :user_id
end

class User
  include CQL::Model(User, Int64)
  db_context AcmeDB, :users

  property id : Int64?
  property name : String
  property email : String

  has_many :posts, Post, foreign_key: :user_id
  has_many :comments, Comment, foreign_key: :user_id
end

class Post
  include CQL::Model(Post, Int64)
  db_context AcmeDB, :posts

  property id : Int64?
  property title : String

  has_many :post_tags, PostTag, foreign_key: :post_id
  has_many :tags, Tag, through: :post_tags
end

class Tag
  include CQL::Model(Tag, Int64)
  db_context AcmeDB, :tags

  property id : Int64?
  property name : String

  has_many :post_tags, PostTag, foreign_key: :tag_id
  has_many :posts, Post, through: :post_tags
end

class PostTag
  include CQL::Model(PostTag, Int64)
  db_context AcmeDB, :post_tags

  property id : Int64?
  property post_id : Int64
  property tag_id : Int64

  belongs_to :post, Post
  belongs_to :tag, Tag
end

class User
  include CQL::Model(User, Int64)
  db_context AcmeDB, :users

  property id : Int64?
  property email : String
  property normalized_email : String?

  before_save :normalize_email
  after_create :send_welcome_email
  before_destroy :cleanup_associations

  private def normalize_email
    @normalized_email = email.downcase.strip
  end

  private def send_welcome_email
    Mailer.welcome(self).deliver
  end

  private def cleanup_associations
    posts.each(&.destroy)
  end
end

class Post
  include CQL::Model(Post, Int64)
  db_context AcmeDB, :posts

  property id : Int64?
  property title : String
  property published : Bool
  property created_at : Time?

  scope :published, -> { where(published: true) }
  scope :recent, -> { order(created_at: :desc) }
  scope :by_user, ->(user_id : Int64) { where(user_id: user_id) }
end

# Usage
Post.published.recent.all
Post.by_user(user.id).published.all

class User
  include CQL::Model(User, Int64)
  db_context AcmeDB, :users

  property id : Int64?
  property name : String
  property email : String
  property password_hash : String?

  def full_name
    name
  end

  def password=(plain_password : String)
    @password_hash = Crypto::Bcrypt::Password.create(plain_password).to_s
  end

  def authenticate(plain_password : String) : Bool
    return false unless hash = password_hash
    Crypto::Bcrypt::Password.new(hash).verify(plain_password)
  end

  def recent_posts(limit = 10)
    Post.where(user_id: id).order(created_at: :desc).limit(limit).all
  end
end

class User
  include CQL::Model(User, Int64)
  include JSON::Serializable
  db_context AcmeDB, :users

  property id : Int64?
  property name : String
  property email : String

  @[JSON::Field(ignore: true)]
  property password_hash : String?
end

# Serialize to JSON
user.to_json  # {"id": 1, "name": "Alice", "email": "alice@example.com"}

struct CreateUserRequest
  include Azu::Request

  getter name : String
  getter email : String
  getter age : Int32?

  validate name, presence: true, length: {min: 2}
  validate email, presence: true, format: /@/
end

struct SearchProductsRequest
  include Azu::Request

  getter query : String           # Required search term
  getter category : String?       # Optional filter
  getter min_price : Float64?     # Optional minimum
  getter max_price : Float64?     # Optional maximum
  getter page : Int32 = 1         # Default: first page
  getter per_page : Int32 = 20    # Default: 20 items
end

struct ProductSearchResponse
  include Azu::Response

  def initialize(
    @products : Array(Product),
    @total : Int64,
    @page : Int32
  )
  end

  def render
    {
      data: @products.map { |p| serialize(p) },
      meta: {total: @total, page: @page}
    }.to_json
  end
end

struct CreateOrderRequest
  include Azu::Request

  getter items : Array(OrderItem)
  getter shipping_address : String
  getter payment_method : String

  # Validation right here with the fields
  validate items, presence: true
  validate shipping_address, presence: true
  validate payment_method, inclusion: {in: ["card", "paypal"]}

  # Custom validation in the same struct
  def validate
    super
    errors << Error.new(:items, "too many") if items.size > 100
  end
end

def call : OrderResponse
  # Type is known: Array(OrderItem)
  items = create_order_request.items

  items.each do |item|
    # Type is known: OrderItem
    process(item.product_id, item.quantity)
  end
end

module V1
  struct UserResponse
    include Azu::Response
    # V1 fields
  end
end

module V2
  struct UserResponse
    include Azu::Response
    # V2 fields (breaking changes)
  end
end

# Different endpoints use different versions
struct V1::UsersEndpoint
  include Azu::Endpoint(Request, V1::UserResponse)
end

struct V2::UsersEndpoint
  include Azu::Endpoint(Request, V2::UserResponse)
end

describe CreateUserRequest do
  it "validates presence of name" do
    request = CreateUserRequest.new(name: "", email: "a@b.com")
    request.valid?.should be_false
    request.errors.map(&.field).should contain(:name)
  end

  it "validates email format" do
    request = CreateUserRequest.new(name: "Alice", email: "invalid")
    request.valid?.should be_false
  end
end

# Generate OpenAPI spec from contracts
OpenAPI.generate(CreateUserRequest)
# => {
#      type: "object",
#      required: ["name", "email"],
#      properties: {
#        name: {type: "string", minLength: 2},
#        email: {type: "string", format: "email"}
#      }
#    }

class ChatChannel < Azu::Channel
  PATH = "/chat"

  CONNECTIONS = [] of HTTP::WebSocket

  def on_message(message : String)
    # Broadcast to everyone except sender
    CONNECTIONS.each do |ws|
      ws.send(message) unless ws == socket
    end
  end
end

class RoomChannel < Azu::Channel
  PATH = "/rooms/:room_id"

  @@rooms = Hash(String, Set(HTTP::WebSocket)).new { |h, k| h[k] = Set(HTTP::WebSocket).new }

  def on_connect
    room_id = params["room_id"]
    @@rooms[room_id] << socket
  end

  def on_close(code, reason)
    room_id = params["room_id"]
    @@rooms[room_id].delete(socket)
  end

  def self.broadcast_to(room_id : String, message : String)
    @@rooms[room_id].each(&.send(message))
  end

  def self.broadcast_to_all(message : String)
    @@rooms.each_value do |sockets|
      sockets.each(&.send(message))
    end
  end
end

class UserChannel < Azu::Channel
  PATH = "/user"

  @@user_sockets = Hash(Int64, Set(HTTP::WebSocket)).new { |h, k| h[k] = Set(HTTP::WebSocket).new }

  def on_connect
    if user = authenticate
      @@user_sockets[user.id] << socket
    end
  end

  def on_close(code, reason)
    if user = @current_user
      @@user_sockets[user.id].delete(socket)
    end
  end

  def self.send_to_user(user_id : Int64, message : String)
    @@user_sockets[user_id].each(&.send(message))
  end

  def self.send_to_users(user_ids : Array(Int64), message : String)
    user_ids.each { |id| send_to_user(id, message) }
  end
end

class FilteredChannel < Azu::Channel
  PATH = "/feed"

  record Connection, socket : HTTP::WebSocket, topics : Set(String)

  @@connections = [] of Connection

  def on_connect
    topics = params["topics"]?.try(&.split(",").to_set) || Set(String).new
    @@connections << Connection.new(socket, topics)
  end

  def self.broadcast(topic : String, message : String)
    @@connections.each do |conn|
      if conn.topics.includes?(topic)
        conn.socket.send(message)
      end
    end
  end
end

def self.broadcast_async(message : String)
  spawn do
    CONNECTIONS.each do |ws|
      begin
        ws.send(message)
      rescue
        # Handle disconnected socket
      end
    end
  end
end

# Background job
class OrderProcessor
  def process(order_id : Int64)
    order = Order.find!(order_id)
    order.process!

    # Notify the user
    UserChannel.send_to_user(order.user_id, {
      type: "order_updated",
      order_id: order.id,
      status: order.status
    }.to_json)
  end
end

class ThrottledChannel < Azu::Channel
  @@last_broadcast = Time.utc
  @@min_interval = 100.milliseconds

  def self.broadcast(message : String)
    now = Time.utc
    return if now - @@last_broadcast < @@min_interval

    @@last_broadcast = now
    CONNECTIONS.each(&.send(message))
  end
end

class BatchedChannel < Azu::Channel
  @@pending_messages = [] of String
  @@flush_scheduled = false

  def self.queue(message : String)
    @@pending_messages << message
    schedule_flush unless @@flush_scheduled
  end

  private def self.schedule_flush
    @@flush_scheduled = true
    spawn do
      sleep 50.milliseconds
      flush
    end
  end

  private def self.flush
    return if @@pending_messages.empty?

    batch = {type: "batch", messages: @@pending_messages}.to_json
    CONNECTIONS.each(&.send(batch))

    @@pending_messages.clear
    @@flush_scheduled = false
  end
end

struct CreateUserEndpoint
  include Azu::Endpoint(CreateUserRequest, UserResponse)

  post "/users"

  def call : UserResponse
    # Access request via snake_case method name
    create_user_request.name
    create_user_request.email
  end
end

struct UserEndpoint
  include Azu::Endpoint(EmptyRequest, UserResponse)

  get "/users/:id"

  def call : UserResponse
    user_id = params["id"].to_i64
    user = User.find?(user_id)

    unless user
      raise Azu::Response::NotFound.new("/users/#{user_id}")
    end

    UserResponse.new(user)
  end
end

struct UserResponse
  include Azu::Response

  def initialize(@user : User)
  end

  def render
    {
      id: @user.id,
      name: @user.name,
      email: @user.email
    }.to_json
  end
end

class NotificationChannel < Azu::Channel
  CONNECTIONS = Set(HTTP::WebSocket).new

  ws "/notifications"

  def on_connect
    # Add socket to connections
    CONNECTIONS << socket.not_nil!

    # Send welcome message
    send_to_client({
      type: "connected",
      message: "Connected to notifications",
      timestamp: Time.utc.to_rfc3339
    })

    Log.info { "Client connected. Total: #{CONNECTIONS.size}" }
  end

  def on_message(message : String)
    begin
      data = JSON.parse(message)
      handle_message(data)
    rescue JSON::ParseException
      send_to_client({type: "error", message: "Invalid JSON"})
    end
  end

  def on_close(code, message)
    CONNECTIONS.delete(socket)
    Log.info { "Client disconnected. Total: #{CONNECTIONS.size}" }
  end

  private def handle_message(data : JSON::Any)
    case data["type"]?.try(&.as_s)
    when "ping"
      send_to_client({type: "pong", timestamp: Time.utc.to_rfc3339})
    when "subscribe"
      send_to_client({type: "subscribed", message: "Subscribed to notifications"})
    else
      send_to_client({type: "error", message: "Unknown message type"})
    end
  end

  private def send_to_client(data)
    socket.not_nil!.send(data.to_json)
  end

  # Broadcast to all connected clients
  def self.broadcast(message)
    CONNECTIONS.each do |socket|
      spawn socket.send(message.to_json)
    end
  end
end

struct CreateUserEndpoint
  include Azu::Endpoint(CreateUserRequest, UserResponse)

  post "/users"

  def call : UserResponse
    unless create_user_request.valid?
      raise Azu::Response::ValidationError.new(
        create_user_request.errors.group_by(&.field).transform_values(&.map(&.message))
      )
    end

    if User.find_by_email(create_user_request.email)
      raise Azu::Response::ValidationError.new(
        {"email" => ["Email is already taken"]}
      )
    end

    user = User.new(
      name: create_user_request.name,
      email: create_user_request.email,
      age: create_user_request.age
    )

    # Broadcast to all WebSocket clients
    NotificationChannel.broadcast({
      type: "user_created",
      user: {
        id: user.id,
        name: user.name,
        email: user.email
      },
      timestamp: Time.utc.to_rfc3339
    })

    status 201
    UserResponse.new(user)
  end
end

require "azu"

require "./models/*"
require "./requests/*"
require "./responses/*"
require "./endpoints/*"
require "./channels/*"

module UserAPI
  include Azu

  configure do
    port = ENV.fetch("PORT", "4000").to_i
    host = ENV.fetch("HOST", "0.0.0.0")
  end
end

UserAPI.start [
  Azu::Handler::RequestId.new,
  Azu::Handler::Rescuer.new,
  Azu::Handler::Logger.new,
  Azu::Handler::CORS.new,
  NotificationChannel.new,  # Add the channel
  ListUsersEndpoint.new,
  ShowUserEndpoint.new,
  CreateUserEndpoint.new,
  UpdateUserEndpoint.new,
  DeleteUserEndpoint.new,
]

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Real-time Notifications</title>
  <style>
    body { font-family: Arial, sans-serif; margin: 20px; }
    #notifications {
      border: 1px solid #ddd;
      padding: 10px;
      margin: 20px 0;
      max-height: 300px;
      overflow-y: auto;
    }
    .notification {
      padding: 5px;
      border-bottom: 1px solid #eee;
    }
    .connected { color: green; }
    .disconnected { color: red; }
  </style>
</head>
<body>
  <h1>Real-time Notifications</h1>

  <div id="status" class="disconnected">Disconnected</div>

  <div id="notifications">
    <h3>Events</h3>
  </div>

  <script>
    const statusEl = document.getElementById('status');
    const notificationsEl = document.getElementById('notifications');

    // Connect to WebSocket
    const ws = new WebSocket('ws://localhost:4000/notifications');

    ws.onopen = function() {
      statusEl.textContent = 'Connected';
      statusEl.className = 'connected';

      // Subscribe to notifications
      ws.send(JSON.stringify({ type: 'subscribe' }));
    };

    ws.onmessage = function(event) {
      const data = JSON.parse(event.data);
      addNotification(data);
    };

    ws.onclose = function() {
      statusEl.textContent = 'Disconnected';
      statusEl.className = 'disconnected';
    };

    function addNotification(data) {
      const div = document.createElement('div');
      div.className = 'notification';

      const time = new Date().toLocaleTimeString();

      switch(data.type) {
        case 'user_created':
          div.textContent = `${time}: User created - ${data.user.name}`;
          break;
        case 'user_updated':
          div.textContent = `${time}: User updated - ${data.user.name}`;
          break;
        case 'user_deleted':
          div.textContent = `${time}: User deleted - ID ${data.user_id}`;
          break;
        case 'connected':
        case 'subscribed':
          div.textContent = `${time}: ${data.message}`;
          break;
        default:
          div.textContent = `${time}: ${JSON.stringify(data)}`;
      }

      notificationsEl.appendChild(div);
    }
  </script>
</body>
</html>

UserAPI.start [
  Azu::Handler::RequestId.new,
  Azu::Handler::Rescuer.new,
  Azu::Handler::Logger.new,
  Azu::Handler::CORS.new,
  Azu::Handler::Static.new("public"),  # Serve static files
  NotificationChannel.new,
  # ... endpoints
]

class ChatChannel < Azu::Channel
  @@rooms = Hash(String, Set(HTTP::WebSocket)).new { |h, k| h[k] = Set(HTTP::WebSocket).new }
  @@socket_rooms = Hash(HTTP::WebSocket, String).new

  ws "/chat"

  def on_connect
    send_to_client({
      type: "connected",
      message: "Send a 'join' message with room_id to join a room"
    })
  end

  def on_message(message : String)
    data = JSON.parse(message)

    case data["type"]?.try(&.as_s)
    when "join"
      handle_join(data)
    when "message"
      handle_chat_message(data)
    end
  rescue
    send_to_client({type: "error", message: "Invalid message"})
  end

  def on_close(code, message)
    if room_id = @@socket_rooms[socket]?
      @@rooms[room_id].delete(socket)
      @@socket_rooms.delete(socket)
    end
  end

  private def handle_join(data)
    room_id = data["room_id"]?.try(&.as_s)
    return send_to_client({type: "error", message: "room_id required"}) unless room_id

    @@socket_rooms[socket] = room_id
    @@rooms[room_id] << socket

    send_to_client({type: "joined", room_id: room_id})

    # Notify others in room
    broadcast_to_room(room_id, {
      type: "user_joined",
      message: "A user joined the room"
    }, exclude: socket)
  end

  private def handle_chat_message(data)
    room_id = @@socket_rooms[socket]?
    return send_to_client({type: "error", message: "Not in a room"}) unless room_id

    message = data["message"]?.try(&.as_s)
    return send_to_client({type: "error", message: "Message required"}) unless message

    broadcast_to_room(room_id, {
      type: "chat_message",
      message: message,
      timestamp: Time.utc.to_rfc3339
    })
  end

  private def broadcast_to_room(room_id : String, data, exclude : HTTP::WebSocket? = nil)
    message = data.to_json
    @@rooms[room_id].each do |connection|
      next if connection == exclude
      spawn { connection.send(message) }
    end
  end

  private def send_to_client(data)
    socket.send(data.to_json)
  end
end

require "cql"
require "azu"

# Define schema
AppDB = CQL::Schema.define(:app, adapter: CQL::Adapter::Postgres, uri: ENV["DATABASE_URL"]) do
  table :users do
    primary :id, Int64
    text :name
    text :email
    timestamps
  end
end

# Define model
struct User
  include CQL::ActiveRecord::Model(Int64)
  db_context AppDB, :users

  getter id : Int64?
  getter name : String
  getter email : String
end

# Use in endpoint
struct UserEndpoint
  include Azu::Endpoint(EmptyRequest, UserResponse)

  get "/users/:id"

  def call : UserResponse
    user = User.find(params["id"].to_i64)
    UserResponse.new(user)
  end
end

class AuthenticationHandler
  include HTTP::Handler

  def call(context)
    token = context.request.headers["Authorization"]?

    unless token && valid_token?(token)
      context.response.status = HTTP::Status::UNAUTHORIZED
      context.response.print "Authentication required"
      return
    end

    context.set("current_user", get_user_from_token(token))
    call_next(context)
  end
end

# Add to middleware stack
MyApp.start [
  AuthenticationHandler.new,
  # ... other handlers
]

# ❌ This causes type inference issues
def create_user(request)
  # Crystal can't infer the request type
end

# ✅ Use explicit types
def create_user(request : CreateUserRequest) : UserResponse
  # Clear type information
end

def call : UserResponse
  # Always validate before processing
  unless create_user_request.valid?
    raise Azu::Response::ValidationError.new(
      create_user_request.errors.group_by(&.field).transform_values(&.map(&.message))
    )
  end

  # Process validated request
  UserResponse.new(create_user(create_user_request))
end

struct UserRequest
  include Azu::Request

  getter name : String
  getter email : String

  # ✅ Correct validation syntax
  validate name, presence: true, length: {min: 2}
  validate email, presence: true, format: /@/

  def initialize(@name = "", @email = "")
  end
end

struct FileUploadRequest
  include Azu::Request

  getter file : Azu::Params::Multipart::File?
  getter description : String

  def initialize(@file = nil, @description = "")
  end
end

def call : FileUploadResponse
  if file = file_upload_request.file
    # Validate file
    raise error("File too large") if file.size > 10.megabytes

    # Save file
    final_path = save_uploaded_file(file)
    file.cleanup # Important: clean up temp file

    FileUploadResponse.new(path: final_path)
  else
    raise error("File is required")
  end
end

def call : UserResponse
  # ❌ Blocking database call
  users = database.query("SELECT * FROM users") # Blocks fiber

  # ✅ Use async operations when possible
  users = database.async_query("SELECT * FROM users")
  UserResponse.new(users)
end

class MyChannel < Azu::Channel
  CONNECTIONS = Set(HTTP::WebSocket).new

  def on_connect
    CONNECTIONS << socket.not_nil!
  end

  def on_close(code, message)
    CONNECTIONS.delete(socket) # Remove on disconnect
  end
end

MyApp.start [
  Azu::Handler::CORS.new(
    allowed_origins: ["http://localhost:3000"], # Add your frontend URL
    allowed_methods: %w(GET POST PUT PATCH DELETE OPTIONS),
    allowed_headers: %w(Accept Content-Type Authorization)
  ),
  # ... other handlers
]

def call : UserResponse
  Log.debug { "Request data: #{create_user_request.inspect}" }
  Log.debug { "Params: #{params.to_hash}" }
  Log.debug { "Headers: #{context.request.headers}" }

  # ... endpoint logic
end

# Add pp for pretty printing
require "pp"

def call : UserResponse
  pp create_user_request # Pretty print request object
  pp params.to_hash      # Pretty print parameters

  # ... endpoint logic
end

# Test request contracts in isolation
user_request = CreateUserRequest.new(name: "test", email: "test@example.com")
puts user_request.valid?
puts user_request.errors.map(&.message)

# Test response objects
user = User.new(name: "test")
response = UserResponse.new(user)
puts response.render

# Log slow queries
def call : UserResponse
  start_time = Time.instant

  users = database.query("SELECT * FROM users WHERE active = true")

  duration = Time.instant - start_time
  if duration > 100.milliseconds
    Log.warn { "Slow query detected: #{duration.total_milliseconds}ms" }
  end

  UserResponse.new(users)
end

**Crystal Version**: 1.10.1
**Azu Version**: 0.5.26
**OS**: macOS 13.0

**Issue**: WebSocket connection fails with "Connection refused"

**Reproduction**:
```crystal
class TestChannel < Azu::Channel
  ws "/test"
  def on_connect
    puts "Connected"
  end
end

# Check your system requirements
echo "Operating System: $(uname -s)"
echo "Architecture: $(uname -m)"
echo "Available Memory: $(free -h | grep Mem | awk '{print $2}')"
echo "Available Disk Space: $(df -h . | tail -1 | awk '{print $4}')"

# Install Crystal on macOS
brew install crystal

# Install Crystal on Ubuntu/Debian
curl -fsSL https://crystal-lang.org/install.sh | sudo bash

# Install Crystal on CentOS/RHEL
curl -fsSL https://crystal-lang.org/install.sh | sudo bash

# Verify installation
crystal --version

# Configure Git
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set up SSH key (optional but recommended)
ssh-keygen -t ed25519 -C "your.email@example.com"
cat ~/.ssh/id_ed25519.pub
# Add to GitHub/GitLab

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/your-username/azu.git
cd azu

# Add upstream remote
git remote add upstream https://github.com/azu-framework/azu.git

# Verify remotes
git remote -v

# Create a feature branch
git checkout -b feature/your-feature-name

# Or create a bugfix branch
git checkout -b fix/your-bug-description

# Or create a documentation branch
git checkout -b docs/your-doc-update

// .vscode/settings.json
{
  "crystal.formatOnSave": true,
  "crystal.languageServer": true,
  "crystal.compiler": "crystal",
  "editor.formatOnSave": true,
  "editor.rulers": [120],
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true
}

# shard.yml development dependencies
development_dependencies:
  ameba:
    github: crystal-ameba/ameba
    version: ~> 1.5.0
  db:
    github: crystal-lang/crystal-db
    version: ~> 0.12.0
  sqlite3:
    github: crystal-lang/crystal-sqlite3
    version: ~> 0.20.0

# Install PostgreSQL (macOS)
brew install postgresql
brew services start postgresql

# Install PostgreSQL (Ubuntu)
sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql

# Create development database
createdb azu_development
createdb azu_test

# config/database.cr
CONFIG.database = {
  development: {
    url: "postgresql://localhost/azu_development",
    pool_size: 5
  },
  test: {
    url: "postgresql://localhost/azu_test",
    pool_size: 2
  }
}

# .editorconfig
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 2

[*.cr]
indent_size = 2

[*.yml]
indent_size = 2

[*.md]
trim_trailing_whitespace = false

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:13
        env:
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: azu_test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v3
      - name: Setup Crystal
        uses: crystal-lang/install-crystal@v1
      - name: Install dependencies
        run: shards install
      - name: Run tests
        run: crystal spec
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/azu_test
      - name: Run code analysis
        run: crystal tool run ameba

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Azu",
      "type": "crystal",
      "request": "launch",
      "program": "${workspaceFolder}/src/azu.cr",
      "args": [],
      "cwd": "${workspaceFolder}"
    },
    {
      "name": "Debug Tests",
      "type": "crystal",
      "request": "launch",
      "program": "crystal",
      "args": ["spec"],
      "cwd": "${workspaceFolder}"
    }
  ]
}

# spec/benchmark/performance_spec.cr
require "benchmark"

describe "Performance Benchmarks" do
  it "benchmarks endpoint performance" do
    time = Benchmark.measure do
      1000.times do
        # Test endpoint
      end
    end

    puts "Average time: #{time.real / 1000}ms"
  end
end

# mkdocs.yml
site_name: Azu Framework
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - search.highlight

nav:
  - Overview: index.md
  - Getting Started:
      - Installation: getting-started/installation.md
      - First App: getting-started/first-app.md
  - Core Concepts:
      - Endpoints: core-concepts/endpoints.md
      - Requests: core-concepts/requests.md
      - Responses: core-concepts/responses.md

# spec/spec_helper.cr
require "spec"
require "../src/azu"

# Test configuration
CONFIG.test = {
  database_url: "sqlite3://./test.db",
  log_level: "error",
  environment: "test"
}

# Test utilities
module TestHelpers
  def self.create_test_request(path : String, method : String = "GET")
    Azu::HttpRequest.new(
      method: method,
      path: path,
      params: {} of String => String,
      headers: HTTP::Headers.new
    )
  end
end

# spec/database_helper.cr
module DatabaseHelper
  def self.setup_test_database
    # Create test database schema
    DB.connect(CONFIG.test.database_url) do |db|
      db.exec("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)")
    end
  end

  def self.cleanup_test_database
    # Clean test data
    DB.connect(CONFIG.test.database_url) do |db|
      db.exec("DELETE FROM users")
    end
  end
end

#!/bin/bash
# scripts/build.sh

echo "Building Azu framework..."

# Clean previous build
rm -rf bin/
mkdir -p bin/

# Build release version
crystal build --release src/azu.cr -o bin/azu

# Build debug version
crystal build --debug src/azu.cr -o bin/azu-debug

echo "Build completed!"

#!/bin/bash
# scripts/quality.sh

echo "Running code quality checks..."

# Format code
crystal tool format

# Run Ameba
crystal tool run ameba

# Run tests
crystal spec

echo "Code quality checks completed!"

# Issue: Crystal not found
export PATH="/usr/local/bin:$PATH"

# Issue: Permission denied
sudo chown -R $(whoami) /usr/local/bin

# Issue: Database connection failed
sudo systemctl start postgresql

# Issue: Dependencies not found
shards install --frozen

# Check Crystal installation
crystal --version
which crystal

# Check dependencies
shards list

# Check database connection
psql -h localhost -U postgres -d azu_development

# Check system resources
top
df -h
free -h

# 1. Fork the repository
# 2. Clone your fork
git clone https://github.com/your-username/azu.git

# 3. Create a feature branch
git checkout -b feature/your-feature

# 4. Make your changes
# 5. Run tests
crystal spec

# 6. Commit your changes
git add .
git commit -m "Add feature: description"

# 7. Push to your fork
git push origin feature/your-feature

# 8. Create a pull request

struct DeleteEndpoint
  include Azu::Endpoint(EmptyRequest, Azu::Response::Empty)

  delete "/items/:id"

  def call
    Item.find(params["id"]).destroy
    status 204
    Azu::Response::Empty.new
  end
end

struct UserResponse
  include Azu::Response

  def initialize(@user : User)
  end

  def render
    {
      id: @user.id,
      name: @user.name,
      email: @user.email,
      created_at: @user.created_at.try(&.to_rfc3339)
    }.to_json
  end
end

struct UsersResponse
  include Azu::Response

  def initialize(
    @users : Array(User),
    @page : Int32,
    @total : Int64
  )
  end

  def render
    {
      data: @users.map { |u| serialize_user(u) },
      meta: {
        page: @page,
        total: @total
      }
    }.to_json
  end

  private def serialize_user(user : User)
    {id: user.id, name: user.name}
  end
end

def call
  response.content_type = "application/json"
  response.headers["Transfer-Encoding"] = "chunked"

  response.print "["
  users.each_with_index do |user, i|
    response.print "," if i > 0
    response.print user.to_json
    response.flush
  end
  response.print "]"
end

def call
  case accept_type
  when "application/json"
    json(data)
  when "text/html"
    html(render_html(data))
  when "text/plain"
    text(data.to_s)
  else
    json(data)
  end
end

private def accept_type
  headers["Accept"]?.try(&.split(",").first) || "application/json"
end

struct CreateUserEndpoint
  include Azu::Endpoint(CreateUserRequest, UserResponse)
  #                     ↑ Input type       ↑ Output type

  def call : UserResponse  # ← Must return this type
    # ...
  end
end

def call : UserResponse
  # Type is known - no nil checks needed
  name = create_user_request.name  # String, not String?

  # Optional fields are nil-able
  if age = create_user_request.age
    validate_age(age)
  end

  # ...
end

struct UserResponse
  include Azu::Response

  def initialize(@user : User)
  end

  def render
    {
      id: @user.id,        # Int64
      name: @user.name,    # String
      email: @user.email   # String
    }.to_json
  end
end

def call : UserResponse
  user = User.find?(params["id"])

  # user is User? (might be nil)
  user.name  # Error: undefined method 'name' for Nil

  # Must handle nil case
  if user
    UserResponse.new(user)
  else
    raise Azu::Response::NotFound.new("/users/#{params["id"]}")
  end
end

def call : Azu::Response
  case action
  when "create"
    CreateResponse.new(create_item)
  when "delete"
    status 204
    Azu::Response::Empty.new
  else
    raise Azu::Response::BadRequest.new("Unknown action")
  end
end

class CacheHandler(T) < Azu::Handler::Base
  def call(context)
    key = cache_key(context)

    if cached = Azu.cache.get(key)
      return T.from_json(cached)
    end

    call_next(context)
  end
end

Azu

Tutorials

Building a User API

hashtagWhat You'll Build

Working with Databases

hashtagWhat You'll Build

Building Live Components

hashtagWhat You'll Build

hashtagPrerequisites

hashtagStep 1: Understanding Live Components

hashtagStep 2: Create a Counter Component

hashtagStep 3: Create a Counter Endpoint

hashtagStep 4: Create a Chat Component

hashtagStep 5: Component Lifecycle

hashtagStep 6: State Management

hashtagStep 7: Form Components

hashtagStep 8: Composing Components

hashtagKey Concepts Learned

hashtagComponent Structure

hashtagDOM Updates

hashtagEvent Handling

hashtagBest Practices

hashtagNext Steps

Testing Your App

hashtagWhat You'll Learn

Endpoints

Create an Endpoint

hashtagBasic Endpoint

Handle Parameters

hashtagRoute Parameters

hashtag

Validation

Real-Time

Database

Caching

File Handling

Middleware

Templates

Testing

Deployment

Error Handling

Performance

API Reference

Handlers

Configuration

Errors

Database

Templates

Migration

Architecture

Concepts

Design Decisions

Resources

Building Live Components

hashtagWhat You'll Build

hashtagPrerequisites

hashtagStep 1: Understanding Live Components

hashtagStep 2: Create a Counter Component

hashtagStep 3: Create a Counter Endpoint

hashtagStep 4: Create a Chat Component

hashtagStep 5: Component Lifecycle

hashtagStep 6: State Management

hashtagStep 7: Form Components

hashtagStep 8: Composing Components

hashtagKey Concepts Learned

hashtagComponent Structure

hashtagDOM Updates

hashtagEvent Handling

hashtagBest Practices

hashtagNext Steps

Building a User API

hashtagWhat You'll Build

Working with Databases

hashtagWhat You'll Build

Handle Parameters

hashtagRoute Parameters

hashtag

Create an Endpoint

hashtagBasic Endpoint

Testing Your App

What You'll Build

What You'll Build

What You'll Build

Prerequisites

Step 1: Understanding Live Components

Step 2: Create a Counter Component

Step 3: Create a Counter Endpoint

Step 4: Create a Chat Component

Step 5: Component Lifecycle

Step 6: State Management

Step 7: Form Components

Step 8: Composing Components

Key Concepts Learned

Component Structure

DOM Updates

Event Handling

Best Practices

Next Steps

What You'll Learn

Basic Endpoint

Route Parameters

What You'll Build

Prerequisites

Step 1: Understanding Live Components

Step 2: Create a Counter Component

Step 3: Create a Counter Endpoint

Step 4: Create a Chat Component

Step 5: Component Lifecycle

Step 6: State Management

Step 7: Form Components

Step 8: Composing Components

Key Concepts Learned

Component Structure

DOM Updates

Event Handling

Best Practices

Next Steps

What You'll Build

What You'll Build

Route Parameters

Basic Endpoint

What You'll Learn

Prerequisites

Step 1: Project Setup

Step 2: Create the User Model

Step 3: Create Request Contracts

Step 4: Create Response Objects

Step 5: Create Endpoints

Step 6: Create the Main Application

Step 7: Run and Test

Create a User

List Users

Get a User

Update a User

Delete a User

Test Validation

Key Concepts Learned

Type-Safe Contracts

Automatic Validation

Structured Error Responses

Route Parameters

Project Structure

Next Steps

Prerequisites

Step 1: Add CQL Dependencies

Step 2: Define the Schema

Step 3: Create the Database

Step 4: Create the Model

Step 5: Update Endpoints

Step 6: Update Main Application

Step 7: Adding Relationships

Step 8: Query Examples

Environment Configuration

Key Concepts Learned

Schema Definition

Model Definition

CRUD Operations

Next Steps

Query Parameters

Request Body (JSON)