# melee

> melee runs small Ruby web apps. Each app is a directory compiled to a native binary by Spinel, run in a
> kernel sandbox, and served on demand. The app-facing surface is Sinatra-shaped: top-level `get`/`post`
> blocks in `app.rb`, `params`, `session`, `render`, `redirect`, `halt`, `db`. Templates are `.erb` files
> compiled at build time; migrations are `.sql` files; static assets are files in `public/`. The Ruby is real
> Ruby minus anything that decides what to call at runtime — no `eval`, no `method_missing`, no threads, no
> gems — because the whole program is compiled ahead of time. One request is one process, which is why every
> helper can be a plain top-level method with no argument to thread through.

## Rules in ten lines

1. Routes are `get "/path" do ... end` at the top level of `app.rb`; the block takes no arguments and its
   return value is the response. A `String` is HTML with status 200.
2. `params.fetch(:x)` returns a `String` (`""` when absent). `params[:x]` returns `String` or `nil`. Use
   `fetch` unless nil and empty must differ. Values are always Strings; convert with `.to_i`, `.to_f`.
3. `db` is a method, never a constant: `db.query(sql, *binds)` -> `Array[Hash{String => value}]`,
   `db.first` -> `Hash` or `nil`, `db.run` -> changed rows, `db.transaction { ... }`. Always `?`
   placeholders, never interpolation. Index rows with `row["name"]`, never `row[:name]`.
4. Migrations are files in `db/migrations/NNN_name.sql`, applied in name order, never edited once applied.
5. Templates are `views/name.erb`, rendered with `render :name, local: value`; partials are `views/_x.erb`,
   rendered with `partial :x, local: value`. Every template declares its locals on line one:
   `<%# locals: (a:, b: nil) %>`. `<%= %>` escapes, `<%== %>` does not. Every form needs `<%= csrf_field %>`.
6. `redirect "/x"` (always 303) and `halt 404` / `halt 400, "why"` do not return; they end the request.
   `status 201` and `header "K", "v"` adjust the response the block is about to return, but are ignored by
   `redirect` and `halt`.
7. String literals are frozen. Build strings with `+""` and `<<`, and put
   `# frozen_string_literal: true` at the top of every file.
8. There is no `Date` and no `Time.parse`. Use `Time.now`, `Time.at(i)`, `Time.local(y, m, d)`, `strftime`,
   and store timestamps as Unix seconds or `YYYY-MM-DD` text.
9. No gems and no `require` outside: `json`, `base64`, `digest`, `securerandom`, `uri`, `net/http`,
   `openssl`, `set`, `csv`, `strscan`, `optparse`, `pathname`, `tmpdir`, `forwardable`. Never `stringio`.
   `require_relative "lib/thing"` for your own files.
10. No `eval`, `method_missing`, computed `define_method`/`send`, `Class.new`, `ObjectSpace`, threads or
    background jobs. Dispatch with `case`. Spell a rescued class in full — `rescue Melee::HTTP::Error`, never
    `rescue HTTP::Error` — because a rescue through a constant alias never matches. Wrong arity, `nil` errors
    and **any undefined method reached through an explicit receiver** (`db.frist(...)`) are not caught at
    build time, so run the app under `melee dev` before pushing.

## Pages

- [API reference](reference.md): every method with its signature, generated from the RBS signatures. Start here to check a name or an argument.
- [The app](app.md): project layout, `app.rb`, routes and patterns, `before` filters, `not_found`, `error`, and the request lifecycle.
- [Reading the request](request.md): `params`, `form`, `query`, `request`, headers, cookies, JSON bodies, `session`, `ENV`.
- [Writing the response](response.md): what a route may return, `render`, `redirect`, `halt`, `json`/`text`/`html`, `status`, `header`, streaming.
- [Templates](templates.md): `.erb` compilation, strict locals, layout, partials, escaping and `<%== %>`, `csrf_field`, what is callable in a template.
- [Database](database.md): `db.query/first/run/exec/transaction/last_id`, the row shape, migrations as files, `setting`, WAL and the one-writer rule.
- [Durable objects](objects.md): `class X < Durable`, `Klass.get/list/count`, `storage` and its `get`/`put`/`delete`, `timer`/`on_timer`/`cancel_timer`, `setup`, `destroy`, object migrations, the positional-and-JSON-shaped rules, object routes (`to: "Lesson#show"` with `view:` or `redirect:`), `Durable::RemoteError`, `melee objects`.
- [Outbound HTTP](http.md): `HTTP.get`/`post`, timeouts, redirects, the error classes, TLS.
- [Logging](logging.md): `log.debug/info/warn/error` with fields, where lines go in development and production, what the 500 line contains.
- [Security](security.md): signed sessions, CSRF, `secure_equal?`, `random_token`, `h`, what is on by default and what you must do yourself.
- [The Ruby that compiles](dialect.md): the dialect rules with the workaround for each — metaprogramming, threads, rescue clauses, Time, gems, frozen literals, inferred types.
- [Working on an app](dev.md): `melee new`, `melee dev`, `melee check`, `melee push`, `melee logs`/`env`/`restart`, the diagnostics format, the generated files.

## Optional

- [The whole manual](../../docs/guide/llms.txt): the introduction, the tutorial, the cookbook guides, the limitations and the operator documentation. These pages are its reference section.
- [Worked example](../../examples/kitchen/): the kitchen calendar — routes, filters, templates, migrations, an outbound feed fetch.
- [Dialect research](../../docs/research/spinel.md): every Spinel trap found so far, including the ones only the stdlib hits.
- [What implements the surface](../../docs/design/stdlib.md): the layer map from the DSL down to the frame protocol.