Jimmu (神武)

A lightweight Ruby web framework. Full-featured but simple: ERB, SQLite, file-based routing, and WebSockets in one file, so you can go from nothing to a working small web app in minutes.

gem install jimmu
jimmu new myapp
cd myapp
jimmu server

Then visit http://127.0.0.1:3000/.

Why

• One file. The entire framework is lib/jimmu.rb. Nothing to configure, nothing to generate boilerplate for.
• No native gem dependencies. SQLite support talks directly to your system's libsqlite3 via Ruby's built-in Fiddle library -- there's no sqlite3 gem, so there's no native extension to compile when you install. Everything else is Ruby standard library.
• A file is a page. Drop a .erb file under views/ and it's routable. No router config, no controller classes.

Installing

gem install jimmu

Requires Ruby >= 2.7 and a system SQLite3 shared library, which ships with macOS and is available via your package manager on Linux (apt install libsqlite3-0, dnf install sqlite-libs, etc.) and typically already present with Ruby installations on Windows.

The CLI

Command	Effect
jimmu new <name>	Create a new project in ./<name>
jimmu server	Start the dev server, reading ./app.rb
jimmu server -p 8080	...on a specific port (overrides port in app.rb)
jimmu server -h 0.0.0.0	...on a specific host (overrides host in app.rb)
jimmu version	Print the installed version
jimmu help	Show usage

Project layout

myapp/
├── app.rb              # entry point -- config, hooks, then `run`
├── views/
│   ├── layout.erb       # auto-applied around every page unless disabled
│   ├── index.erb        # ->  /
│   ├── 404.erb           # shown on 404
│   └── 500.erb           # shown on unhandled errors
├── public/
│   ├── css/style.css    # ->  /css/style.css
│   ├── js/app.js         # ->  /js/app.js
│   └── img/
└── db/                   # SQLite files live here by convention

File-based routing

A file's path under views/ becomes its URL. index.erb files match their parent directory:

views/index.erb              ->  /
views/about.erb               ->  /about
views/blog/index.erb          ->  /blog
views/blog/post.erb           ->  /blog/post

Square brackets make a segment dynamic and land in params:

views/user/[id].erb                  ->  /user/:id            params[:id]
views/post/[category]/[id].erb       ->  /post/:category/:id  params[:category], params[:id]

A literal file always wins over a dynamic one at the same level (so views/user/admin.erb would take priority over views/user/[id].erb for /user/admin specifically, while every other value still hits the dynamic route).

Every HTTP method routes through the same file -- check request.method inside the template to branch between, say, showing a form on GET and handling its submission on POST to the same path.

Inside a view

Each .erb file has access to:

params[:id]                    # route + query + form + JSON body params (merged)
request.method                 # "GET", "POST", ...
request.path                   # "/user/42"
request.ip                     # client IP
request.header("user-agent")   # any request header, by lowercase name
request.query_params           # just the ?query=string part
cookie[:theme]                 # read a cookie
cookie[:theme] = "dark"        # queue a Set-Cookie
session[:user_id]              # read/write server-side session data
                                # (survives across requests via a cookie;
                                # cleared with session.clear or session.delete(:k))

status 404                     # set the response status (doesn't stop rendering)
header "X-Custom", "value"     # set a response header

redirect "/login"              # 302 and stop
json(ok: true)                 # render JSON and stop
text "plain text"              # render text/plain and stop
html "<b>hi</b>"                # render text/html and stop
render "other_view"            # render another view (through the layout) and stop

layout false                   # skip views/layout.erb for this render

log "message"                  # timestamped line on the server console
db                              # the most recently opened `sqlite` connection

redirect / json / text / html / render all end the current template immediately -- nothing written after them in the same .erb file runs.

Layouts

views/layout.erb wraps every page automatically; put <%= yield %> where the page's own content should go. Turn it off per-page with <% layout false %> anywhere in that page's template.

Errors

views/404.erb renders on an unmatched route; views/500.erb renders on an unhandled exception (it can read error.message / error.backtrace if you want to show details, or just show a friendly message). You can also trigger either one yourself:

