Hibana 火花

A single spark can start a prairie fire.

A lightweight Elixir web framework built on Plug and Cowboy for APIs and microservices. Direct routing like Sinatra, powerful plugins like Phoenix, full OTP under the hood.

• 10 lines to a production-grade API
• 35 plugins for auth, caching, real-time, monitoring
• Millions of connections on the BEAM without changing a line
• Fault tolerance -- Supervisors restart failures before users notice

Quick Start

# lib/my_app/router.ex
defmodule MyApp.Router do
  use Hibana.Router.DSL

  plug Hibana.Plugins.BodyParser

  get "/hello" do
    json(conn, %{message: "Hello, World!"})
  end
end

# lib/my_app/endpoint.ex
defmodule MyApp.Endpoint do
  use Hibana.Endpoint, otp_app: :my_app
end

mix deps.get && mix run
curl http://localhost:4000/hello
# => {"message":"Hello, World!"}

Features

Core

Real-time

Background Processing

Infrastructure

Plugins

Security & AuthJWT | OAuth (Google, GitHub, Facebook) | Auth | APIKey | TOTP | RequestSigning | CORS | ScopedCORS | RateLimiter | DistributedRateLimiter

Request ProcessingBodyParser | Session | RequestId | Compression | ContentNegotiation | APIVersioning | I18n

Monitoring & OpsLogger | ColorLogger | Metrics | HealthCheck | GracefulShutdown | TelemetryDashboard | LiveDashboard

Data & ContentCache | OTPCache | Static | Upload | GraphQL | Search | SEO

Development & AdminErrorHandler | DevErrorPage | Admin | LiveViewChannel

Showcases

REST API with Controller

defmodule MyApp.Router do
  use Hibana.Router.DSL

  plug Hibana.Plugins.BodyParser
  plug Hibana.Plugins.CORS, origins: ["*"]

  get "/users", UserController, :index
  get "/users/:id", UserController, :show
  post "/users", UserController, :create
end

defmodule MyApp.UserController do
  use Hibana.Controller

  def index(conn), do: json(conn, %{users: ["Alice", "Bob"]})

  def show(conn) do
    json(conn, %{user: %{id: conn.params["id"]}})
  end

  def create(conn) do
    conn |> Plug.Conn.put_status(201) |> json(%{created: conn.body_params})
  end
end

JWT-Protected API

defmodule MyApp.Router do
  use Hibana.Router.DSL

  plug Hibana.Plugins.JWT, secret: "your-secret", paths: ["/api"]

  get "/api/profile" do
    json(conn, %{user: conn.assigns[:current_user]})
  end
end

WebSocket Chat

defmodule MyApp.ChatSocket do
  use Hibana.WebSocket

  def init(conn, _opts), do: {:ok, conn, %{}}

  def handle_in(message, state) do
    {:reply, {:text, "Echo: #{message}"}, state}
  end
end

Background Jobs with Retry

defmodule MyApp.SendEmail do
  use Hibana.Queue.Job

  def perform(data) do
    Mailer.send(data[:to], data[:subject], data[:body])
  end
end

# Enqueue with 3 retries and 5-second delay
SendEmail.enqueue(%{to: "user@example.com"}, delay: 5000, retry: 3)

Cron Scheduler

defmodule MyApp.Scheduler do
  use Hibana.Cron

  cron "*/5 * * * *", :cleanup_sessions
  cron "0 0 * * *", :daily_report

  def cleanup_sessions, do: Session.cleanup_expired()
  def daily_report, do: Reports.generate_daily()
end

Comparison

Hibana is not a Phoenix replacement. Phoenix is the right choice for full-stack web applications with complex front-ends. Hibana targets developers building APIs, microservices, and lightweight backends who want direct routing with batteries included.

The Name

火花 (Hibana) -- noun. A spark. The flash of light when steel strikes stone.

In the Japanese blacksmith tradition, the spark is the beginning of everything. Days of folding and hammering follow, but nothing starts without that initial flash from steel against stone. Hibana follows the same philosophy:

1. 一撃 (Ichigeki) -- One strike. One route. Start small.
2. 重ねる (Kasaneru) -- Layer by layer. Add plugins as you grow.
3. 鍛える (Kitaeru) -- Forge under pressure. The BEAM handles the heat.
4. 折れない (Orenai) -- Unbreakable. Supervisors catch every fall.

Sample Apps

cd sample_apps/hello_world && mix deps.get && mix run

Commands

# Server
mix run                              # Start server
mix server                           # Start server (alias)

# Generators
mix gen.app my_app                   # New project
mix gen.controller User              # Controller
mix gen.model User name:string       # Model
mix gen.scaffold User name:string    # Full scaffold
mix gen.migration create_users       # Migration

# Utilities
mix routes                           # List routes
mix secret                           # Generate secret key

# Database
mix db.create                        # Create database
mix db.migrate                       # Run migrations
mix db.rollback                      # Rollback migration
mix db.seed                          # Seed data

# Tests
cd apps/hibana && MIX_ENV=test mix test
cd apps/hibana_plugins && MIX_ENV=test mix test

Architecture

hibana/
├── apps/
│   ├── hibana/                # Core framework
│   ├── hibana_plugins/        # 35 built-in plugins
│   ├── hibana_ecto/           # Database support (MySQL, PostgreSQL, MongoDB)
│   └── hibana_generator/      # Mix tasks and project generator
├── sample_apps/               # Demo applications
└── config/

License

MIT -- see LICENSE for details.