Heimdall is listening.

1. 1

   Heimdall accepts

   A fixed pool of worker threads accepts on the shared socket, so concurrency is bounded, not unbounded. Each frames the request (Content-Length or chunked), rejecting ambiguous framing before it can smuggle.

2. 2

   The runes wrap

   next(&b) advances an index through the registered middleware — logger, cors, csrf — each free to act before and after the call downstream.

3. 3

   Dispatch matches

   Method first, then a segment-wise path match. :name segments capture into params. A Ward may guard the route; HEAD falls back to the GET handler with the body dropped.

4. 4

   The handler answers

   Your procedure reads params/JSON/form, perhaps draws a well, and writes back with text, json, or a woven template. On SIGTERM the pool drains in-flight requests and exits cleanly.

A rune is a proc(b: ^Bifrost, next: Next). Inscribe one with rune; they run in registration order, each wrapping everything after it. Calling next(b) runs the next layer — or, at the end, dispatches the route. Skip the call to short-circuit, the way cors answers a preflight OPTIONS directly or csrf rejects a tokenless POST with a 403.

gh.rune(&app, gh.logger)     // one structured, colored line per request
gh.rune(&app, gh.cors)       // CORS headers + preflight short-circuit
gh.rune(&app, gh.csrf)       // synchronizer-token CSRF, session-backed
gh.rune(&app, gh.rate_limit) // per-client token bucket -> 429 + Retry-After

cors :: proc(b: ^gh.Bifrost, next: gh.Next) {
    gh.set_header(b, "Access-Control-Allow-Origin", "*")
    if b.method == .Options {
        gh.text(b, 204, "")  // do not call next
        return
    }
    next(b)  // run the rest of the onion
}