<% unless post
     status 404
     render "404"   # note: a string, not :404 -- see "Gotchas" below
   end %>

If neither file exists, Jimmu shows its own built-in page -- a plain message for 404, and a full backtrace for 500 (since that's only ever seen when you haven't set up your own error page, it defaults to maximally useful rather than maximally polished).

SQLite

# in app.rb
db = sqlite "db/app.db"
db.exec("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT)")

<%# in any view %>
<% users = db.query("SELECT * FROM users WHERE name = ?", params[:name]) %>
<% db.exec("INSERT INTO users(name) VALUES (?)", params[:name]) %>
<% db.transaction do
     db.exec("...")
     db.exec("...")
   end %>

query returns an Array of Hashes with Symbol keys. exec returns the number of rows changed. db.last_insert_rowid gives you the last auto-increment id. ? placeholders are the only supported binding style; always use them for anything that includes user input.

File uploads

<form method="post" enctype="multipart/form-data">
  <input type="file" name="avatar">
</form>

<% file = params[:avatar]
   file.filename        # "photo.png"
   file.content_type    # "image/png"
   file.size             # bytes
   file.save("public/uploads/photo.png") %>

WebSockets

Registered in app.rb, separately from the file-based view routes:

websocket "/ws/[room]" do
  log "opened: #{params[:room]}"
  on_message { |msg| send("echo: #{msg}") }
  on_close   { log "closed" }
end

Inside the block (and inside on_message / on_close), self is the connection, so send, close, params, session, cookie, request, log, and db are all available directly. There's no special "broadcast" method -- see examples/chatroom and examples/poll for the few lines of plain Ruby (a shared Array/Hash + Mutex) it takes to build one yourself.

Hooks

before do
  log "#{request.method} #{request.path}"
end

after do
  header "X-Powered-By", "Jimmu"
end

before runs ahead of every request (including static files); calling redirect/json/etc. inside one stops the request right there, which is enough to build things like auth gates. after runs once a response body has been produced.

Gotchas

• render "404", not render :404. :404 isn't valid Ruby (a bare symbol can't start with a digit) -- use a String for view names that start with a number.
• Helpers belong at the true top level of app.rb. def my_helper / MY_CONST = ... / module Helpers ... end written directly in app.rb are ordinary top-level Ruby and are callable from anywhere -- views, before/after, websocket blocks. (Concretely: app.rb is loaded as a normal file, not stringwise eval'd, specifically so this works.)
• Sessions are in-memory. They reset when the server restarts. Fine for development and small apps; swap in a database-backed store yourself if you need durability.
• One request per connection. Keep-alive isn't implemented -- each HTTP request gets its own TCP connection, which keeps the server simple. This doesn't apply to WebSocket connections, which stay open as long as the client does.
• No chunked request bodies. Incoming requests are read via Content-Length; chunked Transfer-Encoding on requests isn't parsed (this practically never comes up for browser form posts or fetch()).

Examples

Twelve complete apps in examples/, each jimmu server-able as-is:

Example	Shows off
hello-world	The absolute minimum, plus one dynamic route
bbs	A message board -- SQLite, forms, session-remembered name
chatroom	Named chat rooms over WebSocket, with a hand-rolled broadcast
todo	SQLite CRUD via small per-action routes
blog	Posts list/detail, /post/[id], a create form, custom 404
counter	A JSON API endpoint called from client-side fetch()
url-shortener	Dynamic redirect route, plus a JSON API to create links
visitor-counter	before hook + cookie to tell new vs. returning visitors
image-upload	multipart/form-data, saving into public/, a gallery
poll	WebSocket used to push live results to every open tab
json-api	A headless JSON REST API (no HTML views at all)
login-demo	Session-based auth with a before-hook route guard

cd examples/chatroom
jimmu server

(If you're running straight from this source checkout rather than an installed gem, use ruby -I../../lib ../../exe/jimmu server instead, or gem install --local the built .gem first.)

License

MIT. See LICENSE.