roda

roda — go-ruby-roda

A pure-Go (no cgo) reimplementation of the routing-tree engine at the heart of Ruby's Roda — the segment-consuming request router of MRI 4.0.5's roda gem (the Roda 3.x line). It models Roda's defining idea — a single route block that peels path segments off the front of the request as it descends, capturing them for the branch that handles them — and produces the Rack [status, headers, body] tuple, without any Ruby runtime.

It is a routing backend for go-embedded-ruby, but is a standalone, reusable module — a sibling of go-ruby-rack (the Rack core, which it builds on for the environment and header machinery), go-ruby-erb and go-ruby-regexp.

What it is — and isn't. Matching against the request and consuming the path is fully deterministic and lives here as pure Go. Running the route block is not: it is a Ruby block (in a rbgo binding) or a Go closure (standalone), supplied through the injectable Handler seam. The engine drives the routing tree and the block re-enters it. The HTTP server — the socket accept loop, TLS — is the host's job and is out of scope, exactly as it is for Rack.

The routing tree

A Roda app is one route block. Inside it, matcher methods each try to match the front of the remaining path; a matched on consumes the segments it matched, yields any captures to its block, and terminates the request:

app := roda.New(func(r *roda.RodaRequest) (bool, any) {
    r.Root(func(r *roda.RodaRequest, _ []any) (bool, any) {
        return true, "welcome"                       // GET /
    })
    r.On(func(r *roda.RodaRequest, _ []any) (bool, any) {
        // remaining path here is what's left after "/api"
        r.Is(func(r *roda.RodaRequest, c []any) (bool, any) {
            return true, "user " + c[0].(string)     // GET /api/users/42 -> "user 42"
        }, "users", roda.Sym("id"))
        r.Get(func(r *roda.RodaRequest, _ []any) (bool, any) {
            return true, "api root"                   // GET /api
        })
        return false, nil
    }, "api")
    return false, nil                                 // nothing matched -> 404
})

status, headers, body := app.Call(env)                // Rack triplet

Matchers

On, Is and the verb matchers take any number of matcher values; the engine dispatches on each value's dynamic type, exactly as the roda gem dispatches on the matcher's class:

• On enters a branch (partial match); Is matches only when the path is fully consumed (terminal). The verb matchers Get/Post/Put/Delete add a method test: bare (r.Get(h)) they match when the path is fully consumed; with matchers they are terminal like Is. Root matches a GET to exactly /.
• Redirect(path[, status]) sets a redirect (default 302) and terminates; Halt terminates immediately with the current response.

The route-block seam

The route block is the one thing Roda cannot make deterministic, so it is an explicit seam:

type Handler func(r *RodaRequest, captures []any) (handled bool, body any)

When a matcher matches, the engine calls the branch's Handler with the captures accumulated so far. The handler may re-enter the tree (call more matcher methods on r) — that is how nested routing works — and returns whether it produced a body and, if so, the body (a string, a []string, or nil). A matched branch always terminates the request, mirroring how Roda throws :halt after a matched on. In a rbgo binding, the Handler runs the Ruby block.

Roda.Call builds the request and response, runs the route block, catches the terminating halt, and finishes the response — defaulting to 404 when nothing matched and 200 when a body was written, with Content-Type: text/html and Content-Length filled in, exactly as RodaResponse#finish does.

Install

go get github.com/go-ruby-roda/roda

Fidelity vs the roda gem

Modelled on the Roda 3.x request router (tracking the MRI 4.0.5 line):

• Segment consumption is byte-for-byte the gem's: _match_string matches on segment boundaries (/foo does not match /foobar), _match_symbol / String capture \A/([^/]+), Integer captures \A/(\d+) bounded by a segment edge, and regexps are auto-anchored to \A/(?:…) with their captures concatenated and the match consumed.
• on / is / verb / root / redirect / halt semantics match the gem, including the save/restore of the remaining path on a failed branch and the always-terminate-after-match rule.
• RodaResponse#finish defaults match: empty body → 404, present body → 200, text/html default Content-Type, and Content-Type/Length stripped for 1xx/204/304.
• Scope. This is the core routing engine. The gem's plugin system, the full Hash-matcher key set (only :method, :param, :extension are modelled here), and rendering are out of scope — they layer on top of this engine. The :extension matcher captures the segment base name and consumes through the extension.

Tests & coverage

go test -race -cover ./...

The suite enforces 100% line coverage — every matcher type, capture passing, verb and root matching, halt/redirect, the response defaults, and the unmatched → 404 path — and cross-compiles on all six supported 64-bit targets (amd64, arm64, riscv64, loong64, ppc64le, s390x, including the big-endian s390x). CI runs the suite on Linux, macOS and Windows and under QEMU for the non-native arches.

License

BSD-3-Clause — see LICENSE. Copyright (c) 2026, the go-ruby-roda/roda authors.

WebAssembly

Being pure Go (CGO=0), this library also compiles to WebAssembly — both GOOS=js GOARCH=wasm (browser / Node.js) and GOOS=wasip1 GOARCH=wasm (WASI). CI builds both targets on every push, alongside the six 64-bit native/qemu arches.

GOOS=js     GOARCH=wasm go build ./...   # browser / Node
GOOS=wasip1 GOARCH=wasm go build ./...   # WASI (wasmtime, wasmer, wasmedge, …)