rate_limit hands each client a bucket of rate_limit_burst tokens that refills at rate_limit_rps per second: bursts pass untouched, and only sustained excess is refused — with a 429 and a Retry-After saying when the next token lands. It pairs with the bounded worker pool: the pool caps how much work runs at once, this caps how fast any one client may ask for it. Clients are keyed by the peer address captured at accept; behind a trusted reverse proxy, set rate_limit_trust_forwarded to key on X-Forwarded-For instead (it's forgeable, so only with a proxy you trust). Idle buckets are swept, so the table can't grow unbounded.

Custom error pages. on_error swaps the framework's plain-text errors for your own — the ones Gjallarhorn emits on your behalf: 404 (no route), 500 (a handler panicked), 403 (path traversal), the 401 a Ward falls back to. The 500 handler runs under its own recovery guard, so even a bug in it degrades to the plain default rather than crashing the worker.

gh.on_error(&app, 404, proc(b: ^gh.Bifrost) {
    gh.html(b, 404, "<h1>Lost in Niflheim</h1>")
})

Observability comes as two more runes. request_id tags each request — reusing a sane inbound X-Request-Id so an upstream proxy's trace carries through, else minting one — exposes it on b.request_id, echoes it in the response header, and has the logger print it, so a log line, the client's response, and the trace all line up. metrics counts requests by status, in-flight, and cumulative latency, and serves a Prometheus exposition at /metrics (excluded from its own counts).

gh.rune(&app, gh.metrics)      // outermost — times the chain, serves /metrics
gh.rune(&app, gh.request_id)   // before logger, so the id reaches log + header
gh.rune(&app, gh.logger)

// $ curl localhost:8091/metrics
// gjallarhorn_requests_total{status="2xx"} 128
// gjallarhorn_requests_in_flight 2

Mímir guards the well beneath Yggdrasil whose water is memory. In the myth Óðinn traded an eye for a single draught; here your structs describe a shape and Mímir remembers it as rows. You never write a CREATE TABLE, you never write an INSERT, and — the load-bearing promise — values never reach the SQL string. Every value is a bound parameter ($1, $2, …) carried end-to-end through a from-scratch PostgreSQL wire client: SCRAM-SHA-256 auth, a connection pool, optional TLS, no libpq.

The model — db: tags are the schema

A struct field's db: tag is its column: a name, then comma-separated flags. Field type decides the SQL type; wrap it in Maybe(T) to make the column nullable.

Article :: struct {
    id:       int           `db:"id,pk,auto"`,          // BIGINT primary key, auto-assigned
    slug:     string        `db:"slug,unique,notnull"`,  // UNIQUE NOT NULL TEXT
    author:   int           `db:"author_id,fk:users.id"`, // REFERENCES users(id)
    body:     string        `db:"body"`,
    tags:     gh.Json        `db:"tags"`,                 // JSONB
    posted:   time.Time      `db:"posted_at"`,            // TIMESTAMPTZ
    edited:   Maybe(time.Time) `db:"edited_at"`,          // nullable — NULL is None, not a zero time
    secret:   string        `db:"-"`,                    // skipped: no column at all
}

Odin types map to columns both directions — the DDL Mímir carves, the parameter it binds, and the value scan hydrates back:

The five verbs

Mímir's vocabulary is the well's. Build a statement with a verb, then run it against a Well — the handle to the live connection, drawn from the Bifrost (well(b)) or the App (well(app)).

Reading — the query builder

recall starts a SELECT over a model's columns; chain whose (WHERE), join, order_by, and limit, then sql to freeze it into a statement. In whose, write ? for each value — Mímir renumbers them to $1, $2, … and ships the values separately. That is the SQL-injection checkpoint, and it holds no matter what the value is.

w := gh.well(b)
q := gh.recall(w, Article)
gh.join(&q, "JOIN users ON users.id = articles.author_id")
gh.whose(&q, "users.name = ? AND posted_at > ?", name, since)  // ? -> $1, $2
gh.order_by(&q, "posted_at DESC")
gh.limit(&q, 20)

rows, ok := gh.query(w, gh.sql(&q))          // query -> Pg_Rows; exec -> bool (no rows)
articles := gh.scan(rows, Article)            // []Article, fields hydrated by db: name

scan hydrates every row into a []T; scan_one returns the first with an ok for the empty case. Columns match fields by mapped name — an unmatched column is ignored, an unmatched field left zero — and a Maybe(T) field distinguishes a real NULL from an empty value.

Writing, and reading the error

A failed query isn't just false: Pg_Rows.err carries the Postgres SQLSTATE, so a handler can tell a constraint violation from an outage and answer accordingly.

rows, ok := gh.query(w, gh.offer(w, Article{slug = slug, body = body}))
if !ok {
    if gh.failed(rows) && rows.err.code == "23505" {   // unique_violation
        gh.text(b, 409, "slug already taken")
    } else {
        gh.text(b, 503, "database unavailable")
    }
    return
}
id, _ := strconv.parse_int(rows.rows[0][0])   // the RETURNING id

// amend / forget target the row by its primary key.
gh.exec(w, gh.amend(w, Article{id = id, body = "edited"}))
gh.exec(w, gh.forget(w, Article{id = id}))

Transactions

tx pins one pooled connection, wraps your closure in BEGIN/COMMIT, and rolls back if it returns false — so a batch is all-or-nothing. (For a transaction that must span several handlers, pin/unpin hold a dedicated connection across calls.)

ok := gh.tx(w, proc(w: gh.Well) -> bool {
    _, a := gh.query(w, gh.offer(w, Article{slug = "a"}))
    _, b := gh.query(w, gh.offer(w, Article{slug = "b"}))
    return a && b   // either insert failing rolls back both
})

Migrations

remember hands Mímir a model; at run(), migrate carves any missing tables and ALTERs in any new columns you've added since — additive, non-destructive, logged. Set db_type to .Postgres, .MySQL, or .SQLite for the dialect. DDL is generated for all three; Postgres and SQLite have live drivers (SQLite is opt-in: -define:GJ_SQLITE=true, links libsqlite3), while MySQL is DDL-only for now.

// SQLite: same query/exec/scan/tx path, against a file or :memory:
app := gh.new(gh.Config{ db_type = .SQLite, sqlite = "app.db" })
// odin build . -define:GJ_SQLITE=true

A handler often needs to call out — a payment gateway, a webhook, another service. fetch is a small outbound HTTP(S) client built from the same pieces as the server: net for the socket, wire_send/wire_recv (which already abstract plaintext vs TLS), and parse_headers for the reply. It sends Connection: close, reads to EOF, and de-chunks a chunked response.

// The zero-value request is a plain GET.
res, ok := gh.fetch("https://api.example.com/v1/things")
if ok && res.status == 200 {
    payload: My_Type
    json.unmarshal(res.body_bytes, &payload)  // res.body is the same bytes as string
}

// Method, headers, body, timeout via Fetch_Request; reply headers are lower-cased.
res, ok = gh.fetch("https://api.example.com/things", gh.Fetch_Request{
    method  = "POST",
    headers = {"Authorization" = "Bearer …"},
    body    = `{"name":"skuld"}`,
})

// fetch_json marshals the payload and sets Content-Type: application/json.
res, ok = gh.fetch_json("POST", "https://api.example.com/things", My_Type{})

ok is false only on a transport failure (DNS, connect, TLS, or no parseable response) — a 4xx/5xx still returns ok=true with the status set. Redirects are returned, not followed (read res.headers["location"]). An https:// URL needs a -define:GJ_TLS=true build — the same OpenSSL gate as the DB and server — and without it an https fetch fails fast instead of falling back to plaintext.

Flip one config flag and Gjallarhorn serves a docs page — a Loom template carried in the binary — plus an openapi.json document, both generated from the route table the router already holds. Nothing to keep in sync: register a route and it appears. It's off by default, so a public app pays nothing until it opts in.

app := gh.new(gh.Config{
    port = 8091,
    docs = gh.Docs_Config{
        enabled     = true,          // off by default
        title       = "My API",
        version     = "1.2.0",
    },
})

// Give a route its schema — reflected into JSON Schema + an example body.
gh.get(&app, "/sample/:id", get_handler)
gh.describe(&app, .Get, "/sample/:id", {summary = "Fetch one sample", response = Sample})
gh.post(&app, "/sample", create_handler)
gh.describe(&app, .Post, "/sample", {request = Sample, response = Sample})

The page is interactive: each endpoint expands to a Try it panel with inputs for its path parameters, an editable JSON request body, and an Execute button that fires the request from the browser — a plain same-origin fetch — and shows the live status and response. Ward-guarded routes carry a 🔒. Alongside it, /api-docs/openapi.json is a valid OpenAPI 3.0.3 document: :id becomes an {id} path parameter, methods on a shared path are grouped, and a guarded route advertises a 401.

describe points a route at its Odin request/response types, and Gjallarhorn reflects them into schema and example values with the same reflection Mímir uses — a Maybe(T) field becomes a nullable property, nested structs and slices recurse, and property names follow a json: tag or the field name. It's additive: an undescribed route still lists, just without a body schema, and what isn't described is omitted rather than invented. Because Execute sends a real request it passes through your middleware — a POST behind the csrf rune gets the same 403 a browser would — so what you see is the truth. Point Swagger UI or openapi-generator at the spec URL too.

On Arch Linux, install the gjallarhorn command from the AUR — it ships the framework source, which gjallarhorn new vendors into your project:

# Arch Linux (AUR)
yay -S gjallarhorn-git           # or: paru -S gjallarhorn-git
gjallarhorn new blog

Or work from a checkout — the framework is a single dependency-free Odin package, so there's nothing to fetch but the compiler:

# From a git checkout
git clone https://github.com/Lvcky-gg/Gjallarhorn.git && cd Gjallarhorn
docker compose up -d             # optional: Postgres for the ORM
odin run .                       # serves the sample on :8091
odin test ./tests                # the test suite
odin build cli -out:gh           # build the CLI yourself